@ultimat3/cli 29.3.2 → 30.0.0

package/src/cmd-ci.ts

@@ -4,12 +4,21 @@
 // command fetches the runs, opens only the failed steps' log, and hands back the findings the gate
 // already wrote — in the same three-line shape every other Ultimate error is printed in.
 
-import { UltimateError } from '@ultimat3/core';
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
 import type { CiLogLine } from './ci-log';
 import { findingKey, findingsFrom, jobsInLog, parseLogLines, tailOf } from './ci-log';
 import type { CiJob, CiRun } from './ci-runs';
 import { failedLog, isFailed, isRunning, latestPerWorkflow, listRuns, viewRun } from './ci-runs';
-import { CI_EVENTS, ciSpec, TAIL_LINES } from './cmd-ci-spec';
+import type { CiTestedAnswer, TestedCondition } from './ci-tested';
+import {
+  ciTested,
+  ghTestedReads,
+  TESTED_CALL_TIMEOUT_MS,
+  TESTED_CONDITIONS,
+  withDeadline,
+} from './ci-tested';
+import { CI_EVENTS, ciSpec, TAIL_LINES, TESTED_MAX_AGE, TESTED_WORKFLOW } from './cmd-ci-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
 import { parseIntFlag } from './flag-number';
@@ -40,6 +49,11 @@ export const CI_MESSAGE_KEYS = [
   'cli.ci.logs.empty',
 ] as const;
 
+/** One reason per `x ci tested` answer, keyed by the condition that decided it. */
+export const CI_TESTED_MESSAGE_KEYS = TESTED_CONDITIONS.map(
+  (condition) => `cli.ci.tested.${condition}` as const,
+);
+
 /** How far back a branch's run history is read before "the latest run of each workflow". */
 export const RUN_LOOKBACK = 20;
 
@@ -88,6 +102,7 @@ function readEvent(raw: string | undefined): (typeof CI_EVENTS)[number] | undefi
 export const ciCommand: CliCommand = {
   spec: ciSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
+    if (ctx.args.subcommand === 'tested') return tested(ctx);
     // Filters are validated, and crossed with --run, before any subprocess runs: a refusal must
     // not cost a gh round trip, and a filter beside --run would otherwise be silently ignored.
     const rawRun = flagString(ctx.args, 'run');
@@ -130,6 +145,88 @@ export const ciCommand: CliCommand = {
   },
 };
 
