@ultimat3/cli 1.0.0

package/src/cmd-verify.ts

@@ -0,0 +1,265 @@
+// `x verify` — the contract. Every check is a named step with its own pass/fail and duration, the
+// same list in the terminal and in --json, and a non-zero exit if any step fails. Green means
+// shippable (axiom 5): one step list, no second checklist, no CI-only step, and no way to narrow
+// the run — `--only` and `--skip` would make "green" mean whatever the caller chose.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Manifest } from '@ultimat3/manifest';
+import {
+  AGENTS_MD_FILENAME,
+  assertNoDrift,
+  MANIFEST_FILENAME,
+  verifyContract,
+} from '@ultimat3/manifest';
+import { checkAgentsMd } from './app-agents-md';
+import { checkAppBoundaries } from './app-boundaries';
+import { appManifest, readAppManifest } from './app-manifest';
+import { OPENAPI_FILE, openApiJson } from './app-openapi';
+import { APP_CONFIG_FILE, requireAppRoot } from './app-root';
+import { checkBudgets, readBuildStats } from './budgets';
+import type { CliCommand, CommandContext } from './command';
+import { checkDrift } from './drift';
+import { checkErrorFixes } from './error-contract';
+import { msg } from './messages';
+import type { CommandResult, Finding, StepResult } from './output';
+import { findingFrom } from './output';
+import type { StepOutcome, VerifyContext, VerifyStep, VerifyStepName } from './verify-step';
+import { fromExec, fromFindings, hostFindings, passed } from './verify-step';
+import { TEST_STEPS } from './verify-tests';
+import { checkFileSizes, checkPackageShape, hasWorkspacePackages } from './workspace-checks';
+
+/** The whole contract, in cost order. Every check the framework knows how to make lives here. */
+export const VERIFY_STEPS: readonly VerifyStep[] = [
+  {
+    name: 'typecheck',
+    summary: 'tsc -b across every project the root references',
+    async run(ctx) {
+      const result = await ctx.runner(['bunx', 'tsc', '-b', '--pretty', 'false'], {
+        cwd: ctx.root,
+      });
+      return fromExec(result, {
+        code: 'X_TYPECHECK_FAILED',
+        cause: 'the project does not typecheck',
+        fix: 'bunx tsc -b --pretty false',
+      });
+    },
+  },
+  {
+    name: 'lint',
+    summary: 'biome: no any, no default exports, no raw colours',
+    async run(ctx) {
+      const result = await ctx.runner(['bunx', 'biome', 'check', '.'], { cwd: ctx.root });
+      return fromExec(result, {
+        code: 'X_LINT_FAILED',
+        cause: 'biome reported problems',
+        fix: 'bunx biome check --write .',
+      });
+    },
+  },
+  {
+    name: 'boundaries',
+    summary: 'surface, layer and package-tier imports',
+    run: async (ctx) =>
+      fromFindings([
+        ...(await checkAppBoundaries(ctx.root)),
+        ...(await hostFindings(ctx, 'boundaries')),
+      ]),
+  },
+  {
+    name: 'filesize',
+    summary: 'one file, one job',
+    run: async (ctx) => fromFindings(await checkFileSizes(ctx.root)),
+  },
+  {
+    name: 'package-shape',
+    summary: 'every package ships the same contract files',
+    applies: (ctx) => hasWorkspacePackages(ctx.root),
+    run: async (ctx) => fromFindings(await checkPackageShape(ctx.root)),
+  },
+  {
+    name: 'errors',
+    summary: 'every X_* code has a runnable fix and a docs page',
+    // The fix-line half runs anywhere source does. The docs half needs a reference page to check
+    // against, and which file that is belongs to the host repo — hence `hostFindings`.
+    run: async (ctx) =>
+      fromFindings([...(await checkErrorFixes(ctx.root)), ...(await hostFindings(ctx, 'errors'))]),
+  },
+  ...TEST_STEPS,
+  {
+    name: 'drift',
+    summary: 'schema vs migrations',
+    // Only an app owns migrations; a package monorepo's `packages/db` is the driver, not a schema.
+    applies: async (ctx) => existsSync(join(ctx.root, APP_CONFIG_FILE)),
+    run: async (ctx) => fromFindings(await checkDrift(ctx.root)),
+  },
+  {
+    name: 'contract-diff',
+    summary: 'the published contract vs the committed manifest',
+    // Either file is a published contract on its own: `openapi.json` generates the typed client,
+    // so gating on the manifest alone let a stale spec ship a wrong client unchecked.
+    applies: async (ctx) =>
+      existsSync(join(ctx.root, MANIFEST_FILENAME)) || existsSync(join(ctx.root, OPENAPI_FILE)),
+    async run(ctx) {
+      const committed = await readAppManifest(ctx.root);
+      const { manifest, findings } = await appManifest(ctx.root);
+      return fromFindings([
+        ...findings,
+        ...(committed === undefined ? [] : contractFindings(committed, manifest)),
+        ...(await specFindings(ctx.root, manifest)),
+      ]);
+    },
+  },
+  {
+    name: 'budgets',
+    summary: 'per-route JS bytes and LCP',
+    async run(ctx) {
+      const stats = await readBuildStats(ctx.root);
+      if (stats === undefined) return passed;
+      const { manifest } = await appManifest(ctx.root);
+      return fromFindings(checkBudgets(manifest, stats));
+    },
+  },
+  {
+    name: 'manifest',
+    summary: 'the two files an agent reads: generated facts, hand-written conventions',
+    // No `applies`. The drift half has nothing to compare against until `x manifest` has run
+    // once, and says so by finding nothing — but `AGENTS.md` is required of every repo the gate
+    // runs in, so the step always has a question to answer and must never report as skipped.
+    async run(ctx) {
+      const agents = await checkAgentsMd(ctx.root);
+      const findings = [
+        ...(await driftFindings(ctx.root)),
+        ...agents.findings,
+        ...(await hostFindings(ctx, 'manifest')),
+      ];
+      // Warnings are not findings: `AGENTS.md` tabulating a route table is a smell a human
+      // judges, not a build error. They ride in `output`, which `--json` carries verbatim.
+      const output = agents.warnings.map((warning) => `${AGENTS_MD_FILENAME}: ${warning}`);
+      return {
+        ok: findings.length === 0,
+        findings,
+        ...(output.length === 0 ? {} : { output: output.join('\n') }),
+      };
+    },
+  },
+  {
+    name: 'roadmap',
+    summary: "every roadmap milestone's status marker matches what is actually on disk",
+    // A generated app ships no `docs/idea/14-roadmap.md` — only the framework monorepo does, so
+    // only a host that registers this check has anything for the step to verify.
+    applies: async (ctx) => ctx.hostChecks?.roadmap !== undefined,
+    run: async (ctx) => fromFindings(await hostFindings(ctx, 'roadmap')),
+  },
+];
+
+/** `assertNoDrift` throws `X_MANIFEST_DRIFT`; a step reports, so the error becomes a finding. */
+async function driftFindings(root: string): Promise<readonly Finding[]> {
+  const path = join(root, MANIFEST_FILENAME);
+  if (!existsSync(path)) return [];
+  const { manifest, findings } = await appManifest(root);
+  try {
+    await assertNoDrift({ manifest, path });
+    return findings;
+  } catch (error) {
+    return [...findings, { ...findingFrom(error), at: MANIFEST_FILENAME }];
+  }
+}
+
+/** A breaking change is allowed — with a major bump. `verifyContract` is the one that decides. */
+function contractFindings(before: Manifest, after: Manifest): readonly Finding[] {
+  try {
+    verifyContract({ before, after });
+    return [];
+  } catch (error) {
+    return [{ ...findingFrom(error), at: MANIFEST_FILENAME }];
+  }
+}
+
+/** The typed client is generated from `openapi.json`, so a stale spec ships a wrong client. */
+async function specFindings(root: string, manifest: Manifest): Promise<readonly Finding[]> {
+  const path = join(root, OPENAPI_FILE);
+  if (!existsSync(path)) return [];
+  if ((await Bun.file(path).text()) === openApiJson(manifest)) return [];
+  return [
+    {
+      code: 'X_MANIFEST_STALE',
+      cause: `${OPENAPI_FILE} does not match the actions the code registers`,
+      fix: 'x manifest',
+      docs: 'https://ultimate.dev/errors/X_MANIFEST_STALE',
+      at: OPENAPI_FILE,
+    },
+  ];
+}
+
+/**
+ * Run every step in order, never bailing early: an agent fixing three things at once needs all
+ * three findings from one run, not one per round-trip.
+ */
+export async function runVerify(
+  steps: readonly VerifyStep[],
+  ctx: VerifyContext,
+): Promise<CommandResult> {
+  const results: StepResult[] = [];
+  for (const step of steps) {
+    const applies = step.applies === undefined ? true : await step.applies(ctx);
+    if (!applies) {
+      results.push({ name: step.name, ok: true, durationMs: 0, skipped: true, findings: [] });
+      continue;
+    }
+    const started = performance.now();
+    const outcome = await step.run(ctx).catch(
+      (error: unknown): StepOutcome => ({
+        ok: false,
+        findings: [findingOf(error, step.name)],
+      }),
+    );
+    results.push({
+      name: step.name,
+      ok: outcome.ok,
+      durationMs: Math.round(performance.now() - started),
+      findings: outcome.findings,
+      ...(outcome.output === undefined ? {} : { output: outcome.output }),
+    });
+  }
+  const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
+  const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  return {
+    ok: failedSteps.length === 0,
+    command: 'verify',
+    summary:
+      failedSteps.length === 0
+        ? msg('cli.verify.pass', { count: results.length, ms: totalMs })
+        : msg('cli.verify.fail', { failed: failedSteps.length, count: results.length }),
+    steps: results,
+    data: { failed: failedSteps, durationMs: totalMs },
+    exitCode: failedSteps.length === 0 ? 0 : 1,
+  };
+}
+
+function findingOf(error: unknown, step: string): Finding {
+  const cause = error instanceof Error ? error.message : String(error);
+  return {
+    code: 'X_VERIFY_FAILED',
+    cause: `step "${step}" threw: ${cause}`,
+    fix: 'x verify --json',
+    docs: 'https://ultimate.dev/errors/X_VERIFY_FAILED',
+  };
+}
+
+export const verifyCommand: CliCommand = {
+  spec: {
+    name: 'verify',
+    summary: 'the gate: typecheck, lint, boundaries, all tests, drift, contract, budgets',
+    usage: 'x verify [--json]',
+    requiresApp: true,
+    flags: [],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('verify', ctx.cwd).dir;
+    return runVerify(VERIFY_STEPS, { root, runner: ctx.runner });
+  },
+};
+
+export const verifyStepNames = (): readonly VerifyStepName[] =>
+  VERIFY_STEPS.map((step) => step.name);

