@pithy-sh/cli 0.1.0

package/templates/starter/apps/api/src/bindings.workers.test.ts

@@ -0,0 +1,18 @@
+import { env } from "cloudflare:test";
+import { expect, test } from "vitest";
+
+// The one test the scaffold ships, and it exists to prove the wiring rather than the code: a
+// `*.workers.test.ts` file runs inside workerd with real bindings. Delete it once your own tests do.
+//
+// This is the kit's whole testing argument. A test that mocks D1 proves the mock works; a test against
+// the real thing catches the SQL, the codec, and the binding name.
+
+test("the Workers test project hands out a real D1 database", async () => {
+  const { results } = await env.DB.prepare("select 1 as one").all<{ one: number }>();
+  expect(results).toEqual([{ one: 1 }]);
+});
+
+test("and a real KV namespace", async () => {
+  await env.SESSIONS.put("hello", "there");
+  expect(await env.SESSIONS.get("hello")).toBe("there");
+});

package/templates/starter/apps/api/src/cloudflare-test.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// What `*.workers.test.ts` gets from `cloudflare:test`, matching the bindings the root
+// vitest.workers.config.ts declares. Add a binding in both places or the test sees `undefined` typed
+// as something real — the one shape of test failure that looks like a bug in your code.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+    SESSIONS: KVNamespace;
+  }
+}

package/templates/starter/apps/api/src/index.ts

@@ -0,0 +1,8 @@
+import { createEntrypoint } from "@pithy-sh/core/src/createEntrypoint";
+import config from "../pithy.config";
+
+// The Worker. createEntrypoint assembles the capabilities in pithy.config.ts into
+// a Worker entrypoint: `fetch` is one Hono app (typed db/kv registries on every
+// request, fail-fast binding validation, GET /health), and `email` fans inbound
+// mail to every capability that handles it (e.g. @pithy-sh/email's bounce handler).
+export default createEntrypoint(config);

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

@@ -0,0 +1,26 @@
+{
+  // Matches the Pithy toolchain defaults: strict, ESM-only, TS-7 ready.
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": ["@cloudflare/workers-types"],
+    // Referenced from the root solution file, which requires `composite` — and `composite` makes tsc
+    // write build state. It goes under the PROJECT's `dist/`, already gitignored, and deliberately not
+    // under this Worker's: once this Worker carries a UI, Vite owns `apps/<worker>/dist` and empties it
+    // on every build, which would throw the incremental state away each time.
+    "composite": true,
+    "tsBuildInfoFile": "../../dist/api.server.tsbuildinfo",
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "pithy.config.ts"]
+}

package/templates/starter/apps/api/wrangler.jsonc

@@ -0,0 +1,68 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "pithy-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-06-01",
+  "compatibility_flags": ["nodejs_compat"],
+
+  // Workers Logs, on by default. Every `c.var.log` record is a structured, per-line entry you can
+  // query in the dashboard — no setup. `head_sampling_rate` keeps 100% of records; lower it (0-1) to
+  // sample under heavy traffic. To fan records to a tail-consumer or Logpush, add `tail_consumers`
+  // here and attach a transport to the logger (see docs/LOGGING.md).
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1
+  },
+
+  // The deployed version of this Worker, injected by Cloudflare. Top level, so every environment
+  // inherits it — this is metadata about the build, not a per-environment setting.
+  // It answers the first question anyone asks when a deploy goes wrong: which build produced this?
+  // The id reaches five places from here — the `version` field on every log record, the
+  // control-plane manifest, a header on every control-plane response, every audit event, and the
+  // check `pithy deploy` runs to prove the Worker it just shipped is the one answering at your
+  // domain. `CF_VERSION_METADATA` is the name the code reads; renaming it binds something nothing
+  // consumes.
+  "version_metadata": { "binding": "CF_VERSION_METADATA" },
+
+  // The top level is the dev environment — what `wrangler dev` runs locally.
+  // `pithy add <capability>` appends the bindings a capability needs, per environment.
+  // `ENVIRONMENT` names this environment — the one signal that decides dev vs deployed,
+  // and the value log records carry as their `env` correlation field.
+  // `PROJECT` names the owning project (the root pithy.config.ts `name`). Cloudflare Images and
+  // Stream are account-flat and key an asset by an id they mint, so this var is the only thing
+  // that says which project owns an upload this Worker makes.
+  // `WORKER` names this Worker — its apps/<name> directory. The runtime tells a script nothing
+  // about itself, and two Workers that declare the same binding share one database, so this is
+  // what separates their audit events. Every environment repeats all three:
+  // `env.<name>.vars` REPLACES this block rather than merging it.
+  "vars": {
+    "ENVIRONMENT": "dev",
+    "PROJECT": "pithy-app",
+    "WORKER": "api"
+  },
+  "d1_databases": [],
+  "kv_namespaces": [],
+
+  // Staging serves test users; production serves paid users. Deployed names get the
+  // environment suffix automatically (pithy-app-staging, pithy-app-prod).
+  "env": {
+    "staging": {
+      "vars": {
+        "ENVIRONMENT": "staging",
+        "PROJECT": "pithy-app",
+        "WORKER": "api"
+      },
+      "d1_databases": [],
+      "kv_namespaces": []
+    },
+    "prod": {
+      "vars": {
+        "ENVIRONMENT": "prod",
+        "PROJECT": "pithy-app",
+        "WORKER": "api"
+      },
+      "d1_databases": [],
+      "kv_namespaces": []
+    }
+  }
+}

