@pithy-sh/cli 0.1.0

package/src/ui/routeAllowlist.ts

@@ -0,0 +1,208 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { createBackend } from "@pithy-sh/core/src/createBackend";
+import { CI_ENV } from "@pithy-sh/core/src/env/ci";
+import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
+import { HEALTH_PATH } from "@pithy-sh/core/src/worker/health";
+import { ENVIRONMENT_VAR } from "@pithy-sh/core/src/worker/identity";
+import type { WorkerConfig } from "../project/config";
+
+/**
+ * `assets.run_worker_first` — the explicit allowlist of paths that reach the Worker instead of the
+ * static assets.
+ *
+ * It has to be an allowlist, and it has to be derived, because the ordering is not what it looks
+ * like: with `not_found_handling: "single-page-application"`, the asset router answers a request with
+ * `index.html` **before** the Worker runs. A `run_worker_first` that names the wrong prefix does not
+ * degrade — `GET /health` comes back as 200 text/html and `POST /auth/sign-in/magic-link` as 405,
+ * with the Worker never invoked. Pithy's routes sit at capability base paths (`/auth`,
+ * `/leaderboard`, `/ledger`, `/payments`, …) plus `/health`; none of them is under `/api`. So the only
+ * correct list is the one the Worker's own composed route table produces.
+ *
+ * Two verified details shape the emitted patterns:
+ * - `"/auth/*"` does **not** match bare `"/auth"`, so each segment emits both.
+ * - a bare-prefix glob like `"/media*"` over-matches `/mediafoo`, so it is never emitted.
+ *
+ * **Why a list at all, when dropping it makes `fetch` calls work by themselves.** The asset worker's
+ * `canFetch` is one line, and it decides everything here:
+ *
+ * ```js
+ * if (!(has_static_routing || (navigateFlag && request.headers.get("Sec-Fetch-Mode") === "navigate")))
+ *   configuration = { ...configuration, not_found_handling: "none" };
+ * ```
+ *
+ * An array `run_worker_first` sets `has_static_routing`. With it, a path the list misses is answered
+ * by the SPA shell whatever the method — a 200 with the wrong body, the worst failure available, and
+ * the bug this file's derivation exists to prevent. *Without* it, every non-navigation falls through
+ * to the Worker, which is why removing the key looks like a clean fix from a browser's `fetch` and
+ * from curl.
+ *
+ * It is not one, because the navigation half stays: with no list, a request carrying
+ * `Sec-Fetch-Mode: navigate` keeps `not_found_handling` and gets the shell. A magic-link click lands
+ * on `/auth/magic-link/verify` and an OAuth provider redirects to `/auth/callback/<provider>`, both as
+ * top-level navigations — so dropping the list trades every API route for the two flows that carry
+ * Pithy's sign-in, and trades them just as silently. The list stays; {@link uncoveredRoutes} is how
+ * its drift is made loud instead.
+ */
+
+/**
+ * The first path segment of a Hono route pattern, or `null` when it cannot be expressed as an
+ * allowlist entry. Wildcards and the root are `null` (core's own `app.use("*")` middleware lands
+ * here). A `:param` in the first position is `null` too — a Worker mounted at a bare parameter root
+ * claims every path, which no allowlist can say and no Pithy capability does.
+ *
+ * A wildcard in a LATER segment still yields its prefix: `/auth/*` is `auth`, which is how the auth
+ * capability's Better Auth catch-all gets covered.
+ *
+ * **A route the adopter mounts at `/` is deliberately not allowlisted.** In a Worker that serves a
+ * SPA, `/` is the app shell — that is what `not_found_handling` is for. An adopter wanting an API
+ * response at the root of a UI-bearing Worker has a real conflict with the front end, and this
+ * resolves it in the front end's favor rather than shadowing the app's own entry point. It is
+ * silent, so `docs/UI.md` says so as well.
+ */
+export function firstSegment(path: string): string | null {
+  const segment = path.replace(/^\/+/, "").split("/")[0] ?? "";
+  if (segment === "" || segment.includes("*") || segment.startsWith(":")) return null;
+  return segment;
+}
+
+/**
+ * The `run_worker_first` patterns for a route table: `"/<segment>"` and `"/<segment>/*"` for each
+ * distinct first segment, sorted so the written config is stable run to run. The health route is always
+ * present — `createBackend` serves it for every Worker, and it is the one route an adopter is most
+ * likely to check first.
+ *
+ * Seeded from `HEALTH_PATH` through the same `firstSegment` every other route goes through, rather than
+ * from a `"health"` written here (#400). One statement in `@pithy-sh/core`, and the allowlist follows a
+ * rename instead of quietly leaving the renamed route shadowed by the SPA shell.
+ */
+export function workerFirstPatterns(paths: readonly string[]): string[] {
+  const segments = new Set<string>();
+  for (const path of [HEALTH_PATH, ...paths]) {
+    const segment = firstSegment(path);
+    if (segment) segments.add(segment);
+  }
+  return [...segments].sort().flatMap((segment) => [`/${segment}`, `/${segment}/*`]);
+}
+
+/**
+ * **A Worker has one route table per environment, not one route table.** That is the whole of #255.
+ *
+ * A capability may decide at *registration* whether to mount a route, and `@pithy-sh/auth` does: its
+ * dev-login route is mounted only when the composition's `ENVIRONMENT` is `dev` and `CI` is unset. Both
+ * gates are right — the route mints an authenticated session with no credential presented, so its
+ * absence from a production route table is the security property, not an implementation detail.
+ *
+ * The consequence is that composing the app *once*, under whatever environment the command happened to
+ * run in, produces the route table of that environment and calls it the Worker's. `pithy ui sync` runs
+ * with nothing stamped, so it composed a not-`dev` app, never saw `/__pithy/dev-login`, wrote an
+ * allowlist without it — and `--check` then reported `every route reaches the worker`, which is the one
+ * claim that command exists to make.
+ *
+ * So the environment is an *input* here, and every route table is taken.
+ *
+ * ## Why `process.env`
+ *
+ * Because that is the seam a capability reads. `createBackend` calls `routes()` with no environment
+ * argument — in a Worker there is none to give, since bindings arrive per request — so a registration-time
+ * gate reads `process.env` (`@pithy-sh/core`'s `env/ambient`), which workerd populates from the script's
+ * own vars before the first request. Under Node it is the host's. Setting it around a synchronous
+ * composition and restoring it in a `finally` is therefore not a trick played on the capability; it is
+ * the only way to ask it the question it answers.
+ *
+ * ## Why `CI` is cleared rather than honored
+ *
+ * `ui sync --check` is a CI gate, and `ui sync` runs on a laptop. If the derivation honored `CI`, those
+ * two would derive different lists from the same repository: CI would demand the shorter one and fail on
+ * the file a developer correctly wrote. A list is only checkable if it is a function of the project.
+ *
+ * The asymmetry makes the choice free. An allowlist entry nothing serves costs a 404 from the Worker,
+ * which is the right answer. A missing entry costs a 200 with the SPA shell — a request that was never
+ * even seen by the code meant to answer it.
+ */
+function composedPathsIn(config: WorkerConfig, environment: string): string[] {
+  const previousEnvironment = process.env[ENVIRONMENT_VAR];
+  const previousCi = process.env[CI_ENV];
+  process.env[ENVIRONMENT_VAR] = environment;
+  delete process.env[CI_ENV];
+  try {
+    const app = createBackend({ capabilities: config.capabilities, ...(config.app ? { app: config.app } : {}) });
+    return app.routes.map((route) => route.path);
+  } finally {
+    // Restored, not defaulted: a variable this process never had must not exist afterwards, or the next
+    // thing to read `ENVIRONMENT` in this CLI run is told something the project never said.
+    if (previousEnvironment === undefined) delete process.env[ENVIRONMENT_VAR];
+    else process.env[ENVIRONMENT_VAR] = previousEnvironment;
+    if (previousCi === undefined) delete process.env[CI_ENV];
+    else process.env[CI_ENV] = previousCi;
+  }
+}
+
+/**
+ * Every environment a route table is taken in: the ones the project declares, plus the local one.
+ *
+ * `dev` is added here rather than asked for, because {@link DeclaredEnvironments} refuses it — it is the
+ * top-level wrangler stanza, it never deploys, and it always exists. A caller cannot pass it, so a
+ * derivation that waited to be handed it would have missed exactly the environment `pithy dev` runs, on
+ * every project there is. Which is the bug.
+ */
+function derivationEnvironments(environments: readonly string[]): string[] {
+  return [...new Set([...environments, LOCAL_ENVIRONMENT])];
+}
+
+/**
+ * A Worker's real composed route table, unioned across every environment it has. The config is code, so
+ * the only honest source is the assembled app: `createBackend` mounts every capability's routes onto one
+ * Hono instance, and `app.routes` carries the pattern intact — see {@link composedPathsIn} for why the
+ * app is assembled once per environment rather than once.
+ *
+ * `environments` is the project's declaration, from the root `pithy.config.ts`. It has no default: a
+ * defaulted environment set is how a caller silently derives the allowlist of a project that is not the
+ * one in front of it.
+ */
+export function composedPaths(config: WorkerConfig, environments: readonly string[]): string[] {
+  const paths = new Set<string>();
+  for (const environment of derivationEnvironments(environments)) {
+    for (const path of composedPathsIn(config, environment)) paths.add(path);
+  }
+  return [...paths];
+}
+
+/** Derive the allowlist from a Worker's real composed route table, in every environment it has. */
+export function deriveWorkerFirst(config: WorkerConfig, environments: readonly string[]): string[] {
+  return workerFirstPatterns(composedPaths(config, environments));
+}
+
+/**
+ * The routes `patterns` does not cover — the drift `pithy ui sync --check` gates on.
+ *
+ * The list is derived once, at `pithy ui add`, and every route mounted afterwards is a route the SPA
+ * shell answers with a 200. That includes routes the adopter writes into their **own** app capability,
+ * which no `pithy add` and no `pithy remove` is present for, so nothing but a comparison can catch
+ * them. It compares by first segment, because that is the unit the patterns are emitted in: a segment
+ * whose pair is in the list covers every route beneath it.
+ *
+ * A route {@link firstSegment} cannot express is never reported. `core`'s own `app.use("*")` and a
+ * route at `/` are not drift — they are paths this derivation deliberately leaves to the shell, and a
+ * check that flagged them would mark every project drifted forever, which is how a check gets ignored.
+ *
+ * **The invariant it gates is over every environment the project has**, not over the one this process
+ * happens to be: a route the Worker mounts in any of them is a route the asset handler must not answer
+ * first. Stated over one composition, the check passed with the defect present — see {@link composedPaths}.
+ */
+export function uncoveredRoutes(
+  config: WorkerConfig,
+  patterns: readonly string[],
+  environments: readonly string[],
+): string[] {
+  const covered = new Set(patterns);
+  const uncovered = new Set<string>();
+  for (const path of composedPaths(config, environments)) {
+    const segment = firstSegment(path);
+    if (!segment) continue;
+    if (covered.has(`/${segment}`) && covered.has(`/${segment}/*`)) continue;
+    uncovered.add(path);
+  }
+  return [...uncovered].sort();
+}