+/**
+ * `x ci tested`: may this push skip the jobs a green PR run already ran on this exact tree? Exit 0
+ * on every answer — the workflow reads `data.tested`, and a doubt anywhere (no `gh`, no remote, an
+ * API that did not answer) is `tested: false`, a full run. Only a malformed flag refuses.
+ */
+async function tested(ctx: CommandContext): Promise<CommandResult> {
+  const rawAge = flagString(ctx.args, 'max-age') ?? TESTED_MAX_AGE;
+  const maxAgeMs = readMaxAge(rawAge);
+  const workflow = flagString(ctx.args, 'workflow') ?? TESTED_WORKFLOW;
+  const flag = flagString(ctx.args, 'repo');
+  let repo = flag ?? '';
+  let sha = ctx.env['GITHUB_SHA'] ?? '';
+  let answer: CiTestedAnswer;
+  // Every subprocess this answer waits on is killed past its deadline, and that is a doubt too.
+  const host = { ...ctx, ...withDeadline(ctx, TESTED_CALL_TIMEOUT_MS) };
+  try {
+    const resolved = await resolveRepo(host, 'ci tested', flag);
+    repo = resolved.slug;
+    if (sha === '') sha = await headSha(host);
+    answer =
+      sha === ''
+        ? { tested: false, condition: 'sha' }
+        : await ciTested({
+            sha,
+            repo,
+            maxAgeMs,
+            now: Date.now(),
+            reads: ghTestedReads(host, resolved, workflow),
+          });
+  } catch (error) {
+    if (error instanceof BadFlagError) throw error;
+    answer = { tested: false, condition: 'api', detail: renderThrowable(error) };
+  }
+  const reason = testedReason(answer.condition, {
+    pr: answer.pr ?? '?',
+    run: answer.run ?? '?',
+    repo,
+    workflow,
+    maxAge: rawAge,
+    detail: answer.detail ?? '',
+  });
+  return {
+    ok: true,
+    command: 'ci',
+    summary: reason,
+    data: {
+      sha,
+      repo,
+      workflow,
+      tested: answer.tested,
+      condition: answer.condition,
+      reason,
+      ...(answer.pr === undefined ? {} : { pr: answer.pr }),
+      ...(answer.run === undefined ? {} : { run: answer.run }),
+    },
+  };
+}
+
+const testedReason = (
+  condition: TestedCondition,
+  params: Readonly<Record<string, string | number>>,
+): string => msg(`cli.ci.tested.${condition}`, params);
+
+function readMaxAge(raw: string): number {
+  try {
+    return parseDuration(raw);
+  } catch (error) {
+    throw new BadFlagError({
+      flag: 'max-age',
+      command: 'ci tested',
+      reason: `${quoteArg(raw)} is not a duration: ${renderThrowable(error)}`,
+      fix: 'x ci tested --max-age 24h --json',
+    });
+  }
+}
+
+/** The commit a local run asks about; none is a doubt, which the caller answers as one. */
+async function headSha(ctx: CommandContext): Promise<string> {
+  const result = await ctx.runner(['git', 'rev-parse', 'HEAD'], { cwd: ctx.cwd });
+  return result.ok ? result.stdout.trim() : '';
+}
+
 interface JobFailure {
   readonly job: string;
   readonly conclusion: string;

package/src/cmd-client-customer.ts

@@ -0,0 +1,134 @@
+// `x client customer` — the app's own published document (`openapi.json`, or a bearer mount's
+// declared file) compiled into a client a customer's TypeScript imports with no framework on its
+// path. Read from the COMMITTED file: what a customer is handed, and what `drift` hashes back.
+
+// why: Bun ships no path-join primitive.
+import { isAbsolute, join } from 'node:path';
+import { apiDeclaration } from '@ultimat3/action';
+import { loadApp } from './app-load';
+import { OPENAPI_FILE } from './app-openapi';
+import { requireAppRoot } from './app-root';
+import { emitCustomer } from './client-emit-customer';
+import { stamped } from './client-emit-header';
+import { parseSource, sourceHash } from './cmd-client-source';
+import { compileOrRefuse, writeFiles } from './cmd-client-write';
+import type { CommandContext } from './command';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagList, flagString } from './parse';
+import { posixRelative } from './posix-path';
+import { quoteArg } from './shell-quote';
+
+const COMMAND = 'client customer';
+
+/** The document's file: `openapi.json`, or the one a `--mount` declares as its own. */
+function documentFile(mount: string | undefined): string {
+  if (mount === undefined) return OPENAPI_FILE;
+  const mounts = apiDeclaration().http?.mounts ?? [];
+  const found = mounts.find((candidate) => candidate.prefix === mount);
+  if (found === undefined) {
+    throw new BadFlagError({
+      flag: 'mount',
+      command: COMMAND,
+      reason: `no bearer mount has the prefix ${quoteArg(mount)} (declared: ${mounts.map((m) => m.prefix).join(', ') || 'none'})`,
+      fix: 'x routes --json   # every mounted path; pass one of the declared prefixes',
+    });
+  }
+  if (found.openapi === undefined) {
+    throw new BadFlagError({
+      flag: 'mount',
+      command: COMMAND,
+      reason: `the mount ${quoteArg(mount)} declares no openapi file, so it publishes no document a client can be checked against`,
+      fix: `x manifest --json   # after adding openapi: 'openapi${mount.replace(/\//g, '.')}.json' to that mount in apps/web/api/index.ts`,
+    });
+  }
+  return found.openapi;
+}
+
+/** `{ name, version, exports }` — nothing a registry publish would need us to decide. */
+const packageJson = (name: string, version: string): string =>
+  `${JSON.stringify(
+    {
+      name,
+      version,
+      type: 'module',
+      exports: { '.': './index.ts', './types': './types.ts' },
+      files: ['index.ts', 'types.ts'],
+    },
+    null,
+    2,
+  )}\n`;
+
+export async function runCustomer(ctx: CommandContext): Promise<CommandResult> {
+  const root = requireAppRoot(COMMAND, ctx.cwd).dir;
+  const outFlag = flagString(ctx.args, 'out');
+  if (outFlag === undefined) {
+    throw new BadFlagError({
+      flag: 'out',
+      command: COMMAND,
+      reason: 'names no directory to write the client into',
+      fix: 'x client customer --out apps/web/clients/customer --json',
+    });
+  }
+  const out = posixRelative(root, isAbsolute(outFlag) ? outFlag : join(ctx.cwd, outFlag)) || '.';
+  const mount = flagString(ctx.args, 'mount');
+  const only = flagList(ctx.args, 'only');
+  const packageName = flagString(ctx.args, 'package');
+  // A mount's file is the app's declaration, so the app is loaded to read it; the plain document
+  // is `openapi.json` by definition and needs no load.
+  if (mount !== undefined) await loadApp(root);
+  const file = documentFile(mount);
+  const committed = Bun.file(join(root, file));
+  if (!(await committed.exists())) {
+    throw new BadFlagError({
+      flag: mount === undefined ? 'out' : 'mount',
+      command: COMMAND,
+      reason: `${file} has not been written, so there is no published document to compile`,
+      fix: 'x manifest --json',
+    });
+  }
+  const { document } = parseSource(await committed.text(), file);
+  const compiled = compileOrRefuse(document, file, only.length === 0 ? undefined : only, COMMAND);
+  const emitted = emitCustomer(compiled);
+  const flags = [
+    `--out ${quoteArg(out)}`,
+    ...(mount === undefined ? [] : [`--mount ${quoteArg(mount)}`]),
+    ...(only.length === 0 ? [] : [`--only ${only.join(',')}`]),
+    ...(packageName === undefined ? [] : [`--package ${quoteArg(packageName)}`]),
+  ];
+  const stamp = {
+    command: `x client customer ${flags.join(' ')}`,
+    source: file,
+    sourceHash: sourceHash(document),
+  };
+  const files = new Map([
+    [`${out}/types.ts`, stamped(stamp, emitted['types.ts'])],
+    [`${out}/index.ts`, stamped(stamp, emitted['index.ts'])],
+  ]);
+  if (packageName !== undefined) {
+    files.set(`${out}/package.json`, packageJson(packageName, compiled.version));
+  }
+  const written = await writeFiles(root, files);
+  return {
+    ok: true,
+    command: 'client',
+    summary: msg('cli.client.customer.written', {
+      operations: compiled.operations.length,
+      types: compiled.types.size,
+      source: file,
+      dir: out,
+    }),
+    lines: written.map((path) => msg('cli.client.file', { path })),
+    data: {
+      kind: 'customer',
+      dir: out,
+      source: file,
+      mount: mount ?? null,
+      only: only.length === 0 ? null : [...only],
+      operations: compiled.operations.map((op) => op.name),
+      types: compiled.types.size,
+      written: [...written],
+    },
+  };
+}

