@lanes-sh/link 0.1.0

package/src/providers/memory/provider.ts

@@ -0,0 +1,429 @@
+import { z } from 'zod';
+import { splitOptionalFrontmatter, stringList, withFrontmatter } from '#providers/shared/frontmatter.ts';
+import {
+  defineLocalProvider,
+  keepKeys,
+  type BlobStore,
+  type ProviderDefinition,
+} from '#connectivity';
+
+/**
+ * `memory` — the owner's accumulated knowledge.
+ *
+ * **Reading and writing are separate capabilities**, and that separation is the
+ * whole security argument for this provider (ADR-012 §2, `docs/detailed/security.md`).
+ * Upstream content is already treated as potentially prompt-injecting and passed
+ * through unscreened; memory an agent can *write to* changes the shape of that
+ * risk rather than its size, because an injected instruction is stored once and
+ * re-served to every future session, including to a different agent. A read-only
+ * memory cannot do that. Nothing here screens what is written — this separates
+ * the privilege, and makes no claim to detect anything.
+ *
+ * **One entry is one Markdown file.** Title, tags, and timestamp are YAML
+ * frontmatter above the body, in the same format a skill uses, and the whole
+ * thing is a single `BlobStore` object — locally a file under the profile's
+ * storage directory, in a deployment an S3 object. There is no index row.
+ *
+ * That is a deliberate reversal of the original split (ADR-014). An index in
+ * `ScopedStore` beside a body in `BlobStore` made listing cheap, and cost more
+ * than it bought: the two could disagree, the entry could not be opened in an
+ * editor, and a hand-written file was not an entry at all. `lanes link memory` and a
+ * text editor now reach the same bytes, which is the point of the format.
+ *
+ * The store is namespaced `<provider>/<connection>` by core before this
+ * provider sees it, so one connection's memory is not addressable from another.
+ */
+
+const DEFAULT_LIMIT = 10;
+/**
+ * No key prefix.
+ *
+ * There was an `entry/` one, which put a third segment under a path that was
+ * already `<provider>/<connection>` — an entry landed at
+ * `memory/memory/entry/<id>.md`. The namespace is the isolation boundary and it
+ * is already applied by the time a key reaches here, so the prefix only ever
+ * separated entries from other things this provider does not store.
+ */
+const ENTRY_PREFIX = '';
+
+/** An entry's frontmatter, parsed. Every field has a fallback — see `readEntry`. */
+interface Entry {
+  readonly id: string;
+  readonly title: string;
+  readonly tags: readonly string[];
+  readonly updatedAt: string;
+  readonly body: string;
+  readonly bytes: number;
+}
+
+const ENTRY_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+function entryKey(id: string): string {
+  return `${ENTRY_PREFIX}${id}.md`;
+}
+
+function idFromKey(key: string): string | null {
+  if (!key.startsWith(ENTRY_PREFIX) || !key.endsWith('.md')) return null;
+  const id = key.slice(ENTRY_PREFIX.length, -'.md'.length);
+  return ENTRY_ID.test(id) ? id : null;
+}
+
+/**
+ * Parse one stored entry.
+ *
+ * Frontmatter is optional, and its absence is not an error: these files are in
+ * a directory the owner may edit, and a plain Markdown file dropped in there
+ * should read as an entry titled after its id rather than break the listing
+ * that would have shown it. `lanes link memory write` puts the frontmatter back.
+ */
+function parseEntry(id: string, text: string, fallbackUpdatedAt: string): Entry {
+  const { frontmatter, body } = splitOptionalFrontmatter(text);
+  const title = frontmatter['title'];
+  const updatedAt = frontmatter['updated_at'];
+
+  return {
+    id,
+    title: typeof title === 'string' && title.trim().length > 0 ? title : id,
+    tags: stringList(frontmatter['tags']),
+    updatedAt: typeof updatedAt === 'string' ? updatedAt : fallbackUpdatedAt,
+    body: body.trimEnd(),
+    bytes: new TextEncoder().encode(text).byteLength,
+  };
+}
+
+function serialiseEntry(entry: {
+  title: string;
+  tags: readonly string[];
+  updatedAt: string;
+  body: string;
+}): string {
+  return withFrontmatter(
+    {
+      title: entry.title,
+      ...(entry.tags.length > 0 ? { tags: [...entry.tags] } : {}),
+      updated_at: entry.updatedAt,
+    },
+    `${entry.body.trimEnd()}\n`,
+  );
+}
+
+async function readEntry(storage: BlobStore, id: string): Promise<Entry | null> {
+  const bytes = await storage.get(entryKey(id));
+  if (bytes === null) return null;
+
+  return parseEntry(id, new TextDecoder().decode(bytes), new Date(0).toISOString());
+}
+
+/**
+ * How many entries are read at once.
+ *
+ * A bound rather than `Promise.all` over the whole listing: against a bucket
+ * each read is an HTTPS request, and firing four hundred at once trades a slow
+ * search for a rate-limited one. Against a local directory the cap costs
+ * nothing measurable.
+ */
+const READ_CONCURRENCY = 16;
+
+/**
+ * Every entry, newest first.
+ *
+ * **This reads every entry, and is honest about being one pass over all of
+ * them.** That is the cost of one file per entry: the metadata a listing needs
+ * is inside the document, so there is nothing cheaper to consult. At owner
+ * scale — hundreds of entries, one process, a local directory — it is fine, and
+ * the previous index row bought its speed by being a second copy that could
+ * disagree with the file it described.
+ *
+ * The reads are concurrent, which is not a micro-optimisation: one pass over
+ * four hundred entries is four hundred serial round trips once the store is a
+ * bucket rather than a directory, and serial round trips are the whole of the
+ * difference between a search that feels instant and one that times out.
+ *
+ * If this ever has to serve tens of thousands of entries, the fix is a derived
+ * cache that can be rebuilt from the files, never a second source of truth.
+ */
+async function allEntries(storage: BlobStore): Promise<Entry[]> {
+  const blobs = (await storage.list(ENTRY_PREFIX)).flatMap((blob) => {
+    const id = idFromKey(blob.key);
+    return id === null ? [] : [{ blob, id }];
+  });
+
+  const entries: Entry[] = [];
+
+  for (let start = 0; start < blobs.length; start += READ_CONCURRENCY) {
+    const batch = await Promise.all(
+      blobs.slice(start, start + READ_CONCURRENCY).map(async ({ blob, id }) => {
+        const bytes = await storage.get(blob.key);
+        return bytes === null
+          ? null
+          : parseEntry(id, new TextDecoder().decode(bytes), blob.modifiedAt.toISOString());
+      }),
+    );
+    for (const entry of batch) if (entry) entries.push(entry);
+  }
+
+  return entries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** A stable id from a title, so writing does not demand one be invented. */
+function slugify(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+
+  return slug.length > 0 ? slug : `entry-${title.length}`;
+}
+
+export const memoryProvider: ProviderDefinition = defineLocalProvider({
+  id: 'memory',
+  name: 'Memory',
+  version: '1.0.0',
+  description:
+    "The owner's accumulated knowledge. Entries are addressed by id as resources and found by content with memory.search. Writing is a separate capability from reading.",
+
+  configSchema: z.object({}),
+  connectionSchema: z.object({}),
+
+  bundles: [
+    {
+      name: 'read',
+      description: 'Retrieve and search entries.',
+      oauth_scopes: [],
+      capabilities: ['entry', 'search', 'get'],
+      default: true,
+    },
+    {
+      // Not in the default bundle, and worth denying explicitly for any agent
+      // that does not need it — see the provider docstring.
+      name: 'write',
+      description: 'Create, replace, and delete entries.',
+      oauth_scopes: [],
+      capabilities: ['write', 'forget'],
+    },
+  ],
+
+  capabilities: [
+    /**
+     * Retrieval by address — a resource, not a tool (ADR-006).
+     *
+     * A memory entry is read-oriented context with a stable identifier, which is
+     * the definition of the primitive. It is the case ADR-006 said the
+     * distinction would matter for.
+     */
+    {
+      kind: 'resource',
+      name: 'entry',
+      title: 'Memory entry',
+      description: 'One stored memory entry, addressed by its id.',
+      uriTemplate: 'memory://entry/{id}',
+      mimeType: 'text/markdown',
+      // The address is worth recording and the content is not — the same trade
+      // `gmail.get_message` makes with a message id.
+      redact: keepKeys('uri'),
+
+      async list(context) {
+        return (await allEntries(context.storage)).map((entry) => ({
+          uri: `memory://entry/${encodeURIComponent(entry.id)}`,
+          name: entry.title,
+        }));
+      },
+
+      async read(uri, params, context) {
+        const raw = params['id'];
+        if (!raw) throw new Error(`Malformed memory URI: ${uri}`);
+
+        const id = decodeURIComponent(raw);
+        const entry = await readEntry(context.storage, id);
+        if (entry === null) throw new Error(`No memory entry "${id}" on ${context.connection.key}`);
+
+        return { uri, mimeType: 'text/markdown', text: entry.body };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'get',
+      title: 'Read a memory entry',
+      description:
+        'Return one entry by id. The resource memory://entry/{id} is the same content; this exists for clients that do not read resources.',
+      inputSchema: z.object({
+        id: z.string().min(1).describe('Entry id'),
+      }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const entry = await readEntry(context.storage, id);
+
+        if (entry === null) {
+          return {
+            content: [{ type: 'text', text: `No memory entry "${id}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        return { content: [{ type: 'text', text: entry.body }] };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'search',
+      title: 'Search memory',
+      description:
+        'Find entries whose title, tags, or body contain the query. Case-insensitive substring matching, not ranked relevance.',
+      inputSchema: z.object({
+        query: z.string().min(1).describe('Text to look for'),
+        tag: z.string().optional().describe('Restrict to entries carrying this tag'),
+        limit: z.number().int().min(1).max(50).optional().describe(`Maximum results (default ${DEFAULT_LIMIT})`),
+      }),
+      // Nothing kept: a memory query is as revealing as a Gmail search query,
+      // and frequently more so — it is the owner's own material being asked for.
+      async handler({ query, tag, limit }, context) {
+        const needle = query.toLowerCase();
+        const entries = await allEntries(context.storage);
+        const candidates = tag ? entries.filter((entry) => entry.tags.includes(tag)) : entries;
+
+        const matches: Array<{ entry: Entry; snippet: string }> = [];
+
+        for (const entry of candidates) {
+          if (matches.length >= (limit ?? DEFAULT_LIMIT)) break;
+
+          const inHeader =
+            entry.title.toLowerCase().includes(needle) ||
+            entry.tags.some((value) => value.toLowerCase().includes(needle));
+
+          const at = entry.body.toLowerCase().indexOf(needle);
+          if (!inHeader && at === -1) continue;
+
+          matches.push({ entry, snippet: at === -1 ? entry.title : excerpt(entry.body, at) });
+        }
+
+        context.audit.annotate({ scanned: candidates.length, matched: matches.length });
+
+        if (matches.length === 0) {
+          return { content: [{ type: 'text', text: `No memory entry matches on ${context.connection.key}.` }] };
+        }
+
+        // A `resource_link` rather than a URI spelled into the text: core routes
+        // the link to the profile and connection this call was made on, and a
+        // provider must not learn either. Written as text it would name an
+        // address no client could read.
+        return {
+          content: matches.flatMap(({ entry, snippet }) => [
+            {
+              type: 'resource_link' as const,
+              uri: `memory://entry/${encodeURIComponent(entry.id)}`,
+              name: entry.title,
+            },
+            {
+              type: 'text' as const,
+              text: `${entry.title}${entry.tags.length > 0 ? ` [${entry.tags.join(', ')}]` : ''}\n${snippet}`,
+            },
+          ]),
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'write',
+      title: 'Store a memory entry',
+      description:
+        'Create or replace an entry. Deliberately a separate capability from reading: an instruction written here is served to every later session, so an agent that only needs to recall should not be granted this.',
+      inputSchema: z.object({
+        title: z.string().min(1).describe('Short human-readable title'),
+        text: z.string().min(1).describe('The entry body, as Markdown'),
+        id: z.string().optional().describe('Entry id. Derived from the title when omitted; naming an existing one replaces it.'),
+        tags: z.array(z.string()).optional().describe('Labels for filtering searches'),
+      }),
+      // The title and the id are addresses; the text is the content itself.
+      redact: keepKeys('id', 'title', 'tags'),
+      async handler({ title, text, id, tags }, context) {
+        const entryId = id ?? slugify(title);
+        assertEntryId(entryId);
+
+        const document = serialiseEntry({
+          title,
+          tags: tags ?? [],
+          updatedAt: new Date().toISOString(),
+          body: text,
+        });
+        const bytes = new TextEncoder().encode(document);
+        await context.storage.put(entryKey(entryId), bytes, { contentType: 'text/markdown' });
+
+        context.audit.annotate({ entry: entryId, bytes: bytes.byteLength });
+
+        return {
+          content: [
+            { type: 'text', text: `Stored memory entry "${entryId}" on ${context.connection.key}.` },
+            { type: 'resource_link', uri: `memory://entry/${entryId}`, name: title },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'forget',
+      title: 'Delete a memory entry',
+      description: 'Remove an entry and its body.',
+      inputSchema: z.object({
+        id: z.string().min(1).describe('Entry id'),
+      }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const existed = await context.storage.has(entryKey(id));
+        await context.storage.delete(entryKey(id));
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: existed
+                ? `Forgot memory entry "${id}" on ${context.connection.key}.`
+                : `No memory entry "${id}" on ${context.connection.key}.`,
+            },
+          ],
+          ...(existed ? {} : { isError: true }),
+        };
+      },
+    },
+  ],
+});
+
+export function assertEntryId(id: string): void {
+  if (!ENTRY_ID.test(id)) {
+    throw new Error(
+      `Memory entry id ${JSON.stringify(id)} must be lowercase letters, digits, "_" or "-".`,
+    );
+  }
+}
+
+/** A window around a match, so a result says why it matched. */
+function excerpt(body: string, at: number, width = 160): string {
+  const start = Math.max(0, at - width / 4);
+  const text = body.slice(start, start + width).replace(/\s+/g, ' ').trim();
+  return `${start > 0 ? '…' : ''}${text}${start + width < body.length ? '…' : ''}`;
+}
+
+export default memoryProvider;
+
+/**
+ * The pieces `lanes link memory` needs to reach the same bytes this provider does.
+ *
+ * Exported rather than reimplemented in the CLI: two spellings of one storage
+ * layout is exactly how a control plane and its data plane drift apart.
+ */
+export const memoryStorage = {
+  key: entryKey,
+  idFromKey,
+  parse: parseEntry,
+  serialise: serialiseEntry,
+  read: readEntry,
+  all: allEntries,
+  prefix: ENTRY_PREFIX,
+  slugify,
+};
+
+export type MemoryEntry = Entry;

package/src/providers/notion/index.ts

@@ -0,0 +1,19 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Notion supports Dynamic Client Registration, so there is genuinely nothing
+ * for an operator to do: we register ourselves with their authorization server
+ * at connect time. Browser, approve, done.
+ */
+export const notion = defineProvider({
+  id: 'notion',
+  name: 'Notion',
+  description: 'Pages, databases, comments, and workspace search, via Notion\'s official MCP server.',
+  connector: { kind: 'mcp', endpoint: 'https://mcp.notion.com/mcp' },
+  auth: { kind: 'oauth', registration: 'dynamic' },
+  // No identity block on purpose. Notion exposes no "who am I" tool:
+  // `get-users` leads with integration bots rather than the person, and
+  // `get-teams` returns teamspaces, which are not the workspace and may be in
+  // the trash. Both would produce a confident wrong label, so `connect` asks
+  // instead — the fallback exists for exactly this.
+});

package/src/providers/owner.ts

@@ -0,0 +1,49 @@
+/**
+ * The owner layer — memory, skills, vault.
+ *
+ * Three providers that hold no third-party account: no OAuth, no vendor API, no
+ * rate limit anyone else imposes. They are ordinary `defineLocalProvider`
+ * registrations, configured by the same `lanes link connect <provider>`, scoped by the
+ * same profiles, and gated by the same policy evaluation as everything else —
+ * which was the claim `docs/detailed/init.md` made and called the real test of the
+ * architecture.
+ *
+ * They live in `./memory/`, `./skills/` and `./vault/`, beside `google/` and
+ * `icloud/`, because that claim is only true if they are providers in the
+ * layout as well as in the prose. This file is the one thing they share: a
+ * barrel, because each is *constructed* with a store rather than declared as
+ * data, so `#profile`'s registry builder needs all three together.
+ *
+ * `setup` joined them later and is the same shape: it holds no account either,
+ * and it describes the other three rather than reaching anything. It is
+ * read-only by construction — see ADR-019 for why describing setup is not one
+ * of ADR-007's control-plane exclusions.
+ *
+ * The ids `memory`, `skills`, `vault`, and `setup` are reserved (`RESERVED_PROVIDER_IDS`)
+ * and still refused by default — the registry has to be built with
+ * `allowReserved` to hold them, so a third-party provider cannot claim a
+ * namespace whose policy rules would then mean something else.
+ */
+
+export { memoryProvider, memoryStorage, assertEntryId, type MemoryEntry } from './memory/provider.ts';
+export { createSkillsProvider, type SkillsProviderOptions } from './skills/provider.ts';
+export { createVaultProvider, type VaultProviderOptions } from './vault/provider.ts';
+export { createSetupProvider, type SetupProviderOptions } from './setup/provider.ts';
+export { planAll, planFor, type PlanContext, type ProviderPlan } from './setup/plan.ts';
+// The vault's *store* is not here: it is `#secrets`, beside the system
+// credential store it must never become. What lives in `./vault/` is the
+// provider — the capabilities, and the rule that each item is its own.
+export {
+  assertItemId,
+  createBlobVaultStore,
+  createFileVaultStore,
+  createMemoryVaultStore,
+  createSecretVaultStore,
+  generateVaultKey,
+  VAULT_ITEM_ID,
+  type BlobVaultStoreOptions,
+  type SecretVaultStoreOptions,
+  type FileVaultStoreOptions,
+  type VaultItem,
+  type VaultStore,
+} from '#secrets';

package/src/providers/scopes.ts

@@ -0,0 +1,26 @@
+import { GOOGLE_SCOPE_MEANINGS } from './google/shared/scopes.ts';
+import { LINEAR_SCOPE_MEANINGS } from './linear/scopes.ts';
+
+/**
+ * What a scope actually permits, contributed by the provider that requests it.
+ *
+ * Least privilege is the goal, and a vendor's *advertised* scope list is not the
+ * same as its required one. Where a grant does have to be broad it must not
+ * happen quietly: an over-broad grant is invisible after the fact, and a consent
+ * screen listing five Google-worded scopes is not where someone discovers that
+ * "Gmail" meant permanent delete.
+ *
+ * The table is here rather than in the CLI so that a provider owns its own
+ * vocabulary. The CLI renders it and never learns a vendor's words.
+ */
+export interface ScopeMeaning {
+  /** Plain-English meaning. */
+  readonly meaning: string;
+  /** Unrestricted access to the service, or close enough to warrant a stop. */
+  readonly broad?: boolean;
+}
+
+export const SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  ...GOOGLE_SCOPE_MEANINGS,
+  ...LINEAR_SCOPE_MEANINGS,
+};

package/src/providers/setup/plan.ts

@@ -0,0 +1,141 @@
+import type { ProviderManifest } from '#connectivity';
+import { setupRequirements, type SetupRequirement } from '#connectivity';
+
+/**
+ * What connecting a provider involves, assembled from its manifest.
+ *
+ * One implementation, two consumers: `lanes link setup plan` renders it for a
+ * terminal, and the `setup.provider` capability renders it for a model. Both
+ * must emit the *same* command, because the model's job is to hand a person
+ * something to paste — a tool that suggested a command the CLI would reject is
+ * worse than one that suggested nothing.
+ *
+ * Nothing here reads the credential store. What a provider *requires* is a
+ * property of shipped code; whether it is *satisfied* needs a store, and only
+ * the CLI asks that — ADR-007.
+ */
+
+export interface ProviderPlan {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  /** Connection keys of this provider already configured, e.g. `gmail.main`. */
+  readonly connected: readonly string[];
+  /**
+   * Whether this provider holds accounts at all, and so can hold another.
+   *
+   * `auth.kind === 'none'` means there is no credential to key on a connection
+   * id, so a second row would address the same thing the first does and "connect
+   * another" is meaningless. Everything else derives `<provider>/<id>` (or the
+   * `app` it shares), so a second account is a second `connect`.
+   *
+   * Read that as the credential test it is, not as "the owner layer". The owner
+   * layer never reaches here — `catalogue` is `PROVIDER_MANIFESTS`, the shipped
+   * third-party providers, and `memory`, `skills`, `vault` and `setup` are
+   * registered separately and are not in it. The one manifest this actually
+   * excludes is `icloud_drive`, which is `auth: none` because Apple exposes a
+   * synced folder rather than a protocol: its root is a manifest field, so a
+   * second connection would read the same files off the same Mac. Correct, and
+   * for a reason worth stating, because the next `auth: none` provider added
+   * with a per-connection identity would be excluded here silently and wrongly.
+   *
+   * This exists because the overview used to drop a provider entirely once it
+   * had one connection, which made "connect another Gmail account" unanswerable
+   * from the surface built to answer it.
+   */
+  readonly multiAccount: boolean;
+  /**
+   * Finishing this needs a person at a browser.
+   *
+   * The one fact that decides whether an agent can do it. Everything else is a
+   * value that can be written to the store and then used.
+   */
+  readonly browser: boolean;
+  readonly summary?: string;
+  readonly docsUrl?: string;
+  readonly steps: readonly string[];
+  readonly requires: readonly SetupRequirement[];
+  /** True when the command below needs `--id` filling in first. */
+  readonly needsId: boolean;
+  /** The one line that connects it. */
+  readonly command: string;
+  /**
+   * The OAuth client is operated by somebody else, so `requires` is empty
+   * because there is nothing to register — not because setup is trivial.
+   */
+  readonly brokered: boolean;
+  /** Who operates that client, for the sentence shown before consent. */
+  readonly clientOperator?: string;
+  /** The line that opts out of it and registers one of your own instead. */
+  readonly ownClientCommand?: string;
+}
+
+export interface PlanContext {
+  readonly profile: string;
+  /** Every configured connection this caller may see, as `provider.id`. */
+  readonly connections: readonly string[];
+  /**
+   * `oauth_apps` entries this profile declares.
+   *
+   * Which clients are the operator's own, so a profile that has registered one
+   * is described as needing it rather than as needing nothing.
+   */
+  readonly ownClients?: readonly string[];
+}
+
+export function planFor(
+  manifest: ProviderManifest,
+  context: PlanContext,
+  connectionId?: string,
+): ProviderPlan {
+  const { requirements, needsId, brokered } = setupRequirements(
+    manifest,
+    connectionId,
+    context.profile,
+    { ...(context.ownClients ? { ownClients: context.ownClients } : {}) },
+  );
+
+  const connected = context.connections.filter((key) => key.startsWith(`${manifest.id}.`));
+
+  // `--profile` always, never conditionally. One endpoint serves every profile,
+  // and the shell this command is pasted into may default to a different one —
+  // which is exactly what `resolveSelection`'s "never a silent pick" rule
+  // exists to prevent.
+  const command =
+    `lanes link connect ${manifest.id} --profile ${context.profile}` +
+    (needsId ? ' --id <name>' : connectionId ? ` --id ${connectionId}` : '');
+
+  return {
+    id: manifest.id,
+    name: manifest.name,
+    description: manifest.description,
+    connected,
+    multiAccount: manifest.auth.kind !== 'none',
+    browser: manifest.auth.kind === 'oauth',
+    ...(manifest.setup?.summary ? { summary: manifest.setup.summary } : {}),
+    ...(manifest.setup?.docs_url ? { docsUrl: manifest.setup.docs_url } : {}),
+    steps: manifest.setup?.steps ?? [],
+    requires: requirements,
+    needsId,
+    command,
+    brokered,
+    ...(brokered && manifest.auth.kind === 'oauth' && manifest.auth.broker
+      ? {
+          clientOperator: manifest.auth.broker.operator,
+          // The steps stay in `steps` either way. A renderer decides whether to
+          // show a console walkthrough for a path nobody has asked for; the
+          // plan's job is to say the path exists and what opens it.
+          ownClientCommand: `${command} --own-client`,
+        }
+      : {}),
+  };
+}
+
+export function planAll(
+  manifests: readonly ProviderManifest[],
+  context: PlanContext,
+): ProviderPlan[] {
+  return [...manifests]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map((manifest) => planFor(manifest, context));
+}