@lanes-sh/link 0.5.4 → 0.6.1

package/src/cli/commands/target.ts

@@ -1,10 +1,12 @@
 import { describeKnowledge } from '#deployments/knowledge.ts';
 import {
-  loadProfileConfig,
-  resolveSelection,
-  undeclaredTarget,
-  type Config,
-  type ProfileSelection,
+  isPointer,
+  listProfiles,
+  notInRegistry,
+  openTarget,
+  readRegistry,
+  resolveWorkspaceRoot,
+  type WorkspaceTarget,
 } from '#profile';
 import { ConfigError } from '#profile';
 import { deployedUrl, deploymentIdentity, type DeploymentIdentity } from '../endpoint-url.ts';
@@ -13,18 +15,23 @@ import { announce, emit, heading, ok, print, style, table, waiting, warn } from
 import type { GlobalFlags } from '../runtime.ts';
 
 /**
- * `lanes link target` — the adapter sets a profile declares, and which one is in play.
+ * `lanes link target` — the targets this workspace knows, and where each lives.
  *
- * A target names *where a profile runs*: a credential store and a blob store,
- * and optionally a deployment. Connections, providers, policy and limits are
- * declared once and apply to every target, so changing one changes where the
- * bytes go and nothing above them.
+ * A target names *a workspace*: a credential store, a blob store, optionally a
+ * deployment, and the profiles that live in it. Under ADR-052 it is declared
+ * once, by the workspace that is it — not once per profile, which is what let
+ * two profiles disagree about whether a running deployment existed.
  *
- * Two answers are worth telling apart and this is the only place that does.
- * `instance.default_target` is what commands run against when nobody says, and
- * it lives in the profile. `LANES_LINK_TARGET` is what *this shell* says, and it
- * wins. When they disagree — the case that sends someone hunting a bug — `list`
- * marks both and names the variable.
+ * So this command no longer takes `--profile`. It never really wanted one: the
+ * question is "what can I pass to --target", and that had the same answer for
+ * every profile in all but the broken cases.
+ *
+ * **`list` does not follow pointers.** A registry entry either declares its
+ * adapters here or names the workspace that does, and following the second kind
+ * is a network read per entry. `list` prints what the registry says, so it stays
+ * instant and works offline; `show` follows one target and reports what is
+ * really there. That split is why a listing can be trusted when the bucket is
+ * unreachable — which is exactly when someone is running it.
  *
  * Each command is a data function plus a printing wrapper, the split
  * `profile.ts` uses and for the same reason: `--json` wants the facts without
@@ -35,9 +42,18 @@ export interface TargetSummary {
   readonly name: string;
   /** Whether this is the one `--target` named, when it named any. */
   readonly isSelected: boolean;
-  readonly credentials: string;
-  readonly storage: string;
-  readonly vault: string;
+  /**
+   * Where the declaration lives: `null` for one this workspace makes itself,
+   * otherwise the workspace it points at.
+   *
+   * The whole listing hangs off this. A pointer's adapters are not read by
+   * `list`, so every field below it is null for one — which is honest rather
+   * than lossy: they are somewhere else, and `show` is the command that goes.
+   */
+  readonly pointsAt: string | null;
+  readonly credentials: string | null;
+  readonly storage: string | null;
+  readonly vault: string | null;
   /**
    * Where memory and skills are kept, when that is not `storage` above.
    *
@@ -47,7 +63,7 @@ export interface TargetSummary {
    * the log and the state and false of the owner's own notes.
    */
   readonly knowledge: string | null;
-  /** Whether a deployment is declared. Free, and always present. */
+  /** Whether a deployment is declared. Unknown, and false, for a pointer. */
   readonly deployed: boolean;
   readonly deployment: DeploymentIdentity | null;
   /** Only when asked for; absent is "not asked", null is "asked, no answer". */
