@lanes-sh/link 0.7.1 → 0.8.0

package/src/cli/contract3-shape.ts

@@ -0,0 +1,186 @@
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import type { ContractRename, LegacyConnection, LegacyProfile } from './contract3.ts';
+import { keyOf } from './contract3.ts';
+
+/**
+ * Turning contract 2's shape into contract 3's, without touching a file.
+ *
+ * Split from the flow because these are the decisions and that is the ordering:
+ * which connections exist after hoisting, what each profile's grants become, and
+ * what a rule with an expiry means. Every defect review found in this migration
+ * was in one of those three, and none of them needed a filesystem to reproduce.
+ */
+
+/**
+ * Hoist every profile's connections into one list.
+ *
+ * **Keyed on provider and account, not on the id.** The common case is two
+ * profiles that both connected the same mailbox: same provider, same account,
+ * usually the same id, and they merge into one row because they *are* one
+ * account. The interesting case is two profiles each holding a row spelled
+ * `gmail.main` naming different mailboxes, which is legal under contract 2
+ * because a connection lived inside one profile and nothing ever compared them.
+ *
+ * That collision is resolved by renaming, never by picking. Both accounts are
+ * real, both have a credential, and choosing either would take somebody's
+ * mailbox away silently. The second becomes `gmail.main_2`, and the rename is
+ * reported so the operator sees it before anything else reads the file.
+ */
+export function hoistConnections(profiles: ReadonlyMap<string, LegacyProfile>): {
+  rows: LegacyConnection[];
+  renames: ContractRename[];
+  perProfile: Map<string, Map<string, string>>;
+} {
+  const rows: LegacyConnection[] = [];
+  const renames: ContractRename[] = [];
+  const byAccount = new Map<string, LegacyConnection>();
+  const taken = new Set<string>();
+  const perProfile = new Map<string, Map<string, string>>();
+
+  for (const [profile, config] of profiles) {
+    const mapping = new Map<string, string>();
+    perProfile.set(profile, mapping);
+
+    for (const connection of config.connections ?? []) {
+      // Two profiles' owner layers are never the same thing, whatever their
+      // rows say. Every contract-2 profile carried an identical owner layer
+      // written from a fixed table — `{memory: 'Memory', vault: 'Vault', ...}`
+      // — so an identity of provider-plus-account made all of them collide and
+      // merge. That is the one outcome ADR-059 forbids: interleaving two sets of
+      // notes is not reversible and not reviewable, and for the vault the wrong
+      // answer is a credential. Keying on the profile forces a rename instead.
+      const owner = RESERVED_PROVIDER_IDS.includes(connection.provider);
+      const identity = owner
+        ? `${connection.provider} @${profile}`
+        : `${connection.provider} ${connection.account}`;
+      const existing = byAccount.get(identity);
+
+      if (existing) {
+        // The same account, already hoisted. This profile's old key maps to
+        // whatever the first one settled on, which may itself be a rename.
+        mapping.set(keyOf(connection), keyOf(existing));
+        continue;
+      }
+
+      let id = connection.id;
+      if (taken.has(`${connection.provider}.${id}`)) {
+        // The profile's own name for an owner-layer surface, which is what
+        // ADR-059 specifies and reads far better than `memory.main_2` when the
+        // thing being separated is "work's notes". A numeric suffix is the
+        // fallback for a real account, and for the case where the profile name
+        // is itself taken.
+        const preferred = owner ? sanitise(profile) : `${id}_2`;
+        let candidate = preferred;
+        let suffix = 2;
+        while (taken.has(`${connection.provider}.${candidate}`)) {
+          suffix += 1;
+          candidate = `${preferred}_${suffix}`;
+        }
+        renames.push({
+          from: `${connection.provider}.${id}`,
+          to: `${connection.provider}.${candidate}`,
+          reason: owner
+            ? `"${profile}" has its own ${connection.provider}, which is not "${id}"'s`
+            : `"${profile}" named a different account (${connection.account}) with that id`,
+        });
+        id = candidate;
+      }
+
+      const row: LegacyConnection = { ...connection, id };
+      rows.push(row);
+      byAccount.set(identity, row);
+      taken.add(keyOf(row));
+      mapping.set(keyOf(connection), keyOf(row));
+    }
+  }
+
+  return { rows, renames, perProfile };
+}
+
+/** A profile name as a connection id: the same alphabet `connectionRef` allows. */
+function sanitise(profile: string): string {
+  const cleaned = profile.toLowerCase().replace(/[^a-z0-9_]/g, '_').replace(/^_+/, '');
+  return cleaned.length > 0 ? cleaned : 'two';
+}
+
+/**
+ * A rule, in whichever of the two shapes contract 2 accepted, with its expiry.
+ *
+ * Reading the capability alone got both directions wrong, and it is the same
+ * mistake `config-repair.ts` documents. `isRuleActive` is what made a lapsed
+ * rule inert, so dropping `expires_at` turned an allow that died months ago into
+ * a live permanent grant — and an expired *deny* into a permanent one, which is
+ * not the safe direction either, because a deny outranks every allow.
+ *
+ * A rule that has already lapsed is dropped rather than carried: it granted and
+ * denied nothing on the day of the migration, and writing it forward would give
+ * it a meaning it did not have.
+ */
+type Rule = string | { capability: string; expires_at: string };
+
+function patternsOf(rules: unknown, now = Date.now()): Rule[] {
+  if (!Array.isArray(rules)) return [];
+
+  return rules.flatMap((rule): Rule[] => {
+    if (typeof rule === 'string') return [rule];
+
+    const object = rule as { capability?: unknown; expires_at?: unknown } | null;
+    const capability = object?.capability;
+    if (typeof capability !== 'string') return [];
+
+    const expiry = object?.expires_at;
+    if (typeof expiry !== 'string') return [capability];
+
+    const at = Date.parse(expiry);
+    if (Number.isNaN(at)) return [capability];
+    return at > now ? [{ capability, expires_at: expiry }] : [];
+  });
+}
+
+/** The capability a rule names, whichever shape it is in. */
+function capabilityOf(rule: Rule): string {
+  return typeof rule === 'string' ? rule : rule.capability;
+}
+
+/**
+ * The grant rows one contract-2 profile becomes.
+ *
+ * Every connection gets the rules that named its provider, which is precisely
+ * what the flat block meant: rules covered every account of a provider in the
+ * profile. So this loses nothing, and gains the ability to diverge afterwards.
+ *
+ * A rule naming a provider the profile has no connection for is dropped rather
+ * than carried. Under contract 2 an `allow` like that was refused at load, and a
+ * `deny` was permitted as a note to self; there is nowhere to put either now,
+ * because a row without a connection is not expressible.
+ */
+export function grantsFor(
+  config: LegacyProfile,
+  mapping: ReadonlyMap<string, string>,
+): { connection: string; allow: Rule[]; deny: Rule[] }[] {
+  const allow = patternsOf(config.policy?.allow);
+  const deny = patternsOf(config.policy?.deny);
+
+  const covers = (rule: Rule, provider: string): boolean => {
+    const pattern = capabilityOf(rule);
+    return pattern === '*' || pattern.startsWith(`${provider}.`);
+  };
+
+  return (config.connections ?? []).map((connection) => {
+    const provider = connection.provider;
+    // A bare `*` becomes the provider wildcard rather than being copied
+    // through. It would still mean the same thing inside a row, which is
+    // already scoped to one connection, but writing it out is what makes the
+    // file say so. An expiry rides along untouched.
+    const widen = (rule: Rule): Rule => {
+      if (typeof rule === 'string') return rule === '*' ? `${provider}.*` : rule;
+      return rule.capability === '*' ? { ...rule, capability: `${provider}.*` } : rule;
+    };
+
+    return {
+      connection: mapping.get(keyOf(connection)) ?? keyOf(connection),
+      allow: allow.filter((rule) => covers(rule, provider)).map(widen),
+      deny: deny.filter((rule) => covers(rule, provider)).map(widen),
+    };
+  });
+}

