@ultimat3/cli 1.0.0

package/src/cmd-doctor.ts

@@ -0,0 +1,178 @@
+// `x doctor` — everything that makes an environment lie to you, checked in one pass. Every finding
+// carries the command that fixes it; a diagnostic that only describes a problem has handed the
+// work back to the reader.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { usesDevCursorSecret } from '@ultimat3/core';
+import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { ICON_SOURCE } from './dev-assets';
+import { checkDrift } from './drift';
+import { msg } from './messages';
+import type { CommandResult, Finding } from './output';
+import { flagString } from './parse';
+
+/**
+ * The injection seam `runDoctor` reads instead of the environment. Not a semver surface —
+ * `wiki/Upgrading.md` covers `X_*` codes, the eight primitive shapes, the `x` CLI surface, the
+ * tier table and `app.config.ts` fields, and not this — so a new fact the probe must report is a
+ * REQUIRED field: an optional one lets an implementation skip the check and still typecheck.
+ */
+export interface DoctorProbe {
+  readonly bunVersion: string;
+  /** App root, or undefined when the command runs outside an app. */
+  readonly root: string | undefined;
+  readonly port: number;
+  /** True while cursors are signed with the key shipped in the published package. */
+  readonly devCursorSecret: boolean;
+  /** True when this process believes it is serving real clients. */
+  readonly production: boolean;
+  exists(relativePath: string): boolean;
+  portFree(port: number): Promise<boolean>;
+  drift(): Promise<readonly Finding[]>;
+}
+
+const docs = (code: string): string => `https://ultimate.dev/errors/${code}`;
+
+const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
+  at === undefined
+    ? { code, cause, fix, docs: docs(code) }
+    : { code, cause, fix, docs: docs(code), at };
+
+export const OFFLINE_FALLBACK = 'apps/web/app/offline.tsx';
+
+/**
+ * Ordered cheapest-first so the first failure is usually the root cause: a wrong Bun explains
+ * every other symptom, and running outside an app explains the rest.
+ */
+export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]> {
+  const findings: Finding[] = [];
+  if (!versionAtLeast(probe.bunVersion, REQUIRED_BUN)) {
+    findings.push(
+      finding(
+        'X_BUN_VERSION',
+        `Bun ${probe.bunVersion} is older than the required ${REQUIRED_BUN}`,
+        'bun upgrade',
+      ),
+    );
+  }
+  if (probe.root === undefined) {
+    findings.push(
+      finding('X_NOT_IN_APP', 'no app.config.ts at or above the working directory', 'x new myapp'),
+    );
+    return findings;
+  }
+  if (!probe.exists('.env.development')) {
+    findings.push(
+      finding(
+        'X_ENV_MISSING',
+        '.env.development is missing, so committed defaults cannot be read',
+        'x new --force to restore the committed defaults, or create .env.development',
+        '.env.development',
+      ),
+    );
+  }
+  // Production only, and the gate is the point: every development environment signs with the
+  // shipped key on purpose — that is what lets `x dev` page with no configuration — so an
+  // unconditional finding would make `x doctor` red for every developer on day one and teach the
+  // reader to skim past the report. The key is a defect only where cursors reach real clients,
+  // who can read it out of the published package and forge a page position.
+  // Sits here because it costs two env reads and a comparison — cheaper than binding a port.
+  if (probe.production && probe.devCursorSecret) {
+    findings.push(
+      finding(
+        'X_CURSOR_SECRET_DEV',
+        'cursors are signed with the shipped development key, so a client can forge a page position',
+        'export ULTIMATE_CURSOR_SECRET="$(openssl rand -hex 32)"',
+      ),
+    );
+  }
+  if (!(await probe.portFree(probe.port))) {
+    findings.push(
+      finding(
+        'X_PORT_IN_USE',
+        `port ${probe.port} is already listening`,
+        `x dev --port ${probe.port + 1}`,
+      ),
+    );
+  }
+  // `@ultimat3/pwa`'s own codes, not CLI twins of them. `X_PWA_NO_ICON_SOURCE` and
+  // `X_PWA_NO_FALLBACK` used to be declared here for the same two conditions the package already
+  // names — two codes for one condition, one of them registered by nobody, so `x errors explain`
+  // answered for the package's and refused the CLI's.
+  if (!probe.exists(ICON_SOURCE)) {
+    findings.push(
+      finding(
+        'X_PWA_ICON_MISSING',
+        `${ICON_SOURCE} is missing, so install icons and og images cannot be generated`,
+        // An edit naming the file, in `@ultimat3/pwa`'s own words (`requireSourceIcon`). Not
+        // `x new`: it takes an app name and refuses to run inside the app that is missing the icon,
+        // so offering it here hands the reader a command that cannot work where they are standing.
+        `add a 1024x1024 square PNG at ${ICON_SOURCE}`,
+        ICON_SOURCE,
+      ),
+    );
+  }
+  if (!probe.exists(OFFLINE_FALLBACK)) {
+    findings.push(
+      finding(
+        'X_PWA_NO_OFFLINE_FALLBACK',
+        `${OFFLINE_FALLBACK} is missing, so an offline navigation falls back to the browser error page`,
+        'x g route offline --surface app',
+        OFFLINE_FALLBACK,
+      ),
+    );
+  }
+  findings.push(...(await probe.drift()));
+  return findings;
+}
+
+const portFree = async (port: number): Promise<boolean> => {
+  try {
+    const server = Bun.serve({ port, fetch: () => new Response('') });
+    await server.stop(true);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export function probeFor(cwd: string, bunVersion: string, port: number): DoctorProbe {
+  const root = findAppRoot(cwd)?.dir;
+  return {
+    bunVersion,
+    root,
+    port,
+    devCursorSecret: usesDevCursorSecret(),
+    // `X_ENV` first, then `NODE_ENV`: the order `@ultimat3/admin`'s dev-server guard already
+    // reads them in, and a second order would be a second convention.
+    production: (Bun.env['X_ENV'] ?? Bun.env['NODE_ENV']) === 'production',
+    exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
+    portFree,
+    drift: async () => (root === undefined ? [] : checkDrift(root)),
+  };
+}
+
+export const doctorCommand: CliCommand = {
+  spec: {
+    name: 'doctor',
+    summary: 'environment, versions, drift, ports, PWA prerequisites — each with a fix command',
+    usage: 'x doctor [--port 3000] [--json]',
+    flags: [{ name: 'port', type: 'string', summary: 'port to test', default: '3000' }],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const port = Number.parseInt(flagString(ctx.args, 'port') ?? '3000', 10);
+    const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
+    return {
+      ok: findings.length === 0,
+      command: 'doctor',
+      summary:
+        findings.length === 0
+          ? msg('cli.doctor.clean')
+          : msg('cli.doctor.findings', { count: findings.length }),
+      findings,
+      data: { count: findings.length, codes: findings.map((entry) => entry.code) },
+    };
+  },
+};

package/src/cmd-errors.ts

@@ -0,0 +1,99 @@
+// `x errors explain <CODE>` / `x errors list` — the error table, programmatically. An agent that
+// hits an `X_*` code should not have to leave the terminal to learn what it means, and a code it
+// invented should come back refused: the answer to an unregistered code is "no such code", never
+// a plausible-sounding explanation an agent would then act on.
+
+import type { ErrorExplanation } from '@ultimat3/mcp';
+import type { CliCommand, CommandContext } from './command';
+import type { ErrorCatalog } from './error-catalog';
+import { loadErrorCatalog } from './error-catalog';
+import { BadFlagError, ErrorCodeUnknownError } from './errors';
+import { explainErrorCode, explainEveryErrorCode } from './mcp-errors';
+import { msg } from './messages';
+import type { CommandResult, JsonValue } from './output';
+import { nearest } from './parse';
+
+export const ERRORS_SUBCOMMANDS = ['explain', 'list'] as const;
+
+const asJson = (explanation: ErrorExplanation): JsonValue => ({
+  code: explanation.code,
+  cause: explanation.cause,
+  fix: explanation.fix,
+  docs: explanation.docs,
+});
+
+/** The 3-line contract format, minus the leading blank code line `renderFinding` would add. */
+const detailLines = (explanation: ErrorExplanation): readonly string[] => [
+  `  cause: ${explanation.cause}`,
+  `  fix:   ${explanation.fix}`,
+  `  docs:  ${explanation.docs}`,
+];
+
+function explainOne(code: string): CommandResult {
+  const explanation = explainErrorCode(code);
+  if (explanation === undefined) {
+    const suggestion = nearest(
+      code,
+      explainEveryErrorCode().map((entry) => entry.code),
+    );
+    throw new ErrorCodeUnknownError(suggestion === undefined ? { code } : { code, suggestion });
+  }
+  return {
+    ok: true,
+    command: 'errors',
+    summary: msg('cli.errors.explained', { code: explanation.code, title: explanation.cause }),
+    lines: detailLines(explanation),
+    data: asJson(explanation),
+  };
+}
+
+/**
+ * A package that resolved and then threw is a defect, not a host gap: its codes are missing from
+ * this answer and something is broken that a `fix:` can address. Reported as findings — and `ok`
+ * goes false — so the incomplete catalog cannot read as a complete one.
+ */
+function listAll(catalog: ErrorCatalog): CommandResult {
+  const all = explainEveryErrorCode();
+  return {
+    ok: catalog.failed.length === 0,
+    command: 'errors',
+    summary: msg('cli.errors.count', { count: all.length }),
+    lines: all.map((entry) => `  ${entry.code.padEnd(30)} ${entry.cause}`),
+    findings: catalog.failed,
+    data: {
+      codes: all.map(asJson),
+      unavailable: [...catalog.unavailable],
+      failed: catalog.failed.map((finding) => ({
+        code: finding.code,
+        cause: finding.cause,
+        fix: finding.fix,
+        at: finding.at ?? null,
+      })),
+    },
+  };
+}
+
+export const errorsCommand: CliCommand = {
+  spec: {
+    name: 'errors',
+    summary: 'an X_* code, explained: cause, runnable fix, docs URL',
+    usage: 'x errors [explain <CODE>|list] [--json]',
+    subcommands: ERRORS_SUBCOMMANDS,
+  },
+  // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
+  // promise this signature promises, including the dispatcher's own error path.
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const catalog = await loadErrorCatalog();
+    if (ctx.args.subcommand === 'list') return listAll(catalog);
+    const code = ctx.args.positionals[0];
+    if (code === undefined) {
+      throw new BadFlagError({
+        flag: 'code',
+        command: 'errors',
+        reason: 'x errors explain <CODE> needs a code',
+        fix: 'x errors list --json',
+      });
+    }
+    return explainOne(code);
+  },
+};

package/src/cmd-fix.ts

@@ -0,0 +1,126 @@
+// `x fix boundary <file>` — the minimal cut for an import that crossed a surface boundary.
+// Analysis and a plan only: it never rewrites a file, and there is no `--write` flag
+// (`docs/architecture/02-boundaries.md`) — a caller runs the printed edit, or the generated
+// `git mv`, itself.
+
+import { appImportGraph, readAppSources } from './app-boundaries';
+import { requireAppRoot } from './app-root';
+import type { BoundaryCut } from './boundary-cuts';
+import { planBoundaryCuts } from './boundary-cuts';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, FixTargetUnknownError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { nearest } from './parse';
+
+export type { BoundaryCut };
+export { planBoundaryCuts };
+
+export const FIX_SUBCOMMANDS = ['boundary'] as const;
+
+const docsUrl = (code: string): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * Accept either an app-root-relative path or a suffix that matches exactly one scanned file —
+ * an agent copying the path out of a `fix:` line has the short form
+ * (`packages/render/README.md:89` emits exactly that shape).
+ */
+function resolveTarget(input: string, paths: readonly string[]): string {
+  const matches = paths.filter((path) => path === input || path.endsWith(`/${input}`));
+  if (matches.length > 1) {
+    throw new BadFlagError({
+      flag: 'file',
+      command: 'fix',
+      reason: `"${input}" matches ${matches.length} files: ${matches.join(', ')}`,
+    });
+  }
+  const [only] = matches;
+  if (only !== undefined) return only;
+  // Compare on the last segment too: a wrong directory is the common miss, and edit distance
+  // over the whole path would score every file in the right directory as equally far away.
+  const suggestion =
+    nearest(input, [...paths]) ??
+    paths.find((path) => path.split('/').at(-1) === input.split('/').at(-1));
+  throw new FixTargetUnknownError({
+    file: input,
+    scanned: paths.length,
+    ...(suggestion === undefined ? {} : { suggestion }),
+  });
+}
+
+const splitJson = (split: BoundaryCut['split']): JsonValue =>
+  split === null
+    ? null
+    : {
+        module: split.module,
+        surface: split.surface,
+        to: split.to,
+        command: split.command,
+        importers: split.importers,
+        // The human `edit` line names every specifier the move invalidates, so `--json` carries
+        // them structured — a plan an agent can apply without re-parsing the sentence.
+        edits: split.edits.map((edit) => ({
+          file: edit.file,
+          imported: edit.imported,
+          specifier: edit.specifier,
+        })),
+      };
+
+const cutJson = (cut: BoundaryCut): JsonValue => ({
+  code: cut.code,
+  rule: cut.rule,
+  entry: cut.entry,
+  at: cut.at,
+  edge: { from: cut.edge.from, to: cut.edge.to },
+  chain: cut.chain,
+  edit: cut.edit,
+  split: splitJson(cut.split),
+});
+
+const findingForCut = (cut: BoundaryCut): Finding => ({
+  code: cut.code,
+  cause: cut.cause,
+  fix: cut.edit,
+  docs: docsUrl(cut.code),
+  at: cut.at,
+});
+
+/** Distinct edges among the cuts — one edit can clear more than one flagged rule at once. */
+const editCount = (cuts: readonly BoundaryCut[]): number =>
+  new Set(cuts.map((cut) => JSON.stringify([cut.edge.from, cut.edge.to]))).size;
+
+export const fixCommand: CliCommand = {
+  spec: {
+    name: 'fix',
+    summary: 'the minimal cut for an import that crossed a surface boundary',
+    usage: 'x fix boundary <file> [--json]',
+    requiresApp: true,
+    subcommands: FIX_SUBCOMMANDS,
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('fix', ctx.cwd).dir;
+    const files = await readAppSources(root);
+    const target = resolveTarget(
+      ctx.args.positionals[0] ?? '',
+      files.map((file) => file.path),
+    );
+    const cuts = planBoundaryCuts(target, appImportGraph(files));
+
+    if (cuts.length === 0) {
+      return {
+        ok: true,
+        command: 'fix',
+        summary: msg('cli.fix.clean', { file: target }),
+        data: { file: target, cuts: [] },
+      };
+    }
+
+    return {
+      ok: false,
+      command: 'fix',
+      summary: msg('cli.fix.plan', { count: cuts.length, file: target, edits: editCount(cuts) }),
+      findings: cuts.map(findingForCut),
+      data: { file: target, cuts: cuts.map(cutJson) },
+    };
+  },
+};