@lanes-sh/link 0.3.0 → 0.3.2

package/src/deployments/sync-apply.ts

@@ -0,0 +1,330 @@
+import { parseDocument } from 'yaml';
+import {
+  ConfigError,
+  parseConfig,
+  readWorkspaceFile,
+  workspaceFiles,
+  writeWorkspaceFile,
+  type Config,
+} from '#profile';
+import { ConfigDocument } from '#cli/config-edit.ts';
+import { diffConfigs, keyOfElement, keyedArrayFor, type Change } from './sync.ts';
+import { isWorkspaceConfig } from './upload.ts';
+
+/**
+ * Deciding a difference and writing it down.
+ *
+ * The rule is union, and refusal where a union is not possible. Anything one
+ * side is missing is copied to it; anything both sides hold differently stops
+ * the sync and prints the diff. Last-writer-wins was the alternative and it is
+ * the failure this whole command exists because of — a copy of a profile
+ * quietly replaced another that held six connections it did not.
+ *
+ * `--prefer` is how a conflict is resolved, and it is deliberately one flag for
+ * the whole run rather than a prompt per key: a sync that asks twelve questions
+ * is one answered by pressing return, and the twelfth answer is the one that
+ * matters.
+ */
+
+export type Prefer = 'local' | 'remote';
+
+export interface ProfileSync {
+  readonly profile: string;
+  readonly changes: readonly Change[];
+  /** Only on the local side: the remote file does not exist at all. */
+  readonly onlyRemote: boolean;
+  readonly onlyLocal: boolean;
+}
+
+const profileKey = (profile: string): string => `profiles/${profile}.yaml`;
+
+/** Parse a profile out of a workspace, or `undefined` when it is not there. */
+async function readProfile(root: string, profile: string): Promise<Config | undefined> {
+  const text = await readWorkspaceFile(workspaceFiles(root), profileKey(profile));
+  if (text === null) return undefined;
+
+  // A remote copy that will not parse is a conflict the operator has to look
+  // at, not something to overwrite with the local one — it may be the only copy
+  // of something.
+  try {
+    return parseConfig(text, `${root}/${profileKey(profile)}`).config;
+  } catch (error) {
+    throw new ConfigError(
+      `${root}/${profileKey(profile)} could not be read, so it cannot be merged:\n` +
+        `  ${error instanceof Error ? (error.message.split('\n')[0] ?? '') : String(error)}\n` +
+        '  Fix it there, or pass --prefer local to overwrite it.',
+    );
+  }
+}
+
+/**
+ * The same file, unvalidated, as the source of what actually gets written.
+ *
+ * The diff compares *validated* configs, because that is the only comparison
+ * that gets equality right: `policy.allow: [gmail.*]` and
+ * `[{capability: gmail.*}]` are the same grant written two ways, and a raw
+ * comparison would call that a conflict.
+ *
+ * What is written has to come from here all the same. Writing the validated
+ * value back means writing every default zod filled in on the way through —
+ * `min_instances: 0`, an OAuth token lifetime nobody set — into a file the
+ * operator reads. Recovering six connections should not also silently expand
+ * three policy rules into a shape they were not written in.
+ *
+ * The two cannot disagree about whether something is missing: a default is
+ * filled in identically on both sides, so it is equal, so it is never a change.
+ */
+async function readRawProfile(root: string, profile: string): Promise<unknown> {
+  const text = await readWorkspaceFile(workspaceFiles(root), profileKey(profile));
+  return text === null ? undefined : parseDocument(text).toJSON();
+}
+
+/** Every profile either side has, so one that exists only remotely is still seen. */
+export async function profilesInEither(local: string, remote: string): Promise<string[]> {
+  const names = async (root: string): Promise<string[]> =>
+    (await workspaceFiles(root).list('profiles/'))
+      .map((entry) => entry.key.slice('profiles/'.length))
+      .filter((name) => name.endsWith('.yaml') && !name.endsWith('.example.yaml'))
+      .filter((name) => !name.includes('/'))
+      .map((name) => name.slice(0, -'.yaml'.length));
+
+  return [...new Set([...(await names(local)), ...(await names(remote))])].sort();
+}
+
+/** What differs, for one profile, between the workspace and a target's copy. */
+export async function planProfile(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  prefer: Prefer | undefined,
+): Promise<ProfileSync> {
+  const local = await readProfile(localRoot, profile);
+  const remote = prefer === 'local' && local !== undefined
+    ? // Told local wins outright: there is nothing to ask the remote copy, and
+      // reading it could only produce conflicts already decided.
+      undefined
+    : await readProfile(remoteRoot, profile);
+
+  return {
+    profile,
+    changes: diffConfigs(local, remote),
+    onlyRemote: local === undefined && remote !== undefined,
+    onlyLocal: remote === undefined && local !== undefined,
+  };
+}
+
+/** The changes that will be written, once `--prefer` has decided the rest. */
+export function resolved(changes: readonly Change[], prefer: Prefer | undefined): Change[] {
+  return changes.map((change) => {
+    if (change.direction !== 'conflict') return change;
+    if (prefer === undefined) return change;
+    return { ...change, direction: prefer === 'remote' ? 'pull' : 'push' } as Change;
+  });
+}
+
+/**
+ * Write everything the local copy is missing into the local profile.
+ *
+ * Through `ConfigDocument`, so the comments an operator wrote survive a
+ * recovery, and so the result is validated before it lands — a merged config
+ * that would not load is a worse outcome than the one being fixed.
+ *
+ * A keyed-array element is written by rewriting its array. A YAML sequence has
+ * no addressable slot for "the entry whose provider is gmail", and merging by
+ * index is exactly the comparison this avoided making in the first place.
+ */
+export async function applyPulls(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  changes: readonly Change[],
+): Promise<number> {
+  const pulls = changes.filter((change) => change.direction === 'pull');
+  if (pulls.length === 0) return 0;
+
+  // A profile local does not have at all is a file copy: there is no document
+  // to edit, and every key in it is a pull.
+  if (pulls.some((change) => change.path.length === 0)) {
+    const text = await readWorkspaceFile(workspaceFiles(remoteRoot), profileKey(profile));
+    if (text === null) return 0;
+    await writeWorkspaceFile(workspaceFiles(localRoot), profileKey(profile), text);
+    return 1;
+  }
+
+  const document = await ConfigDocument.open(localRoot, profile);
+  const remote = await readRawProfile(remoteRoot, profile);
+  if (remote === undefined) return 0;
+
+  const local = document.toJSON();
+  const written = new Set<string>();
+
+  for (const change of pulls) {
+    const array = keyedArrayFor(change.path);
+
+    if (array) {
+      // One write per array, however many of its elements were missing — and
+      // the value written is the *merge*, never the remote array.
+      //
+      // It used to be `setIn(array, remoteArray)`, which reads as "pull the
+      // connections" and means "replace the connections". A profile that had
+      // gained six accounts locally since the last deploy lost all six to a
+      // command whose entire purpose is not losing things. The tests missed it
+      // because every one of them had a local array that was a subset of the
+      // remote — the case where replacing and merging agree.
+      const key = array.join('.');
+      if (written.has(key)) continue;
+      written.add(key);
+
+      const merged = mergeKeyed(
+        array,
+        valueAt(local, array),
+        valueAt(remote, array),
+        pulls
+          .filter((one) => keyedArrayFor(one.path)?.join('.') === key)
+          .map((one) => one.path[array.length])
+          .filter((name): name is string => name !== undefined),
+      );
+      if (merged !== undefined) document.setIn([...array], merged);
+      continue;
+    }
+
+    const value = valueAt(remote, change.path);
+    // Absent from the raw document means the remote side only has it as a
+    // default, which the local side fills in identically. Nothing to write.
+    if (value === undefined) continue;
+
+    document.setIn([...change.path], value);
+  }
+
+  await document.save();
+  return written.size;
+}
+
+/**
+ * The local array, with the named elements taken from the remote one.
+ *
+ * Element order is local's, with anything new appended, so a pull reads as a
+ * diff in the file rather than as a reshuffle. An element named in `wanted` and
+ * absent from the remote array is skipped rather than removed: the diff said it
+ * was missing locally, so it cannot also be missing remotely.
+ */
+function mergeKeyed(
+  arrayPath: readonly string[],
+  local: unknown,
+  remote: unknown,
+  wanted: readonly string[],
+): unknown[] | undefined {
+  if (!Array.isArray(remote)) return undefined;
+
+  const merged = Array.isArray(local) ? [...(local as unknown[])] : [];
+  const keyOf = (item: unknown): string | undefined => keyOfElement(arrayPath, item);
+
+  for (const name of new Set(wanted)) {
+    const incoming = remote.find((item) => keyOf(item) === name);
+    if (incoming === undefined) continue;
+
+    const at = merged.findIndex((item) => keyOf(item) === name);
+    if (at >= 0) merged[at] = incoming;
+    else merged.push(incoming);
+  }
+
+  return merged;
+}
+
+/** Read a path out of the raw document, for handing to `setIn`. */
+function valueAt(config: unknown, path: readonly string[]): unknown {
+  let value: unknown = config;
+  for (const step of path) {
+    if (!(typeof value === 'object' && value !== null)) return undefined;
+    value = (value as Record<string, unknown>)[step];
+  }
+  return value;
+}
+
+/**
+ * Send the local profile up, once it holds everything both sides had.
+ *
+ * Wholesale rather than key by key, and only *after* the pulls have been
+ * applied: at that point the local file is the union, so copying it up makes
+ * the remote one the union too. The remote copy has no comments of its own to
+ * lose — `uploadWorkspace` wrote it — so there is nothing finer-grained to
+ * preserve, and one PUT cannot half-apply a merge.
+ */
+export async function applyPushes(
+  localRoot: string,
+  remoteRoot: string,
+  profile: string,
+  changes: readonly Change[],
+): Promise<boolean> {
+  if (!changes.some((change) => change.direction === 'push')) return false;
+
+  const text = await readWorkspaceFile(workspaceFiles(localRoot), profileKey(profile));
+  if (text === null) return false;
+
+  await writeWorkspaceFile(workspaceFiles(remoteRoot), profileKey(profile), text);
+  return true;
+}
+
+/**
+ * The authored areas inside `data/` — skills and provider manifests.
+ *
+ * They ride the same allowlist a deploy uploads by, and for the reason that
+ * comment gives at length: the list is what keeps a credential store out of a
+ * bucket, and a second answer to "which files" is how the two drift. Compared
+ * by content, since they are documents rather than config, and differing
+ * content is a conflict like any other.
+ */
+export interface BlobSync {
+  readonly key: string;
+  readonly direction: 'pull' | 'push' | 'conflict';
+}
+
+export async function planBlobs(localRoot: string, remoteRoot: string): Promise<BlobSync[]> {
+  const read = async (root: string): Promise<Map<string, Uint8Array>> => {
+    const files = workspaceFiles(root);
+    const found = new Map<string, Uint8Array>();
+
+    for (const entry of await files.list('')) {
+      // `undefined` profile: every profile's authored areas, since sync is
+      // scoped to the target and not to one of them.
+      if (!isWorkspaceConfig(entry.key) || entry.key.endsWith('.yaml')) continue;
+      const bytes = await files.get(entry.key);
+      if (bytes !== null) found.set(entry.key, bytes);
+    }
+    return found;
+  };
+
+  const here = await read(localRoot);
+  const there = await read(remoteRoot);
+  const equal = (a: Uint8Array, b: Uint8Array): boolean =>
+    a.length === b.length && a.every((byte, index) => byte === b[index]);
+
+  return [...new Set([...here.keys(), ...there.keys()])].sort().flatMap((key): BlobSync[] => {
+    const local = here.get(key);
+    const remote = there.get(key);
+    if (local === undefined) return [{ key, direction: 'pull' }];
+    if (remote === undefined) return [{ key, direction: 'push' }];
+    return equal(local, remote) ? [] : [{ key, direction: 'conflict' }];
+  });
+}
+
+export async function applyBlobs(
+  localRoot: string,
+  remoteRoot: string,
+  blobs: readonly BlobSync[],
+): Promise<number> {
+  let copied = 0;
+
+  for (const blob of blobs) {
+    const from = blob.direction === 'pull' ? remoteRoot : localRoot;
+    const to = blob.direction === 'pull' ? localRoot : remoteRoot;
+
+    const bytes = await workspaceFiles(from).get(blob.key);
+    if (bytes === null) continue;
+
+    await workspaceFiles(to).put(blob.key, bytes, { contentType: 'application/octet-stream' });
+    copied += 1;
+  }
+
+  return copied;
+}