package/src/cli/contract3.ts

@@ -0,0 +1,282 @@
+import { newConnectionsTemplate } from './config-templates.ts';
+import { applyMoves, mergeCredentials, planCredentials, planMoves, type Move } from './contract3-data.ts';
+import { parseDocument } from 'yaml';
+import {
+  CONNECTIONS_FILE,
+  ConfigError,
+  DATA_DIR,
+  WORKSPACE_FILE,
+  layout,
+  listProfiles,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+} from '#profile';
+import { RESERVED_PROVIDER_IDS } from '#connectivity';
+import { ConfigDocument } from './config-edit.ts';
+import { grantsFor, hoistConnections } from './contract3-shape.ts';
+
+/**
+ * Contract 2 to contract 3: connections move out of the profile.
+ *
+ * The hardest migration this project has done, and the one it could least
+ * afford to skip. `layout.ts` and ADR-030 both set the precedent that there is
+ * no migration, because machinery to move an old layout is more code than the
+ * thing it moves and has to keep working forever. That precedent was set for
+ * *empty directories*. Here the thing being moved is every credential the
+ * operator holds, and "re-authorise fifteen accounts in a browser" is not a
+ * release note anyone should write.
+ *
+ * Four moves, in an order chosen so a crash between any two leaves a workspace
+ * that still opens:
+ *
+ *   1. Connections are hoisted into `connections.yaml`.
+ *   2. Credentials are merged into one store, and read back before the old ones
+ *      are touched.
+ *   3. Profiles are rewritten, `grants:` being the old connections crossed with
+ *      the old flat policy, which is exactly what contract 2 meant.
+ *   4. Bytes move to their connection-keyed homes.
+ *
+ * The registry rename rides along at the end, because it is the one step that
+ * cannot half-apply: it is a single document.
+ */
+
+/** What a divergent id was renamed to, and why. */
+export interface ContractRename {
+  readonly from: string;
+  readonly to: string;
+  readonly reason: string;
+}
+
+export interface Contract3Migration {
+  readonly workspaceRoot: string;
+  readonly profiles: readonly string[];
+  readonly connections: readonly string[];
+  readonly renames: readonly ContractRename[];
+  readonly credentials: readonly string[];
+  readonly moved: readonly string[];
+  readonly changes: readonly string[];
+  readonly alreadyCurrent: boolean;
+}
+
+export interface LegacyConnection {
+  readonly id: string;
+  readonly provider: string;
+  readonly account: string;
+  readonly label?: string;
+  readonly credential_ref?: string;
+  readonly config?: Record<string, unknown>;
+}
+
+export interface LegacyProfile {
+  readonly contract?: number;
+  readonly connections?: LegacyConnection[];
+  readonly policy?: { allow?: unknown[]; deny?: unknown[] };
+  readonly oauth_apps?: Record<string, unknown>;
+}
+
+/** Whether this workspace still holds anything at contract 2. */
+export async function needsContract3(workspaceRoot: string): Promise<boolean> {
+  for (const profile of await listProfiles(workspaceRoot)) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 2) return true;
+  }
+  return false;
+}
+
+async function readProfile(root: string, profile: string): Promise<LegacyProfile | null> {
+  const text = await readWorkspaceFile(workspaceFiles(root), `profiles/${profile}.yaml`);
+  if (text === null) return null;
+  try {
+    return parseDocument(text).toJSON() as LegacyProfile;
+  } catch {
+    // A file that will not parse is not this function's problem to report;
+    // `check` gives it a better sentence than "needs migrating" would.
+    return null;
+  }
+}
+
+/** `gmail.main` — how a connection is addressed in every file after this. */
+export function keyOf(connection: { provider: string; id: string }): string {
+  return `${connection.provider}.${connection.id}`;
+}
+
+export async function migrateToContract3(
+  workspaceRoot: string,
+  options: { apply: boolean; subject?: string } = { apply: true },
+): Promise<Contract3Migration> {
+  const legacy = new Map<string, LegacyProfile>();
+
+  for (const profile of await listProfiles(workspaceRoot)) {
+    const raw = await readProfile(workspaceRoot, profile);
+    if (raw !== null && (raw.contract ?? 0) === 2) legacy.set(profile, raw);
+  }
+
+  const nothing: Contract3Migration = {
+    workspaceRoot,
+    profiles: [],
+    connections: [],
+    renames: [],
+    credentials: [],
+    moved: [],
+    changes: [],
+    alreadyCurrent: true,
+  };
+  if (legacy.size === 0) return nothing;
+
+  const { rows, renames, perProfile } = hoistConnections(legacy);
+  const files = workspaceFiles(workspaceRoot);
+
+  // Everything that can be computed is computed before the first write, so a
+  // refusal leaves the workspace exactly as it was.
+  const credentials = await planCredentials(workspaceRoot, [...legacy.keys()]);
+  const moves = await planMoves(files, [...legacy.keys()], perProfile);
+
+  const changes: string[] = [
+    `${CONNECTIONS_FILE}: ${rows.length} connection(s) hoisted`,
+    ...renames.map((rename) => `renamed ${rename.from} to ${rename.to} (${rename.reason})`),
+    ...[...legacy.keys()].map((profile) => `profiles/${profile}.yaml: contract 3, grants`),
+  ];
+  if (credentials.length > 0) {
+    changes.push(`${layout.credentials()}: ${credentials.length} credential(s) merged`);
+  }
+  if (moves.length > 0) changes.push(`${moves.length} object(s) moved to their connection`);
+
+  const result: Contract3Migration = {
+    workspaceRoot,
+    profiles: [...legacy.keys()],
+    connections: rows.map(keyOf),
+    renames,
+    credentials,
+    moved: moves.map((move) => move.to),
+    changes,
+    alreadyCurrent: false,
+  };
+
+  if (!options.apply) return result;
+
+  // The registry first, and this ordering is the whole of the re-entrancy.
+  //
+  // Every later step is idempotent — writing `connections.yaml` again produces
+  // the same file, merging a credential that is already there is a no-op,
+  // rewriting a contract-3 profile is skipped, and a move whose source is gone
+  // is skipped. `rewriteRegistry` is the one step that is not, because it reads
+  // `targets:` and would find none the second time.
+  //
+  // Running it last meant an interruption anywhere before it left profiles at
+  // contract 3 and `lanes-link.yaml` still at contract 2 — a state where
+  // re-entry found nothing to migrate, and `workspaceSchema` parsed a file whose
+  // `workspaces:` defaulted to empty, so every command refused with "declares no
+  // workspace" and there was no way back.
+  await rewriteRegistry(workspaceRoot);
+  await writeConnections(workspaceRoot, rows, legacy);
+  await mergeCredentials(workspaceRoot, [...legacy.keys()]);
+
+  // **The bytes move before the profile says they have.**
+  //
+  // `rewriteProfiles` is what stamps `contract: 3`, and that stamp is the only
+  // thing `needsContract3` reads — so it is not a step among steps, it is the
+  // record that the migration finished. Running it before `applyMoves` meant an
+  // interruption between the two left profiles claiming contract 3 with every
+  // byte still under `data/<profile>/`, and a re-run that looked at the stamp
+  // and found nothing to do. The workspace opened, which is what this file
+  // ordered its steps to guarantee, and the owner's memory, tasks, skills and
+  // audit log were not in it.
+  //
+  // A network round trip per object made that window real rather than
+  // theoretical: this migrates buckets now, and the first one it was pointed at
+  // held 1,906 objects.
+  await applyMoves(files, moves);
+  await rewriteProfiles(workspaceRoot, legacy, perProfile, options.subject);
+
+  return result;
+}
+
+/** The hoisted rows, plus every profile's `oauth_apps` merged into one block. */
+async function writeConnections(
+  root: string,
+  rows: readonly LegacyConnection[],
+  legacy: ReadonlyMap<string, LegacyProfile>,
+): Promise<void> {
+  const apps: Record<string, unknown> = {};
+  for (const config of legacy.values()) Object.assign(apps, config.oauth_apps ?? {});
+
+  const document = ConfigDocument.fromText(newConnectionsTemplate(), CONNECTIONS_FILE);
+  document.setIn(['connections'], rows);
+  document.setIn(['oauth_apps'], apps);
+
+  await writeWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE, document.toString());
+}
+
+/** Contract 3, `grants:` and `members:`, with everything else left as written. */
+async function rewriteProfiles(
+  root: string,
+  legacy: ReadonlyMap<string, LegacyProfile>,
+  perProfile: ReadonlyMap<string, Map<string, string>>,
+  subject: string | undefined,
+): Promise<void> {
+  for (const [profile, config] of legacy) {
+    const document = await ConfigDocument.open(root, profile);
+
+    document.setIn(['contract'], 3);
+    document.setIn(['grants'], grantsFor(config, perProfile.get(profile) ?? new Map()));
+    // Empty unless the migration was run by somebody signed in. Nobody is a
+    // legitimate state and it is default deny on the identity axis, but a
+    // workspace whose profiles nobody can consume is a poor thing to hand back,
+    // so `update` passes the signed-in subject through.
+    document.setIn(['members'], subject ? [{ subject, role: 'owner' }] : []);
+
+    // The authorization block arrives here rather than in the template, because
+    // an existing profile has one only if it was deployed. Every endpoint runs
+    // the flow now, loopback included (ADR-062).
+    if (document.getIn(['auth', 'authorization']) === undefined) {
+      document.setIn(['auth', 'authorization'], { mode: 'self' });
+    }
+
+    document.removeIn(['connections']);
+    document.removeIn(['policy']);
+    document.removeIn(['oauth_apps']);
+
+    await document.save();
+  }
+}
+
+/** `targets:` becomes `workspaces:`, and a pointer's `workspace:` becomes `at:`. */
+async function rewriteRegistry(root: string): Promise<void> {
+  const document = await ConfigDocument.openKey(root, WORKSPACE_FILE);
+  const registry = document.toJSON() as {
+    contract?: number;
+    targets?: Record<string, { workspace?: string }>;
+  } | null;
+
+  const targets = registry?.targets;
+
+  // Already renamed, which is what a contract-1 workspace looks like here: the
+  // 1-to-2 migration wrote `workspaces:` on its way through. Returning early
+  // skipped the contract stamp and the default below, so that path finished a
+  // migration and left neither.
+  if (targets !== undefined) {
+    const workspaces: Record<string, unknown> = {};
+    for (const [name, entry] of Object.entries(targets)) {
+      const { workspace, ...rest } = entry;
+      workspaces[name] = workspace === undefined ? rest : { at: workspace, ...rest };
+    }
+
+    document.setIn(['workspaces'], workspaces);
+    document.removeIn(['targets']);
+  }
+
+  document.setIn(['contract'], 3);
+  const workspaces = (document.toJSON() as { workspaces?: Record<string, unknown> } | null)
+    ?.workspaces ?? {};
+
+  // The first workspace in the registry, which for every workspace this
+  // migration will ever see is `local`. Written rather than left absent so the
+  // sticky default is on from the first command after upgrading (ADR-061).
+  if (document.getIn(['default_workspace']) === undefined) {
+    const first = Object.keys(workspaces)[0];
+    if (first !== undefined) document.setIn(['default_workspace'], first);
+  }
+
+  await document.save();
+}

