@ultimat3/cli 1.0.0

package/src/dev-traces.ts

@@ -0,0 +1,141 @@
+// The `/_x` timeline panel's source: core's own spans, recorded in this process. `x dev` installs
+// the exporter at boot, so every `withSpan` the framework already opens — the request, the action,
+// the query, the cache bust — arrives here and is assembled back into the tree the flame draws.
+// A tracer written here instead would be a second one, disagreeing with `x trace` by construction.
+
+import type { RequestTrace, SpanKind, TimelineSpan } from '@ultimat3/admin/dev';
+import type { ReadableSpan, SpanExporter } from '@ultimat3/core';
+
+/** Traces retained. A dev panel shows recent requests; it does not page through history. */
+const DEFAULT_LIMIT = 50;
+
+export interface TraceRecorder {
+  /** Hand this to `configureTelemetry({ exporter })`. */
+  readonly exporter: SpanExporter;
+  /** Complete request traces, newest first. */
+  traces(): readonly RequestTrace[];
+  reset(): void;
+}
+
+/**
+ * Span name → the vocabulary the panel renders. The framework's span names are prefixed by the
+ * subsystem that opened them (`action.publishPost`, `query.feed`, `cache.invalidate`), so the
+ * prefix IS the kind — no registry of names to keep in step with the packages that emit them.
+ */
+const KIND_BY_PREFIX: readonly (readonly [string, SpanKind])[] = [
+  ['query.', 'sql'],
+  ['cache.', 'cache'],
+  ['action.', 'action'],
+  ['policy.', 'policy'],
+  ['job.', 'job'],
+  ['render.', 'render'],
+];
+
+function kindOf(name: string, isRoot: boolean): SpanKind {
+  if (isRoot) return 'http';
+  for (const [prefix, kind] of KIND_BY_PREFIX) {
+    if (name.startsWith(prefix)) return kind;
+  }
+  // Everything the framework opens carries a prefix; anything else came from app code, which is
+  // work the request did — filed under `action` rather than dropped from the flame it happened in.
+  return 'action';
+}
+
+const attrString = (span: ReadableSpan, key: string): string | undefined => {
+  const value = span.attributes[key];
+  return typeof value === 'string' ? value : undefined;
+};
+
+const attrNumber = (span: ReadableSpan, key: string): number | undefined => {
+  const value = span.attributes[key];
+  return typeof value === 'number' ? value : undefined;
+};
+
+/**
+ * The pipeline names its root span `<METHOD> <path>` and tags it with `http.*`. Reading the
+ * attributes first and the name only as a fallback keeps the panel working against a root span
+ * from any host, while still preferring the facts the pipeline states outright.
+ */
+function requestFacts(root: ReadableSpan): { method: string; path: string } {
+  const [namedMethod = '', namedPath = ''] = root.name.split(' ');
+  return {
+    method: attrString(root, 'http.method') ?? namedMethod,
+    path: attrString(root, 'http.route') ?? namedPath,
+  };
+}
+
+const isHttpRoot = (span: ReadableSpan): boolean =>
+  span.parentSpanId === undefined &&
+  (span.attributes['http.request_id'] !== undefined || /^[A-Z]+ \//.test(span.name));
+
+function toTrace(root: ReadableSpan, spans: readonly ReadableSpan[]): RequestTrace {
+  const { method, path } = requestFacts(root);
+  const origin = root.startedAt;
+  return {
+    requestId: attrString(root, 'http.request_id') ?? root.context.traceId,
+    method,
+    path,
+    status: attrNumber(root, 'http.status_code') ?? 0,
+    startedAt: new Date(origin).toISOString(),
+    totalMs: root.durationMs,
+    spans: spans
+      .map(
+        (span): TimelineSpan => ({
+          id: span.context.spanId,
+          // The root anchors the flame at depth 0, so its parent is null even though the span
+          // itself may have arrived with a parent from an inbound `traceparent`.
+          parentId: span === root ? null : (span.parentSpanId ?? null),
+          kind: kindOf(span.name, span === root),
+          name: span.name,
+          startMs: Math.max(0, span.startedAt - origin),
+          durationMs: span.durationMs,
+          // The panel counts repeats of `detail` to find the N+1, and a framework span's name is
+          // exactly the identity that repeats — `query.feed` twice is two reads of one query.
+          detail: attrString(span, 'db.statement') ?? span.name,
+        }),
+      )
+      .sort((a, b) => a.startMs - b.startMs),
+  };
+}
+
+/**
+ * Spans end innermost-first, so a trace is only whole once its root arrives — which is also the
+ * moment the request finished. Grouping by trace id and reporting only groups that have an HTTP
+ * root is what keeps a half-finished request, and a job's spans, out of a panel about requests.
+ */
+export function createTraceRecorder(options: { limit?: number } = {}): TraceRecorder {
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  // Insertion-ordered: the oldest trace id is the first key, which is the one eviction drops.
+  const byTrace = new Map<string, ReadableSpan[]>();
+
+  const record = (span: ReadableSpan): void => {
+    const traceId = span.context.traceId;
+    const spans = byTrace.get(traceId);
+    if (spans === undefined) {
+      byTrace.set(traceId, [span]);
+      // Bounded by trace, not by span: dropping half a request would leave a flame with holes.
+      while (byTrace.size > limit) {
+        const oldest = byTrace.keys().next();
+        if (oldest.done === true) break;
+        byTrace.delete(oldest.value);
+      }
+      return;
+    }
+    spans.push(span);
+  };
+
+  return {
+    exporter: { export: record },
+    traces(): readonly RequestTrace[] {
+      const traces: RequestTrace[] = [];
+      for (const spans of byTrace.values()) {
+        const root = spans.find(isHttpRoot);
+        if (root !== undefined) traces.push(toTrace(root, spans));
+      }
+      return traces.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+    },
+    reset(): void {
+      byTrace.clear();
+    },
+  };
+}

package/src/dispatch.ts

@@ -0,0 +1,98 @@
+// The one place the CLI does I/O: parse, run, render, exit. Commands return data; this decides
+// whether it is printed as text or JSON and what the process exits with. Errors take the same
+// path as results, so a failure is machine-readable exactly like a success.
+
+import { isAbsolute, resolve } from 'node:path';
+import { requireBunVersion } from './app-root';
+import { createHelpCommand } from './cmd-help';
+import type { CommandContext } from './command';
+import { UnknownCommandError } from './errors';
+import type { Runner } from './exec';
+import { exec } from './exec';
+import type { CommandResult } from './output';
+import { exitCodeFor, findingFrom, render } from './output';
+import type { ParsedArgs } from './parse';
+import { parseArgs } from './parse';
+import { commandFor, SPECS } from './registry';
+
+export interface DispatchOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly bunVersion: string;
+  readonly runner?: Runner;
+  readonly write: (line: string) => void;
+}
+
+const resolveCwd = (cwd: string, flag: string | undefined): string => {
+  if (flag === undefined) return cwd;
+  return isAbsolute(flag) ? flag : resolve(cwd, flag);
+};
+
+const errorResult = (command: string, error: unknown): CommandResult => ({
+  ok: false,
+  command,
+  summary: 'command failed',
+  findings: [findingFrom(error)],
+  exitCode: 1,
+});
+
+/**
+ * Returns the exit code instead of calling process.exit, so a test can drive the whole CLI end to
+ * end without terminating the test runner.
+ */
+export async function dispatch(options: DispatchOptions): Promise<number> {
+  let args: ParsedArgs;
+  try {
+    requireBunVersion(options.bunVersion);
+    args = parseArgs(options.argv, SPECS);
+  } catch (error) {
+    const result = errorResult('x', error);
+    options.write(render(result, options.argv.includes('--json')));
+    return 1;
+  }
+
+  const command = commandFor(args.command);
+  if (command === undefined) {
+    const result = errorResult(
+      args.command,
+      new UnknownCommandError({
+        path: args.command,
+        known: SPECS.map((spec) => spec.name),
+      }),
+    );
+    options.write(render(result, args.json));
+    return 1;
+  }
+
+  // `--help` on any command is answered by help itself, never by the command's own branch.
+  const target = args.help ? createHelpCommand(() => SPECS) : command;
+  const helpArgs: ParsedArgs = args.help
+    ? { ...args, command: 'help', positionals: [args.command] }
+    : args;
+
+  const ctx: CommandContext = {
+    args: helpArgs,
+    cwd: resolveCwd(
+      options.cwd,
+      typeof args.flags.get('cwd') === 'string' ? String(args.flags.get('cwd')) : undefined,
+    ),
+    runner: options.runner ?? exec,
+    env: options.env,
+    bunVersion: options.bunVersion,
+  };
+
+  try {
+    const result = await target.run(ctx);
+    options.write(render(result, args.json, args.flags.get('verbose') === true));
+    // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the
+    // url is on stdout the moment it is reachable, then stay in the process until the drain that
+    // stops them. Without this the exit code below is what takes the server down.
+    await result.hold?.();
+    return exitCodeFor(result);
+  } catch (error) {
+    const result = errorResult(args.command, error);
+    options.write(render(result, args.json));
+    return 1;
+  }
+}

