@pithy-sh/cli 0.1.0

package/src/ui/wire.ts

@@ -0,0 +1,311 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { parse } from "comment-json";
+import { writeFileAtomic } from "../project/atomic";
+import { writeJsonc } from "../project/jsonc";
+import { alreadyProvided, execArgs, type PackageManager } from "../project/packageManager";
+import { readOptionalFile, requireRecord } from "../project/readOptionalFile";
+import { DEV_PORT_TOKEN } from "../project/workerManifest";
+import { readWranglerConfig, writeWranglerConfig } from "../project/wrangler";
+import type { UiStub } from "./stubs";
+import { readManifestDocument, writeManifestDocument } from "./workerUi";
+
+/**
+ * The four files `pithy ui` edits rather than creates: the worker's `wrangler.jsonc` (how the built
+ * assets are served), its `pithy.worker.jsonc` (how `pithy dev` runs it and `pithy deploy` builds it),
+ * its `package.json` (the stub's packages and scripts), and the project's root `tsconfig.json` (which
+ * programs `bun run typecheck` builds).
+ *
+ * All four are edited in place and comment-preserving. comment-json keeps an adopter's notes as
+ * symbol-keyed properties on the very object or array they hang off, so a replaced array is a
+ * deleted comment — every update below mutates what is already there.
+ */
+
+/** The `assets` slice of a worker's `wrangler.jsonc`. */
+interface AssetsStanza {
+  not_found_handling?: string;
+  run_worker_first?: string[];
+}
+
+/** What {@link wireAssets} changed — the before/after `pithy ui sync` reports. */
+export interface AssetsChange {
+  /** The previous `run_worker_first`, or `null` when there was no `assets` stanza at all. */
+  before: string[] | null;
+  /** The derived allowlist now in the file. */
+  after: string[];
+  /** `not_found_handling` as it stands now — written when absent, left alone when the adopter set it. */
+  notFoundHandling: string | undefined;
+  /** True when this call wrote `not_found_handling`, so a report can say the file moved. */
+  wroteNotFoundHandling: boolean;
+}
+
+/** SPA routing: a request matching no asset is answered with `index.html` rather than a 404. */
+const SPA_NOT_FOUND = "single-page-application";
+
+/**
+ * The `assets` stanza as the file currently holds it, without touching it — what `pithy ui sync
+ * --check` reads. A missing stanza, or a `run_worker_first` that is not an array, both come back as an
+ * empty list: neither is a list this Worker is relying on.
+ *
+ * Separate from {@link wireAssets} rather than a flag on it, because a check that can write is a check
+ * nobody can run twice for the same answer.
+ */
+export async function readAssets(workerDir: string): Promise<{ runWorkerFirst: string[]; notFoundHandling?: string }> {
+  const document = (await readWranglerConfig(workerDir)) as { assets?: AssetsStanza };
+  const assets = document.assets;
+  return {
+    runWorkerFirst: Array.isArray(assets?.run_worker_first) ? [...assets.run_worker_first] : [],
+    ...(assets?.not_found_handling === undefined ? {} : { notFoundHandling: assets.not_found_handling }),
+  };
+}
+
+/**
+ * Write the `assets` stanza into a worker's `wrangler.jsonc`.
+ *
+ * `assets.directory` is deliberately **not** written. Under the Vite plugin it is supplied by the
+ * plugin, which overwrites whatever is there without complaining — so a `directory` in the adopter's
+ * config would be a line that looks authoritative and is not.
+ *
+ * `not_found_handling` is written only when **absent**. The allowlist is derived and must be
+ * re-derived on every sync; `not_found_handling` is a routing choice, and once the file has one it is
+ * the adopter's. Overwriting it on every `pithy ui sync` would silently undo a deliberate change —
+ * create-never-overwrite applied to a value rather than a file.
+ *
+ * Idempotent: re-running rewrites the same derived list. That is exactly what `pithy ui sync` is.
+ *
+ * **The allowlist arrives derived; this function does not compose anything.** It used to take the config
+ * and call {@link deriveWorkerFirst} itself, which put the step that can fail — assembling every
+ * capability's routes, in every environment — *inside* the writer, and therefore after `pithy ui add`
+ * had already written its whole template (#259). The derivation is the caller's now, so a composition
+ * that throws throws before a byte is written.
+ */
+export async function wireAssets(workerDir: string, patterns: readonly string[]): Promise<AssetsChange> {
+  const document = (await readWranglerConfig(workerDir)) as { assets?: AssetsStanza };
+
+  const existing = document.assets;
+  let before: string[] | null = null;
+  if (existing) before = Array.isArray(existing.run_worker_first) ? [...existing.run_worker_first] : [];
+
+  const assets: AssetsStanza = existing ?? {};
+  const wroteNotFoundHandling = assets.not_found_handling === undefined;
+  if (wroteNotFoundHandling) assets.not_found_handling = SPA_NOT_FOUND;
+  if (Array.isArray(assets.run_worker_first)) {
+    // In place: the array object carries the adopter's comments.
+    assets.run_worker_first.splice(0, assets.run_worker_first.length, ...patterns);
+  } else {
+    assets.run_worker_first = [...patterns];
+  }
+  document.assets = assets;
+
+  await writeWranglerConfig(workerDir, document);
+  return {
+    before,
+    after: [...patterns],
+    notFoundHandling: assets.not_found_handling,
+    wroteNotFoundHandling,
+  };
+}
+
+/**
+ * Write the `dev` and `ui` blocks into a worker's `pithy.worker.jsonc`.
+ *
+ * `dev.command` is a full argv — the manifest has no package-manager concept — so the stub's
+ * package-manager-agnostic argv is resolved here through the adopter's `execArgs`: `bun x vite dev …`
+ * for a Bun project, `npx vite dev …` for an npm one. `{port}` stays a placeholder; `pithy dev`
+ * substitutes the feature's pinned port at spawn time, because ports are assigned at feature
+ * creation and never probed at startup.
+ *
+ * `ui.build` stays package-manager-agnostic: `pithy deploy` runs it through the same `execArgs` at
+ * build time, where it also knows the environment.
+ */
+export async function wireManifest(workerDir: string, stub: UiStub, packageManager: PackageManager): Promise<void> {
+  const document = await readManifestDocument(workerDir);
+
+  const dev: Record<string, unknown> = (document.dev as Record<string, unknown> | undefined) ?? {};
+  const [bin, ...rest] = stub.devCommand(DEV_PORT_TOKEN);
+  if (!bin) {
+    throw new InternalError({
+      message: `The ${stub.id} stub declares an empty dev command.`,
+      action: "This is a Pithy bug. Report it at https://github.com/pithy-sh/pithy/issues.",
+    });
+  }
+  const { command, args } = execArgs(packageManager, bin, rest);
+  dev.autostart = true;
+  dev.readySignal = stub.readySignal;
+  dev.command = [command, ...args];
+  document.dev = dev;
+
+  const ui: Record<string, unknown> = (document.ui as Record<string, unknown> | undefined) ?? {};
+  ui.stub = stub.id;
+  ui.build = [...stub.buildCommand];
+  document.ui = ui;
+
+  await writeManifestDocument(workerDir, document);
+}
+
+/**
+ * The one script value `pithy ui add` replaces. Pithy wrote it into every scaffolded worker, and
+ * serving the worker through Vite supersedes it — leaving it would hand the adopter a `bun run dev`
+ * that starts the API without the UI. Any other value is the adopter's and is kept.
+ */
+const REPLACEABLE_DEV_SCRIPT = "wrangler dev";
+
+/** A worker's `package.json`, in the shape this module merges into. */
+interface WorkerPackage {
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+/** Add every missing key from `incoming`; never touch one that is already there. */
+function mergeMissing(target: Record<string, string>, incoming: Record<string, string>): string[] {
+  const added: string[] = [];
+  for (const [key, value] of Object.entries(incoming)) {
+    if (key in target) continue;
+    target[key] = value;
+    added.push(key);
+  }
+  return added;
+}
+
+/**
+ * Drop every package there is no range to write for, so nothing unresolvable lands in a `package.json`.
+ *
+ * Two ways that happens, and both end in the same 404 on the adopter's *next* install — long after
+ * `pithy ui add` said Done.
+ *
+ * **The project already provides it.** A `@pithy-sh/*` package linked in from a checkout resolves from
+ * the project root either way, so omitting the line costs nothing and the build still finds it. Same
+ * predicate `pithy add` skips its install on ({@link alreadyProvided}).
+ *
+ * **There is no such version yet.** A stub declares a `null` range for a package the registry cannot
+ * serve at all — every `@pithy-sh/*` one, until the scope publishes. That case is the checkout case
+ * generalized: `alreadyProvided` only ever caught the adopter who linked one in, and a plain project
+ * kept the literal and broke. `kitRange` decides it once, for every producer, and stops deciding it the
+ * day the version is real.
+ */
+async function withoutProvided(
+  projectDir: string,
+  packages: Record<string, string | null>,
+): Promise<Record<string, string>> {
+  const kept: Record<string, string> = {};
+  for (const [name, range] of Object.entries(packages)) {
+    if (range === null) continue;
+    if (await alreadyProvided(projectDir, name)) continue;
+    kept[name] = range;
+  }
+  return kept;
+}
+
+/** What {@link wirePackage} added, for the command's report. */
+export interface PackageChange {
+  /** Dependency names newly added (an existing pin is never touched, so never downgraded). */
+  dependencies: string[];
+  /** Dev-dependency names newly added. */
+  devDependencies: string[];
+  /** Script names newly added or, for `dev`, superseded. */
+  scripts: string[];
+}
+
+/**
+ * Merge the stub's packages and scripts into `apps/<worker>/package.json`.
+ *
+ * **Merge, never replace.** Every existing key survives, which also means an existing pin is never
+ * downgraded: a dependency already declared keeps whatever version the adopter chose. The single
+ * exception is the `dev` script when it still holds Pithy's own scaffolded `wrangler dev` — see
+ * {@link REPLACEABLE_DEV_SCRIPT}.
+ *
+ * `projectDir` is the root, not the worker: it is where the packages resolve from, and a `@pithy-sh/*`
+ * one that already does gets no range written for it — see {@link withoutProvided}.
+ */
+export async function wirePackage(projectDir: string, workerDir: string, stub: UiStub): Promise<PackageChange> {
+  const path = join(workerDir, "package.json");
+  // One `try` used to wrap the read and the parse and answer both with *pithy worker add creates one*
+  // (#217). That command refuses on a worker that already exists, so a `package.json` holding a stray
+  // comma sent the adopter to a door that was already shut — and an `EACCES` sent them there too. Three
+  // failures, three answers: absence is the only one `pithy worker add` addresses, `readOptionalFile`
+  // owns the errno that is not absence, and the parse gets its own. `requireRecord` closes the fourth:
+  // `[]` parses, and the merge below would have hung `dependencies` off an array and written it back.
+  const raw = await readOptionalFile(path);
+  if (raw === null) {
+    throw new NotFoundError({
+      message: `No package.json in ${workerDir}.`,
+      action: "Every worker under apps/ needs a package.json. pithy worker add creates one.",
+    });
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new InternalError({
+      message: `${path} is not valid JSON.`,
+      action: "Fix that file's JSON, then run the command again.",
+      detail: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+  const pkg = requireRecord(path, parsed) as WorkerPackage;
+
+  pkg.dependencies ??= {};
+  pkg.devDependencies ??= {};
+  pkg.scripts ??= {};
+
+  const dependencies = mergeMissing(pkg.dependencies, await withoutProvided(projectDir, stub.dependencies));
+  const devDependencies = mergeMissing(pkg.devDependencies, await withoutProvided(projectDir, stub.devDependencies));
+
+  if (pkg.scripts.dev === REPLACEABLE_DEV_SCRIPT) delete pkg.scripts.dev;
+  const scripts = mergeMissing(pkg.scripts, stub.scripts);
+
+  await writeFileAtomic(path, `${JSON.stringify(pkg, null, 2)}\n`);
+  return { dependencies, devDependencies, scripts };
+}
+
+/** The project's root `tsconfig.json`, in the shape this module extends. */
+interface SolutionFile {
+  references?: { path: string }[];
+}
+
+/**
+ * Add the client's two programs to the project's root `tsconfig.json`, so `bun run typecheck` builds them.
+ *
+ * The client cannot join the Worker's program and must not: the Worker needs `@cloudflare/workers-types`
+ * and the client needs the DOM, and a program holding both makes `Uint8Array` structurally incompatible
+ * with `BufferSource` — which breaks every crypto call in the kit's control-plane signing code. So a
+ * scaffolded front end is two more *programs*, and a program nothing references is a program nothing
+ * checks. `pithy ui add` used to leave exactly that: two tsconfigs, unreferenced, silently unchecked.
+ *
+ * Appended in file order — the Worker's program, then its client's — because `tsc -b` reports in that
+ * order and reading a failure top-down should walk the project the way its layout does.
+ *
+ * **Extends, never creates.** A project scaffolded before the root solution file existed has Workers whose
+ * programs are not `composite`, and `tsc -b` refuses a reference to one of those outright. Writing the file
+ * would hand that adopter a `typecheck` that cannot pass; leaving it alone costs them only what they
+ * already had. Returns the paths added — empty when there is no solution file, or when a re-run finds both
+ * already there.
+ */
+export async function wireSolution(projectDir: string, worker: string): Promise<string[]> {
+  const path = join(projectDir, "tsconfig.json");
+  let document: SolutionFile;
+  try {
+    document = parse(await readFile(path, "utf8")) as unknown as SolutionFile;
+  } catch {
+    return []; // no solution file — this project predates it, and inventing one would break its typecheck
+  }
+
+  const references = Array.isArray(document.references) ? document.references : [];
+  const present = new Set(references.map((reference) => reference.path));
+  const added = [`./apps/${worker}/tsconfig.client.json`, `./apps/${worker}/tsconfig.node.json`].filter(
+    (reference) => !present.has(reference),
+  );
+  if (added.length === 0) return [];
+
+  // In place: the array object carries the adopter's comments, and comment-json hangs them off it.
+  references.push(...added.map((reference) => ({ path: reference })));
+  document.references = references;
+  await writeJsonc(path, document);
+  return added;
+}

package/src/ui/workerUi.ts

@@ -0,0 +1,172 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join } from "node:path";
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+import { parse } from "comment-json";
+import { z } from "zod";
+import { writeJsonc } from "../project/jsonc";
+import { readMergeBase } from "../project/readOptionalFile";
+import { WORKER_MANIFEST_FILE, type WorkerUi } from "../project/workerManifest";
+
+/**
+ * The `ui` block of `pithy.worker.jsonc` — the framework-stub contract as persisted.
+ *
+ * ```jsonc
+ * "ui": { "stub": "react", "build": ["vite", "build"] }
+ * ```
+ *
+ * `pithy deploy` reads `build` and runs it through the adopter's package manager before
+ * `wrangler deploy`; `pithy ui sync` reads `stub` to know which worker already has a front end. The
+ * block's presence **is** the "this worker has a UI" signal, which is why `pithy ui add` refuses on
+ * a worker that already carries one rather than half-overwriting a scaffold.
+ *
+ * Read here from the raw JSONC rather than through `parseWorkerManifest`: the Zod manifest strips
+ * what it does not declare, and this reader has to see the block whether or not the schema has caught
+ * up with it. Writes go back comment-preserving (comment-json), mutating in place — replacing an
+ * object or array would drop the adopter's notes, which live on it as symbol-keyed properties.
+ */
+
+/** A parsed `pithy.worker.jsonc`, loose — this module writes two known blocks and preserves the rest. */
+type ManifestDocument = Record<string, unknown> & {
+  dev?: Record<string, unknown>;
+  ui?: Record<string, unknown>;
+};
+
+/**
+ * What the type above claims, as a check rather than as a cast — the two blocks this module assigns
+ * into, and every other one of the adopter's kept untouched.
+ *
+ * `catchall` rather than a closed object for the same reason `dev.json`'s schema has one: a manifest holds
+ * bindings, routes, a name and whatever the schema has not caught up with, and a write here must round-trip
+ * all of it. What is declared is only what this module *dereferences* — `document.ui` is read as an object
+ * and `document.dev` is assigned as one.
+ */
+const ManifestBlocks = z
+  .object({
+    dev: z
+      .record(z.string().describe("A key of the dev block."), z.unknown().describe("Its value, whatever it is."))
+      .optional()
+      .describe("The `dev` block — `pithy dev`'s per-worker settings. An object when it is there at all."),
+    ui: z
+      .record(z.string().describe("A key of the ui block."), z.unknown().describe("Its value, whatever it is."))
+      .optional()
+      .describe("The `ui` block — the framework-stub contract. An object when it is there at all."),
+  })
+  .catchall(z.unknown().describe("Another block of the manifest, read and written back untouched."))
+  .describe("A `pithy.worker.jsonc` as this module reads it: two blocks it knows, and every other one kept.");
+
+/**
+ * The same document, **validated without being rebuilt** (#222).
+ *
+ * The check has to be a check and not a parse, because comment-json hangs the file's notes off the object
+ * it returns as symbol-keyed properties, and every Zod object schema constructs a *new* object from the
+ * keys it validated. Running {@link ManifestBlocks} as the merge base's schema directly would therefore
+ * pass every test about shape and silently drop every comment in the adopter's manifest at the next
+ * write — trading the cast this exists to remove for a quieter version of the same loss.
+ *
+ * So the schema validates by delegation and hands back the value it was given, issue paths and all, which
+ * is what lets a refusal name `ui` rather than "the top level".
+ */
+const ManifestDocument = z
+  .custom<ManifestDocument>()
+  .check((ctx) => {
+    const checked = ManifestBlocks.safeParse(ctx.value);
+    if (checked.success) return;
+    // The key path travels and the message travels; the value never does. `readMergeBase` reports where a
+    // document broke by key path alone, and this is the schema that has to keep that true.
+    for (const issue of checked.error.issues) {
+      ctx.issues.push({ code: "custom", path: issue.path, message: issue.message, input: ctx.value });
+    }
+  })
+  .describe("A `pithy.worker.jsonc` document, checked against its shape and handed back exactly as parsed.");
+
+/**
+ * Parse `<dir>/pithy.worker.jsonc` comment-preserving, or an empty document when the file is **absent**.
+ *
+ * Absent means `ENOENT` and nothing else — the decision is {@link readOptionalFile}'s, and the words are
+ * this file's. A read that answered `{}` for every failure was #142 with a different file name: the caller
+ * merges its two blocks into that empty base and {@link writeManifestDocument} renames the result over a
+ * file whose every other block the process never saw. Committed rather than gitignored, so the loss is
+ * recoverable from git — but only by someone who notices before committing over it.
+ *
+ * **Three ways in, and `{}` is the answer to exactly one of them.** The file is not there; the file is
+ * there and will not open; the file opened and is not a document. The third was the last path left from
+ * "the read succeeded" to "start from an empty base" (#204) — `typeof null === "object"` let `null`
+ * through, and an array passed the same check and then lost every key `stringify` drops off it. Such a
+ * file is malformed either way, which changes what the loss costs, not whether it is the same defect.
+ *
+ * The tag check that decides the third was written here and is `requireRecord`'s now (#209): the two
+ * credential files reached the same conclusion independently, which is the count at which a rule stops
+ * belonging to the call site.
+ *
+ * **And there was a fourth, which a cast made invisible (#222).** The read refused on all three above and
+ * then asserted the survivor was a {@link ManifestDocument} — a type claiming `dev` and `ui` are objects —
+ * so a manifest whose `ui` is the string `"react"` reached the merge as if it were valid. `readMergeBase`
+ * is the whole sentence and this was the one reader in the family not asking it, so it asks it now: the
+ * cast is a schema, the four refusals are its four, and the JSONC parser comes in through the seam that
+ * exists for it. The words below are still this file's — a `pithy.worker.jsonc` names a manifest object,
+ * not a document — and only the decisions moved.
+ */
+export async function readManifestDocument(workerDir: string): Promise<ManifestDocument> {
+  const path = join(workerDir, WORKER_MANIFEST_FILE);
+  const base = await readMergeBase(path, ManifestDocument, {
+    // Comment-preserving, because {@link writeManifestDocument} hands this straight back to the printer.
+    parse: (source) => parse(source),
+    unreadable: ({ code, cause }) =>
+      new ConflictError(
+        {
+          message: `Cannot update ${path}: Pithy could not read what is already in it.`,
+          action: "Fix the file's permissions, or move it aside, and run the command again.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+    unparseable: () =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is there and is not valid JSONC.`,
+        action: "Fix the syntax, or move it aside, and run the command again.",
+        // Never the parser's own message: comment-json quotes the line it choked on, and this rewrite
+        // renames a whole document over the adopter's file. The path and "it did not parse" is the whole
+        // of what fixes it (#219).
+        detail: `${WORKER_MANIFEST_FILE} in ${workerDir} did not parse, and Pithy will not rewrite a manifest it could not read back`,
+      }),
+    notARecord: ({ found }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it holds ${found}, not a manifest object.`,
+        action: "Restore it to a JSONC object, or move it aside, and run the command again.",
+        detail: `${WORKER_MANIFEST_FILE} in ${workerDir} parsed to ${found}`,
+      }),
+    invalid: ({ at }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is not the manifest Pithy keeps there.`,
+        action: "Fix it, or move it aside, and run the command again.",
+        // The key path, so the block can be found. Never what was on it.
+        detail: `${WORKER_MANIFEST_FILE} in ${workerDir} failed its schema at ${at}`,
+      }),
+  });
+  return base.document;
+}
+
+/** Write the document back, printed the way the Biome `pithy init` scaffolds would print it (#249). */
+export async function writeManifestDocument(workerDir: string, document: ManifestDocument): Promise<void> {
+  await writeJsonc(join(workerDir, WORKER_MANIFEST_FILE), document);
+}
+
+/** The `ui` block on a parsed document, or `null` when the worker has no front end. */
+export function uiBlock(document: ManifestDocument): WorkerUi | null {
+  const block = document.ui;
+  if (typeof block !== "object" || block === null) return null;
+  const stub = (block as { stub?: unknown }).stub;
+  const build = (block as { build?: unknown }).build;
+  if (typeof stub !== "string") return null;
+  return {
+    stub,
+    build: Array.isArray(build) ? build.filter((entry): entry is string => typeof entry === "string") : [],
+  };
+}
+
+/** The `ui` block for a worker directory, or `null`. The "does this worker already have a UI?" check. */
+export async function readWorkerUi(workerDir: string): Promise<WorkerUi | null> {
+  return uiBlock(await readManifestDocument(workerDir));
+}

package/templates/starter/.dev.secrets.example.jsonc

@@ -0,0 +1,43 @@
+// Documentation. Nothing copies this file anywhere — `pithy add <capability>` writes the real one.
+//
+// Your dev secrets do not live in this repository. They live at
+//   <config>/<project>/secrets.jsonc
+// where <config> is $PITHY_CONFIG_DIR, else %APPDATA%\pithy, $XDG_CONFIG_HOME/pithy, or
+// ~/.config/pithy. `pithy doctor` prints the exact path every run — that is how you find it.
+//
+// Outside the checkout on purpose: nothing about a secret can then reach a commit, a tarball, or an
+// `rm -rf` on the working copy, and every worktree of one project reads the same values.
+//
+// Two files, two namespaces, and the split is the point:
+//   .dev.vars      — wrangler env bindings. UPPER_SNAKE. In the worker's directory, because wrangler
+//                    reads it there. Still in the repo, still gitignored.
+//   secrets.jsonc  — secrets. <capability>-<what>, the payload each one's destination receives.
+//                    Outside the repo.
+//
+// The key is the registry secret name, verbatim. Nothing here names a destination: the registry
+// already knows each secret's backend, so `pithy seed` sends a `d1` secret to the local SECRETS
+// database and a `cf-secrets-store` one to .dev.vars, and the two can never disagree.
+//
+// A secret's value here is the precise payload its destination receives. Nothing wraps it, nothing
+// unwraps it, and no secret is an exception.
+//
+// For every ordinary secret that payload is a full { currentVersion, versions } envelope, even a
+// single-version one — which is what makes the format unambiguous, because a JSON secret's own
+// object sits inside `versions` where it can never be mistaken for the envelope around it, and it is
+// the shape the store actually holds. SECRETS_ENCRYPTION_KEYS is the one secret whose binding is read
+// before any envelope decoder exists, so its binding carries the value and this file states the value.
+// The registry says which is which; you never have to guess.
+//
+// Generated secrets are not hand-written. Anything a value can honestly be invented for — a session
+// key, a link-signing key — is minted here on `pithy add` and left alone afterwards. What you write
+// by hand is what a third party issued you.
+{
+  // "auth-session-secret": {
+  //   "currentVersion": "1",
+  //   "versions": { "1": "..." }
+  // },
+  // "auth-google-credentials": {
+  //   "currentVersion": "1",
+  //   "versions": { "1": { "clientId": "...", "clientSecret": "..." } }
+  // }
+}

package/templates/starter/.dev.vars.example

@@ -0,0 +1,30 @@
+# This file is documentation. Two different `.dev.vars` exist, and they have different owners.
+#
+#   <root>/.dev.vars            yours. The CLI's own Cloudflare credentials, below. Copy this to it.
+#   <root>/apps/<worker>/.dev.vars   generated. pithy writes it; wrangler reads it. Do not edit one.
+#
+# One-time setup:
+#   1. Run `wrangler login` — OAuth, used by `wrangler dev` and `wrangler deploy`.
+#   2. Set the bootstrap Cloudflare API token below. pithy uses it to call the
+#      Cloudflare REST API and to mint scoped, account-owned tokens from there.
+# CLOUDFLARE_ACCOUNT_ID=your-account-id
+# CLOUDFLARE_API_TOKEN=your-bootstrap-token
+#
+# A Worker's `.dev.vars` is generated on every `pithy dev` and `pithy seed`, from the dev secrets file
+# and this machine's `dev.json`. Run `pithy doctor` to see where those are. An edit to a generated file
+# is lost on the next run, and a file pithy did not write is never overwritten — it refuses and says so.
+#
+# To override a value locally, use `.dev.vars.local` — git-ignored, hand-authored, merged last:
+#
+#   <root>/.dev.vars.local            every worker
+#   <root>/apps/<worker>/.dev.vars.local   that worker, and wins
+#
+# It is for overrides, not for variables. A value that should exist in production belongs in
+# `wrangler.jsonc`'s `vars` — committed, reviewed, deployed. A variable that lives only in a `.local`
+# file works in dev and is simply absent in production, and that failure lands at deploy. `pithy doctor`
+# names any such key.
+#
+# Application secrets live in neither. `pithy add <capability>` puts them in the dev secrets file,
+# outside this repository. The registry's `backend` decides: a `d1` secret is read from the secrets
+# store in every environment, dev included. A `cf-secrets-store` secret has no local store to read, so
+# pithy puts its value in the generated file for you.

package/templates/starter/apps/api/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pithy-app-api",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "deploy:prod": "wrangler deploy --env prod"
+  },
+  "dependencies": {
+    "@pithy-sh/core": "^0.0.0",
+    "hono": "^4.13.2"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "wrangler": "^4.123.0"
+  }
+}

