@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/config-repair.ts

@@ -1,6 +1,5 @@
-import { listProfiles } from '#profile';
 import { ConfigDocument } from './config-edit.ts';
-import { ok, print, style, warn } from './output.ts';
+import { nextConnectionId } from './identity.ts';
 
 /**
  * Giving a profile a reserved provider it is missing, without undoing a choice.
@@ -18,16 +17,16 @@ import { ok, print, style, warn } from './output.ts';
  * than several that look alike.
  */
 
-/** The reserved provider ids that hold no account, and the label each row carries. */
+/** Lanes' own provider ids, and the label each row carries. */
 const RESERVED_SURFACES = {
-  memory: 'Memory',
-  tasks: 'Tasks',
-  assets: 'Assets',
-  skills: 'Skills',
-  vault: 'Vault',
-  setup: 'Setup',
-  identity: 'Identity',
-  entities: 'Entities',
+  lanes_memory: 'Memory',
+  lanes_tasks: 'Tasks',
+  lanes_assets: 'Assets',
+  lanes_skills: 'Skills',
+  lanes_vault: 'Vault',
+  lanes_setup: 'Setup',
+  lanes_identity: 'Identity',
+  lanes_entities: 'Entities',
 } as const;
 
 type ReservedSurface = keyof typeof RESERVED_SURFACES;
