@lanes-sh/link 0.3.2 → 0.4.0

package/src/cli/commands/connect/custom/spec.ts

@@ -0,0 +1,293 @@
+/**
+ * The two fixed lists, as data, and what each member needs typed.
+ *
+ * `connect custom` exists to compose them: a connectivity type from
+ * `connectivity/manifest/connector.ts` and a credential type from
+ * `connectivity/manifest/auth.ts`, which are closed discriminated unions. So
+ * this file is a projection of those two schemas onto flags, and nothing here
+ * decides anything — `derive.ts` builds the manifest and `defineProvider` has
+ * the final word, exactly as it does for a hand-written file.
+ *
+ * One member is deliberately absent. `local` means the capability code is
+ * *ours*, compiled into this build, so there is nothing for a manifest to point
+ * at — refused by name rather than omitted in silence, because an operator
+ * reading the schema will find it and ask.
+ *
+ * `strategy` *is* offered, and naming one is a large part of what a declaration
+ * is for. A strategy travels on a provider's definition rather than in a global
+ * registry, so a YAML manifest reaches one by name — which is the only way to
+ * point a connection at a vendor's sandbox, since a built-in manifest's
+ * `options` are not the operator's to edit. See ADR-046.
+ */
+
+/** Reachable by declaring one. `local` is ours; see the note above. */
+export const CONNECTOR_KINDS = ['mcp', 'http', 'imap', 'dav', 'fs'] as const;
+export type ConnectorKind = (typeof CONNECTOR_KINDS)[number];
+
+/**
+ * Typed with a hyphen, stored with an underscore.
+ *
+ * The manifest spells it `api_key` because `identifier` does, and a flag spells
+ * it `api-key` because every other flag in this CLI is kebab-case. One place
+ * knows both.
+ */
+export const AUTH_METHODS = [
+  'none',
+  'bearer',
+  'api-key',
+  'header',
+  'basic',
+  'oauth',
+  'strategy',
+] as const;
+export type AuthMethod = (typeof AUTH_METHODS)[number];
+
+export const AUTH_KIND: Record<AuthMethod, string> = {
+  none: 'none',
+  bearer: 'bearer',
+  'api-key': 'api_key',
+  header: 'header',
+  basic: 'basic',
+  oauth: 'oauth',
+  strategy: 'strategy',
+};
+
+/**
+ * Provider ids this command's own grammar has taken.
+ *
+ * `custom` is the second word of `lanes link connect custom`, so a provider
+ * called `custom` could be declared, registered, and then never connected —
+ * that command would always mean this one. Refused in two places: here, so it
+ * cannot be created, and in `buildRegistryWithWorkspace`, so a file written by
+ * hand before this existed says why rather than being quietly unreachable.
+ *
+ * Not `RESERVED_PROVIDER_IDS`: that list is the owner layer's, it is surfaced to
+ * an agent as "the owner providers present in this profile", and the CLI
+ * registry passes `allowReserved: true` so it would not have fired here anyway.
+ */
+export const RESERVED_BY_GRAMMAR = ['custom'] as const;
+
+/** One value the operator supplies, and what to call it when asking. */
+export interface FieldSpec {
+  /** The kebab-case flag, which is also the key in `CustomFlags` once camelised. */
+  readonly flag: string;
+  readonly label: string;
+  readonly required: boolean;
+  /** One line under the prompt, where the answer is not obvious from the label. */
+  readonly hint?: string;
+  /** A closed set, offered as a choice rather than a free string. */
+  readonly choices?: readonly string[];
+}
+
+/**
+ * Per connectivity type: what must be said, and what may be.
+ *
+ * Only fields with no honest default appear. `port`, `max_body_bytes`,
+ * `max_range_days`, `max_file_bytes` and the rest are schema defaults and stay
+ * out of the written file, so a later change to a default reaches manifests
+ * already on disk instead of being frozen into each one.
+ */
+/**
+ * The one field `mcp` and `http` share, and the only one worth a flag.
+ *
+ * Repeatable. What the *vendor* requires of a client rather than what a caller
+ * wants from it: a `User-Agent` on a host that throttles the default one
+ * hardest, or the header an mcp server offers for asking it to expose fewer
+ * tools. `Authorization` is refused — that one belongs to `auth`.
+ */
+const HEADER: FieldSpec = {
+  flag: 'header',
+  label: 'Header sent on every request',
+  required: false,
+  hint: 'Name: value, repeatable. For what the vendor requires of a client, e.g. a User-Agent',
+};
+
+export const CONNECTOR_FIELDS: Record<ConnectorKind, readonly FieldSpec[]> = {
+  mcp: [
+    {
+      flag: 'endpoint',
+      label: 'MCP endpoint',
+      required: true,
+      hint: 'The URL the server speaks Streamable HTTP on, e.g. https://mcp.example.com/mcp',
+    },
+    HEADER,
+  ],
+  http: [
+    { flag: 'base-url', label: 'Base URL', required: true, hint: 'e.g. https://api.example.com/v1' },
+    {
+      flag: 'openapi',
+      label: 'OpenAPI document',
+      required: true,
+      hint: 'A URL, or a path to a file beside the manifest',
+    },
+    {
+      flag: 'operations',
+      label: 'Operations to expose',
+      required: false,
+      hint: 'Globs on operationId, path or tag. A large spec is a tool list no agent can reason over',
+    },
+    HEADER,
+  ],
+  imap: [
+    { flag: 'host', label: 'IMAP host', required: true, hint: 'e.g. imap.example.com' },
+    { flag: 'port', label: 'IMAP port', required: false, hint: 'Defaults to 993' },
+    {
+      flag: 'smtp-host',
+      label: 'SMTP host',
+      required: false,
+      hint: 'Leave empty for a read-only mailbox — without it there is no send capability',
+    },
+    { flag: 'smtp-port', label: 'SMTP port', required: false, hint: '465 for implicit TLS, 587 to upgrade in-band' },
+  ],
+  dav: [
+    { flag: 'base-url', label: 'Base URL', required: true, hint: 'Where discovery begins, e.g. https://dav.example.com' },
+    { flag: 'service', label: 'Service', required: true, choices: ['caldav', 'carddav'] },
+  ],
+  fs: [
+    { flag: 'root', label: 'Folder', required: true, hint: 'Everything under it is reachable and nothing above it. May start with ~' },
+    { flag: 'exclude', label: 'Names to exclude', required: false, hint: 'On top of .git, .ssh and node_modules, which are always refused' },
+  ],
+};
+
+/**
+ * Per credential type.
+ *
+ * The credential itself is never here, and never a flag. A flag value is in
+ * shell history, in `ps` output while the command runs, and in any transcript of
+ * the session — which is why `secrets set` reads from stdin and why this command
+ * writes `setup.prompts` into the manifest and lets the ordinary connect path
+ * ask. The upshot is that this change handles no secrets at all.
+ */
+export const AUTH_FIELDS: Record<AuthMethod, readonly FieldSpec[]> = {
+  none: [],
+  bearer: [
+    { flag: 'auth-header', label: 'Header name', required: false, hint: 'Defaults to Authorization' },
+  ],
+  'api-key': [
+    { flag: 'auth-header', label: 'Header name', required: false, hint: 'Defaults to X-API-Key' },
+    { flag: 'auth-query', label: 'Query parameter', required: false, hint: 'Instead of a header' },
+  ],
+  header: [
+    { flag: 'auth-header', label: 'Header name', required: true, hint: 'The header the value is sent in, verbatim' },
+  ],
+  basic: [],
+  strategy: [
+    {
+      flag: 'strategy',
+      label: 'Strategy name',
+      required: true,
+      hint: 'The name a provider in this build supplies, e.g. bunq',
+    },
+    {
+      flag: 'strategy-option',
+      label: 'Strategy option',
+      required: false,
+      hint: 'key=value, repeatable. Read by the strategy itself',
+    },
+  ],
+  oauth: [
+    { flag: 'scopes', label: 'Scopes', required: true, hint: 'What to ask the authorization server for' },
+    { flag: 'authorize-url', label: 'Authorize URL', required: false, hint: 'Required for an http connector; discovered for mcp' },
+    { flag: 'token-url', label: 'Token URL', required: false, hint: 'Declared with authorize-url or not at all' },
+    { flag: 'client-app', label: 'OAuth app name', required: false, hint: 'Which oauth_apps entry holds the client. Defaults to the provider id' },
+    { flag: 'registration', label: 'Registration', required: false, choices: ['dynamic', 'manual'] },
+    {
+      flag: 'authorize-param',
+      label: 'Extra authorization parameter',
+      required: false,
+      hint: 'key=value, repeatable. Some vendors need one to issue a refresh token at all',
+    },
+    {
+      flag: 'redirect-uri',
+      label: 'Redirect URI',
+      required: false,
+      hint: 'Only for a vendor that matches the whole URL — connect otherwise uses a port the kernel picks',
+    },
+  ],
+};
+
+/** Everything `connect custom` accepts, including what it forwards to `connect`. */
+export const CONNECT_CUSTOM_FLAGS: readonly string[] = [
+  'connector',
+  'auth',
+  'name',
+  'description',
+  ...new Set(
+    [...Object.values(CONNECTOR_FIELDS), ...Object.values(AUTH_FIELDS)]
+      .flat()
+      .map((field) => field.flag),
+  ),
+  'identity-url',
+  'identity-field',
+  'setup-docs',
+  'replace-manifest',
+  'yes',
+  // Forwarded to `connect` untouched, so declaring and connecting is one line.
+  // `--own-client` is not among them: it selects between an operator's client
+  // and a broker's, and a synthesized manifest never declares a broker.
+  'id',
+  'display-name',
+  'replace',
+  'non-interactive',
+  'accept-broad-scopes',
+];
+
+/** What the operator typed, before any of it has been judged. */
+export interface CustomFlags {
+  readonly connector?: string | undefined;
+  readonly auth?: string | undefined;
+  readonly name?: string | undefined;
+  readonly description?: string | undefined;
+  readonly endpoint?: string | undefined;
+  readonly baseUrl?: string | undefined;
+  readonly openapi?: string | undefined;
+  readonly operations?: readonly string[] | undefined;
+  readonly service?: string | undefined;
+  readonly host?: string | undefined;
+  readonly port?: string | undefined;
+  readonly smtpHost?: string | undefined;
+  readonly smtpPort?: string | undefined;
+  readonly root?: string | undefined;
+  readonly exclude?: readonly string[] | undefined;
+  readonly header?: readonly string[] | undefined;
+  readonly authHeader?: string | undefined;
+  readonly authQuery?: string | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  readonly authorizeUrl?: string | undefined;
+  readonly tokenUrl?: string | undefined;
+  readonly clientApp?: string | undefined;
+  readonly registration?: string | undefined;
+  readonly redirectUri?: string | undefined;
+  readonly authorizeParam?: readonly string[] | undefined;
+  readonly strategy?: string | undefined;
+  readonly strategyOption?: readonly string[] | undefined;
+  readonly identityUrl?: string | undefined;
+  readonly identityField?: string | undefined;
+  readonly setupDocs?: string | undefined;
+  readonly replaceManifest?: boolean | undefined;
+  readonly yes?: boolean | undefined;
+}
+
+/** Everything settled, ready for `deriveManifest`. */
+export interface CustomAnswers {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly connector: ConnectorKind;
+  readonly auth: AuthMethod;
+  readonly values: Readonly<Record<string, string | readonly string[]>>;
+}
+
+/** `acme_billing` reads as `Acme Billing` until somebody says otherwise. */
+export function titleCase(id: string): string {
+  return id
+    .split('_')
+    .filter((part) => part.length > 0)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+/** camelCase, so a flag name indexes `CustomFlags` without a second table. */
+export function camel(flag: string): string {
+  return flag.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}

package/src/cli/commands/connect/custom/values.ts

@@ -0,0 +1,53 @@
+import type { CustomAnswers } from './spec.ts';
+
+/**
+ * Reading what the operator said, in the shape the schema wants it.
+ *
+ * `values` is flag-keyed and every value arrived as a string or a list of them,
+ * because argv has nothing else to offer. These four are the only places that
+ * changes, so a field is read the same way wherever it is read.
+ */
+
+export const one = (answers: CustomAnswers, flag: string): string | undefined => {
+  const value = answers.values[flag];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+
+export const many = (answers: CustomAnswers, flag: string): readonly string[] => {
+  const value = answers.values[flag];
+  return Array.isArray(value) ? value.filter((entry) => entry.length > 0) : [];
+};
+
+/**
+ * `--strategy-option key=value` and `--authorize-param key=value`, repeated.
+ *
+ * Both untyped on purpose. A strategy's `options` are validated by the strategy
+ * itself, which is the only thing that knows what it takes; an authorization
+ * request's extra parameters are the vendor's vocabulary and not ours.
+ */
+export function pairs(answers: CustomAnswers, flag: string): Record<string, string> | undefined {
+  const declared = many(answers, flag);
+  if (declared.length === 0) return undefined;
+
+  const parsed: Record<string, string> = {};
+
+  for (const entry of declared) {
+    const split = entry.indexOf('=');
+    if (split < 1) {
+      throw new Error(`--${flag} "${entry}" is not a setting. Write it as "key=value".`);
+    }
+    parsed[entry.slice(0, split).trim()] = entry.slice(split + 1).trim();
+  }
+
+  return parsed;
+}
+
+export function port(value: string | undefined, flag: string): number | undefined {
+  if (value === undefined) return undefined;
+
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    throw new Error(`--${flag} must be a port between 1 and 65535, not "${value}".`);
+  }
+  return parsed;
+}

package/src/cli/commands/connect/custom/write.ts

@@ -0,0 +1,166 @@
+import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { stringify } from 'yaml';
+import type { ProviderManifest } from '#connectivity';
+import { layout } from '#profile';
+import { parseManifest } from '#providers/custom/index.ts';
+
+/**
+ * Putting the manifest where the loader will find it.
+ *
+ * The only filesystem code in this command, and the only place that decides what
+ * the file looks like. Writing is local: a deployed revision reads its
+ * manifests from a bucket but never writes its own config (ADR-007), so the
+ * operator's workspace is where a declaration is authored and `deploy` or the
+ * publish that follows a connect is what carries it.
+ */
+
+/** Where this profile keeps its own declarations. */
+export function manifestPath(workspaceRoot: string, profile: string, id: string): string {
+  return join(workspaceRoot, layout.providers(profile), `${id}.yaml`);
+}
+
+/**
+ * Fields this command never writes, so a hand-added one is not a difference.
+ *
+ * The file belongs to the operator the moment it exists. `redact` and `hints`
+ * are exactly what somebody adds after seeing the tool list — per-capability
+ * argument keys worth recording, and prose the vendor's own description leaves
+ * out — and a re-run must not read them as drift.
+ */
+const THEIRS = ['redact', 'hints', 'bundles'];
+
+/**
+ * One header line, about the file rather than about the fields.
+ *
+ * `manifestTemplate` is the other way round and stays that way: it is teaching
+ * material whose values are deliberately wrong and whose comments explain each
+ * field. This is a record of what somebody just said, where every value is
+ * theirs — so a comment describing a field would end up describing a different
+ * provider than the value beside it, and every optional field they declined
+ * would sit in the file as a value that now *is* declared.
+ */
+const HEADER =
+  '# Written by `lanes link connect custom`. Yours to edit from here —\n' +
+  '# `lanes link connect <id>` re-reads this file every time.\n';
+
+export function renderManifest(declaration: Record<string, unknown>): string {
+  return HEADER + stringify(declaration, { lineWidth: 0 });
+}
+
+/** The manifest already at this path, or null. Parsed, so defaults match. */
+export async function readExistingManifest(path: string): Promise<ProviderManifest | null> {
+  let text: string;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+
+  // Deliberately `parseManifest` and not the loader's file variant: a relative
+  // `openapi` must compare as it was written, not as it resolves, or every
+  // re-run reads as a change.
+  return parseManifest(text, path);
+}
+
+/**
+ * Where a re-run would differ from what is on disk, as dotted paths.
+ *
+ * Compared as parsed manifests rather than as bytes, so both sides have the same
+ * defaults applied and neither key order nor a reflowed line reads as drift.
+ * Both directions, minus `THEIRS`: dropping `--operations` from a second run is
+ * a real difference, and answering "unchanged" there would leave a filter in
+ * place that the operator has just stopped asking for.
+ */
+export function manifestDiff(derived: ProviderManifest, existing: ProviderManifest): string[] {
+  const differences: string[] = [];
+
+  const walk = (a: unknown, b: unknown, path: string): void => {
+    if (path.length > 0 && THEIRS.includes(path.split('.')[0]!)) return;
+
+    if (Array.isArray(a) || Array.isArray(b)) {
+      if (JSON.stringify(a) !== JSON.stringify(b)) differences.push(describe(path, a, b));
+      return;
+    }
+
+    if (isRecord(a) && isRecord(b)) {
+      for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+        walk(a[key], b[key], path.length > 0 ? `${path}.${key}` : key);
+      }
+      return;
+    }
+
+    if (a !== b) differences.push(describe(path, a, b));
+  };
+
+  walk(derived, existing, '');
+  return differences.sort();
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+function describe(path: string, derived: unknown, existing: unknown): string {
+  return `${path}: ${show(existing)} → ${show(derived)}`;
+}
+
+const show = (value: unknown): string =>
+  value === undefined ? '(absent)' : typeof value === 'string' ? value : JSON.stringify(value);
+
+/** Write through a temp file, so a crash cannot leave half a declaration. */
+export async function writeManifest(path: string, text: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+
+  // `.tmp` because the filesystem blob store skips that suffix when it lists —
+  // so a crash between write and rename leaves a file the loader will not try to
+  // parse, rather than one that breaks every command for this profile.
+  const temporary = `${path}.tmp`;
+  await writeFile(temporary, text, { mode: 0o600 });
+  await rename(temporary, path);
+}
+
+/**
+ * That an OpenAPI document named as a path is actually there.
+ *
+ * Checked before the manifest is written, because the alternative is bleak:
+ * discovery is the only thing that reads the spec, `openRuntime` swallows a
+ * discovery failure so startup survives a provider that is merely unreachable,
+ * and the result is a provider registered with zero capabilities and nothing
+ * anywhere saying why.
+ *
+ * A relative path resolves against `providers.d/`, which is what
+ * `resolveSpecPath` does when the loader reads it — and is almost never what
+ * somebody typing `./spec.json` at a shell prompt means. So when it is missing
+ * there and present in the working directory, say both.
+ */
+export async function checkOpenapiReachable(
+  value: string,
+  workspaceRoot: string,
+  profile: string,
+): Promise<void> {
+  if (/^https?:/i.test(value)) return;
+
+  const beside = isAbsolute(value)
+    ? value
+    : resolve(join(workspaceRoot, layout.providers(profile)), value);
+
+  if (await exists(beside)) return;
+
+  const here = isAbsolute(value) ? undefined : resolve(process.cwd(), value);
+  const alsoLookedAt =
+    here && here !== beside && (await exists(here))
+      ? `\n  It does exist at ${here}. A relative path in a manifest resolves against the manifest, ` +
+        'not against wherever you ran this from — copy it beside the manifest, or give an absolute ' +
+        'path or a URL.'
+      : '';
+
+  throw new Error(`No OpenAPI document at ${beside}.${alsoLookedAt}`);
+}
+
+const exists = async (path: string): Promise<boolean> => {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+};

package/src/cli/commands/connect/grant.ts

@@ -0,0 +1,27 @@
+import type { ConfigDocument } from '../../config-edit.ts';
+import { matchesRule } from './accounts.ts';
+
+/**
+ * What connecting grants.
+ *
+ * One rule per provider, not one per capability. The pinned-per-tool form this
+ * replaced was 85 lines for four providers and unreadable, and what it bought —
+ * a vendor cannot widen your policy by shipping a new tool — is preserved
+ * instead by `doctor`, which reports capabilities that appeared after you
+ * connected.
+ *
+ * Idempotent, and by matching rather than by equality: a profile already holding
+ * a broader rule that covers this one is not widened, and a second connect to
+ * the same provider adds nothing.
+ */
+export function grantProvider(
+  document: ConfigDocument,
+  allow: readonly { readonly capability: string }[],
+  providerId: string,
+): string[] {
+  const rule = `${providerId}.*`;
+  if (allow.some((existing) => matchesRule(existing.capability, rule))) return [];
+
+  document.addTo(['policy', 'allow'], rule, { inline: true });
+  return [rule];
+}

package/src/cli/commands/connect/index.ts

@@ -4,7 +4,8 @@ import { ensureSetupConnection, repaired } from '../../config-repair.ts';
 import { emit, print } from '../../output.ts';
 import { nonInteractivePrompter, terminalPrompter, type Prompter } from '../../prompt.ts';
 import { openRuntime, type GlobalFlags } from '../../runtime.ts';
-import { matchesRule, moveCredential, siblingAccountId } from './accounts.ts';
+import { moveCredential, siblingAccountId } from './accounts.ts';
+import { grantProvider } from './grant.ts';
 import { discoverCapabilities } from './discover.ts';
 import { connectFamily, familyMembers } from './family.ts';
 import { authoriseWithKey } from './assertion.ts';
@@ -16,7 +17,9 @@ import { ALREADY, NOTHING, renderOutcome, where, type ConnectOutcome } from './o
 import { nextAfterEdit, publishRuntimeEdit } from '#cli/publish.ts';
 import { ensureStaticCredential } from './setup.ts';
 import { settleIdentity } from './settle.ts';
+import { runStrategySetup } from './strategy.ts';
 import { announceConnectTarget } from './target-note.ts';
+import { unknownProvider } from './unknown.ts';
 
 /**
  * `lanes link connect <provider>` — the one command that adds an account.
@@ -91,7 +94,14 @@ export async function connect(target: string, options: ConnectOptions): Promise<
   return emit(options.json, outcome, () => renderOutcome(outcome));
 }
 
-async function runConnect(
+/**
+ * Exported for `connect custom`, which declares a provider and then connects it.
+ *
+ * Narrow on purpose — no extra parameters, no second entry point into the five
+ * steps. The manifest is written before this is called, because the registry
+ * that reads `providers.d/` is built by `openRuntime` on the first line.
+ */
+export async function runConnect(
   target: string,
   options: ConnectOptions,
   /** A family member — the account this belongs to has already said where it goes. */
@@ -133,17 +143,13 @@ async function runConnect(
     }
 
     if (!entry) {
-      const available = registry.list();
-      const builtin = available.filter((c) => c.origin === 'builtin').map((c) => c.manifest.id);
-      const custom = available.filter((c) => c.origin === 'workspace').map((c) => c.manifest.id);
-
-      throw new Error(
-        `Unknown provider "${providerId}".\n` +
-          `  built in: ${builtin.join(', ')}\n` +
-          (custom.length > 0
-            ? `  yours:    ${custom.join(', ')}\n`
-            : `  add your own: a manifest in ${runtime.resolution.workspaceRoot}/providers/\n`),
-      );
+      throw unknownProvider({
+        providerId,
+        registry,
+        workspaceRoot: runtime.resolution.workspaceRoot,
+        profile: runtime.resolution.profile,
+        target: runtime.target,
+      });
     }
 
     const manifest = entry.manifest;
@@ -257,6 +263,9 @@ async function runConnect(
       });
     }
 