package/templates/starter/apps/api/pithy.config.ts

@@ -0,0 +1,65 @@
+// apps/api/pithy.config.ts — what THIS Worker is made of.
+//
+// Every Worker under apps/ has its own config. Capabilities are per-Worker
+// because everything they drive is per-Worker: the composed route tree, the
+// bindings written into this Worker's wrangler.jsonc, and Durable Object class
+// migrations (which register a class against a specific script).
+//
+// Two Workers share a resource by declaring the SAME binding name — feature
+// resource names are derived from the binding, not the Worker — so two Workers
+// that both declare `DB` are backed by one D1. A Worker that wants its own
+// declares a different binding (e.g. COLLAB_DB).
+
+import { defineCapability } from "@pithy-sh/core/src/capability/capability";
+import { compositionEnvironment } from "@pithy-sh/core/src/env/ambient";
+import { originFor } from "@pithy-sh/core/src/naming/domains";
+
+// Where this Worker answers, per environment. Declare it once here and the
+// `routes` entry and `vars.BASE_URL` in wrangler.jsonc are generated from it —
+// `pithy init` and `pithy worker add` fill this in when you name a domain.
+// `dev` is absent on purpose: local runs on the port your feature pinned.
+const DOMAINS = {
+  // staging: { pattern: "staging.api.example.com", zone: "example.com" },
+  // prod: { pattern: "api.example.com", zone: "example.com" },
+};
+
+// This Worker's public origin, for the environment it is composing in. Hand it
+// to every capability that needs one — auth's callbacks, email's links, a
+// payment's return URL — so no origin is ever written down.
+//
+// An origin written down is production's origin written into staging, and that
+// is not a typo you notice: it is staging mailing your testers magic links into
+// production, and an unsubscribe from a staging test unsubscribing them there.
+// An environment DOMAINS does not name resolves to the local origin, so a link
+// built in the wrong place goes nowhere rather than somewhere real.
+//
+// Exported so your own code can build a link against the same origin.
+export const PUBLIC_ORIGIN = originFor(compositionEnvironment(), DOMAINS);
+
+// Your app is a capability like any other: routes, middleware, databases, KV
+// namespaces, and the bindings they need. It composes last, after every
+// library capability.
+const app = defineCapability({
+  // The app's capability name. Also its migration namespace once it has tables.
+  name: "app",
+  // Bindings your own routes need beyond what capabilities declare. Validated
+  // on the first request — a missing binding fails fast with the binding's name.
+  requiredBindings: [],
+  // Mount your routes here. Every route declares how callers are verified —
+  // bearer, session, signed-webhook, or public. `GET /health` is built in.
+  // routes: (a) => {
+  //   a.get("/hello", (c) => c.text("Hi."));
+  // },
+});
+
+const config = {
+  domains: DOMAINS,
+  // Library capabilities this Worker composes, in order.
+  // `pithy add <capability> --worker api` registers them here.
+  capabilities: [
+    // pithy:capabilities (managed region — do not remove this marker)
+  ],
+  app,
+};
+
+export default config;

package/templates/starter/apps/api/pithy.worker.jsonc

@@ -0,0 +1,11 @@
+{
+  // How `pithy dev` runs this Worker locally. This file is yours; wrangler.jsonc stays wrangler's.
+  "dev": {
+    // Must this run for the local environment to function? pithy dev starts exactly the autostart workers.
+    "autostart": true,
+    // Regex marking "ready" in this Worker's output.
+    "readySignal": "Ready on https?://"
+    // "preferredPort": 8787   // a hint only — the feature's reserved port block is authoritative.
+    // "command": ["bun", "run", "dev"]   // set this for a non-Worker process (e.g. a Vite frontend).
+  }
+}