@pithy-sh/cli 0.1.0

package/src/capabilities/requiredOptions.ts

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+
+/**
+ * **An option a manifest states no `default` for is a required option.** That is the whole model.
+ *
+ * There is no flag beside a default that could contradict it. An option that states a default has an
+ * answer the kit is willing to pick; an option that states none has one only the adopter can — so every
+ * path that could write a config either carries a value for it or refuses, and none of them guesses.
+ *
+ * The defect this closes had one shape in three places. `ConfigOption.default` was a required field, so
+ * `promptConfigValues` offered `String(option.default)` as the thing enter accepts, and a `--json` or
+ * non-TTY run attached no prompt at all and fell straight through to the manifest's value. `pithy add
+ * payments --json` picked a billing model: whether an entitlement is held by a person or a company, into
+ * a column and a UNIQUE index, reported as `Done.` A project that meant `organization` found out when it
+ * had subscriptions (#412).
+ *
+ * So the rule lives here, once, and both writers ask it — `pithy add`'s flow before it wires anything,
+ * and `pithy upgrade`'s reconcile before it splices a key into a registration it did not write.
+ */
+
+/** The half of a config option this module needs: what to name, and what it legally takes. */
+export interface RequiredOption {
+  /** The option's key, as `--set key=value` spells it. */
+  readonly key: string;
+  /** The closed set of values it takes, when it states one. */
+  readonly choices?: readonly string[] | undefined;
+  /** The manifest's default. `undefined` is the declaration that this option is required. */
+  readonly default?: unknown;
+}
+
+/** Whether this option must be answered before anything can be written for it. */
+export function isRequired(option: RequiredOption): boolean {
+  return option.default === undefined;
+}
+
+/**
+ * The required options this run has not settled, in manifest order.
+ *
+ * Asked **after** `--set` and any prompt, because those are the two ways of settling one and the answer
+ * is the same whichever it came from. A run with a human attached is never refused for a question it was
+ * asked; a run with no human is refused for a question nobody could ask it.
+ */
+export function unsettledOptions<T extends RequiredOption>(
+  options: readonly T[],
+  values: Readonly<Record<string, unknown>>,
+): T[] {
+  return options.filter((option) => isRequired(option) && values[option.key] === undefined);
+}
+
+/** What {@link requiredOptionRefusal} names: the capability, and each option nobody answered. */
+export interface RequiredOptionRefusalOptions {
+  /** The capability being wired, as `pithy add <capability>` spells it. */
+  capability: string;
+  /** The unsettled options, in manifest order. */
+  missing: readonly RequiredOption[];
+}
+
+/** `--set key=a or --set key=b` for a closed set, `--set key=<value>` for an open one. */
+function flagsFor(option: RequiredOption): string {
+  const choices = option.choices;
+  if (choices === undefined || choices.length === 0) return `--set ${option.key}=<value>`;
+  const flags = choices.map((choice) => `--set ${option.key}=${choice}`);
+  if (flags.length === 1) return flags[0] as string;
+  return `${flags.slice(0, -1).join(", ")} or ${flags[flags.length - 1]}`;
+}
+
+/** `a`, `a and b`, `a, b and c` — for a sentence, never for a command line. */
+function andList(names: readonly string[]): string {
+  if (names.length <= 1) return names.join("");
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/**
+ * The refusal a run that names no value for a required option takes.
+ *
+ * Shaped like `prerequisiteRefusal`, and for the same reason: the `message` says what is wrong and the
+ * `action` is the operator's, so it names the exact flag and every value that flag takes. An agent
+ * driving `pithy add --json` has one line to correct itself from, and "billingSubject is required" is not
+ * that line — `--set billingSubject=user or --set billingSubject=organization` is.
+ */
+export function requiredOptionRefusal(options: RequiredOptionRefusalOptions): ValidationError {
+  const { capability, missing } = options;
+  const keys = missing.map((option) => option.key);
+  return new ValidationError({
+    message: `${capability} needs a value for ${andList(keys)}, and nothing in this run names one.`,
+    action: `Pass ${missing.map(flagsFor).join(", and ")}.`,
+    detail: `${capability}'s manifest declares ${JSON.stringify(keys)} with no default, which is how a capability says the answer is the adopter's. There is nothing to render and nothing to accept by pressing enter.`,
+  });
+}

package/src/capabilities/rotateSecrets.ts

@@ -0,0 +1,305 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import type { SecretDispatcher, SecretRotationRecorder } from "@pithy-sh/secrets/src/cli/dispatch";
+import { dispatchedRotationLedger } from "@pithy-sh/secrets/src/cli/rotationLedger";
+import { secretWriteTargets } from "@pithy-sh/secrets/src/cli/writeTargets";
+import { SecretRotationUnrecordedError } from "@pithy-sh/secrets/src/error/errors";
+import type { SecretRegistry, SecretRegistryEntry } from "@pithy-sh/secrets/src/registry";
+import {
+  type RotationSleeper,
+  rotateSecretValue,
+  type SecretRotationOutcome,
+} from "@pithy-sh/secrets/src/rotation/rotateValue";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { CliAuditEmit } from "../audit/cliAudit";
+
+/**
+ * **`pithy secrets rotate` — the command side of the rotation core.**
+ *
+ * The core (`@pithy-sh/secrets`' `rotateSecretValue`) decides *what happened*; this decides what the
+ * operator reads, what the trail records, and what the shell gets back. They are split because a state and
+ * the sentence describing it must have one producer each — two would let a partial run be phrased as a
+ * complete one, which is the shape #321 and #324 each produced once already.
+ *
+ * ## Three things this file is responsible for
+ *
+ * - **A line per secret, never a summary.** {@link rotationReportLines} renders from the outcome and only
+ *   from the outcome, so there is no path by which "rotated" is printed over an environment that did not
+ *   take the value.
+ * - **The unrecorded state, made unmissable.** {@link unrecordedFailure} turns it into a
+ *   `secrets/rotation_unrecorded` — its own code, its own exit status, and an action line composed from
+ *   the declaration, so the operator is told which console to open rather than that something failed.
+ * - **An exit code that distinguishes it.** {@link EXIT_ROLLED_NOT_RECORDED}.
+ *
+ * ## And one thing it deliberately does not do
+ *
+ * **It never surfaces the value.** Not on a success, not on a failure, not on the failure where the value
+ * is about to be lost. The argument, in full, is in `docs/commands/secrets.md`; in short, a live
+ * credential written to a terminal is in scrollback, in the CI log, and in whatever recorded the session,
+ * permanently — while a rolled-and-unrecorded credential is an outage whose remedy the declaration can
+ * name. The core has no field that could carry a value out, so this is structural rather than a habit.
+ */
+
+/**
+ * The exit status for **rolled at the issuer, not recorded**.
+ *
+ * Distinct from `1`, which every ordinary failure uses, because the two need different reactions and a
+ * script cannot tell them apart from a message. `1` means the previous credential is still live and the
+ * command can be run again. `3` means it is not, and nothing automated will fix it.
+ *
+ * `2` is left alone: shells and citty both use it for usage errors, and a status that could mean either
+ * "you typed it wrong" or "a production credential is dead" is no signal at all.
+ */
+export const EXIT_ROLLED_NOT_RECORDED = 3;
+
+/**
+ * What a rotation needs from the manager: the write, and the ledger row around it.
+ *
+ * One object rather than two arguments because a rotation is one act and the two calls must land on the
+ * same project's managers. `WorkflowSecretDispatcher` implements both, so this is a description of what is
+ * already true rather than a constraint anything has to satisfy separately.
+ */
+export type SecretRotationDispatcher = SecretDispatcher & SecretRotationRecorder;
+
+/** What the command asks for: one secret, in one environment (or none, for a `global` secret). */
+export interface SecretRotateCommand {
+  /** The registry name. */
+  name: string;
+  /** The environment the operator named with `--env`, or `undefined`. Not defaulted — see `SecretWriteCommand`. */
+  env: ManagedEnvironment | undefined;
+  /** Every environment the project declares. What a `global` secret fans out across. */
+  environments: DeclaredEnvironments | readonly string[];
+  /** Resolve the declaration and report what would happen. Calls nothing, writes nothing. */
+  dryRun?: boolean;
+  /** Store attempts per environment. Defaults to the core's 3. Never a re-roll. */
+  attempts?: number;
+  /** Injected in tests so a retry costs no real time. */
+  sleep?: RotationSleeper;
+}
+
+/** The entry, or the same refusal `runSecretWrite` gives for a name the registry has never heard of. */
+function requireEntry(registry: SecretRegistry, name: string): SecretRegistryEntry {
+  const entry = registry[name];
+  if (!entry) {
+    throw new NotFoundError({
+      message: `Secret '${name}' is not declared in the registry.`,
+      action: "Add it to your secret registry, then run this again.",
+    });
+  }
+  return entry;
+}
+
+/**
+ * Rotate one secret and record what happened.
+ *
+ * **The targets come from `secretWriteTargets`**, the same rule `pithy secrets create` and
+ * `mintDeclaredSecrets` ask, so a rotation cannot put a value somewhere an update would not — and a
+ * `global` secret narrowed with `--env` is refused here for the same reason it is there, before anything
+ * is rolled.
+ *
+ * The audit line is `secrets/rotated`, matching what `pithy secrets update` already emits for the same
+ * act, and it carries the name and the environments and nothing else. `unchanged` records nothing: a
+ * trail that logs a rotation for a secret nothing touched is a trail that cannot be read.
+ *
+ * **The rotation ledger is a second record, and not a duplicate of that one.** The audit trail answers
+ * *who did what, across the project*; `pithy_secrets_rotations` answers *when was this secret last
+ * replaced*, in the environment holding it, and it is what `lastRotatedAt` and every overdue report are
+ * read from. `#379` is what it looks like when only the first is written: the command succeeds, the trail
+ * records a rotation, and the product goes on telling the operator the secret is overdue. The ledger is
+ * built here and handed to the core, which opens the row before the roll — see
+ * `@pithy-sh/secrets`' `cli/rotationLedger.ts`.
+ */
+export async function runSecretRotation(
+  registry: SecretRegistry,
+  dispatcher: SecretRotationDispatcher,
+  command: SecretRotateCommand,
+  audit: CliAuditEmit = async () => {},
+): Promise<SecretRotationOutcome> {
+  const entry = requireEntry(registry, command.name);
+  // A keyspace has no single value; the core says so too, but asking the routing rule first would raise a
+  // less useful refusal about environments. Left to the core, which names the right thing.
+  const targets = entry.keyed
+    ? []
+    : secretWriteTargets({
+        name: command.name,
+        backend: entry.backend,
+        scope: entry.scope,
+        mode: "update",
+        requested: command.env,
+        declared: command.environments,
+      });
+
+  const outcome = await rotateSecretValue({
+    name: command.name,
+    entry,
+    targets,
+    ledger: dispatchedRotationLedger(dispatcher, { targets }),
+    store: ({ env, value }) =>
+      dispatcher.dispatch({
+        env,
+        mode: "update",
+        name: command.name,
+        value,
+        valueType: entry.valueType,
+        rotatable: entry.rotatable,
+      }),
+    ...(command.attempts !== undefined ? { attempts: command.attempts } : {}),
+    ...(command.sleep !== undefined ? { sleep: command.sleep } : {}),
+    ...(command.dryRun !== undefined ? { dryRun: command.dryRun } : {}),
+  });
+
+  if (outcome.status !== "unchanged") {
+    await audit({
+      action: "secrets/rotated",
+      outcome: outcome.status === "rotated" ? "success" : "failure",
+      // The unrecorded state is the one administrative act in this command that leaves a system broken,
+      // so it is the one that reads as `critical` in a trail somebody scans after an incident.
+      severity: outcome.status === "unrecorded" ? "critical" : "warning",
+      resourceType: "secret",
+      resourceId: command.name,
+      metadata: {
+        name: command.name,
+        environments: outcome.recorded,
+        rotation: outcome.kind,
+        rolled: outcome.rolled,
+        // The trail is what an incident review reads, and *was rolled* against *may have been rolled* is
+        // the fact that review turns on. Recorded rather than left to be inferred from the absence of
+        // environments, which is the same information only if somebody knows to look for it.
+        ...(outcome.rollFailed === undefined ? {} : { rollFailed: outcome.rollFailed }),
+        ...(outcome.stranded.length > 0 ? { stranded: outcome.stranded } : {}),
+      },
+    });
+  }
+  return outcome;
+}
+
+/** The issuer a `provider` or `manual` secret names, for a sentence that has to say where. */
+function issuerOf(entry: SecretRegistryEntry): string {
+  return entry.rotation !== undefined && entry.rotation.kind !== "local" ? entry.rotation.issuer : "its issuer";
+}
+
+/** The page a `provider` or `manual` secret names, when it names one. */
+function documentationOf(entry: SecretRegistryEntry): string | undefined {
+  return entry.rotation !== undefined && entry.rotation.kind !== "local" ? entry.rotation.documentation : undefined;
+}
+
+/** `pithy secrets update <NAME> --env <env>` — the command that records a value a human obtained. */
+function updateCommand(name: string, env: ManagedEnvironment | undefined): string {
+  return `pithy secrets update ${name}${env === undefined ? "" : ` --env ${env}`}`;
+}
+
+/**
+ * The lines an operator reads, one per outcome, on stdout.
+ *
+ * **The word "rotated" appears only where a new value is stored**, and never on a run that rolled and
+ * lost it. Everything else is said plainly: what was replaced, where it landed, and where it did not.
+ */
+export function rotationReportLines(
+  entry: SecretRegistryEntry,
+  outcome: SecretRotationOutcome,
+  env: ManagedEnvironment | undefined,
+): string[] {
+  const issuer = issuerOf(entry);
+  const documentation = documentationOf(entry);
+  switch (outcome.status) {
+    case "rotated":
+      return [
+        outcome.rolled
+          ? `${outcome.name} rolled at ${issuer} and recorded in ${outcome.recorded.join(", ")}.`
+          : `${outcome.name} rotated in ${outcome.recorded.join(", ")}.`,
+      ];
+    case "unchanged":
+      if (outcome.reason === "manual") {
+        return [
+          `${outcome.name} is replaced by a human at ${issuer}. Nothing was called.`,
+          ...(documentation === undefined ? [] : [documentation]),
+          `Record the new value with ${updateCommand(outcome.name, env)}.`,
+        ];
+      }
+      return [
+        outcome.kind === "provider"
+          ? `${outcome.name} would be rolled at ${issuer}, then written to ${outcome.stranded.join(", ")}.`
+          : `${outcome.name} would be minted here, then written to ${outcome.stranded.join(", ")}.`,
+      ];
+    case "unrecorded":
+      // **The rotator threw, so `rolled` is a guess and the line says so.** The call reached the issuer and
+      // the answer did not come back; nothing here can tell a request that never landed from a response
+      // that was lost, and claiming either is wrong half the time about the fact being acted on.
+      if (outcome.rollFailed) {
+        return [
+          `${outcome.name} may have been rolled at ${issuer}. Nothing was recorded.`,
+          `Check ${issuer} before running this again.`,
+        ];
+      }
+      return [
+        outcome.recorded.length > 0
+          ? `${outcome.name} rolled at ${issuer} and recorded in ${outcome.recorded.join(", ")}.`
+          : `${outcome.name} rolled at ${issuer} and recorded nowhere.`,
+        `${outcome.stranded.join(", ")} still holds a credential ${issuer} has retired.`,
+      ];
+    case "failed":
+      return outcome.recorded.length > 0
+        ? [
+            `${outcome.name} rotated in ${outcome.recorded.join(", ")}.`,
+            `${outcome.stranded.join(", ")} refused the write, and still holds the previous value.`,
+          ]
+        : [`${outcome.name} was not rotated. Nothing was rolled and nothing was written.`];
+  }
+}
+
+/**
+ * The unrecorded state as a throwable failure: its own code, the secret and the issuer in `message`, and
+ * an action line that names the console and the command.
+ *
+ * **The action is the whole point of the declaration.** #322 put an issuer and a documentation URL on
+ * every non-`local` rotation precisely so this sentence could be written from the registry rather than
+ * guessed — the operator holding a dead credential should not also have to work out whose console it is.
+ *
+ * The `cause` is attached but never rendered into `message`: what the store said belongs in `detail`,
+ * which the HTTP codec strips, and the operator's own remedy belongs in front of them.
+ */
+export function unrecordedFailure(
+  entry: SecretRegistryEntry,
+  outcome: SecretRotationOutcome,
+  env: ManagedEnvironment | undefined,
+): SecretRotationUnrecordedError {
+  const issuer = issuerOf(entry);
+  const documentation = documentationOf(entry);
+  const where = outcome.stranded.join(", ");
+  const page = documentation === undefined ? "" : ` ${documentation}`;
+  // The rotator never answered, so whether the credential moved is unknown — and the remedy starts with
+  // finding out, not with rolling again. Rolling again on an issuer that already rolled produces a second
+  // orphan; the check is the step that difference costs.
+  if (outcome.rollFailed) {
+    return new SecretRotationUnrecordedError(
+      {
+        message: `${outcome.name} may have been rolled at ${issuer}, and nothing was recorded. ${where} may be holding a retired credential.`,
+        // Careful about what it claims. The rotator threw, so whether this process ever held the value is
+        // itself unknown — "the value is gone" would be a second guess stacked on the first. What is known
+        // is that nothing recorded one, and that is what the sentence says.
+        action: `Check at ${issuer} whether a new credential was issued. If one was, nothing here recorded it — take the value from ${issuer} and record it with ${updateCommand(outcome.name, env)}. If none was, run this again.${page}`,
+        detail: `rotate '${outcome.name}': rotator failed, nothing stored in [${where}] — ${describeCause(outcome.cause)}`,
+      },
+      { cause: outcome.cause },
+    );
+  }
+  return new SecretRotationUnrecordedError(
+    {
+      message: `${outcome.name} was rolled at ${issuer} and its new value was not stored. ${where} holds a credential ${issuer} has retired.`,
+      // Said outright, because the alternative reading — that the value is sitting somewhere recoverable —
+      // is the one an operator will assume, and acting on it wastes the minutes that matter.
+      action: `The new value is gone. It existed only in this process, and printing it would leave a live credential in your shell history. Roll it again at ${issuer}, then record it with ${updateCommand(outcome.name, env)}.${page}`,
+      detail: `rotate '${outcome.name}': rolled, recorded in [${outcome.recorded.join(", ")}], not recorded in [${where}] after ${outcome.attempts ?? 0} store attempts — ${describeCause(outcome.cause)}`,
+    },
+    { cause: outcome.cause },
+  );
+}
+
+/** What ended the store attempt, for `detail` only. Never a value — the store is given one, never asked for one. */
+function describeCause(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  return cause === undefined ? "no cause recorded" : String(cause);
+}

package/src/capabilities/secrets.ts

@@ -0,0 +1,178 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { NotFoundError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { isSecretsCapability } from "@pithy-sh/secrets/src/capability";
+import { type AuditResult, auditSecrets, passesPromoteGate } from "@pithy-sh/secrets/src/cli/audit";
+import {
+  dispatchSecretWrite,
+  environmentsWrittenBeforeFailure,
+  type SecretDispatcher,
+} from "@pithy-sh/secrets/src/cli/dispatch";
+import { validateSecretValue } from "@pithy-sh/secrets/src/cli/validate";
+import { parseKeyedSecretName } from "@pithy-sh/secrets/src/keyspace";
+import type { SecretRegistry } from "@pithy-sh/secrets/src/registry";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import { allCapabilities, type WorkerConfig } from "../project/config";
+
+/** The audit action for a value-touching secret command, by mode. Never carries the secret's value. */
+const SECRET_WRITE_ACTION: Record<SecretWriteCommand["mode"], string> = {
+  create: "secrets/set",
+  update: "secrets/rotated",
+  delete: "secrets/removed",
+};
+
+/**
+ * Discover a Worker's secret registry by finding the secrets capability in its loaded
+ * `apps/<name>/pithy.config.ts` (#25's config model). The capability carries its own registry, so there
+ * is no separate loading convention — the CLI reads what the Worker reads. Capabilities are per-Worker,
+ * so the registry is too: a caller spanning several Workers resolves each and merges by secret name
+ * (the name is the join key).
+ */
+export function resolveSecretRegistry(config: WorkerConfig): SecretRegistry {
+  const capability = allCapabilities(config).find(isSecretsCapability);
+  if (!capability) {
+    throw new NotFoundError({
+      message: "The secrets capability isn't enabled in this worker.",
+      action: "Add secrets({ registry }) to the worker's pithy.config.ts capabilities, or pass --worker.",
+    });
+  }
+  return capability.secretRegistry;
+}
+
+/**
+ * The brains of `pithy secrets` — pure wiring over the `@pithy-sh/secrets` cores, with the registry
+ * and dispatcher injected so it is fully testable. The citty command (`commands/secrets.ts`) handles
+ * I/O — value capture, registry discovery, building the live dispatcher — and calls these.
+ */
+
+export interface SecretWriteCommand {
+  mode: "create" | "update" | "delete";
+  name: string;
+  /** The raw value for create/update (omitted for delete) — validated client-side here. */
+  value?: string;
+  /**
+   * The environment the operator named with `--env`, or `undefined` when they named none.
+   *
+   * **Not defaulted, and that is load-bearing.** A missing `--env` on a `global` secret used to be
+   * resolved to the canonical environment before this was called, which made *narrow this write to
+   * staging* and *say nothing* indistinguishable by the time anything could refuse either.
+   * `secretWriteTargets` refuses on exactly that difference, so the absence has to reach it.
+   */
+  env: ManagedEnvironment | undefined;
+  /**
+   * Every environment the project declares, from the root `pithy.config.ts` (#241) — the set a `global`
+   * secret fans out across, and the one the canonical CF-Secrets-Store write is chosen from.
+   *
+   * Beside `env` rather than defaulted, because a default would be the silence this replaced: a project
+   * declaring `live` would have its shared secrets written to staging and prod and not to `live`, and
+   * nothing would say so.
+   */
+  environments: DeclaredEnvironments | readonly string[];
+}
+
+/**
+ * Validate a value client-side (the authoritative A2 check) and dispatch the write to the manager
+ * Workflow(s). The registry lookup gives the routing facts (backend, scope) and the schema; an
+ * undeclared secret is rejected before anything is sent. Returns the environments written.
+ *
+ * Audited on success and on failure — `secrets/set` (create), `secrets/rotated` (update), or
+ * `secrets/removed` (delete) — recording only the secret's **name** and the environments it reached.
+ * The value itself, and anything derived from it, never appears in an audit event: that is the one
+ * hard rule of a secrets trail.
+ */
+export async function runSecretWrite(
+  registry: SecretRegistry,
+  dispatcher: SecretDispatcher,
+  command: SecretWriteCommand,
+  audit: CliAuditEmit = async () => {},
+): Promise<ManagedEnvironment[]> {
+  const entry = registry[command.name];
+  if (!entry) {
+    throw new NotFoundError({
+      message: `Secret '${command.name}' is not declared in the registry.`,
+      action: "Add it to your secret registry, then run this again.",
+    });
+  }
+
+  // A keyspace has no single value to write, and a write under its bare name would land somewhere no
+  // member read ever looks. Its members belong to the app that mints them, which writes them in-worker.
+  if (entry.keyed) {
+    throw new ValidationError({
+      message: `Secret '${command.name}' is a keyspace, not a secret.`,
+      action: "Its members are written by the application that owns them, one key at a time.",
+    });
+  }
+
+  let value: string | undefined;
+  if (command.mode !== "delete") {
+    if (command.value === undefined || command.value === "") {
+      throw new ValidationError({ message: `A value is required to ${command.mode} '${command.name}'.` });
+    }
+    value = validateSecretValue(entry, command.name, command.value);
+  }
+
+  const action = SECRET_WRITE_ACTION[command.mode];
+  try {
+    const targets = await dispatchSecretWrite(
+      dispatcher,
+      {
+        mode: command.mode,
+        name: command.name,
+        backend: entry.backend,
+        scope: entry.scope,
+        rotatable: entry.rotatable,
+        valueType: entry.valueType,
+        value,
+        requested: command.env,
+      },
+      command.environments,
+    );
+    await audit({
+      action,
+      outcome: "success",
+      severity: "warning",
+      resourceType: "secret",
+      resourceId: command.name,
+      metadata: { name: command.name, environments: targets },
+    });
+    return targets;
+  } catch (error) {
+    // **The environments it reached before it failed, not none of them.** This recorded the name alone,
+    // so a `global` fan-out that half-completed left a trail saying a write failed and nothing saying
+    // which environments now hold the new value — for `pithy secrets rm`, which environments no longer
+    // hold a live key. A refusal reaches this with an empty list, which is true: nothing was sent.
+    await audit({
+      action,
+      outcome: "failure",
+      severity: "warning",
+      resourceType: "secret",
+      resourceId: command.name,
+      metadata: { name: command.name, environments: environmentsWrittenBeforeFailure(error) },
+    });
+    throw error;
+  }
+}
+
+/** The `ls` / `ls --check` view: the declared names (keyspaces included), the audit, and the gate. */
+export interface SecretsListView {
+  names: string[];
+  audit: AuditResult;
+  promotable: boolean;
+}
+
+export function runSecretsList(registry: SecretRegistry, presentNames: string[]): SecretsListView {
+  const names = Object.keys(registry).sort();
+  // A keyspace is expected to have no value of its own, and its stored members are expected to have no
+  // registry entry of their own. Counting either would make the promote gate unpassable the day an
+  // adopter declares their first per-tenant credential, and would report every tenant as junk.
+  const expected = names.filter((name) => !registry[name]?.keyed);
+  const present = presentNames.filter((stored) => {
+    const member = parseKeyedSecretName(stored);
+    return !(member && registry[member.name]?.keyed);
+  });
+  const audit = auditSecrets(expected, present);
+  return { names, audit, promotable: passesPromoteGate(audit) };
+}

package/src/capabilities/secretsDispatcher.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareWorkflowsClient } from "@pithy-sh/cloudflare/src/workflows/workflowsClient";
+import type { SecretDispatcher, SecretProbe, SecretRotationRecorder } from "@pithy-sh/secrets/src/cli/dispatch";
+import { WorkflowSecretDispatcher } from "@pithy-sh/secrets/src/manager/dispatcher";
+
+/**
+ * Build the live secrets dispatcher every value-touching command writes through — the manager
+ * write-Workflow over the CF Workflows REST API, keyed by the canonical `<project>-<env>-secrets-write`
+ * Workflow name. Shared by `pithy secrets`, `pithy turnstile`, `pithy storage`, and `pithy media` so the
+ * dispatch wiring lives in exactly one place.
+ *
+ * `project` is the root `pithy.config.ts` `name` via `requireProjectName`, never a guess. Workflow names
+ * are account-scoped: a wrong project here dispatches this project's secret values into another
+ * project's manager, which encrypts and stores them under a master key this project cannot read.
+ *
+ * It is also the {@link SecretProbe} — the read seam provisioning asks before it mints anything — and the
+ * {@link SecretRotationRecorder}, the rotation ledger `pithy secrets rotate` opens a row in before it rolls
+ * (`#379`). All three contracts land on the same Workflow, so the same one object answers them, and a
+ * caller cannot end up probing or recording against one project's manager while writing to another's.
+ */
+export function buildSecretDispatcher(
+  accountId: string,
+  apiToken: string,
+  project: string,
+): SecretDispatcher & SecretProbe & SecretRotationRecorder {
+  return new WorkflowSecretDispatcher(new CloudflareWorkflowsClient({ accountId, apiToken }), project);
+}