@lanes-sh/link 0.2.2 → 0.3.1

package/src/cli/config-edit.ts

@@ -94,6 +94,24 @@ export class ConfigDocument {
     this.#expand(path.slice(0, -1));
   }
 
+  /**
+   * Remove a key, leaving everything around it untouched.
+   *
+   * The counterpart to `setIn`, and it exists because a block a command wrote
+   * has to be a block that command can take back. `lanes link knowledge use
+   * local` moves memory and skills off a repository, and a `knowledge:` block
+   * left behind afterwards would point the profile at the repository it just
+   * stopped using — a config that is not merely untidy but wrong.
+   *
+   * Absent is not an error: removing what is not there is what the caller
+   * wanted, and a profile whose targets do not all have the key is the ordinary
+   * case rather than a broken one.
+   */
+  removeIn(path: readonly (string | number)[]): void {
+    if (this.#document.getIn(path as (string | number)[]) === undefined) return;
+    this.#document.deleteIn(path as (string | number)[]);
+  }
+
   /**
    * Append to a sequence, creating it if absent.
    *
@@ -121,6 +139,22 @@ export class ConfigDocument {
     this.#expand(path);
   }
 
+  /**
+   * Drop one item out of a sequence, by position.
+   *
+   * By index rather than by value because the items this is used on are
+   * mappings: matching one by value would mean deciding which fields count as
+   * its identity, and the caller has already decided that by finding it. The
+   * index is therefore the caller's to compute against the *validated* config,
+   * whose order this file preserves.
+   *
+   * `save` re-validates, so removing an item that something else references
+   * fails there rather than landing a config that no longer loads.
+   */
+  removeFrom(path: readonly (string | number)[], index: number): void {
+    this.#document.deleteIn([...path, index] as (string | number)[]);
+  }
+
   /**
    * Force a collection we just grew onto multiple lines.
    *
@@ -176,138 +210,6 @@ export class ConfigDocument {
   }
 }
 
-/** The reserved provider id the setup surface registers under. */
-const SETUP_PROVIDER_ID = 'setup';
-
-/**
- * What a repair did, split by what a caller does with each half.
- *
- * `connect` reports config edits under `changes` and policy under `granted`,
- * and both are serialised verbatim by `--json` — so an audit asking what a
- * command widened reads only the second, and one blended list of sentences
- * filed the grant as an edit and left prose in a field meant for matching.
- */
-export interface SetupRepair {
-  /** Config edits made, spelled for display. Empty when none were needed. */
-  readonly changes: readonly string[];
-  /** Allow rules added — patterns, not prose, so a caller can act on them. */
-  readonly granted: readonly string[];
-}
-
-/**
- * Give a profile the `setup` surface if it does not already have it.
- *
- * A profile written before the surface existed has neither the connection row
- * nor the allow rule, and the failure is silent in the worst way:
- * `allowedConnections` returns nothing for a provider with no connection row
- * *before* it consults policy, so `setup_overview` and `setup_provider` are
- * simply absent from `tools/list` with nothing saying why. An agent asked what
- * is connected then has nothing to read and invents a command — which is the
- * bug this exists to close, not a hypothetical.
- *
- * Both halves or neither: a connection row without `setup.*` is as inert as the
- * rule without the row, so adding one alone would look like a fix and change
- * nothing.
- *
- * CLI-side by construction. ADR-007 keeps configuration mutation off the served
- * surface, and a deployed revision holds `objectViewer` on `profiles/`
- * (ADR-023) so it could not write this even if the code let it.
- */
-export function ensureSetupConnection(document: ConfigDocument): SetupRepair {
-  // Raw YAML, so nothing here has been through a schema: this runs over sibling
-  // profiles that were never validated, and every field is whatever was typed.
-  const config = document.toJSON() as {
-    connections?: unknown;
-    policy?: { allow?: unknown; deny?: unknown };
-  } | null;
-
-  const rule = `${SETUP_PROVIDER_ID}.*`;
-  const covers = (pattern: string): boolean => pattern === '*' || pattern === rule;
-
-  // Denied on purpose, and a deny beats an allow — so writing the rule would
-  // widen nothing while announcing that an agent "can now see what is connected
-  // here", which would be false. Deleting the two lines no longer removes the
-  // surface, because the next `connect` or `deploy` puts them back; a deny is
-  // the way it stays off, so it is the one thing this must not undo.
-  //
-  // Only a rule covering the whole surface counts. `deny: [setup.provider]` is
-  // an operator narrowing it, not switching it off, and that narrowing survives
-  // the repair untouched — which is the point of denying one capability.
-  if (patternsIn(config?.policy?.deny).some(covers)) return { changes: [], granted: [] };
-
-  const changes: string[] = [];
-  const granted: string[] = [];
-
-  const connections = Array.isArray(config?.connections) ? config.connections : [];
-  const isSetup = (row: unknown): boolean =>
-    (row as { provider?: unknown } | null)?.provider === SETUP_PROVIDER_ID;
-
-  if (!connections.some(isSetup)) {
-    // Inline, and `main` for the id, so a repaired profile is spelled exactly
-    // like `newProfileTemplate` writes a fresh one. Two spellings of one row is
-    // how a template and its repair drift apart.
-    document.addTo(
-      ['connections'],
-      { id: 'main', provider: SETUP_PROVIDER_ID, account: 'Setup' },
-      { inline: true },
-    );
-    changes.push(`connections += ${SETUP_PROVIDER_ID}.main`);
-  }
-
-  // `*` already covers it. Re-stating the rule under a blanket allow would be
-  // noise in the file and a diff the operator did not ask for.
-  if (!patternsIn(config?.policy?.allow).some(covers)) {
-    document.addTo(['policy', 'allow'], rule, { inline: true });
-    granted.push(rule);
-  }
-
-  return { changes, granted };
-}
-
-/** Whether a repair did anything, without a caller adding up two lists. */
-export function repaired(repair: SetupRepair): boolean {
-  return repair.changes.length > 0 || repair.granted.length > 0;
-}
-
-/** The repair as display lines, in the order the two halves are applied. */
-export function repairLines(repair: SetupRepair): string[] {
-  return [...repair.changes, ...repair.granted.map((rule) => `policy.allow += ${rule}`)];
-}
-
-/**
- * The patterns a raw policy list puts *in force*, in either spelling.
- *
- * `policyRuleSchema` takes a bare pattern or `{ capability, expires_at }` and
- * both parse to the same thing, so reading only the string form would re-add a
- * rule the operator had already written with an expiry. Anything that is
- * neither is dropped rather than guessed at: this reads unvalidated YAML, and a
- * malformed rule is for `validateConfig` to report, not for this to interpret.
- *
- * **Expiry is part of the reading.** `evaluate` holds a rule to
- * `expiresAt === undefined || expiresAt > now` (`#policy`), so a lapsed rule
- * grants and denies nothing — and reading the capability alone got both
- * directions wrong. A lapsed *allow* read as live, so the repair wrote the row,
- * skipped the rule, and announced success: the inert half-state this exists to
- * prevent. A lapsed *deny* blocked the repair for good and printed nothing,
- * because having nothing to add is how "already had it" looks.
- *
- * An unparseable date reads as lapsed, which is the safe direction — it adds a
- * working rule rather than trusting a broken one, and the `save` that follows
- * hands the malformed value to `validateConfig`, whose job it is to complain.
- */
-function patternsIn(rules: unknown, now = Date.now()): string[] {
-  if (!Array.isArray(rules)) return [];
-
-  return rules
-    .filter((rule) => {
-      const expiry = (rule as { expires_at?: unknown } | null)?.expires_at;
-      return typeof expiry !== 'string' || Date.parse(expiry) > now;
-    })
-    .map((rule) =>
-      typeof rule === 'string' ? rule : (rule as { capability?: unknown } | null)?.capability,
-    )
-    .filter((pattern): pattern is string => typeof pattern === 'string');
-}
 
 /**
  * A fresh profile config.
@@ -315,7 +217,7 @@ function patternsIn(rules: unknown, now = Date.now()): string[] {
  * Written with comments, because this is the file an operator will read first
  * and most of what it needs to say is *why*, not *what*.
  */
-export function newProfileTemplate(profile: string, port: number): string {
+export function newProfileTemplate(profile: string, port: number, targets: string): string {
   return `# Lanes Link profile: ${profile}
 #
 # This file is the source of truth for what exists. It never contains a
@@ -328,17 +230,19 @@ contract: 1
 
 instance:
   profile: ${profile}
-  default_target: local
   port: ${port}
   host: 127.0.0.1
 
-# Adapter selection is per target. Everything below "targets" is
-# target-independent and declared exactly once.
+# Adapter selection is per target, and every command names the one it means:
+#
+#     lanes link status --profile ${profile} --target <name>
+#
+# There is no default. A target is chosen on the command line or not at all,
+# so a flag that goes missing fails here rather than quietly running somewhere
+# else (ADR-037). Everything below "targets" is target-independent and declared
+# exactly once.
 targets:
-  local:
-    credentials: { adapter: file, path: ./data/${profile}/credentials.enc }
-    storage: { adapter: filesystem, path: ./data/${profile} }
-
+${targets}
 # The bearer token for the endpoint this profile serves.
 #
 # "lanes link start" serves every profile in the workspace from one URL, and this
@@ -386,12 +290,17 @@ policy:
 `;
 }
 
-export function newWorkspaceTemplate(defaultProfile?: string): string {
+export function newWorkspaceTemplate(): string {
   return `# Lanes Link workspace
 #
 # A workspace holds one or more profiles, and one endpoint serves all of them:
-# every call names the profile it means. Profiles never share a database or a
-# credential store, so what one holds is invisible to another.
+# every call names the profile it means, with --profile. Profiles never share a
+# database or a credential store, so what one holds is invisible to another.
+#
+# "deploy" adds a "deployments:" list here. It is an index, not configuration —
+# nothing resolves from it. It records where a deployment lives so that losing
+# the target block out of a profile does not lose the service, the bucket, and
+# the credential store along with it. "lanes link sync targets" reads it.
 contract: 1
-${defaultProfile ? `default_profile: ${defaultProfile}\n` : ''}`;
+`;
 }

package/src/cli/config-repair.ts

@@ -0,0 +1,186 @@
+import type { ConfigDocument } from './config-edit.ts';
+
+/**
+ * Giving a profile a reserved provider it is missing, without undoing a choice.
+ *
+ * Its own file, apart from `ConfigDocument`, because there are now two callers
+ * of the same repair and generalising it in place would have pushed
+ * `config-edit.ts` past the file-size budget. The split is along the seam that
+ * was already there: that file knows how to *edit* YAML safely, and this one
+ * knows what a reserved provider needs to be reachable at all.
+ *
+ * Two providers hold no account and are therefore invisible without a
+ * connection row nobody would think to write: `setup`, which describes what is
+ * connected, and `identity`, which says who the owner is. Both are repaired the
+ * same way and the rules below are subtle enough that a second copy would drift
+ * — which is the whole reason this is one function taking a provider id rather
+ * than two that look alike.
+ */
+
+/** The reserved provider ids that hold no account, and the label each row carries. */
+const RESERVED_SURFACES = {
+  setup: 'Setup',
+  identity: 'Identity',
+} as const;
+
+type ReservedSurface = keyof typeof RESERVED_SURFACES;
+
+/**
+ * What a repair did, split by what a caller does with each half.
+ *
+ * `connect` reports config edits under `changes` and policy under `granted`,
+ * and both are serialised verbatim by `--json` — so an audit asking what a
+ * command widened reads only the second, and one blended list of sentences
+ * filed the grant as an edit and left prose in a field meant for matching.
+ */
+export interface SurfaceRepair {
+  /** Config edits made, spelled for display. Empty when none were needed. */
+  readonly changes: readonly string[];
+  /** Allow rules added — patterns, not prose, so a caller can act on them. */
+  readonly granted: readonly string[];
+}
+
+/**
+ * Give a profile one of those surfaces if it does not already have it.
+ *
+ * A profile that never had the surface has neither the connection row nor the
+ * allow rule, and the failure is silent in the worst way: `allowedConnections`
+ * returns nothing for a provider with no connection row *before* it consults
+ * policy, so the tools are simply absent from `tools/list` with nothing saying
+ * why. It is not a hypothetical in either direction — asked what was connected,
+ * an agent with no `setup` surface invented a command; and an `identity` block
+ * written without the row is a file saying exactly what its owner meant to an
+ * agent that cannot see a word of it.
+ *
+ * Both halves or neither: a connection row without the matching `<provider>.*`
+ * rule is as inert as the rule without the row, so adding one alone would look
+ * like a fix and change nothing.
+ *
+ * CLI-side by construction. ADR-007 keeps configuration mutation off the served
+ * surface, and a deployed revision holds `objectViewer` on `profiles/`
+ * (ADR-023) so it could not write this even if the code let it.
+ */
+export function ensureReservedConnection(
+  document: ConfigDocument,
+  provider: ReservedSurface,
+): SurfaceRepair {
+  // Raw YAML, so nothing here has been through a schema: this runs over sibling
+  // profiles that were never validated, and every field is whatever was typed.
+  const config = document.toJSON() as {
+    connections?: unknown;
+    policy?: { allow?: unknown; deny?: unknown };
+  } | null;
+
+  const rule = `${provider}.*`;
+  const covers = (pattern: string): boolean => pattern === '*' || pattern === rule;
+
+  // Denied on purpose, and a deny beats an allow — so writing the rule would
+  // widen nothing while announcing that an agent can now read the surface,
+  // which would be false. For `setup`, deleting the two lines no longer removes
+  // it either, because the next `connect` or `deploy` puts them back; a deny is
+  // the way it stays off, so it is the one thing this must not undo. The same
+  // holds for `identity`, where the next `identity add` is what would put them
+  // back.
+  //
+  // Only a rule covering the whole surface counts. `deny: [setup.provider]` is
+  // an operator narrowing it, not switching it off, and that narrowing survives
+  // the repair untouched — which is the point of denying one capability.
+  if (patternsIn(config?.policy?.deny).some(covers)) return { changes: [], granted: [] };
+
+  const changes: string[] = [];
+  const granted: string[] = [];
+
+  const connections = Array.isArray(config?.connections) ? config.connections : [];
+  const declared = (row: unknown): boolean =>
+    (row as { provider?: unknown } | null)?.provider === provider;
+
+  if (!connections.some(declared)) {
+    // Inline, and `main` for the id, so a repaired profile is spelled exactly
+    // like `newProfileTemplate` writes a fresh one. Two spellings of one row is
+    // how a template and its repair drift apart.
+    document.addTo(
+      ['connections'],
+      { id: 'main', provider, account: RESERVED_SURFACES[provider] },
+      { inline: true },
+    );
+    changes.push(`connections += ${provider}.main`);
+  }
+
+  // `*` already covers it. Re-stating the rule under a blanket allow would be
+  // noise in the file and a diff the operator did not ask for.
+  if (!patternsIn(config?.policy?.allow).some(covers)) {
+    document.addTo(['policy', 'allow'], rule, { inline: true });
+    granted.push(rule);
+  }
+
+  return { changes, granted };
+}
+
+/** Whether a repair did anything, without a caller adding up two lists. */
+export function repaired(repair: SurfaceRepair): boolean {
+  return repair.changes.length > 0 || repair.granted.length > 0;
+}
+
+/** The repair as display lines, in the order the two halves are applied. */
+export function repairLines(repair: SurfaceRepair): string[] {
+  return [...repair.changes, ...repair.granted.map((rule) => `policy.allow += ${rule}`)];
+}
+
+/**
+ * The patterns a raw policy list puts *in force*, in either spelling.
+ *
+ * `policyRuleSchema` takes a bare pattern or `{ capability, expires_at }` and
+ * both parse to the same thing, so reading only the string form would re-add a
+ * rule the operator had already written with an expiry. Anything that is
+ * neither is dropped rather than guessed at: this reads unvalidated YAML, and a
+ * malformed rule is for `validateConfig` to report, not for this to interpret.
+ *
+ * **Expiry is part of the reading.** `evaluate` holds a rule to
+ * `expiresAt === undefined || expiresAt > now` (`#policy`), so a lapsed rule
+ * grants and denies nothing — and reading the capability alone got both
+ * directions wrong. A lapsed *allow* read as live, so the repair wrote the row,
+ * skipped the rule, and announced success: the inert half-state this exists to
+ * prevent. A lapsed *deny* blocked the repair for good and printed nothing,
+ * because having nothing to add is how "already had it" looks.
+ *
+ * An unparseable date reads as lapsed, which is the safe direction — it adds a
+ * working rule rather than trusting a broken one, and the `save` that follows
+ * hands the malformed value to `validateConfig`, whose job it is to complain.
+ */
+function patternsIn(rules: unknown, now = Date.now()): string[] {
+  if (!Array.isArray(rules)) return [];
+
+  return rules
+    .filter((rule) => {
+      const expiry = (rule as { expires_at?: unknown } | null)?.expires_at;
+      return typeof expiry !== 'string' || Date.parse(expiry) > now;
+    })
+    .map((rule) =>
+      typeof rule === 'string' ? rule : (rule as { capability?: unknown } | null)?.capability,
+    )
+    .filter((pattern): pattern is string => typeof pattern === 'string');
+}
+
+/**
+ * The `setup` surface, which every profile is expected to have.
+ *
+ * A named wrapper rather than a call site passing `'setup'`, because three
+ * callers say it and reading `ensureReservedConnection(document, 'setup')` at
+ * each of them says less than the name did.
+ */
+export function ensureSetupConnection(document: ConfigDocument): SurfaceRepair {
+  return ensureReservedConnection(document, 'setup');
+}
+
+/**
+ * The `identity` surface, which only a profile that declares an identity gets.
+ *
+ * Unlike `setup`, this is *not* repaired by `connect` or `deploy` — a profile
+ * with no identity block has nothing for the surface to report, and registering
+ * a tool that answers "nothing declared" on every fresh install would spend a
+ * paragraph of the instructions budget to say so. `identity add` is the only
+ * caller, so the grant arrives exactly when there is something behind it.
+ */
+export function ensureIdentityConnection(document: ConfigDocument): SurfaceRepair {
+  return ensureReservedConnection(document, 'identity');
+}