@@ -55,13 +54,13 @@ type ReservedSurface = keyof typeof RESERVED_SURFACES;
  * template writes and a diff between the two reads as a diff.
  */
 export const DEFAULT_SURFACES: readonly ReservedSurface[] = [
-  'memory',
-  'tasks',
-  'assets',
-  'skills',
-  'vault',
-  'setup',
-  'entities',
+  'lanes_memory',
+  'lanes_tasks',
+  'lanes_assets',
+  'lanes_skills',
+  'lanes_vault',
+  'lanes_setup',
+  'lanes_entities',
 ];
 
 /**
@@ -100,55 +99,131 @@ export interface SurfaceRepair {
  * (ADR-023) so it could not write this even if the code let it.
  */
 export function ensureReservedConnection(
-  document: ConfigDocument,
+  connections: ConfigDocument,
+  profile: ConfigDocument,
   provider: ReservedSurface,
+  options: { grants?: boolean } = {},
 ): SurfaceRepair {
+  // Whether the profile half is written at all. `connect` without `--profile`
+  // repairs the workspace's connection rows and touches no profile, because it
+  // was not told which one to touch (ADR-057).
+  const grants = options.grants ?? true;
   // Raw YAML, so nothing here has been through a schema: this runs over sibling
   // profiles that were never validated, and every field is whatever was typed.
-  const config = document.toJSON() as {
-    connections?: unknown;
-    policy?: { allow?: unknown; deny?: unknown };
-  } | null;
+  const workspace = connections.toJSON() as { connections?: unknown } | null;
+  const config = profile.toJSON() as { grants?: unknown } | null;
 
   const rule = `${provider}.*`;
   const covers = (pattern: string): boolean => pattern === '*' || pattern === rule;
 
+  const rows = Array.isArray(workspace?.connections) ? workspace.connections : [];
+  const held_grants = Array.isArray(config?.grants) ? config.grants : [];
+
+  // **This profile's own grant comes first.** Any instance of the provider will
+  // do, and the *first* one is taken rather than `main` specifically: an
+  // operator who renamed theirs should not get a second one bolted on beside
+  // it. That reasoning was right and the lookup implementing it was not — it
+  // read the workspace's first row, which under contract 2 was this profile's
+  // because a profile carried its own connections, and under contract 3 is
+  // whichever profile sorts first.
+  //
+  // So the repair asked whether `personal` granted `memory.main` — demo's — saw
+  // that it did not, and set about adding it. For `vault` and `skills` the
+  // schema refuses a second grant and the save failed loudly, which is how this
+  // was found. For `memory`, `tasks`, `assets`, `setup` and `entities` nothing
+  // refuses it, and the profile would quietly have been granted another
+  // profile's notes and another profile's task list — the outcome ADR-059
+  // exists to prevent, arriving from the repair rather than the migration.
+  //
+  // **Every** instance, not the first one matched. A profile may grant two —
+  // `memory.team` and `memory.personal` — and reading only the first let a deny
+  // on the other be stepped around: the repair widened the undenied row and
+  // reported the surface granted, which is the one thing the paragraph below
+  // says it must never do.
+  //
+  // `startsWith` rather than slicing at the dot, because these rows are raw
+  // unvalidated YAML: `indexOf` answers -1 for a value with no dot at all, and
+  // `'vaults'.slice(0, -1)` is `'vault'` — so a typo'd `connection: vaults`
+  // matched the vault surface and was widened while the real one stayed
+  // unreachable.
+  const mine = held_grants.filter((row) => {
+    const connection = (row as { connection?: unknown } | null)?.connection;
+    return typeof connection === 'string' && connection.startsWith(`${provider}.`);
+  }) as { connection?: string; allow?: unknown; deny?: unknown }[];
+
   // Denied on purpose, and a deny beats an allow — so writing the rule would
   // widen nothing while announcing that an agent can now read the surface,
-  // which would be false. For `setup`, deleting the two lines no longer removes
-  // it either, because the next `connect` or `deploy` puts them back; a deny is
-  // the way it stays off, so it is the one thing this must not undo. The same
-  // holds for `identity`, where the next `identity add` is what would put them
-  // back.
+  // which would be false. Deleting the row no longer removes the surface
+  // either, because the next `connect` or `deploy` puts it back; a deny is the
+  // way it stays off, so it is the one thing this must not undo.
   //
   // Only a rule covering the whole surface counts. `deny: [setup.provider]` is
   // an operator narrowing it, not switching it off, and that narrowing survives
   // the repair untouched — which is the point of denying one capability.
-  if (patternsIn(config?.policy?.deny).some(covers)) return { changes: [], granted: [] };
+  if (mine.some((row) => patternsIn(row.deny).some(covers))) return { changes: [], granted: [] };
+
+  // The instance already carrying the rule, if any. Not an early return: the
+  // workspace row can be missing while the grant is present — a profile written
+  // before the surface existed, repaired once against a `connections.yaml` that
+  // has since been hand-edited — and repairing one half only is what this
+  // function exists to prevent.
+  const allowed = mine.find((row) => patternsIn(row.allow).some(covers));
+
+  // Otherwise the first row that exists and grants nothing is the one to widen.
+  const owned = allowed ?? mine[0];
+
+  // Only when this profile grants no instance of the provider at all is the
+  // workspace consulted, which is the case this was written for: a surface that
+  // did not exist when the profile was written.
+  const declared = rows.find(
+    (row) => (row as { provider?: unknown } | null)?.provider === provider,
+  ) as { id?: unknown } | undefined;
+
+  // The id an existing row already has, else the next free one. Opaque and
+  // allocated across the whole workspace, so `lan3` names exactly one row
+  // however many surfaces a repair adds in one pass.
+  const taken = rows.flatMap((row) => {
+    const id = (row as { id?: unknown } | null)?.id;
+    return typeof id === 'string' ? [id] : [];
+  });
+  const id = typeof declared?.id === 'string' ? declared.id : nextConnectionId(taken, true);
+
+  const key = owned?.connection ?? `${provider}.${id}`;
+
+  // Whether the *workspace* needs a row, which is a separate question from
+  // which one this profile grants: a profile cannot grant a connection that is
+  // not declared, so `owned` implies `declared`.
+  const existing = declared;
+  const held = owned;
 
   const changes: string[] = [];
   const granted: string[] = [];
 
-  const connections = Array.isArray(config?.connections) ? config.connections : [];
-  const declared = (row: unknown): boolean =>
-    (row as { provider?: unknown } | null)?.provider === provider;
-
-  if (!connections.some(declared)) {
-    // Inline, and `main` for the id, so a repaired profile is spelled exactly
-    // like `newProfileTemplate` writes a fresh one. Two spellings of one row is
-    // how a template and its repair drift apart.
-    document.addTo(
+  if (existing === undefined) {
+    // Inline, and the allocated id, so a repaired workspace is spelled exactly
+    // like `newConnectionsTemplate` writes a fresh one — which is what
+    // `config-edit.test.ts` asserts by checking a fresh profile needs no repair.
+    // Two spellings of one row is how a template and its repair drift apart.
+    connections.addTo(
       ['connections'],
-      { id: 'main', provider, account: RESERVED_SURFACES[provider] },
+      { id, provider, account: RESERVED_SURFACES[provider] },
       { inline: true },
     );
-    changes.push(`connections += ${provider}.main`);
+    changes.push(`connections.yaml += ${key}`);
   }
 
-  // `*` already covers it. Re-stating the rule under a blanket allow would be
-  // noise in the file and a diff the operator did not ask for.
-  if (!patternsIn(config?.policy?.allow).some(covers)) {
-    document.addTo(['policy', 'allow'], rule, { inline: true });
+  if (!grants) return { changes, granted };
+
+  if (held === undefined) {
+    profile.addTo(['grants'], { connection: key, allow: [rule], deny: [] }, { inline: true });
+    changes.push(`grants += ${key}`);
+    granted.push(rule);
+  } else if (allowed === undefined) {
+    // A row that exists and grants nothing is a surface that is present and
+    // silent. Widening it back is the repair; the deny check above is what stops
+    // this undoing a deliberate narrowing.
+    const at = held_grants.indexOf(held as never);
+    profile.addTo(['grants', at, 'allow'], rule, { inline: true });
     granted.push(rule);
   }
 
@@ -156,20 +231,13 @@ export function ensureReservedConnection(
 }
 
 /** Whether a repair did anything, without a caller adding up two lists. */
-/** `memory, tasks, assets, skills, vault, setup and entities`, in repair order. */
-function listSurfaces(): string {
-  const names = [...DEFAULT_SURFACES];
-  const last = names.pop();
-  return names.length === 0 ? String(last) : `${names.join(', ')} and ${last}`;
-}
-
 export function repaired(repair: SurfaceRepair): boolean {
   return repair.changes.length > 0 || repair.granted.length > 0;
 }
 
 /** The repair as display lines, in the order the two halves are applied. */
 export function repairLines(repair: SurfaceRepair): string[] {
-  return [...repair.changes, ...repair.granted.map((rule) => `policy.allow += ${rule}`)];
+  return [...repair.changes, ...repair.granted.map((rule) => `grants[].allow += ${rule}`)];
 }
 
 /**
@@ -219,12 +287,16 @@ function patternsIn(rules: unknown, now = Date.now()): string[] {
  * Each surface is still decided independently, so a profile that denied exactly
  * one of them keeps that decision while the rest are repaired.
  */
-export function ensureOwnerLayer(document: ConfigDocument): SurfaceRepair {
+export function ensureOwnerLayer(
+  connections: ConfigDocument,
+  profile: ConfigDocument,
+  options: { grants?: boolean } = {},
+): SurfaceRepair {
   const changes: string[] = [];
   const granted: string[] = [];
 
   for (const provider of DEFAULT_SURFACES) {
-    const repair = ensureReservedConnection(document, provider);
+    const repair = ensureReservedConnection(connections, profile, provider, options);
     changes.push(...repair.changes);
     granted.push(...repair.granted);
   }
@@ -241,76 +313,10 @@ export function ensureOwnerLayer(document: ConfigDocument): SurfaceRepair {
  * paragraph of the instructions budget to say so. `identity add` is the only
  * caller, so the grant arrives exactly when there is something behind it.
  */
-export function ensureIdentityConnection(document: ConfigDocument): SurfaceRepair {
-  return ensureReservedConnection(document, 'identity');
+export function ensureIdentityConnection(
+  connections: ConfigDocument,
+  profile: ConfigDocument,
+): SurfaceRepair {
+  return ensureReservedConnection(connections, profile, 'lanes_identity');
 }
 
-/**
- * Apply that repair across a workspace, saving and reporting what changed.
- *
- * Here rather than in `#deployments`, where it was, because `start` needs it as
- * much as `deploy` does — more, in fact: `start` is the one command an existing
- * install runs without being asked to, so it is the path by which a profile
- * written before ADR-050 gets the layer at all. Two copies of a function that
- * widens a policy is not a thing to have.
- *
- * **The caller scopes it**, and for `deploy` that is exactly the set being
- * uploaded: a profile it sends is a profile the endpoint will serve, so
- * repairing a narrower set would leave a served profile without the surfaces.
- * Note what a `--profile` flag does not mean — it is the flag alone, so a
- * profile resolved from the environment leaves it undefined and that reads as
- * the whole workspace.
- *
- * *Which files are profiles* comes from `listProfiles`, never from an allowlist
- * of what is safe to copy: that would happily hand over a committed
- * `personal.example.yaml` or a nested `profiles/archive/old.yaml`, and this
- * opens and validates what it is given — which once turned a template into a
- * `ConfigError` aborting a deploy after provisioning had made cloud resources.
- *
- * A profile that cannot be read is warned about rather than fatal: the repair is
- * a courtesy on the way past, and the caller's real work should still happen.
- * Not silent, though — nothing else widens a policy without being asked.
- *
- * CLI-side by construction, like everything else in this file: a deployed
- * revision holds `objectViewer` on `profiles/` (ADR-023) and could not write
- * this even if the code let it.
- */
-export async function repairOwnerLayer(
-  workspaceRoot: string,
-  profiles: readonly string[] | undefined,
-  options: { report?: (line: string) => void } = {},
-): Promise<void> {
-  // stdout by default, because every caller but one is printing a report a
-  // person reads. `update --json` passes `progress` instead: what it produces is
-  // a document, and a line of prose in front of it corrupts whatever is parsing.
-  // Routed rather than silenced — nothing else here widens a policy without
-  // saying so, and this must not be the exception.
-  const say = options.report ?? print;
-  const wanted = profiles === undefined ? undefined : new Set(profiles);
-
-  for (const name of await listProfiles(workspaceRoot)) {
-    if (wanted !== undefined && !wanted.has(name)) continue;
-
-    try {
-      const document = await ConfigDocument.open(workspaceRoot, name);
-      const repair = ensureOwnerLayer(document);
-      if (!repaired(repair)) continue;
-
-      await document.save();
-
-      say(ok(`gave ${style.bold(name)} its own owner layer`));
-      for (const change of repairLines(repair)) say(`      ${style.dim(change)}`);
-      // Built from `DEFAULT_SURFACES` rather than typed out. The typed-out
-      // version still named six after a seventh had been added, so a person
-      // watching a deploy was told entities had arrived on the line above and
-      // that the layer was six things on the line below.
-      say(`      ${style.dim(`${listSurfaces()} — your own material, no account behind any of them`)}`);
-    } catch (error) {
-      say(
-        warn(
-          `could not give ${name} its owner layer: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`,
-        ),
-      );
-    }
-  }
-}

package/src/cli/config-templates.ts

@@ -0,0 +1,200 @@
+import { SUPPORTED_CONTRACT } from '#profile';
+
+/**
+ * The files a fresh workspace and a fresh profile are written from.
+ *
+ * Split out of `config-edit.ts` because they are prose rather than machinery:
+ * that file knows how to edit YAML without disturbing what an operator wrote,
+ * and these are the comments an operator reads. Keeping both in one file put it
+ * over the size budget, and the seam was already there.
+ *
+ * **The template and the repair must write a row in one spelling.** Two
+ * spellings of one row is how they drift apart, and `config-edit.test.ts`
+ * asserts that a fresh profile and workspace need no repair, which is the check
+ * that catches it (ADR-050).
+ */
+
+export function newProfileTemplate(profile: string, port: number, subject?: string): string {
+  return `# Lanes Link profile: ${profile}
+#
+# A profile is a *selection*: which of the workspace's accounts this agent may
+# reach, what it may do with each, and who may use it. The accounts themselves
+# live in connections.yaml beside this file, because authorising an account and
+# deciding what may be done with it are two different acts (ADR-057).
+#
+# This file never contains a credential value — only "_ref" pointers into the
+# credential store, which is the workspace's and is encrypted at rest.
+#
+# Edit it by hand or through the CLI; both are supported, and CLI edits preserve
+# your comments and ordering.
+contract: 4
+
+instance:
+  profile: ${profile}
+  port: ${port}
+  host: 127.0.0.1
+
+# What this profile is for, in your own words. Members see it, and so does
+# setup_overview — "reads my mail, keeps the calendar, never sends" is what
+# somebody needs to know before accepting it.
+# description: 
+
+# This file says nothing about where it runs, and that is the point.
+#
+# A profile lives in exactly one workspace, and that workspace declares its own
+# adapters, once, in lanes-link.yaml beside the profiles/ directory (ADR-052).
+# Moving this profile somewhere else is copying the file there.
+#
+#     lanes link status --profile ${profile} --workspace <name>
+#
+# The bearer token below is for CI. People sign in instead: a client that asks
+# for authorization is sent to the Lanes login, and comes back as somebody
+# (ADR-062). "lanes link token show" is for a runner with no browser.
+auth:
+  mode: bearer
+  token_ref: profile/token
+  authorization:
+    mode: self
+
+limits:
+  requests_per_minute: 120      # per profile
+  upstream_calls_per_minute: 60 # per connection, protects vendor quota
+
+# One row per connection this profile may reach, and what it may do with each.
+#
+# A row is the grant. There is no separate list of accounts and list of rules
+# that have to agree — naming a connection here is what makes it reachable, and
+# the allow list is what makes any of its capabilities callable. An account the
+# workspace holds and this file does not name is simply absent: not denied, not
+# advertised, not there.
+#
+# Rules name capabilities of that row's own provider. "gmail.*" covers
+# everything Gmail offers *for that one account*, which is what lets a second
+# row over a second mailbox allow something different (ADR-058).
+#
+# The seven below hold no account, and that is why they are here already: they
+# reach your own material rather than anybody's API, so there was never anything
+# for a connect step to authorise (ADR-050). What each one is:
+#
+#   memory   what you want remembered between sessions
+#   tasks    what you have to do, each with a status
+#   assets   files you want kept, by name
+#   skills   procedures you have written, handed to an agent as instructions
+#   vault    passwords and API keys, released one at a time
+#   setup    what is connected here, and what connecting more would take
+#   entities the people, companies and projects you deal with, and how to
+#            reach each of them — so an agent looks an address up rather
+#            than recalling one
+#
+# To switch one off, add it to that row's deny — deleting the row no longer
+# works, because the next connect or deploy puts it back. The three narrowings
+# worth knowing:
+#
+#   deny: [lanes_memory.write]     remember nothing new
+#   deny: [lanes_skills.manage.*]  invoke procedures, do not write them
+#   deny: [lanes_vault.put, lanes_vault.remove]
+grants:
+  - { connection: lanes_memory.lan1, allow: [lanes_memory.*], deny: [] }
+  - { connection: lanes_tasks.lan2, allow: [lanes_tasks.*], deny: [] }
+  - { connection: lanes_assets.lan3, allow: [lanes_assets.*], deny: [] }
+  - { connection: lanes_skills.lan4, allow: [lanes_skills.*], deny: [] }
+  - { connection: lanes_vault.lan5, allow: [lanes_vault.*], deny: [] }
+  - { connection: lanes_setup.lan6, allow: [lanes_setup.*], deny: [] }
+  - { connection: lanes_entities.lan7, allow: [lanes_entities.*], deny: [] }
+
+# Who may consume this profile (ADR-060).
+#
+# Empty is nobody, not everybody — default deny on the identity axis. A caller
+# proves who they are by signing in to Lanes, and reaches this profile only if
+# their subject is listed here.
+#
+# "owner" may edit this list. Both roles reach exactly what the grants above
+# allow: a role that changed what an agent could call would be a second policy
+# system beside grants, answering a question the first one already answers.
+members:${
+    subject
+      ? `
+  - { subject: ${subject}, role: owner }`
+      : ' []'
+  }
+`;
+}
+
+export function newWorkspaceTemplate(): string {
+  return `# Lanes Link workspace
+#
+# A workspace holds the accounts you have authorised (connections.yaml) and the
+# profiles that select among them (profiles/). One endpoint serves all of them:
+# every call names the profile it means, with --profile.
+#
+# "workspaces:" below says where this one's bytes go, once, for every profile in
+# it — a profile says nothing about where it runs, so there is one copy of it and
+# nothing to keep in step (ADR-052).
+#
+# A workspace somewhere else is a pointer, and "deploy" writes one:
+#
+#   workspaces:
+#     cloud:
+#       at: gs://your-bucket
+#       lanes_workspace: <id>     # whose members may be delegated to
+#
+# The workspace at that address declares its own adapters, and is the only thing
+# that does. Reading it is a network call, which is why "--workspace cloud" needs
+# that bucket reachable.
+#
+# default_workspace is used when --workspace is absent, and every command that
+# uses it prints which one it got. Commands that publish or destroy — deploy,
+# sync, secrets push, profile remove, disconnect, token rotate — refuse it and
+# make you type the name (ADR-061).
+contract: 4
+default_workspace: local
+workspaces:
+  local:
+    credentials: { adapter: file }
+    storage: { adapter: filesystem }
+`;
+}
+
+/**
+ * `connections.yaml` for a workspace that has just been created.
+ *
+ * The owner layer arrives here rather than in the profile, because these are
+ * connections now (ADR-059) and a second profile should select the same stores
+ * rather than get its own empty ones. `ensureOwnerLayer` keeps this in one
+ * spelling with the repair, which `config-edit.test.ts` asserts by checking that
+ * a fresh workspace needs no repair.
+ */
+export function newConnectionsTemplate(): string {
+  return `# Lanes Link connections
+#
+# Every account authorised in this workspace, in one place. A profile names the
+# ones it may reach in its own "grants:" block — connecting an account and
+# deciding what may be done with it are two acts, and only the second belongs to
+# a profile (ADR-057).
+#
+# "account" is the identity the provider reports — an address, a workspace — so
+# this list says whose data is reachable without having to look anything up.
+# "label" is your own word for the same row, and only ever displayed.
+#
+# The "lanes_" rows are Lanes' own surfaces and hold no account: they reach your
+# own material rather than anybody's API, so there was never anything for a
+# connect step to authorise (ADR-050). Every profile grants the same ones and
+# still keeps its own bytes — what you write through one profile is absent in
+# another (ADR-066). A second instance is for holding two of something in one
+# profile: "lanes link connect lanes_memory --id lan9".
+contract: 4
+
+connections:
+  - { id: lan1, provider: lanes_memory, account: Memory }
+  - { id: lan2, provider: lanes_tasks, account: Tasks }
+  - { id: lan3, provider: lanes_assets, account: Assets }
+  - { id: lan4, provider: lanes_skills, account: Skills }
+  - { id: lan5, provider: lanes_vault, account: Vault }
+  - { id: lan6, provider: lanes_setup, account: Setup }
+  - { id: lan7, provider: lanes_entities, account: Entities }
+
+# App registrations, shared by every connection of that vendor.
+oauth_apps: {}
+`;
+}
+