package/templates/starter/biome.template.jsonc

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.8/schema.json",
+  // Biome for both lint and format — one tool, one pass, no ESLint/Prettier pair to keep in step.
+  // `bun run lint` reports; `bun run format` writes.
+  //
+  // No `vcs` block on purpose. Reading .gitignore needs a repository, and `pithy init` scaffolds into
+  // directories that are not one yet — the ignores are stated here instead, so the first `bun run lint`
+  // works before the first `git init`.
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!**/dist", "!**/.wrangler", "!**/.worktrees"]
+  },
+  // The logging gate. Scoped to each Worker's own `.ts` source, because that is the code that runs in
+  // the Worker, where `c.var.log` and `createWorkerLogger()` exist. A `.tsx` file is the client, and a
+  // browser console is not a Workers log. A test printing to a terminal is output for a human, not a
+  // log line, so tests are out too.
+  //
+  // `no-process-io.grit` is the same rule for `process.stdout` / `process.stderr` — the Node habit that
+  // reaches for a stream instead of a logger. Same scope, and for the same reason: it is the Worker's
+  // source that must stay queryable. A build script or a Node CLI of your own writing to stdout is
+  // correct, and neither lives under `apps/*/src`.
+  //
+  // Yours to change, like every other line here — narrow them, widen them, or drop an entry and delete
+  // its plugin file with it. Both plugin files say the same.
+  "plugins": [
+    {
+      "path": "plugins/no-console.grit",
+      "includes": ["**/apps/*/src/**/*.ts", "!**/*.test.ts"]
+    },
+    {
+      "path": "plugins/no-process-io.grit",
+      "includes": ["**/apps/*/src/**/*.ts", "!**/*.test.ts"]
+    }
+  ],
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120,
+    "lineEnding": "lf"
+    // Nothing is exempt. `wrangler.jsonc` and `pithy.worker.jsonc` were, because the writer behind
+    // `pithy add` and `pithy ui sync` put every array element on its own line and Biome collapses the
+    // short ones — so the CLI's own output failed the commit hook the CLI scaffolds (#249). Exempting
+    // the two files Pithy touches most from the formatter is not a fix; the writer prints what Biome
+    // would print now, and these are ordinary files again.
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": { "level": "on" }
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": { "preset": "recommended" }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "trailingCommas": "all"
+    }
+  },
+  "json": {
+    // Every config Pithy writes is JSONC — wrangler.jsonc, pithy.worker.jsonc, and the tsconfigs.
+    "parser": {
+      "allowComments": true,
+      "allowTrailingCommas": false
+    },
+    "formatter": {
+      "trailingCommas": "none"
+    }
+  }
+}

package/templates/starter/gitignore

