@lanes-sh/link 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/cli/commands/operate/inspect.ts

@@ -2,9 +2,10 @@ import { credentialRefFor, formatPlan, planIsNoop, planReconcile } from '#regist
 import { DEFAULT_SURFACES } from '../../config-repair.ts';
 import { announce, announceProfile, emit, fail, ok, print, warn } from '../../output.ts';
 import { staleNudge } from '../../release.ts';
-import { openRuntime, resolveProfileOnly, type GlobalFlags } from '../../runtime.ts';
+import { openRuntime, resolveProfileOnly, type GlobalFlags, type Runtime } from '../../runtime.ts';
 import type { FetchLike } from '#deployments/knowledge.ts';
 import { credentialAge, reportCapabilityDrift } from './findings.ts';
+import { migratedRenamedProviders } from './migrate.ts';
 
 /**
  * The gate order — check, doctor, plan, start — exists so failures surface in
@@ -41,6 +42,8 @@ export async function plan(flags: GlobalFlags): Promise<void> {
 
 export interface DoctorFlags extends GlobalFlags {
   readonly json?: boolean | undefined;
+  /** Apply a repair `doctor` would otherwise only report. */
+  readonly fix?: boolean | undefined;
   /** Injected for tests. A knowledge repository is the only thing doctor fetches. */
   readonly fetch?: FetchLike | undefined;
 }