+    // 1b. The vendor's own handshake — see `./strategy.ts`, including why here.
+    await runStrategySetup(manifest, provisionalId, runtime);
+
     // 2. Ask the provider whose account that was.
     //
     //    This is what distinguishes reconnecting an existing account from
@@ -322,20 +331,8 @@ async function runConnect(
       changes.push(`re-authorised ${connectionKey}${method.id ? ` with ${method.id}` : ''}`);
     }
 
-    // 5. Grant it.
-    //
-    //    One rule per provider, not one per capability. The pinned-per-tool
-    //    form this replaced was 85 lines for four providers and unreadable, and
-    //    what it bought — a vendor cannot widen your policy by shipping a new
-    //    tool — is preserved instead by `doctor`, which reports capabilities
-    //    that appeared after you connected.
-    const granted: string[] = [];
-    const rule = `${providerId}.*`;
-
-    if (!runtime.config.policy.allow.some((existing) => matchesRule(existing.capability, rule))) {
-      document.addTo(['policy', 'allow'], rule, { inline: true });
-      granted.push(rule);
-    }
+    // 5. Grant it — one rule per provider; `grant.ts` says why not per capability.
+    const granted = grantProvider(document, runtime.config.policy.allow, providerId);
 
     // 6. Repair the setup surface if this profile predates it.
     //

package/src/cli/commands/connect/outcome.ts

@@ -140,7 +140,9 @@ function renderBlocked(outcome: ConnectOutcome): void {
         ? 'a browser is needed'
         : outcome.reason === 'needs_terminal'
           ? 'a terminal is needed'
-          : 'more is needed first',
+          : outcome.reason === 'needs_declaration'
+            ? 'this provider is not declared yet'
+            : 'more is needed first',
     ),
   );
 

package/src/cli/commands/connect/requirements.ts

@@ -37,7 +37,17 @@ export type BlockedReason =
   | 'needs_browser'
   /** A question only a person can answer, on a run with nobody to ask. */
   | 'needs_terminal'
-  | 'missing_credentials';
+  | 'missing_credentials'
+  /**
+   * The manifest itself is not settled yet — `connect custom` only.
+   *
+   * Unlike the others this is not about a credential: nothing has been written
+   * and nothing needs storing first, the declaration is simply incomplete or
+   * disagrees with the file already on disk. It shares `Blocked` because it
+   * shares the thing that matters about one — every missing piece named at
+   * once, and the command that ends it.
+   */
+  | 'needs_declaration';
 
 export interface Blocked {
   readonly reason: BlockedReason;