@@ -56,8 +72,6 @@ export interface TargetSummary {
 
 export interface TargetListing {
   readonly root: string;
-  readonly profile: string;
-  readonly path: string;
   /** What `--target` named, when it named anything. */
   readonly selected: string | null;
   /**
@@ -76,64 +90,79 @@ export interface TargetFlags extends GlobalFlags {
 }
 
 /**
- * The profile, its config, and what it declares — in one pass.
+ * The registry, and what each entry says about itself — in one pass.
  *
  * **Deliberately not `resolveProfile`.** That helper resolves the target the way
  * every other command needs it resolved: by refusing a name that is not
- * declared. Here that is exactly backwards. `LANES_LINK_TARGET=clod` is the
- * state in which every other command has just started failing, and this is the
- * command someone runs to find out why — so it has to survive the condition it
- * exists to diagnose. It resolves the name with `askedTarget` and reports
- * whether it landed on anything, rather than throwing. `readProfiles` in
- * `profile.ts` declines to parse configs for the same reason.
+ * declared. Here that is exactly backwards. `--target clod` is the state in
+ * which every other command has just started failing, and this is the command
+ * someone runs to find out why — so it has to survive the condition it exists to
+ * diagnose. It reports whether the name landed on anything rather than throwing.
+ * `readProfiles` in `profile.ts` declines to parse configs for the same reason.
+ *
+ * It reads no profile at all now. The registry is the answer, and it is one file
+ * (ADR-052).
  */
 async function survey(
   flags: TargetFlags,
   options: { urls?: boolean; env?: Record<string, string | undefined> } = {},
-): Promise<{ selection: ProfileSelection; config: Config; listing: TargetListing }> {
-  const selection = await resolveSelection({
-    ...(flags.profile !== undefined ? { profileFlag: flags.profile } : {}),
-    ...(options.env !== undefined ? { env: options.env } : {}),
-  });
-
-  const { config } = await loadProfileConfig(selection.workspaceRoot, selection.profile);
+): Promise<{ root: string; listing: TargetListing }> {
+  const root = resolveWorkspaceRoot(options.env !== undefined ? { env: options.env } : {});
+  const registry = await readRegistry(root);
 
   const selected = flags.target ?? null;
-  const names = Object.keys(config.targets);
+  const names = Object.keys(registry).sort();
 
   const summaries: TargetSummary[] = names.map((name) => {
-    const declared = config.targets[name]!;
-    return {
-      name,
-      isSelected: name === selected,
-      credentials: declared.credentials.adapter,
-      storage: declared.storage.adapter,
-      vault: declared.vault?.adapter ?? 'file',
-      knowledge: declared.knowledge ? describeKnowledge(declared.knowledge) : null,
-      deployed: declared.deploy !== undefined,
-      deployment: deploymentIdentity(declared.deploy),
-    };
+    const entry = registry[name]!;
+    return summarise(name, entry, name === selected);
   });
 
   return {
-    selection,
-    config,
+    root,
     listing: {
-      root: selection.workspaceRoot,
-      profile: selection.profile,
-      path: selection.profilePath,
+      root,
       selected,
       selectedDeclared: selected === null || names.includes(selected),
       // Asking the platform is opt-in: one `gcloud` subprocess per deployable
-      // target, and the profiles that make this command worth running are
+      // target, and the workspaces that make this command worth running are
       // exactly the ones with several. A discovery command that takes ten
       // seconds and needs a cloud CLI installed is one nobody runs twice —
       // `outputs --target X` is already the command that asks.
-      targets: options.urls === true ? await withUrls(config, summaries) : summaries,
+      targets: options.urls === true ? await withUrls(registry, summaries) : summaries,
     },
   };
 }
 
+/** One entry, rendered without following it. */
+function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): TargetSummary {
+  if (isPointer(entry)) {
+    return {
+      name,
+      isSelected,
+      pointsAt: entry.workspace,
+      credentials: null,
+      storage: null,
+      vault: null,
+      knowledge: null,
+      deployed: false,
+      deployment: null,
+    };
+  }
+
+  return {
+    name,
+    isSelected,
+    pointsAt: null,
+    credentials: entry.credentials?.adapter ?? null,
+    storage: entry.storage?.adapter ?? null,
+    vault: entry.vault?.adapter ?? 'file',
+    knowledge: null,
+    deployed: entry.deploy !== undefined,
+    deployment: deploymentIdentity(entry.deploy),
+  };
+}
+
 /** What `--json` and the tests want, without the rendering. */
 export async function readTargets(
   flags: TargetFlags,
@@ -144,7 +173,7 @@ export async function readTargets(
 
 /** Every deployable target's address, asked for at once rather than in turn. */
 async function withUrls(
-  config: Config,
+  registry: Record<string, WorkspaceTarget>,
   summaries: readonly TargetSummary[],
 ): Promise<TargetSummary[]> {
   return waiting('asking the platform for addresses', () =>
@@ -154,7 +183,7 @@ async function withUrls(
         // Resolves to null immediately for a target with no deployment, and
         // swallows a missing or unauthenticated `gcloud` — neither is a reason
         // for a listing to fail.
-        url: await deployedUrl(config.targets[summary.name]?.deploy),
+        url: await deployedUrl(registry[summary.name]?.deploy),
       })),
     ),
   );
@@ -164,16 +193,23 @@ export async function targetList(flags: TargetFlags): Promise<void> {
   const { listing } = await survey(flags, { urls: flags.urls === true });
 
   return emit(flags.json, listing, () => {
-    print(style.dim(`${listing.profile}  ${listing.path}`));
+    print(style.dim(listing.root));
     print();
 
     table(
       listing.targets.map((target) => [
         `  ${target.isSelected ? style.cyan('→') : ' '}`,
         style.bold(target.name),
-        style.dim(target.credentials),
-        style.dim(target.storage),
-        deploymentCell(target),
+        // A pointer says where it lives instead of what it is made of. Its
+        // adapters are declared in that workspace and reading them is a network
+        // call `list` deliberately does not make.
+        ...(target.pointsAt !== null
+          ? [style.dim(target.pointsAt), '', '']
+          : [
+              style.dim(target.credentials ?? ''),
+              style.dim(target.storage ?? ''),
+              deploymentCell(target),
+            ]),
       ]),
     );
 
@@ -233,13 +269,15 @@ export function targetUse(name: string | undefined): never {
 /**
  * `lanes link target show [name]` — one target's adapters, and where it answers.
  *
- * The deep counterpart to `list`, and the one that *does* ask the platform: one
- * target, one subprocess, and you named it. Nothing else prints a target's
- * adapter set — `config show` dumps the whole file as JSON — which is what earns
- * this its place beside `outputs`.
+ * The deep counterpart to `list`, and the one that *does* go and look: it
+ * follows a pointer to the workspace that declares the target, then asks the
+ * platform for the address. One target, one hop, one subprocess, and you named
+ * it. Nothing else prints a target's adapter set — `config show` dumps a
+ * profile, which no longer carries one — which is what earns this its place
+ * beside `outputs`.
  */
 export async function targetShow(name: string | undefined, flags: TargetFlags): Promise<void> {
-  const { config, listing } = await survey(flags);
+  const { root, listing } = await survey(flags);
 
   // Positionally or by flag, but one of them: this command's whole subject is a
   // single target, and there is no default left to mean "the one you would have
@@ -247,28 +285,31 @@ export async function targetShow(name: string | undefined, flags: TargetFlags):
   const wanted = name ?? listing.selected;
   if (!wanted) {
     throw new ConfigError(
-      'Usage: lanes link target show <name> --profile <name>\n' +
+      'Usage: lanes link target show <name>\n' +
         `  Declared here: ${listing.targets.map((one) => one.name).join(', ') || 'none'}`,
     );
   }
 
-  const summary = listing.targets.find((candidate) => candidate.name === wanted);
-  if (!summary) throw undeclaredTarget(wanted, config, listing.profile);
+  const resolved = await openTarget(root, wanted);
+  const summary = summarise(wanted, { ...resolved.declared, ...resolved.entry }, true);
+  const profiles = await listProfiles(resolved.workspaceRoot);
 
   const url = summary.deployment
     ? await waiting('asking the platform for an address', () =>
-        deployedUrl(config.targets[wanted]?.deploy),
+        deployedUrl(resolved.declared.deploy),
       )
     : null;
 
-  return emit(flags.json, { ...summary, url }, () => {
-    print(style.dim(`${listing.profile}  ${listing.path}`));
+  return emit(flags.json, { ...summary, workspace: resolved.workspaceRoot, profiles, url }, () => {
+    print(style.dim(resolved.workspaceRoot));
 
     heading(summary.name);
     table([
-      ['  credentials', summary.credentials],
-      ['  storage', summary.storage],
-      ['  vault', summary.vault],
+      ['  workspace', resolved.workspaceRoot],
+      ['  profiles', profiles.join(', ') || style.dim('none yet')],
+      ['  credentials', summary.credentials ?? ''],
+      ['  storage', summary.storage ?? ''],
+      ['  vault', summary.vault ?? ''],
       ...(summary.knowledge
         ? [['  knowledge', summary.knowledge, style.dim('memory and skills')]]
         : []),

package/src/cli/commands/update.ts

@@ -2,6 +2,7 @@ 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 { emit, fail, ok, print, printErr, progress, style, warn } from '../output.ts';
 import { PACKAGE, release, type ReleaseState } from '../release.ts';
 import { version } from '../version.ts';
@@ -169,7 +170,21 @@ export async function update(flags: UpdateFlags): Promise<void> {
   // profile of someone already on the latest version is exactly the one this was
   // reported against.
   if (flags.check !== true) {
-    await repairOwnerLayer(resolveWorkspaceRoot(), undefined, {
+    const root = resolveWorkspaceRoot();
+
+    // The contract migration before the owner-layer repair, and the order is not
+    // cosmetic: the repair opens profiles through the ordinary loader, and the
+    // loader refuses contract 1 outright (ADR-052). On a workspace that has not
+    // been migrated the repair has nothing it can read.
+    //
+    // Local workspace only. A remote one is a bucket whose endpoint is running a
+    // pinned image, and migrating it from here would leave that revision reading
+    // a contract it does not implement until someone redeploys. `deploy` is what
+    // migrates a bucket, because it is the command that ships the image in the
+    // same breath.
+    await migrateLocal(root, flags.json === true ? progress : print);
+
+    await repairOwnerLayer(root, undefined, {
       ...(flags.json === true ? { report: progress } : {}),
     });
   }
@@ -275,3 +290,43 @@ async function runInstall(argv: readonly string[], json: boolean): Promise<boole
     return false;
   }
 }
+
+/**
+ * Bring the local workspace to the current contract, saying so if it did.
+ *
+ * Narrated rather than silent: this rewrites every profile in the workspace, and
+ * a command that reshapes somebody's config without a word is one they cannot
+ * audit afterwards. Routed to `report` for `--json`, where a line of prose in
+ * front of the document corrupts whatever is parsing it — the same routing
+ * `repairOwnerLayer` takes, for the same reason.
+ *
+ * A failure here is reported and swallowed. `update`'s job is to install a
+ * version, and a workspace that cannot migrate — a custom path that will not
+ * hoist, two profiles disagreeing about one target — is a thing to be told
+ * 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.
+ */
+async function migrateLocal(root: string, say: (line: string) => void): Promise<void> {
+  try {
+    if (!(await needsMigration(root))) return;
+
+    const migration = await migrateWorkspace(root);
+    if (migration.alreadyCurrent) return;
+
+    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}`);
+
+    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)}`);
+  }
+}

package/src/cli/config-edit.ts

@@ -5,6 +5,7 @@ import {
   isRemoteWorkspace,
   readWorkspaceFile,
   validateConfig,
+  validateConfigShape,
   workspaceFiles,
   writeWorkspaceFile,
 } from '#profile';
@@ -179,12 +180,28 @@ export class ConfigDocument {
    * Validation happens on the rendered text rather than the in-memory tree so
    * that what is checked is exactly what would land on disk.
    */
-  async save(): Promise<void> {
+  /**
+   * `shapeOnly` validates the schema and the secret scan, and skips the
+   * referential checks.
+   *
+   * For the contract 1 → 2 migration, and nothing else. That migration rewrites
+   * the structure of a file which may *also* carry an unrelated problem the
+   * loader refuses — a connection row still spelling a renamed provider is the
+   * one that actually happens. Blocking the structural fix on the unrelated one
+   * would leave the file stuck at a contract nothing reads, which is a worse
+   * place to be than contract 2 with a stale row that `doctor --fix` names and
+   * repairs.
+   *
+   * The half it keeps is the half that matters for a write: the schema, and the
+   * scan that stops a credential value being written into config.
+   */
+  async save(options: { shapeOnly?: boolean } = {}): Promise<void> {
     const rendered = this.toString();
 
     // Throws on any validation failure, including a credential value that has
     // crept in — so a CLI edit can never introduce one.
-    validateConfig(this.#document.toJSON(), this.#path);
+    if (options.shapeOnly === true) validateConfigShape(this.#document.toJSON(), this.#path);
+    else validateConfig(this.#document.toJSON(), this.#path);
 
     if (!this.#location) {
       throw new ConfigError(`${this.#path}: opened from text, so there is nowhere to save it`);
@@ -217,7 +234,7 @@ export class ConfigDocument {
  * 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, targets: string): string {
+export function newProfileTemplate(profile: string, port: number): string {
   return `# Lanes Link profile: ${profile}
 #
 # This file is the source of truth for what exists. It never contains a
@@ -226,23 +243,24 @@ export function newProfileTemplate(profile: string, port: number, targets: strin
 #
 # Edit it by hand or through the CLI; both are supported, and CLI edits
 # preserve your comments and ordering.
-contract: 1
+contract: 2
 
 instance:
   profile: ${profile}
   port: ${port}
   host: 127.0.0.1
 
-# Adapter selection is per target, and every command names the one it means:
+# This file says nothing about where it runs, and that is the point.
+#
+# A profile lives in exactly one target, and the target is the workspace holding
+# this file — which declares its own adapters, once, in lanes-link.yaml beside
+# the profiles/ directory (ADR-052). Moving this profile somewhere else is
+# copying the file there; there is no block in it to edit.
+#
+# Every command still names both, because neither is inferred (ADR-037):
 #
 #     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:
-${targets}
 # The bearer token for the endpoint this profile serves.
 #
 # "lanes link start" serves every profile in the workspace from one URL, and this
@@ -323,10 +341,23 @@ export function newWorkspaceTemplate(): string {
 # 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
+# This workspace IS a target. "targets:" below says where its bytes go, once,
+# for every profile in it — a profile says nothing about where it runs, so
+# there is one copy of it and nothing to keep in step (ADR-052).
+#
+# A target somewhere else is a pointer, and "deploy" writes one:
+#
+#   targets:
+#     cloud:
+#       workspace: gs://your-bucket
+#
+# The workspace at that address declares its own adapters, and is the only
+# thing that does. Reading it is a network call, which is why "--target cloud"
+# needs that bucket reachable.
+contract: 2
+targets:
+  local:
+    credentials: { adapter: file }
+    storage: { adapter: filesystem }
 `;
 }

package/src/cli/endpoint-url.ts

@@ -1,4 +1,4 @@
-import type { Config, DeployConfig } from '#profile';
+import type { Config, DeployConfig, TargetConfig } from '#profile';
 
 /**
  * Where this profile's endpoint answers, for the target in play.
@@ -15,8 +15,8 @@ import type { Config, DeployConfig } from '#profile';
  * answer and the other could not see it, which is what a copied line does
  * eventually.
  */
-export async function endpointUrl(config: Config, target: string): Promise<string> {
-  const deployed = await deployedUrl(config.targets[target]?.deploy);
+export async function endpointUrl(config: Config, declared: TargetConfig): Promise<string> {
+  const deployed = await deployedUrl(declared.deploy);
   return deployed ?? localUrl(config);
 }
 

package/src/cli/main.ts

@@ -32,7 +32,8 @@ 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 { assertKnownFlags, requireSelection } from './selection.ts';
+import { assertKnownFlags } from './selection.ts';
+import { requireSelection } from './selection-require.ts';
 import { PROGRAM, USAGE } from './usage.ts';
 import { version } from './version.ts';
 import { print } from './output.ts';
@@ -125,19 +126,20 @@ 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> [--target <name>]`);
+            throw new Error(`Usage: ${PROGRAM} profile add <name> --target <name>`);
           }
           return profileAdd(rest[0], {
-            // Read from argv rather than from `flags`, because this is the one
-            // place a flag is a list: a profile declares every target it can run
-            // on, and the parser keeps only the last value of a repeated flag.
-            targets: all(argv, 'target'),
+            // 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')!],
             nonInteractive: flags['non-interactive'] === true,
             json,
           });
         case 'list':
         case undefined:
-          return profileList({ json });
+          return profileList(text(flags, 'target')!, { json });
         case 'default':
           if (!rest[0]) throw new Error(`Usage: ${PROGRAM} profile default <name>`);
           return profileDefault(rest[0]);