package/src/cli/endpoint-url.ts

@@ -9,7 +9,7 @@ import type { Config, DeployConfig, TargetConfig } from '#profile';
  *
  * Shared because getting it wrong is silent in the worst way. `outputs` asked
  * the driver; `mcp add` built the local URL unconditionally, so
- * `lanes link mcp add --target cloud` registered `http://127.0.0.1:7337/mcp`
+ * `lanes link mcp add --workspace cloud` registered `http://127.0.0.1:7337/mcp`
  * with the agent — a registration that looks successful, names the right
  * server, and points at a port with nothing behind it. One of the two had the
  * answer and the other could not see it, which is what a copied line does

package/src/cli/lanes.ts

@@ -21,13 +21,23 @@ const AREAS: Record<string, string> = {
   link: 'a self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets',
 };
 
+/** Commands that belong to the binary rather than to any one area. */
+const TOP_LEVEL: Record<string, string> = {
+  auth: 'sign in to Lanes, so a profile can say who may use it',
+  'set-workspace': 'which workspace a command means when it does not say',
+};
+
 function areasUsage(): string {
   const rows = Object.entries(AREAS)
     .map(([name, blurb]) => `  ${style.bold(`lanes ${name}`)}  ${blurb}`)
     .join('\n');
 
+  const top = Object.entries(TOP_LEVEL)
+    .map(([name, blurb]) => `  ${style.bold(`lanes ${name}`)}  ${blurb}`)
+    .join('\n');
+
   return (
-    `${style.bold('lanes')} — your own tools, wherever you work\n\n${rows}\n\n` +
+    `${style.bold('lanes')} — your own tools, wherever you work\n\n${rows}\n\n${top}\n\n` +
     `Run ${style.bold('lanes <area> help')} for what an area can do, ` +
     `or ${style.bold('lanes --version')} for which release this is.\n`
   );
@@ -51,6 +61,20 @@ async function main(argv: readonly string[]): Promise<void> {
     return;
   }
 
+  // A top-level command rather than an area, because it selects the workspace
+  // *the CLI* acts in — every area's commands read the same answer (ADR-061).
+  if (area === 'auth') {
+    const { runAuth } = await import('./commands/auth-dispatch.ts');
+    return await runAuth(rest);
+  }
+
+  if (area === 'set-workspace') {
+    const { setWorkspace } = await import('./commands/set-workspace.ts');
+    const { parseArgv } = await import('./argv.ts');
+    const { command, flags } = parseArgv(rest);
+    return await setWorkspace(command[0], { json: flags['json'] === true });
+  }
+
   if (area === 'link') {
     // Loaded here rather than at the top of the file so that a failure while
     // the area's module graph evaluates — a malformed environment variable read