@@ -0,0 +1,37 @@
+# deps & build
+node_modules/
+dist/
+
+# cloudflare / wrangler
+.wrangler/
+.dev.vars
+.dev.vars.*
+!.dev.vars.example
+
+# pithy local dev state
+.dev-state.json
+# Legacy: the port registry lives at <config>/dev-ports.json now (#435). Kept so a project scaffolded
+# before the move keeps ignoring the file it already has.
+.dev-ports.json
+logs/
+
+# pithy feature worktrees + per-feature state
+.worktrees/
+.dev.config.json
+.pithy-feature.json
+
+# env & secrets
+# No dev secrets line. They live at <config>/<project>/secrets.jsonc, outside every checkout, so there
+# is nothing here to ignore — and `.dev.secrets.example.jsonc` is committed documentation. See #156.
+.env
+.env.*
+!.env.example
+
+# atomic-write temp siblings (.dev.vars.<rand>.tmp, …). A write interrupted by SIGINT leaves one
+# holding the full plaintext; it must never be committable.
+*.tmp
+
+# editor / os
+.DS_Store
+*.log
+coverage/

package/templates/starter/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "pithy-app",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "workspaces": [
+    "apps/*"
+  ],
+  "scripts": {
+    "dev": "pithy dev",
+    "deploy": "pithy deploy",
+    "deploy:staging": "pithy deploy --env staging",
+    "deploy:prod": "pithy deploy --env prod",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@types/node": "^22.15.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0"
+  }
+}

package/templates/starter/pithy.config.ts

@@ -0,0 +1,67 @@
+// pithy.config.ts — your project's identity and policy.
+//
+// This file is project-wide. It deliberately does NOT list capabilities: what a
+// Worker is made of is per-Worker, and lives in apps/<name>/pithy.config.ts.
+// Only settings that cannot be per-Worker belong here.
+
+const config = {
+  // The project name, and the first segment of every name Pithy provisions:
+  // <project>-<env>-<thing>, kebab-case, one rule for every namespace — D1, KV,
+  // R2, Worker scripts, Workflows, Secrets Store entries, and Cloudflare API
+  // tokens. A thing shared across environments puts the literal `global` in the
+  // environment slot. Feature resources extend the same shape
+  // (<project>-f<issue>-<slug>-<binding>-<kind>).
+  //
+  // Cloudflare's namespaces are flat and account-wide, so this segment is the
+  // only thing keeping two projects in one account from adopting each other's
+  // resources — and it is the only key teardown has to find them by. Renaming it
+  // does not rename anything already provisioned: it orphans it, silently. Set it
+  // once, keep it stable across machines and checkouts, and don't rename it.
+  // `pithy doctor` checks that it still matches what your workers declare.
+  name: "pithy-app",
+
+  // Every environment this project deploys to, in the order provisioning walks
+  // them — least-production first. It is the SECOND segment of every Cloudflare
+  // name the project composes (<project>-<env>-<thing>), the set `pithy secrets
+  // provision` gives a master key and a manager to, and the set each Worker's
+  // `env.<name>` wrangler stanzas are generated from. `dev` is never listed: it
+  // is local, it is the top-level wrangler stanza, and it always exists.
+  //
+  // Absent means ["staging", "prod"], which is what `pithy init` scaffolds
+  // unless you told it otherwise. Like `name`, this is effectively permanent:
+  // renaming an environment does not rename anything already provisioned under
+  // the old name — it orphans it. `pithy doctor` reports a change rather than
+  // applying one.
+  // environments: ["staging", "prod"],
+
+  // Which Cloudflare account this project belongs to. `pithy init` writes this
+  // block when it can discover the account from your token.
+  //
+  // `accountName` selects the credentials file: <config>/cloudflare.<name>.json
+  // rather than <config>/cloudflare.json. One machine, several companies, one
+  // file each — without it every project on the machine reads the same file, so
+  // switching accounts means editing that file in place and every project
+  // silently follows. A bare token: lowercase, digits, single hyphens. It
+  // becomes a file name, so nothing else is accepted.
+  //
+  // `accountId` pins the account those credentials must belong to. Every command
+  // that resolves them compares the two and refuses on a mismatch, naming both.
+  // The nickname above means whatever each machine says it means; this is what
+  // makes the repository the authority. An account id is an identifier, not a
+  // secret — wrangler.toml commits them — so it is safe here, including in a
+  // public repository. Optional, and it earns its keep the moment more than one
+  // person deploys.
+  // cloudflare: { accountName: "acme", accountId: "" },
+
+  // Overrides for the predefined Cloudflare API token profiles (`pithy token`).
+  // Account-level, so it lives here rather than on a Worker.
+  // tokens: { overrides: {} },
+
+  // `pithy seed` policy. `productionEnvironments` names every environment this
+  // project treats as production, beyond the built-in production/prod — each one
+  // requires the type-to-confirm phrase, not just --yes. A safety rule no single
+  // Worker should be able to quietly omit.
+  // seed: { includeExamples: false, productionEnvironments: ["live"] },
+};
+
+export default config;