package/src/drift.ts

@@ -0,0 +1,86 @@
+// Migration drift detection. `x db gen` records the hash of the app's entity schema next to the
+// migration it produced; drift is "the schema hashes to something no migration recorded". The
+// hash file is committed beside the migration, so a fresh clone can detect drift with no local
+// state and CI needs no database to answer the question.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Finding } from './output';
+
+export const DB_PACKAGE = join('packages', 'db');
+export const MIGRATIONS_DIR = join(DB_PACKAGE, 'migrations');
+const SCHEMA_GLOB = 'packages/db/src/**/*.ts';
+
+/** Content hash of the whole schema, order-independent per file path. */
+export async function schemaHash(root: string): Promise<string> {
+  const glob = new Bun.Glob(SCHEMA_GLOB);
+  const paths: string[] = [];
+  for await (const path of glob.scan({ cwd: root, absolute: false })) {
+    if (!path.includes('.test.')) paths.push(path);
+  }
+  paths.sort();
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const path of paths) {
+    hasher.update(path);
+    hasher.update(await Bun.file(join(root, path)).text());
+  }
+  return hasher.digest('hex').slice(0, 16);
+}
+
+export interface MigrationRecord {
+  readonly file: string;
+  readonly hash: string;
+}
+
+/** Every `<n>_<name>.hash` sidecar, sorted by filename so the last entry is the newest. */
+export async function recordedHashes(root: string): Promise<readonly MigrationRecord[]> {
+  const dir = join(root, MIGRATIONS_DIR);
+  if (!existsSync(dir)) return [];
+  const glob = new Bun.Glob('*.hash');
+  const files: string[] = [];
+  for await (const file of glob.scan({ cwd: dir, absolute: false })) files.push(file);
+  files.sort();
+  const out: MigrationRecord[] = [];
+  for (const file of files) {
+    out.push({ file, hash: (await Bun.file(join(dir, file)).text()).trim() });
+  }
+  return out;
+}
+
+export async function writeSchemaHash(root: string, migrationName: string): Promise<string> {
+  const hash = await schemaHash(root);
+  await Bun.write(join(root, MIGRATIONS_DIR, `${migrationName}.hash`), `${hash}\n`);
+  return hash;
+}
+
+/**
+ * Empty result = no drift. A missing db package is not drift (an app may have no database yet);
+ * a schema with no migration at all is.
+ */
+export async function checkDrift(root: string): Promise<readonly Finding[]> {
+  if (!existsSync(join(root, DB_PACKAGE))) return [];
+  const current = await schemaHash(root);
+  const records = await recordedHashes(root);
+  const latest = records.at(-1);
+  if (latest === undefined) {
+    return [
+      {
+        code: 'X_DB_DRIFT',
+        cause: 'packages/db has a schema but no migration recorded it',
+        fix: 'x db gen "initial"',
+        docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+        at: MIGRATIONS_DIR,
+      },
+    ];
+  }
+  if (records.some((record) => record.hash === current)) return [];
+  return [
+    {
+      code: 'X_DB_DRIFT',
+      cause: `schema hashes to ${current}, newest migration ${latest.file} recorded ${latest.hash}`,
+      fix: 'x db gen "describe the change"',
+      docs: 'https://ultimate.dev/errors/X_DB_DRIFT',
+      at: `${DB_PACKAGE}/src`,
+    },
+  ];
+}

