@lanes-sh/link 0.3.2 → 0.4.1

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

@@ -0,0 +1,229 @@
+import { defineProvider, type ProviderManifest } from '#connectivity';
+import {
+  AUTH_METHODS,
+  CONNECTOR_KINDS,
+  type AuthMethod,
+  type ConnectorKind,
+  type CustomAnswers,
+} from './spec.ts';
+import { identityBlock, setupBlock } from './prompts.ts';
+import { authBlock } from './credential.ts';
+import { many, one, port } from './values.ts';
+
+/**
+ * Turning what the operator said into a manifest.
+ *
+ * The flag surface cannot mirror the schema, because `defineProvider` demands
+ * fields nobody should have to type: `setup.prompts` for every credential type
+ * that is asked for rather than granted, an `identity` block wherever the
+ * connector can answer, and — for a manual OAuth client — two prompt keys and
+ * two credential refs whose exact spelling is read back by literal string
+ * elsewhere. So this file derives them, and `defineProvider` still has the last
+ * word, exactly as it does for a hand-written file.
+ *
+ * It also refuses three things the schema accepts and `authorise` cannot run.
+ * That is the failure class worth the most care here: the manifest validates,
+ * the connection is declared, and the flow has nowhere to go — which is
+ * indistinguishable from a working setup right up until somebody uses it.
+ */
+
+export function parseConnectorKind(value: string): ConnectorKind {
+  if ((CONNECTOR_KINDS as readonly string[]).includes(value)) return value as ConnectorKind;
+
+  if (value === 'local') {
+    throw new Error(
+      '"local" is not a connectivity type you can declare: it means the capability code is ours, ' +
+        'compiled into this build — the example provider and the owner layer. There is nothing for a ' +
+        `manifest to point at. Pick one of: ${CONNECTOR_KINDS.join(', ')}.`,
+    );
+  }
+
+  throw new Error(`Unknown connectivity type "${value}". Pick one of: ${CONNECTOR_KINDS.join(', ')}.`);
+}
+
+export function parseAuthMethod(value: string): AuthMethod {
+  if ((AUTH_METHODS as readonly string[]).includes(value)) return value as AuthMethod;
+
+  throw new Error(`Unknown credential type "${value}". Pick one of: ${AUTH_METHODS.join(', ')}.`);
+}
+
+/**
+ * Which pairs `defineProvider` would refuse, refused here instead.
+ *
+ * Same rules, earlier, and naming the alternative. The point is not to
+ * duplicate the check — it runs regardless a moment later — but that its
+ * message states a rule where this one states what to do about it.
+ */
+export function refuseIllegalPair(connector: ConnectorKind, auth: AuthMethod): void {
+  if (connector === 'mcp' && auth !== 'none' && auth !== 'oauth' && auth !== 'bearer') {
+    throw new Error(
+      `An mcp connector sends exactly one header, "Authorization: Bearer", because that is what the ` +
+        `MCP specification says a client sends. There is nowhere else on the request for a "${auth}" ` +
+        'credential to go, so this would connect unauthenticated: no error, an empty tool list, and ' +
+        'nothing to read that says why.\n' +
+        '  Reach the same service over its REST API with --connector http, or use --auth bearer.',
+    );
+  }
+
+  if ((connector === 'imap' || connector === 'dav') && auth !== 'basic') {
+    throw new Error(
+      `An ${connector} connector authenticates with a username and password. Every mail and DAV host ` +
+        'that matters issues an app password and expects it over Basic; OAuth for these exists but is ' +
+        'partner-gated with no published scopes, so declaring it would validate and then fail to ' +
+        'authenticate.\n  Use --auth basic.',
+    );
+  }
+
+  if (auth === 'strategy' && connector !== 'http') {
+    throw new Error(
+      `A strategy signs or negotiates an HTTP request, and a ${connector} connector does not make ` +
+        'one it could sign.\n  Use --connector http.',
+    );
+  }
+
+  if (connector === 'fs' && auth !== 'none') {
+    throw new Error(
+      'An fs connector reads a folder on this machine and holds no account. The permission is the ' +
+        'operating system\'s, held against this process — there is nothing to store and nothing that ' +
+        'could be carried to another machine (ADR-011).\n  Use --auth none.',
+    );
+  }
+}
+
+/**
+ * What gets written: only the fields the operator's answers actually settle.
+ *
+ * Deliberately *not* a `ProviderManifest`, and the distinction is load-bearing
+ * twice over. `defineProvider` fills in every schema default, and writing those
+ * back out would freeze them — a manifest saying `port: 993` no longer follows
+ * the default if it ever changes, and a re-run diffs against a file full of
+ * values nobody chose.
+ *
+ * Worse, it would not even load. Defaulting `auth.refresh_token` to `required`
+ * puts a key ending in `_token` into the document, and the entropy check that
+ * guards a manifest refuses any such key that is not a `_ref` — so the file this
+ * command wrote would be rejected the next time anything read it. Rendering the
+ * declaration rather than the validated manifest is what keeps the two honest.
+ */
+export function deriveDeclaration(answers: CustomAnswers): Record<string, unknown> {
+  refuseIllegalPair(answers.connector, answers.auth);
+
+  const setup = setupBlock(answers);
+  const identity = identityBlock(answers);
+
+  return {
+    id: answers.id,
+    name: answers.name,
+    ...(answers.description ? { description: answers.description } : {}),
+    connector: connectorBlock(answers),
+    auth: authBlock(answers),
+    ...(identity ? { identity } : {}),
+    ...(setup ? { setup } : {}),
+  };
+}
+
+/** The same declaration, validated — which is what a re-run compares against. */
+export function deriveManifest(answers: CustomAnswers): ProviderManifest {
+  return defineProvider(deriveDeclaration(answers));
+}
+
+/**
+ * `--header 'Name: value'`, repeated.
+ *
+ * `Authorization` is refused here as well as by `defineProvider`, because this
+ * is where somebody is choosing: the credential comes from `auth`, and a
+ * manifest setting both would leave which one is sent up to merge order.
+ */
+function headers(answers: CustomAnswers): Record<string, string> | undefined {
+  const declared = many(answers, 'header');
+  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(`--header "${entry}" is not a header. Write it as "Name: value".`);
+    }
+
+    const name = entry.slice(0, split).trim();
+    if (name.toLowerCase() === 'authorization') {
+      throw new Error(
+        'The credential is the auth block\'s, so --header cannot set Authorization — setting both ' +
+          'would leave which one is sent up to merge order.\n' +
+          '  Use --auth bearer (or api-key, or header with --auth-header) instead.',
+      );
+    }
+
+    parsed[name] = entry.slice(split + 1).trim();
+  }
+
+  return parsed;
+}
+
+/**
+ * Only what was said, plus what cannot be defaulted.
+ *
+ * A schema default is deliberately not written: leaving `port` out means a
+ * manifest follows the default if it ever changes, and it keeps the diff on a
+ * re-run down to what actually differs.
+ */
+function connectorBlock(answers: CustomAnswers): Record<string, unknown> {
+  const kind = answers.connector;
+
+  const sent = headers(answers);
+
+  if (kind === 'mcp') {
+    return { kind, endpoint: one(answers, 'endpoint'), ...(sent ? { headers: sent } : {}) };
+  }
+
+  if (kind === 'http') {
+    const include = many(answers, 'operations');
+    return {
+      kind,
+      base_url: one(answers, 'base-url'),
+      openapi: one(answers, 'openapi'),
+      ...(include.length > 0 ? { operations: { include } } : {}),
+      ...(sent ? { headers: sent } : {}),
+    };
+  }
+
+  if (kind === 'imap') {
+    const smtpHost = one(answers, 'smtp-host');
+    const smtpPort = port(one(answers, 'smtp-port'), 'smtp-port');
+
+    return {
+      kind,
+      host: one(answers, 'host'),
+      ...(port(one(answers, 'port'), 'port') !== undefined
+        ? { port: port(one(answers, 'port'), 'port') }
+        : {}),
+      // No SMTP host, no send capability — `imap/index.ts` reads the absence of
+      // the block, so a mailbox declared without one is read-only by
+      // construction rather than by policy.
+      ...(smtpHost
+        ? {
+            smtp: {
+              host: smtpHost,
+              ...(smtpPort !== undefined ? { port: smtpPort } : {}),
+              // A consequence of the port rather than a separate question: 465
+              // is implicit TLS, 587 upgrades in-band, and the default is the
+              // latter. Written only when it is not the default.
+              ...(smtpPort === 465 ? { starttls: false } : {}),
+            },
+          }
+        : {}),
+    };
+  }
+
+  if (kind === 'dav') {
+    return { kind, base_url: one(answers, 'base-url'), service: one(answers, 'service') };
+  }
+
+  const exclude = many(answers, 'exclude');
+  return {
+    kind,
+    root: one(answers, 'root'),
+    ...(exclude.length > 0 ? { exclude } : {}),
+  };
+}

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