package/src/deployments/sync.ts

@@ -0,0 +1,164 @@
+import type { Config } from '#profile';
+
+/**
+ * What differs between a workspace and a target's copy of it.
+ *
+ * A deployed endpoint reads its config out of a bucket, and `deploy` puts it
+ * there — so from the moment of the first deploy there are two copies of every
+ * profile. They are supposed to agree. When they do not, one of them holds
+ * something the other has lost, and until now nothing could say which or bring
+ * it back.
+ *
+ * This file only *finds* the difference. Deciding it and writing it are
+ * `sync-apply.ts`, and choosing which bucket to compare against is the command.
+ * Split that way because the diff is the part worth testing exhaustively and
+ * the only part with no I/O in it.
+ */
+
+/** Which side is missing what, or that both have it and disagree. */
+export type Direction = 'pull' | 'push' | 'conflict';
+
+export interface Change {
+  /** Where in the config, e.g. `['targets', 'cloud']` or `['connections']`. */
+  readonly path: readonly string[];
+  readonly direction: Direction;
+  /** What remote holds. Absent when remote is the side that is missing it. */
+  readonly remote?: unknown;
+  /** What local holds. Absent when local is the side that is missing it. */
+  readonly local?: unknown;
+}
+
+/**
+ * Arrays whose elements are records rather than an ordered list.
+ *
+ * `connections` is a set of accounts keyed by `provider.id`; comparing it
+ * positionally would call a reordered file a conflict and, worse, would call an
+ * *added* connection a change to whichever one now sits at that index. The key
+ * function is what makes "personal gained a mailbox" a different fact from
+ * "personal's third connection changed".
+ *
+ * `identity` is deliberately absent. Its declaration order is meaningful — the
+ * first entry of a kind is the one to reach for — so it is an ordered list and
+ * compares as one.
+ */
+const KEYED: Record<string, (item: unknown) => string | undefined> = {
+  connections: (item) =>
+    isRecord(item) ? `${String(item['provider'])}.${String(item['id'])}` : undefined,
+  // Two shapes, and both are reached. The diff runs over validated configs,
+  // where `allow: [gmail.*]` has become `[{capability: gmail.*}]`; the writer
+  // runs over the raw document, where it is still a string. A key function that
+  // knew only the validated shape found nothing to merge and silently wrote the
+  // array without it.
+  'policy.allow': capabilityOf,
+  'policy.deny': capabilityOf,
+};
+
+function capabilityOf(item: unknown): string | undefined {
+  if (typeof item === 'string') return item;
+  return isRecord(item) ? String(item['capability']) : undefined;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Every difference between one profile's two copies.
+ *
+ * Recursive over objects so a change reports at the narrowest path that
+ * describes it: two profiles differing only in `auth.authorization` produce
+ * that path, not `auth`, and applying it cannot take `token_ref` with it.
+ */
+export function diffConfigs(local: Config | undefined, remote: Config | undefined): Change[] {
+  if (local === undefined && remote === undefined) return [];
+
+  // A whole profile that only one side has. Reported at the root, because the
+  // unit that has to be copied is the file.
+  if (local === undefined) return [{ path: [], direction: 'pull', remote }];
+  if (remote === undefined) return [{ path: [], direction: 'push', local }];
+
+  return walk([], local as unknown, remote as unknown);
+}
+
+function walk(path: readonly string[], local: unknown, remote: unknown): Change[] {
+  if (same(local, remote)) return [];
+
+  if (local === undefined) return [{ path, direction: 'pull', remote }];
+  if (remote === undefined) return [{ path, direction: 'push', local }];
+
+  const key = path.join('.');
+  const keyOf = KEYED[key];
+  if (keyOf && Array.isArray(local) && Array.isArray(remote)) {
+    return walkKeyed(path, keyOf, local, remote);
+  }
+
+  if (isRecord(local) && isRecord(remote)) {
+    const keys = [...new Set([...Object.keys(local), ...Object.keys(remote)])].sort();
+    return keys.flatMap((name) => walk([...path, name], local[name], remote[name]));
+  }
+
+  // Two scalars, or two ordered arrays, that are not equal. There is no
+  // narrower path to report and no way to have both.
+  return [{ path, direction: 'conflict', local, remote }];
+}
+
+/**
+ * A keyed array, compared as the set of records it is.
+ *
+ * Each element reports under `path.key` — `connections.gmail.work` — so a
+ * missing account names itself in the output instead of appearing as an index.
+ * Applying still rewrites the whole array, because a YAML sequence has no
+ * addressable slot for "the element whose provider is gmail".
+ */
+function walkKeyed(
+  path: readonly string[],
+  keyOf: (item: unknown) => string | undefined,
+  local: readonly unknown[],
+  remote: readonly unknown[],
+): Change[] {
+  const index = (items: readonly unknown[]): Map<string, unknown> =>
+    new Map(
+      items
+        .map((item) => [keyOf(item), item] as const)
+        .filter((pair): pair is readonly [string, unknown] => pair[0] !== undefined),
+    );
+
+  const here = index(local);
+  const there = index(remote);
+  const names = [...new Set([...here.keys(), ...there.keys()])].sort();
+
+  return names.flatMap((name) => walk([...path, name], here.get(name), there.get(name)));
+}
+
+/**
+ * The array a change belongs to, when it belongs to one.
+ *
+ * `['connections', 'gmail.work']` is applied by rewriting `connections`, so
+ * both the writer and the renderer need to know where the element stops and the
+ * key begins. Longest prefix first, so `policy.allow` wins over `policy`.
+ */
+export function keyedArrayFor(path: readonly string[]): readonly string[] | undefined {
+  for (let depth = path.length - 1; depth > 0; depth--) {
+    if (path.slice(0, depth).join('.') in KEYED) return path.slice(0, depth);
+  }
+  return undefined;
+}
+
+/**
+ * How an element of a keyed array identifies itself, for the writer.
+ *
+ * The diff indexes these to compare them; applying one has to find the same
+ * element again in *both* raw documents, and it cannot re-derive the key from
+ * the path — `connections.gmail.work` is one key containing a dot, not two
+ * steps. Exported so the two halves cannot disagree about what identifies a
+ * connection.
+ */
+export function keyOfElement(arrayPath: readonly string[], item: unknown): string | undefined {
+  return KEYED[arrayPath.join('.')]?.(item);
+}
+
+/** Whether a set of changes can be applied without being told which side wins. */
+export function conflictsIn(changes: readonly Change[]): Change[] {
+  return changes.filter((change) => change.direction === 'conflict');
+}

package/src/deployments/upload.ts

@@ -64,17 +64,21 @@ export function deployedWorkspace(declared: TargetConfig): string | undefined {
  * prefix: `data/personal/skills.detour/` is not `skills.d`, and the difference
  * between matching it and not is a credential in a bucket.
  */
-export function isWorkspaceConfig(key: string, profile?: string | undefined): boolean {
+export function isWorkspaceConfig(key: string, profiles?: readonly string[]): boolean {
   if (key === WORKSPACE_FILE) return true;
 
-  // One profile when the deploy names one, so a workspace holding personal and
-  // work does not push both into a bucket only one of them is for. The same
-  // question for both shapes, asked once.
+  // A set rather than one name, because a deploy now sends every profile that
+  // declares the target rather than the single one it was told. `undefined`
+  // still means the whole workspace, and an *empty* set means nothing — which
+  // is a distinction a bare string could not make.
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
+
   const owner = authoredAreaOwner(key);
-  if (owner !== null) return profile === undefined || owner === profile;
+  if (owner !== null) return wanted === undefined || wanted.has(owner);
 
   if (!key.startsWith('profiles/') || !key.endsWith('.yaml')) return false;
-  return profile === undefined || key === `profiles/${profile}.yaml`;
+  const name = key.slice('profiles/'.length, -'.yaml'.length);
+  return wanted === undefined || wanted.has(name);
 }
 
 /**
@@ -120,10 +124,12 @@ function authoredAreaOwner(key: string): string | null {
  */
 export async function repairSetupSurface(
   workspaceRoot: string,
-  profile: string | undefined,
+  profiles: readonly string[] | undefined,
 ): Promise<void> {
+  const wanted = profiles === undefined ? undefined : new Set(profiles);
+
   for (const name of await listProfiles(workspaceRoot)) {
-    if (profile !== undefined && name !== profile) continue;
+    if (wanted !== undefined && !wanted.has(name)) continue;
 
     try {
       const document = await ConfigDocument.open(workspaceRoot, name);
@@ -151,14 +157,14 @@ export async function repairSetupSurface(
 export async function uploadWorkspace(
   root: string,
   destination: string,
-  profile: string | undefined,
+  profiles: readonly string[] | undefined,
 ): Promise<void> {
   const local = workspaceFiles(root);
   const remote = workspaceFiles(destination);
 
   let copied = 0;
   for (const entry of await local.list('')) {
-    if (!isWorkspaceConfig(entry.key, profile)) continue;
+    if (!isWorkspaceConfig(entry.key, profiles)) continue;
 
     const bytes = await local.get(entry.key);
     if (bytes === null) continue;
@@ -203,6 +209,6 @@ export async function publishWorkspace(input: {
   const destination = deployedWorkspace(declared);
   if (!destination) return null;
 
-  await uploadWorkspace(input.workspaceRoot, destination, input.profile);
+  await uploadWorkspace(input.workspaceRoot, destination, [input.profile]);
   return destination;
 }

package/src/profile/deployments.ts

@@ -0,0 +1,80 @@
+import { parseDocument } from 'yaml';
+import { readWorkspaceFile, workspaceFiles, writeWorkspaceFile } from './files.ts';
+import { workspaceSchema, type DeploymentRecord } from './schema.ts';
+import { WORKSPACE_FILE, readWorkspace } from './workspace.ts';
+
+/**
+ * The workspace's record of where its deployments live.
+ *
+ * A target is declared by a profile, and that declaration is what every command
+ * resolves from. This is the index beside it, and the distinction is the whole
+ * design: a profile file rewritten by hand or by a tool took a live Cloud Run
+ * service, its bucket, and its credential store out of reach in one edit,
+ * because the four lines naming them were the only copy. The service was still
+ * running. Nothing could find it.
+ *
+ * So the record is kept where the thing it describes is not: one level up, in
+ * `lanes-link.yaml`. `sync targets` reads it to know which bucket to open, and
+ * nothing else reads it at all — an index that starts being resolved from is a
+ * second source of truth, which is the failure ADR-037 spent a release
+ * removing (ADR-044).
+ */
+
+/** Every deployment the workspace has recorded. Empty for a workspace with none. */
+export async function readDeployments(workspaceRoot: string): Promise<DeploymentRecord[]> {
+  // A workspace file that will not parse is not a reason to fail a recovery:
+  // the caller has other ways to find a target, and this is the cheapest.
+  try {
+    return (await readWorkspace(workspaceRoot))?.deployments ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** What the workspace knows about one target, if anything. */
+export async function findDeployment(
+  workspaceRoot: string,
+  target: string,
+): Promise<DeploymentRecord | undefined> {
+  return (await readDeployments(workspaceRoot)).find((entry) => entry.target === target);
+}
+
+/**
+ * Record a deployment, replacing any earlier entry for the same target.
+ *
+ * Keyed by target rather than appended, because a target has one deployment by
+ * definition — a second entry would be a history, and a history is a thing to
+ * read wrong. Redeploying the same target to a new bucket should leave one
+ * record naming the new one.
+ *
+ * Merged into the existing entry so a field this caller does not know about —
+ * `primary`, on a redeploy that did not ask — is carried forward rather than
+ * dropped.
+ *
+ * Written through the YAML document API, so the comments in a workspace file an
+ * operator has annotated survive being indexed.
+ */
+export async function recordDeployment(
+  workspaceRoot: string,
+  entry: DeploymentRecord,
+): Promise<void> {
+  const files = workspaceFiles(workspaceRoot);
+  const text = (await readWorkspaceFile(files, WORKSPACE_FILE)) ?? 'contract: 1\n';
+
+  const document = parseDocument(text);
+  const existing = await readDeployments(workspaceRoot);
+  const previous = existing.find((record) => record.target === entry.target);
+
+  const merged = [
+    ...existing.filter((record) => record.target !== entry.target),
+    { ...previous, ...entry },
+  ].sort((a, b) => a.target.localeCompare(b.target));
+
+  document.setIn(['deployments'], merged);
+
+  // Validated before it lands, on the rendered tree rather than the input, so
+  // what is checked is what would be read back.
+  workspaceSchema.parse(document.toJSON());
+
+  await writeWorkspaceFile(files, WORKSPACE_FILE, String(document));
+}

package/src/profile/index.ts

@@ -14,11 +14,13 @@
 export {
   SUPPORTED_CONTRACT,
   configSchema,
+  deploymentRecordSchema,
   workspaceSchema,
   type AuthorizationConfig,
   type Config,
   type ConnectionConfig,
   type DeployConfig,
+  type DeploymentRecord,
   type IdentityEntry,
   type PolicyRuleConfig,
   type TargetConfig,
@@ -54,19 +56,25 @@ export {
   installRoot,
   listProfiles,
   loadProfileConfig,
+  loadWorkspaceProfiles,
   noProfileNamed,
   profilePath,
   readWorkspace,
   resolveSelection,
   resolveWorkspaceRoot,
+  targetsByName,
   workspacePath,
+  type LoadedProfile,
+  type WorkspaceProfiles,
 } from './workspace.ts';
 export {
   LEGACY_TARGET_ENV,
+  noTargetInWorkspace,
   noTargetNamed,
   requireTarget,
   undeclaredTarget,
 } from './targets.ts';
+export { findDeployment, readDeployments, recordDeployment } from './deployments.ts';
 export {
   isRemoteWorkspace,
   readWorkspaceFile,