package/src/error-catalog.ts

@@ -0,0 +1,156 @@
+// Every framework package's error codes, present in this process before `x errors` answers.
+// A package registers its titles when it is imported, and the CLI only imports the packages its
+// commands actually need — so without this, `x errors explain X_UNAUTHENTICATED` answered "not a
+// registered error code" for a code the framework throws on every unauthenticated request.
+
+import { listErrorCodes, registerErrorCodes } from '@ultimat3/core';
+import { SCHEMA_ERROR_CODES } from '@ultimat3/schema';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/**
+ * Every `@ultimat3/*` package that owns `X_*` codes, `cli` excluded — `errors.ts` registers its
+ * own at import. Importing one already in the graph is a module-cache hit, so the list needs no
+ * knowledge of which commands pulled what. `error-catalog.test.ts` asserts it against the
+ * workspace, which is what stops a new package from silently missing its codes.
+ */
+export const CATALOG_PACKAGES = [
+  '@ultimat3/action',
+  '@ultimat3/admin',
+  '@ultimat3/ai',
+  '@ultimat3/auth',
+  '@ultimat3/cache',
+  '@ultimat3/core',
+  '@ultimat3/db',
+  '@ultimat3/entity',
+  '@ultimat3/http',
+  '@ultimat3/i18n',
+  '@ultimat3/jobs',
+  '@ultimat3/mail',
+  '@ultimat3/manifest',
+  '@ultimat3/mcp',
+  '@ultimat3/money',
+  '@ultimat3/policy',
+  '@ultimat3/pwa',
+  '@ultimat3/query',
+  '@ultimat3/realtime',
+  '@ultimat3/render',
+  '@ultimat3/schema',
+  '@ultimat3/seo',
+  '@ultimat3/storage',
+  '@ultimat3/testing',
+  '@ultimat3/time',
+  '@ultimat3/ui',
+] as const;
+
+export interface ErrorCatalog {
+  /** Packages whose codes are now registered. */
+  readonly loaded: readonly string[];
+  /**
+   * Packages this process could not *resolve*, so their codes are absent from the answer. The one
+   * tolerated case is the optional host: `@ultimat3/ui` and `@ultimat3/admin` reach for a JSX
+   * runtime an app has and a bare CLI process does not, and a list silently missing their codes is
+   * worse than one that says which packages are missing. A package that resolved and then threw is
+   * a defect, not a host gap, and goes to `failed`.
+   */
+  readonly unavailable: readonly string[];
+  /**
+   * Packages that resolved and threw while initializing — a duplicate code, an invalid
+   * registration, a module that cannot evaluate. Carried with the thrown error's own code, cause
+   * and fix so `x errors` reports them as findings: reporting a package defect as merely
+   * "unavailable" is a partial catalog with no cause and nothing to run.
+   */
+  readonly failed: readonly Finding[];
+}
+
+let cached: Promise<ErrorCatalog> | undefined;
+let schemaRegistered = false;
+
+/**
+ * `@ultimat3/schema` is tier 0 alongside `core`, so it cannot register its own codes — it exports
+ * the declarations and names the CLI as the package that may import both tiers. This is that, in
+ * one unguarded call: a `hasErrorCode()` skip would swallow the exact collision
+ * `registerErrorCodes` raises `X_ERROR_CODE_DUPLICATE` for, and `x errors` would then explain a
+ * schema code with whatever title the package that claimed it first gave it. Once per process,
+ * because the code registry is process-global while this module's cache is not.
+ */
+function registerSchemaCodes(): void {
+  if (schemaRegistered) return;
+  schemaRegistered = true;
+  registerErrorCodes(SCHEMA_ERROR_CODES);
+}
+
+/**
+ * Bun reports an unresolvable specifier as a `ResolveMessage` carrying `ERR_MODULE_NOT_FOUND` —
+ * the host gap. Anything else escaped the package's own module evaluation and is its defect.
+ */
+const isUnresolved = (thrown: unknown): boolean =>
+  typeof thrown === 'object' &&
+  thrown !== null &&
+  'code' in thrown &&
+  thrown.code === 'ERR_MODULE_NOT_FOUND';
+
+/** The package's own error, named and located, so the report says what broke and what to run. */
+function initFailure(specifier: string, thrown: unknown): Finding {
+  const finding = findingFrom(thrown);
+  return {
+    ...finding,
+    cause: `${specifier} failed to initialize: ${finding.cause}`,
+    at: specifier,
+  };
+}
+
+/**
+ * Test seam: the catalog over an injected loader. `loadErrorCatalog()` hands it `import()`; a test
+ * hands it one that throws, which is the only way to reach the failure paths in a repo where every
+ * package initializes.
+ */
+export async function buildErrorCatalog(
+  load: (specifier: string) => Promise<unknown>,
+): Promise<ErrorCatalog> {
+  const loaded: string[] = [];
+  const unavailable: string[] = [];
+  const failed: Finding[] = [];
+  await Promise.all(
+    CATALOG_PACKAGES.map(async (specifier) => {
+      try {
+        await load(specifier);
+        loaded.push(specifier);
+      } catch (thrown) {
+        if (isUnresolved(thrown)) unavailable.push(specifier);
+        else failed.push(initFailure(specifier, thrown));
+      }
+    }),
+  );
+  return {
+    loaded: loaded.sort(),
+    unavailable: unavailable.sort(),
+    failed: failed.sort((a, b) => (a.at ?? '').localeCompare(b.at ?? '')),
+  };
+}
+
+async function importAll(): Promise<ErrorCatalog> {
+  registerSchemaCodes();
+  return buildErrorCatalog((specifier) => import(specifier));
+}
+
+/** Memoised: the registry is process-global, so the imports are worth paying for exactly once. */
+export function loadErrorCatalog(): Promise<ErrorCatalog> {
+  cached ??= importAll();
+  return cached;
+}
+
+/** Test seam — the counterpart to every other reset in this package. */
+export function resetErrorCatalog(): void {
+  cached = undefined;
+}
+
+/**
+ * Every code `x errors explain` can answer for, as a set. The `errors` step checks the reference
+ * page against exactly this: a documented code missing from here is one an agent can read but not
+ * look up. Loads the catalog first, so the answer does not depend on which commands ran before it.
+ */
+export async function registeredErrorCodes(): Promise<ReadonlySet<string>> {
+  await loadErrorCatalog();
+  return new Set(listErrorCodes().map((entry) => entry.code));
+}