@pithy-sh/cli 0.1.0

package/src/ui/flow.ts

@@ -0,0 +1,451 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readdir } from "node:fs/promises";
+import { basename, join, sep } from "node:path";
+import { ConflictError, NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { allCapabilities, projectEnvironments, type WorkerConfig } from "../project/config";
+import { detectPackageManager, type PackageManager } from "../project/packageManager";
+import { readOptionalFile } from "../project/readOptionalFile";
+import { withRollback } from "../project/rollback";
+import { pathExists } from "../project/scaffold";
+import { deriveWorkerFirst, uncoveredRoutes } from "./routeAllowlist";
+import { scaffoldFiles } from "./scaffold";
+import { PITHY_SCREEN_DIR, unstyledScreenClasses } from "./screenStyles";
+import { resolveStub, UI_STUBS, type UiStub } from "./stubs";
+import { loadStubFiles } from "./templates";
+import { readAssets, wireAssets, wireManifest, wirePackage, wireSolution } from "./wire";
+import { readWorkerUi } from "./workerUi";
+
+/**
+ * `pithy ui add` and `pithy ui sync`, as flows — the command file stays argument parsing and output,
+ * the way `capabilities/flow.ts` sits behind `pithy add`.
+ */
+
+/** The capability the auth template's screens are written against. */
+const AUTH_CAPABILITY = "auth";
+
+/** The capability the paywall and subscription screens are written against. */
+const PAYMENTS_CAPABILITY = "payments";
+
+/** Which capability-gated screen set a decision is about. */
+export type UiScreenSet = typeof AUTH_CAPABILITY | typeof PAYMENTS_CAPABILITY;
+
+/**
+ * Ask whether to scaffold one capability's screens.
+ *
+ * One seam for every screen set rather than one per set: a third capability's screens must be a new member
+ * of {@link UiScreenSet} and nothing else, and a prompt-per-capability is exactly the shape that stops
+ * being true.
+ */
+export type UiScreenPrompt = (request: { screens: UiScreenSet; suggestion: boolean }) => Promise<boolean>;
+
+/**
+ * The one name this file uses for a Worker: the directory it lives in, `apps/<name>`.
+ *
+ * Derived here rather than accepted as an argument, because a Worker has **two** names and the wrong one
+ * is what a caller has to hand. `ResolvedWorker.name` is the *deployed* name — `<project>-<worker>`, the
+ * string in `wrangler.jsonc` — and taking it wrote `apps/<project>-<worker>/tsconfig.client.json` into the
+ * root solution file, a reference to a directory that has never existed. `tsc -b` stops on it with TS6053
+ * and Vite refuses to load the Worker's `vite.config.ts`, so a freshly scaffolded project could neither
+ * typecheck nor start.
+ *
+ * Everything below is either a path or a `--worker` value, and both are the directory. The deployed name
+ * belongs in `wrangler.jsonc` and nowhere else.
+ */
+function workerName(workerDir: string): string {
+  return basename(workerDir);
+}
+
+/** One entry of `pithy ui list`. */
+export interface UiStubListing {
+  /** The `<framework>` positional. */
+  id: string;
+  /** One line describing what it scaffolds. */
+  description: string;
+}
+
+/** Every framework `pithy ui add` can scaffold, sorted. */
+export function listStubs(): UiStubListing[] {
+  return Object.values(UI_STUBS)
+    .map((stub) => ({ id: stub.id, description: stub.description }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** Options for {@link runUiAdd} — the target worker, already resolved, plus the choices. */
+export interface UiAddOptions {
+  /** The project root — where the lockfile that names the package manager lives. */
+  projectDir: string;
+  /** The target worker's directory, `apps/<name>` — which is also where its name comes from. */
+  workerDir: string;
+  /** The target worker's loaded `pithy.config.ts` — the route table the allowlist is derived from. */
+  config: WorkerConfig;
+  /** The `<framework>` positional. */
+  framework: string;
+  /** `--auth` / `--no-auth`. Undefined means "decide", by prompt when one is attached. */
+  auth?: boolean;
+  /** `--payments` / `--no-payments`. Undefined means "decide", the same way. */
+  payments?: boolean;
+  /**
+   * Ask whether to scaffold a capability's screens. Supplied only when a human is attached; without it
+   * every decision falls to whether that capability is composed, so no invocation can ever block.
+   */
+  prompt?: UiScreenPrompt;
+  /** Package-manager override. Tests set it; otherwise it is detected from the project's lockfile. */
+  packageManager?: PackageManager;
+}
+
+/** What `pithy ui add` did. */
+export interface UiAddReport {
+  /** The worker the front end landed in. */
+  worker: string;
+  /** The stub that wrote it. */
+  framework: string;
+  /** Whether the auth template was included. */
+  auth: boolean;
+  /** Whether the payments screens were included. */
+  payments: boolean;
+  /** Worker-relative paths created by this run, sorted. */
+  created: string[];
+  /** Worker-relative paths that already existed and were left byte-identical, sorted. */
+  skipped: string[];
+  /**
+   * Class names Pithy's screens render that nothing in this Worker's stylesheets defines — empty on
+   * every ordinary run, and the exact list to fix when it is not.
+   *
+   * Separate from {@link created} because "wrote the screens" and "the screens are styled" are two
+   * claims and only one of them was ever reported. A backfill writes `routes/pithy/sign-in.tsx` and
+   * correctly skips the adopter's `src/styles.css`; if the rules those screens need are not on disk,
+   * the run said `created` and the adopter met an unstyled login page with nothing pointing at why.
+   *
+   * Measured against the files as they stand **after** the write, not against the template, because
+   * the template is not what renders: a stylesheet the adopter has since edited, or deleted, is the
+   * case this exists for.
+   */
+  unstyled: string[];
+  /** The derived `assets.run_worker_first` allowlist now in `wrangler.jsonc`. */
+  runWorkerFirst: string[];
+  /** The project's package manager. */
+  packageManager: PackageManager;
+  /** Dependency names added to the worker's `package.json`. */
+  dependencies: string[];
+  /** Dev-dependency names added to the worker's `package.json`. */
+  devDependencies: string[];
+  /** Script names added (or superseded, for a `dev` that still held `wrangler dev`). */
+  scripts: string[];
+}
+
+/**
+ * Whether to write one capability's screens. `--auth`/`--no-auth` and `--payments`/`--no-payments` decide
+ * outright. With neither, a human is asked (defaulting to yes when the capability is composed on this
+ * worker) and anyone else — `--json`, an agent, CI — gets that same default with no prompt, because no
+ * invocation may block.
+ *
+ * Asking for a capability's screens on a worker that does not compose it is an error, not a scaffold of
+ * broken imports.
+ */
+async function resolveScreens(
+  options: UiAddOptions,
+  screens: UiScreenSet,
+  requested: boolean | undefined,
+  composed: boolean,
+): Promise<boolean> {
+  let wanted = requested;
+  if (wanted === undefined)
+    wanted = options.prompt ? await options.prompt({ screens, suggestion: composed }) : composed;
+  if (wanted && !composed) {
+    const worker = workerName(options.workerDir);
+    throw new ValidationError({
+      message: `The ${screens} screens need the ${screens} capability, and ${worker} doesn't compose it.`,
+      action: `Run pithy add ${screens} --worker ${worker} first, or leave them out with --no-${screens}.`,
+    });
+  }
+  return wanted;
+}
+
+/** Whether a worker composes a capability by name. */
+function composes(config: WorkerConfig, capability: string): boolean {
+  return allCapabilities(config).some((composed) => composed.name === capability);
+}
+
+/**
+ * The files this run may write: the whole template on a first scaffold, and only what does not exist
+ * yet on a backfill (`--auth` after `--no-auth`).
+ *
+ * A worker that already carries a front end and gains nothing new is the "adding a UI twice" error —
+ * clean and actionable, never a partial overwrite. A worker carrying a *different* stub is refused
+ * outright: two frameworks in one worker is not a merge anyone should attempt for you.
+ */
+async function planFiles(
+  options: UiAddOptions,
+  stub: UiStub,
+  screens: { auth: boolean; payments: boolean },
+): Promise<{ files: Record<string, string>; strict: boolean }> {
+  const current = await readWorkerUi(options.workerDir);
+  const worker = workerName(options.workerDir);
+  const files = await loadStubFiles(stub, {
+    worker,
+    ...screens,
+    packageManager: options.packageManager ?? "npm",
+  });
+  if (!current) return { files, strict: true };
+
+  if (current.stub !== stub.id) {
+    throw new ConflictError({
+      message: `${worker} already has a ${current.stub} front end.`,
+      action: "One worker, one front end. Remove it, or add the new one to a different worker with --worker.",
+    });
+  }
+
+  // `pathExists`, the shared `lstat`, and not the local `access` this used to roll. `access` follows a
+  // link, so a dangling one planted at a template path answered "nothing there" — the file counted as
+  // fresh, and the plan handed it to `scaffoldFiles` to write. That is the same predicate five other
+  // modules got wrong, in the one module the tripwire could not see because it imports no writer of its
+  // own. One question, one implementation.
+  let fresh = 0;
+  for (const rel of Object.keys(files)) {
+    if (!(await pathExists(join(options.workerDir, rel)))) fresh += 1;
+  }
+  if (fresh === 0) {
+    throw new ConflictError({
+      message: `${worker} already has a ${current.stub} front end.`,
+      action: "Add screens by dropping files into src/routes/app/. Run pithy ui sync to re-derive its route allowlist.",
+    });
+  }
+  // The whole record, non-strict: the writer skips what exists and reports it, so the run says what
+  // it added AND what it left alone.
+  return { files, strict: false };
+}
+
+/**
+ * Whether Pithy's screens in this worker render styled, read off the worker exactly as it stands.
+ *
+ * The template's own files are not the answer, and neither is the plan. On a backfill the plan still
+ * carries Pithy's `src/styles.css` while the file on disk is the adopter's — so checking the plan would
+ * report a screen as styled by rules that exist in this process and nowhere else. Only the disk renders.
+ *
+ * **The whole of `src/` is swept, not the paths this run happened to plan (#401).** Two reasons, and the
+ * second is the one that matters now the finding can fail a build:
+ *
+ * - `pithy ui sync` plans nothing. A check that could only run over a plan could only run at scaffold,
+ *   which is the defect: the report ran once, printed, and nothing ever asked again.
+ * - A class defined in a stylesheet Pithy did not write is defined. An adopter with `src/brand.css` was
+ *   previously told their screens were unstyled, because that file was in no plan. A false finding is
+ *   affordable in a warning and not in a gate.
+ */
+async function unstyledOnDisk(workerDir: string): Promise<string[]> {
+  const src = join(workerDir, "src");
+  // `recursive` gives worker-relative paths under `src/`, in whatever separator the platform uses;
+  // normalized to `/` because `PITHY_SCREEN_DIR` is a path *within a scaffolded worker*, and those are
+  // written the way the templates write them. A worker with no `src/` at all answers the empty set.
+  const entries = await readdir(src, { recursive: true }).catch(() => [] as string[]);
+  const onDisk: Record<string, string> = {};
+  for (const entry of entries) {
+    const path = `src/${entry.split(sep).join("/")}`;
+    const stylesheet = path.endsWith(".css");
+    const screen = path.startsWith(PITHY_SCREEN_DIR) && path.endsWith(".tsx");
+    if (!stylesheet && !screen) continue;
+    const contents = await readOptionalFile(join(workerDir, path));
+    if (contents !== null) onDisk[path] = contents;
+  }
+  return unstyledScreenClasses(onDisk);
+}
+
+/**
+ * Every file this run may create or edit, absolute — what a failure has to put back.
+ *
+ * The template's own paths, plus the four documents `ui/wire.ts` edits rather than creates. Stated here
+ * rather than discovered afterwards, because a rollback that guesses is one that misses a file.
+ */
+function touchedPaths(options: UiAddOptions, planned: Record<string, string>): string[] {
+  return [
+    ...Object.keys(planned).map((rel) => join(options.workerDir, rel)),
+    join(options.workerDir, "wrangler.jsonc"),
+    join(options.workerDir, "pithy.worker.jsonc"),
+    join(options.workerDir, "package.json"),
+    join(options.projectDir, "tsconfig.json"),
+  ];
+}
+
+/**
+ * Scaffold a front end into one worker and wire it end to end: the client files, the `assets` stanza
+ * that serves them, the dev command `pithy dev` runs, the build command `pithy deploy` runs, and the
+ * packages the build needs. The SPA and the API stay one deploy on one origin.
+ *
+ * **A run that fails leaves the project as it found it**, and that is two things rather than one.
+ *
+ * The allowlist is derived *before* anything is written: composing the app is the step most likely to
+ * throw — a capability misconfigured, a required binding missing (#258), a syntax error in a file the
+ * adopter has edited — and it used to run after the whole template had landed. So a failure left the
+ * files written, the wiring absent, and the retry refused by this command's own "already has a front
+ * end" guard, which cannot tell a finished front end from one abandoned a minute ago (#259).
+ *
+ * And every write after that runs under {@link withRollback}, because ordering alone only removes the
+ * failure anyone has already seen: the next step added goes back on the end of the list, and the
+ * property quietly stops being true. Stated over the outcome, it survives the next step.
+ */
+export async function runUiAdd(options: UiAddOptions): Promise<UiAddReport> {
+  const stub = resolveStub(options.framework);
+  const packageManager = options.packageManager ?? (await detectPackageManager(options.projectDir));
+  const auth = await resolveScreens(options, AUTH_CAPABILITY, options.auth, composes(options.config, AUTH_CAPABILITY));
+  const payments = await resolveScreens(
+    options,
+    PAYMENTS_CAPABILITY,
+    options.payments,
+    composes(options.config, PAYMENTS_CAPABILITY),
+  );
+
+  const plan = await planFiles({ ...options, packageManager }, stub, { auth, payments });
+  // Compose first. `deriveWorkerFirst` assembles every capability's routes, once per environment, and
+  // reads nothing this run is about to write — which is what makes moving it ahead of the write legal.
+  const patterns = deriveWorkerFirst(options.config, await projectEnvironments(options.projectDir));
+
+  const scope = { root: options.projectDir, paths: touchedPaths(options, plan.files) };
+  const result = await withRollback(scope, async () => {
+    const written = await scaffoldFiles({ workerDir: options.workerDir, files: plan.files, strict: plan.strict });
+    const assets = await wireAssets(options.workerDir, patterns);
+    await wireManifest(options.workerDir, stub, packageManager);
+    const pkg = await wirePackage(options.projectDir, options.workerDir, stub);
+    // Last, and project-wide rather than per-worker: the client's programs join the root solution file so
+    // `bun run typecheck` builds them. Two tsconfigs nothing references are two tsconfigs nothing checks.
+    await wireSolution(options.projectDir, workerName(options.workerDir));
+    // Read inside the scope, because it reads the files this block just wrote — outside, a rollback
+    // would already have taken them away.
+    const unstyled = await unstyledOnDisk(options.workerDir);
+    return { written, assets, pkg, unstyled };
+  });
+
+  return {
+    worker: workerName(options.workerDir),
+    framework: stub.id,
+    auth,
+    payments,
+    created: result.written.written,
+    skipped: result.written.skipped,
+    unstyled: result.unstyled,
+    runWorkerFirst: result.assets.after,
+    packageManager,
+    dependencies: result.pkg.dependencies,
+    devDependencies: result.pkg.devDependencies,
+    scripts: result.pkg.scripts,
+  };
+}
+
+/** What `pithy ui sync` did. */
+export interface UiSyncReport {
+  /** The worker whose allowlist was re-derived. */
+  worker: string;
+  /** The allowlist before this run. */
+  before: string[];
+  /** The allowlist after it. */
+  after: string[];
+  /** Whether anything actually moved — false on a re-run, which is the point. */
+  changed: boolean;
+  /**
+   * Routes the allowlist **in the file** does not cover: the ones the SPA shell is answering with a 200
+   * and the wrong body. Always empty after a write — the run just re-derived the list — so this is the
+   * finding `--check` exists to produce, and the one thing that fails the exit.
+   */
+  uncovered: string[];
+  /**
+   * Class names Pithy's screens render that nothing in this worker's stylesheets defines — read off the
+   * worker as it stands now, not as it stood when it was scaffolded.
+   *
+   * **This is the check that used to run once and never again (#401).** It was written at `pithy ui add`
+   * because that is where the defect it caught happened: a backfill wrote the sign-in screens and
+   * correctly skipped the adopter's `src/styles.css`, and the run reported `created` over a login page
+   * whose `stack`, `divider` and `secondary` nothing defined. But `styles.css` is theirs, and the
+   * ordinary case is an edit a week later — deleting a rule, replacing the file, dropping
+   * `pithy-screens.css` in a tidy-up. None of that errors. The screen renders, unstyled, with a 200.
+   *
+   * So it belongs here too, on the one command that re-checks a front end after scaffold, and under
+   * `--check` it is one of the two findings that fail the exit. The counter-argument is real and worth
+   * stating: a class with no rule is a cosmetic defect, and a build that fails over one teaches people
+   * to write `.stack {}` and move on. What settles it is that the fix anybody actually reaches for is
+   * restoring `pithy-screens.css` or defining the rule they meant to define — and that deleting the
+   * class from the screen is also a fix, because the screen is theirs. A stub rule is available and is
+   * not what the message asks for.
+   */
+  unstyled: string[];
+  /**
+   * `assets.not_found_handling` as it stands. Reported because SPA routing depends on it: an adopter
+   * who set it to something else has deep links 404ing in Hono rather than serving the app shell, and
+   * `ui sync` does not overwrite a value they chose.
+   */
+  notFoundHandling: string | undefined;
+}
+
+/**
+ * Re-derive one worker's `assets.run_worker_first` from its current route table, or — with `check` —
+ * only report how far the file has drifted from it.
+ *
+ * The allowlist is written once, at `pithy ui add`, and every route mounted afterwards is a route the
+ * asset router answers before the worker runs. `pithy add <capability>` is one way that happens; the
+ * adopter writing a route into their own app capability is the other, and that one runs no command at
+ * all. So the allowlist has to be re-derivable on demand *and* checkable in CI, because a list that
+ * has gone stale does not fail — it returns 200 with the SPA shell.
+ *
+ * **It re-runs the unstyled check too (#401), which is the other thing that goes stale in silence.**
+ * Both findings have the same shape: a 200, the wrong output, and no error anywhere. One is the shell
+ * answering a route; the other is a screen rendering with no rules. This is the command that re-checks a
+ * front end, so it checks both, and `--check` fails on either.
+ *
+ * Creates no files either way, and re-running changes nothing.
+ */
+export async function runUiSync(options: {
+  /** The project root — where the `environments` declaration the derivation needs lives. */
+  projectDir: string;
+  /** The target worker's directory, `apps/<name>` — which is also where its name comes from. */
+  workerDir: string;
+  /** The target worker's loaded `pithy.config.ts`. */
+  config: WorkerConfig;
+  /** Report the drift and write nothing — the CI gate. */
+  check?: boolean;
+}): Promise<UiSyncReport> {
+  const worker = workerName(options.workerDir);
+  const current = await readWorkerUi(options.workerDir);
+  if (!current) {
+    throw new NotFoundError({
+      message: `${worker} has no front end.`,
+      action: `Run pithy ui add react --worker ${worker} to scaffold one.`,
+    });
+  }
+
+  const environments = await projectEnvironments(options.projectDir);
+  const after = deriveWorkerFirst(options.config, environments);
+  // Read on both paths, and before the write on the one that writes. `wireAssets` touches
+  // `wrangler.jsonc` and no stylesheet, so the answer is the same either side of it — taking it first
+  // means the report is assembled from one reading of the worker rather than two.
+  const unstyled = await unstyledOnDisk(options.workerDir);
+  if (options.check) {
+    const assets = await readAssets(options.workerDir);
+    return {
+      worker,
+      before: assets.runWorkerFirst,
+      after,
+      changed: assets.runWorkerFirst.join("\n") !== after.join("\n") || assets.notFoundHandling === undefined,
+      uncovered: uncoveredRoutes(options.config, assets.runWorkerFirst, environments),
+      unstyled,
+      notFoundHandling: assets.notFoundHandling,
+    };
+  }
+
+  // `after` above is the same derivation the write needs, so it is computed once and handed over —
+  // and, incidentally, before anything is written here too.
+  const change = await wireAssets(options.workerDir, after);
+  const before = change.before ?? [];
+  return {
+    worker,
+    before,
+    after: change.after,
+    // Every way this call can have moved the file, not just the allowlist — a report that says
+    // nothing changed while the file did is worse than no report, because CI keys off it.
+    changed: before.join("\n") !== change.after.join("\n") || change.wroteNotFoundHandling,
+    // The list was just re-derived from this same route table, so nothing is left outside it.
+    uncovered: [],
+    // Unlike `uncovered`, this one is not emptied by the write. Nothing here touches a stylesheet, so a
+    // missing rule is still missing — and saying so is the point of re-running the check at all.
+    unstyled,
+    notFoundHandling: change.notFoundHandling,
+  };
+}

package/src/ui/react.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PACKAGE_VERSION } from "@pithy-sh/core/src/version.generated";
+import { HOME_SCREEN, TEMPLATE_DIR, TEMPLATE_GROUPS, WORKER_TOKEN } from "@pithy-sh/ui-react/src/templates";
+import { kitRange } from "../project/scaffold";
+import { WRANGLER_RANGE } from "../project/workerScaffold";
+import type { UiStub, UiStubContext, UiStubFile } from "./stubs";
+
+/**
+ * The React 19 stub — the first framework `pithy ui add` scaffolds, registered through the same
+ * {@link UiStub} declaration any later framework would use.
+ *
+ * Two templates. **bare** is a SPA with one typed `fetch("/health")`: no auth imports, no dead files.
+ * **auth** is that plus the passwordless screens, a session hook, and a route guard.
+ *
+ * The screens live in `@pithy-sh/ui-react`, a template library with its own React toolchain, so they
+ * are typechecked and linted like any other source. This module is the part that belongs to the CLI:
+ * which of them a given invocation writes, and how the result is run and built. A second framework
+ * brings its own library and its own module here; neither needs to touch the other's toolchain.
+ *
+ * Every client file is `.tsx`. That is load-bearing: the Worker's own `tsconfig.json` includes
+ * `src/**\/*.ts`, which does **not** match `.tsx`, so the client never enters the Worker's program and
+ * the Worker's config needs no edit. The ambient declarations live at the Worker root as
+ * `client-env.d.ts` rather than under `src/`, because `.d.ts` *would* match that glob.
+ */
+
+/** The same path in and out — true of every template except the home screen. */
+function inPlace(paths: readonly string[]): UiStubFile[] {
+  return paths.map((path) => ({ source: path, target: path }));
+}
+
+function manifest(context: UiStubContext): UiStubFile[] {
+  const files = inPlace(TEMPLATE_GROUPS.base);
+  files.push({
+    source: context.auth ? HOME_SCREEN.auth : HOME_SCREEN.bare,
+    target: HOME_SCREEN.target,
+  });
+  // The capability groups stack rather than choose: they name disjoint files over one layout, so a Worker
+  // composing both auth and payments gets both screen sets and no path moves.
+  if (context.auth) files.push(...inPlace(TEMPLATE_GROUPS.auth));
+  if (context.payments) files.push(...inPlace(TEMPLATE_GROUPS.payments));
+  return files;
+}
+
+/** React 19, through Vite 8 and `@cloudflare/vite-plugin`. */
+export const reactStub: UiStub = {
+  id: "react",
+  description: "React 19 SPA on Vite, served by the worker as static assets",
+  templateDir: TEMPLATE_DIR,
+  manifest,
+  substitutions: (context) => ({ [WORKER_TOKEN]: context.worker }),
+  dependencies: {
+    react: "^19.2.8",
+    "react-dom": "^19.2.8",
+    // **Every screen renders through the translator seam, so the front end depends on it the way it
+    // depends on React.** This is not the auth/payments pattern and could not be: those screens are
+    // written only when their capability is composed, and their package arrives with `pithy add auth`.
+    // `src/pithy-locale.tsx`, `src/router.tsx` and the home screen all reach it — all `base`, all
+    // written on every scaffold — so a project that never composes `i18n` still imports the package, and
+    // before this line `vite build` could not resolve it. The alternative was to un-translate the base
+    // screens, which is the feature.
+    //
+    // A dependency rather than a devDependency, for the reason `react` is one: it is bundled into what
+    // the browser downloads. And core's `PACKAGE_VERSION` for the reason `@pithy-sh/vite` uses it —
+    // the release train below is what makes that honest, and `react.test.ts` holds both halves.
+    "@pithy-sh/i18n": kitRange(PACKAGE_VERSION),
+  },
+  devDependencies: {
+    "@cloudflare/vite-plugin": "^1.48.0",
+    // Derived, never a literal: `"^0.0.0"` 404'd the adopter's next install, and no release would ever
+    // have moved it. `kitRange` answers `null` while nothing under the scope is published, which drops
+    // the line entirely, and writes a real range the day one exists.
+    //
+    // **`PACKAGE_VERSION` is core's, and this is a sibling** — which `stampWorkerManifest` forbids
+    // outright, because two packages that version independently share no honest range. What makes it
+    // honest here is `.changeset/config.json`: `@pithy-sh/core` and `@pithy-sh/vite` are a `fixed` group,
+    // always released together at one version, so core's number IS vite's number. `linked` would not do
+    // it — a release touching only core leaves a linked sibling on its old version, and the range would
+    // then name something vite never published. `react.test.ts` holds the group and the equality; break
+    // either and this line goes back to inventing a version.
+    "@pithy-sh/vite": kitRange(PACKAGE_VERSION),
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.4",
+    // A DOM for the seeded gate, and for every client test the adopter writes after it. The starter's
+    // node project already collects `.tsx` co-located tests (#245) but runs them in `environment:
+    // "node"`, where `document` does not exist — so `src/turnstile.test.tsx` names its own environment
+    // in a docblock, and this is the package that has to be installed for that name to resolve (#383).
+    "happy-dom": "^20.11.2",
+    vite: "^8.2.1",
+    // The Worker's own pin, imported from the producer that writes it — this was a third copy of a
+    // literal that `scaffoldParity.test.ts` held between only the other two.
+    wrangler: WRANGLER_RANGE,
+  },
+  // `--configLoader runner` is load-bearing, not a preference. Vite's default config loader bundles
+  // vite.config.ts and leaves every bare import external, so Node itself has to import
+  // `@pithy-sh/vite` — which, like every package here, ships raw TypeScript with extensionless
+  // relative imports. Node cannot resolve those, and refuses to strip types under node_modules at
+  // all. The runner loads the config through Vite's own resolver instead, where both are ordinary.
+  devCommand: (port) => ["vite", "dev", "--configLoader", "runner", "--strictPort", "--port", port],
+  readySignal: "ready in \\d+",
+  buildCommand: ["vite", "build", "--configLoader", "runner"],
+  // The adopter's own entry points. Every one loads vite.config.ts, so every one needs the runner —
+  // and `dev` deliberately omits `--port`/`--strictPort`: a bare `vite dev` is someone working on the
+  // front end alone, where Vite picking its own port is right. `pithy dev` is what pins ports.
+  scripts: {
+    dev: "vite dev --configLoader runner",
+    build: "vite build --configLoader runner",
+    preview: "vite preview --configLoader runner",
+  },
+};