@pithy-sh/cli 0.1.0

package/src/doctor/workerName.ts

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { basename } from "node:path";
+import { kebab } from "@pithy-sh/core/src/naming/resource";
+import { loadProject } from "../project/config";
+import { discoverWorkers, type WorkerTarget } from "../project/workers";
+import { readWranglerConfig } from "../project/wrangler";
+
+/**
+ * Whether a Worker's three names still agree.
+ *
+ * **A Worker's name is not one string.** It is stamped in three places, and every one of them is read by
+ * something different:
+ *
+ * - the directory, `apps/<name>/`, which tsconfig references and CI working-directories point at;
+ * - the deployed script name in `wrangler.jsonc`, which is what Cloudflare serves it under;
+ * - `vars.WORKER`, which is what separates two Workers' audit events when they share a database.
+ *
+ * `pithy worker rename` moves all three together. A rename done by hand — `git mv`, then the edits —
+ * moves whichever the person remembered, and nothing until now noticed the rest. The failure is quiet and
+ * it is the worst shape a failure can take: the Worker deploys under one name and stamps its events with
+ * another, so the audit trail names a Worker that is not the one that acted.
+ *
+ * This is the counterpart to {@link checkProjectName}, one level down, and it is held to the same
+ * evidence discipline: a name is only a fault when this repo's own files positively contradict each
+ * other. An adopter who migrated an existing Worker in has a script name Pithy never composed, and that
+ * is theirs.
+ */
+export type WorkerNameState =
+  /** Every stamp this project declares agrees with the directory it sits in. */
+  | "ok"
+  /** A `wrangler.jsonc` would not parse, or the worker set would not enumerate. Never fails the exit. */
+  | "could-not-check"
+  /** A stamp contradicts the directory. Established from local files alone, and it fails the exit. */
+  | "drifted";
+
+/** One stamp that disagrees with the directory holding it. */
+export interface WorkerNameMismatch {
+  /** The `apps/<dir>` basename — the anchor, since tsconfig and CI point at the path, not at a config key. */
+  worker: string;
+  /** Which stamp disagrees: the deployed script name, or the `WORKER` var. */
+  stamp: "name" | "vars.WORKER";
+  /** The value the file declares. */
+  declared: string;
+  /** The value the directory implies. */
+  expected: string;
+  /**
+   * The environment stanzas declaring it — `dev` for the top-level one. Empty for the script name, which
+   * is one top-level key rather than a per-environment one.
+   */
+  envs: string[];
+}
+
+/** What `doctor` learned about this project's worker names. */
+export interface WorkerNameCheck {
+  state: WorkerNameState;
+  mismatches: WorkerNameMismatch[];
+}
+
+/** The `wrangler.jsonc` keys this reads: the script name, and the `WORKER` var in every stanza. */
+interface NamedWorkerConfig {
+  name?: string;
+  vars?: Record<string, string | undefined>;
+  env?: Record<string, NamedWorkerConfig | undefined>;
+}
+
+/** Every environment's stanza: the top-level one (the dev environment) plus each `env.<name>`. */
+function envStanzas(config: NamedWorkerConfig): { env: string; stanza: NamedWorkerConfig }[] {
+  const list = [{ env: "dev", stanza: config }];
+  for (const [env, stanza] of Object.entries(config.env ?? {})) {
+    if (stanza) list.push({ env, stanza });
+  }
+  return list;
+}
+
+/**
+ * The script-name mismatch for one Worker, or `null` when there is nothing to say.
+ *
+ * **Shape is the filter, exactly as it is for the project name.** `<project>-<worker>` is what
+ * `scaffoldWorker` writes, so a declared name leading with this project's own segment was composed by
+ * Pithy's rule and its tail is a worker segment — a tail that is not the directory is this repo
+ * contradicting itself. A name that does not lead with the project (`my-service`, brought in from a
+ * Worker that predates the project) was never composed from anything, so nothing local establishes what
+ * it ought to be, and a check that renamed it would be inventing a fault on the adoption path.
+ */
+function scriptNameMismatch(worker: string, declared: string | undefined, project: string | null): boolean {
+  if (declared === undefined || project === null) return false;
+  return declared.startsWith(`${project}-`) && declared !== `${project}-${worker}`;
+}
+
+/** Group the per-environment `WORKER` disagreements by the value they declare — one line per wrong value. */
+function workerVarMismatches(worker: string, config: NamedWorkerConfig): WorkerNameMismatch[] {
+  const byValue = new Map<string, string[]>();
+  for (const { env, stanza } of envStanzas(config)) {
+    const declared = stanza.vars?.WORKER;
+    // A stanza that declares no `WORKER` declares nothing to contradict. Adding one is `pithy worker`'s
+    // job, not a diagnostic's, and reporting its absence would fail every Worker written before the var.
+    if (declared === undefined || declared === worker) continue;
+    byValue.set(declared, [...(byValue.get(declared) ?? []), env]);
+  }
+  return [...byValue].map(([declared, envs]) => ({
+    worker,
+    stamp: "vars.WORKER" as const,
+    declared,
+    expected: worker,
+    envs,
+  }));
+}
+
+/** The configured project name, or `null` when the root config would not read or carries none. */
+async function configuredProject(projectDir: string): Promise<string | null> {
+  try {
+    const config = await loadProject(projectDir);
+    // Kebabed through core's own helper, because that is the form `scaffoldWorker` stamped into the
+    // script name. An illegal name is not refused here: `checkProjectName` is the check that owns that
+    // verdict, and two blocks reporting one fault is how a report starts contradicting itself.
+    return config.name ? kebab(config.name) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check every Worker under `apps/` for the three-way disagreement a hand-rename leaves.
+ *
+ * Never throws. A diagnostic has to work in the broken project it exists to diagnose, so an unreadable
+ * `wrangler.jsonc` becomes `could-not-check` rather than an exception — and only when nothing else was
+ * found. A mismatch this read is a fault whether or not the next file parsed; degrading a positive
+ * finding into "I could not check" would hide the fault behind the noise.
+ */
+export async function checkWorkerNames(projectDir: string): Promise<WorkerNameCheck> {
+  let workers: WorkerTarget[];
+  try {
+    workers = await discoverWorkers(projectDir);
+  } catch {
+    return { state: "could-not-check", mismatches: [] };
+  }
+
+  const project = await configuredProject(projectDir);
+  const mismatches: WorkerNameMismatch[] = [];
+  let unreadable = false;
+  for (const target of workers) {
+    if (!target.hasWrangler) continue; // a non-Worker process in the dev set has no script name at all
+    let config: NamedWorkerConfig;
+    try {
+      config = (await readWranglerConfig(target.dir)) as NamedWorkerConfig;
+    } catch {
+      unreadable = true;
+      continue;
+    }
+    const worker = basename(target.dir);
+    if (scriptNameMismatch(worker, config.name, project) && config.name !== undefined) {
+      mismatches.push({
+        worker,
+        stamp: "name",
+        declared: config.name,
+        expected: `${project}-${worker}`,
+        envs: [],
+      });
+    }
+    mismatches.push(...workerVarMismatches(worker, config));
+  }
+
+  if (mismatches.length > 0) return { state: "drifted", mismatches };
+  return { state: unreadable ? "could-not-check" : "ok", mismatches: [] };
+}
+
+/** One mismatch in a sentence — what the stamp does with the wrong name, and what the directory says. */
+export function describeWorkerName(mismatch: WorkerNameMismatch): string {
+  return mismatch.stamp === "name"
+    ? `deploys as ${mismatch.declared}, not ${mismatch.expected}`
+    : `stamps events as ${mismatch.declared}, not ${mismatch.expected}`;
+}

package/src/doctor/wranglerVars.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readWranglerConfig } from "../project/wrangler";
+
+/**
+ * Every variable name one Worker's `wrangler.jsonc` declares — the top-level `vars` block **and** every
+ * `env.<name>.vars`.
+ *
+ * **`env.<name>.vars` REPLACES the top-level block rather than merging it**, which is the gotcha the
+ * starter's own `wrangler.jsonc` comment warns about: every environment repeats every variable. So a
+ * name counts as declared if it appears at the top level **or** in any environment — reading only the
+ * top level names a staging-only variable as undeclared, and reading only one environment names every
+ * ordinary variable as undeclared.
+ *
+ * **It lives here rather than in either caller.** Two doctor checks ask this question — what a
+ * `.dev.vars.local` key has behind it, and what a root `.dev.vars` key has behind it — and a rule this
+ * easy to get half-right is a rule that must exist once. An unreadable or absent config declares
+ * nothing, which is the honest answer: the health block is where a `wrangler.jsonc` that will not parse
+ * gets said, and louder.
+ */
+export async function declaredVars(workerDir: string): Promise<Set<string>> {
+  const config = (await readWranglerConfig(workerDir).catch(() => null)) as {
+    vars?: Record<string, unknown>;
+    env?: Record<string, { vars?: Record<string, unknown> } | undefined>;
+  } | null;
+  const keys = new Set<string>();
+  for (const key of Object.keys(config?.vars ?? {})) keys.add(key);
+  for (const environment of Object.values(config?.env ?? {})) {
+    for (const key of Object.keys(environment?.vars ?? {})) keys.add(key);
+  }
+  return keys;
+}

package/src/feature/bindings.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingType } from "@pithy-sh/core/src/capability/bindings";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import type { FeatureResourceKind } from "@pithy-sh/core/src/naming/feature";
+
+/**
+ * A single Cloudflare resource `pithy provision --feature` stands up: the Worker binding it backs and the
+ * kind of resource that binding needs. Derived purely from the composed capabilities' `requiredBindings`
+ * — no hand-maintained list — so enabling a capability automatically brings its resources into the set.
+ */
+export interface ProvisionableBinding {
+  /** The Worker binding name (e.g. "DB", "SESSIONS", "ASSETS"). */
+  binding: string;
+  /** The provisionable resource kind this binding needs. */
+  kind: FeatureResourceKind;
+}
+
+/**
+ * The subset of {@link BindingType}s `pithy feature` provisions as standalone, per-feature resources.
+ * D1 databases, KV namespaces, and R2 buckets each get their own ephemeral resource. Every other
+ * binding kind is either account-scoped (`ai`), wired in config rather than provisioned (`durable_object`,
+ * `service`, `workflow`, `queue`), or owned by another capability's provisioner (`secret`, `email`) — so
+ * `provision` skips them. Extend this map (and the CF provisioners) to grow the provisionable set.
+ */
+const PROVISIONABLE: Partial<Record<BindingType, FeatureResourceKind>> = {
+  d1: "d1",
+  kv: "kv",
+  r2: "r2",
+};
+
+/**
+ * The provisionable resources for a set of enabled capabilities: every `d1`/`kv`/`r2` binding they
+ * declare, deduplicated by binding name (two capabilities may share one binding — one resource backs it),
+ * in a stable order. Non-provisionable binding kinds are dropped. This is the auto-discovered set
+ * `provision` creates one CF resource per and `destroy` reconciles against.
+ */
+/** A worker-to-worker RPC binding: the env name it appears under, and the Worker it calls. */
+export interface ServiceBinding {
+  /** The binding name in the Worker env (e.g. "API"). */
+  binding: string;
+  /** The target Worker, as named in `apps/<name>/`. */
+  target: string;
+}
+
+/**
+ * Every `service` binding the enabled capabilities declare, deduplicated by binding name. These are not
+ * provisioned — the target Worker is deployed, not created — but each one must be *rewritten per
+ * environment*: in a feature environment the binding has to point at that feature's own deployment of the
+ * target, not at production's. `provision` resolves each target to its environment-scoped script name.
+ */
+export function serviceBindings(capabilities: Capability[]): ServiceBinding[] {
+  const seen = new Set<string>();
+  const result: ServiceBinding[] = [];
+  for (const capability of capabilities) {
+    for (const spec of capability.requiredBindings) {
+      // `service` is guaranteed by BindingSpec's check; the guard keeps this total for a hand-built spec.
+      if (spec.type !== "service" || !spec.service || seen.has(spec.name)) continue;
+      seen.add(spec.name);
+      result.push({ binding: spec.name, target: spec.service });
+    }
+  }
+  return result;
+}
+
+export function provisionableBindings(
+  capabilities: readonly Capability[],
+  declined: ReadonlySet<string> = new Set(),
+): ProvisionableBinding[] {
+  const seen = new Set<string>();
+  const result: ProvisionableBinding[] = [];
+  for (const capability of capabilities) {
+    for (const spec of capability.requiredBindings) {
+      const kind = PROVISIONABLE[spec.type];
+      if (!kind || seen.has(spec.name)) continue;
+      // **A declined binding gets no resource.** Stopping `pithy upgrade` writing the binding while
+      // provisioning still created the bucket behind it handed the adopter exactly the resource they had
+      // declined (#440). `declined` is resolved once, by `honoredDeclines` in the reconcile engine, so
+      // this reads an answer rather than deciding one — a second expression of that rule is how the two
+      // would come to disagree.
+      //
+      // `spec.optional` is asked again anyway, and deliberately. `resolveDeclines` already refuses a
+      // decline of a required binding, but this function is reached by a different command through a
+      // different path, and a provisioning step that could skip a required resource on a name alone is
+      // one bad set away from a project whose database was never created.
+      if (spec.optional && declined.has(spec.name)) continue;
+      seen.add(spec.name);
+      result.push({ binding: spec.name, kind });
+    }
+  }
+  return result;
+}

