@ultimat3/cli 29.4.0 → 30.1.0

package/src/ci-tested.ts

@@ -0,0 +1,243 @@
+// `x ci tested`'s predicate: was THIS push's tree already proved green by the pull request run that
+// merged it? Pure over three injected GitHub reads, so every condition is a unit test; `ghTestedReads`
+// is the one `gh api` binding. Any doubt answers `tested: false`, which runs everything.
+
+import { renderFixShellArg, renderThrowable } from '@ultimat3/core';
+import { t } from '@ultimat3/schema';
+import type { GhHost } from './gh';
+import { GhFailedError, ghJson } from './gh';
+import type { GhRepo } from './gh-target';
+
+/** Why the answer is what it is: `tested` when every condition held, else the first that did not. */
+export const TESTED_CONDITIONS = [
+  'tested',
+  'subject',
+  'merged',
+  'fork',
+  'tree',
+  'run',
+  'stale',
+  'api',
+  // No commit to ask about: no `GITHUB_SHA`, and `git rev-parse HEAD` named none.
+  'sha',
+] as const;
+
+export type TestedCondition = (typeof TESTED_CONDITIONS)[number];
+
+export interface TestedCommit {
+  /** The whole message's first line. */
+  readonly subject: string;
+  readonly tree: string;
+}
+
+export interface TestedPull {
+  readonly merged: boolean;
+  readonly mergeCommitSha: string | null;
+  readonly headSha: string;
+  /** `owner/name` of the head's repository; `null` when that repository is gone. */
+  readonly headRepo: string | null;
+}
+
+export interface TestedRun {
+  readonly id: number;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly headRepo: string | null;
+  /** When the run last changed, which for a completed run is when it concluded. */
+  readonly completedAt: string;
+}
+
+/** The three questions the predicate asks GitHub, injected. */
+export interface CiTestedReads {
+  readonly commit: (sha: string) => Promise<TestedCommit>;
+  readonly pull: (number: number) => Promise<TestedPull>;
+  /** The workflow's runs on one head commit, any event. */
+  readonly runs: (headSha: string) => Promise<readonly TestedRun[]>;
+}
+
+export interface CiTestedAnswer {
+  readonly tested: boolean;
+  readonly condition: TestedCondition;
+  readonly pr?: number;
+  readonly run?: number;
+  /** Only for `api`: the refusal, rendered. */
+  readonly detail?: string;
+}
+
+/**
+ * `(#N)` as the subject's LAST characters, which is how GitHub's squash and merge-commit subjects
+ * end. Mid-subject, or on a body line, it is a reference to a PR, never the PR that merged it.
+ */
+export function mergedPullOf(subject: string): number | undefined {
+  const match = /\(#(\d+)\)$/.exec(subject);
+  return match === null || subject.includes('\n') ? undefined : Number(match[1]);
+}
+
+export async function ciTested(input: {
+  readonly sha: string;
+  readonly repo: string;
+  readonly maxAgeMs: number;
+  readonly now: number;
+  readonly reads: CiTestedReads;
+}): Promise<CiTestedAnswer> {
+  const { sha, repo, reads } = input;
+  let pr: number | undefined;
+  try {
+    const pushed = await reads.commit(sha);
+    pr = mergedPullOf(pushed.subject);
+    if (pr === undefined) return { tested: false, condition: 'subject' };
+    const pull = await reads.pull(pr);
+    if (!pull.merged || pull.mergeCommitSha !== sha)
+      return { tested: false, condition: 'merged', pr };
+    // A fork's workflow file is the fork's to write: its green says nothing this repository trusts.
+    if (pull.headRepo !== repo) return { tested: false, condition: 'fork', pr };
+    const head = await reads.commit(pull.headSha);
+    if (head.tree !== pushed.tree) return { tested: false, condition: 'tree', pr };
+    const own = (await reads.runs(pull.headSha)).filter((run) => run.headRepo === repo);
+    // The newest run decides: a red run after a green one on the same head is the later verdict.
+    const newest = [...own].sort((a, b) => b.id - a.id)[0];
+    if (newest === undefined) return { tested: false, condition: 'run', pr };
+    if (newest.status !== 'completed' || newest.conclusion !== 'success') {
+      return { tested: false, condition: 'run', pr, run: newest.id };
+    }
+    const age = input.now - Date.parse(newest.completedAt);
+    if (!(age >= 0 && age <= input.maxAgeMs)) {
+      return { tested: false, condition: 'stale', pr, run: newest.id };
+    }
+    return { tested: true, condition: 'tested', pr, run: newest.id };
+  } catch (error) {
+    // Any read that did not answer widens the gate: a full run costs minutes, a wrong skip ships.
+    return {
+      tested: false,
+      condition: 'api',
+      ...(pr === undefined ? {} : { pr }),
+      detail: renderThrowable(error),
+    };
+  }
+}
+
+const COMMIT = t.object({ subject: t.string, tree: t.string });
+const PULL = t.object({
+  merged: t.boolean,
+  mergeCommitSha: t.nullable(t.string),
+  headSha: t.string,
+  headRepo: t.nullable(t.string),
+});
+const RUNS = t.array(
+  t.object({
+    id: t.number,
+    status: t.string,
+    conclusion: t.nullable(t.string),
+    headRepo: t.nullable(t.string),
+    completedAt: t.string,
+  }),
+);
+
+/** One `gh` call's deadline: four calls stay well inside the `tested` job's five minutes. */
+export const TESTED_CALL_TIMEOUT_MS = 30_000;
+
+const killHard = (pid: number): void => {
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    // Already gone between the deadline and the signal.
+  }
+};
+
+/**
+ * `host`, with every call killed past `ms`: a stalled `gh api` must answer `tested: false` (the
+ * caller's `api` doubt), never hold the job until its `timeout-minutes` turns it red. The refusal
+ * is `X_GH_COMMAND_FAILED` — a call that did not answer is one more non-zero `gh`.
+ */
+export function withDeadline(
+  host: GhHost,
+  ms: number,
+  kill: (pid: number) => void = killHard,
+): GhHost {
+  return {
+    cwd: host.cwd,
+    runner: (command, options) =>
+      new Promise((resolve, reject) => {
+        let pid: number | undefined;
+        const timer = setTimeout(() => {
+          if (pid !== undefined) kill(pid);
+          reject(
+            new GhFailedError({
+              label: command.slice(0, 3).join(' '),
+              code: -1,
+              detail: `did not answer within ${ms} ms and was killed`,
+              fix: 'x ci tested --json',
+            }),
+          );
+        }, ms);
+        host
+          .runner(command, {
+            ...options,
+            onSpawn: (spawned) => {
+              pid = spawned;
+              options.onSpawn?.(spawned);
+            },
+          })
+          .then(
+            (result) => {
+              clearTimeout(timer);
+              resolve(result);
+            },
+            (error: unknown) => {
+              clearTimeout(timer);
+              reject(error);
+            },
+          );
+      }),
+  };
+}
+
+/** The reads, through `gh api`: `--jq` projects each answer to exactly the fields above. */
+export function ghTestedReads(host: GhHost, repo: GhRepo, workflow: string): CiTestedReads {
+  const api = `repos/${repo.slug}`;
+  const fix = `x ci tested --repo ${renderFixShellArg(repo.slug, '<owner/name>')} --json`;
+  return {
+    commit: (sha) =>
+      ghJson(
+        host,
+        [
+          'api',
+          `${api}/commits/${sha}`,
+          '--jq',
+          '{subject: (.commit.message | split("\\n")[0]), tree: .commit.tree.sha}',
+        ],
+        COMMIT,
+        { label: `gh api commits/${sha}`, fix },
+      ),
+    pull: (number) =>
+      ghJson(
+        host,
+        [
+          'api',
+          `${api}/pulls/${number}`,
+          '--jq',
+          '{merged, mergeCommitSha: .merge_commit_sha, headSha: .head.sha, headRepo: .head.repo.full_name}',
+        ],
+        PULL,
+        { label: `gh api pulls/${number}`, fix },
+      ),
+    runs: (headSha) =>
+      ghJson(
+        host,
+        [
+          'api',
+          '-X',
+          'GET',
+          `${api}/actions/workflows/${workflow}/runs`,
+          '-f',
+          `head_sha=${headSha}`,
+          '-f',
+          'per_page=50',
+          '--jq',
+          '[.workflow_runs[] | {id, status, conclusion, headRepo: .head_repository.full_name, completedAt: .updated_at}]',
+        ],
+        RUNS,
+        { label: `gh api ${workflow} runs`, fix },
+      ),
+  };
+}