package/src/cmd-client-source.ts

@@ -0,0 +1,81 @@
+// Where `x client vendor` reads its document from: `--from` (a file, or an https URL read through
+// `outbound({ dial: 'public' })`), else the client's committed `source.json` — so a regeneration
+// with no flags is reproducible and offline. One parse, one canonical hash.
+
+// why: Bun ships no path-join primitive.
+import { isAbsolute, join } from 'node:path';
+import { renderFixShellArg } from '@ultimat3/core';
+import { outbound } from '@ultimat3/core/outbound';
+import { sha256 } from './client-emit-header';
+import { BadFlagError } from './errors';
+import { ClientSpecInvalidError } from './openapi-refuse';
+
+/** The longest a vendor's document may take to arrive. */
+export const SOURCE_DEADLINE_MS = 30_000;
+
+export interface ClientSource {
+  readonly document: unknown;
+  /** The document as committed: two-space JSON, so a regeneration rewrites the same bytes. */
+  readonly text: string;
+}
+
+/**
+ * The hash a stamp records: of the PARSED document, so reformatting `source.json` (an editor, the
+ * app's Biome) is not a change of contract — only a change of what it says is.
+ */
+export const sourceHash = (document: unknown): string => sha256(JSON.stringify(document));
+
+export function parseSource(raw: string, label: string): ClientSource {
+  let document: unknown;
+  try {
+    document = JSON.parse(raw);
+  } catch {
+    // The parser's own message names a character offset in a file the reader did not write.
+    throw new ClientSpecInvalidError({ source: label, reason: 'it is not JSON' });
+  }
+  return { document, text: `${JSON.stringify(document, null, 2)}\n` };
+}
+
+/** `--from` as given, or the committed copy at `committed` (app-root-relative). */
+export async function readClientSource(input: {
+  readonly from: string | undefined;
+  readonly cwd: string;
+  readonly root: string;
+  readonly committed: string;
+  readonly name: string;
+}): Promise<ClientSource> {
+  const { from } = input;
+  if (from === undefined) {
+    const file = Bun.file(join(input.root, input.committed));
+    if (!(await file.exists())) {
+      throw new BadFlagError({
+        flag: 'from',
+        command: 'client vendor',
+        reason: `${input.committed} does not exist yet, so there is no document to regenerate from`,
+        fix: `x client vendor ${renderFixShellArg(input.name, 'billing')} --from ./openapi.json --json   # the vendor's document, a file or an https URL`,
+      });
+    }
+    return parseSource(await file.text(), input.committed);
+  }
+  if (/^https?:\/\//.test(from)) {
+    const answer = await outbound({
+      url: from,
+      vendor: input.name,
+      dial: 'public',
+      deadlineMs: SOURCE_DEADLINE_MS,
+      headers: { accept: 'application/json' },
+    });
+    return parseSource(answer.text(), from);
+  }
+  const path = isAbsolute(from) ? from : join(input.cwd, from);
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new BadFlagError({
+      flag: 'from',
+      command: 'client vendor',
+      reason: `${from} does not exist`,
+      fix: `x client vendor ${renderFixShellArg(input.name, 'billing')} --from ./openapi.json --json   # a path from the current directory, or an https URL`,
+    });
+  }
+  return parseSource(await file.text(), from);
+}

