@lanes-sh/link 0.7.2 → 0.8.0

package/src/cli/commands/profile.ts

@@ -1,7 +1,9 @@
+import { newConnectionsTemplate, newProfileTemplate, newWorkspaceTemplate } from '../config-templates.ts';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import {
+  CONNECTIONS_FILE,
   ConfigError,
   WORKSPACE_FILE,
   listProfiles,
@@ -13,8 +15,11 @@ import {
   resolveTargetWorkspace,
   resolveWorkspaceRoot,
 } from '#profile';
-import { newProfileTemplate, newWorkspaceTemplate } from '../config-edit.ts';
+
+import { recordConfigChange } from '../audit-change.ts';
+import { resolveProfile } from '../runtime.ts';
 import { emit, ok, print, style, table } from '../output.ts';
+import { readSession } from '#auth/lanes/session.ts';
 
 /**
  * Profile management.
@@ -58,7 +63,7 @@ export interface ProfileListing {
  *
  * It now decides *where the file goes* rather than what is written in it: a
  * profile lives in one target's workspace and declares nothing about it
- * (ADR-052), so `--target cloud` writes into the bucket and the endpoint there
+ * (ADR-052), so `--workspace cloud` writes into the bucket and the endpoint there
  * serves it on its next reconcile.
  */
 export async function createProfile(
@@ -69,7 +74,7 @@ export async function createProfile(
   const target = options.targets[0]!;
 
   // The workspace file before the target is resolved, not after. `profile add
-  // <name> --target local` on an empty directory is how a workspace comes into
+  // <name> --workspace local` on an empty directory is how a workspace comes into
   // existence, and the target it names is declared *by* that file — so writing
   // it second means resolving a target nothing has declared yet.
   if (!isRemoteWorkspace(local) && !existsSync(join(local, WORKSPACE_FILE))) {
@@ -80,6 +85,14 @@ export async function createProfile(
   const root = await resolveTargetWorkspace(local, target);
   const path = profilePath(root, name);
 
+  // The connections file comes into existence with the workspace, carrying the
+  // owner layer. It is written before the profile because the profile's grants
+  // name rows in it, and `assertGrantsResolve` refuses a grant with nothing
+  // behind it — so a profile written first would not load until this existed.
+  if (!(await workspaceFiles(root).has(CONNECTIONS_FILE))) {
+    await writeWorkspaceFile(workspaceFiles(root), CONNECTIONS_FILE, newConnectionsTemplate());
+  }
+
   if (await workspaceFiles(root).has(`profiles/${name}.yaml`)) {
     throw new Error(`Profile "${name}" already exists at ${path}`);
   }
@@ -99,10 +112,23 @@ export async function createProfile(
   // sibling's, or asked. It declares no target now (ADR-052): it is written into
   // the workspace of the target it was named with, and that workspace already
   // says where its bytes go.
+  // The signed-in subject, so the profile reaches somebody the moment it
+  // exists. Without it every new profile shipped `members: []` while the
+  // template writes `authorization: mode: self` — an endpoint that advertises
+  // OAuth and lists nobody, where the owner signs in at lanes.sh and is told no
+  // profile lists them. A local stdio or CI caller still worked, which is why a
+  // smoke test passed: those carry `profiles: undefined` and `mayReach` admits
+  // everything.
+  //
+  // Null when nobody is signed in, which is a real state — `lanes auth login`
+  // has not been run yet — and the template then says how to fix it rather than
+  // inventing a subject.
+  const session = await readSession();
+
   await writeWorkspaceFile(
     workspaceFiles(root),
     `profiles/${name}.yaml`,
-    newProfileTemplate(name, port),
+    newProfileTemplate(name, port, session?.subject),
   );
 
   return { name, path, port, targets: options.targets, copiedFrom: {} };
@@ -142,8 +168,8 @@ export async function profileAdd(
   if (options.targets.length === 0) {
     throw new ConfigError(
       'Say which targets this profile declares:\n' +
-        `  lanes link profile add ${name} --target local\n` +
-        `  lanes link profile add ${name} --target local --target cloud\n` +
+        `  lanes link profile add ${name} --workspace local\n` +
+        `  lanes link profile add ${name} --workspace local --workspace cloud\n` +
         '\n' +
         '  A target is where a profile runs — a credential store and a blob store.\n' +
         '  There is no default to inherit before the profile exists.',
@@ -152,11 +178,21 @@ export async function profileAdd(
 
   const created = await createProfile(name, options);
 
+  // Re-read rather than assembled from `created`, because the file on disk is
+  // what a workspace with a remote credential store needs to open one.
+  const primary = created.targets[0]!;
+  const { resolution, config } = await resolveProfile({ profile: created.name, target: primary });
+  await recordConfigChange(config, resolution.workspaceRoot, primary, {
+    capability: 'config.profile.add',
+    scope: created.name,
+    arguments: { port: created.port, workspace: primary },
+  });
+
   return emit(options.json, created, () => {
     print(ok(`created profile ${style.bold(created.name)}`));
     print(`      config   ${created.path}`);
     print(`      port     ${created.port}`);
-    print(`      targets  ${created.targets.join(', ')}`);
+    print(`      workspace  ${created.targets.join(', ')}`);
 
     for (const [target, from] of Object.entries(created.copiedFrom)) {
       print(`      ${style.dim(`${target} adapters copied from profile "${from}"`)}`);
@@ -165,7 +201,7 @@ export async function profileAdd(
     print();
     print(
       style.dim(
-        `Next: lanes link connect example --profile ${created.name} --target ${created.targets[0]}`,
+        `Next: lanes link connect example --profile ${created.name} --workspace ${created.targets[0]}`,
       ),
     );
   });
@@ -180,7 +216,7 @@ export async function profileList(
   return emit(options.json, listing, () => {
     if (listing.profiles.length === 0) {
       print(style.dim(`No profiles in ${listing.root}.`));
-      print(style.dim('Create one with: lanes link profile add personal --target local'));
+      print(style.dim('Create one with: lanes link profile add personal --workspace local'));
       return;
     }
 
@@ -210,7 +246,7 @@ export function profileDefault(name: string | undefined): never {
   throw new ConfigError(
     'lanes link profile default was removed.\n' +
       '  Nothing reads default_profile any more — pass --profile on every command:\n' +
-      `    lanes link status --profile ${name ?? '<name>'} --target <target>\n` +
+      `    lanes link status --profile ${name ?? '<name>'} --workspace <name>\n` +
       '  If the key is still in lanes-link.yaml it is inert, and safe to delete.',
   );
 }

package/src/cli/commands/relabel.ts

@@ -0,0 +1,112 @@
+import { CONNECTIONS_FILE, readConnections, type Resolution } from '#profile';
+import { ConfigDocument } from '../config-edit.ts';
+import { announce, announceWorkspace, emit, ok, print, style } from '../output.ts';
+import { recordConfigChange } from '../audit-change.ts';
+import { openWorkspaceRuntime, type GlobalFlags } from '../runtime.ts';
+import { nextAfterEdit, publishProfileEdit } from '../publish.ts';
+import { locate } from './connection.ts';
+
+/**
+ * `lanes link relabel` — the operator's own word for an account.
+ *
+ * Split from `disconnect` so `connection.ts` stays inside the size budget, and
+ * on a real seam rather than a line count: `disconnect` reaches two files, every
+ * profile that granted the row, and the credential store, while this writes one
+ * field in one document.
+ *
+ * The label is a separate field from `account` for the reason the bug below
+ * gives, and the two must not be merged back.
+ */
+
+export interface Relabelled {
+  readonly profile: string;
+  readonly target: string;
+  readonly key: string;
+  readonly from: string;
+  readonly to: string;
+  readonly published: string;
+}
+
+export interface RelabelFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+}
+
+/**
+ * Rename a connection, writing `label` and never `account`.
+ *
+ * It wrote `account` until it was noticed that `account` is not a display name:
+ * `settleIdentity` matches on it to tell a repair from a new account,
+ * `idFromAccount` derives the id from it, and `gmail.send_message` writes it
+ * into a `From` header. Renaming through it therefore un-recognised the account
+ * it renamed — the next `connect` added a second row beside it.
+ */
+export async function renameConnection(
+  key: string,
+  label: string,
+  flags: RelabelFlags,
+): Promise<{ resolution: Resolution; relabelled: Relabelled }> {
+  const runtime = await openWorkspaceRuntime(flags);
+
+  try {
+    const { resolution, config, target } = runtime;
+    const root = resolution.workspaceRoot;
+
+    // The workspace's file, not the profile's. A label is the operator's own
+    // word for an account (ADR-057 moved the row that carries it), so renaming
+    // it once renames it everywhere — which is what someone renaming "the work
+    // mailbox" means, and what two copies could never keep true.
+    const connectionsFile = await readConnections(root);
+    const located = locate(connectionsFile.connections, key, target);
+
+    const document = await ConfigDocument.openKey(root, CONNECTIONS_FILE);
+    document.setIn(['connections', located.index, 'label'], label);
+    await document.save();
+
+    await recordConfigChange(config, root, target, {
+      capability: 'config.connection.relabel',
+      scope: target,
+      connection: key,
+      arguments: { from: located.connection.label ?? located.connection.account, to: label },
+    });
+
+    return {
+      resolution,
+      relabelled: {
+        profile: resolution.profile,
+        target,
+        key,
+        // What it was called a moment ago, which is the account only until the
+        // first rename.
+        from: located.connection.label ?? located.connection.account,
+        to: label,
+        published: nextAfterEdit(await publishProfileEdit({ resolution, config, target })),
+      },
+    };
+  } finally {
+    await runtime.close();
+  }
+}
+
+export async function relabel(
+  key: string | undefined,
+  label: string | undefined,
+  flags: RelabelFlags,
+): Promise<void> {
+  if (!key) throw new Error('Which connection? Run: lanes link status');
+  if (!label) throw new Error(`What should ${key} be called? Run: lanes link relabel ${key} "New name"`);
+
+  const { resolution, relabelled: result } = await renameConnection(key, label, flags);
+
+  return emit(flags.json, result, () => {
+    announceWorkspace(resolution);
+    print(ok(`${style.bold(result.key)} is now ${style.bold(result.to)}`));
+    if (result.from) print(`      was     ${style.dim(result.from)}`);
+    // The label is a display name in two places, and only one of them changed.
+    print(
+      style.dim(
+        '      The state store keeps the old name until the next reconcile, which updates it.',
+      ),
+    );
+    if (result.published) print(style.dim(`      ${result.published}`));
+  })
+}

package/src/cli/commands/secrets.ts

@@ -1,14 +1,20 @@
 import { ConfigError } from '#profile';
 import { assertValidSecretRef } from '#secrets';
-import { announce, announceProfile, heading, ok, print, style } from '../output.ts';
-import { openSecretStoreFor, resolveProfile, resolveProfileOnly, type GlobalFlags } from '../runtime.ts';
+import { announceWorkspace, announceProfile, heading, ok, print, style } from '../output.ts';
+import {
+  openSecretStoreFor,
+  primaryProfile,
+  resolveProfile,
+  resolveProfileOnly,
+  type GlobalFlags,
+} from '../runtime.ts';
 
 /**
  * `lanes link secrets` — moving credential values between a profile's targets.
  *
  * Credentials follow the target, because each target has its own credential
- * store: `lanes link connect gmail.side --target cloud` writes the refresh token into
- * Secret Manager, and the same command with `--target local` writes it into
+ * store: `lanes link connect gmail.side --workspace cloud` writes the refresh token into
+ * Secret Manager, and the same command with `--workspace local` writes it into
  * the encrypted file. That is the right default and it leaves one gap, which
  * this command fills — a setup built locally first, and now wanted in the
  * cloud, without re-running every OAuth flow.
@@ -43,7 +49,7 @@ export async function secretsPush(flags: SecretsFlags): Promise<void> {
 
   const refs = await source.list();
   if (refs.length === 0) {
-    print(style.dim(`No credentials in target "${flags.from}".`));
+    print(style.dim(`No credentials in workspace "${flags.from}".`));
     return;
   }
 
@@ -104,7 +110,7 @@ export async function secretsSet(ref: string | undefined, flags: GlobalFlags): P
   if (!ref) {
     throw new ConfigError(
       'Usage: lanes link secrets set <ref>   (the value is read from stdin)\n' +
-        '  e.g. printf %s "$DATABASE_URL" | lanes link secrets set cloud/database_url --target cloud',
+        '  e.g. printf %s "$DATABASE_URL" | lanes link secrets set cloud/database_url --workspace cloud',
     );
   }
   assertValidSecretRef(ref);
@@ -119,8 +125,16 @@ export async function secretsSet(ref: string | undefined, flags: GlobalFlags): P
     );
   }
 
-  const { resolution, config, target } = await resolveProfile(flags);
-  announce(resolution);
+  // The credential store belongs to the workspace since contract 3, so every
+  // profile opened the same one and naming one chose nothing. A profile is
+  // still resolved, because `openSecretStoreFor` reads the adapter set through
+  // one — so the banner names the workspace rather than reporting whichever
+  // profile happened to supply it.
+  const { resolution, config, target } = await resolveProfile({
+    ...flags,
+    profile: await primaryProfile(flags),
+  });
+  announceWorkspace(resolution);
 
   const value = (await Bun.stdin.text()).replace(/\n$/, '');
   if (!value) {
@@ -133,20 +147,28 @@ export async function secretsSet(ref: string | undefined, flags: GlobalFlags): P
   const replacing = await credentials.has(ref);
   await credentials.set(ref, value);
 
-  print(ok(`${replacing ? 'replaced' : 'stored'} ${style.bold(ref)} in target ${target}`));
+  print(ok(`${replacing ? 'replaced' : 'stored'} ${style.bold(ref)} in workspace ${target}`));
   if (replacing) {
     print(style.dim('  Anything still using the old value will start failing.'));
   }
 }
 
 export async function secretsList(flags: GlobalFlags): Promise<void> {
-  const { resolution, config, target } = await resolveProfile(flags);
-  announce(resolution);
+  // The credential store belongs to the workspace since contract 3, so every
+  // profile opened the same one and naming one chose nothing. A profile is
+  // still resolved, because `openSecretStoreFor` reads the adapter set through
+  // one — so the banner names the workspace rather than reporting whichever
+  // profile happened to supply it.
+  const { resolution, config, target } = await resolveProfile({
+    ...flags,
+    profile: await primaryProfile(flags),
+  });
+  announceWorkspace(resolution);
 
   const credentials = await openSecretStoreFor(config, resolution.workspaceRoot, target);
   const refs = await credentials.list();
 
-  heading(`Credential references in target ${target} (${refs.length})`);
+  heading(`Credential references in workspace ${target} (${refs.length})`);
   if (refs.length === 0) {
     print(style.dim('  none'));
   } else {

package/src/cli/commands/set-workspace.ts

@@ -0,0 +1,96 @@
+import {
+  ConfigError,
+  WORKSPACE_FILE,
+  readRegistry,
+  readWorkspace,
+  resolveWorkspaceRoot,
+} from '#profile';
+import { ConfigDocument } from '../config-edit.ts';
+import { ok, print, style } from '../output.ts';
+
+/**
+ * `lanes set-workspace <name>` — which workspace a command means when it does
+ * not say.
+ *
+ * ADR-037 deleted the command this replaces, and its reasoning is the thing to
+ * read before changing anything here:
+ *
+ * > Persisted context state is the standard way operators run destructive
+ * > commands against the wrong target, and the version of it that bites is the
+ * > dotfile nothing prints.
+ *
+ * Both halves of that sentence are answered rather than argued with (ADR-061).
+ * The default is **printed on every command that uses it**, so it is not the
+ * dotfile nothing prints; and it is **refused by every command that publishes or
+ * destroys**, so it is not what runs a destructive command against the wrong
+ * thing. Take either half away and the objection stands again.
+ *
+ * Top level rather than under `lanes link`, because it selects the workspace
+ * *the CLI* acts in and a second area added to `lanes` will want the same
+ * answer.
+ */
+
+export interface SetWorkspaceResult {
+  readonly workspace: string;
+  readonly previous: string | null;
+  readonly path: string;
+}
+
+export async function setWorkspace(
+  name: string | undefined,
+  options: { json?: boolean } = {},
+): Promise<void> {
+  const root = resolveWorkspaceRoot();
+
+  if (name === undefined) {
+    const current = (await readWorkspace(root))?.default_workspace;
+    throw new ConfigError(
+      `Usage: lanes set-workspace <name>\n` +
+        (current ? `  The default is currently "${current}".\n` : '  No default is set.\n') +
+        `  Run "lanes link workspace list" to see what there is.`,
+    );
+  }
+
+  // Checked against the registry, not accepted on trust. A default naming a
+  // workspace that does not exist would turn every later command's refusal into
+  // one about the wrong thing — and the operator would have been told "ok" by
+  // the command that caused it.
+  const registry = await readRegistry(root);
+  if (!(name in registry)) {
+    const names = Object.keys(registry).sort();
+    throw new ConfigError(
+      `${root} declares no workspace "${name}".\n` +
+        (names.length > 0
+          ? `  It has: ${names.join(', ')}\n`
+          : '  It has none yet. Create one with: lanes link profile add <name> --workspace local\n') +
+        `  Run "lanes link workspace list" to see them.`,
+    );
+  }
+
+  const document = await ConfigDocument.openKey(root, WORKSPACE_FILE);
+  const previous = document.getIn(['default_workspace']);
+  document.setIn(['default_workspace'], name);
+  await document.save();
+
+  const result: SetWorkspaceResult = {
+    workspace: name,
+    previous: typeof previous === 'string' ? previous : null,
+    path: `${root}/${WORKSPACE_FILE}`,
+  };
+
+  if (options.json === true) {
+    print(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  print(ok(`default workspace: ${style.bold(name)}`));
+  print(style.dim(`      ${result.path}`));
+  print('');
+  print(
+    style.dim(
+      '      Every command that uses it prints it. Commands that publish or destroy —\n' +
+        '      deploy, sync, secrets push, profile remove, disconnect, token rotate —\n' +
+        '      still want --workspace typed out.',
+    ),
+  );
+}

package/src/cli/commands/setup.ts

@@ -25,11 +25,11 @@ export async function setupPlan(provider: string | undefined, flags: SetupFlags)
     const context = {
       profile: runtime.resolution.profile,
       target: runtime.resolution.target,
-      connections: runtime.config.connections.map((c) => `${c.provider}.${c.id}`),
+      connections: runtime.connections.map(({ ref }) => ref),
       // Declaring an `oauth_apps` entry is how a profile says "use my own
       // client". Without this the plan would tell someone who has already
       // registered one that they need nothing.
-      ownClients: Object.keys(runtime.config.oauth_apps),
+      ownClients: runtime.ownClients,
     };
 
     const manifests = runtime.registry.list().map((entry) => entry.manifest);

package/src/cli/commands/sync.ts

@@ -64,15 +64,15 @@ async function locateRemote(
   }
 
   const entry = (await readRegistry(root))[target];
-  if (entry?.workspace) return { workspace: entry.workspace, how: 'already recorded' };
+  if (entry?.at) return { workspace: entry.at, how: 'already recorded' };
 
   if (flags.discover !== true) {
     throw new ConfigError(
       `Nothing here says where "${target}" lives.\n` +
         '  No pointer to it in lanes-link.yaml, and nothing else records one.\n\n' +
-        '  If you know the bucket:  lanes link sync targets --target ' +
+        '  If you know the bucket:  lanes link sync workspaces --workspace ' +
         `${target} --from gs://<bucket>\n` +
-        `  If you do not:           lanes link sync targets --target ${target} --discover`,
+        `  If you do not:           lanes link sync targets --workspace ${target} --discover`,
     );
   }
 
@@ -99,7 +99,7 @@ async function locateRemote(
   if (candidates.length > 1 || !isInteractive()) {
     throw new ConfigError(
       `Found ${candidates.length} deployment(s). Name the one you mean:\n` +
-        `  lanes link sync targets --target ${target} --from ${first.workspace}`,
+        `  lanes link sync targets --workspace ${target} --from ${first.workspace}`,
     );
   }
 
@@ -132,7 +132,7 @@ export async function syncTargets(flags: SyncFlags): Promise<void> {
   const remoteRegistry = await readRegistry(workspace);
   const declaresIt = remoteRegistry[target] !== undefined;
   const existing = (await readRegistry(root))[target];
-  const already = existing?.workspace === workspace;
+  const already = existing?.at === workspace;
 
   const payload = { workspace: root, remote: workspace, target, how, declaresIt, applied: false };
 
@@ -163,7 +163,7 @@ export async function syncTargets(flags: SyncFlags): Promise<void> {
     }
 
     heading('Would write');
-    print(`  targets.${target}.workspace: ${workspace}`);
+    print(`  workspaces.${target}.at: ${workspace}`);
     print(style.dim('  The bucket keeps everything else; this records where it is.'));
   };
 
@@ -184,11 +184,11 @@ export async function syncTargets(flags: SyncFlags): Promise<void> {
   // deploy block, whose token opens it — is declared where it lives, and reading
   // it from there is what makes this safe to run on a workspace that has lost
   // its own copy of anything.
-  await recordTarget(root, target, { workspace });
+  await recordTarget(root, target, { at: workspace });
 
   print('');
   print(ok(`"${target}" now points at ${workspace}`));
-  print(style.dim(`  lanes link status --target ${target}   reads it from there`));
+  print(style.dim(`  lanes link status --workspace ${target}   reads it from there`));
 
   return emit(flags.json, { ...payload, applied: true }, () => {});
 }

package/src/cli/commands/target.ts

@@ -158,7 +158,7 @@ function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): T
     return {
       name,
       isSelected,
-      pointsAt: entry.workspace,
+      pointsAt: entry.at,
       credentials: null,
       storage: null,
       vault: null,
@@ -200,7 +200,7 @@ function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): T
  * line above, from the same object.
  */
 export function resolvedEntry(resolved: ResolvedTarget): WorkspaceTarget {
-  const { workspace: _followed, ...record } = resolved.entry;
+  const { at: _followed, ...record } = resolved.entry;
   return { ...resolved.declared, ...record };
 }
 
@@ -261,7 +261,7 @@ export async function targetList(flags: TargetFlags): Promise<void> {
     // as input would be circular, and it has to keep working in the state every
     // other command fails in — which is what `selectedDeclared` reports.
     if (listing.selected === null) {
-      print(style.dim('  Every other command names one of these with --target.'));
+      print(style.dim('  Every other command names one of these with --workspace.'));
       return;
     }
 
@@ -299,10 +299,12 @@ function deploymentCell(target: TargetSummary): string {
  */
 export function targetUse(name: string | undefined): never {
   throw new ConfigError(
-    'lanes link target use was removed.\n' +
-      '  Nothing reads instance.default_target any more — pass --target on every\n' +
-      '  command instead:\n' +
-      `    lanes link status --profile <name> --target ${name ?? '<target>'}\n` +
+    'lanes link workspace use was removed, and came back under a new name.\n' +
+      '  `instance.default_target` is still inert — nothing reads it. What does\n' +
+      '  read a default is `default_workspace` in lanes-link.yaml (ADR-061):\n' +
+      `    lanes set-workspace ${name ?? '<name>'}\n` +
+      '  Or name it per command:\n' +
+      `    lanes link status --profile <name> --workspace ${name ?? '<name>'}\n` +
       '  If the key is still in your profile it is inert, and safe to delete.',
   );
 }

package/src/cli/commands/update.ts

@@ -2,10 +2,12 @@ import { homedir } from 'node:os';
 import { join, sep } from 'node:path';
 import { installRoot, resolveWorkspaceRoot } from '#profile';
 import { repairOwnerLayer } from '../config-repair.ts';
-import { migrateWorkspace, needsMigration } from '../workspace-migrate.ts';
+import { migrateToCurrentContract, type ContractMigration } from '../workspace-migrate.ts';
+import type { Contract3Migration } from '../contract3.ts';
 import { emit, fail, ok, print, printErr, progress, style, warn } from '../output.ts';
 import { PACKAGE, release, type ReleaseState } from '../release.ts';
 import { version } from '../version.ts';
+import { readSession } from '#auth/lanes/session.ts';
 
 /**
  * `lanes link update` — install the newer release, or say why it will not.
@@ -306,27 +308,66 @@ async function runInstall(argv: readonly string[], json: boolean): Promise<boole
  * about, in a sentence naming the fix, rather than a reason for the upgrade to
  * fail. `check` and `doctor` both refuse loudly on the next run.
  */
+/**
+ * Contract 2 to contract 3, reported the same way its predecessor is.
+ *
+ * Loud about what moved, because this one moves credentials. An operator whose
+ * fifteen accounts were merged into one store should see that happen rather than
+ * discover it from a directory listing.
+ */
+function sayContract3(migration: Contract3Migration, say: (line: string) => void): void {
+  say(
+    `migrated ${migration.profiles.length} profile(s) to contract 3 — connections belong to the ` +
+      'workspace now, and a profile grants them one by one',
+  );
+  for (const change of migration.changes) say(`  ${change}`);
+
+  if (migration.renames.length > 0) {
+    say('  Two profiles named different accounts with the same id, so one was renamed.');
+    say('  Check the grants in each profile before running an agent against them.');
+  }
+
+  say(`  The old per-profile credential stores are left in place; remove them once this works.`);
+}
+
 async function migrateLocal(root: string, say: (line: string) => void): Promise<void> {
   try {
-    if (!(await needsMigration(root))) return;
+    // One call, both steps, in order — a workspace that predates both walks
+    // through them rather than jumping, so each step's reasoning applies to the
+    // shape it was written for. `update` used to spell that walk itself, which
+    // is how `deploy` and `doctor --fix` came to spell only half of it.
+    //
+    // The subject is passed rather than left to be defaulted because this is
+    // the one caller that already had it in hand.
+    const session = await readSession();
+    const migration = await migrateToCurrentContract(root, {
+      apply: true,
+      ...(session ? { subject: session.subject } : {}),
+    });
+
+    if (migration.legacy) sayLegacyTargets(migration.legacy, say);
+    if (migration.contract3) sayContract3(migration.contract3, say);
+  } catch (error) {
+    say(`could not migrate this workspace: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
 
-    const migration = await migrateWorkspace(root);
-    if (migration.alreadyCurrent) return;
+/** Contract 1 to contract 2: targets move from the profile to the workspace. */
+function sayLegacyTargets(
+  migration: NonNullable<ContractMigration['legacy']>,
+  say: (line: string) => void,
+): void {
+  say(
+    `migrated ${migration.profiles.length} profile(s) to contract 2 — a target is declared by ` +
+      'the workspace now, not by each profile',
+  );
+  for (const change of migration.changes) say(`  ${change}`);
 
+  for (const pointer of migration.targets.filter((one) => one.kind === 'pointer')) {
     say(
-      `migrated ${migration.profiles.length} profile(s) to contract 2 — a target is declared by ` +
-        'the workspace now, not by each profile',
+      `  "${pointer.name}" points at ${pointer.where} — run ` +
+        `lanes link deploy --workspace ${pointer.name} to migrate what is there`,
     );
-    for (const change of migration.changes) say(`  ${change}`);
-
-    const pointers = migration.targets.filter((one) => one.kind === 'pointer');
-    for (const pointer of pointers) {
-      say(
-        `  "${pointer.name}" points at ${pointer.where} — run ` +
-          `lanes link deploy --target ${pointer.name} to migrate what is there`,
-      );
-    }
-  } catch (error) {
-    say(`could not migrate this workspace: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+