package/src/client-emit-customer-runtime.ts

@@ -0,0 +1,139 @@
+// The fixed half of every customer client's `index.ts`: options, the problem error and the one
+// sender each operation calls. Platform only — no import — and the same bytes in every client, so
+// what a customer reviews once is what every regeneration ships.
+
+export const CUSTOMER_RUNTIME = `/** Where the API lives, and how each request is authorised. */
+export interface ClientOptions {
+  /** \`https://api.example.com\` — every operation's path is appended to it. */
+  readonly baseUrl: string;
+  /** Called before every request: the token or session the caller holds is the caller's to keep. */
+  readonly headers?:
+    | (() => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>)
+    | undefined;
+  /** The transport; the platform \`fetch\` when omitted. */
+  readonly fetch?: ((url: string, init: RequestInit) => Promise<Response>) | undefined;
+}
+
+export interface CallOptions {
+  readonly signal?: AbortSignal | undefined;
+}
+
+/** An RFC 9457 problem body, as the API answers a refusal. */
+export interface Problem {
+  readonly type?: string | undefined;
+  readonly title?: string | undefined;
+  readonly status?: number | undefined;
+  readonly code?: string | undefined;
+  readonly detail?: string | undefined;
+  readonly cause?: string | undefined;
+  readonly fix?: string | undefined;
+  readonly requestId?: string | undefined;
+}
+
+/** A non-2xx answer: which operation, the status, and the problem body when there was one. */
+export class ProblemError extends Error {
+  readonly operation: string;
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly problem: Problem | undefined;
+
+  constructor(operation: string, status: number, problem: Problem | undefined) {
+    const code = problem?.code ?? /^urn:ultimate:error:(X_[A-Z0-9_]+)$/.exec(problem?.type ?? '')?.[1];
+    super(\`\${operation} answered \${String(status)}\${code === undefined ? '' : \` \${code}\`}\`);
+    this.name = 'ProblemError';
+    this.operation = operation;
+    this.status = status;
+    this.code = code;
+    this.problem = problem;
+  }
+}
+
+interface CallSpec {
+  readonly operation: string;
+  readonly method: string;
+  readonly path: string;
+  readonly pathParams: readonly string[];
+  readonly query: readonly string[];
+  readonly headers: readonly string[];
+  /** \`value\`: \`input.body\` is the body; a list: those input fields are. */
+  readonly body: 'none' | 'value' | readonly string[];
+  readonly empty: boolean;
+}
+
+/** The longest \`Retry-After\` waited out; a longer one is the caller's to schedule. */
+const RETRY_AFTER_MAX_MS = 60_000;
+
+const read = (input: object, key: string): unknown =>
+  Object.hasOwn(input, key) ? (input as Readonly<Record<string, unknown>>)[key] : undefined;
+
+function retryAfterMs(response: Response): number | undefined {
+  const raw = response.headers.get('retry-after');
+  if (raw === null) return undefined;
+  const seconds = Number(raw);
+  const ms = raw.trim() !== '' && Number.isFinite(seconds) ? seconds * 1000 : Date.parse(raw) - Date.now();
+  return Number.isFinite(ms) && ms >= 0 && ms <= RETRY_AFTER_MAX_MS ? ms : undefined;
+}
+
+function wait(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted === true) return reject(signal.reason);
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}
+
+async function problemOf(response: Response): Promise<Problem | undefined> {
+  try {
+    const body: unknown = await response.json();
+    return typeof body === 'object' && body !== null ? (body as Problem) : undefined;
+  } catch {
+    // Not JSON: the status alone is the answer, and the error says so with no problem body.
+    return undefined;
+  }
+}
+
+function sender(options: ClientOptions) {
+  const transport =
+    options.fetch ?? ((url: string, init: RequestInit) => fetch(url, { ...init, signal: init.signal ?? null }));
+  return async (spec: CallSpec, input: object, call: CallOptions): Promise<unknown> => {
+    let path = spec.path;
+    for (const name of spec.pathParams) {
+      path = path.replace(\`{\${name}}\`, encodeURIComponent(String(read(input, name))));
+    }
+    const url = new URL(\`\${options.baseUrl.replace(/\\/$/, '')}\${path}\`);
+    for (const name of spec.query) {
+      const value = read(input, name);
+      if (value === undefined) continue;
+      for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(name, String(item));
+    }
+    const headers: Record<string, string> = { accept: 'application/json', ...(await options.headers?.()) };
+    for (const name of spec.headers) {
+      const value = read(input, name);
+      if (value !== undefined) headers[name] = String(value);
+    }
+    let body: string | null = null;
+    if (spec.body === 'value') body = JSON.stringify(read(input, 'body'));
+    else if (typeof spec.body !== 'string') {
+      const fields = spec.body.filter((key) => read(input, key) !== undefined);
+      body = JSON.stringify(Object.fromEntries(fields.map((key) => [key, read(input, key)])));
+    }
+    if (body !== null) headers['content-type'] = 'application/json';
+    for (let attempt = 0; ; attempt += 1) {
+      const response = await transport(url.toString(), { method: spec.method, headers, body, signal: call.signal ?? null });
+      if (response.ok) return spec.empty || response.status === 204 ? undefined : await response.json();
+      // A 429 or 503 with a Retry-After is waited out once; a second refusal is the caller's.
+      const delay = attempt === 0 && (response.status === 429 || response.status === 503) ? retryAfterMs(response) : undefined;
+      if (delay === undefined) throw new ProblemError(spec.operation, response.status, await problemOf(response));
+      await response.body?.cancel();
+      await wait(delay, call.signal);
+    }
+  };
+}
+`;

