@ultimat3/cli 6.0.0 → 8.0.0

package/src/templates/guard-unzoned-date.ts

@@ -0,0 +1,142 @@
+// The `unzoned-date` guard `x new` ships: no date is formatted without an explicit IANA zone.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `toLocaleDateString('en-US')`
+// in a scaffolded page was green on `x verify`, and it renders the SERVER's zone, so the same row
+// reads as two different days depending on which container answered.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'unzoned-date';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// unzoned-date: a date is stored in UTC and formatted with an explicit IANA zone, never with the
+// host's ambient one. \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside
+// the \`boundaries\` step — nothing registers this file, so nothing can forget to.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/** Every call whose output depends on a zone. The \`(\` is the start of the argument list. */
+const FORMATTER = /(?:\\.toLocale(?:Date|Time)?String|Intl\\.DateTimeFormat)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/**
+ * Comments blanked IN PLACE — not deleted — so the line number a finding reports still points at
+ * the source line. What it does not blank is a string body: a call spelled inside a quoted string
+ * is reported, which is the one false positive this rule can produce and the reason its own test
+ * lives in \`guards/\`, which nothing here scans.
+ */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/**
+ * The call's own argument list, from its \`(\` to the \`)\` that closes it. Depth-counted rather
+ * than "up to the next \`)\`": \`toLocaleDateString(locale, { timeZone: zoneFor(x) })\` closes twice
+ * before the one that ends the call, and reading only the first would report a zoned call.
+ */
+function argumentsOf(text: string, open: number): string {
+  let depth = 0;
+  for (let index = open; index < text.length; index += 1) {
+    const char = text[index];
+    if (char === '(') depth += 1;
+    else if (char === ')') {
+      depth -= 1;
+      if (depth === 0) return text.slice(open + 1, index);
+    }
+  }
+  return text.slice(open + 1);
+}
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function unzonedDates(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(FORMATTER)) {
+      const open = match.index + match[0].length - 1;
+      if (argumentsOf(text, open).includes('timeZone')) continue;
+      const line = lineOf(text, match.index);
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} calls \${match[0].trim()}) with no timeZone — it formats in whatever zone the process happens to run in, so one row reads as two different days across two containers\`,
+        fix: \`pass an explicit IANA zone in \${file.path} — toLocaleDateString(locale, { timeZone: 'UTC' }) — then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a date is never formatted without an explicit IANA time zone',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test's subject is often the wrong shape on purpose, and \`node_modules\` is not this
+      // app's source. Neither exclusion hides a rendered date from a user.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return unzonedDates(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { unzonedDates } from './unzoned-date';
+
+const file = (source: string) => [{ path: 'apps/web/app/dashboard/page.tsx', source }];
+
+unitTest('toLocaleDateString with no timeZone is refused', () => {
+  const findings = unzonedDates(file("const shown = at.toLocaleDateString('en-US');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.fix).toContain('timeZone');
+});
+
+unitTest('an explicit zone satisfies it, even nested behind another call', () => {
+  const zoned = "at.toLocaleDateString('en-US', { timeZone: zoneFor(actor) });";
+  expect(unzonedDates(file(zoned))).toEqual([]);
+});
+
+unitTest('Intl.DateTimeFormat and toLocaleTimeString are the same rule', () => {
+  expect(unzonedDates(file("new Intl.DateTimeFormat('en-US').format(at);"))).toHaveLength(1);
+  expect(unzonedDates(file("at.toLocaleTimeString('en-US');"))).toHaveLength(1);
+});
+
+unitTest('a commented-out call is a note, not a call', () => {
+  expect(unzonedDates(file("// at.toLocaleDateString('en-US');"))).toEqual([]);
+});
+`;
+
+/** `guards/unzoned-date.ts` and its test. No index, no registry — the directory registers it. */
+export const unzonedDateGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/unzoned-date.ts', contents: source() },
+  { path: 'guards/unzoned-date.test.ts', contents: test() },
+];

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';
@@ -38,6 +39,9 @@ export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
+export { entryFiles } from './scaffold-entries';
+// The four guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
+export { scaffoldGuardFiles } from './scaffold-guards';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
 export type { SliceModule } from './slice-foundation';

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,137 @@ 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 refused by the boundaries step, not by lint — 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 +173,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) },
   ];
 }