package/src/cmd-client-spec.ts

@@ -0,0 +1,48 @@
+// `x client`'s declaration, apart from its body: the parser, `x help` and the `errors` step read it
+// without loading `cmd-client.ts`, which `registry.ts` imports only when the command runs.
+
+import type { CommandSpec } from './parse';
+
+export const CLIENT_SUBCOMMANDS = ['vendor', 'customer'] as const;
+
+export const clientSpec: CommandSpec = {
+  name: 'client',
+  summary:
+    'a typed client compiled from an OpenAPI document: a vendor you call, or the one your customers call you with',
+  usage:
+    'x client vendor <name> [--from <file|url>] [--only <tag,…>] [--json] · x client customer --out <dir> [--mount <prefix>] [--only <tag,…>] [--package <name>] [--json]',
+  requiresApp: true,
+  subcommands: [...CLIENT_SUBCOMMANDS],
+  // Both write files, into two different places: neither is a default a bare `x client` may pick.
+  flags: [
+    {
+      name: 'from',
+      type: 'string',
+      summary: "the document, a file or an https URL; omitted, the client's committed source.json",
+      subcommands: ['vendor'],
+    },
+    {
+      name: 'only',
+      type: 'string',
+      summary: 'keep only operations carrying one of these comma-separated tags',
+    },
+    {
+      name: 'out',
+      type: 'string',
+      summary: 'the directory the client is written to',
+      subcommands: ['customer'],
+    },
+    {
+      name: 'mount',
+      type: 'string',
+      summary: "a bearer mount's prefix — its own document, not the app's",
+      subcommands: ['customer'],
+    },
+    {
+      name: 'package',
+      type: 'string',
+      summary: 'also write a package.json with this name, ready to publish',
+      subcommands: ['customer'],
+    },
+  ],
+};