package/src/feature/create.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { migrateProject } from "../migrations/run";
+import { loadProject, loadProjectCloudflare, requireProjectName } from "../project/config";
+import { detectPackageManager, type InstallRunner } from "../project/packageManager";
+import type { WorkerTarget } from "../project/workers";
+import { seedProject } from "../seed/run";
+import type { DevConfig } from "./devConfig";
+import { syncFeatureDevConfig } from "./sync";
+import { createWorktree, defaultGit, type GitRunner } from "./worktree";
+
+/**
+ * `pithy feature create` — the local, automatic half of the lifecycle, run from the main checkout. It
+ * creates the branch + worktree (the proven core), reserves a non-overlapping port block and pins one port
+ * per worker into the worktree's `.dev.config.json`, installs deps with the adopter's package manager, then
+ * migrates and seeds the local Miniflare backend. No Cloudflare spend — a working local env, ready for
+ * `pithy dev`, from one command.
+ *
+ * No `.dev.vars` is wired here, and none is copied. Each Worker's is generated by `pithy dev` from this
+ * machine's own sources (#154), so a fresh worktree needs nothing carried into it.
+ */
+
+/** A local/dev backend step (migrate or seed) — a seam so create is testable without Miniflare. */
+export type LocalRunner = (args: { projectDir: string }) => Promise<void>;
+
+// A `dev` migrate names its project too: the local Miniflare store lives at the project root and is
+// shared with `wrangler dev`, and this is usually the run that first stamps it. An unstamped database is
+// one any project can later claim, so the first write is the only chance to record the owner.
+const localMigrate: LocalRunner = async ({ projectDir }) => {
+  // One config load, two facts: the name the database is stamped with, and the account it is reached in.
+  // Both are read from the **worktree's** own `pithy.config.ts`, because the branch being created is what
+  // decides them and it may already differ from the checkout this command was run in (#234).
+  const config = await loadProject(projectDir);
+  await migrateProject({
+    env: "dev",
+    projectDir,
+    project: requireProjectName(config),
+    account: loadProjectCloudflare(config) ?? null,
+  });
+};
+
+// Even a `dev` seed names its project: Cloudflare Images and Stream have no local emulation, so a media
+// fixture here writes into the same account-wide store production shares, and only the ownership metadata
+// says who put it there.
+const localSeed: LocalRunner = async ({ projectDir }) => {
+  const config = await loadProject(projectDir);
+  await seedProject({
+    env: "dev",
+    projectDir,
+    project: requireProjectName(config),
+    account: loadProjectCloudflare(config) ?? null,
+    json: true,
+  });
+};
+
+/**
+ * The structured outcome of `pithy feature create` — the `--json` payload and the human summary source.
+ *
+ * **It says nothing about migrate and seed, and that is the change (#231).** It used to carry
+ * `migrated: true, seeded: true`, both written as literals a few lines below the two `await`s. Neither
+ * step has a flag here and both throw on failure, so a report that exists at all is the proof they ran:
+ * the pair was a constant with the grammar of a fact, and the only branch a consumer could write on it
+ * — `if (migrated && !seeded)` — is one that can never fire and can never be tested. If create ever
+ * grows a `--skip-data` of its own, `feature sync`'s `data` is the field to copy, because a value that
+ * can be `false` is the only kind worth emitting.
+ */
+export interface CreateReport {
+  /** The command that produced the report. */
+  command: "feature.create";
+  /** The feature branch created or attached. */
+  branch: string;
+  /** The absolute worktree path. */
+  worktree: string;
+  /**
+   * Whether a new worktree was created (false on an idempotent re-run over an existing one).
+   *
+   * **Named for what it created (#235).** It was `created`, and `pithy ui add` emits a `created` of its
+   * own that is a `string[]` of files — one name, two types, so `if (result.created)` is true for a
+   * non-empty file list and true for this boolean, and a consumer that guessed wrong got no error. The
+   * subject is the outlier here: `ui`'s says *what* was created, this one says *whether*, and the thing it
+   * says it about is already in the payload beside it. `feature.destroy` had settled the convention
+   * anyway — `portsFreed`, `worktreePruned`, `branchDeleted` — so a bare `created` was the odd one out
+   * inside its own command before it was one across the CLI.
+   */
+  worktreeCreated: boolean;
+  /**
+   * The ref the branch was cut from — the trunk's name, or `"HEAD"`. **Null when nothing was cut**: an
+   * already-registered worktree, or a branch that already existed and was attached to.
+   *
+   * The command reports how far the trunk is behind its remote, and only when this is non-null. On the
+   * attach path that sentence would be about a base somebody else chose months ago — a false sentence
+   * about a base, which is the defect `#454` is about.
+   */
+  base: string | null;
+  /** The feature's dev config — its reserved port block and each worker's pinned endpoint. */
+  dev: DevConfig;
+}
+
+/** Options for {@link createFeature}. */
+export interface CreateFeatureOptions {
+  /** The main checkout root — the port registry's key, and where the source `.dev.vars` lives. */
+  projectDir: string;
+  /** The issue number. */
+  issue: string;
+  /** The kebab-case slug. */
+  slug: string;
+  /** Skip the dependency install (tests set this; a real run installs so the gates run in the tree). */
+  skipInstall?: boolean;
+  /** Ports per feature block (defaults to the registry's block size). */
+  blockSize?: number;
+  /** The registry file (default: `<config>/dev-ports.json`). A seam, so a test never writes the real one. */
+  registryPath?: string;
+  /** git runner seam. */
+  git?: GitRunner;
+  /** Install runner seam. */
+  install?: InstallRunner;
+  /** Local migrate seam (default: `migrateProject` against dev). */
+  migrate?: LocalRunner;
+  /** Local seed seam (default: `seedProject` against dev). */
+  seed?: LocalRunner;
+  /** Worker-discovery seam (default: `discoverWorkers`), so tests fix the worker set. */
+  discoverWorkers?: (projectDir: string) => Promise<WorkerTarget[]>;
+}
+
+/**
+ * Stand up a feature's local environment. Creates the worktree, reserves its port block and pins one port
+ * per worker into `.dev.config.json`, installs deps (unless skipped),
+ * then migrates and seeds the local backend. Idempotent: a re-run reuses the existing worktree, keeps its
+ * port block (so every worker's address is stable for the life of the feature), and re-runs migrate/seed
+ * harmlessly.
+ */
+export async function createFeature(options: CreateFeatureOptions): Promise<CreateReport> {
+  const git = options.git ?? defaultGit;
+  const worktree = await createWorktree({ issue: options.issue, slug: options.slug, git });
+
+  // Install before discovering workers so a freshly-cut worktree has its dependencies in place.
+  if (!options.skipInstall) {
+    const pm = await detectPackageManager(worktree.wtPath);
+    const installer = options.install ?? defaultInstall;
+    await installer(pm, ["install"], worktree.wtPath);
+  }
+
+  // Reserve the block and pin every worker's port — the same reconciliation `pithy feature sync` runs, so
+  // creating and later adding a worker go through one implementation.
+  const { dev } = await syncFeatureDevConfig({
+    mainRoot: worktree.root,
+    worktreePath: worktree.wtPath,
+    branch: worktree.branch,
+    ...(options.registryPath !== undefined ? { registryPath: options.registryPath } : {}),
+    ...(options.blockSize !== undefined ? { blockSize: options.blockSize } : {}),
+    ...(options.discoverWorkers !== undefined ? { discoverWorkers: options.discoverWorkers } : {}),
+  });
+
+  // Migrate and seed run against the **worktree**, and discover its Workers themselves: the branch being
+  // created is what decides which Workers exist and what each composes, and it may already differ from the
+  // main checkout this command was run in.
+  const migrate = options.migrate ?? localMigrate;
+  const seed = options.seed ?? localSeed;
+  // Both throw on failure, so reaching the return is what says they ran. Nothing in the report repeats it.
+  await migrate({ projectDir: worktree.wtPath });
+  await seed({ projectDir: worktree.wtPath });
+
+  return {
+    command: "feature.create",
+    branch: worktree.branch,
+    worktree: worktree.wtPath,
+    worktreeCreated: worktree.created,
+    base: worktree.base,
+    dev,
+  };
+}
+
+/** The default install runner — spawn the detected package manager. Lazy import keeps it out of the seam type. */
+const defaultInstall: InstallRunner = async (command, args, cwd) => {
+  const { execFile } = await import("node:child_process");
+  const { promisify } = await import("node:util");
+  await promisify(execFile)(command, args, { cwd });
+};