package/src/client-emit-customer.ts

@@ -0,0 +1,108 @@
+// The customer client: what a third party's TypeScript calls the app's published API with. Zero
+// imports beyond the platform — `fetch`, types, and a `ProblemError` read from the RFC 9457 body —
+// so the directory is publishable as it is. `rpc` stays the client inside the app's own repo.
+
+import { CUSTOMER_RUNTIME } from './client-emit-customer-runtime';
+import type { DocumentNames } from './client-emit-types';
+import { documentNames, propertyKey, typeText } from './client-emit-types';
+import type { ClientOperation, CompiledDocument } from './openapi-compile-ir';
+
+export interface CustomerFiles {
+  readonly 'index.ts': string;
+  readonly 'types.ts': string;
+}
+
+function typesFile(document: CompiledDocument, names: DocumentNames): string {
+  const lines: string[] = [
+    `// The types of ${document.title} ${document.version}, one per schema the operations reach.`,
+    '',
+  ];
+  for (const [name, type] of document.types) {
+    lines.push(`export type ${names.component(name)} = ${typeText(type, names.component)};`);
+  }
+  for (const op of document.operations) {
+    const types = names.operation.get(op.name);
+    for (const named of [types?.request, types?.response]) {
+      if (named?.text !== undefined) lines.push(`export type ${named.name} = ${named.text};`);
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/** The field names a `fields` body sends, its `$ref` followed into the document's types. */
+export function bodyKeys(document: CompiledDocument, op: ClientOperation): readonly string[] {
+  const type = op.body?.type;
+  const target = type?.kind === 'ref' ? document.types.get(type.name) : type;
+  return target?.kind === 'object' ? target.fields.map((field) => field.name) : [];
+}
+
+/** The call one operation makes: where each parameter goes, and what the body is. */
+function callSpec(document: CompiledDocument, op: ClientOperation): string {
+  const where = (place: 'path' | 'query' | 'header'): string =>
+    JSON.stringify(op.parameters.filter((p) => p.in === place).map((p) => p.name));
+  const body =
+    op.body === undefined
+      ? "'none'"
+      : op.body.mode === 'value'
+        ? "'value'"
+        : JSON.stringify(bodyKeys(document, op));
+  return `{ operation: ${JSON.stringify(op.name)}, method: ${JSON.stringify(op.method)}, path: ${JSON.stringify(op.path)}, pathParams: ${where('path')}, query: ${where('query')}, headers: ${where('header')}, body: ${body}, empty: ${String(op.response === undefined)} }`;
+}
+
+function operationLine(
+  document: CompiledDocument,
+  op: ClientOperation,
+  names: DocumentNames,
+): string {
+  const types = names.operation.get(op.name);
+  const request = types?.request === undefined ? undefined : `T.${types.request.name}`;
+  const response = types?.response === undefined ? 'void' : `T.${types.response.name}`;
+  const doc = op.summary === undefined ? '' : `    /** ${op.summary.replace(/\*\//g, '* /')} */\n`;
+  const input = request === undefined ? 'input: Record<string, never> = {}' : `input: ${request}`;
+  return `${doc}    ${propertyKey(op.name)}: (${input}, call: CallOptions = {}): Promise<${response}> =>\n      send(${callSpec(document, op)}, input, call) as Promise<${response}>,`;
+}
+
+/** Both files' text, unstamped: the command adds the header with the source hash. */
+export function emitCustomer(document: CompiledDocument): CustomerFiles {
+  const names = documentNames(document);
+  const refusals = document.operations.map(
+    (op) =>
+      `  ${propertyKey(op.name)}: ${op.refusals.length === 0 ? 'never' : op.refusals.map((code) => JSON.stringify(code)).join(' | ')};`,
+  );
+  const declared = document.operations.map(
+    (op) => `  ${propertyKey(op.name)}: ${JSON.stringify(op.refusals)},`,
+  );
+  const index = [
+    `// The client for ${document.title} ${document.version}: one method per published operation.`,
+    "import type * as T from './types';",
+    '',
+    CUSTOMER_RUNTIME,
+    '/** The codes each operation declares it may refuse with; `never` when it declares none. */',
+    'export interface Refusals {',
+    ...refusals,
+    '}',
+    '',
+    'const DECLARED: { readonly [K in keyof Refusals]: readonly string[] } = {',
+    ...declared,
+    '};',
+    '',
+    '/** The declared refusal `error` carries for `operation`, narrowed; `undefined` for anything else. */',
+    'export function refusalOf<K extends keyof Refusals>(error: unknown, operation: K): Refusals[K] | undefined {',
+    '  if (!(error instanceof ProblemError) || error.operation !== operation) return undefined;',
+    '  const code = error.code;',
+    '  return code !== undefined && DECLARED[operation].includes(code) ? (code as Refusals[K]) : undefined;',
+    '}',
+    '',
+    '/** One method per operation, named by its `operationId`. */',
+    'export function createClient(options: ClientOptions) {',
+    '  const send = sender(options);',
+    '  return {',
+    ...document.operations.map((op) => operationLine(document, op, names)),
+    '  };',
+    '}',
+    '',
+    'export type Client = ReturnType<typeof createClient>;',
+    '',
+  ].join('\n');
+  return { 'index.ts': index, 'types.ts': typesFile(document, names) };
+}

package/src/client-emit-drift.ts

@@ -0,0 +1,72 @@
+// The `drift` step's client rail: every file `x client` wrote, read back against its own stamp. A
+// source document whose content moved is `X_CLIENT_STALE`; a body whose bytes moved is
+// `X_CLIENT_EDITED`. The stamp is the convention's build error — no file is trusted on its name.
+
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, timingSafeEqual } from '@ultimat3/core';
+import { readStamp, STAMP_MARKER, sha256 } from './client-emit-header';
+import { sourceHash } from './cmd-client-source';
+import type { Finding } from './output';
+import { eachSourceFile, isVendored } from './source-files';
+
+/** Vendor clients live here; customer clients wherever `--out` put them inside the source globs. */
+const CLIENT_GLOB = 'apps/*/clients/**/*.ts';
+
+/** How much of a file is read to look for a stamp: the header is the first three lines. */
+const HEAD_BYTES = 600;
+
+async function candidates(root: string): Promise<readonly string[]> {
+  const paths = new Set<string>();
+  for await (const path of new Bun.Glob(CLIENT_GLOB).scan({ cwd: root, absolute: false })) {
+    if (!isVendored(path)) paths.add(path.replace(/\\/g, '/'));
+  }
+  for await (const path of eachSourceFile(root)) paths.add(path);
+  return [...paths].sort();
+}
+
+/** The source's hash now, or `undefined` when it is gone or no longer JSON. */
+async function currentHash(root: string, source: string): Promise<string | undefined> {
+  const file = Bun.file(join(root, source));
+  if (source === '' || !(await file.exists())) return undefined;
+  try {
+    return sourceHash(JSON.parse(await file.text()));
+  } catch {
+    // Unparseable is "not the document the client was compiled from" — the stale finding says so.
+    return undefined;
+  }
+}
+
+export async function checkClientDrift(root: string): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  const hashes = new Map<string, string | undefined>();
+  for (const path of await candidates(root)) {
+    const file = Bun.file(join(root, path));
+    if (!(await file.slice(0, HEAD_BYTES).text()).includes(STAMP_MARKER)) continue;
+    const read = readStamp(await file.text());
+    if (read === undefined) continue;
+    const { stamp, body } = read;
+    const fix = `${stamp.command === '' ? 'x client --help' : stamp.command} --json`;
+    if (!timingSafeEqual(sha256(body), stamp.bodyHash)) {
+      findings.push({
+        code: 'X_CLIENT_EDITED',
+        cause: `${path} no longer matches the hash in its own stamp: it was edited by hand, and the next regeneration discards that edit`,
+        fix: `${fix}   # then keep the change in a file of your own that wraps this client`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      });
+      continue;
+    }
+    if (!hashes.has(stamp.source)) hashes.set(stamp.source, await currentHash(root, stamp.source));
+    if (!timingSafeEqual(hashes.get(stamp.source) ?? '', stamp.sourceHash)) {
+      findings.push({
+        code: 'X_CLIENT_STALE',
+        cause: `${path} was compiled from a ${stamp.source} that has since changed, so it calls the old contract`,
+        fix,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      });
+    }
+  }
+  return findings;
+}

package/src/client-emit-header.ts

@@ -0,0 +1,67 @@
+// The stamp every file `x client` writes opens with: the command that regenerates it, the source
+// document and its hash, and the hash of the file's own body. The `drift` step reads it back — a
+// source that moved is `X_CLIENT_STALE`, a body that moved is `X_CLIENT_EDITED`.
+
+import { t } from '@ultimat3/schema';
+
+export const STAMP_MARKER = '// @x-client ';
+
+/** What a generated file says about itself. */
+export interface ClientStamp {
+  /** The invocation that writes this file again, flags included. */
+  readonly command: string;
+  /** App-root-relative path of the document it was compiled from. */
+  readonly source: string;
+  readonly sourceHash: string;
+  readonly bodyHash: string;
+}
+
+const stampSchema = t.object({
+  command: t.string,
+  source: t.string,
+  sourceHash: t.string,
+  bodyHash: t.string,
+});
+
+export const sha256 = (text: string): string =>
+  new Bun.CryptoHasher('sha256').update(text).digest('hex');
+
+const HEAD = (source: string): readonly string[] => [
+  '// biome-ignore-all format: generated by x client; its bytes are hashed in the stamp below',
+  `// GENERATED from ${source} by x client: never edit it, wrap it in a file of your own.`,
+];
+
+/** `body` with its header: the stamp names the hash of exactly the bytes after it. */
+export function stamped(stamp: Omit<ClientStamp, 'bodyHash'>, body: string): string {
+  const full: ClientStamp = { ...stamp, bodyHash: sha256(body) };
+  const ordered = {
+    command: full.command,
+    source: full.source,
+    sourceHash: full.sourceHash,
+    bodyHash: full.bodyHash,
+  };
+  return `${[...HEAD(stamp.source), `${STAMP_MARKER}${JSON.stringify(ordered)}`].join('\n')}\n${body}`;
+}
+
+/** The stamp and the body after it; `undefined` for a file `x client` did not write. */
+export function readStamp(
+  text: string,
+): { readonly stamp: ClientStamp; readonly body: string } | undefined {
+  const at = text.indexOf(STAMP_MARKER);
+  if (at < 0 || at > 400) return undefined;
+  const end = text.indexOf('\n', at);
+  if (end < 0) return undefined;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text.slice(at + STAMP_MARKER.length, end));
+  } catch {
+    // A marker whose JSON does not parse is a hand edit of the stamp itself: the body hash below
+    // cannot be read, so the file is reported as edited by the caller rather than skipped.
+    return { stamp: { command: '', source: '', sourceHash: '', bodyHash: '' }, body: '' };
+  }
+  const parsed = stampSchema.safeParse(raw);
+  if (!('value' in parsed)) {
+    return { stamp: { command: '', source: '', sourceHash: '', bodyHash: '' }, body: '' };
+  }
+  return { stamp: parsed.value as ClientStamp, body: text.slice(end + 1) };
+}