package/src/cmd-client-write.ts

@@ -0,0 +1,41 @@
+// The two halves both `x client` subcommands share: the compile, refused when `--only` keeps
+// nothing, and the write of every file a generation produces.
+
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { BadFlagError } from './errors';
+import { compileOpenApi } from './openapi-compile';
+import type { CompiledDocument } from './openapi-compile-ir';
+
+/** Where every vendor client lives, app-root-relative. */
+export const CLIENTS_DIR = 'apps/web/clients';
+
+/** The compile, refused when `--only` kept nothing: an empty client is a typo, not a client. */
+export function compileOrRefuse(
+  document: unknown,
+  source: string,
+  only: readonly string[] | undefined,
+  command: string,
+): CompiledDocument {
+  const compiled = compileOpenApi(document, { source, only });
+  if (only !== undefined && compiled.operations.length === 0) {
+    throw new BadFlagError({
+      flag: 'only',
+      command,
+      reason: `no operation in ${source} carries a tag in ${only.join(',')}`,
+      fix: 'x help client --json   # then rerun without --only, and pick tags from the operations it lists',
+    });
+  }
+  return compiled;
+}
+
+/** Writes every file (`Bun.write` makes the directories); answers the app-root-relative paths written. */
+export async function writeFiles(
+  root: string,
+  files: ReadonlyMap<string, string>,
+): Promise<readonly string[]> {
+  for (const [path, text] of files) {
+    await Bun.write(join(root, path), text);
+  }
+  return [...files.keys()];
+}

package/src/cmd-client.ts