@@ -63,7 +66,18 @@ export interface DoctorFinding {
 
 /** Read-only external checks: credentials resolve, stores reachable. */
 export async function doctor(flags: DoctorFlags): Promise<void> {
-  const runtime = await openRuntime(flags, { fetch: flags.fetch });
+  // The one check that cannot use a runtime, because it answers for the profiles
+  // that cannot open one. A provider rename left in the config refuses at load,
+  // which takes every command down together — including the rest of this one —
+  // so it is asked first and, with `--fix`, undone. Anything else that refused
+  // is rethrown untouched.
+  let runtime: Runtime;
+  try {
+    runtime = await openRuntime(flags, { fetch: flags.fetch });
+  } catch (refusal) {
+    if (await migratedRenamedProviders(flags, refusal)) return;
+    throw refusal;
+  }
 
   const checks: string[] = [];
   const warnings: DoctorFinding[] = [];

package/src/cli/commands/operate/migrate.ts

@@ -0,0 +1,100 @@
+import { ConfigError, resolveSelection } from '#profile';
+import { ConfigDocument } from '../../config-edit.ts';
+import { migrateRenamedProviders, pendingRenames, shapeOf } from '../../config-migrate.ts';
+import { emit, fail, ok, print, style, warn } from '../../output.ts';
+import { openSecretStoreFor, type GlobalFlags } from '../../runtime.ts';
+
+/**
+ * `doctor` answering for a profile whose config will not load.
+ *
+ * Here rather than in `inspect.ts` because it is the opposite of everything
+ * there: every other check reads a runtime, and this one runs precisely when no
+ * runtime can be opened. Keeping it beside them would have put a second
+ * `try`/`catch` shape around a file that is otherwise one long list of findings.
+ *
+ * Why `doctor` at all, and not a command of its own: it is already the command
+ * whose job is to say what is wrong and name the fix, and a `lanes link migrate`
+ * would be a command an operator has to know exists before their config breaks.
+ * `doctor` is what someone runs when something is broken, so it has to be the
+ * one that works when everything else refuses.
+ */
+
+export interface RenameFlags extends GlobalFlags {
+  readonly json?: boolean | undefined;
+  /** Apply the migration rather than reporting it. */
+  readonly fix?: boolean | undefined;
+}
+
+/**
+ * Whether a refusal to load was a provider rename, and — with `--fix` — undo it.
+ *
+ * Returns false for anything else, so the caller rethrows the original error
+ * rather than replacing a real config problem with "nothing to migrate".
+ *
+ * The selection is resolved again here, and cheaply: `resolveSelection` reads
+ * the workspace and the flag, never a profile's config, which is what makes it
+ * usable on the path where the config is the thing that is broken.
+ */
+export async function migratedRenamedProviders(
+  flags: RenameFlags,
+  refusal: unknown,
+): Promise<boolean> {
+  if (!(refusal instanceof ConfigError)) return false;
+
+  const selection = await resolveSelection({ profileFlag: flags.profile });
+  const document = await ConfigDocument.open(selection.workspaceRoot, selection.profile);
+  if (pendingRenames(document).length === 0) return false;
+
+  // Shape-only, because the check this document fails runs after the schema.
+  // Throws when it is malformed beyond a rename, which is a better sentence
+  // than the referential one it would otherwise be reported under.
+  const config = shapeOf(document);
+  const target = flags.target ?? '';
+  const credentials = await openSecretStoreFor(config, selection.workspaceRoot, target);
+
+  const migration = await migrateRenamedProviders(document, credentials, {
+    apply: flags.fix === true,
+  });
+
+  const applied = flags.fix === true && migration.changes.length > 0;
+
+  // A report is a problem, because the profile is still unusable. A repair that
+  // left nothing behind is not, and one that could not decide every row is —
+  // those rows are exactly as broken as before.
+  if (!applied || migration.blocked.length > 0) process.exitCode = 1;
+
+  await emit(
+    flags.json,
+    {
+      ok: applied && migration.blocked.length === 0,
+      profile: selection.profile,
+      target,
+      applied,
+      rows: migration.rows,
+      changes: migration.changes,
+      blocked: migration.blocked,
+    },
+    () => {
+      print(`profile ${style.bold(selection.profile)}  target ${style.bold(target)}`);
+      print();
+
+      if (applied) {
+        print(ok(`${document.path} no longer names a provider that has moved`));
+      } else {
+        print(fail(`${document.path} names a provider that has moved, so nothing can load it`));
+      }
+
+      for (const change of migration.changes) {
+        print(`      ${style.dim(applied ? change : `would ${change}`)}`);
+      }
+      for (const problem of migration.blocked) print(warn(problem));
+
+      if (!applied && migration.changes.length > 0) {
+        print();
+        print(`Run the same command with ${style.bold('--fix')} to apply it.`);
+      }
+    },
+  );
+
+  return true;
+}

package/src/cli/config-migrate.ts

@@ -0,0 +1,251 @@
+import { ConfigError, renamedProviderFor, validateConfigShape, type Config } from '#profile';
+import type { SecretStore } from '#secrets';
+import { ConfigDocument } from './config-edit.ts';
+
+/**
+ * Applying a provider rename to a profile that still names the old id.
+ *
+ * Apart from `config-repair.ts` because the subject differs, not because either
+ * file grew: that one gives a profile a surface it never had, reading a config
+ * that loads. This one runs when the config does *not* load, which is the whole
+ * difficulty. `renamedProviderFor` refuses a stale row at load (`#profile`), and
+ * every command opens the config — so one row left saying `provider: tasks`
+ * takes `status`, `start`, `plan` and `doctor` down together, for a state an
+ * upgrade put the operator in without asking. The only way back was to
+ * hand-edit YAML, which is not a thing a CLI should require to undo its own
+ * release.
+ *
+ * So this reads raw YAML through `ConfigDocument` and edits it comment-first,
+ * exactly as the other repairs do.
+ *
+ * **It never guesses.** A `tasks` row labelled anything but `Tasks` is either a
+ * pre-rename Google Tasks connection or a hand-edited built-in one, and the
+ * refusal names both because the two fixes are opposite. What decides here is
+ * evidence rather than a heuristic: a stored credential at `tasks/<id>` can only
+ * belong to the OAuth connection, because the built-in holds none and never
+ * has. With no credential this reports both readings and changes nothing.
+ */
+
+/** One row that has to move. */
+export interface PendingRename {
+  readonly index: number;
+  readonly from: string;
+  readonly to: string;
+  readonly id: string;
+  readonly account: string;
+  /** `provider.id`, as the rest of the CLI addresses a connection. */
+  readonly key: string;
+}
+
+export interface RenameMigration {
+  /** Every stale row found, whether or not it could be moved. */
+  readonly rows: readonly PendingRename[];
+  /** What was done, or would be — spelled for display. */
+  readonly changes: readonly string[];
+  /** What was left alone, each with why. */
+  readonly blocked: readonly string[];
+}
+
+/**
+ * The rows a document still spells the old way.
+ *
+ * Raw YAML, so nothing here has been through a schema — this runs on a file the
+ * loader has already refused, and every field is whatever was typed. A row
+ * missing `provider` or `account` is not a rename, it is a shape error, and
+ * reporting that is `validateConfig`'s job rather than this one's.
+ */
+export function pendingRenames(document: ConfigDocument): PendingRename[] {
+  const pending: PendingRename[] = [];
+
+  connectionsOf(document).forEach((row, index) => {
+    const { provider, id, account } = (row ?? {}) as {
+      provider?: unknown;
+      id?: unknown;
+      account?: unknown;
+    };
+    if (typeof provider !== 'string' || typeof id !== 'string' || typeof account !== 'string') {
+      return;
+    }
+
+    const moved = renamedProviderFor({ provider, account });
+    if (moved) {
+      pending.push({ index, from: provider, to: moved.to, id, account, key: `${provider}.${id}` });
+    }
+  });
+
+  return pending;
+}
+
+/**
+ * Report what a profile is owed, and optionally apply it.
+ *
+ * Takes the credential store rather than opening one, so the caller decides
+ * whether the target is reachable and a test needs no adapter. `apply: false` is
+ * what `doctor` prints without `--fix`: the same reading against the same
+ * evidence, with nothing written.
+ *
+ * The credential is copied *before* the config is saved, and the old reference
+ * deleted only after. A crash between the two leaves a second copy of a secret
+ * the operator already holds — recoverable, and invisible. The other order
+ * leaves a config naming a credential that is gone, which presents as a
+ * connection that lost its authorisation for no reason anyone can see.
+ */
+export async function migrateRenamedProviders(
+  document: ConfigDocument,
+  credentials: SecretStore,
+  options: { apply: boolean },
+): Promise<RenameMigration> {
+  const rows = pendingRenames(document);
+  if (rows.length === 0) return { rows, changes: [], blocked: [] };
+
+  const changes: string[] = [];
+  const blocked: string[] = [];
+  const accepted: PendingRename[] = [];
+
+  for (const row of rows) {
+    if (await credentials.has(`${row.from}/${row.id}`)) {
+      accepted.push(row);
+      changes.push(`connections[${row.index}]: ${row.from} → ${row.to} (${row.key})`);
+      changes.push(`credential: ${row.from}/${row.id} → ${row.to}/${row.id}`);
+    } else {
+      blocked.push(
+        `${row.key} has no stored credential, so nothing proves it was ${row.to} rather than a ` +
+          `built-in row labelled "${row.account}" by hand — set its provider or its account in ` +
+          `the file itself`,
+      );
+    }
+  }
+
+  // The policy rules second, because whether one can move depends on what is
+  // left declaring the old id once the rows above have.
+  for (const [from, to] of new Map(accepted.map((row) => [row.from, row.to]))) {
+    const policy = renamePolicyRules(document, { from, to }, {
+      stillDeclared: keepsDeclaring(document, from, accepted),
+      apply: options.apply,
+    });
+    changes.push(...policy.changes);
+    blocked.push(...policy.blocked);
+  }
+
+  if (!options.apply || accepted.length === 0) return { rows, changes, blocked };
+
+  for (const row of accepted) {
+    document.setIn(['connections', row.index, 'provider'], row.to);
+
+    const value = await credentials.get(`${row.from}/${row.id}`);
+    if (value !== null) await credentials.set(`${row.to}/${row.id}`, value);
+  }
+
+  // Throws unless the result is a config that loads, which is the assertion
+  // worth having here — the whole premise was that it did not.
+  await document.save();
+
+  for (const row of accepted) await credentials.delete(`${row.from}/${row.id}`);
+
+  return { rows, changes, blocked };
+}
+
+/**
+ * Rewrite the policy rules that named the old id, where that is unambiguous.
+ *
+ * A rule names a provider and never an account, so `tasks.*` written for Google
+ * Tasks has to follow the rename or the migrated connection is granted nothing
+ * — `allowedConnections` drops a provider no rule covers before policy is even
+ * consulted, so the repair would land a row that serves exactly as little as
+ * the broken one did.
+ *
+ * But a profile declaring *both* — a Google Tasks row and the built-in — has one
+ * rule serving two providers, and moving it would silently revoke the one that
+ * kept its name. That profile keeps its rule and is told to add the second,
+ * which is a sentence rather than a guess at which was meant.
+ *
+ * Both lists. A `deny` written to switch Google Tasks off means it as firmly as
+ * an allow means it on, and leaving it behind would re-enable something the
+ * operator turned off.
+ */
+function renamePolicyRules(
+  document: ConfigDocument,
+  provider: { from: string; to: string },
+  options: { stillDeclared: boolean; apply: boolean },
+): { changes: string[]; blocked: string[] } {
+  const changes: string[] = [];
+  const blocked: string[] = [];
+
+  for (const field of ['allow', 'deny'] as const) {
+    const rules = document.getIn(['policy', field]) as { items?: unknown[] } | null;
+
+    (rules?.items ?? []).forEach((_item, index) => {
+      // Either spelling: a bare pattern, or `{ capability, expires_at }`. The
+      // path to it differs; the decision does not.
+      const bare = document.getIn(['policy', field, index]);
+      const path =
+        typeof bare === 'string'
+          ? (['policy', field, index] as const)
+          : (['policy', field, index, 'capability'] as const);
+
+      const capability = typeof bare === 'string' ? bare : document.getIn(path);
+      if (typeof capability !== 'string') return;
+
+      const [named, ...rest] = capability.split('.');
+      if (named !== provider.from) return;
+
+      const moved = [provider.to, ...rest].join('.');
+
+      if (options.stillDeclared) {
+        blocked.push(
+          `policy.${field} keeps "${capability}" — this profile still declares a ` +
+            `"${provider.from}" connection, so add "${moved}" rather than moving it`,
+        );
+        return;
+      }
+
+      if (options.apply) document.setIn(path, moved);
+      changes.push(`policy.${field}: ${capability} → ${moved}`);
+    });
+  }
+
+  return { changes, blocked };
+}
+
+/**
+ * Whether a row naming the old provider survives the migration.
+ *
+ * Computed against the accepted set rather than by re-reading the document,
+ * because the same answer has to hold on a report-only run, where nothing has
+ * been rewritten yet.
+ */
+function keepsDeclaring(
+  document: ConfigDocument,
+  provider: string,
+  accepted: readonly PendingRename[],
+): boolean {
+  return connectionsOf(document).some(
+    (row, index) =>
+      (row as { provider?: unknown } | null)?.provider === provider &&
+      !accepted.some((moved) => moved.index === index),
+  );
+}
+
+function connectionsOf(document: ConfigDocument): unknown[] {
+  const config = document.toJSON() as { connections?: unknown } | null;
+  return Array.isArray(config?.connections) ? config.connections : [];
+}
+
+/**
+ * The config of a document the loader has refused, shape-checked only.
+ *
+ * `openSecretStoreFor` needs a `Config` to name the target's adapter, and the
+ * document in hand fails the check that runs *after* the schema — so this is
+ * that parse without it. A document failing the schema itself is beyond this
+ * repair, and says so rather than reporting a rename it cannot see.
+ */
+export function shapeOf(document: ConfigDocument): Config {
+  try {
+    return validateConfigShape(document.toJSON(), document.path);
+  } catch (error) {
+    throw new ConfigError(
+      `${document.path} is malformed beyond a provider rename, so there is nothing to migrate.\n` +
+        `  ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/cli/main.ts

@@ -277,7 +277,7 @@ export async function run(argv: readonly string[]): Promise<void> {
     case 'plan':
       return plan(global);
     case 'doctor':
-      return doctor({ ...global, json });
+      return doctor({ ...global, json, fix: flags['fix'] === true });
     case 'status':
       return status({ ...global, json });
     case 'outputs':

package/src/cli/selection.ts

@@ -320,6 +320,10 @@ const ACCEPTS: Record<string, readonly string[]> = {
   // the list that decides whether it may be typed.
   'profile remove': ['dry-run', 'yes', 'target'],
   disconnect: ['yes', 'keep-credential'],
+  // The one repair `doctor` can apply rather than only name. Narrow on purpose:
+  // it undoes a provider rename this project shipped, and every other finding
+  // there is something only the operator can decide.
+  doctor: ['fix'],
   relabel: [],
   'target list': ['urls', 'target'],
   'target show': ['target'],

package/src/cli/usage.ts

@@ -127,6 +127,8 @@ ${style.bold('Deploying')}
 ${style.bold('Inspection')}
   ${PROGRAM} check                      static validation, no external calls
   ${PROGRAM} doctor [--json]            credentials resolve, stores reachable
+  ${PROGRAM} doctor --fix               apply a repair it can make itself, such as
+                                        a provider this project renamed under you
   ${PROGRAM} tools [--json]             what the endpoint advertises to a client
   ${PROGRAM} plan                       what reconcile would change
   ${PROGRAM} audit tail [--limit N] [--denied-only] [--format md]

package/src/profile/index.ts

@@ -38,10 +38,14 @@ export {
 
 export {
   ConfigError,
+  RENAMED_PROVIDERS,
   loadConfigFile,
   parseConfig,
+  renamedProviderFor,
   validateConfig,
+  validateConfigShape,
   type LoadedConfig,
+  type ProviderRename,
 } from './load.ts';
 
 export {

package/src/profile/load.ts

@@ -40,6 +40,25 @@ export interface LoadedConfig {
  *  4. Referential integrity, which needs a well-formed document to check.
  */
 export function validateConfig(raw: unknown, source = '<config>'): Config {
+  const config = validateConfigShape(raw, source);
+  assertReferentialIntegrity(config, source);
+  return config;
+}
+
+/**
+ * The first three steps, without the fourth.
+ *
+ * Only one caller, and it is the repair: `migrateRenamedProviders` has to open
+ * the credential store of a config that referential integrity has just refused,
+ * because whether a credential is stored is the evidence deciding which of two
+ * readings a row gets. A shape-valid document is enough to name a target's
+ * adapter, and nothing here trusts the part that failed.
+ *
+ * Not exported as a way to *load* a config. Everything that acts on one goes
+ * through `validateConfig`, and the split exists so that the one command whose
+ * job is to fix a refusal is not blocked by it.
+ */
+export function validateConfigShape(raw: unknown, source = '<config>'): Config {
   if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new ConfigError(`${source}: expected a YAML mapping at the top level`);
   }
@@ -59,7 +78,6 @@ export function validateConfig(raw: unknown, source = '<config>'): Config {
     throw new ConfigError(`${source}:\n${formatZodIssues(parsed.error)}`);
   }
 
-  assertReferentialIntegrity(parsed.data, source);
   return parsed.data;
 }
 
@@ -138,15 +156,85 @@ function formatZodIssues(error: z.ZodError): string {
  * are, and keying on `id !== 'main'` would refuse a valid profile forever to
  * catch a one-release migration. Labelling both `Tasks` is consistent with what
  * the accountless providers already do — every memory connection is `Memory`.
+ *
+ * **The refusal names a command, because it is a refusal at load.** Every
+ * command opens the config, so this one takes `status`, `start` and `doctor`
+ * down together and leaves hand-editing YAML as the only way back — for a state
+ * an upgrade put the operator in, without asking. `doctor --fix` is that way
+ * back, and it is named here because this is the only place anyone sees.
  */
-function renamedProvider(connection: { provider: string; account: string }): string | null {
-  if (connection.provider !== 'tasks' || connection.account === 'Tasks') return null;
+export interface ProviderRename {
+  /** What a row naming the old id should say instead. */
+  readonly to: string;
+  /** The account label that means this row is the built-in, not a vendor one. */
+  readonly keeps: string;
+  /** What the plain noun now names, for the sentence below. */
+  readonly becomes: string;
+  /** What it used to name. */
+  readonly was: string;
+  /** The built-in, in the operator's words. */
+  readonly noun: string;
+}
+
+/**
+ * Provider ids that have moved, and everything two places need to agree on.
+ *
+ * `renamedProviderFor` refuses a row still naming the old id; `#cli`'s
+ * `migrateRenamedProviders` rewrites one. A rename landing in one and not the
+ * other is a refusal with no fix, or a fix nothing asks for — which is why the
+ * pair reads from one table rather than each knowing the rename itself.
+ *
+ * `keeps` is the single spelling `newProfileTemplate` and `ensureReservedConnection`
+ * write for the built-in's row. Keep it in step with `RESERVED_SURFACES` there.
+ */
+export const RENAMED_PROVIDERS: Readonly<Record<string, ProviderRename>> = {
+  tasks: {
+    to: 'google_tasks',
+    keeps: 'Tasks',
+    becomes: 'the built-in task list',
+    was: 'Google Tasks',
+    noun: 'task list',
+  },
+};
+
+/**
+ * The repair, spelled with the selection it will refuse without.
+ *
+ * Both flags come off the document being validated rather than off the command
+ * that is running: nothing has resolved anything yet, and the profile is written
+ * in the file. A profile declaring one target names it; one declaring several
+ * cannot be guessed at, and a placeholder is more honest than picking.
+ */
+function repairCommand(config: Config): string {
+  const targets = Object.keys(config.targets);
+  const target = targets.length === 1 ? targets[0] : `<${targets.join('|') || 'target'}>`;
+  return `lanes link doctor --fix --profile ${config.instance.profile} --target ${target}`;
+}
+
+/** The rename a row is owed, or `null` when it is owed none. */
+export function renamedProviderFor(connection: {
+  provider: string;
+  account: string;
+}): ProviderRename | null {
+  const moved = RENAMED_PROVIDERS[connection.provider];
+  if (!moved || connection.account === moved.keeps) return null;
+  return moved;
+}
+
+function renamedProvider(
+  connection: { provider: string; account: string },
+  repair: string,
+): string | null {
+  const moved = renamedProviderFor(connection);
+  if (!moved) return null;
 
   return (
-    `"tasks" is now the built-in task list, and this row is labelled ` +
-    `"${connection.account}" rather than "Tasks".\n` +
-    '  If it was Google Tasks: set provider to google_tasks here, and rename any "tasks.*" policy rule.\n' +
-    '  If it is your own task list: set account to Tasks.'
+    `"${connection.provider}" is now ${moved.becomes}, and this row is labelled ` +
+    `"${connection.account}" rather than "${moved.keeps}".\n` +
+    `  If it was ${moved.was}: set provider to ${moved.to} here, and rename any ` +
+    `"${connection.provider}.*" policy rule.\n` +
+    `  If it is your own ${moved.noun}: set account to ${moved.keeps}.\n` +
+    `  ${repair} applies the first, where a stored credential proves it.`
   );
 }
 
@@ -186,7 +274,7 @@ function assertReferentialIntegrity(config: Config, source: string): void {
     }
     connectionKeys.add(key);
 
-    const renamed = renamedProvider(connection);
+    const renamed = renamedProvider(connection, repairCommand(config));
     if (renamed) problems.push(`connections[${index}]: ${renamed}`);
   });