package/templates/starter/plugins/no-console.grit

@@ -0,0 +1,25 @@
+// Your project's logging gate. Scoped by biome.jsonc to each Worker's own `.ts` source.
+//
+// A console line carries no level, no logger name, and no request id. Workers Logs cannot filter it,
+// and nothing downstream can key on it — so it is output you can read once, live, and never again.
+// The replacement is already wired: `c.var.log` inside a request handler, bound to that request, and
+// `createWorkerLogger()` anywhere else in the Worker.
+//
+// Biome ships `suspicious/noConsole` and it matches the same code. This exists instead because its
+// message names the replacement — a rule that only prohibits gets ignored by the next person who
+// needs a line of output, since it never told them where the line was supposed to go.
+//
+// This file is yours. Narrow the `includes` in biome.jsonc, widen them, or delete both the entry and
+// this file. Pithy ships the practice; the code is yours.
+//
+// The match is the member access rather than the call, so `items.forEach(console.log)` and
+// `const sink = console.error` are caught alongside `console.log(x)`. A call contains the member
+// access, so each site still reports exactly once.
+language js
+
+or {
+  `console.$method`,
+  `globalThis.console.$method`
+} as $ref where {
+  register_diagnostic(span=$ref, message="console is not the logger. Reach for c.var.log in a request, or createWorkerLogger() elsewhere — a console line carries no level, name, or request id, and Workers Logs cannot filter it.")
+}

package/templates/starter/plugins/no-process-io.grit

@@ -0,0 +1,25 @@
+// The sibling of no-console.grit, for the other way a line of output gets written by hand.
+//
+// `process.stdout.write` and `process.stderr.write` are Node habits. Your Worker enables
+// `nodejs_compat`, so they resolve rather than throwing — and what they write is an unstructured line
+// with no level, no logger name, and no request id, which Workers Logs cannot filter. Same hole as
+// `console.log`, with the extra catch that it only works at all because of a compatibility flag.
+//
+// `c.var.log` inside a request handler, `createWorkerLogger()` anywhere else in the Worker.
+//
+// Scoped to `apps/*/src/**/*.ts` — your Worker code. If you add a build script or a Node CLI of your
+// own, writing to stdout there is correct and this gate should not reach it; that is why the scope is
+// the Worker's source and not the whole project.
+//
+// This file is yours. Narrow it, widen it, or delete the entry in biome.jsonc and this file with it.
+//
+// The match is the member access rather than the call, so a method handed off as a callback is caught
+// alongside a direct call. A call contains the member access, so each site reports exactly once.
+language js
+
+or {
+  `process.stdout.$method`,
+  `process.stderr.$method`
+} as $ref where {
+  register_diagnostic(span=$ref, message="A Worker log must be queryable. process.stdout writes an unstructured line with no level, name, or request id, and Workers Logs cannot filter it. Reach for c.var.log in a request, or createWorkerLogger() elsewhere.")
+}

package/templates/starter/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  // The SOLUTION file. It compiles nothing of its own — `"files": []` — and names the programs that do.
+  // `bun run typecheck` is `tsc -b`, which builds every reference below, in order.
+  //
+  // Why several programs rather than one: a Worker needs `@cloudflare/workers-types`, a browser client
+  // needs the DOM, and TypeScript cannot hold both in one program. Load both and `Uint8Array` stops being
+  // assignable to `BufferSource`, which breaks every crypto call in the kit's control-plane signing code.
+  // Keeping them apart by construction is what this file is for.
+  //
+  // `pithy ui add` appends that Worker's client programs here. `pithy worker add` does not yet — add the
+  // new Worker's `tsconfig.json` yourself, or its source is typechecked by nothing.
+  "files": [],
+  "references": [{ "path": "./tsconfig.tools.json" }, { "path": "./apps/api/tsconfig.json" }]
+}