@@ -0,0 +1,111 @@
+// `x client` — one OpenAPI compiler, two emitters. `vendor <name>` compiles a third party's
+// document into `apps/web/clients/<name>/` (outbound() and `t` schemas); `customer --out <dir>`
+// compiles the app's own published document into a client with no framework import at all.
+//
+// CLI wiring only: the compiler is `openapi-compile.ts`, the bytes are `client-emit-*.ts`.
+
+// why: Bun ships no path-join primitive.
+import { isAbsolute, join } from 'node:path';
+import { requireAppRoot } from './app-root';
+import { readStamp, stamped } from './client-emit-header';
+import { emitVendor } from './client-emit-vendor';
+import { runCustomer } from './cmd-client-customer';
+import { readClientSource, sourceHash } from './cmd-client-source';
+import { clientSpec } from './cmd-client-spec';
+import { CLIENTS_DIR, compileOrRefuse, writeFiles } from './cmd-client-write';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, MissingPositionalError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagList, flagString } from './parse';
+import { posixRelative } from './posix-path';
+import { quoteArg } from './shell-quote';
+
+const VENDOR_NAME = /^[a-z][a-z0-9-]{0,63}$/;
+
+/** `--only`, or — on a regeneration that passes none — the tags the client was generated with. */
+async function onlyFor(
+  ctx: CommandContext,
+  existing: string,
+): Promise<readonly string[] | undefined> {
+  const given = flagList(ctx.args, 'only');
+  if (given.length > 0) return given;
+  const file = Bun.file(existing);
+  if (!(await file.exists())) return undefined;
+  const stamp = readStamp(await file.text())?.stamp;
+  const kept = stamp === undefined ? undefined : /(?:^| )--only (\S+)/.exec(stamp.command)?.[1];
+  return kept === undefined ? undefined : kept.split(',').filter((tag) => tag.length > 0);
+}
+
+async function runVendor(ctx: CommandContext): Promise<CommandResult> {
+  const root = requireAppRoot('client vendor', ctx.cwd).dir;
+  const name = ctx.args.positionals[0];
+  if (name === undefined) {
+    throw new MissingPositionalError({
+      command: 'client vendor',
+      positional: 'name',
+      example: 'x client vendor billing --from ./openapi.json --json',
+    });
+  }
+  if (!VENDOR_NAME.test(name)) {
+    throw new BadFlagError({
+      flag: 'name',
+      command: 'client vendor',
+      reason: `${quoteArg(name)} is not a lower-case slug (a-z, 0-9, -), so it cannot name a directory and a vendor label`,
+      fix: 'x client vendor billing --from ./openapi.json --json',
+    });
+  }
+  const dir = `${CLIENTS_DIR}/${name}`;
+  const committed = `${dir}/source.json`;
+  const fromFlag = flagString(ctx.args, 'from');
+  const from =
+    fromFlag === undefined || isAbsolute(fromFlag) || /^https?:/.test(fromFlag)
+      ? fromFlag
+      : posixRelative(root, join(ctx.cwd, fromFlag));
+  const source = await readClientSource({ from: fromFlag, cwd: ctx.cwd, root, committed, name });
+  const only = await onlyFor(ctx, join(root, dir, 'client.ts'));
+  const compiled = compileOrRefuse(source.document, from ?? committed, only, 'client vendor');
+  const emitted = emitVendor(name, compiled);
+  const stamp = {
+    command: `x client vendor ${name}${only === undefined ? '' : ` --only ${only.join(',')}`}`,
+    source: committed,
+    sourceHash: sourceHash(source.document),
+  };
+  const written = await writeFiles(
+    root,
+    new Map([
+      [committed, source.text],
+      [`${dir}/schemas.ts`, stamped(stamp, emitted['schemas.ts'])],
+      [`${dir}/client.ts`, stamped(stamp, emitted['client.ts'])],
+    ]),
+  );
+  return {
+    ok: true,
+    command: 'client',
+    summary: msg('cli.client.vendor.written', {
+      name,
+      operations: compiled.operations.length,
+      types: compiled.types.size,
+      source: from ?? committed,
+      dir,
+    }),
+    lines: written.map((path) => msg('cli.client.file', { path })),
+    data: {
+      kind: 'vendor',
+      name,
+      dir,
+      source: committed,
+      only: only === undefined ? null : [...only],
+      operations: compiled.operations.map((op) => op.name),
+      types: compiled.types.size,
+      written: [...written],
+    },
+  };
+}
+
+export const clientCommand: CliCommand = {
+  spec: clientSpec,
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    return ctx.args.subcommand === 'customer' ? runCustomer(ctx) : runVendor(ctx);
+  },
+};

package/src/cmd-db-recount.ts

