@lanes-sh/link 0.1.0

package/src/providers/setup/provider.ts

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+import { defineLocalProvider, keepKeys, type ProviderDefinition, type ProviderManifest } from '#connectivity';
+import { planAll, planFor, type ProviderPlan } from './plan.ts';
+
+/**
+ * `setup` — what is connected, and what connecting something else would take.
+ *
+ * **Read-only by construction, and that is the whole design.** ADR-007 keeps
+ * connection creation, credential writing, OAuth, and configuration mutation off
+ * the MCP surface, because each authorises *future* agent behaviour and the
+ * decision has to originate outside the agent. Describing what setup requires
+ * authorises nothing: it is the same category as `tools/list`, which already
+ * tells a caller what exists. ADR-019 records the argument.
+ *
+ * So there are two capabilities, both reads, and no write bundle. The absence is
+ * a decision rather than an omission — see `provider.test.ts`, which asserts the
+ * capability list holds nothing else.
+ *
+ * Everything it reports is either shipped code (which providers exist, what
+ * their setup blocks say) or already visible to the same caller through
+ * `tools/list`, the injected `profile` and `connection` enums, and the
+ * unauthenticated `/health`. The one genuinely new fact is the account *label*
+ * on a connection — `you@example.com` — and it is deliberate: a caller holding a
+ * grant on `gmail.main` can already read that mailbox, which discloses the
+ * address on the first message. Withholding it here while serving the mailbox
+ * would be theatre, and the label is the entire point.
+ *
+ * What it must never report is whether a credential is *present*. That is the
+ * requires/satisfied split: this surface says what setup needs, and only
+ * `lanes link` says what is already there. `missingRequirements` is CLI-only for
+ * exactly this reason.
+ *
+ * The names are load-bearing. `control-plane.test.ts` runs seven unanchored
+ * patterns over every registered capability id, so `setup.connection_steps`
+ * trips the `connect` pattern (`.connect` matches inside `.connection_`) and
+ * `setup.credentials_needed` trips the credential one. `overview` and `provider`
+ * are clean. Renaming either is not a cosmetic change.
+ */
+
+export interface SetupProviderOptions {
+  /**
+   * Which profile this instance serves.
+   *
+   * Stamped at construction because a handler cannot learn it: `makeHandler`
+   * strips `profile` off the arguments before dispatch, and `ProviderContext`
+   * does not carry it. Every emitted command needs it, so it has to arrive
+   * here — one registry is built per profile, so each instance gets its own.
+   */
+  readonly profile: string;
+  /** Sibling profile names on this endpoint. Names only; already at `/health`. */
+  readonly profiles?: readonly string[];
+  /**
+   * `oauth_apps` entries this profile declares.
+   *
+   * Configuration, not a credential: it names which vendors this profile holds
+   * a client of its own for, never whether the client is stored. Reporting a
+   * provider as needing nothing when the profile has in fact registered one
+   * would send the owner to a command that then asks for two values.
+   */
+  readonly ownClients?: readonly string[];
+  /** Every provider this build ships. Shipped code, identical for every caller. */
+  readonly catalogue?: readonly ProviderManifest[];
+  /**
+   * Accounts this principal can actually reach, in this profile.
+   *
+   * A function, not a snapshot, so it is evaluated per call. Computed by the
+   * caller because filtering it is a policy decision and `#providers` may not
+   * import `#policy` — `open.ts` runs it through the same `allowedConnections`
+   * the dispatcher enforces with and `mergeCapabilities` builds the connection
+   * enum from. Computing it separately here is how discovery and enforcement
+   * drift, and a leak in discovery is still a leak.
+   */
+  readonly reachable?: () => ReadonlyArray<{ key: string; provider: string; account: string }>;
+}
+
+export function createSetupProvider(options: SetupProviderOptions): ProviderDefinition {
+  const catalogue = options.catalogue ?? [];
+  const reachable = options.reachable ?? (() => []);
+
+  const context = () => ({
+    profile: options.profile,
+    connections: reachable().map((connection) => connection.key),
+    ...(options.ownClients ? { ownClients: options.ownClients } : {}),
+  });
+
+  return defineLocalProvider({
+    id: 'setup',
+    name: 'Setup',
+    version: '1.0.0',
+    description:
+      'What this endpoint is connected to, and what connecting something else would involve. ' +
+      'Read-only: nothing here writes configuration, stores a credential, runs a sign-in, or ' +
+      'changes what is permitted — those are control-plane operations and stay in the CLI.',
+
+    configSchema: z.object({}),
+    connectionSchema: z.object({}),
+
+    bundles: [
+      {
+        name: 'read',
+        description: 'Describe what is set up. There is no write bundle, by design.',
+        oauth_scopes: [],
+        capabilities: ['overview', 'provider'],
+        default: true,
+      },
+    ],
+
+    capabilities: [
+      {
+        kind: 'tool',
+        name: 'overview',
+        title: 'What is set up',
+        description:
+          'List the accounts reachable in this profile and the providers that could be connected. ' +
+          'Call this before answering any question about what you can reach, or before suggesting ' +
+          'that something be set up.',
+        inputSchema: z.object({}),
+        // No arguments to redact.
+        async handler(_input, handlerContext) {
+          const connections = reachable();
+          const plans = planAll(catalogue, context());
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: renderOverview(options, connections, plans, handlerContext.connection.key),
+              },
+            ],
+          };
+        },
+      },
+
+      {
+        kind: 'tool',
+        name: 'provider',
+        title: 'What connecting one provider takes',
+        description:
+          'The console steps, the values needed, and the exact command that connects it. ' +
+          'Use this to tell the owner what to run — do not compose the command yourself.',
+        inputSchema: z.object({
+          id: z.string().min(1).describe('Provider id, as listed by setup_overview — e.g. "notion"'),
+          connection: z
+            .string()
+            .optional()
+            .describe('Name for the account, when the provider stores a credential per account'),
+        }),
+        // A provider id is a name this project ships, not the owner's data, so
+        // it is worth recording verbatim: an audit line that cannot say which
+        // provider was asked about answers very little. `connection` is a label
+        // the caller chose and is type-marked with everything else.
+        redact: keepKeys('id'),
+        async handler({ id, connection }, _handlerContext) {
+          const manifest = catalogue.find((candidate) => candidate.id === id);
+
+          if (!manifest) {
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text:
+                    `No provider "${id}". Call setup_overview for the ids this endpoint knows.`,
+                },
+              ],
+              isError: true,
+            };
+          }
+
+          return {
+            content: [{ type: 'text', text: renderProvider(planFor(manifest, context(), connection)) }],
+          };
+        },
+      },
+    ],
+  });
+}
+
+function renderOverview(
+  options: SetupProviderOptions,
+  connections: ReadonlyArray<{ key: string; account: string }>,
+  plans: readonly ProviderPlan[],
+  self: string,
+): string {
+  const lines: string[] = [`Profile "${options.profile}".`, ''];
+
+  if (connections.length === 0) {
+    lines.push('No accounts are connected and reachable here yet.');
+  } else {
+    lines.push('Connected and reachable:');
+    for (const connection of connections) {
+      lines.push(`  ${connection.key}  — ${connection.account}`);
+    }
+  }
+
+  // Anything already connected is filtered out by `connected`, and anything
+  // configured but not granted never reached `reachable()` — so a denied
+  // provider appears here as merely available, indistinguishable from one that
+  // was never connected. That is ADR-007's "probing must not be an oracle".
+  //
+  // Both lists key off `plan.connected`, which is the policy-filtered set, and
+  // never off the raw config. Keying the second one off what is *configured*
+  // would say "gmail is connected" about a connection policy hides, which is
+  // the oracle this is careful not to be.
+  const available = plans.filter((plan) => plan.connected.length === 0);
+
+  if (available.length > 0) {
+    lines.push('', 'Could be connected:');
+    for (const plan of available) {
+      lines.push(`  ${plan.id}${plan.browser ? '  (needs a browser sign-in)' : ''} — ${plan.description}`);
+    }
+    lines.push('', 'For what one of them takes, call setup_provider with its id.');
+  }
+
+  // A provider used to vanish from this surface the moment it had one
+  // connection, so "connect another Gmail account" — the question this exists
+  // to answer — had no answer in the overview at all, and an agent reading it
+  // would conclude none was possible and improvise. Saying so costs one line.
+  const more = plans.filter((plan) => plan.connected.length > 0 && plan.multiAccount);
+
+  if (more.length > 0) {
+    lines.push(
+      '',
+      `Already connected, and able to hold a further account: ${more.map((plan) => plan.id).join(', ')}.`,
+      'Connecting a second account is the same command again — call setup_provider with the id for it.',
+    );
+  }
+
+  const siblings = (options.profiles ?? []).filter((name) => name !== options.profile);
+  if (siblings.length > 0) {
+    lines.push(
+      '',
+      `This endpoint also serves: ${siblings.join(', ')}. Pass that profile to see what it reaches.`,
+    );
+  }
+
+  lines.push(
+    '',
+    'Setting anything up is done by the owner, in a terminal — this endpoint cannot do it. ' +
+      'A connection they make is served here within moments of them making it.',
+    `(reported for connection ${self})`,
+  );
+
+  return lines.join('\n');
+}
+
+function renderProvider(plan: ProviderPlan): string {
+  const lines: string[] = [`${plan.name} — ${plan.description}`];
+
+  if (plan.summary) lines.push('', plan.summary);
+  if (plan.docsUrl) lines.push(plan.docsUrl);
+
+  if (plan.connected.length > 0) {
+    lines.push('', `Already connected here: ${plan.connected.join(', ')}.`);
+
+    // Without this the reader has a list of existing accounts and a command,
+    // and no way to know the command is the one that adds another rather than
+    // the one that already ran.
+    if (plan.multiAccount) {
+      lines.push(
+        'The command below adds another account rather than replacing those — ' +
+          'each account is its own connection.',
+      );
+    }
+  }
+
+  // A console walkthrough is withheld from this surface when it does not apply.
+  // A model handed nine steps it has no reason to relay will relay them, and
+  // the owner ends up registering a client they did not need.
+  if (plan.steps.length > 0 && !plan.brokered) {
+    lines.push('', 'The owner does this first, in the vendor’s own console:');
+    plan.steps.forEach((step, index) => lines.push(`  ${index + 1}. ${step}`));
+  }
+
+  if (plan.brokered) {
+    lines.push(
+      '',
+      `There is nothing to register: the OAuth client is operated by ${plan.clientOperator}, ` +
+        'and its secret never reaches this machine. The command below is the whole of it.',
+    );
+  }
+
+  // Labels, never the credential references they resolve to. The command below
+  // *asks* for each of these, so the owner never needs to know where a value is
+  // filed — and a ref names a key in the credential store, which is a detail of
+  // ours rather than anything they can act on. The `secrets set` spelling exists
+  // for `lanes link setup plan`, where the reader has a shell and is scripting.
+  if (plan.requires.length > 0) {
+    lines.push('', 'It will ask them for:');
+    for (const requirement of plan.requires) lines.push(`  ${requirement.label}`);
+  }
+
+  if (plan.needsId) {
+    lines.push(
+      '',
+      'This provider stores a credential per account, so the command needs a name for the ' +
+        'account — replace <name> with whatever they want to call it.',
+    );
+  }
+
+  lines.push('', 'The command:', `  ${plan.command}`);
+
+  if (plan.brokered && plan.ownClientCommand) {
+    lines.push(
+      '',
+      'If the owner would rather use an OAuth client they register themselves — some ' +
+        'organisations require it — the same command takes --own-client and then asks for ' +
+        `the client id and secret:`,
+      `  ${plan.ownClientCommand}`,
+    );
+  }
+
+  if (plan.browser) {
+    lines.push(
+      '',
+      'That opens a browser for consent, so it has to be run by whoever owns the account. ' +
+        'Give them the line above rather than trying to run it.',
+    );
+  }
+
+  lines.push('', 'Once it is done this becomes reachable here, with nothing further to run.');
+
+  return lines.join('\n');
+}