@@ -0,0 +1,285 @@
+import { relative } from 'node:path';
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import { isRemoteWorkspace, resolveWorkspaceRoot } from '#profile';
+import { parseManifest } from '#providers/custom/index.ts';
+import { PROVIDER_MANIFESTS } from '#providers/index.ts';
+import { announce, emit, ok, progress } from '../../../output.ts';
+import { nonInteractivePrompter, terminalPrompter, type Prompter } from '../../../prompt.ts';
+import { resolveProfile, type GlobalFlags } from '../../../runtime.ts';
+import { PROGRAM } from '../../../usage.ts';
+import { runConnect, type ConnectOptions } from '../index.ts';
+import { renderOutcome, type ConnectOutcome } from '../outcome.ts';
+import { collect, type Blocked } from './ask.ts';
+import { deriveDeclaration, deriveManifest } from './derive.ts';
+import { RESERVED_BY_GRAMMAR, type CustomFlags } from './spec.ts';
+import {
+  checkOpenapiReachable,
+  manifestDiff,
+  manifestPath,
+  readExistingManifest,
+  renderManifest,
+  writeManifest,
+} from './write.ts';
+
+/**
+ * `lanes link connect custom <id>` — declare a provider, then connect it.
+ *
+ * The built-in list has never been the boundary: a manifest in the profile's
+ * `providers.d/` is validated by the same schema a built-in is and registered
+ * into the same registry, which is the scalability claim of the whole manifest
+ * design. What was missing was the way in. An operator had to find an
+ * undocumented directory, write YAML, and satisfy cross-field rules they could
+ * not see — and the one message that would have told them where to put the file
+ * named a directory nothing reads.
+ *
+ * So this composes the two closed unions: a connectivity type and a credential
+ * type. Anything not covered by a pair of them is not something to bolt on here
+ * — it is a member missing from one of those lists, which is a folder and a
+ * schema entry away. `docs/detailed/connectivity-coverage.md` is the standing
+ * account of which pairs work, which are closed on purpose, and which are not
+ * built yet.
+ *
+ * The manifest is written *before* `runConnect`, because the registry that reads
+ * `providers.d/` is built by `openRuntime` on its first line. Everything that
+ * can be refused is refused before the write.
+ */
+
+export interface ConnectCustomOptions extends GlobalFlags, CustomFlags {
+  readonly json?: boolean | undefined;
+  /** Forwarded to `connect` untouched. */
+  readonly id?: string | undefined;
+  readonly displayName?: string | undefined;
+  readonly replace?: boolean | undefined;
+  readonly nonInteractive?: boolean | undefined;
+  readonly acceptBroadScopes?: boolean | undefined;
+  /** Injected by tests, so the declaration can be checked without a runtime. */
+  readonly prompter?: Prompter | undefined;
+  readonly connectWith?:
+    | ((target: string, options: ConnectOptions, announced?: boolean) => Promise<ConnectOutcome>)
+    | undefined;
+}
+
+export async function connectCustom(
+  providerId: string | undefined,
+  options: ConnectCustomOptions,
+): Promise<void> {
+  if (!providerId) throw new Error(`Usage: ${PROGRAM} connect custom <provider-id>`);
+
+  // Both of these are answerable without reading anything, so they come before
+  // the profile is resolved: loading a config from a bucket is a network call,
+  // and refusing afterwards means having made it to say no.
+  refuseUnusableId(providerId);
+
+  // A manifest is read from the workspace and written to the filesystem, and a
+  // bucket only does the first. Not a limitation of this command: a deployed
+  // revision never rewrites its own config (ADR-007), so a declaration is
+  // authored where the operator is and carried up by the publish that follows.
+  const root = resolveWorkspaceRoot();
+  if (isRemoteWorkspace(root)) {
+    throw new Error(
+      `This workspace is ${root}, and a manifest is written to a local filesystem.\n` +
+        `  Declare it in the workspace you deploy from, and \`${PROGRAM} deploy\` carries it up.`,
+    );
+  }
+
+  const { resolution, target } = await resolveProfile(options);
+  const { workspaceRoot, profile } = resolution;
+
+  // Before it acts, because writing the manifest *is* acting and `usage.ts`
+  // promises every command says where. `runConnect` is told it has been said, so
+  // the line does not appear twice.
+  if (options.json !== true) announce(resolution);
+
+  const path = manifestPath(workspaceRoot, profile, providerId);
+  const rerun = `${PROGRAM} connect custom ${providerId} --profile ${profile} --target ${target}`;
+
+  const prompter =
+    options.prompter ??
+    (options.nonInteractive ? nonInteractivePrompter(rerun) : terminalPrompter);
+
+  const collected = await collect(providerId, options, prompter, (missing) =>
+    [rerun, ...missing.map((flag) => `--${flag} <value>`)].join(' '),
+  );
+
+  if ('missing' in collected) {
+    return refuse(blockedOn(collected, providerId), options.json);
+  }
+
+  const declaration = deriveDeclaration(collected);
+  const text = renderManifest(declaration);
+
+  // Through the loader's own gate, not a copy of it: the entropy check that
+  // refuses a pasted credential, then every cross-field rule. A second
+  // implementation of "is this a secret" is how the two come to disagree.
+  const derived = parseManifest(text, path);
+
+  if (derived.connector.kind === 'http') {
+    await checkOpenapiReachable(derived.connector.openapi, workspaceRoot, profile);
+  }
+
+  // A connection is labelled with the account it belongs to, and a provider that
+  // cannot report one has to be told. Interactively `settleIdentity` asks; with
+  // nobody to ask it throws — but only after the credential has been stored, so
+  // the operator gets two failed runs instead of one refusal. Checked here
+  // because this command is the one that knows no identity block was derived.
+  if (options.nonInteractive && !derived.identity && derived.auth.kind !== 'none' && !options.displayName) {
+    throw new Error(
+      `${derived.name} has no way to report whose account a connection is, so on a run with nobody ` +
+        'to ask it has to be named.\n  Nothing was written. Add --display-name "<label>"' +
+        (derived.connector.kind === 'http'
+          ? ', or --identity-url and --identity-field if the API can answer for itself.'
+          : '.'),
+    );
+  }
+
+  const shown = relative(workspaceRoot, path);
+  const existing = await readExistingManifest(path);
+  const differences = existing ? manifestDiff(deriveManifest(collected), existing) : [];
+
+  if (existing && differences.length > 0 && !options.replaceManifest) {
+    return refuse(alreadyDescribed(shown, differences, rerun, options.replace), options.json);
+  }
+
+  const changes: string[] = [];
+  if (!existing) {
+    await writeManifest(path, text);
+    changes.push(`wrote ${shown}`);
+  } else if (differences.length > 0) {
+    await writeManifest(path, text);
+    changes.push(`rewrote ${shown}`);
+  } else {
+    changes.push(`${shown} unchanged`);
+  }
+
+  // Said now rather than only in the outcome: the connect that follows may open
+  // a browser, and knowing the file landed is worth having before that.
+  progress(ok(changes[0]!));
+
+  // Named field by field rather than spread, because the two commands share a
+  // flag name that means different things. `--auth` here is the credential type
+  // in the manifest — `none`, `basic`, `api-key` — and on `connect` it names
+  // which *route* in, for a provider offering two. Spreading sent `--auth none`
+  // straight through, and `connect` refused a provider it had just been handed
+  // with "--auth accepts: oauth".
+  const handOff = options.connectWith ?? runConnect;
+  const outcome = await handOff(
+    providerId,
+    {
+      profile: options.profile,
+      target: options.target,
+      quiet: options.quiet ?? false,
+      ...(options.id ? { id: options.id } : {}),
+      ...(options.displayName ? { displayName: options.displayName } : {}),
+      ...(options.replace ? { replace: options.replace } : {}),
+      ...(options.nonInteractive ? { nonInteractive: options.nonInteractive } : {}),
+      ...(options.acceptBroadScopes ? { acceptBroadScopes: options.acceptBroadScopes } : {}),
+      ...(options.json ? { json: options.json } : {}),
+    },
+    true,
+  );
+
+  // The manifest first, because it is the change this command made and the rest
+  // is what `connect` made. It stays in the list on a failure too: the file is
+  // real, it is the operator's now, and the retry is plain `connect` — which is
+  // what `then` already says.
+  const merged: ConnectOutcome = { ...outcome, changes: [...changes, ...outcome.changes] };
+
+  if (!merged.ok) process.exitCode = 1;
+
+  // `--json` gets the manifest in `changes`, because that list is what a caller
+  // counts and matches on. The human rendering does not, because they were told
+  // above — before the connect, which is where it mattered — and the same
+  // sentence twice reads as two things having happened.
+  return emit(options.json, merged, () => renderOutcome(outcome));
+}
+
+/**
+ * Ids this command cannot create.
+ *
+ * `custom` is the second word of its own grammar, so such a provider could be
+ * declared, registered, and then never connected. The reserved owner ids are
+ * refused by `defineProvider` a moment later, but with a rule rather than with
+ * the reason — and this is the one place somebody is choosing a name.
+ */
+function refuseUnusableId(id: string): void {
+  if (!/^[a-z][a-z0-9_]*$/.test(id)) {
+    throw new Error(
+      `"${id}" cannot be a provider id: they are lowercase, start with a letter, and use ` +
+        'underscores rather than hyphens — it becomes part of every capability name and every ' +
+        `policy rule. Try "${id.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '')}".`,
+    );
+  }
+
+  if ((RESERVED_BY_GRAMMAR as readonly string[]).includes(id)) {
+    throw new Error(
+      `"${id}" is the second word of this command, so a provider called "${id}" could be declared ` +
+        `and then never connected — \`${PROGRAM} connect ${id}\` would always mean this command. ` +
+        'Pick another id.',
+    );
+  }
+
+  if (RESERVED_PROVIDER_IDS.includes(id)) {
+    throw new Error(
+      `"${id}" is reserved for what this endpoint provides itself — your memory, skills, vault, ` +
+        'setup surface and identity. Pick another id.',
+    );
+  }
+
+  if (PROVIDER_MANIFESTS.some((manifest) => manifest.id === id)) {
+    throw new Error(
+      `"${id}" is already built in, so a manifest of yours would shadow it — and a provider ` +
+        'silently answering differently from the one it is named after is very hard to diagnose ' +
+        `from the outside.\n  Connect the built-in with \`${PROGRAM} connect ${id}\`, or pick ` +
+        'another id.',
+    );
+  }
+}
+
+function blockedOn(blocked: Blocked, providerId: string): ConnectOutcome {
+  const plural = blocked.missing.length === 1 ? 'value' : 'values';
+
+  return {
+    ok: false,
+    changes: [],
+    granted: [],
+    discovered: 0,
+    reason: 'needs_declaration',
+    message:
+      `Declaring ${providerId} needs ${blocked.missing.length} more ${plural}, and this run is ` +
+      'non-interactive.\n  Nothing was written. Either run it in a terminal, or pass:',
+    needs: [],
+    then: blocked.command,
+  };
+}
+
+function alreadyDescribed(
+  shown: string,
+  differences: readonly string[],
+  rerun: string,
+  replacePassed: boolean | undefined,
+): ConnectOutcome {
+  // `--replace` and `--replace-manifest` are one word apart and do different
+  // things, so somebody who reached here with the wrong one is told which.
+  const confusion = replacePassed
+    ? '\n  (--replace asks for the credential again; the manifest is a separate thing.)'
+    : '';
+
+  return {
+    ok: false,
+    changes: [],
+    granted: [],
+    discovered: 0,
+    reason: 'needs_declaration',
+    message:
+      `${shown} already describes this provider, differently. Nothing was written.${confusion}\n` +
+      `${differences.map((line) => `    ${line}`).join('\n')}\n\n` +
+      '  Edit the file and connect it, or replace it:',
+    needs: [],
+    then: `${rerun} --replace-manifest`,
+  };
+}
+
+function refuse(outcome: ConnectOutcome, json: boolean | undefined): void | Promise<void> {
+  process.exitCode = 1;
+  return emit(json, outcome, () => renderOutcome(outcome));
+}

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