package/src/ui/scaffold.ts

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+import { writeFileAtomic } from "../project/atomic";
+import { ensureScaffoldPath, pathExists } from "../project/scaffold";
+
+/**
+ * Create, never overwrite.
+ *
+ * A stub is scaffolded once and then it belongs to the adopter. Pithy may add files that do not exist
+ * yet — an OTP screen today, whatever templates follow — because a new file cannot clobber work
+ * somebody did. It may never rewrite one. That asymmetry is the whole ownership rule, and it is what
+ * lets `pithy ui add --auth` backfill a scaffold created with `--no-auth`.
+ *
+ * The check runs over **every** path before anything is written, so a collision is a clean error
+ * rather than a half-written directory.
+ */
+
+/** The directory every Worker lives under, and the segment `pithy ui add` composes a path through. */
+const APPS_DIR = "apps";
+
+/**
+ * The boundary {@link ensureScaffoldPath} walks down from: **the project root**, not the worker.
+ *
+ * The primitive checks every path from its root down to the target, and skips the root itself — the root
+ * is the adopter's directory, which they may legitimately keep behind a symlink. Bounding it at
+ * `workerDir` therefore put `apps` *and* `apps/<worker>` above the walk, where nothing looked at them,
+ * and a symlink at either carried the whole front end out of the project. Reproduced: `pithy ui add
+ * react --worker board` with `apps` linked outside wrote ten files there and printed "Done."
+ *
+ * `apps/<worker>` is a path **Pithy composed**, out of a name, exactly like the directories under it. So
+ * it belongs inside the walk, and the way to put it there is to start one directory above `apps`.
+ *
+ * The layout is read from the path rather than guessed at: this is only the boundary when the worker
+ * really does sit at `apps/<name>`, which is the shape `pithy ui add` resolves and the shape every other
+ * function in this flow assumes (`workerName` is `basename(workerDir)`). Handed anything else — a bare
+ * directory, as the unit tests pass — there is no `apps` segment Pithy invented, nothing above the
+ * directory is ours to judge, and the boundary is the directory itself.
+ */
+function scaffoldRoot(workerDir: string): string {
+  const here = resolve(workerDir);
+  return basename(dirname(here)) === APPS_DIR ? resolve(here, "..", "..") : here;
+}
+
+/** What one scaffold run wrote. */
+export interface ScaffoldResult {
+  /** The worker-relative paths written, sorted. Empty when every file already existed. */
+  written: string[];
+  /** The worker-relative paths already present and therefore left byte-identical, sorted. */
+  skipped: string[];
+}
+
+/**
+ * Write a stub's file record into `workerDir`, creating parent directories.
+ *
+ * Every path that already exists is a `ConflictError` naming all of them, and nothing is written —
+ * `strict` is the initial `pithy ui add`, where a collision means the worker already has a front end
+ * of some sort and guessing which file to keep is not ours to do.
+ *
+ * With `strict` off (the backfill path) an existing file is skipped and reported instead. Either way
+ * no existing byte changes.
+ */
+export async function scaffoldFiles(options: {
+  /** The worker's directory — `apps/<name>`. Every path below it is checked; the directory itself is the
+   * caller's, and `pithy worker add` is what gates *that* one. */
+  workerDir: string;
+  /** The stub's file record: worker-relative path → contents. */
+  files: Record<string, string>;
+  /** Refuse the whole run if any path exists (the default). Off for a backfill, which skips instead. */
+  strict?: boolean;
+}): Promise<ScaffoldResult> {
+  const entries = Object.entries(options.files).sort(([a], [b]) => a.localeCompare(b));
+  const root = scaffoldRoot(options.workerDir);
+
+  const skipped: string[] = [];
+  for (const [rel] of entries) {
+    const path = join(options.workerDir, rel);
+    // Every directory this run would create or write through, before any of it is created. `exists()` here
+    // was `access`, which follows a link and answers about its destination — so a symlink at
+    // `apps/<worker>/src` read as "src/client.tsx is missing", cleared the gate, and `pithy ui add react`
+    // wrote six files of the front end outside the project and exited 0. Reproduced against the real CLI.
+    //
+    // From {@link scaffoldRoot}, not from `workerDir`: bounded at the worker, the two segments above it
+    // were outside the walk and a link at either escaped just as completely.
+    //
+    // The refusal covers the backfill (`strict: false`) too, and that is not the same rule as the skip
+    // below. A file already *there* is safe to skip because nothing is written to it. A link where a
+    // directory belongs is the opposite: the file under it does not exist, so the backfill writes — outside.
+    await ensureScaffoldPath(root, dirname(path));
+    if (await pathExists(path)) skipped.push(rel);
+  }
+
+  if (skipped.length > 0 && options.strict !== false) {
+    throw new ConflictError({
+      message: `${skipped.length === 1 ? "This file already exists" : "These files already exist"}: ${skipped.join(", ")}.`,
+      action: "Pithy never overwrites a file it did not just write. Move or delete them, then run pithy ui add again.",
+    });
+  }
+
+  const written: string[] = [];
+  for (const [rel, contents] of entries) {
+    if (skipped.includes(rel)) continue;
+    const path = join(options.workerDir, rel);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFileAtomic(path, contents);
+    written.push(rel);
+  }
+
+  return { written, skipped };
+}