package/src/providers/shared/frontmatter.ts

@@ -0,0 +1,119 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { ConfigError } from '#profile';
+
+/**
+ * YAML frontmatter between `---` fences, and the Markdown body after it.
+ *
+ * Two owner-layer artifacts are stored this way — a skill and a memory entry —
+ * and they parse identically on purpose. One file per thing, holding both its
+ * metadata and its text, is what makes either of them hand-editable: an entry
+ * whose title lived in a database row beside a body in a blob could not be
+ * opened in an editor, and could go out of sync with itself.
+ *
+ * The format is the one every other tool that reads a skill file already uses,
+ * which is the reason it was not invented here.
+ */
+
+export interface Frontmatter {
+  readonly frontmatter: Record<string, unknown>;
+  readonly body: string;
+}
+
+/**
+ * Split a document, refusing one whose frontmatter is absent or malformed.
+ *
+ * Each failure is reported as itself rather than as one generic message, and
+ * `source` names the file in all of them: these are read from a directory a
+ * person edits by hand, where "could not parse frontmatter" without a filename
+ * or a reason is not a diagnosis.
+ */
+export function splitFrontmatter(text: string, source: string): Frontmatter {
+  const normalised = stripBom(text);
+
+  if (!normalised.startsWith('---')) {
+    throw new ConfigError(
+      `${source}: expected YAML frontmatter between "---" fences at the start of the file.`,
+    );
+  }
+
+  const fences = splitAtFences(normalised);
+  if (!fences) {
+    throw new ConfigError(`${source}: the frontmatter block is never closed with "---".`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fences.head);
+  } catch (error) {
+    throw new ConfigError(`${source}: could not parse frontmatter — ${(error as Error).message}`);
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new ConfigError(`${source}: the frontmatter must be a YAML mapping.`);
+  }
+
+  return { frontmatter: parsed as Record<string, unknown>, body: fences.body };
+}
+
+/**
+ * Split a document that may not have frontmatter, treating the whole of it as
+ * the body when it does not.
+ *
+ * A memory entry uses this rather than `splitFrontmatter`: entries are files in
+ * a directory the owner is invited to edit, and a plain Markdown file dropped
+ * in there should read as an untitled entry rather than becoming an error that
+ * hides the rest of the directory behind it.
+ */
+export function splitOptionalFrontmatter(text: string): Frontmatter {
+  const normalised = stripBom(text);
+  if (!normalised.startsWith('---')) return { frontmatter: {}, body: normalised };
+
+  const fences = splitAtFences(normalised);
+  if (!fences) return { frontmatter: {}, body: normalised };
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fences.head);
+  } catch {
+    return { frontmatter: {}, body: normalised };
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { frontmatter: {}, body: normalised };
+  }
+
+  return { frontmatter: parsed as Record<string, unknown>, body: fences.body };
+}
+
+/** Serialise frontmatter and a body back into one document. */
+export function withFrontmatter(data: Record<string, unknown>, body: string): string {
+  const head = stringifyYaml(data).trimEnd();
+  return `---\n${head}\n---\n\n${body.replace(/^\n+/, '')}`;
+}
+
+/** A frontmatter value that should be a list of strings, tolerating a bare one. */
+export function stringList(raw: unknown): string[] {
+  if (typeof raw === 'string') return [raw];
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((entry): entry is string => typeof entry === 'string');
+}
+
+function splitAtFences(normalised: string): { head: string; body: string } | null {
+  const end = normalised.indexOf('\n---', 3);
+  if (end === -1) return null;
+
+  const rest = normalised.slice(normalised.indexOf('\n', end + 1) + 1);
+
+  return {
+    head: normalised.slice(normalised.indexOf('\n') + 1, end),
+    // One blank line after the closing fence is the conventional separator, not
+    // content. Exactly one is dropped, so a body that deliberately opens with
+    // blank lines keeps the rest of them — and so `withFrontmatter` round-trips
+    // a body back to itself.
+    body: rest.startsWith('\n') ? rest.slice(1) : rest,
+  };
+}
+
+function stripBom(text: string): string {
+  return text.replace(/^/, '');
+}