@pithy-sh/core 0.9.0 → 0.10.0

package/src/cli/commandFacts.ts

@@ -0,0 +1,219 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * **What the catalog cannot say about a `pithy` command, written down once (#711).**
+ *
+ * `commandCatalog.generated.ts` is the parser's own account of every command: its arguments, its flags, which
+ * are required, which have defaults, which go together. Four facts are not in any parser, and each was the
+ * fault behind a line that did not run as written:
+ *
+ * - **Which commands act on one Worker**, and are refused `input/required` without `--worker` where a project
+ *   has several. `packages/cli/src/ci/runnableCommands.test.ts` proves every entry by running it in a
+ *   two-Worker project, and fails on a command that takes `--worker` and is not classified here.
+ * - **Which flag's default changes what the command acts on.** `pithy vector provision` with no `--env`
+ *   provisions `dev`, so a line about staging that leaves it off sends the reader to the wrong environment.
+ * - **Which commands destroy something**, and are never a remedy for a smaller fault. `pithy feature destroy`
+ *   was offered as the fix for one mis-shaped vector index.
+ * - **Which flag needs another beside it** that the parser does not enforce: `pithy provision --env` is refused
+ *   without `--yes`, at run time.
+ *
+ * `command.ts` builds every command a line names from these and the catalog, and refuses one that breaks them.
+ * Nothing here imports anything, so a Worker that names a command pays for two tables and nothing more.
+ */
+
+/**
+ * The commands that act on exactly one Worker, and refuse `input/required` without `--worker` when a project
+ * has several and the run cannot ask. Every line that names one names the Worker, by its `apps/` directory.
+ */
+export const WORKER_SCOPED = [
+  "add",
+  "dashboard connect",
+  "email provision",
+  "media provision",
+  "payments provision",
+  "storage provision",
+  "support provision",
+  "testers provision",
+  "turnstile deprovision",
+  "turnstile provision",
+  "ui add",
+  "ui sync",
+  "vector provision",
+  "vector reprocess",
+  "vector reset",
+  "worker sync",
+] as const;
+
+/** A command that acts on one Worker. */
+export type WorkerScopedPath = (typeof WORKER_SCOPED)[number];
+
+/**
+ * The commands that take `--worker` and do not need it: each fans out over every Worker, or falls back to the
+ * first that answers, and the flag narrows.
+ */
+export const WORKER_NARROWS = [
+  "contract",
+  "dashboard disconnect",
+  "dashboard revoke-key",
+  "dashboard rotate",
+  "dashboard status",
+  "doctor",
+  "env",
+  "init",
+  "migrate",
+  "seed",
+  "support deprovision",
+  "upgrade",
+] as const;
+
+/**
+ * A command only a person runs, at a terminal, where the Worker is asked for. `pithy remove` refuses every run
+ * that cannot ask (`core/person_required`).
+ */
+export const PERSON_ONLY = ["remove"] as const;
+
+/** A flag that turns a Worker-scoped command into one that acts on no Worker: `pithy add --list` reads the catalog. */
+export const NO_WORKER_MODES: Readonly<Record<string, readonly string[]>> = { add: ["--list"] };
+
+/**
+ * **A flag whose default decides what the command acts on.** Left off a line, the command still runs — on the
+ * default, which is rarely the environment the line was about. Every `--env` with a default is one: `dev` for
+ * `vector provision`, `migrate` and `testers list`, `staging` for `payments reconcile`. A line names it, always.
+ */
+export const MEANING_FLAGS = ["--env"] as const;
+
+/**
+ * The commands whose `--env` decides nothing until another flag asks it to: `pithy remove` touches no database
+ * without `--drop`, and `pithy upgrade` migrates none without `--migrate`. Without that flag a line need not
+ * name the environment; with it, it must.
+ */
+export const MEANING_ONLY_WITH = { remove: "--drop", upgrade: "--migrate" } as const;
+
+/**
+ * **The commands that destroy something, by what they destroy.** None is ever built as a remedy: a line that
+ * names one says it is a person's decision and what it deletes (`command.ts`'s `personDecision`), and carries
+ * no `fix`. `packages/core/src/cli/command.test.ts` holds every command the catalog has to this list or to
+ * {@link NOT_DESTRUCTIVE}, so a new one cannot arrive unexamined.
+ */
+export const DESTRUCTIVE_COMMANDS = {
+  "dashboard disconnect": "the environment's dashboard connection and the key it signs with",
+  "dashboard revoke-key": "a signing key the dashboard holds",
+  "email deprovision": "the email Workers, and with --suppression the suppression database",
+  "feature destroy": "the feature's worktree, its branch and every resource it provisioned",
+  "media deprovision": "the media Worker, and with --storage its bucket",
+  remove: "a capability's wiring",
+  "secrets deprovision": "the secrets manager, and with --keys the store's keys",
+  "secrets rm": "a stored secret",
+  "storage deprovision": "the storage Worker, and with --storage its bucket",
+  "support deprovision": "the support Workers, and with --storage its attachments",
+  "testers deprovision": "the testers Worker",
+  "token revoke": "an API token",
+  "turnstile deprovision": "the Turnstile widget, whose sitekey every client embeds",
+  "vector reset": "every vector in the index",
+  "worker remove": "a Worker's directory",
+} as const;
+
+/** A command that destroys something. */
+export type DestructivePath = keyof typeof DESTRUCTIVE_COMMANDS;
+
+/**
+ * **The flags that make a command destroy something**, on any command that declares them. Each is refused by
+ * the builder; a line that needs one is a person's decision.
+ */
+export const DESTRUCTIVE_FLAGS = {
+  "--destroy-retained": "a resource kept for recovery",
+  "--drop": "a capability's tables",
+  "--redo": "the data a seed wrote",
+  "--rollback": "the schema a migration group applied",
+} as const;
+
+/** A flag that makes a command destroy something. */
+export type DestructiveFlag = keyof typeof DESTRUCTIVE_FLAGS;
+
+/**
+ * The commands whose name reads as destructive and which are not, and why. A command named here is built like
+ * any other.
+ */
+export const NOT_DESTRUCTIVE: Readonly<Record<string, string>> = {
+  "cloudflare disconnect": "revokes a sign-in and deletes no data, which `cloudflare connect` gives back",
+  "docs disconnect": "removes the docs server from an editor's config, which `docs connect` restores",
+  "feature prune": "forgets worktrees that are already gone",
+  "testers close": "stops a cohort accruing, and keeps its history",
+  "testers remove": "takes one tester off a roster, which `testers invite` reverses",
+};
+
+/**
+ * **A flag whose value is a person's confirmation**, never written into a line an agent reads: a phrase spelled
+ * in a remedy is a confirmation nobody gave. A person's decision names the flag and leaves the phrase to them.
+ */
+export const CONFIRM_FLAGS = ["--confirm", "--confirm-production", "--confirm-reset", "--confirm-rollback"] as const;
+
+/**
+ * When a command asks for a confirmation: always, when a flag is passed (`when`), or in every environment but the
+ * ones it trusts (`unlessEnv`) — `vector reset` asks nothing of `dev`, whose index is a laptop's.
+ */
+export const CONFIRMATIONS: readonly { path: string; when?: string; unlessEnv?: readonly string[]; flag: string }[] = [
+  { path: "vector reset", unlessEnv: ["dev"], flag: "--confirm-reset" },
+  { path: "migrate", when: "--rollback", flag: "--confirm-rollback" },
+  { path: "seed", when: "--redo", flag: "--confirm-reset" },
+];
+
+/**
+ * **A flag whose value is a credential**, never written into a line: an error's action reaches logs, a terminal
+ * scrollback and a `--json` consumer, none of which should hold a key. A run named again carries the flag's name
+ * and leaves its value to whoever passed it.
+ */
+export const CREDENTIAL_FLAGS = [
+  "--api-token",
+  "--r2-access-key-id",
+  "--r2-api-token",
+  "--r2-secret-access-key",
+] as const;
+
+/**
+ * The environments every project treats as production. A project can name more in `seed.productionEnvironments`;
+ * a builder that has them passes them.
+ */
+export const PRODUCTION_ENVIRONMENTS = ["prod", "production"] as const;
+
+/**
+ * **What a production run of a command needs from a person**, by command: the confirmation it asks for, or `null`
+ * for one that asks none. A production provision or seed is never a remedy — a line names it as a person's
+ * decision either way, and names a confirmation only when the command declares it: `testers provision` and
+ * `vector provision` take no `--confirm`, and a line that told a person to pass one would be refused.
+ */
+export const PRODUCTION_CONFIRMS = {
+  provision: "--confirm",
+  seed: "--confirm-production",
+  "secrets provision": null,
+  "testers provision": null,
+  "vector provision": null,
+} as const satisfies Readonly<Record<string, string | null>>;
+
+/** A command whose production run is a person's decision. */
+export type ProductionPath = keyof typeof PRODUCTION_CONFIRMS;
+
+/**
+ * **A command that acts on every environment when its `--env` is left off (#711)**, production among them. `pithy
+ * testers provision` with no `--env` provisions every declared environment, so the bare line touches production as
+ * surely as `--env prod` does, and is a person's decision for the same reason. Each declares `--env` with no
+ * default; `command.test.ts` holds that against the catalog.
+ */
+export const EVERY_ENVIRONMENT_WITHOUT_ENV = ["testers provision"] as const satisfies readonly ProductionPath[];
+
+/**
+ * **A command that acts on every environment on every run (#711)**, production among them, with no `--env` to narrow
+ * it. `pithy secrets provision` deploys each declared environment's manager and mints its store entries, so every line
+ * naming it touches production and is a person's decision — never the fix for one binding, one database or one
+ * setting. None declares `--env`; `command.test.ts` holds that against the catalog.
+ */
+export const EVERY_ENVIRONMENT_ALWAYS = ["secrets provision"] as const satisfies readonly ProductionPath[];
+
+/**
+ * A flag a command refuses to run without, beside another, that the parser does not enforce. `pithy provision
+ * --env <env>` with no `--yes` is refused before it does anything; a dry run needs neither.
+ */
+export const REQUIRED_BESIDE: readonly { path: string; with: string; needs: string; unless: string }[] = [
+  { path: "provision", with: "--env", needs: "--yes", unless: "--dry-run" },
+];

package/src/controlPlane/error/errors.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
+import { commandName } from "../../cli/command";
 import { PithyError } from "../../error/pithyError";
 import type { MessageParams } from "../../i18n/catalog";
 
@@ -40,7 +41,9 @@ export class ControlPlaneNotConnectedError extends PithyError {
         code: "controlplane/not_connected",
         status: 403,
         message: args.message ?? "No management client is connected to this environment.",
-        action: args.action ?? "Run pithy dashboard connect --env <environment> to register one.",
+        action:
+          args.action ??
+          `Register one for this environment with ${commandName("dashboard connect")}, naming it with --env.`,
         detail: args.detail,
         params: args.params,
       },
@@ -60,7 +63,9 @@ export class ControlPlaneInvalidCredentialError extends PithyError {
         code: "controlplane/invalid_credential",
         status: 401,
         message: args.message ?? "That credential is not valid here.",
-        action: args.action ?? "Rotate the connection's key, or re-run pithy dashboard connect --update.",
+        action:
+          args.action ??
+          `Rotate the connection's key, or update this environment's connection with ${commandName("dashboard connect")} and its --update flag.`,
         detail: args.detail,
         params: args.params,
       },
@@ -77,7 +82,9 @@ export class ControlPlaneInsufficientScopeError extends PithyError {
         code: "controlplane/insufficient_scope",
         status: 403,
         message: args.message ?? "This connection is not scoped for that operation.",
-        action: args.action ?? "Re-run pithy dashboard connect --update and grant the scope this call needs.",
+        action:
+          args.action ??
+          `Update this environment's connection with ${commandName("dashboard connect")} and its --update flag, granting the scope this call needs.`,
         detail: args.detail,
         params: args.params,
       },

package/src/controlPlane/http/guard.ts

@@ -3,6 +3,8 @@
 
 import type { MiddlewareHandler } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
+import { commandName, remedy } from "../../cli/command";
+import { type AmbientEnv, compositionEnvironment } from "../../env/ambient";
 import { PithyError } from "../../error/pithyError";
 import { workerVersionMetadata } from "../../worker/identity";
 import { ControlPlaneAuditActions, safeEmit } from "../audit/actions";
@@ -55,7 +57,7 @@ export type ControlPlaneVerifier = (
  */
 export function createControlPlaneVerifier(deps: ControlPlaneVerifyDeps): ControlPlaneVerifier {
   return async (request, requirement) => {
-    // Clone before reading. The handler still has to parse this body through `zValidator`, and a stream
+    // Clone before reading. The handler still has to parse this body through `validate`, and a stream
     // consumed here would reach it empty — the digest check would pass and the request would then fail
     // validation for no visible reason.
     const body = new Uint8Array(await request.clone().arrayBuffer());
@@ -138,7 +140,7 @@ export function requireControlPlane(requirement: ControlPlaneRequirement): Middl
     if (!verify) {
       const denial = new ControlPlaneNotConnectedError({
         message: "This deployment does not accept management-client calls.",
-        action: "Add `controlplane()` to this Worker's pithy.config.ts, then run pithy dashboard connect.",
+        action: `Add \`controlplane()\` to this Worker's pithy.config.ts, then ${connectStep(compositionEnvironment(c.env as unknown as AmbientEnv))}.`,
         detail: "no control-plane verifier on the request — the controlplane capability is not composed",
       });
       await auditDenial(c, requirement, denial);
@@ -221,3 +223,13 @@ async function auditDenial(
     c.var.log,
   );
 }
+
+/**
+ * The step that connects a management client, as this deployed Worker can name it: with its own environment when
+ * it knows it, and never with a Worker — it cannot know the `apps/` directory that provisioned it (#711).
+ */
+function connectStep(env: string | undefined): string {
+  if (env === undefined)
+    return `connect one with ${commandName("dashboard connect")}, naming this environment with --env`;
+  return remedy("dashboard connect", { flags: { "--env": env } }, { runtime: true }).say((command) => `run ${command}`);
+}

package/src/controlPlane/http/routes.ts

@@ -1,11 +1,11 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 
-import { zValidator } from "@hono/zod-validator";
 import type { Hono } from "hono";
 import type { PithyHonoEnv } from "../../capability/capability";
-import { validationHook } from "../../http/validation";
-import type { AdminRoute } from "../discovery/adminRoute";
+import { describeRoute } from "../../http/routeSpec";
+import { validate } from "../../http/validation";
+import { type AdminRoute, ControlPlaneManifest } from "../discovery/adminRoute";
 import { ANY_VERIFIED_CALLER, KEYS_ROTATE_SCOPE, MANIFEST_READ_SCOPE } from "../scope/scope";
 import { requireControlPlane } from "./guard";
 import {
@@ -16,6 +16,12 @@ import {
   pingHandler,
   registerKeyHandler,
 } from "./handlers";
+import {
+  ControlPlaneKeysResponse,
+  ControlPlanePingResponse,
+  ExpireKeyResponse,
+  RegisterKeyResponse,
+} from "./responses";
 import { ExpireKeyParams, ExpireKeyRequest, RegisterKeyRequest } from "./schemas";
 
 /**
@@ -92,24 +98,66 @@ export function registerControlPlaneRoutes(
   basePath: string,
   deps: ControlPlaneHandlerDeps,
 ): void {
-  app.get(`${basePath}/ping`, requireControlPlane(ANY_VERIFIED_CALLER), pingHandler(deps));
+  app.get(
+    `${basePath}/ping`,
+    describeRoute({
+      summary: "Prove the connection and the key it signs with.",
+      verification: "control-plane",
+      responses: { 200: ControlPlanePingResponse },
+    }),
+    requireControlPlane(ANY_VERIFIED_CALLER),
+    pingHandler(deps),
+  );
 
-  app.get(`${basePath}/manifest`, requireControlPlane(MANIFEST_READ_SCOPE), manifestHandler(deps));
+  app.get(
+    `${basePath}/manifest`,
+    describeRoute({
+      summary: "Describe what this Worker composes and how to call its admin surface.",
+      verification: "control-plane",
+      scopes: [MANIFEST_READ_SCOPE],
+      responses: { 200: ControlPlaneManifest },
+    }),
+    requireControlPlane(MANIFEST_READ_SCOPE),
+    manifestHandler(deps),
+  );
 
-  app.get(`${basePath}/keys`, requireControlPlane(KEYS_ROTATE_SCOPE), listKeysHandler(deps));
+  app.get(
+    `${basePath}/keys`,
+    describeRoute({
+      summary: "Read the connection's key registration state.",
+      verification: "control-plane",
+      scopes: [KEYS_ROTATE_SCOPE],
+      responses: { 200: ControlPlaneKeysResponse },
+    }),
+    requireControlPlane(KEYS_ROTATE_SCOPE),
+    listKeysHandler(deps),
+  );
 
   app.post(
     `${basePath}/keys`,
+    describeRoute({
+      summary: "Register a key for the connection.",
+      verification: "control-plane",
+      scopes: [KEYS_ROTATE_SCOPE],
+      responses: { 201: RegisterKeyResponse },
+    }),
     requireControlPlane(KEYS_ROTATE_SCOPE),
-    zValidator("json", RegisterKeyRequest, validationHook),
+    validate("json", RegisterKeyRequest),
     (c) => registerKeyHandler(deps)(c, c.req.valid("json")),
   );
 
   app.post(
     `${basePath}/keys/:keyId/expire`,
+    describeRoute({
+      summary: "Retire a superseded key.",
+      description: "Must be signed with the successor it names as proven.",
+      verification: "control-plane",
+      scopes: [KEYS_ROTATE_SCOPE],
+      responses: { 200: ExpireKeyResponse },
+    }),
     requireControlPlane(KEYS_ROTATE_SCOPE),
-    zValidator("param", ExpireKeyParams, validationHook),
-    zValidator("json", ExpireKeyRequest, validationHook),
+    validate("param", ExpireKeyParams),
+    validate("json", ExpireKeyRequest),
     (c) => expireKeyHandler(deps)(c, c.req.valid("param"), c.req.valid("json")),
   );
 }

package/src/createBackend.ts

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { Hono } from "hono";
+import { z } from "zod";
 import { noopEmit } from "./audit/recorder";
 import { BindingSpec } from "./capability/bindings";
 import type {
@@ -14,17 +15,21 @@ import type {
 } from "./capability/capability";
 import { recordComposition } from "./capability/composition";
 import { validateBindings } from "./capability/validateBindings";
+import { pithyCommandOf } from "./cli/command";
 import { isControlPlaneCapability } from "./controlPlane/capability";
 import { allowedOriginSet, corsSurface, registerControlPlaneCors } from "./controlPlane/http/cors";
 import { buildDbRegistry, composeDatabases, type DbRegistry } from "./data/databases";
 import { noEntitlementProvider } from "./entitlement/entitlement";
 import { ValidationError } from "./error/pithyError";
+import { describeRoute } from "./http/routeSpec";
 import { catalogFor, composeMessages } from "./i18n/registry";
 import { bakedTranslator, DEFAULT_LOCALE } from "./i18n/translator";
 import { buildKvRegistry, composeKv, type KvRegistry } from "./kv/namespaces";
 import { loggingErrorHandler } from "./logger/errorHandler";
 import type { Logger } from "./logger/logger";
 import { bindRequestContext, createWorkerLogger } from "./logger/worker";
+import type { RouteGroup } from "./openapi/document";
+import { recordRouteGroups } from "./openapi/routeGroups";
 import { HEALTH_PATH } from "./worker/health";
 import { workerVersion } from "./worker/identity";
 import { registeredWorkflowBinding } from "./workflow/bindings";
@@ -103,6 +108,18 @@ function envNameOf(env: Record<string, unknown>, fallback: string | undefined):
   return typeof env.ENVIRONMENT === "string" && env.ENVIRONMENT.length > 0 ? env.ENVIRONMENT : (fallback ?? "unknown");
 }
 
+/** What `GET /health` answers. */
+export const HealthBody = z
+  .object({
+    status: z.literal("ok").describe("Always `ok`: an answer at all is the liveness signal."),
+    version: z
+      .string()
+      .nullable()
+      .describe("The Cloudflare version id of the build answering, or null where the Worker cannot say."),
+  })
+  .describe("Liveness, and which build is answering.");
+export type HealthBody = z.infer<typeof HealthBody>;
+
 /**
  * Assemble capabilities into a deployable Hono app — a valid Worker `fetch` handler.
  *
@@ -135,7 +152,7 @@ export function createBackend<
       if (!present.has(dep)) {
         throw new ValidationError({
           message: `Capability "${cap.name}" requires the "${dep}" capability, which is not composed.`,
-          action: `Add ${dep}() to createBackend's capabilities (run \`pithy add ${dep}\`).`,
+          action: `Add ${dep}() to createBackend's capabilities (run \`${pithyCommandOf("add", { args: [dep], flags: { "--with-prerequisites": true } }, { runtime: true })}\`).`,
         });
       }
     }
@@ -283,14 +300,30 @@ export function createBackend<
    * before `version_metadata` was declared reports "I cannot tell you", and `deploy` reports the check
    * as inconclusive instead of failing it.
    */
-  app.get(HEALTH_PATH, (c) => c.json({ status: "ok", version: workerVersion(c.env) }));
+  const groups: RouteGroup[] = [];
+  const healthStart = app.routes.length;
+  app.get(
+    HEALTH_PATH,
+    describeRoute({
+      summary: "Report liveness, and which build is answering.",
+      verification: "public",
+      responses: { 200: HealthBody },
+    }),
+    (c) => c.json({ status: "ok", version: workerVersion(c.env) } satisfies HealthBody),
+  );
+  groups.push({ tag: "core", routes: app.routes.slice(healthStart) });
 
   for (const cap of all) {
     for (const middleware of cap.middleware ?? []) middleware(app);
   }
+  // Each hook's slice of the route table is noted as it mounts, so the OpenAPI contract can tag every
+  // operation with the capability that owns it (`openapi/routeGroups.ts`).
   for (const cap of all) {
+    const start = app.routes.length;
     cap.routes?.(app);
+    groups.push({ tag: cap.name, routes: app.routes.slice(start) });
   }
+  recordRouteGroups(app, groups);
 
   return app as unknown as Hono<BackendEnv<readonly [...Caps, App]>>;
 }

package/src/entitlement/require.ts

@@ -16,7 +16,7 @@ import {
  * `verification`-strategy sibling every paid route carries: it says what the caller must *hold*, the
  * way `requireAuth()` says who the caller must *be*, and it belongs on the route line beside it.
  *
- *   app.get("/reports", requireAuth(), requireEntitlement("pro"), zValidator(…), handler)
+ *   app.get("/reports", requireAuth(), requireEntitlement("pro"), validate(…), handler)
  *
  * It lives in `@pithy-sh/core` rather than in `@pithy-sh/payments` for the same reason `requireAuth()`
  * is copied into each capability instead of imported from `@pithy-sh/auth`: a gate that arrives with a