package/src/ui/screenStyles.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **A screen this command writes renders styled, or the command says exactly what is missing.**
+ *
+ * `pithy ui add` writes only what does not exist, which is right and is what makes a backfill safe: an
+ * adopter's `src/styles.css` is theirs, and overwriting it would destroy their design. But the screens
+ * and the rules they need were once one file, so the backfill wrote `routes/pithy/sign-in.tsx` —
+ * rendering `stack`, `divider` and `secondary` — while correctly skipping the only file that defined
+ * them, and reported the result as `created`. An adopter's first sight of the feature they had just
+ * enabled was an unstyled login page.
+ *
+ * The structural half of the fix is `src/pithy-screens.css`: Pithy's screens carry their own stylesheet,
+ * in the `base` group, so the run that writes a screen writes its rules. This module is the half that
+ * keeps it true — it extracts what the screens render and what the stylesheets define, and diffs them.
+ *
+ * It runs in three places, and the third is why it is a module rather than a test helper:
+ *
+ * - **As a gate**, over the template itself. A screen gaining a class whose rule lives somewhere the
+ *   backfill never writes fails CI. That is the drift that produced this, in that direction.
+ * - **As output**, at `pithy ui add`, over what that run left on disk. A stylesheet the adopter has
+ *   since edited, a `pithy-screens.css` they deleted, a screen of their own under `routes/pithy/` —
+ *   none of those are things the template can be checked for, and all of them end in the same unstyled
+ *   screen. So the report names the classes rather than claiming the screens are fine.
+ * - **As a gate again**, at `pithy ui sync --check`, where a non-empty finding exits 1 (#401). It used
+ *   to run only at scaffold, print, and not affect the exit — but `styles.css` is the adopter's, and the
+ *   ordinary way a screen goes unstyled is an edit a week later. A one-shot warning cannot see that.
+ *   `docs/UI.md` § *Two stylesheets, and why* is where an adopter reads this.
+ */
+
+/** Where Pithy's own screens live inside a scaffolded Worker — the only files this checks. */
+export const PITHY_SCREEN_DIR = "src/routes/pithy/";
+
+/**
+ * The class names a React source renders.
+ *
+ * Both `className="a b"` and `className={cond ? "a" : "b"}` are read, because both put a literal class
+ * name in the markup and only one of them is the shape the templates happen to use today. An expression
+ * with no literal at all contributes nothing, which is the honest answer — a class assembled at runtime
+ * is not something a static check can claim to have verified.
+ *
+ * ## The blind spot, stated because a template author will meet it
+ *
+ * **`className={CHECKOUT_FRAME}` contributes nothing.** A bare identifier is an expression with no
+ * literal in it, so this reads no name from it, and the check downstream reports the screen as fully
+ * styled. Today that is harmless and deliberate: `CHECKOUT_FRAME` is `"pithy-checkout"`, the hosted
+ * checkout's mount point, and it is defined by no stylesheet Pithy ships because it is an adopter hook.
+ * The one Pithy-rendered class with no rule anywhere is exactly the one this cannot see (#391 item E).
+ *
+ * A future constant that *is* meant to be styled would be invisible the same way, and now that a finding
+ * fails `pithy ui sync --check` (#401), invisible means it passes. Resolving identifiers across files is
+ * not the fix — it would surface `pithy-checkout` and force an exemption list for a class that is
+ * correctly undefined. **Write the name as a literal in the `className` if you want it checked.**
+ */
+export function renderedClassNames(source: string): string[] {
+  const names = new Set<string>();
+  for (const match of source.matchAll(/className\s*=\s*(?:"([^"]*)"|\{([^}]*)\})/g)) {
+    const literals =
+      match[1] !== undefined ? [match[1]] : [...(match[2] ?? "").matchAll(/"([^"]*)"/g)].map((m) => m[1]);
+    for (const literal of literals) {
+      for (const name of (literal ?? "").split(/\s+/)) if (name) names.add(name);
+    }
+  }
+  return [...names].sort();
+}
+
+/**
+ * The class names a stylesheet defines.
+ *
+ * Read from the selector preludes rather than by scanning the whole text, so a `.secondary` inside a
+ * comment or a `content: ".x"` string is not mistaken for a rule. A prelude is whatever precedes a `{`
+ * since the last `{`, `}` or `;`, which walks nested blocks at any depth — and that is what lets it see
+ * inside `@layer` and `@media`. The layer is how these rules stay overridable, so a reader that could
+ * not look into one would report every class as undefined.
+ *
+ * **Its own `/* … *\/` strip, and it stays one (#439).** Every TypeScript-source scan in this repository
+ * reads through `blankComments` in `@pithy-sh/core/src/text/comments`, because a pattern over comments
+ * cannot tell a comment from a `//` in a URL or a `/*` in a glob. CSS has neither: no line comments at
+ * all, and no string a `/*` can hide in that this reader would reach — a `content: ".x"` is a value,
+ * inside a block this walk has already entered. A stripper written for TypeScript would also have to
+ * guess at `/` as a divide and as a regex, which is a guess with nothing to gain here.
+ */
+export function definedClassNames(css: string): string[] {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, " ");
+  const names = new Set<string>();
+  let prelude = "";
+  for (const character of withoutComments) {
+    if (character === "{") {
+      // An at-rule's prelude (`@layer pithy`, `@media …`) names no selector; its body is walked next.
+      if (!prelude.trim().startsWith("@")) {
+        for (const match of prelude.matchAll(/\.(-?[A-Za-z_][\w-]*)/g)) if (match[1]) names.add(match[1]);
+      }
+      prelude = "";
+    } else if (character === "}" || character === ";") {
+      // A declaration ends at `;` and a block at `}`; either way what came before is not a selector.
+      prelude = "";
+    } else {
+      prelude += character;
+    }
+  }
+  return [...names].sort();
+}
+
+/** One scaffolded file, keyed the way `pithy ui` keys everything: relative to `apps/<worker>/`. */
+export type ScaffoldedFiles = Readonly<Record<string, string>>;
+
+/**
+ * The class names Pithy's screens render that no stylesheet in the same set defines — empty, or the
+ * exact list a report has to name.
+ *
+ * Every `.css` in the set counts, not only Pithy's own: a project whose stylesheet already defines
+ * `stack` is not broken, and a check that insisted the rule live in a particular file would be
+ * enforcing a layout rather than the property that matters.
+ */
+export function unstyledScreenClasses(files: ScaffoldedFiles): string[] {
+  const defined = new Set<string>();
+  for (const [path, contents] of Object.entries(files)) {
+    if (path.endsWith(".css")) for (const name of definedClassNames(contents)) defined.add(name);
+  }
+  const missing = new Set<string>();
+  for (const [path, contents] of Object.entries(files)) {
+    if (!path.startsWith(PITHY_SCREEN_DIR) || !path.endsWith(".tsx")) continue;
+    for (const name of renderedClassNames(contents)) if (!defined.has(name)) missing.add(name);
+  }
+  return [...missing].sort();
+}

