@ultimat3/cli 6.0.0 → 7.0.0

package/src/static-report.ts

@@ -0,0 +1,219 @@
+// The inventory of one `x build --target static`: which declared route reached the artifact, which
+// did not, and WHY for each. Written by the prerenderer, read back by `x build`, so both renderers
+// state the same thing. A skipped route with no reason is what turned "the island did not mount"
+// into a bug report about a page that had never been in `.x/static/` at all (#242).
+
+// `node:` twice, and only where Bun answers nothing: Bun ships no path API, and `rm(…, { force })`
+// deletes a report that may not be there without a branch. `existsSync` was a third and is gone —
+// `Bun.file(path).json()` already rejects on a missing file, into the catch that answers `undefined`.
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RenderMode } from '@ultimat3/core';
+import { RENDER_MODES } from '@ultimat3/core';
+import type { Surface } from '@ultimat3/render';
+import { SURFACE_SPECS, SURFACES, surfaceAllows } from '@ultimat3/render';
+import type { JsonValue } from './output';
+
+/** Beside `.x/build-stats.json`, and written by the same call — see `readStaticReport` below. */
+export const STATIC_REPORT_FILE = join('.x', 'static-report.json');
+
+export const SKIP_REASONS = [
+  'surface-forbids-static',
+  'mode-revalidates',
+  'mode-per-request',
+  'no-prerender-paths',
+] as const;
+
+export type SkipReason = (typeof SKIP_REASONS)[number];
+
+/**
+ * Type ALIASES, never interfaces — every shape below is JSON on both sides of a file, and only an
+ * alias carries the implicit index signature that makes it assignable to `JsonValue`. As
+ * interfaces, `data: { emitted, skipped }` in `cmd-build.ts` was TS2322 (`not assignable to type
+ * 'JsonValue'`) with nothing wrong in either file, and the obvious fixes — a cast, a widened
+ * annotation — are the two this repo refuses. Same rule `RouteContext` in `@ultimat3/render` is an
+ * alias for.
+ */
+
+/** The two declarations a skip decision reads. Narrower than `RouteEntry` so a test can state one. */
+export type RouteFacts = {
+  readonly surface: Surface;
+  readonly render: RenderMode;
+};
+
+export type SkippedRoute = RouteFacts & {
+  /** The DECLARED path, `/blog/:slug` — never a filled one, so the author can grep for it. */
+  readonly route: string;
+  readonly reason: SkipReason;
+  readonly why: string;
+};
+
+/** One HTML file in the artifact, and the declared route that produced it. */
+export type EmittedPage = {
+  readonly route: string;
+  readonly path: string;
+  /** Relative to the build output root, POSIX — the file a screenshot tool actually opens. */
+  readonly file: string;
+};
+
+export type StaticReport = {
+  readonly target: 'static';
+  readonly out: string;
+  readonly buildId: string;
+  readonly emitted: readonly EmittedPage[];
+  readonly skipped: readonly SkippedRoute[];
+};
+
+/**
+ * The ONE decision about what lands on a CDN — `isPrerenderable` is derived from it, so the answer
+ * and the reason can never disagree.
+ *
+ * Surface is asked FIRST, and that ordering is the whole finding. `app/` allows `stream | ssr` and
+ * nothing else, so no `render:` edit can put an app/ route into the artifact: the surface is the
+ * cause, and naming the mode would send an author to change the one thing that cannot help. On a
+ * surface that DOES allow `static`, the mode is the cause and the edit is real — which is why the
+ * two produce different sentences below rather than one flat "not prerendered".
+ */
+export function skipReasonFor(route: RouteFacts): SkipReason | null {
+  if (!surfaceAllows(route.surface, 'static')) return 'surface-forbids-static';
+  if (route.render === 'static') return null;
+  return route.render === 'isr' ? 'mode-revalidates' : 'mode-per-request';
+}
+
+/**
+ * `Object.freeze<Record<…>>`, never `const X: Readonly<Record<…>> = Object.freeze({…})`: the second
+ * form infers from the literal and accepts an EXTRA key in silence (`bun run frozen-records`).
+ *
+ * English rather than `t()`, for the reason every `cause:`/`fix:` in this repo is English: this is
+ * a diagnostic an agent pastes into a report, and `wiki/Error-Codes.md` is the same surface.
+ */
+const WHY = Object.freeze<Record<SkipReason, (route: RouteFacts) => string>>({
+  'surface-forbids-static': (route) =>
+    `${route.surface}/ surface — server-rendered, not prerendered; ` +
+    `${route.surface}/ allows ${SURFACE_SPECS[route.surface].allowedModes.join(' | ') || 'no render mode'}, ` +
+    'so no route on it can ever reach the artifact',
+  'mode-revalidates': (route) =>
+    `render: '${route.render}' regenerates on a tag or ttl and a published file cannot, ` +
+    "so it is served by the app — change it to render: 'static' to emit it",
+  'mode-per-request': (route) =>
+    `render: '${route.render}' is rendered per request, so it is served by the app — ` +
+    "change it to render: 'static' to emit it",
+  'no-prerender-paths': (route) =>
+    `render: '${route.render}' with dynamic params and no prerender() paths, so the build ` +
+    'enumerated nothing to write — add prerender() to the route',
+});
+
+/** The reason as a row: the code a machine keys off, and the sentence a human reads. */
+export function skippedRoute(
+  input: RouteFacts & { readonly route: string },
+  reason: SkipReason,
+): SkippedRoute {
+  return {
+    route: input.route,
+    surface: input.surface,
+    render: input.render,
+    reason,
+    why: WHY[reason](input),
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * A closed vocabulary, checked against the vocabulary itself. `typeof value === 'string'` is what
+ * `surface` and `render` were held to, and a string is not a `Surface`: the parse then handed back
+ * a `SkippedRoute` whose declared type says `'site' | 'app' | 'api' | 'shared'` while it holds
+ * whatever the file said, so `SURFACE_SPECS[route.surface]` on the read side is `undefined` at the
+ * first reader that indexes it. `SKIP_REASONS` was already checked this way; these two are the same
+ * kind of field and get the same rule.
+ */
+const inDomain = (domain: readonly string[], value: unknown): boolean =>
+  typeof value === 'string' && domain.includes(value);
+
+const isSkipped = (value: unknown): value is SkippedRoute =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  inDomain(SURFACES, value['surface']) &&
+  inDomain(RENDER_MODES, value['render']) &&
+  typeof value['why'] === 'string' &&
+  inDomain(SKIP_REASONS, value['reason']);
+
+const isEmitted = (value: unknown): value is EmittedPage =>
+  isRecord(value) &&
+  typeof value['route'] === 'string' &&
+  typeof value['path'] === 'string' &&
+  typeof value['file'] === 'string';
+
+/**
+ * Parsed, never cast. The file is this build's own output, but `x build` reads it back off disk
+ * after a subprocess — a truncated write or a hand-edit must read as "no report", which the caller
+ * already handles, rather than as a report with a `skipped` nobody can render.
+ */
+export function parseStaticReport(value: unknown): StaticReport | undefined {
+  if (!isRecord(value)) return undefined;
+  const { target, out, buildId, emitted, skipped } = value;
+  if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
+    return undefined;
+  }
+  if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
+  if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
+  return { target, out, buildId, emitted, skipped };
+}
+
+export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
+  const path = join(root, STATIC_REPORT_FILE);
+  await Bun.write(path, `${JSON.stringify(report, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * `undefined` means no report — an app whose `apps/web/prerender.ts` does not call `prerenderSite`.
+ * That app also writes no `.x/build-stats.json` (one call writes both), so `x verify`'s `budgets`
+ * step already reds it with `X_BUDGET_UNMEASURED`; this side stays quiet rather than adding a
+ * second code for one cause.
+ */
+export async function readStaticReport(root: string): Promise<StaticReport | undefined> {
+  try {
+    return parseStaticReport(await Bun.file(join(root, STATIC_REPORT_FILE)).json());
+  } catch {
+    return undefined;
+  }
+}
+
+/** Deleted before the builder is spawned, so a failed build can never report the last one's list. */
+export async function removeStaticReport(root: string): Promise<void> {
+  await rm(join(root, STATIC_REPORT_FILE), { force: true });
+}
+
+/**
+ * The `--json` half, beside `renderStaticReport`'s human one — and a `Record<string, JsonValue>`
+ * rather than a `JsonValue`, because `x build` SPREADS it into `data` beside `target` and
+ * `artifact`: a bare `JsonValue` admits a string, so the spread is TS2698 (`spread types may only
+ * be created from object types`) and no annotation at the call site can rescue it.
+ *
+ * A field the compiler cannot prove is JSON reds HERE, at the projection, rather than at whichever
+ * caller happens to hand the report to a renderer.
+ */
+export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
+  // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
+  // which the inventory is about — `data` already carries `artifact` and the build's own id.
+  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+}
+
+/**
+ * The human half. Fixed-width columns headed by the JSON's own field names, exactly as
+ * `renderRouteTable` is — the renderer invents no prose, so `--json` and the terminal cannot drift.
+ */
+export function renderStaticReport(report: StaticReport): readonly string[] {
+  const rows: readonly (readonly string[])[] = [
+    ...report.emitted.map((page) => ['emitted', page.route, page.file]),
+    ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+  ];
+  const widths = [0, 1].map((index) =>
+    Math.max(...rows.map((row) => (row[index] ?? '').length), 0),
+  );
+  return rows.map((row) =>
+    `  ${row.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join('  ')}`.trimEnd(),
+  );
+}

package/src/templates/index.ts

@@ -30,6 +30,7 @@ export type { QueryOptions } from './query';
 export { queryFiles } from './query';
 export type { ResourceOptions } from './resource';
 export { resourceFiles } from './resource';
+export { formIslandFiles } from './resource-form-island';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';

package/src/templates/island-fixture.ts

@@ -0,0 +1,76 @@
+// TEST-ONLY. An app root on disk holding emitted files, with the packages an island imports
+// resolvable BY SPECIFIER the way a real app resolves them — so a template that emits
+// `import { Button } from '@ultimat3/ui'` is proven by a build that actually resolves it, and not
+// by a string assertion that the import is present.
+
+// `node:` by necessity, and SYNC by necessity: `[Symbol.dispose]` cannot await, so the teardown
+// half has to be synchronous — and Bun ships neither a path API nor a `symlink`.
+import { mkdirSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { GeneratedFile } from './naming';
+
+/** `packages/cli/src/templates` → the repo root, four hops up. */
+const REPO_ROOT = join(import.meta.dir, '..', '..', '..', '..');
+
+/**
+ * INSIDE the checkout, and measured rather than chosen: the identical fixture under `os.tmpdir()`
+ * fails every `@ultimat3/*` and every relative import inside it with `Could not resolve`, because
+ * `Bun.build`'s resolver is scoped to the project `bun test` was started in and an app root outside
+ * it cannot reach its own `node_modules`. `.prerender-fixture` is the same shape for the same
+ * reason. The leading dot keeps it out of every `tsc` wildcard include.
+ */
+const FIXTURE_ROOT = join(REPO_ROOT, 'packages', 'cli', '.island-fixture');
+
+/** The package the fixture lives inside. Linking it would aim a symlink at its own ancestor. */
+const SELF = 'cli';
+
+export interface FixtureApp extends Disposable {
+  /** Absolute path of the app root — what `buildIslands` globs from. */
+  readonly path: string;
+}
+
+/**
+ * Symlinks rather than a `bun install`: the emitted island must resolve THIS working copy of
+ * `@ultimat3/ui`, and an install in a fixture directory would fetch the registry's last release
+ * and quietly prove nothing about the change under test. Every workspace is linked, not a chosen
+ * few — a template that grows an import should build, not fail on a list nobody updated.
+ */
+function linkDependencies(root: string): void {
+  const scope = join(root, 'node_modules', '@ultimat3');
+  mkdirSync(scope, { recursive: true });
+  const packages = join(REPO_ROOT, 'packages');
+  for (const entry of new Bun.Glob('*/package.json').scanSync({ cwd: packages })) {
+    const name = entry.slice(0, entry.indexOf('/'));
+    if (name === SELF) continue;
+    symlinkSync(join(packages, name), join(scope, name), 'dir');
+  }
+  // Resolved, never spelled as a path: the installer's layout is its own business and a hardcoded
+  // `node_modules/solid-js` is a fixture that breaks on a linker change rather than on a real one.
+  symlinkSync(
+    dirname(Bun.resolveSync('solid-js/package.json', REPO_ROOT)),
+    join(root, 'node_modules', 'solid-js'),
+    'dir',
+  );
+}
+
+/**
+ * `Disposable`, so the idiom is `using root = await fixtureAppRoot(label, files)`. `label` is the
+ * caller's, and is what keeps two test FILES off one directory: the path is fixed rather than
+ * random, because a random one cannot be named in `.gitignore` and a crashed run leaves it behind.
+ */
+export async function fixtureAppRoot(
+  label: string,
+  files: readonly GeneratedFile[],
+): Promise<FixtureApp> {
+  const path = join(FIXTURE_ROOT, label);
+  rmSync(path, { recursive: true, force: true });
+  mkdirSync(path, { recursive: true });
+  linkDependencies(path);
+  for (const file of files) await Bun.write(join(path, file.path), String(file.contents));
+  return {
+    path,
+    [Symbol.dispose]: (): void => {
+      rmSync(path, { recursive: true, force: true });
+    },
+  };
+}

package/src/templates/island.ts

@@ -1,7 +1,8 @@
 // `x g island <name>` — the one file on a route that ships JavaScript. Not a ninth primitive and
 // not a component generator: an island is a client ENTRY POINT, so what the scaffold has to get
-// right is the filename (the bundler discovers by it) and the `mount` export (the hydration
-// runtime calls it by name). Both are pinned by the emitted test.
+// right is the filename (the bundler discovers by it), the `mount` export (the hydration runtime
+// calls it by name) and what `mount` DOES — Solid's `render`, the one client shape the island build
+// compiles. All three are pinned by the emitted test, which builds the chunk and mounts it.
 
 import type { GeneratedFile } from './naming';
 import { kebab, pascal } from './naming';
@@ -11,6 +12,18 @@ export interface IslandOptions {
   readonly dir: string;
 }
 
+/**
+ * `join(import.meta.dir, '..', …)` back to the app root, one hop per directory segment. The
+ * emitted test names the island app-root-relative because that is how `discoverIslands` reports it,
+ * so the two spellings have to agree or `mountIsland` reports a file it did not build.
+ */
+export const upToAppRoot = (dir: string): string =>
+  dir
+    .split('/')
+    .filter((part) => part.length > 0)
+    .map(() => "'..'")
+    .join(', ');
+
 const islandSource = (name: string): string => {
   const Name = pascal(name);
   return `// ${Name}: the interactive half of an otherwise static page, and the only module on this
@@ -21,39 +34,136 @@ const islandSource = (name: string): string => {
 // A string has no import edge, so nothing follows one into this file and the page's bundle graph
 // stays the page's (axiom 6). WHEN it wakes is the route's \`hydrate\`, never a declaration here.
 
+import type { JSX } from 'solid-js';
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import styles from './${name}.module.scss';
+
 /** What the server sends. Declared here AND in the page's \`island({ props })\` — both, or neither. */
 export interface ${Name}Props {
   /** Already translated: this runs in the browser, where \`t()\`'s catalog is not. */
   readonly label: string;
 }
 
+/**
+ * Solid, and not hand-written DOM: reactivity is a COMPILE-time contract that \`babel-preset-solid\`
+ * fulfils inside the island build, which is what makes \`count()\` read below update that one text
+ * node and nothing around it. A component written against an eager JSX factory reads every signal
+ * once and never again — it renders, and then it is a photograph.
+ */
+function ${Name}(props: ${Name}Props): JSX.Element {
+  const [count, setCount] = createSignal(0);
+  return (
+    <p class={styles.panel}>
+      <button type="button" class={styles.trigger} onClick={() => setCount(count() + 1)}>
+        {props.label}
+      </button>
+      <output data-role="count">{count()}</output>
+    </p>
+  );
+}
+
 /**
  * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
- * \`el\` is the wrapper the page rendered, with the server's own markup already inside it, so a
- * mount that replaces the markup instead of taking it over is a visible flash on every load.
+ * \`el\` is the wrapper the page rendered, with the server's own markup already inside it.
+ *
+ * The shell is cleared first, and that line is load-bearing: Solid's \`render\` APPENDS when the
+ * container already has children, so without it the server's markup stays on screen above a
+ * second, live copy of the same thing.
  */
 export function mount(el: HTMLElement, props: ${Name}Props): void {
-  el.textContent = props.label;
-  el.addEventListener('click', () => {
-    // \`dataset.open\`, not \`dataset['open']\`: the bracket form is lint/complexity/useLiteralKeys,
-    // which the app's own \`biome check\` fails on — twice, in the one file every island copies.
-    el.dataset.open = el.dataset.open === 'true' ? 'false' : 'true';
-  });
+  el.textContent = '';
+  render(() => <${Name} {...props} />, el);
 }
 `;
 };
 
+const islandStyle = (): string => `// Semantic tokens only — a raw hex here is a dark-theme bug and
+// a lint failure. Scoped by the island build, with the class names the server hashed.
+@use '@ultimat3/ui/tokens' as tokens;
+
+.panel {
+  display: flex;
+  align-items: center;
+  gap: tokens.space(2);
+}
+
+.trigger {
+  padding: tokens.space(2);
+  border-radius: tokens.radius('sm');
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
+}
+`;
+
 const islandTest = (
   name: string,
-): string => `// The runtime boots an island by calling \`mount\` on whatever the module exports. A renamed or
-// deleted export is a page that renders, serves, passes every other gate and does nothing when
-// clicked — which is exactly the failure nothing else in the build can see.
+  dir: string,
+): string => `// The island the browser actually runs. \`mountIsland\` builds this entry with the same
+// \`buildIslands\` that \`x build\` and \`x dev\` use, imports the emitted chunk the way the hydration
+// runtime does, and drives \`mount\` against a DOM small enough to read.
+//
+// Importing the module and asserting \`typeof mount === 'function'\` proves the file exists, and a
+// file that exists is exactly what ships dead: a renamed export, a dropped handler and a signal
+// that never reaches the DOM all pass that test and none of them survive this one.
+
+import { join } from 'node:path';
+import { buildIslands } from '@ultimat3/cli';
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  type MountedIsland,
+  mountIsland,
+  test,
+} from '@ultimat3/testing';
 
-import { expect, unitTest } from '@ultimat3/testing';
-import * as entry from './${name}.island';
+const APP_ROOT = join(import.meta.dir, ${upToAppRoot(dir)});
+const ISLAND = '${dir}/${name}.island.tsx';
+
+let mounted: MountedIsland;
+
+// The build is a Babel pass plus a browser bundle — seconds, not milliseconds. It lives in
+// \`beforeAll\` with its own timeout because \`test\` takes no third argument: fixtures are resolved
+// per case, so the slow work goes where it can be given one and every case shares the result.
+beforeAll(async () => {
+  mounted = await mountIsland({
+    build: buildIslands,
+    root: APP_ROOT,
+    file: ISLAND,
+    props: { label: 'Open' },
+    // What the server rendered inside the island's wrapper. \`mount\` replaces it.
+    shell: '<span>Open</span>',
+  });
+}, 60_000);
 
-unitTest('${name}.island exports the mount the hydration runtime calls', () => {
-  expect(typeof entry.mount).toBe('function');
+// The fake \`document\` is process-global: left installed it reaches every LATER FILE in the run.
+//
+// \`?.\` on a binding the type says is always set: TypeScript's definite-assignment analysis does not
+// cross the \`beforeAll\` closure, so a setup that REJECTED leaves this undefined at run time — and
+// bun runs \`afterAll\` regardless. Unguarded, the build failure is followed by a \`TypeError:
+// undefined is not an object\` that says nothing, and that second line is the one a tail reads.
+// Nothing is skipped by the guard: \`mountIsland\` restores the process itself when a mount throws.
+afterAll(() => {
+  mounted?.[Symbol.dispose]();
+});
+
+describe('the ${name} island', () => {
+  test('mount replaces the server shell', () => {
+    expect(mounted.find('span')).toBeNull();
+    // Solid compiles to real DOM calls; a chunk that fell back to the classic React factory names
+    // a global that is not in it, and \`Bun.build\` answers \`success: true\` over that all the same.
+    expect(mounted.code).not.toMatch(/\\bReact\\b/);
+  });
+
+  test('a click reaches the DOM through the signal', () => {
+    expect(mounted.text('[data-role="count"]')).toBe('0');
+    // \`false\` means no handler ran — an island whose onClick never reached the DOM looks identical
+    // to a selector typo otherwise.
+    expect(mounted.fire('button', 'click')).toBe(true);
+    expect(mounted.text('[data-role="count"]')).toBe('1');
+  });
 });
 `;
 
@@ -62,6 +172,7 @@ export function islandFiles(rawName: string, options: IslandOptions): readonly G
   const dir = options.dir.replace(/\/+$/, '');
   return [
     { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
-    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name) },
+    { path: `${dir}/${name}.module.scss`, contents: islandStyle() },
+    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name, dir) },
   ];
 }