fix: centralize provider setup in Connections

Author: konard

.changeset/issue-27-connections-dry.md

@@ -0,0 +1,7 @@
+---
+'meta-sovereign': patch
+---
+
+Move provider credential, archive import, and direct probe controls onto
+Connections provider detail pages while keeping data-section empty states as
+compact links into Connections.

.gitkeep

@@ -317,27 +317,6 @@ pre {
 .connection-guide > h2 {
   margin: 0;
 }
-.connection-guide-provider {
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-.connection-guide-provider .col {
-  gap: 0.25rem;
-}
-.connection-guide-provider h3 {
-  margin: 0;
-  font-size: 1rem;
-}
-.connection-guide-provider h4 {
-  margin: 0.25rem 0 0;
-  font-weight: 600;
-  font-size: 0.85rem;
-}
-.connection-guide-provider .probe-row {
-  gap: 0.5rem;
-  align-items: flex-start;
-}
 .local-server-help {
   background: var(--bg-elev);
   border: 1px dashed var(--border);

js/src/web/app.css

@@ -121,8 +121,8 @@ const App = () => {
         setActive(detail.view);
       }
       if (typeof detail.anchor === 'string') {
-        // Update the URL hash so the Settings view can scroll to the
-        // matching `id="conn-{provider}"` card on first paint.
+        // Update the URL hash so the Connections view can open the
+        // matching `id="conn-{provider}"` detail on first paint.
         if (globalThis.location) {
           globalThis.location.hash = detail.anchor;
         }

js/src/web/app.js

@@ -13,7 +13,6 @@ import React, { useState } from 'react';
 import {
   connectionGuides,
   getGuide,
-  getProvider,
   isCrossOrigin,
   localServerHelp,
   providerCatalogue,
@@ -37,88 +36,6 @@ const tx = (t, value, key) => {
   return value;
 };
 
-const ProbeRow = ({ provider }) => {
-  const t = useT();
-  // R-O1: per-section ProbeRow refuses to fire when no credentials are
-  // saved (which would always 404/400 — the original bug). It points
-  // the user at Settings → Connections instead.
-  const ready = false;
-  const placeholder = t('guide.probeDisabled', {
-    label: tx(t, provider.label, provider.labelKey),
-  });
-  return el('div', { className: 'col probe-row' }, [
-    el('div', { key: 'row', className: 'row' }, [
-      el(
-        'button',
-        {
-          key: 'probe',
-          type: 'button',
-          className: 'primary',
-          disabled: !ready,
-        },
-        t('settings.probe.button')
-      ),
-      el('span', { key: 'meta', className: 'meta' }, placeholder),
-    ]),
-  ]);
-};
-
-const ProviderCard = ({ providerId }) => {
-  const t = useT();
-  const provider = getProvider(providerId);
-  return el('section', { className: 'card connection-guide-provider' }, [
-    el('h3', { key: 'h' }, tx(t, provider.label, provider.labelKey)),
-    el('div', { key: 'archive', className: 'col' }, [
-      el(
-        'h4',
-        { key: 'h', className: 'meta' },
-        tx(t, provider.archive.title, provider.archive.titleKey)
-      ),
-      el(
-        'p',
-        { key: 'p' },
-        tx(t, provider.archive.hint, provider.archive.hintKey)
-      ),
-      el(
-        'div',
-        { key: 'fileHint', className: 'meta' },
-        t('guide.filesLabel', { hint: provider.archive.fileHint })
-      ),
-    ]),
-    el('div', { key: 'api', className: 'col' }, [
-      el(
-        'h4',
-        { key: 'h', className: 'meta' },
-        tx(t, provider.apiCredentials.title, provider.apiCredentials.titleKey)
-      ),
-      el(
-        'p',
-        { key: 'p' },
-        tx(t, provider.apiCredentials.hint, provider.apiCredentials.hintKey)
-      ),
-      el(
-        'div',
-        { key: 'env', className: 'meta' },
-        t('guide.envVarLabel', { name: provider.apiCredentials.envVar })
-      ),
-      el(
-        'div',
-        { key: 'docs', className: 'meta' },
-        el(
-          'a',
-          {
-            href: provider.apiCredentials.docsUrl,
-            target: '_blank',
-            rel: 'noopener noreferrer',
-          },
-          t('settings.docsLink')
-        )
-      ),
-      el(ProbeRow, { key: 'probe', provider }),
-    ]),
-  ]);
-};
-
 export const LocalServerHelp = () => {
   const t = useT();
   const [override, setOverride] = useState('');
@@ -181,23 +98,22 @@ export const LocalServerHelp = () => {
   ]);
 };
 
-// R-O7: per-section "Connect first" CTA. Renders above the in-place
-// guide and deep-links into Settings → Connections, scrolling to the
-// matching provider card via the `meta-sovereign:navigate` event that
-// app.js listens for.
-export const SettingsConnectFirstCta = ({ providerId }) => {
+// Issue #27: per-section "Connect first" CTA. Empty data surfaces keep
+// their explanation but deep-link into the dedicated Connections detail
+// page instead of repeating provider setup cards inline.
+export const ConnectionsConnectFirstCta = ({ providerId }) => {
   const t = useT();
   const provider = providerId ? providerCatalogue[providerId] : null;
   const target = provider
-    ? t('guide.openSettingsTarget', {
+    ? t('guide.openConnectionsTarget', {
         label: tx(t, provider.label, provider.labelKey),
       })
-    : t('guide.openSettingsRoot');
+    : t('guide.openConnectionsRoot');
   const navigate = () => {
     const anchor = providerId ? `#conn-${providerId}` : '';
     globalThis.dispatchEvent?.(
       new CustomEvent('meta-sovereign:navigate', {
-        detail: { view: 'settings', anchor },
+        detail: { view: 'connections', anchor },
       })
     );
   };
@@ -210,10 +126,11 @@ export const SettingsConnectFirstCta = ({ providerId }) => {
         type: 'button',
         className: 'primary',
         onClick: navigate,
-        'data-action': 'open-settings',
+        'data-action': 'open-connections',
+        'data-target-provider': providerId ?? '',
         'data-target-anchor': providerId ? `#conn-${providerId}` : '',
       },
-      t('guide.openSettings', { target })
+      t('guide.openConnections', { target })
     ),
   ]);
 };
@@ -232,21 +149,19 @@ export const ConnectionGuide = ({ section }) => {
     'section',
     {
       className: 'connection-guide',
+      'data-guide-mode': guide.providers.length > 0 ? 'compact' : 'help',
       'data-connection-guide': section,
       role: 'note',
     },
     [
       el('h2', { key: 'h' }, tx(t, guide.title, guide.titleKey)),
       el('p', { key: 'body' }, tx(t, guide.body, guide.bodyKey)),
       guide.providers.length > 0
-        ? el(SettingsConnectFirstCta, {
+        ? el(ConnectionsConnectFirstCta, {
             key: 'cta',
             providerId: guide.connectFirst?.providerId ?? guide.providers[0],
           })
         : null,
-      ...guide.providers.map((id) =>
-        el(ProviderCard, { key: id, providerId: id })
-      ),
       guide.providers.length === 0
         ? el(LocalServerHelp, { key: 'help' })
         : null,

js/src/web/app.min.js

@@ -19,7 +19,7 @@ import { saveServerOverride } from './discover.js';
 //
 // Issue #16 / R-O1, R-O2 additions per provider:
 //   - `apiCredentials.fields` enumerates the credential inputs the
-//     Settings → Connections card renders (text/password). Each field
+//     Connections provider detail renders (text/password). Each field
 //     names the `secret:*` link id it persists into.
 //   - `apiCredentials.probeUrlTemplate` is a string with `{token}` /
 //     `{phoneNumberId}` / `{appId}` placeholders that resolve against
@@ -32,7 +32,7 @@ import { saveServerOverride } from './discover.js';
 //   - `apiCredentials.errorHints` maps an HTTP status to a user-facing
 //     remediation hint surfaced by `<ProbeRow>`.
 //   - `archive.accept` is the `<input type="file" accept>` filter used
-//     by the Settings → Connections archive uploader (R-O4).
+//     by the Connections archive uploader (R-O4).
 export const providerCatalogue = {
   email: {
     label: 'Email',
@@ -664,15 +664,15 @@ export const providerCatalogue = {
 
 // Section -> guide. Keys mirror `navItems` in views.js (R-M1).
 //
-// Issue #16 / R-O7 additions:
+// Issue #16 / R-O7 and issue #27 additions:
 //   - `connectFirst` is the per-section deep-link the empty-state card
-//     shows. It points the user at Settings → Connections and scrolls to
-//     the first relevant provider card (`#conn-{providerId}`).
+//     shows. It points the user at Connections -> provider detail, where
+//     the matching provider owns credentials, archive import, and probe.
 export const connectionGuides = {
   chat: {
     title: 'Your unified inbox starts empty.',
     titleKey: 'guide.chat.title',
-    body: 'meta-sovereign keeps every chat from every connected service in one place. Connect a provider below, or import an exported archive to populate this view.',
+    body: 'meta-sovereign keeps every chat from every connected service in one place. Open Connections to connect a provider or import an exported archive, then come back here.',
     bodyKey: 'guide.chat.body',
     providers: [
       'email',
@@ -691,7 +691,7 @@ export const connectionGuides = {
   operator: {
     title: 'Operator queue is empty.',
     titleKey: 'guide.operator.title',
-    body: 'The operator card stream walks you through unread messages chat by chat. Connect a chat-capable provider below to start the queue.',
+    body: 'The operator card stream walks you through unread messages chat by chat. Open Connections and add a chat-capable provider to start the queue.',
     bodyKey: 'guide.operator.body',
     providers: [
       'email',
@@ -710,7 +710,7 @@ export const connectionGuides = {
   contacts: {
     title: 'No contacts yet.',
     titleKey: 'guide.contacts.title',
-    body: 'Contacts are aggregated from every connected provider so the same person across networks shows up once. Add a provider to populate this list.',
+    body: 'Contacts are aggregated from every connected provider so the same person across networks shows up once. Open Connections to add a provider and populate this list.',
     bodyKey: 'guide.contacts.body',
     providers: [
       'email',
@@ -732,7 +732,7 @@ export const connectionGuides = {
   automation: {
     title: 'No automation graphs yet.',
     titleKey: 'guide.automation.title',
-    body: 'Automation graphs route incoming messages from a pattern to a reply variation. Drop a node above, or import an archive first so you have data to match against.',
+    body: 'Automation graphs route incoming messages from a pattern to a reply variation. Open Connections to import provider data before building automations.',
     bodyKey: 'guide.automation.body',
     providers: [
       'email',
@@ -748,15 +748,15 @@ export const connectionGuides = {
   patterns: {
     title: 'No patterns yet.',
     titleKey: 'guide.patterns.title',
-    body: 'Patterns are inferred from example messages. Connect a provider, or import an archive, then come back here and feed the inferrer a few examples.',
+    body: 'Patterns are inferred from example messages. Open Connections to connect a provider or import an archive, then return with examples to infer from.',
     bodyKey: 'guide.patterns.body',
     providers: ['email', 'telegram', 'vk', 'x', 'whatsapp'],
     connectFirst: { providerId: 'telegram' },
   },
   replies: {
     title: 'No reply variation groups yet.',
     titleKey: 'guide.replies.title',
-    body: 'Reply groups are extracted from your previous outgoing messages by fuzzy similarity. Connect a chat-capable provider to seed your reply library.',
+    body: 'Reply groups are extracted from your previous outgoing messages by fuzzy similarity. Open Connections to add a chat-capable provider and seed your reply library.',
     bodyKey: 'guide.replies.body',
     providers: [
       'email',
@@ -773,15 +773,15 @@ export const connectionGuides = {
   facts: {
     title: 'No facts extracted yet.',
     titleKey: 'guide.facts.title',
-    body: 'Facts are question -> answer pairs extracted across messages by your patterns. Add a pattern with a capture group, or connect a chat provider to start gathering data.',
+    body: 'Facts are question -> answer pairs extracted across messages by your patterns. Open Connections to gather provider data, then add a capture pattern here.',
     bodyKey: 'guide.facts.body',
     providers: ['email', 'telegram', 'vk', 'x', 'whatsapp'],
     connectFirst: { providerId: 'telegram' },
   },
   audience: {
     title: 'Build your first audience.',
     titleKey: 'guide.audience.title',
-    body: 'Cross-reference contacts using AND/OR/NOT plus dimensions like network:, chat:, sender:, kind:, fact:. Connect at least one provider so you have contacts to filter.',
+    body: 'Cross-reference contacts using AND/OR/NOT plus dimensions like network:, chat:, sender:, kind:, fact:. Open Connections to add at least one provider first.',
     bodyKey: 'guide.audience.body',
     providers: [
       'email',
@@ -800,15 +800,15 @@ export const connectionGuides = {
   broadcast: {
     title: 'No broadcast targets yet.',
     titleKey: 'guide.broadcast.title',
-    body: 'Broadcasts post the same message to every connected feed. Connect a public-posting provider below to enable a target checkbox.',
+    body: 'Broadcasts post the same message to every connected feed. Open Connections to connect a public-posting provider and enable target checkboxes.',
     bodyKey: 'guide.broadcast.body',
     providers: ['x', 'vk', 'facebook', 'linkedin', 'telegram'],
     connectFirst: { providerId: 'x' },
   },
   outreach: {
     title: 'No outreach surface yet.',
     titleKey: 'guide.outreach.title',
-    body: 'Mass-personal outreach sends a templated message 1:1 to each contact in an audience query. Connect a chat-capable provider to enable outreach.',
+    body: 'Mass-personal outreach sends a templated message 1:1 to each contact in an audience query. Open Connections to add a chat-capable provider first.',
     bodyKey: 'guide.outreach.body',
     providers: [
       'email',
@@ -826,7 +826,7 @@ export const connectionGuides = {
   profile: {
     title: 'No profile yet.',
     titleKey: 'guide.profile.title',
-    body: 'Edit your profile and resume here; saves are pushed to every connected provider. Connect at least one provider so the sync envelope has somewhere to go.',
+    body: 'Edit your profile and resume here; saves are pushed to every connected provider. Open Connections to add at least one provider for profile sync.',
     bodyKey: 'guide.profile.body',
     providers: [
       'telegram',
@@ -865,7 +865,7 @@ export const connectionGuides = {
   settings: {
     title: 'Settings',
     titleKey: 'guide.settings.title',
-    body: 'Provider connections, credentials, and archive imports live here. The list below mirrors every catalogued provider; pick one to enter its credentials, upload an archive, and probe the live API.',
+    body: 'App-level preferences live here. Provider credentials, archive imports, and live probes live on the dedicated Connections screen.',
     bodyKey: 'guide.settings.body',
     providers: [],
   },
@@ -1078,8 +1078,8 @@ export const buildProbeHeaders = ({ provider, credentials = {} } = {}) => {
   return out;
 };
 
-// Convenience: used by the Settings UI to read every credential field
-// for a provider out of an array of `secret:*` links.
+// Convenience: used by the Connections UI to read every credential
+// field for a provider out of an array of `secret:*` links.
 export const credentialsFromLinks = (provider, links = []) => {
   const fields = provider?.apiCredentials?.fields ?? [];
   const byId = new Map();