package/src/ui/stubs.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import type { PackageManager } from "../project/packageManager";
+import { reactStub } from "./react";
+
+/**
+ * The framework-stub contract — everything `pithy ui` needs to scaffold a front end into a Worker and
+ * everything `pithy dev` and `pithy deploy` need to run and build it afterwards. Nothing more abstract
+ * than that: React 19 is the only stub today, so the interface describes the two jobs a stub actually
+ * has (write files, declare its commands) rather than a framework model invented against one example.
+ */
+
+/** What a stub is told about the Worker it is being scaffolded into. */
+export interface UiStubContext {
+  /**
+   * The target Worker's **directory** name — the `<name>` in `apps/<name>`.
+   *
+   * Not its deployed name: a Worker deploys as `<project>-<worker>`, and every use of this value is a path
+   * or a build-state file that sits beside the ones `pithy init` already named after the directory.
+   */
+  worker: string;
+  /** Whether to write the auth template (the passwordless screens) on top of the bare SPA. */
+  auth: boolean;
+  /**
+   * Whether to write the payments screens — the paywall and the subscription status page.
+   *
+   * A second capability-gated screen set, chosen exactly the way `auth` is. It rides on the target Worker
+   * composing `payments`, and it stacks: a Worker with both gets both, because the groups name disjoint
+   * files over one layout.
+   */
+  payments: boolean;
+  /** The project's package manager — what the generated docs and commands tell the adopter to run. */
+  packageManager: PackageManager;
+}
+
+/** One file a stub writes: where it comes from in the template tree, and where it lands in the Worker. */
+export interface UiStubFile {
+  /** Path within the stub's `templateDir`. */
+  source: string;
+  /** Path relative to `apps/<worker>/`. Usually the same as `source`, but not always — the bare
+   *  template's home screen lives beside the auth one as `home.bare.tsx` so both compile in place. */
+  target: string;
+}
+
+/** One framework stub: the files it writes, the packages it needs, and how it is run and built. */
+export interface UiStub {
+  /** The positional `pithy ui add <framework>` takes, e.g. `react`. */
+  id: string;
+  /** One line, for `pithy ui list`. */
+  description: string;
+  /**
+   * The root of this stub's template tree — real files on disk, in the stub's own template library
+   * (`@pithy-sh/ui-react` for React).
+   *
+   * They are real files rather than string literals so that CI typechecks them and Biome lints them:
+   * ~800 lines of React that only ever existed as a template literal is 800 lines no gate can see.
+   * They live in a separate package because a framework's templates need that framework's toolchain
+   * to be checked — folding them in here would make the CLI carry every framework's devDependencies
+   * and every framework's tsconfig, to typecheck files it only ever copies.
+   *
+   * The tree mirrors the scaffolded layout exactly, which is what lets a screen's `../../router`
+   * import resolve in the template as well as in the Worker it is copied into.
+   */
+  templateDir: string;
+  /**
+   * Every file this stub writes, for a given context. **Pure** — no filesystem, no clock, no
+   * randomness — so the whole file set is assertable as a value in a test, and so the
+   * create-never-overwrite check can see every target path before anything is read or written.
+   * {@link loadStubFiles} is what turns this declaration into contents.
+   */
+  manifest(context: UiStubContext): UiStubFile[];
+  /**
+   * Literal tokens replaced in every template's text, e.g. `__PITHY_WORKER__` → the Worker's name.
+   * Pure, and deliberately tiny: a template that needs more than a name substituted is a template
+   * that should have been two files.
+   */
+  substitutions(context: UiStubContext): Record<string, string>;
+  /**
+   * Runtime dependencies merged into the Worker's `package.json`.
+   *
+   * A **null** range means "declare nothing" — the package is needed, but no range exists that the
+   * registry could resolve. That is the state every `@pithy-sh/*` package is in until the scope
+   * publishes, and it is `kitRange` that decides, not this declaration: see {@link devDependencies}.
+   */
+  dependencies: Record<string, string | null>;
+  /**
+   * Build-time dependencies merged into the Worker's `package.json`.
+   *
+   * Every `@pithy-sh/*` range here is `kitRange(PACKAGE_VERSION)` rather than a literal, for the reason
+   * `stampWorkerManifest` gives: a hardcoded `"^0.0.0"` 404s the adopter's next install today and keeps
+   * 404ing after release, because no release moves it. `null` drops the line; a real version writes it.
+   */
+  devDependencies: Record<string, string | null>;
+  /**
+   * The dev argv **without** a package-manager prefix, for a given port. `wire` runs it through the
+   * adopter's `execArgs` before persisting, so a Bun project gets `bun x vite dev …` and an npm project
+   * `npx vite dev …` — the same rule `buildCommand` follows, and the reason adoption is never gated
+   * behind Bun. `--strictPort` is not optional: without it Vite silently increments off a busy port,
+   * which breaks Pithy's rule that ports are assigned at feature creation, never probed at startup.
+   */
+  devCommand(port: string): string[];
+  /** Regex source marking "ready" in this process's output — `pithy dev` matches it to release the gate. */
+  readySignal: string;
+  /** The build argv, run through the adopter's package manager before `wrangler deploy`. */
+  buildCommand: string[];
+  /**
+   * The `package.json` scripts merged into the target Worker — the adopter's own entry points, for
+   * when they reach past `pithy dev`/`pithy deploy` and run the tool directly.
+   *
+   * Declared by the stub rather than hardcoded by the wiring, because they must not drift from
+   * {@link devCommand} and {@link buildCommand}. They carry the same flags for the same reasons: a
+   * `build` script missing `--configLoader runner` fails to load `vite.config.ts` at all, and the
+   * adopter meets that as a raw Node resolution error on the most ordinary command there is.
+   */
+  scripts: Record<string, string>;
+}
+
+/** Every framework stub `pithy ui add` can scaffold, keyed by its `id`. */
+export const UI_STUBS: Record<string, UiStub> = {
+  [reactStub.id]: reactStub,
+};
+
+/** The stub a `<framework>` positional names, or an actionable error pointing at `pithy ui list`. */
+export function resolveStub(id: string): UiStub {
+  const stub = UI_STUBS[id];
+  if (!stub) {
+    throw new NotFoundError({
+      message: `No UI stub named "${id}".`,
+      action: `Run pithy ui list to see the frameworks you can add. Known: ${Object.keys(UI_STUBS).join(", ")}.`,
+    });
+  }
+  return stub;
+}