package/src/feature/destroy.ts

@@ -0,0 +1,160 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { rm } from "node:fs/promises";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import type { FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
+import { partialWriteReport } from "@pithy-sh/secrets/src/cli/partialWrite";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import type { ResourceProvisioners } from "../provision/resources";
+import type { SecretsStore } from "../provision/store";
+import { devConfigPath } from "./devConfig";
+import { freePortBlock, portsRegistryPath, resolveMainRepoRoot } from "./ports";
+import { type DeprovisionedResource, deletedBeforeFailure, deprovisionFeature } from "./provision";
+import { defaultGit, type GitRunner, teardownWorktree } from "./worktree";
+
+/**
+ * `pithy feature destroy` — the teardown half, run from within the worktree. It reverses both remote and
+ * local, in order: delete the manifest's Cloudflare resources then reconcile by prefix-scan, free the
+ * feature's port block, and finally prune the worktree the Linux-safe way. Every step is idempotent, so a
+ * partial-failed provision or a half-torn-down feature still tears down to zero, exiting 0. It is exactly
+ * what the merge-to-main CI job runs headlessly.
+ */
+
+/** The structured outcome of `pithy feature destroy` — the `--json` payload and the human summary source. */
+export interface DestroyReport {
+  /** The command that produced the report. */
+  command: "feature.destroy";
+  /** Every Cloudflare resource deleted (manifest + reconcile). Empty when nothing remained or remote was skipped. */
+  deleted: DeprovisionedResource[];
+  /** Whether the remote teardown ran (false when no provisioners were available, e.g. no CF credentials). */
+  remote: boolean;
+  /** Whether the feature's port block was freed. */
+  portsFreed: boolean;
+  /** Whether a registered worktree was pruned. */
+  worktreePruned: boolean;
+  /** Whether the feature branch was deleted (only when merged). */
+  branchDeleted: boolean;
+}
+
+/** A carried value arrives as `unknown`; this is the narrowing, never a cast. */
+function isDestroyReport(value: unknown): value is DestroyReport {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<DestroyReport>;
+  return candidate.command === "feature.destroy" && Array.isArray(candidate.deleted);
+}
+
+/**
+ * **Where the record of a teardown that failed partway rides out of it (#380).**
+ *
+ * A teardown destroys infrastructure and reports what it destroyed. Until now a throw from the remote
+ * half took that report with it, so an operator whose token expired on the fourth of five deletes was
+ * told only that it failed — and the three databases that were already gone were gone unrecorded. The
+ * report is the whole product of this command, so it survives the failure the same way a partial mint
+ * does (#324).
+ */
+const deprovisionReport = partialWriteReport<DestroyReport>("pithy.cli.destroyReport", isDestroyReport);
+
+/** What a failed {@link destroyFeature} run tore down before it failed, or `undefined` for any other throw. */
+export function destroyedBeforeFailure(error: unknown): DestroyReport | undefined {
+  return deprovisionReport.read(error);
+}
+
+/** Options for {@link destroyFeature}. */
+export interface DestroyFeatureOptions {
+  /** The worktree root — where the manifest lives and the branch is checked out. */
+  projectDir: string;
+  /** The feature identity — project/issue/slug — for recomputing resource names and the branch name. */
+  identity: FeatureIdentity;
+  /**
+   * Every capability the feature spans — the union of its Workers' own configs, the same one `provision`
+   * derived resource names from. The remote reconcile recomputes those exact names from it.
+   */
+  capabilities: Capability[];
+  /** The environment being torn down. Recorded on each audit event. */
+  env: string;
+  /** The provisioners to delete through, or undefined to skip remote teardown (e.g. no CF credentials). */
+  provisioners?: ResourceProvisioners;
+  /**
+   * The account's Secrets Store, when one is reachable. Teardown removes the entries this feature
+   * created; a store entry left behind is a live credential in a flat namespace with nothing pointing
+   * at it.
+   */
+  store?: SecretsStore;
+  /** Audit emitter, so every deletion leaves a record. Defaults to recording nothing. */
+  audit?: CliAuditEmit;
+  /** git runner seam. */
+  git?: GitRunner;
+  /** Override the registry file (tests inject; a real run resolves `<config>/dev-ports.json`). */
+  registryPath?: string;
+  /** Override the main checkout root, the registry's key (tests inject; a real run resolves it via git-common-dir). */
+  root?: string;
+}
+
+/**
+ * Tear a feature down. Delete its Cloudflare resources (manifest ids, then prefix-scan reconcile) when
+ * provisioners are available, free its port block, and prune its worktree + branch — in that order.
+ * Idempotent end to end: already-gone resources, an unallocated port block, and an absent worktree are all
+ * clean no-ops, so re-running (or running on a never-provisioned feature) exits without error.
+ */
+export async function destroyFeature(options: DestroyFeatureOptions): Promise<DestroyReport> {
+  const git = options.git ?? defaultGit;
+
+  let deleted: DeprovisionedResource[] = [];
+  const remote = options.provisioners !== undefined;
+  if (options.provisioners) {
+    try {
+      const report = await deprovisionFeature({
+        projectDir: options.projectDir,
+        identity: options.identity,
+        capabilities: options.capabilities,
+        env: options.env,
+        provisioners: options.provisioners,
+        ...(options.store !== undefined ? { store: options.store } : {}),
+        ...(options.audit !== undefined ? { audit: options.audit } : {}),
+      });
+      deleted = report.deleted;
+    } catch (error) {
+      // What the remote half destroyed before it failed, moved onto this report and carried on again so
+      // the command can print it beside the failure (#380). The local half below deliberately does not
+      // run: pruning the worktree would remove the checkout the re-run has to happen from, and the
+      // feature manifest that says what is left to delete lives in it.
+      throw deprovisionReport.carry(error, {
+        command: "feature.destroy",
+        deleted: deletedBeforeFailure(error),
+        remote,
+        portsFreed: false,
+        worktreePruned: false,
+        branchDeleted: false,
+      });
+    }
+  }
+
+  const registryPath = options.registryPath ?? portsRegistryPath();
+  // The same git-common-dir derivation the registry key was always freed by — `projectDir` is the
+  // worktree, and this is the main checkout it belongs to. `ports.test.ts` pins it against the
+  // `git worktree list` derivation `feature create` reserves under, because a key freed under a root
+  // create never wrote is a no-op that still reports `portsFreed: true` (#435).
+  const root = options.root ?? (await resolveMainRepoRoot(options.projectDir));
+  const branch = `feature/${options.identity.issue}-${options.identity.slug}`;
+  // Drop the feature's pinned ports **before** freeing its registry key, and in that order. Teardown leaves
+  // the worktree's files on disk by design (recursive deletion is what we must never do on Linux), and
+  // `.dev.config.json` is a port claim: every later `feature create`/`sync` rebuilds the registry from the
+  // pinned blocks it finds under `.worktrees`, so a surviving one hands this branch its block straight back —
+  // permanently, to a feature that no longer exists. Removing one file is not a recursive delete. If the run
+  // dies between the two steps, the registry is the only claim left and a re-run clears it; the reverse order
+  // would leave the stale claim to be reclaimed.
+  await rm(devConfigPath(options.projectDir), { force: true });
+  await freePortBlock({ registryPath, root, branch });
+
+  const teardown = await teardownWorktree({ issue: options.identity.issue, slug: options.identity.slug, git });
+
+  return {
+    command: "feature.destroy",
+    deleted,
+    remote,
+    portsFreed: true,
+    worktreePruned: teardown.pruned,
+    branchDeleted: teardown.branchDeleted,
+  };
+}