@pithy-sh/cli 0.1.0

package/src/commands/provision.ts

@@ -0,0 +1,368 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { environmentScope } from "@pithy-sh/core/src/naming/provisionScope";
+import { defineCommand } from "citty";
+import { type CliAuditEmit, createCliAudit } from "../audit/cliAudit";
+import { storeSecretMinter } from "../capabilities/mintSecrets";
+import { type CloudflareAccountSelection, cloudflareAccountConfirmation, cloudflareEnv } from "../cloudflare/config";
+import { branchIdentity } from "../feature/identity";
+import { provisionFeature } from "../feature/provision";
+import {
+  loadProject,
+  loadProjectCloudflare,
+  loadProjectEnvironments,
+  projectCloudflareAccount,
+  requireProjectName,
+} from "../project/config";
+import { requireManagedEnvironment } from "../project/environment";
+import { projectCapabilities, resolveWorkers } from "../project/workerScope";
+import { assertProvisionConfirmed, provisionConfirmPhrase } from "../provision/confirm";
+import { type ProvisionReport, provisionEnvironment } from "../provision/environment";
+import { type ProvisionMode, requireProvisionMode } from "../provision/mode";
+import { type PendingSecrets, pendingSecretLines, pendingSecrets } from "../provision/pendingSecrets";
+import { AUDIT_DESTINATION_ENV, cloudflareProvisioners, type ResourceProvisioners } from "../provision/resources";
+import { secretsStoreBindings, workerSecretRegistry } from "../provision/secretBindings";
+import { cloudflareSecretsStore, type SecretsStore } from "../provision/store";
+import { formatDone, formatJsonLine, withErrorReporting } from "../terminal/output";
+
+/**
+ * `pithy provision --env <name>` and `pithy provision --feature` — **one command, because provisioning is
+ * one job.**
+ *
+ * Both create an environment's Cloudflare resources, write their ids into each Worker's config, and
+ * migrate. They differ only in how the target environment is *named*: declared in the root
+ * `pithy.config.ts`, or derived from the checked-out branch. That is a flag, not a different verb.
+ *
+ * **The safety is in the scope, not in the spelling.** A `ProvisionScope` carries the resource naming and
+ * the `env.<name>` stanza the ids are written into, as one value (#240) — so a feature-named resource
+ * landing in a declared environment's stanza of a checked-in config is unexpressible rather than merely
+ * refused. Nothing about that depends on which words were typed, which is what leaves one command free to
+ * carry both modes.
+ *
+ * **The one real difference is persistence, and the command says so on every run.** `--env` writes
+ * `env.<name>` into the tracked `wrangler.jsonc`: long-lived ids a human reviews in a pull request.
+ * `--feature` writes a generated config under the already-ignored `.wrangler/`: one job's output,
+ * rebuilt every run and never committed. A single flag that flips whether output is committed will
+ * eventually surprise someone, so each run names the file it wrote and whether that file is committed,
+ * in the human summary and as `--json`'s `committed`. It is also what keeps the standing rule checkable
+ * rather than remembered — **a CI build process never commits back to the repository**: a pipeline runs
+ * `--feature` and has nothing to commit.
+ *
+ * **It is still its own command, and `deploy` refuses rather than calling it.** A deploy that silently
+ * creates account resources is hard to review. `pithy deploy --env staging` names this command instead of
+ * failing inside wrangler.
+ *
+ * **There is no `pithy deprovision`.** `pithy feature destroy` reverses a branch's environment because a
+ * branch's environment is disposable. Staging and production are not, and the one-word difference between
+ * the two is not a difference a flag should carry.
+ */
+
+/** Build the CF control-plane provisioners from the environment's credentials, or null when they are absent. */
+function buildProvisioners(account: CloudflareAccountSelection | null): ResourceProvisioners | null {
+  const vars = cloudflareEnv({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) return null;
+  // What vouches for that id travels with it (#378). `find` is find-or-create's first half, and an empty
+  // listing from an account nothing claims is not the absence the second half reads it as.
+  const confirmation = cloudflareAccountConfirmation({ account });
+  return cloudflareProvisioners(new CloudflareClients({ accountId, apiToken }), { accountId, confirmation });
+}
+
+/**
+ * The account's Secrets Store, or `null` when this project has recorded no store id.
+ *
+ * Absent is a degraded environment, never a failed command: a project composing no `secrets` capability
+ * needs no store, and one that does gets its `secrets_store_secrets` stanza — the binding `pithy add`
+ * deliberately could not write, and nothing came back for (#238).
+ */
+function buildStore(account: CloudflareAccountSelection | null): SecretsStore | null {
+  const vars = cloudflareEnv({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  const storeId = vars.SECRETS_STORE_ID ?? "";
+  if (!accountId || !apiToken || !storeId) return null;
+  return cloudflareSecretsStore(new CloudflareClients({ accountId, apiToken }), storeId);
+}
+
+/**
+ * The audit emitter. Provisioning creates real infrastructure under a real token, and it runs headlessly
+ * in CI, so every creation leaves a record of what was made and under whose credentials.
+ *
+ * The trail lands in the project's own top-level database — the environment being provisioned may not
+ * have one yet, which is the whole point of the command.
+ */
+async function buildAudit(
+  projectDir: string,
+  capabilities: Capability[],
+  account: CloudflareAccountSelection | null,
+): Promise<CliAuditEmit> {
+  const vars = cloudflareEnv({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) return async () => {};
+  return createCliAudit({
+    projectDir,
+    // Routing, not truth: each event names the environment it acted on. Claiming this as `actedOn`
+    // would blame `dev` for a change to production — the regression `auditDestination.test.ts` pins.
+    env: AUDIT_DESTINATION_ENV,
+    capabilities,
+    clients: new CloudflareClients({ accountId, apiToken }),
+    apiToken,
+  });
+}
+
+/** The interactive confirm prompt for a production environment. Names what is about to happen first. */
+function confirmPrompt(env: string): () => Promise<string> {
+  return async () => {
+    const { isCancel, text } = await import("@clack/prompts");
+    const answer = await text({
+      message: `This creates Cloudflare resources in ${env}. Type "${provisionConfirmPhrase(env)}" to confirm:`,
+    });
+    return isCancel(answer) ? "" : answer;
+  };
+}
+
+/** Refuse a run with no credentials, naming the environment it was for. */
+function requireProvisioners(account: CloudflareAccountSelection | null, target: string): ResourceProvisioners {
+  const provisioners = buildProvisioners(account);
+  if (provisioners) return provisioners;
+  throw new ValidationError({
+    message: "Cloudflare credentials are missing.",
+    action: `Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN to provision ${target}.`,
+  });
+}
+
+/** Everything `pithy provision` reads off the command line. */
+export interface ProvisionRunOptions {
+  /**
+   * The project root. Defaults to the working directory.
+   *
+   * A seam, and one the refusal gate needs: `commands/provision.test.ts` proves the mode is refused
+   * before anything is read by pointing this at a directory that is not a project at all, which a test
+   * that had to `chdir` could not do without racing every other suite in the pool.
+   */
+  projectDir?: string;
+  /** `--env <name>`: a declared environment. */
+  env?: string | undefined;
+  /** `--feature`: this branch's own environment. */
+  feature: boolean;
+  /** `--yes`. Required for a declared environment; never sufficient for production. */
+  yes: boolean;
+  /** `--confirm <phrase>`: the production phrase, for a headless run. */
+  confirm?: string | undefined;
+  /** `--seed`: also load fixtures. A feature environment is always seeded, so this adds nothing to it. */
+  seed: boolean;
+  /** `--json`. */
+  json: boolean;
+}
+
+/** One line per file written: what landed there, and what happens to it next. */
+function describeConfigs(report: ProvisionReport): string[] {
+  return report.configs.map((config) => {
+    const what = config.ids === 0 ? config.path : `${config.ids} id${config.ids === 1 ? "" : "s"} into ${config.path}`;
+    // The whole point of the line: one flag decides whether these bytes are reviewed and kept, or thrown
+    // away and rebuilt. Saying which costs a sentence and saves someone committing a build artifact — or
+    // wondering why an id they were told to commit is not in `git status`.
+    const fate = report.committed
+      ? `Commit ${config.ids > 1 ? "them" : "it"}.`
+      : "Ignored, and rebuilt on the next run.";
+    return `Wrote ${what}. ${fate}`;
+  });
+}
+
+/**
+ * **What this command declares and cannot create**, and who can — which is not the same answer in both
+ * modes. See `provision/pendingSecrets.ts`, which holds the reasoning and the sentences.
+ */
+function deferredSecrets(capabilities: Capability[], mode: ProvisionMode): PendingSecrets {
+  return pendingSecrets(workerSecretRegistry(capabilities) ?? {}, mode);
+}
+
+/** Write the report: one JSON line, or the human summary. */
+function writeReport(
+  report: ProvisionReport,
+  options: { json: boolean; seeded: boolean; pending: PendingSecrets },
+): void {
+  if (options.json) {
+    process.stdout.write(
+      `${formatJsonLine({
+        command: "provision",
+        ...report,
+        pendingSecrets: options.pending.names,
+        pendingSecretsRemedy: options.pending.remedy,
+      })}\n`,
+    );
+    return;
+  }
+  for (const resource of report.resources) {
+    process.stdout.write(`${resource.name}: ${resource.created ? "created" : "exists"}.\n`);
+  }
+  for (const worker of report.workers) {
+    process.stdout.write(`${worker.worker} deploys as ${worker.name}.\n`);
+  }
+  for (const service of report.services) {
+    process.stdout.write(`${service.binding} bound to ${service.service}.\n`);
+  }
+  for (const secret of report.secretBindings) {
+    // Three states, and the middle one is new (#321): created by this run, already there, or waiting on
+    // a human. The value never appears — what was made and where it went is the whole useful report.
+    if (secret.minted) {
+      process.stdout.write(`${secret.binding} created. Reads ${secret.entry}.\n`);
+    } else if (secret.bound) {
+      process.stdout.write(`${secret.binding} reads ${secret.entry}.\n`);
+    } else {
+      process.stdout.write(
+        `${secret.binding} has no store entry yet. Create it with pithy secrets create ${secret.binding}.\n`,
+      );
+    }
+  }
+  for (const line of describeConfigs(report)) process.stdout.write(`${line}\n`);
+  process.stdout.write(`Provisioned ${report.env}. ${options.seeded ? "Migrated and seeded." : "Migrated."}\n`);
+  // Before `Done.`, because it is the part of the job this command did not do. See `pendingSecrets`.
+  for (const line of pendingSecretLines(options.pending)) process.stdout.write(`${line}\n`);
+  process.stdout.write(`${formatDone()}\n`);
+}
+
+/**
+ * `--env <name>`: an environment the project declares, whose ids are source.
+ *
+ * It takes the resolved {@link ProvisionMode} rather than a bare name, and hands it on to the deferred-
+ * secrets report. There is one producer of the mode — `requireProvisionMode`, in `runProvision` — so
+ * neither branch can report itself as the other, which is how `--feature` came to print `--env`'s
+ * remedy in the first place (#330).
+ */
+async function provisionDeclared(
+  projectDir: string,
+  mode: Extract<ProvisionMode, { kind: "environment" }>,
+  options: ProvisionRunOptions,
+): Promise<void> {
+  const env = mode.env;
+  const config = await loadProject(projectDir);
+  // The declaration decides what may be provisioned. `--env live` on a project that never declared
+  // `live` is refused here, naming the set it does have — rather than creating `<project>-live-db`
+  // that nothing else in the CLI would ever look for again. It is also what closes `--env feature`:
+  // that name is a legal stanza key and an illegal declaration, so no project can admit it.
+  const environment = requireManagedEnvironment(env, loadProjectEnvironments(config));
+  const interactive = !options.json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+  await assertProvisionConfirmed({
+    env: environment,
+    yes: options.yes,
+    json: options.json,
+    ...(options.confirm !== undefined ? { confirmPhrase: options.confirm } : {}),
+    ...(interactive ? { prompt: confirmPrompt(environment) } : {}),
+    ...(config.seed?.productionEnvironments !== undefined
+      ? { productionEnvironments: config.seed.productionEnvironments }
+      : {}),
+  });
+
+  const account = loadProjectCloudflare(config) ?? null;
+  const provisioners = requireProvisioners(account, environment);
+  const capabilities = projectCapabilities(await resolveWorkers({ projectDir }));
+  // The scope carries both the names and the stanza. There is no second argument to disagree with.
+  const scope = environmentScope(requireProjectName(config), environment);
+  const store = buildStore(account);
+  const audit = await buildAudit(projectDir, capabilities, account);
+  const report = await provisionEnvironment({
+    projectDir,
+    scope,
+    capabilities,
+    provisioners,
+    ...(store
+      ? {
+          secretBindings: async (workerCapabilities) =>
+            secretsStoreBindings({
+              // A Worker composing no secrets capability declares no secrets, and gets no stanza.
+              registry: workerSecretRegistry(workerCapabilities) ?? {},
+              scope,
+              storeId: store.storeId,
+              exists: (name) => store.exists(name),
+              // A declared secret whose value is arbitrary is created here rather than printed as
+              // homework (#321). Absence is checked first, so an existing value is never replaced.
+              mint: storeSecretMinter({ store, environment: scope.stanza, audit }),
+            }),
+        }
+      : {}),
+    // Off unless asked. A declared environment already holds real rows; seeding one is `pithy seed`'s
+    // job, with its own gate, and it must not be something provisioning did on the way past.
+    seedData: options.seed,
+    audit,
+  });
+  writeReport(report, { json: options.json, seeded: options.seed, pending: deferredSecrets(capabilities, mode) });
+}
+
+/**
+ * `--feature`: this branch's own environment, whose ids are a build artifact.
+ *
+ * **No confirmation gate, and that is not an omission.** A feature environment is created per pull
+ * request and destroyed on merge; requiring the phrase that protects production would put it in every
+ * pipeline, which is exactly how a gate stops meaning anything. It also always seeds — a feature
+ * environment is created empty and useless without fixtures — so `--seed` has nothing to add to it.
+ */
+async function provisionBranch(
+  projectDir: string,
+  mode: Extract<ProvisionMode, { kind: "feature" }>,
+  options: ProvisionRunOptions,
+): Promise<void> {
+  const { identity, capabilities } = await branchIdentity(projectDir);
+  const account = await projectCloudflareAccount(projectDir);
+  const provisioners = requireProvisioners(account, "a feature environment");
+  const store = buildStore(account);
+  const report = await provisionFeature({
+    projectDir,
+    capabilities,
+    ...(store ? { store } : {}),
+    identity,
+    provisioners,
+    audit: await buildAudit(projectDir, capabilities, account),
+  });
+  writeReport(report, { json: options.json, seeded: true, pending: deferredSecrets(capabilities, mode) });
+}
+
+/**
+ * The command body, exported so the mode gate can be tested against a directory that is not a project.
+ *
+ * Throws `PithyError`; the citty wrapper below is what reports and exits.
+ */
+export async function runProvision(options: ProvisionRunOptions): Promise<void> {
+  // First, before the working directory is read, before a config is loaded, and before any Cloudflare
+  // client exists. A run that named no environment or two is a mistake in the command line, and it gets
+  // an answer about the command line.
+  const mode = requireProvisionMode(options);
+  const projectDir = options.projectDir ?? process.cwd();
+  if (mode.kind === "feature") return provisionBranch(projectDir, mode, options);
+  return provisionDeclared(projectDir, mode, options);
+}
+
+export default defineCommand({
+  meta: {
+    name: "provision",
+    description: "Create an environment's own Cloudflare resources, wire them into each Worker, then migrate",
+  },
+  args: {
+    env: { type: "string", description: "The declared environment to provision" },
+    feature: { type: "boolean", default: false, description: "Provision this branch's own environment instead" },
+    yes: { type: "boolean", default: false, description: "Confirm that this creates real Cloudflare resources" },
+    confirm: {
+      type: "string",
+      description: 'Unlock a production environment non-interactively: "yes, i really want to provision <env>"',
+    },
+    seed: { type: "boolean", default: false, description: "With --env: also load seed fixtures once the schema is up" },
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, () =>
+      runProvision({
+        env: args.env,
+        feature: args.feature,
+        yes: args.yes,
+        confirm: args.confirm,
+        seed: args.seed,
+        json: args.json,
+      }),
+    ),
+});

package/src/commands/remove.ts

@@ -0,0 +1,151 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join, relative } from "node:path";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { defineCommand } from "citty";
+import { defaultRemoveSteps, removeCapability } from "../capabilities/remove";
+import { loadProject, projectCloudflareAccount, requireProjectName } from "../project/config";
+import { envArg, requireEnvironment } from "../project/environment";
+import { formatDone, withErrorReporting } from "../terminal/output";
+import { buildAudit, targetWorker } from "./add";
+
+/**
+ * `remove` is the deliberate exception to the agent-drivable / `--json` convention: it is destructive,
+ * so it is human-only. `--json` fast-fails here — before anything is read or changed.
+ */
+export function rejectJson(json: boolean): void {
+  if (json) {
+    throw new ValidationError({
+      message: "pithy remove is a manual command. --json is not supported.",
+      action: "Run pithy remove <capability> at a terminal.",
+    });
+  }
+}
+
+/**
+ * The `--drop` confirmation for an environment. `dev` asks a light yes/no; any non-dev env demands the
+ * exact typed phrase `drop <cap> from <env>` (the Cloudflare-dashboard delete pattern) — a mismatch or
+ * a cancel returns false and aborts with zero changes. There is no bypass flag.
+ */
+export function dropConfirm(capability: string, env: string): () => Promise<boolean> {
+  return async () => {
+    const clack = await import("@clack/prompts");
+    if (env === "dev") {
+      const answer = await clack.confirm({ message: `Drop ${capability}'s tables from dev? This deletes data.` });
+      return !clack.isCancel(answer) && answer === true;
+    }
+    const phrase = `drop ${capability} from ${env}`;
+    const typed = await clack.text({ message: `This deletes ${env} data. Type "${phrase}" to confirm:` });
+    return !clack.isCancel(typed) && typed === phrase;
+  };
+}
+
+export default defineCommand({
+  meta: { name: "remove", description: "Remove a capability — the manual, interactive inverse of add" },
+  args: {
+    capability: { type: "positional", required: true, description: "Capability name, e.g. auth" },
+    worker: { type: "string", description: "Which worker to unwire it from (apps/<name>)" },
+    drop: {
+      type: "boolean",
+      default: false,
+      description: "Also roll back the capability's migrations (drops its tables)",
+    },
+    env: envArg("With --drop, the environment whose tables to drop"),
+    json: { type: "boolean", default: false, description: "Not supported — remove is manual-only" },
+  },
+  // Errors always render as terminal problem/action lines: `remove` has no machine-readable surface.
+  run: ({ args }) =>
+    withErrorReporting(false, async () => {
+      rejectJson(args.json);
+
+      const projectDir = process.cwd();
+      const env = requireEnvironment(args.env);
+
+      // Which Worker to unwire. `remove` is human-only, so the prompt is available whenever a TTY is.
+      const target = await targetWorker({
+        projectDir,
+        interactive: Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY),
+        ...(args.worker === undefined ? {} : { worker: args.worker }),
+      });
+      const capabilities = target.capabilities;
+
+      // `requireProjectName`, never `resolveProjectName`: a `--drop` reverses migrations against a live
+      // database, and the name is what that database's owner stamp is checked against. A guessed one
+      // (the alphabetically-first Worker, the directory basename) differs between checkouts, so it would
+      // either refuse this project's own database or claim another's. Resolved here, at the command edge,
+      // before anything is read or unwired — a nameless project is told to fix its config, not half-removed.
+      const project = requireProjectName(await loadProject(projectDir));
+      // Resolved once, at the command edge, and used for both the drop and the audit. A `--drop --env
+      // staging` reverses migrations against a live database; the account is what says whose (#234).
+      const account = await projectCloudflareAccount(projectDir);
+
+      const result = await removeCapability({
+        workerDir: target.dir,
+        capability: args.capability,
+        drop: args.drop ? { env, confirm: dropConfirm(args.capability, env) } : undefined,
+        steps: defaultRemoveSteps({
+          projectDir,
+          workerDir: target.dir,
+          loadCapabilities: async () => capabilities,
+          project,
+          account,
+        }),
+        // `--drop`'s env is the natural audit target when given; otherwise "dev", which is inert — a
+        // plain unwiring has no live environment, and the audit database is resolved from the project
+        // root, narrowed to the Worker being unwired.
+        audit: await buildAudit({
+          account,
+          projectDir,
+          worker: target.name,
+          env: args.drop ? env : "dev",
+          capabilities,
+        }),
+      });
+
+      if (!result.present) {
+        process.stdout.write(`${args.capability} is not present in ${target.name}. Nothing to remove.\n`);
+        return;
+      }
+      if (result.aborted) {
+        process.stdout.write("Aborted. Nothing changed.\n");
+        return;
+      }
+
+      process.stdout.write(`Removed ${args.capability} from ${target.name}.\n`);
+      if (result.dropped) {
+        const total = result.dropped.reduce((sum, run) => sum + run.results.length, 0);
+        process.stdout.write(`Dropped ${total} migration${total === 1 ? "" : "s"} from ${env}.\n`);
+      }
+      if (result.ejected) {
+        process.stdout.write(`Deleted ${relative(projectDir, join(target.dir, "capabilities", args.capability))}/.\n`);
+      } else if (result.packageManager) {
+        process.stdout.write(`Uninstalled @pithy-sh/${args.capability}.\n`);
+      } else if (result.keptLinked) {
+        // Nothing declared the package, so there is nothing to uninstall — and npm, asked anyway, prunes
+        // every linked sibling with it. Say what was left, so the link in node_modules is never a surprise.
+        process.stdout.write(`Kept @pithy-sh/${args.capability} — a linked checkout provides it.\n`);
+      } else if (result.keptFor.length > 0) {
+        // The wiring is gone from this Worker, but the package is one shared install — say so plainly,
+        // and name who still holds it, so the leftover dependency is never a surprise.
+        const holders = result.keptFor.join(", ");
+        const verb = result.keptFor.length === 1 ? "still wires it" : "still wire it";
+        process.stdout.write(`Kept @pithy-sh/${args.capability} installed — ${holders} ${verb}.\n`);
+      }
+      if (result.tablesRemain) {
+        // The down code is gone now, so there's no post-removal pithy command to reverse them — name
+        // the tables to drop by hand, and point at --drop for next time.
+        //
+        // Unless a sibling Worker still wires the capability: Workers sharing a binding name share one
+        // database, so those tables are live for the sibling. Telling someone to drop them by hand would
+        // be telling them to delete data another Worker is serving.
+        const shared = result.keptFor.length > 0;
+        process.stdout.write(
+          shared
+            ? `${args.capability}'s D1 tables were left in place — ${result.keptFor.join(", ")} still ${result.keptFor.length === 1 ? "wires" : "wire"} it and ${result.keptFor.length === 1 ? "is" : "are"} using them. Don't drop them by hand.\n`
+            : `${args.capability}'s D1 tables were left in place — your data is safe, and a later pithy add ${args.capability} reuses them. To drop them, remove the pithy_${args.capability}_* tables by hand (pass --drop to reverse them during removal).\n`,
+        );
+      }
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});