package/src/ui/templates.ts

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { UiStub, UiStubContext } from "./stubs";
+
+/**
+ * Turn a stub's declaration into the file contents it writes.
+ *
+ * A stub declares *what* it writes ({@link UiStub.manifest}) and keeps that pure; this is the one
+ * place that reads the template tree off disk. Splitting it that way is what lets the screens be real
+ * `.tsx` files — typechecked by CI, linted by Biome, readable in a diff — while the file set a given
+ * invocation produces stays assertable as a plain value.
+ */
+
+/** Replace every literal token in `text`. Tokens are fixed strings, never patterns. */
+function substitute(text: string, tokens: Record<string, string>): string {
+  let out = text;
+  for (const [token, value] of Object.entries(tokens)) out = out.split(token).join(value);
+  return out;
+}
+
+/**
+ * Read every file a stub writes for this context, keyed by its path relative to `apps/<worker>/`.
+ *
+ * A missing template is an internal error, not an adopter error: it means this package shipped
+ * without part of its own template tree, and no adopter action can fix it.
+ */
+export async function loadStubFiles(stub: UiStub, context: UiStubContext): Promise<Record<string, string>> {
+  const tokens = stub.substitutions(context);
+  const files: Record<string, string> = {};
+  for (const file of stub.manifest(context)) {
+    const path = join(stub.templateDir, file.source);
+    let text: string;
+    try {
+      text = await readFile(path, "utf8");
+    } catch (cause) {
+      throw new InternalError(
+        {
+          message: `The ${stub.id} front-end template is incomplete.`,
+          action: "Reinstall @pithy-sh/cli. This is a packaging fault, not something in your project.",
+          detail: `missing template file ${path}`,
+        },
+        { cause },
+      );
+    }
+    files[file.target] = substitute(text, tokens);
+  }
+  return files;
+}