@@ -0,0 +1,120 @@
+// `x db recount <entity>.<column>`: the counters `countedIn` declares, compared with the truth and
+// — with `--write` — set to it. A counter drifts only when its trigger was missing or disabled
+// (`X_LIFECYCLE_TRIGGER_MISSING`); this is the repair, and the dry run is the report.
+
+import {
+  CROSS_TENANT_SETTING,
+  raw,
+  recountDriftSql,
+  recountSql,
+  setLocal,
+  withTransaction,
+} from '@ultimat3/db';
+import { countersOf, describeCounter, getEntity } from '@ultimat3/entity';
+import { loadApp } from './app-load';
+import type { CommandContext } from './command';
+import { DevAlreadyRunningError, liveDevLock } from './dev-lock';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool } from './parse';
+import { resolveServices } from './runtime-bindings';
+import { startDb } from './runtime-queue';
+import { quoteArg } from './shell-quote';
+
+/** Rows of drift a report lists; the count is always whole. */
+const SHOWN = 50;
+
+interface DriftRow {
+  readonly key: string;
+  readonly stored: number;
+  readonly actual: number;
+}
+
+const refuse = (target: string, reason: string): never => {
+  throw new BadFlagError({
+    flag: 'name',
+    command: 'db recount',
+    reason: `"${target}" ${reason}`,
+    fix: 'x entities list --json   # then x db recount <entity>.<column> naming a countedIn column',
+  });
+};
+
+/** `<entity>.<column>` to the one counter it names, after the app's modules declared them. */
+function counterNamed(target: string) {
+  const [name, column, ...rest] = target.split('.');
+  if (name === undefined || column === undefined || rest.length > 0) {
+    return refuse(target, 'is not <entity>.<column>');
+  }
+  const parent = getEntity(name)?.core;
+  if (parent === undefined) return refuse(target, `names no entity "${name}"`);
+  const counter = countersOf(parent).find((each) => each.column === column);
+  if (counter === undefined)
+    return refuse(target, `names no column any countedIn keeps on ${name}`);
+  return { parent, counter: describeCounter(counter) };
+}
+
+export async function runRecountCommand(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const target = ctx.args.positionals[0];
+  if (target === undefined) return refuse('', 'is missing: name the counter as <entity>.<column>');
+  const { findings } = await loadApp(root);
+  const { parent, counter } = counterNamed(target);
+  const write = flagBool(ctx.args, 'write');
+  const services = resolveServices(root, ctx.env);
+  if (services.db.mode === 'embedded') {
+    const holder = liveDevLock(services.stateDir);
+    if (holder !== undefined) {
+      throw new DevAlreadyRunningError({
+        lock: holder,
+        stateDir: services.stateDir,
+        embeddedDb: true,
+      });
+    }
+  }
+  const started = startDb(services, ctx.env);
+  try {
+    // One transaction, cross-tenant: a counter is every tenant's, and under forced row security an
+    // unset tenant would match no row.
+    const drift = await withTransaction(
+      async (tx) => {
+        await setLocal(tx, { [CROSS_TENANT_SETTING]: 'on' });
+        const rows = await tx.query<DriftRow>(raw(recountDriftSql(parent.$table, counter)));
+        if (write && rows.length > 0) await tx.execute(raw(recountSql(parent.$table, counter)));
+        return rows;
+      },
+      { client: started.client },
+    );
+    return {
+      ok: findings.length === 0 && (write || drift.length === 0),
+      command: 'db',
+      summary: msg(write ? 'cli.db.recount.repaired' : 'cli.db.recount.drift', {
+        target,
+        count: drift.length,
+      }),
+      findings: [
+        ...findings,
+        ...(write || drift.length === 0
+          ? []
+          : [
+              {
+                code: 'X_LIFECYCLE_TRIGGER_MISSING',
+                cause: `${drift.length} row(s) of ${parent.$table} hold a ${counter.column} that is not the count of ${counter.table} rows pointing at them`,
+                fix: `x db recount ${quoteArg(target)} --write --json`,
+              },
+            ]),
+      ],
+      lines: drift
+        .slice(0, SHOWN)
+        .map((row) => `  ${row.key}  stored ${row.stored}  actual ${row.actual}`),
+      data: {
+        target,
+        write,
+        drifted: drift.length,
+        rows: drift.slice(0, SHOWN).map((row) => ({ ...row })),
+      },
+    };
+  } finally {
+    await started.client.close();
+    await started.replica?.close();
+  }
+}