@lanes-sh/link 0.7.2 → 0.9.0

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

package/src/cli/main.ts

@@ -1,6 +1,10 @@
 import { connect } from './commands/connect/index.ts';
 import { connectCustom } from './commands/connect/custom/index.ts';
-import { disconnect, relabel } from './commands/connection.ts';
+import { disconnect } from './commands/connection.ts';
+import { grantConnectionTo, revokeConnectionFrom } from './commands/grant.ts';
+import { connectionList } from './commands/connection-list.ts';
+import { membersAdd, membersList, membersRemove } from './commands/members.ts';
+import { relabel } from './commands/relabel.ts';
 import {
   attachFile,
   auditTail,
@@ -11,6 +15,7 @@ import {
   desktop,
   doctor,
   outputs,
+  pair,
   plan,
   policyList,
   policyRule,
@@ -26,13 +31,23 @@ import { syncTargets } from './commands/sync.ts';
 import { targetList, targetShow, targetUse } from './commands/target.ts';
 import { identityAdd, identityList, identityRemove } from './commands/identity.ts';
 import { setupPlan } from './commands/setup.ts';
-import { mcpAdd, mcpList, mcpStdio, skillDocument } from './commands/mcp.ts';
+import { installInstructions, mcpAdd, mcpList, mcpStdio, skillDocument } from './commands/mcp.ts';
 import { deploy } from '#deployments/deploy.ts';
 import { secretsList, secretsPush, secretsSet } from './commands/secrets.ts';
 import { knowledgeShow, knowledgeUse } from './commands/knowledge.ts';
 import { dispatchOwner } from './dispatch-owner.ts';
 import { update } from './commands/update.ts';
-import { all, customFlags, globalFlags, knowledgeFlags, ownerFlags, parseArgv, text } from './argv.ts';
+import {
+  all,
+  customFlags,
+  globalFlags,
+  knowledgeFlags,
+  ownerFlags,
+  parseArgv,
+  text,
+} from './argv.ts';
+import type { GlobalFlags } from './runtime.ts';
+import type { OwnerFlags } from './commands/owner/shared.ts';
 import { assertKnownFlags } from './selection.ts';
 import { requireSelection } from './selection-require.ts';
 import { PROGRAM, USAGE } from './usage.ts';
@@ -57,8 +72,12 @@ export async function run(argv: readonly string[]): Promise<void> {
   const { command, flags } = parseArgv(argv);
   const [first, second, ...rest] = command;
 
-  const global = globalFlags(flags);
-  const owner = ownerFlags(flags, argv);
+  // Both are read *after* `requireSelection`, which is what resolves
+  // `default_workspace` onto `flags` (ADR-061). Capturing them before it would
+  // hand every command an undefined workspace on the path the default exists to
+  // serve — the flag would be resolved and nothing would be looking.
+  let global: GlobalFlags;
+  let owner: OwnerFlags;
 
   const show = flags['show'] === true;
   const raw = flags['raw'] === true;
@@ -77,6 +96,9 @@ export async function run(argv: readonly string[]): Promise<void> {
   assertKnownFlags(first, second, flags);
   await requireSelection(first, second, flags);
 
+  global = globalFlags(flags);
+  owner = ownerFlags(flags, argv);
+
   switch (first) {
     case 'connect':
       // A nested switch rather than an `if`, so `selection.test.ts` sees
@@ -117,6 +139,20 @@ export async function run(argv: readonly string[]): Promise<void> {
           });
       }
 
+    // The command connecting no longer implies. A connection belongs to the
+    // workspace (ADR-057), so which profiles may reach it is a separate say.
+    case 'connection':
+      if (second !== 'list' && second !== undefined) {
+        throw new Error(`Unknown: ${PROGRAM} connection ${second}`);
+      }
+      return connectionList({ ...global, json });
+
+    case 'grant':
+      return grantConnectionTo(second, { ...global, json });
+
+    case 'revoke':
+      return revokeConnectionFrom(second, { ...global, json });
+
     case 'setup':
       if (second !== 'plan' && second !== undefined) {
         throw new Error(`Unknown: ${PROGRAM} setup ${second}`);
@@ -127,27 +163,47 @@ export async function run(argv: readonly string[]): Promise<void> {
       switch (second) {
         case 'add':
           if (!rest[0]) {
-            throw new Error(`Usage: ${PROGRAM} profile add <name> --target <name>`);
+            throw new Error(`Usage: ${PROGRAM} profile add <name> --workspace <name>`);
           }
           return profileAdd(rest[0], {
             // One target, not a list. A profile declared every target it could
             // run on under contract 1, which is why this read the repeated flag
             // out of argv; it lives in exactly one now (ADR-052), so a second
             // --target would be naming a second place to put the same file.
-            targets: [text(flags, 'target')!],
+            targets: [text(flags, 'workspace')!],
             nonInteractive: flags['non-interactive'] === true,
             json,
           });
         case 'list':
         case undefined:
-          return profileList(text(flags, 'target')!, { json });
+          return profileList(text(flags, 'workspace')!, { json });
         case 'default':
           if (!rest[0]) throw new Error(`Usage: ${PROGRAM} profile default <name>`);
           return profileDefault(rest[0]);
+        case 'members': {
+          const [action, subject] = rest;
+          switch (action) {
+            case 'add':
+              return membersAdd(subject, {
+                ...global,
+                json,
+                me: flags['me'] === true,
+                role: text(flags, 'role'),
+              });
+            case 'remove':
+              return membersRemove(subject, { ...global, json });
+            case 'list':
+            case undefined:
+              return membersList({ ...global, json });
+            default:
+              throw new Error(`Unknown: ${PROGRAM} profile members ${action}`);
+          }
+        }
         case 'remove':
           if (!rest[0]) {
             throw new Error(
-              `Usage: ${PROGRAM} profile remove <name> [--target t] [--dry-run] [--yes]`,
+              `Usage: ${PROGRAM} profile remove <name> [--workspace <name>] [--dry-run] [--yes] ` +
+                '[--delete-data | --migrate-to <profile>]',
             );
           }
           return profileRemove(rest[0], {
@@ -155,23 +211,31 @@ export async function run(argv: readonly string[]): Promise<void> {
             json,
             dryRun: flags['dry-run'] === true,
             yes: flags['yes'] === true,
+            deleteData: flags['delete-data'] === true,
+            ...(typeof flags['migrate-to'] === 'string'
+              ? { migrateTo: flags['migrate-to'] }
+              : {}),
           });
         default:
           throw new Error(`Unknown: ${PROGRAM} profile ${second}`);
       }
 
+    // `target` was the old word for the same thing (ADR-061). Kept as its own
+    // case rather than aliased, so `selection.test.ts` sees both spellings and
+    // neither can default quietly.
     case 'target':
+    case 'workspace':
       switch (second) {
         case 'list':
         case undefined:
           return targetList({ ...global, json, urls: flags['urls'] === true });
         case 'use':
-          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} target use <name>`);
+          if (!rest[0]) throw new Error(`Usage: ${PROGRAM} workspace use <name>`);
           return targetUse(rest[0]);
         case 'show':
           return targetShow(rest[0], { ...global, json });
         default:
-          throw new Error(`Unknown: ${PROGRAM} target ${second}`);
+          throw new Error(`Unknown: ${PROGRAM} workspace ${second}`);
       }
 
     case 'identity': {
@@ -206,11 +270,15 @@ export async function run(argv: readonly string[]): Promise<void> {
           const [capability] = rest;
           if (!capability) {
             throw new Error(
-              `Usage: ${PROGRAM} policy ${second} <capability>\n` +
-                `  e.g. ${PROGRAM} policy ${second} gmail.send_message, or gmail.* for the whole provider`,
+              `Usage: ${PROGRAM} policy ${second} <capability> --connection <provider>.<id>\n` +
+                `  e.g. ${PROGRAM} policy ${second} gmail.send_message --connection gmail.personal,\n` +
+                `       or gmail.* for everything that connection's provider offers`,
             );
           }
-          return policyRule(second, capability, global);
+          return policyRule(second, capability, {
+            ...global,
+            ...(typeof flags.connection === 'string' ? { connection: flags.connection } : {}),
+          });
         }
         default:
           throw new Error(`Unknown: ${PROGRAM} policy ${second}`);
@@ -227,6 +295,14 @@ export async function run(argv: readonly string[]): Promise<void> {
           throw new Error(`Unknown: ${PROGRAM} token ${second}`);
       }
 
+    case 'pair':
+      return pair({
+        ...global,
+        print: flags['print'] === true,
+        rotate: flags['rotate'] === true,
+        yes: flags['yes'] === true,
+      });
+
     case 'audit':
       if (second === 'verify') return auditVerify(global);
       if (second !== 'tail' && second !== undefined) {
@@ -340,7 +416,10 @@ export async function run(argv: readonly string[]): Promise<void> {
             dryRun: flags['dry-run'] === true,
             force: flags['force'] === true,
             noSkill: flags['no-skill'] === true,
+            headless: flags['headless'] === true,
           });
+        case 'install-instructions':
+          return installInstructions({ ...(text(flags, 'client') ? { client: text(flags, 'client') } : {}) });
         case 'stdio':
           return mcpStdio({ ...global, ...(flags['only'] === true ? { only: true } : {}) });
         case 'list':
@@ -398,6 +477,7 @@ export async function run(argv: readonly string[]): Promise<void> {
       switch (second) {
         case undefined:
         case 'targets':
+        case 'workspaces':
           return syncTargets({
             ...global,
             dryRun: flags['dry-run'] === true,

package/src/cli/migrate-move.ts

@@ -0,0 +1,166 @@
+import { ConfigError } from '#profile';
+import type { BlobStore } from '#stores/blobs';
+
+/**
+ * Moving objects between two layouts, without losing one.
+ *
+ * Shared by every contract migration that relocates bytes rather than YAML —
+ * contract 3 hoisting a profile's data to the workspace, contract 4 carrying it
+ * back into the profile. Each learned the same rules the same hard way, so they
+ * live once: nothing is deleted until what replaced it has been read back, every
+ * destination is checked before the first byte moves, and a rerun after an
+ * interruption finishes rather than refusing.
+ */
+
+export interface Move {
+  readonly from: string;
+  readonly to: string;
+  /**
+   * Rewrite the object's bytes on the way across.
+   *
+   * Only a connection record needs this, and it needs it for a reason a plain
+   * copy cannot serve: `ConnectionRepository.list` reads `provider` and `id`
+   * out of the record *body*, not out of the key it was stored under. A renamed
+   * connection whose bytes were copied verbatim would sit at
+   * `connections.v1/vault.work` still calling itself `vault.main`, and the next
+   * `upsert` would write a second record beside it.
+   */
+  readonly rewrite?: (data: Uint8Array) => Uint8Array;
+  /**
+   * Write only where the destination is empty; leave the source alone if not.
+   *
+   * For the objects two profiles can legitimately both hold — a connection they
+   * share, a provider-keyed cache, one custom manifest — where a second copy is
+   * a duplicate rather than a clash. `claim` drops the loser within one run, but
+   * deletes the winner's source and leaves the loser's: the rerun then saw a
+   * different first claimant, found foreign bytes at the destination, and threw,
+   * permanently. `rewriteProfiles` stamps the contract *after* the moves, so an
+   * interruption during them forces exactly that rerun.
+   */
+  readonly whenAbsent?: boolean;
+  /**
+   * Copy, and leave the source where it is.
+   *
+   * For the one thing contract 4 cannot decide: a store two profiles both grant
+   * has to land in both, and neither copy may delete what the other still needs
+   * to read. The original is reported rather than removed — merging two sets of
+   * notes is not reversible, and picking one profile's would take the other's
+   * away silently.
+   */
+  readonly keep?: boolean;
+}
+
+/**
+ * Two objects aimed at one key, caught while this is still a plan.
+ *
+ * `applyMoves` checks the destination per object as well, but that check cannot
+ * see a collision between two objects *in this run* once the moves are applied
+ * concurrently — both would look at an absent destination and both would write.
+ * Hoisting it here also puts it where this file says it belongs: everything that
+ * can fail happens before the first byte moves, so a refusal leaves the
+ * workspace exactly as it was.
+ */
+export function assertOneObjectPerDestination(moves: readonly Move[]): void {
+  const seen = new Map<string, string>();
+
+  for (const move of moves) {
+    const first = seen.get(move.to);
+    if (first !== undefined) {
+      throw new ConfigError(
+        `Two objects want to be at ${move.to}, and this migration cannot merge them.\n` +
+          `  ${first} and ${move.from}. Nothing has been written.\n` +
+          '  Which one to keep is yours to decide, because both are your data: move or\n' +
+          '  delete one of the two, then run this again.',
+      );
+    }
+    seen.set(move.to, move.from);
+  }
+}
+
+/** First claim on a destination wins; a later one is left where it is. */
+export function claim(claimed: Set<string>, move: Move): Move | null {
+  if (claimed.has(move.to)) return null;
+  claimed.add(move.to);
+  return { ...move, whenAbsent: true };
+}
+
+/**
+ * How many objects are in flight at once.
+ *
+ * Serial was fine while this only ever ran against a local disk. A deployed
+ * workspace's audit log is one object per event, so the first real bucket this
+ * migrated held 1,906 of them — three round trips each, in series, is minutes of
+ * a deploy spent with nothing on screen. The same 16 the read paths in
+ * `#providers/memory` and `#providers/tasks` settled on, and for the same
+ * reason: enough to hide the latency, not enough to look like an incident to the
+ * other end.
+ *
+ * Safe to widen only while each move stays independent, which is what
+ * `assertOneObjectPerDestination` guarantees.
+ */
+const MOVE_CONCURRENCY = 16;
+
+export async function applyMoves(files: BlobStore, moves: readonly Move[]): Promise<void> {
+  const pending = moves.filter((move) => move.from !== move.to);
+
+  for (let start = 0; start < pending.length; start += MOVE_CONCURRENCY) {
+    await Promise.all(
+      pending.slice(start, start + MOVE_CONCURRENCY).map((move) => applyMove(files, move)),
+    );
+  }
+}
+
+/** One object, moved or finished. Never deletes before the copy reads back. */
+async function applyMove(files: BlobStore, move: Move): Promise<void> {
+  const source = await files.get(move.from);
+  if (source === null) return;
+
+  // Before the comparison below as well as before the write. Comparing the
+  // *source* bytes against a destination that holds the rewritten ones would
+  // read an already-finished move as a collision, and refuse the one rerun this
+  // file promises.
+  const data = move.rewrite === undefined ? source : move.rewrite(source);
+
+  if (await files.has(move.to)) {
+    const held = await files.get(move.to);
+
+    // Raced away between the two calls, so there is nothing there after all and
+    // the ordinary path below is still the right one.
+    if (held !== null) {
+      // Another instance of the same connection, or another profile's copy of
+      // one shared cache, got there first. Left where it is rather than
+      // refused — and rerunnable, which is the whole point.
+      if (!sameBytes(held, data)) {
+        if (move.whenAbsent === true) return;
+        throw new ConfigError(
+          `Two objects want to be at ${move.to}, and this migration cannot merge them.\n` +
+            `  ${move.from} is the second, and what is already there is not a copy of it.\n` +
+            '  Nothing has been deleted. Please report it with the layout of your data ' +
+            'directory.',
+        );
+      }
+
+      // Already copied, by a run that did not get to the delete.
+      if (move.keep !== true) await files.delete(move.from);
+      return;
+    }
+  }
+
+  await files.put(move.to, data);
+  if ((await files.get(move.to)) === null) {
+    throw new ConfigError(
+      `${move.to} did not read back after being written. Nothing has been deleted; ` +
+        `fix the store and run this again.`,
+    );
+  }
+
+  if (move.keep !== true) await files.delete(move.from);
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}

package/src/cli/migrate-plan.ts

@@ -1,4 +1,5 @@
-import { ConfigError, layout, isRemoteWorkspace, type LegacyTarget, type WorkspaceTarget } from '#profile';
+import {
+  LEGACY_DATA_DIR, ConfigError, layout, isRemoteWorkspace, type LegacyTarget, type WorkspaceTarget } from '#profile';
 import { deployedWorkspace } from '#deployments/upload.ts';
 
 /**
@@ -88,7 +89,7 @@ export function toEntry(
   // produces `gs://b` pointing at `gs://b`. That is a loop, and `openTarget`
   // refuses it — which made `deploy` unable to run against the bucket it had
   // just migrated, on the one command the refusal names as the fix.
-  if (remote && remote !== workspaceRoot) return { workspace: remote };
+  if (remote && remote !== workspaceRoot) return { at: remote };
 
   // **A filesystem target is dropped from a remote workspace.**
   //
@@ -105,8 +106,13 @@ export function toEntry(
   const storagePath = declared.storage.path;
   const credentialsPath = declared.credentials.path;
 
-  const defaultStorage = `./${layout.blobs(profile)}`;
-  const defaultCredentials = `./${layout.credentials(profile)}`;
+  // The **contract-1** defaults, spelled out rather than taken from `layout`.
+  // This function reads a contract-1 profile, where every path was per profile,
+  // and `layout` describes where things live *now* — workspace-level since
+  // ADR-057. Asking it would compare a contract-1 path against a contract-3
+  // default and refuse every profile that had written the ordinary one.
+  const defaultStorage = `./${LEGACY_DATA_DIR}/${profile}`;
+  const defaultCredentials = `./${LEGACY_DATA_DIR}/${profile}/credentials.enc`;
 
   refuseCustomPath(name, profile, workspaceRoot, 'storage.path', storagePath, defaultStorage);
   refuseCustomPath(
@@ -149,12 +155,12 @@ function refuseCustomPath(
       `  A target is declared once for the whole workspace now (ADR-052), so it cannot hold a\n` +
       `  different path per profile. The default it would get is ${expected}.\n\n` +
       `  Move the data there and delete the line, or keep this profile in a workspace of its\n` +
-      `  own: LANES_LINK_HOME=${workspaceRoot}/<somewhere> lanes link profile add ${profile} --target ${target}`,
+      `  own: LANES_LINK_HOME=${workspaceRoot}/<somewhere> lanes link profile add ${profile} --workspace ${target}`,
   );
 }
 
 export function summarise(entry: WorkspaceTarget): string {
-  if (entry.workspace !== undefined) return `points at ${entry.workspace}`;
+  if (entry.at !== undefined) return `points at ${entry.at}`;
   const parts = [entry.credentials?.adapter, entry.storage?.adapter].filter(Boolean);
   return `${parts.join(' + ')}${entry.deploy ? `, deploys ${entry.deploy.service}` : ''}`;
 }

package/src/cli/output.ts

@@ -1,3 +1,4 @@
+import { wasDefaulted } from './selection-require.ts';
 import type { Resolution } from '#profile';
 
 /**
@@ -126,16 +127,48 @@ export function announceProfile(selection: {
   print(style.dim(`profile ${style.bold(selection.profile)}  ${selection.workspaceRoot}`));
 }
 
+/**
+ * The line every command prints before its output.
+ *
+ * It names the workspace, and whether that workspace was *typed* or came from
+ * `default_workspace`. The provenance is not decoration: ADR-037 removed sticky
+ * selection because "the dotfile nothing prints" is how an operator runs a
+ * command against the wrong thing, and ADR-061 gives the default back only on
+ * the condition that it announces itself. Dropping the `(default)` marker for
+ * tidiness would reverse that decision.
+ */
 export function announce(resolution: Resolution): void {
+  const provenance = wasDefaulted(resolution.target) ? ' (default)' : '';
+
   print(
     style.dim(
       `profile ${style.bold(resolution.profile)}  ` +
-        `target ${style.bold(resolution.target)}  ` +
+        `workspace ${style.bold(resolution.target)}${provenance}  ` +
         `${resolution.workspaceRoot}`,
     ),
   );
 }
 
+/**
+ * The same line, for a command whose subject is the workspace.
+ *
+ * It names no profile, and that is the point rather than a saving. A
+ * workspace-level command still opens a runtime, and a runtime carries a
+ * profile — so `announce` would print whichever one happened to be picked, and
+ * a reader would take it for the thing being acted on. The audit log is one
+ * chain for the whole workspace; saying `profile personal` above it describes a
+ * log that does not exist.
+ */
+export function announceWorkspace(resolution: Resolution): void {
+  const provenance = wasDefaulted(resolution.target) ? ' (default)' : '';
+
+  print(
+    style.dim(
+      `workspace ${style.bold(resolution.target)}${provenance}  ${resolution.workspaceRoot}`,
+    ),
+  );
+}
+
 /**
  * Print a machine-readable result, or fall through to the human rendering.
  *

package/src/cli/publish.ts

@@ -53,7 +53,8 @@ export async function publishAndNotify(input: {
   readonly config: Config;
   readonly workspaceRoot: string;
   readonly target: string;
-  readonly profile: string;
+  /** Every profile the edit touched. See `publishWorkspace`. */
+  readonly profile: string | readonly string[];
   readonly credentials: SecretStore;
 }): Promise<PublishOutcome> {
   let published: string | null = null;
@@ -98,18 +99,16 @@ export async function publishProfileEdit(input: {
   readonly resolution: { readonly workspaceRoot: string; readonly profile: string };
   readonly config: Config;
   readonly target: string;
+  /** Every profile the edit touched, where it reached more than the one named. */
+  readonly touched?: readonly string[] | undefined;
 }): Promise<PublishOutcome> {
-  const credentials = await openSecretStoreFor(
-    input.config,
-    input.resolution.workspaceRoot,
-    input.target,
-  );
+  const credentials = await openSecretStoreFor(input.resolution.workspaceRoot, input.target);
 
   return publishAndNotify({
     config: input.config,
     workspaceRoot: input.resolution.workspaceRoot,
     target: input.target,
-    profile: input.resolution.profile,
+    profile: input.touched ?? input.resolution.profile,
     credentials,
   });
 }