@@ -0,0 +1,160 @@
+import type { CustomAnswers } from './spec.ts';
+
+/**
+ * What the manifest says about being connected: what to ask for, and how to
+ * label the account it turns out to be.
+ *
+ * Neither is optional decoration. `ensureStaticCredential` throws for any
+ * credential type that is asked for rather than granted and finds no
+ * per-connection prompt, so a manifest without one is a provider that cannot be
+ * connected at all. And without an `identity` block a connection list reads
+ * `Thing main`, `Thing main2` — which cannot answer the only question anyone
+ * asks of it, and leaves `connect` unable to tell a reconnect from a new
+ * account.
+ */
+
+/** Where a per-account prompt's ref comes from, so it must not be declared. */
+const PER_ACCOUNT = { scope: 'connection' } as const;
+
+/**
+ * The two prompt keys that are not ours to choose.
+ *
+ * `declareOwnClient` looks these up by literal key, and `resolveOAuthClient`
+ * reads `<app>/client_id` and `<app>/client_secret` out of the credential store
+ * by literal string. Spell either differently and the manifest validates,
+ * `connect` collects two secrets from the operator, stores them, and *then*
+ * refuses with "No OAuth client stored" — after they have been through a vendor
+ * console. There is no freedom here and the tests assert it against
+ * `declareOwnClient` rather than against a copy of these strings.
+ */
+const OAUTH_CLIENT_KEYS = ['client_id', 'client_secret'] as const;
+
+export function setupBlock(answers: CustomAnswers): Record<string, unknown> | undefined {
+  const prompts = promptsFor(answers);
+  const docs = documentation(answers);
+
+  if (prompts.length === 0 && Object.keys(docs).length === 0) return undefined;
+  return { ...docs, ...(prompts.length > 0 ? { prompts } : {}) };
+}
+
+function promptsFor(answers: CustomAnswers): Record<string, unknown>[] {
+  const { auth, name } = answers;
+
+  if (auth === 'none') return [];
+
+  if (auth === 'basic') {
+    // Exactly one of each, in this order: `basic` stores `username:password` —
+    // RFC 7617's own encoding — and cannot be assembled from anything else.
+    return [
+      { key: 'username', label: 'Username', ...PER_ACCOUNT, field: 'username' },
+      { key: 'password', label: 'Password', secret: true, ...PER_ACCOUNT, field: 'password' },
+    ];
+  }
+
+  if (auth === 'bearer') {
+    return [{ key: 'token', label: `${name} API token`, secret: true, ...PER_ACCOUNT }];
+  }
+
+  if (auth === 'api-key' || auth === 'header' || auth === 'strategy') {
+    // A strategy negotiates rather than just attaching, but what it starts from
+    // is still one secret the operator holds — bunq's handshake begins with an
+    // API key pasted from the app. If a strategy needs something else, the
+    // manifest is a file and this is one line of it.
+    return [{ key: 'api_key', label: `${name} API key`, secret: true, ...PER_ACCOUNT }];
+  }
+
+  // Dynamic registration asks for nothing: the authorization server hands out a
+  // client and the operator never sees one.
+  const app = clientApp(answers);
+  if (!app) return [];
+
+  return OAUTH_CLIENT_KEYS.map((key) => ({
+    key,
+    label: `${name} OAuth ${key.replace('_', ' ')}`,
+    ...(key === 'client_secret' ? { secret: true } : {}),
+    // Shared across every account of this profile, so the ref cannot derive
+    // from a connection and has to be named.
+    scope: 'shared',
+    credential_ref: `${app}/${key}`,
+  }));
+}
+
+/** The `oauth_apps` entry a manual client lands in, or nothing. */
+function clientApp(answers: CustomAnswers): string | undefined {
+  if (answers.auth !== 'oauth') return undefined;
+
+  const declared = answers.values['registration'];
+  const explicit = answers.values['client-app'];
+  const endpoints = answers.values['authorize-url'];
+
+  const dynamic =
+    declared === 'dynamic' ||
+    (declared === undefined && answers.connector === 'mcp' && !explicit && !endpoints);
+
+  if (dynamic) return undefined;
+  return typeof explicit === 'string' && explicit.length > 0 ? explicit : answers.id;
+}
+
+/**
+ * `--setup-docs`, placed by shape.
+ *
+ * Never into `setup.docs`, which nothing reads — `printSetup` renders `summary`,
+ * `docs_url` and `steps`, and `planFor` reads `docs_url`. A manifest using
+ * `docs` validates and then shows the operator nothing, which is the worst of
+ * the three outcomes.
+ */
+function documentation(answers: CustomAnswers): Record<string, unknown> {
+  const value = answers.values['setup-docs'];
+  if (typeof value !== 'string' || value.length === 0) return {};
+
+  if (!/^https?:\/\//i.test(value)) return { steps: [value] };
+
+  const app = clientApp(answers);
+  return {
+    docs_url: value,
+    // The one thing a vendor's console asks for that this command knows and the
+    // operator cannot guess: the redirect URI is a loopback address on a port
+    // chosen per run, so a fixed port registered there will not match.
+    ...(app
+      ? {
+          steps: [
+            `Register an OAuth client at ${value}. Its redirect URI is a loopback address on a port ` +
+              'chosen per run, which most authorization servers accept. One that matches the whole ' +
+              'URL will refuse the grant with redirect_uri_mismatch — declare the URL it was given ' +
+              'with --redirect-uri if so.',
+          ],
+        }
+      : {}),
+  };
+}
+
+/**
+ * How this provider will say whose account was authorised.
+ *
+ * Three transports implement `identify()` — imap, dav and fs — and for the first
+ * two it is also the credential check, since the answer is the name the *server
+ * accepted* rather than the one the operator typed. An mcp connector gets no
+ * block: the identity would be a tool call, and a guessed tool name turns a
+ * working connect into a failed probe. An http one gets a block only when both
+ * halves were given, because a URL with no field to read is not an identity.
+ */
+export function identityBlock(answers: CustomAnswers): Record<string, unknown> | undefined {
+  if (answers.connector === 'imap' || answers.connector === 'dav' || answers.connector === 'fs') {
+    return { kind: 'connector' };
+  }
+
+  if (answers.connector !== 'http') return undefined;
+
+  const url = answers.values['identity-url'];
+  const field = answers.values['identity-field'];
+  if (typeof url !== 'string' || url.length === 0) return undefined;
+
+  if (typeof field !== 'string' || field.length === 0) {
+    throw new Error(
+      '--identity-url needs --identity-field: the probe is one GET, and the field is which value in ' +
+        'the response names the account. Without it there is nothing to read out of the body.',
+    );
+  }
+
+  return { kind: 'http', url, field };
+}