package/templates/starter/tsconfig.tools.json

@@ -0,0 +1,30 @@
+{
+  // The TOOLING program: the files that configure the project rather than run in it. They execute on
+  // Node, not in a Worker and not in a browser, so they get their own program and `types: ["node"]`.
+  //
+  // Left out of the solution, these were config files nothing checked — which is how a Vitest config
+  // that names a project no longer present, or a `pithy.config.ts` with a typo in a key, survives until
+  // the command that reads it fails.
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    // `composite` is what a referenced project must declare, and it makes tsc write build state.
+    // Under `dist/`, which .gitignore already covers — and the project root's `dist/`, never a
+    // Worker's: Vite empties a Worker's on every client build, taking the incremental state with it.
+    "composite": true,
+    "tsBuildInfoFile": "dist/tools.tsbuildinfo",
+    "noEmit": true
+  },
+  "include": ["pithy.config.ts", "vitest.config.ts", "vitest.workers.config.ts"]
+}

package/templates/starter/vitest.config.ts

@@ -0,0 +1,124 @@
+import { existsSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vitest/config";
+
+/** This file sits at the project root, and every path below is resolved from it rather than from a cwd. */
+const PROJECT_ROOT = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The directory `name` resolves to when a Worker asks for it, or `null` when it resolves nowhere.
+ *
+ * Node's own resolution, walking outward from the Worker: `apps/<worker>/node_modules` first, then the
+ * project root's, then whatever is above that. Deliberately not a fixed path — Bun installs a workspace
+ * member's dependencies beside that member, npm and pnpm hoist most of them to the root, and both
+ * answers are correct. Asking the resolver means this file needs no opinion about which you use.
+ *
+ * `<name>/package.json` rather than the bare name, because the bare name answers with an entry file
+ * that differs per export condition, and what an alias replacement needs is the package's directory.
+ */
+function packageDir(from: string, name: string): string | null {
+  try {
+    return dirname(createRequire(join(from, "package.json")).resolve(`${name}/package.json`));
+  } catch {
+    // Nothing there. A project with no front end has no React at all, which is not an error here.
+    return null;
+  }
+}
+
+/**
+ * One React, however many checkouts the packages live in.
+ *
+ * Vite resolves a symlinked package from its realpath, so a package linked in from somewhere else — the
+ * Pithy kit, a design system, any workspace you point at by path — imports `react` out of *its* tree
+ * rather than out of this project's. Two copies of React is `invalid hook call` in every component that
+ * package renders, and the stack blames the component rather than the resolution. It stays invisible for
+ * as long as no linked component is mounted, which in a project that owns its own screens is a long
+ * time: the first one you ever mount is the one that fails.
+ *
+ * **An alias and not `dedupe`, and the reason is where React lives.** `dedupe` resolves the names it is
+ * given from Vite's root, and this config's root is the project root, where React is not installed — it
+ * is a dependency of `apps/<worker>`. So `dedupe` here finds nothing and changes nothing, without a
+ * word. `apps/<worker>/vite.config.ts` is rooted at the Worker and uses `dedupe` for that reason; this
+ * file cannot, and a `dedupe` line added here would read as covered while resolving nothing.
+ *
+ * **Two rules per package, an exact one and a prefixed one.** The exact rule answers `react`; the
+ * prefixed one answers the subpaths — `react/jsx-runtime`, `react-dom/client`. A single `^react` rule
+ * would answer `react-dom` too and rewrite it through React's own directory, which lands on a path that
+ * exists only while the two packages happen to sit side by side under one `node_modules`.
+ *
+ * **No Worker is named here, because none of them is the project's.** The first `apps/*` that resolves
+ * React is the copy every test gets. A name written into this file would be one more place your Worker's
+ * name lives, and it would go stale the day you rename it or `pithy worker add` a second one.
+ *
+ * **An empty list is a legitimate answer, and it says nothing.** No `apps/*` resolves React in a project
+ * with no front end, which is every project between `pithy init` and its first `pithy ui add`. Throwing
+ * would fail `bun run test` on a fresh scaffold; warning would print on every run of a project that
+ * simply has no client. What separates this from the `dedupe` line it replaces is therefore not noise,
+ * it is reach: an alias list is a value, so an empty one is visible to anything that cares to look — the
+ * kit's own gates plant a Worker with no React and require the loop to skip past it.
+ *
+ * It is not a workaround for a symlink. It is what every linked-package setup needs, it costs nothing
+ * when nothing is linked, and it goes on costing nothing the day `@pithy-sh/*` is published.
+ */
+function oneReact(): { find: RegExp; replacement: string }[] {
+  const apps = join(PROJECT_ROOT, "apps");
+  if (!existsSync(apps)) return [];
+  // Sorted, so a project with two front ends resolves the same React on every machine.
+  const workers = readdirSync(apps, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+  for (const worker of workers) {
+    const react = packageDir(join(apps, worker), "react");
+    const reactDom = packageDir(join(apps, worker), "react-dom");
+    if (react === null || reactDom === null) continue;
+    return [
+      { find: /^react-dom$/, replacement: reactDom },
+      { find: /^react-dom\//, replacement: `${reactDom}/` },
+      { find: /^react$/, replacement: react },
+      { find: /^react\//, replacement: `${react}/` },
+    ];
+  }
+  return [];
+}
+
+const ONE_REACT = oneReact();
+
+// Two projects, split by runtime, because a Pithy project has two runtimes.
+//
+// `node` runs plain unit tests in Node — codecs, pure logic, anything with no binding in it.
+// `workers` runs against the real Workers runtime with real D1 and KV, in vitest.workers.config.ts.
+// A test that touches a binding belongs there and nowhere else: mocking D1 proves your mock works.
+//
+// The split is by filename, not by directory: `*.workers.test.ts` is the Workers project, every other
+// `*.test.ts` is the node one. Tests sit beside the code they cover, so a folder rule would mean
+// choosing between co-location and the runtime — and the runtime is not negotiable.
+//
+// `.tsx` is in the include for the same reason. A front end scaffolded by `pithy ui add` is all `.tsx`,
+// so a `.ts`-only pattern silently collected none of its tests — and `passWithNoTests` made that green
+// (#245). Every co-located test runs, whatever the file's extension.
+export default defineConfig({
+  test: {
+    // A scaffolded project starts with almost no tests. `bun run test` should still be green.
+    passWithNoTests: true,
+    projects: [
+      {
+        // See `oneReact` at the head of this file. On the project rather than beside `passWithNoTests`,
+        // and that is measured rather than assumed: on vitest 4.1.10 a `resolve.alias` stated at the
+        // root of a `projects` config does not reach an inline project, and one stated here does. Up
+        // there it would read as covered and rewrite nothing. This is also the project that collects
+        // the `.tsx` tests a front end brings, so this is where it has to be either way.
+        resolve: { alias: ONE_REACT },
+        test: {
+          name: "node",
+          environment: "node",
+          include: ["apps/*/src/**/*.test.{ts,tsx}"],
+          exclude: ["apps/*/src/**/*.workers.test.{ts,tsx}"],
+        },
+      },
+      "./vitest.workers.config.ts",
+    ],
+  },
+});

package/templates/starter/vitest.workers.config.ts

@@ -0,0 +1,26 @@
+import { cloudflareTest } from "@cloudflare/vitest-plugin";
+import { defineConfig } from "vitest/config";
+
+// The Workers-runtime project: `*.workers.test.ts` runs inside workerd, against a real D1 database and
+// a real KV namespace that Miniflare creates per run and throws away after. No mocks, no fakes.
+//
+// The bindings here are declared for the *test* runtime, not read from a Worker's wrangler.jsonc — one
+// test run covers every Worker under apps/, and they do not all declare the same bindings. Add a
+// binding here when a capability you compose needs one; `pithy add <capability>` writes it into the
+// Worker's wrangler.jsonc, and this file is the matching statement for tests.
+export default defineConfig({
+  plugins: [
+    cloudflareTest({
+      miniflare: {
+        compatibilityDate: "2026-06-01",
+        compatibilityFlags: ["nodejs_compat"],
+        d1Databases: ["DB"],
+        kvNamespaces: ["SESSIONS"],
+      },
+    }),
+  ],
+  test: {
+    name: "workers",
+    include: ["apps/*/src/**/*.workers.test.ts"],
+  },
+});