package/src/command.ts

@@ -0,0 +1,33 @@
+// The shape every command implements. A command is a spec (for parsing and help) plus a pure-ish
+// `run` that returns a `CommandResult` — it never writes to stdout and never calls process.exit,
+// so the dispatcher owns rendering and the exit code, and every command is directly testable.
+
+import type { Runner } from './exec';
+import type { CommandResult } from './output';
+import type { CommandSpec, ParsedArgs } from './parse';
+
+export interface CommandContext {
+  readonly args: ParsedArgs;
+  /** Already resolved: `--cwd` applied, app root not yet required. */
+  readonly cwd: string;
+  readonly runner: Runner;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly bunVersion: string;
+}
+
+export interface CliCommand {
+  readonly spec: CommandSpec;
+  run(ctx: CommandContext): Promise<CommandResult>;
+}
+
+export const ok = (
+  command: string,
+  summary: string,
+  extra: Partial<CommandResult> = {},
+): CommandResult => ({ ok: true, command, summary, ...extra });
+
+export const failed = (
+  command: string,
+  summary: string,
+  extra: Partial<CommandResult> = {},
+): CommandResult => ({ ok: false, command, summary, ...extra });

package/src/dev-assets.ts

@@ -0,0 +1,177 @@
+// Projecting the framework's one image pipeline onto the routes `x dev` serves. Three packages
+// declare what an image is — `@ultimat3/seo` a variant URL, `@ultimat3/storage` a variant key,
+// `@ultimat3/pwa` the icons a web manifest promises — and `@ultimat3/core`'s pipeline owns every
+// pixel, so this file picks the two base paths they hang off and decides nothing else.
+
+// `join` is `node:`-only by necessity: Bun exposes no path-join primitive, and `ICON_SOURCE` is
+// app-root-relative, so resolving it against the root is string work no `Bun.file` overload does.
+import { join } from 'node:path';
+import { probeImage } from '@ultimat3/core';
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import type { IconPlan } from '@ultimat3/pwa';
+import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
+import type { ImageQuery } from '@ultimat3/seo';
+import { builtinImageDriver, parseImageQuery } from '@ultimat3/seo';
+import type { ImageFormat, ImageTransform, Storage } from '@ultimat3/storage';
+import { IMAGE_FORMATS, variantKey } from '@ultimat3/storage';
+
+/**
+ * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
+ * it and this file reads it — one constant, because a second spelling is an app that passes the
+ * diagnostic and still serves no icons. PNG, not SVG: core's pipeline decodes PNG and JPEG only.
+ */
+export const ICON_SOURCE = 'apps/web/site/icon.png';
+
+/** Where `planIcons` writes, and therefore the paths the generated web manifest names. */
+export const ICON_BASE_PATH = '/icons';
+
+/** Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it. */
+export const MEDIA_BASE_PATH = '/media';
+
+/**
+ * Variants are content-addressed by `variantKey`, so a URL that answers once answers forever with
+ * the same bytes — the immutable hint is a fact about the key, not an optimism about the source.
+ */
+const imageResponse = (bytes: Uint8Array, contentType: string): Response =>
+  applyCacheHeaders(
+    // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+    // `SharedArrayBuffer`, which `Response` does not accept, and copying is what makes that true
+    // by construction rather than by a cast that would only silence it.
+    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    { mode: 'immutable' },
+  );
+
+const isImageFormat = (value: string): value is ImageFormat =>
+  (IMAGE_FORMATS as readonly string[]).includes(value);
+
+/**
+ * `exactOptionalPropertyTypes` makes an explicit `undefined` a different answer from an absent
+ * key, and `variantKey` reads presence — so a spread, never an assignment.
+ */
+function storageTransform(query: ImageQuery, format: ImageFormat | undefined): ImageTransform {
+  return {
+    ...(query.width === undefined ? {} : { width: query.width }),
+    ...(format === undefined ? {} : { format }),
+    ...(query.quality === undefined ? {} : { quality: query.quality }),
+  };
+}
+
+/**
+ * A cache hit costs one `exists` and one `get`; a miss costs a decode. The source is read once
+ * either way and handed to the driver rather than fetched again — `read` exists so seo never has
+ * to guess whether a `src` is a path, a key or a URL, and here it is unambiguously a storage key.
+ */
+async function transformedVariant(
+  storage: Storage,
+  key: string,
+  query: ImageQuery,
+): Promise<Response> {
+  const disk = storage.disk();
+  // A format storage cannot name has no variant key, so it cannot be cached. The driver refuses
+  // it with core's `X_IMAGE_UNSUPPORTED`; refusing it here too would give one bad URL two codes.
+  const format =
+    query.format !== undefined && isImageFormat(query.format) ? query.format : undefined;
+  const cacheable = query.format === undefined || format !== undefined;
+  const cached = cacheable ? variantKey(key, storageTransform(query, format)) : undefined;
+  if (cached !== undefined && (await disk.exists(cached))) {
+    const hit = await disk.get(cached);
+    return imageResponse(hit.bytes, hit.object.contentType);
+  }
+
+  const source = await disk.get(key);
+  const variant = await builtinImageDriver({ read: async () => source.bytes }).transform({
+    src: key,
+    // A header read, not a decode: `?f=webp` alone still needs a width, and the source's own is
+    // the only one that does not resize an image the caller never asked to resize.
+    width: query.width ?? probeImage(source.bytes).width,
+    ...(query.format === undefined ? {} : { format: query.format }),
+    ...(query.quality === undefined ? {} : { quality: query.quality }),
+  });
+  if (cached !== undefined) {
+    await disk.put(cached, variant.bytes, { contentType: variant.contentType });
+  }
+  return imageResponse(variant.bytes, variant.contentType);
+}
+
+async function mediaResponse(request: UltimateRequest, storage: Storage): Promise<Response> {
+  const key = request.params['key'] ?? '';
+  const query = parseImageQuery(request.url.searchParams);
+  if (query !== null) return transformedVariant(storage, key, query);
+  // No transform asked for: the object itself, still under the storage key's own safety checks.
+  const read = await storage.disk().get(key);
+  return imageResponse(read.bytes, read.object.contentType);
+}
+
+/**
+ * Rendered once per process, not per request: the fourteen matrix entries are pure functions of
+ * one source file, and re-encoding a 512px PNG on every hit would be work no caller can observe.
+ */
+function iconRenderer(root: string): (plan: IconPlan, path: string) => Promise<Uint8Array> {
+  const pipeline = new BuiltinImagePipeline();
+  const rendered = new Map<string, Promise<Uint8Array>>();
+  const sourceBytes = async (): Promise<Uint8Array> => {
+    const file = Bun.file(join(root, ICON_SOURCE));
+    if (!(await file.exists())) {
+      throw new PwaIconMissingError(
+        `${ICON_SOURCE} does not exist, so every icon the web manifest declares is unbacked and ` +
+          'the app is not installable',
+        // The same edit `x doctor` reports for the same condition, in `@ultimat3/pwa`'s own words.
+        // `x new` was here and takes an app name, so it could never run inside the broken app.
+        `add a 1024x1024 square PNG at ${ICON_SOURCE}`,
+      );
+    }
+    return file.bytes();
+  };
+  return async (plan, path) => {
+    const entry = plan.entries.find((candidate) => candidate.outputPath === path);
+    if (entry === undefined) {
+      throw new PwaIconMissingError(
+        `${path} is not in the icon matrix, so no transform describes it`,
+        `request one of ${plan.entries.map((one) => one.outputPath).join(', ')}`,
+      );
+    }
+    const existing = rendered.get(path);
+    if (existing !== undefined) return existing;
+    const bytes = sourceBytes().then((source) => pipeline.resize(source, entry.transform));
+    rendered.set(path, bytes);
+    // A failed render must not be remembered — the next request comes after the source was added.
+    bytes.catch(() => rendered.delete(path));
+    return bytes;
+  };
+}
+
+export interface AssetRoutesOptions {
+  /** App root. The source icon is resolved against it; storage keys never are. */
+  readonly root: string;
+  readonly storage: Storage;
+}
+
+/**
+ * The icon routes mount whether or not the source exists, and a missing source is refused on the
+ * wire with `X_PWA_ICON_MISSING` and its fix — a route that silently disappears is a 404 whose
+ * meaning an agent has to guess. Deliberately NOT a boot finding: `x doctor` already reports this
+ * exact condition with this exact code, and a second reporter of one condition is the duplication
+ * this package's own rule forbids. `x dev` owns the runtime half, the diagnostic owns the other.
+ */
+export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
+  const plan = planIcons({ sourceIcon: ICON_SOURCE, outDir: ICON_BASE_PATH });
+  const render = iconRenderer(options.root);
+
+  const routes: Route[] = plan.entries.map((entry) => ({
+    method: 'GET',
+    path: entry.outputPath,
+    meta: { name: `assets.icon.${entry.spec.filename}`, auth: 'public', tags: ['assets'] },
+    handler: async (request: UltimateRequest): Promise<Response> =>
+      imageResponse(await render(plan, request.pathname), 'image/png'),
+  }));
+  routes.push({
+    method: 'GET',
+    path: `${MEDIA_BASE_PATH}/*key`,
+    meta: { name: 'assets.media', auth: 'public', tags: ['assets'] },
+    handler: async (request: UltimateRequest): Promise<Response> =>
+      mediaResponse(request, options.storage),
+  });
+
+  return routes;
+}