@pithy-sh/core 0.9.0 → 0.11.0

package/dist/capability/settings.d.ts

@@ -1,6 +1,7 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
 import { z } from "zod";
+import { InternalError } from "../error/pithyError";
 import type { HostEnvReport } from "../workflow/hostEnv";
 /**
  * How a capability checks that its own settings **work** — the seam `pithy doctor` runs (#411).
@@ -45,6 +46,7 @@ export declare const SettingsFinding: z.ZodObject<{
     environment: z.ZodNullable<z.ZodString>;
     problem: z.ZodString;
     action: z.ZodString;
+    fix: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SettingsFinding = z.infer<typeof SettingsFinding>;
 /** One environment the project declares, and what this Worker's own config says about it. */
@@ -63,8 +65,15 @@ export interface SettingsEnvironment {
 export interface SettingsCheckContext {
     /** The root config's `name` — the leading segment of every resource this project provisions. */
     project: string;
-    /** The Worker whose `pithy.config.ts` composed this capability. */
+    /** The Worker whose `pithy.config.ts` composed this capability, by its `wrangler.jsonc` name. */
     worker: string;
+    /**
+     * That Worker's directory under `apps/` — the value `--worker` takes, and the one a refusal lists (#711).
+     *
+     * Not `worker` under another name. A scaffold deploys `apps/api` as `acme-api`, so a command a finding names
+     * for one Worker is written with this.
+     */
+    workerDirectory: string;
     /** Every environment the project declares, in declaration order. */
     environments: readonly SettingsEnvironment[];
 }
@@ -73,8 +82,8 @@ export interface SettingsCheckContext {
  *
  * Closed for the reason `CapabilityHealth` is: handing a capability a raw Cloudflare client would make
  * every capability a place a network call can be invented, and would put `@pithy-sh/cloudflare` in the
- * dependency list of packages that need none of it. Three questions cover what the first checks ask; a
- * fourth lands here, once, when a capability actually needs it.
+ * dependency list of packages that need none of it. A question lands here once a capability actually needs
+ * it, and not before: six cover what the checks ask.
  *
  * Every method may throw. A throw is the account failing to answer, and the runner reports that
  * capability's account tier as unchecked rather than as a pass.
@@ -102,12 +111,84 @@ export interface SettingsAccountReader {
      * created it with, so the check looks where the value went.
      */
     storeEntry(name: string): Promise<boolean>;
+    /**
+     * The ids of the rows in one of the kit's own tables whose column holds one of `values`, in the app
+     * database a Worker binds as `DB` in one deployed environment (#727).
+     *
+     * Asked by media and storage after a project narrows `visibility.allowed`: narrowing never rewrites a
+     * record, so the records left outside the policy have to be *named*, and only the deployed database
+     * holds them. Closed in its own way — the table must be a `pithy_` one and the column an identifier,
+     * both refused otherwise, and the values are bound, never interpolated — so it reads a fact about a
+     * capability's own rows and cannot become a query language.
+     */
+    appRows(request: AppRowsRequest): Promise<readonly string[]>;
+    /**
+     * Whether that environment's **D1 vault** holds a `json` secret that still carries a top-level `field` —
+     * asked of its manager Worker, which opens the value and answers a bit, never the value (#728). `false`
+     * for a secret that is not stored, since it carries nothing.
+     *
+     * Asked by media of `media-storage-credentials`, which held a supplied Cloudflare token until the runtime
+     * token replaced it: the upgrade is finished only once the bundle has been rewritten without it.
+     */
+    vaultSecretField(request: {
+        name: string;
+        environment: string;
+        field: string;
+    }): Promise<boolean>;
+    /**
+     * Whether the account holds a Cloudflare API token of exactly this name (#728). The name is the token's,
+     * composed with the namer that minted it — never a pattern, so a check names one credential it can see.
+     *
+     * Asked by secrets of the manager token the runtime token superseded, which nothing revokes for you.
+     */
+    accountToken(name: string): Promise<boolean>;
+}
+/** What {@link SettingsAccountReader.appRows} is asked. */
+export interface AppRowsRequest {
+    /** The deployed environment whose app database is read. `dev` is refused: it has no deployed database. */
+    readonly environment: string;
+    /** The Worker's `apps/` directory — whose `wrangler.jsonc` names the database for that environment. */
+    readonly workerDirectory: string;
+    /** The kit table, as it is named in SQL — `pithy_media_assets`. Must carry the `pithy_` prefix. */
+    readonly table: string;
+    /** The column compared, as it is named in SQL — `visibility`. */
+    readonly column: string;
+    /** The values that make a row worth naming. */
+    readonly values: readonly string[];
 }
 /** What the account tier is told: everything the local tier gets, plus the account it may ask. */
 export interface SettingsAccountContext extends SettingsCheckContext {
     /** The account, as the closed set of questions above. */
     account: SettingsAccountReader;
 }
+/** One environment an account check could not answer for, and why. */
+export interface UnansweredEnvironment {
+    /** The environment id. */
+    readonly environment: string;
+    /** What the account, or the project, said instead of an answer. */
+    readonly cause: unknown;
+}
+/**
+ * An account check that answered for some environments and not for others.
+ *
+ * A check that asks per environment must not let one unanswerable environment cost the others their
+ * findings: staging stood up before prod is the ordinary bring-up, and a check that threw on prod's missing
+ * database would throw away what it had already found in staging. So it collects what it can, and throws
+ * this at the end carrying those findings. The runner reports them as findings and the tier as unchecked,
+ * both — a fault and an unanswered question are two facts, and neither hides the other.
+ */
+export declare class SettingsAccountIncomplete extends InternalError {
+    /** What the environments that did answer were found to have wrong. */
+    readonly findings: readonly SettingsFinding[];
+    /** The environments that did not answer, in the order they were asked. */
+    readonly unanswered: readonly string[];
+    constructor(findings: readonly SettingsFinding[], unanswered: readonly UnansweredEnvironment[]);
+}
+/**
+ * The findings an account check reached before it threw — none for an ordinary throw, and what it had
+ * collected for a {@link SettingsAccountIncomplete}.
+ */
+export declare function settingsFindingsBefore(error: unknown): readonly SettingsFinding[];
 /**
  * A capability's settings check, as it hangs off the capability.
  *
@@ -121,6 +202,17 @@ export interface CapabilitySettings {
     /** The half that costs a Cloudflare call. Omitted where a capability has nothing to ask the account. */
     account?(context: SettingsAccountContext): Promise<SettingsFinding[]>;
 }
+/**
+ * **Two or more checks on one capability, as the one `settings` it declares (#728).** Media names records a
+ * narrowed visibility no longer admits and a bundle still holding a superseded token: two questions, one
+ * capability, one seam.
+ *
+ * Each tier runs every check's, in declaration order. A check that could not answer for some environments
+ * costs those environments and nothing else: the others' findings are kept, and the run ends in one
+ * {@link SettingsAccountIncomplete} carrying every finding and every unanswered environment. A check that
+ * throws outright is unanswered for every environment the context declares.
+ */
+export declare function allSettings(...checks: readonly CapabilitySettings[]): CapabilitySettings;
 /**
  * Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
  *
@@ -128,7 +220,7 @@ export interface CapabilitySettings {
  * import("../workflow/hostEnv").checkHostEnv} against its own declaration, and hands the report here. The
  * problem line is Zod's own message and the action line is {@link hostEnvProviderSentence} — the same
  * words the host writes into its log before it refuses to start. Two readers of one declaration, and no
- * second wording to drift.
+ * second wording to drift. A provider that names a command carries it as `fix` too.
  */
 export declare function hostEnvFindings(report: HostEnvReport<unknown>, environment: string | null): SettingsFinding[];
 //# sourceMappingURL=settings.d.ts.map

package/dist/capability/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/capability/settings.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,mFAAmF;AACnF,eAAO,MAAM,eAAe;;;;;iBA0B+D,CAAC;AAC5F,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,6FAA6F;AAC7F,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,4GAA4G;AAC5G,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,WAAW,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC1C,+GAA+G;IAC/G,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED,kGAAkG;AAClG,MAAM,WAAW,sBAAuB,SAAQ,oBAAoB;IAClE,yDAAyD;IACzD,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,KAAK,CAAC,OAAO,EAAE,oBAAoB,GAAG,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACrF,wGAAwG;IACxG,OAAO,CAAC,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CACvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,eAAe,EAAE,CAO7G"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/capability/settings.ts"],"names":[],"mappings":"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"}

package/dist/capability/settings.js

@@ -1,5 +1,6 @@
 // SPDX-FileCopyrightText: 2026 Pithy
 // SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
 import { hostEnvProviderSentence } from "../workflow/hostEnv.js";
 import { z } from "zod";
 //#region src/capability/settings.ts
@@ -45,24 +46,104 @@ const SettingsFinding = z.object({
 	setting: z.string().min(1).describe("What is wrong — the env field, config key, or account resource, spelled as the operator would find it. It leads the line, so it is the name they search for."),
 	environment: z.string().min(1).nullable().describe("The environment this is about, or `null` where the setting is the same in all of them. A per-environment fault is reported once per environment, because that is how many edits it takes."),
 	problem: z.string().min(1).describe("Why it does not work, in one sentence. The problem line, in the same voice every PithyError uses."),
-	action: z.string().min(1).describe("What resolves it: the `pithy` command, the `pithy.config.ts` key, or the one-time account action. Never optional — a finding nobody can act on is a complaint.")
+	action: z.string().min(1).describe("What resolves it: the `pithy` command, the `pithy.config.ts` key, or the one-time account action. Never optional — a finding nobody can act on is a complaint."),
+	fix: z.string().min(1).optional().describe("The `pithy` command that resolves it, whole and runnable as written, when one does. Absent when the remedy is an edit or an account action, and from a capability older than the field — `pithy doctor --json` reports either as `fix: null`.")
 }).describe("One capability setting that does not work, with the action that resolves it.");
 /**
+* An account check that answered for some environments and not for others.
+*
+* A check that asks per environment must not let one unanswerable environment cost the others their
+* findings: staging stood up before prod is the ordinary bring-up, and a check that threw on prod's missing
+* database would throw away what it had already found in staging. So it collects what it can, and throws
+* this at the end carrying those findings. The runner reports them as findings and the tier as unchecked,
+* both — a fault and an unanswered question are two facts, and neither hides the other.
+*/
+var SettingsAccountIncomplete = class extends InternalError {
+	/** What the environments that did answer were found to have wrong. */
+	findings;
+	/** The environments that did not answer, in the order they were asked. */
+	unanswered;
+	constructor(findings, unanswered) {
+		const reasons = unanswered.map(({ environment, cause }) => `${environment}: ${describeCause(cause)}`).join("; ");
+		super({
+			message: `The account check could not answer for ${unanswered.map(({ environment }) => environment).join(", ")}.`,
+			detail: reasons
+		}, { cause: unanswered[0]?.cause });
+		this.findings = findings;
+		this.unanswered = unanswered.map(({ environment }) => environment);
+	}
+};
+/** A cause, as one line. */
+function describeCause(cause) {
+	return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+* The findings an account check reached before it threw — none for an ordinary throw, and what it had
+* collected for a {@link SettingsAccountIncomplete}.
+*/
+function settingsFindingsBefore(error) {
+	return error instanceof SettingsAccountIncomplete ? error.findings : [];
+}
+/**
+* **Two or more checks on one capability, as the one `settings` it declares (#728).** Media names records a
+* narrowed visibility no longer admits and a bundle still holding a superseded token: two questions, one
+* capability, one seam.
+*
+* Each tier runs every check's, in declaration order. A check that could not answer for some environments
+* costs those environments and nothing else: the others' findings are kept, and the run ends in one
+* {@link SettingsAccountIncomplete} carrying every finding and every unanswered environment. A check that
+* throws outright is unanswered for every environment the context declares.
+*/
+function allSettings(...checks) {
+	const accounts = checks.flatMap((check) => check.account ? [check.account.bind(check)] : []);
+	return {
+		async local(context) {
+			const findings = [];
+			for (const check of checks) findings.push(...await check.local(context));
+			return findings;
+		},
+		...accounts.length === 0 ? {} : { async account(context) {
+			const findings = [];
+			const unanswered = [];
+			for (const account of accounts) try {
+				findings.push(...await account(context));
+			} catch (cause) {
+				findings.push(...settingsFindingsBefore(cause));
+				if (cause instanceof SettingsAccountIncomplete) {
+					for (const environment of cause.unanswered) if (!unanswered.some((entry) => entry.environment === environment)) unanswered.push({
+						environment,
+						cause: cause.cause ?? cause
+					});
+					continue;
+				}
+				if (context.environments.length === 0) throw cause;
+				for (const { name } of context.environments) if (!unanswered.some((entry) => entry.environment === name)) unanswered.push({
+					environment: name,
+					cause
+				});
+			}
+			if (unanswered.length > 0) throw new SettingsAccountIncomplete(findings, unanswered);
+			return findings;
+		} }
+	};
+}
+/**
 * Turn a host env's own parse report into findings — the bridge that makes "one schema, two readers" real.
 *
 * A capability's local tier builds the env its host *would* be handed, runs {@link
 * import("../workflow/hostEnv").checkHostEnv} against its own declaration, and hands the report here. The
 * problem line is Zod's own message and the action line is {@link hostEnvProviderSentence} — the same
 * words the host writes into its log before it refuses to start. Two readers of one declaration, and no
-* second wording to drift.
+* second wording to drift. A provider that names a command carries it as `fix` too.
 */
 function hostEnvFindings(report, environment) {
 	return report.problems.map((problem) => ({
 		setting: problem.field,
 		environment,
 		problem: problem.reason,
-		action: hostEnvProviderSentence(problem.provider)
+		action: hostEnvProviderSentence(problem.provider),
+		...problem.provider.command === void 0 ? {} : { fix: problem.provider.command }
 	}));
 }
 //#endregion
-export { SettingsFinding, hostEnvFindings };
+export { SettingsAccountIncomplete, SettingsFinding, allSettings, hostEnvFindings, settingsFindingsBefore };

package/dist/cli/command.d.ts

@@ -0,0 +1,364 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import type { DEFAULT_ENVIRONMENTS, LOCAL_ENVIRONMENT } from "../naming/environment";
+import { COMMANDS, GROUPS } from "./commandCatalog.generated";
+import { CONFIRM_FLAGS, type DestructiveFlag, type DestructivePath, EVERY_ENVIRONMENT_ALWAYS, MEANING_FLAGS, MEANING_ONLY_WITH, PRODUCTION_ENVIRONMENTS, type ProductionPath, type WorkerScopedPath } from "./commandFacts";
+/**
+ * **The one place a `pithy` command line is spelled (#711).**
+ *
+ * #697 held every `fix` to one rule: it runs as written. The sentences beside it were held to nothing, and three
+ * review rounds each found new ones that did not run — a `--worker` dropped, an `--env` left to default to `dev`,
+ * a placeholder an agent pasted verbatim, a command that destroyed far more than the fault it was offered for.
+ * Every one was a command spelled by hand at its own site, so every fix was one site, and the next site was
+ * still spelled by hand.
+ *
+ * So no site spells one. A line that names a command gets it from here, and this module knows the tree
+ * (`commandCatalog.generated.ts`, projected from the CLI's own parser) and the facts the parser cannot state
+ * (`commandFacts.ts`). It refuses to build:
+ *
+ * - **a command that does not exist**, or a flag the command does not declare — at compile time for a literal
+ *   path, at run time for one assembled from a capability's name;
+ * - **a command missing a flag it needs**: one the parser requires, one a rule over several flags requires, an
+ *   `--env` whose default would change what the command acts on, or the `--worker` a command acting on one
+ *   Worker is refused without — and `--worker` takes a {@link WorkerDir}, the Worker's `apps/` directory, never
+ *   its deployed script name;
+ * - **a command that destroys something**, or a production provision. Those are a person's decision, and
+ *   {@link personDecision} says so in a sentence that carries no command an agent would run.
+ *
+ * ## A builder reached at run time never throws because of data
+ *
+ * Every refusal above is about what **the program spells** — a command path, a flag name, an enum choice, the
+ * shape of the line — and a value is one of two kinds:
+ *
+ * - **Spelled by the program**: the path, each flag's name, a choice from a flag's fixed set, a Worker directory
+ *   (a {@link WorkerDir}, which only {@link workerDirOf} makes). These are checked, at compile time where the path
+ *   is a literal.
+ * - **Supplied by a caller**: a `--set` value, a secret's name, free text, anything a run read. These are
+ *   shell-quoted as they are and never checked — `fromName=Acme <hi@acme.io>` is a value, not a placeholder, and a
+ *   builder that read it as one turned `pithy add email` into `core/internal` after it had installed the package
+ *   (#711). A `<placeholder>` is a fault of **spelling**, so the place that refuses one is the gate that reads
+ *   spellings, `packages/cli/src/ci/runnableCommands.test.ts`, which reads every literal handed to a builder too.
+ *
+ * So whether a line is a person's decision never turns on a value at run time either. An environment a run reads —
+ * a deployed Worker's `ENVIRONMENT`, a caller's `--env` — is data: {@link pithyCommand} takes no `--env` on a
+ * command a production run makes a person's decision except a literal non-production one, {@link pithyCommandOf}
+ * takes none there at all, and a line that names one it read is {@link remedy}'s or {@link rerunRemedy}'s, which
+ * say a production one as a person's decision. {@link personDecision} takes only a command or flag that destroys
+ * something, which is shape. What is left to throw is a program that spelled a line wrong, every time it runs.
+ *
+ * `packages/cli/src/ci/runnableCommands.test.ts` reads every string in every package's shipped source and fails
+ * on a `pithy …` spelled anywhere but here, wherever it sits in the sentence.
+ */
+type Catalog = typeof COMMANDS;
+/** A command the CLI runs, as typed after `pithy`. */
+export type CommandPath = keyof Catalog;
+/** A group, which only lists its subcommands. A sentence may name one in prose. */
+export type GroupPath = (typeof GROUPS)[number];
+declare const WORKER_DIR: unique symbol;
+/**
+ * **A Worker as `--worker` takes it: its `apps/` directory.** Branded, so the deployed script name — a `string`
+ * every Worker also carries — cannot be passed where this is wanted. Made by {@link workerDirOf} from the
+ * Worker's directory.
+ */
+export type WorkerDir = string & {
+    readonly [WORKER_DIR]: true;
+};
+/**
+ * The Worker a directory holds, as `--worker` names it: the directory's own name. Takes the directory rather
+ * than a name, because a name in hand is as often the deployed script name, which `--worker` does not resolve.
+ */
+export declare function workerDirOf(worker: {
+    readonly dir: string;
+}): WorkerDir;
+declare const BUILT: unique symbol;
+/** A command line this module built, and so one that runs as written. The only thing a `fix` may carry. */
+export type Command = string & {
+    readonly [BUILT]: true;
+};
+type FlagDefs<P extends CommandPath> = Catalog[P]["flags"];
+type FlagName<P extends CommandPath> = Extract<keyof FlagDefs<P>, string>;
+type ConfirmFlag = (typeof CONFIRM_FLAGS)[number];
+type MeaningFlag = (typeof MEANING_FLAGS)[number];
+/**
+ * An environment no project's production run is: the local one, and the deployed one that is not `prod`. The only
+ * `--env` a literal line may give a command whose production run is a person's decision — so it is spelled, never
+ * read, and an environment a run read goes through {@link remedy}, which decides by its value.
+ */
+export type QuietEnvironment = typeof LOCAL_ENVIRONMENT | Exclude<(typeof DEFAULT_ENVIRONMENTS)[number], (typeof PRODUCTION_ENVIRONMENTS)[number]>;
+/**
+ * The value one flag takes: `true` for a boolean, a {@link WorkerDir} for `--worker`, one of a fixed set's choices,
+ * a {@link QuietEnvironment} for the `--env` of a command a production run makes a person's decision, else a string.
+ */
+type FlagValue<P, D, F> = F extends "--worker" ? WorkerDir : D extends {
+    type: "boolean";
+} ? true : F extends "--env" ? P extends ProductionPath ? QuietEnvironment : string : D extends {
+    enum: readonly (infer E)[];
+} ? D extends {
+    repeatable: true;
+} ? E | readonly E[] : E : D extends {
+    repeatable: true;
+} ? string | readonly string[] : string;
+/** Whether a line naming `P` must carry `F`. `add`'s Worker is its own builder's to name (`addCommand.ts`). */
+type IsNeeded<P extends CommandPath, F extends FlagName<P>> = FlagDefs<P>[F] extends {
+    required: true;
+} ? true : F extends MeaningFlag ? FlagDefs<P>[F] extends {
+    default: string;
+} ? P extends keyof typeof MEANING_ONLY_WITH ? false : true : false : F extends "--worker" ? P extends Exclude<WorkerScopedPath, "add"> ? true : false : false;
+type NeededFlag<P extends CommandPath> = {
+    [F in FlagName<P>]: IsNeeded<P, F> extends true ? F : never;
+}[FlagName<P>];
+/** The flags a line naming `P` passes: the ones it needs, and any other it declares that destroys nothing. */
+export type CommandFlags<P extends CommandPath> = {
+    [F in NeededFlag<P>]: FlagValue<P, FlagDefs<P>[F], F>;
+} & {
+    [F in Exclude<FlagName<P>, NeededFlag<P> | DestructiveFlag | ConfirmFlag>]?: FlagValue<P, FlagDefs<P>[F], F>;
+};
+type HasRequiredPositional<P extends CommandPath> = [
+    Extract<Catalog[P]["positionals"][number], {
+        required: true;
+    }>
+] extends [never] ? false : true;
+/** What a line naming `P` passes: its positional arguments, and its flags, in the order they are written. */
+export type CommandParts<P extends CommandPath> = (HasRequiredPositional<P> extends true ? {
+    args: readonly [string, ...string[]];
+} : {
+    args?: readonly string[];
+}) & ([NeededFlag<P>] extends [never] ? {
+    flags?: CommandFlags<P>;
+} : {
+    flags: CommandFlags<P>;
+});
+type PartsArgument<P extends CommandPath> = HasRequiredPositional<P> extends true ? [parts: CommandParts<P>] : [NeededFlag<P>] extends [never] ? [parts?: CommandParts<P>] : [parts: CommandParts<P>];
+/**
+ * A command that is built like any other: one that destroys nothing, and that does not act on every environment on
+ * every run — a line names that one through {@link remedy}, which says it as a person's decision.
+ */
+export type BuildablePath = Exclude<CommandPath, DestructivePath | (typeof EVERY_ENVIRONMENT_ALWAYS)[number]>;
+/** Parts as a builder holds them when the path is a value rather than a literal. */
+export interface LooseParts {
+    readonly args?: readonly string[];
+    readonly flags?: Readonly<Record<string, string | true | readonly string[] | undefined>>;
+}
+/** What {@link commandFaults} is asked to allow. */
+export interface FaultOptions {
+    /**
+     * A person's decision: a destructive command or flag, or a production run, is named for a person to choose,
+     * and the confirmation flags are theirs to add. {@link personDecision} asks for this; nothing else does.
+     */
+    readonly person?: boolean;
+    /** The project's `seed.productionEnvironments`, beyond the {@link PRODUCTION_ENVIRONMENTS} every project has. */
+    readonly productionEnvironments?: readonly string[];
+    /**
+     * A line said by a **deployed** Worker — into its own log, or to an HTTP caller — which cannot know the `apps/`
+     * directory that provisioned it. Every rule holds but `--worker`. Only the files
+     * `packages/cli/src/ci/runnableCommands.test.ts` lists as runtime lines may pass it.
+     */
+    readonly runtime?: boolean;
+    /**
+     * **Every value on the line was spelled by the program** — the gate, reading a line written in a literal — so a
+     * `<placeholder>` or a blank among them is a fault. No builder says this: a value handed to a builder is a
+     * caller's, and is shell-quoted as it is (see the module comment).
+     */
+    readonly spelled?: boolean;
+    /** Treat `<x>`, the gate's mark for interpolation, as a value rather than a placeholder. */
+    readonly interpolated?: boolean;
+}
+/**
+ * What a builder adds to {@link FaultOptions}: that every value is the caller's own run, handed back as it was
+ * given, so not even a fixed set of choices is held against it — the run's own parser has had its say.
+ */
+interface BuildOptions extends FaultOptions {
+    readonly given?: boolean;
+}
+/** Whether `path` is a command the CLI runs. */
+export declare function isCommandPath(path: string): path is CommandPath;
+/** Whether `path` is a group. */
+export declare function isGroupPath(path: string): path is GroupPath;
+/**
+ * What the catalog says about one flag of one command — its type, whether it is required, its default — or
+ * `undefined` when the command does not declare it.
+ */
+export declare function commandFlag(path: string, flag: string): {
+    readonly type: "boolean" | "string";
+    readonly required: boolean;
+    readonly default?: string;
+} | undefined;
+/**
+ * **Every reason a command line would not run as written, or would do more than a remedy may.** Empty when it
+ * runs. The builder throws on any; `runnableCommands.test.ts` holds every hand-spelled line it reads to the same
+ * function, so the gate and the builder cannot disagree about a rule.
+ */
+export declare function commandFaults(path: string, parts?: LooseParts, options?: BuildOptions): string[];
+/**
+ * **What a command does that only a person may decide**: what it deletes, or that it runs against production. Empty
+ * for a command a remedy may name.
+ */
+export declare function consequencesOf(path: string, parts?: LooseParts, options?: FaultOptions): string[];
+/**
+ * Whether `path` acts on every environment, production among them, when its `--env` is left off — `pithy testers
+ * provision` (`commandFacts.ts`'s {@link EVERY_ENVIRONMENT_WITHOUT_ENV}). A line about one environment names it.
+ */
+export declare function actsOnEveryEnvironment(path: string): boolean;
+/**
+ * Whether `path` acts on every environment, production among them, on every run, with no `--env` to narrow it —
+ * `pithy secrets provision` (`commandFacts.ts`'s {@link EVERY_ENVIRONMENT_ALWAYS}). A line naming it is a person's
+ * decision, always.
+ */
+export declare function actsOnEveryEnvironmentAlways(path: string): boolean;
+/**
+ * **A command line that runs as written**, from a literal path: the tree checks its command, its flags and the
+ * flags it needs at compile time, and {@link commandFaults} checks the rest when it is built.
+ */
+export declare function pithyCommand<P extends BuildablePath>(path: P, ...parts: PartsArgument<P>): Command;
+/** The parts of a line a deployed Worker builds: no `--env`, which it reads as data and names through {@link remedy}. */
+export interface RuntimeParts extends LooseParts {
+    readonly flags?: LooseParts["flags"] & {
+        readonly "--env"?: never;
+    };
+}
+/**
+ * **The same, from a path that is a value** — `` `${capability} provision` ``. Nothing is checked at compile
+ * time, so everything is checked here, and a path the CLI does not have is refused rather than spelled.
+ *
+ * Whether a command is a person's decision never turns on a value here. A runtime line names no `--env`: a deployed
+ * Worker's environment is data, and whether its command is a person's decision depends on it, so that line is
+ * {@link remedy}'s. Nor does any line name the `--env` of a command a production run makes a person's decision —
+ * `provision`, `seed`, `vector provision`. Each is refused for every value, so no environment is a surprise.
+ */
+export declare function pithyCommandOf(path: string, parts: RuntimeParts, options: {
+    readonly runtime: true;
+}): Command;
+export declare function pithyCommandOf(path: string, parts?: LooseParts): Command;
+/**
+ * **A command a person decides on, said as one.** For a fault whose only remedy destroys something, or runs
+ * against production: the sentence names the command, says what it does and that the choice is a person's, and
+ * leaves every confirmation flag for them to add. It returns a sentence, never a {@link Command}, so it cannot
+ * become a `fix`.
+ *
+ * It takes a command that destroys something, or a line naming a flag that does — shape, never a value. A command
+ * whose production run is a person's decision is a decision only for a production `--env`, which is data, so that
+ * line is {@link remedy}'s, which decides by the value; here it is refused for every value.
+ */
+export declare function personDecision(path: PersonPath, parts: LooseParts, options?: Pick<FaultOptions, "productionEnvironments" | "runtime">): string;
+/** A command that destroys something, or one declaring a flag that does: what {@link personDecision} takes. */
+export type PersonPath = {
+    [P in CommandPath]: P extends DestructivePath ? P : [Extract<FlagName<P>, DestructiveFlag>] extends [never] ? never : P;
+}[CommandPath];
+/** **A remedy**: the command a `fix` carries when one may, and the words a line says about it. */
+export interface Remedy {
+    /** The command, when it runs as written and a `fix` may carry it. `undefined` for a person's decision. */
+    readonly fix: Command | undefined;
+    /** The words: `wrap` around the command, or — for a person's decision — that sentence in its place. */
+    say(wrap: (command: string) => string): string;
+}
+/**
+ * **The remedy a line names**, decided by the command rather than by its site: a command a remedy may name is a
+ * `fix` and goes into the sentence; one that destroys something or runs against production is a person's
+ * decision, said as one, with no `fix`. A command that does not run is refused either way.
+ */
+export declare function remedy(path: string, parts?: LooseParts, options?: Pick<FaultOptions, "productionEnvironments" | "runtime">): Remedy;
+declare const CALLER: unique symbol;
+/**
+ * **The caller's own run (#711): the one input every rerun and every fix naming it again is built from.**
+ *
+ * Each review round of #711 found another run again that dropped what the caller gave — `--json`, `--worker`,
+ * `--dry-run`, a `--set`, an option the Worker's config already answers — because each was rebuilt at its own site
+ * from whatever flags that site held. So a rerun builder ({@link rerunCommand}, {@link rerunRemedy}, `pithy add`'s
+ * `addAgain`) takes this and nothing else, and this is made only by {@link callerOf}, from a run's parsed arguments.
+ * Branded, so loose flags do not type-check where one is wanted; `packages/cli/src/ci/runnableCommands.test.ts`
+ * fails on a cast to it and on a {@link callerOf} handed anything but a run's own arguments.
+ */
+export interface Caller<P extends CommandPath = CommandPath> {
+    /** The command the run was. */
+    readonly path: P;
+    /** Its parsed arguments, keyed as the parser keys them (`worker`, `routing-zone`, `dry-run`). */
+    readonly given: Readonly<Record<string, unknown>>;
+    /** Its `--set` values, by key, and every option it settled by a prompt ({@link settledBy}). */
+    readonly set: Readonly<Record<string, string>>;
+    /**
+     * The options the Worker's config already answers, for a command that reads one (`pithy add`): settled, so a
+     * rerun names no `--set` for them, which could contradict the config.
+     */
+    readonly answered: ReadonlySet<string>;
+    readonly [CALLER]: true;
+}
+/**
+ * **A run's own context**, from its parsed arguments. `set` is the raw `--set` entries where the parser keeps only the
+ * last (`collectSetFlags`); absent, they are read from `given.set`. `answered` is what the Worker's config states.
+ */
+export declare function callerOf<P extends CommandPath>(path: P, given: Readonly<Record<string, unknown>>, context?: {
+    readonly set?: readonly string[] | undefined;
+    readonly answered?: Iterable<string> | undefined;
+}): Caller<P>;
+/** The same caller, with what the run settled on its way — a prompt's answers — carried as `--set` too. */
+export declare function settledBy<P extends CommandPath>(caller: Caller<P>, values: Readonly<Record<string, string>>): Caller<P>;
+/** The same caller, with the options its Worker's config answers. */
+export declare function answeredBy<P extends CommandPath>(caller: Caller<P>, keys: Iterable<string>): Caller<P>;
+/** What a run-again is told beyond the arguments the run was given. */
+export interface RerunOptions {
+    /** The positional arguments, as the command takes them. */
+    readonly args?: readonly string[];
+    /** What the run resolved for itself — the Worker it picked when it was not named — or `undefined` to drop one. */
+    readonly flags?: LooseParts["flags"];
+    /** The project's `seed.productionEnvironments`, beyond the ones every project has. */
+    readonly productionEnvironments?: readonly string[] | undefined;
+}
+/** A command whose run again is always a command: it destroys nothing, and no production run of it is a person's. */
+export type RerunPath = Exclude<CommandPath, DestructivePath | ProductionPath>;
+/**
+ * **The caller's own command, to run again (#711)**, as a {@link Command} — rebuilt from the run's {@link Caller}, so
+ * a rerun asks for nothing the first run did not. `options.flags` adds what the run resolved for itself (the Worker it
+ * picked) or drops a flag whose work is done (`undefined`).
+ *
+ * It takes no command whose run again could be a person's decision — one that destroys something, or one a
+ * production `--env` makes a person's: that run again is {@link rerunRemedy}'s, which says so rather than throwing.
+ */
+export declare function rerunCommand(caller: Caller<RerunPath>, options?: Omit<RerunOptions, "productionEnvironments">): Command;
+/**
+ * **The caller's own command, as a line names it to run again (#711)** — the {@link Remedy} for
+ * {@link rerunCommand}'s parts, for any command. A run again that a production `--env` makes a person's decision is
+ * said as one, with no `fix`, rather than thrown after the run did its work. `say` hands `wrap` the command in code
+ * and — where the run was given a credential by flag, which no line repeats — the flags to pass again beside it.
+ */
+export declare function rerunRemedy(caller: Caller, options?: RerunOptions): Remedy;
+/**
+ * **A command named in prose, not given to run** — "as `pithy add` wrote it". Checked to exist, and spelled with
+ * nothing after it. A line that tells somebody to run a command builds it with {@link pithyCommand}.
+ */
+export declare function commandName(path: CommandPath | GroupPath): string;
+/** {@link commandName}, for a path that is a value: refused when the CLI has no such command or group. */
+export declare function commandNameOf(path: string): string;
+/**
+ * {@link commandNameOf}, for a path as a parser walked it, word by word. Empty is the root, which is the CLI
+ * itself rather than a command, and is named as such.
+ */
+export declare function commandNameOfPath(path: readonly string[]): string;
+/**
+ * **The CLI at a version** — `pithy 0.9.5`, as a line names a release rather than a command. A line never spells
+ * `pithy` before an interpolation: the gate reads that as a command it cannot check.
+ */
+export declare function cliAtVersion(version: string): string;
+/**
+ * **How each package manager runs a project's own binary**: `bun x`, `pnpm exec`, `yarn`, `npx`. The one table
+ * both a spawned process (`packages/cli/src/project/packageManager.ts`'s `execArgs`) and a line naming one read.
+ */
+export declare const PACKAGE_EXEC: {
+    readonly bun: readonly ["bun", "x"];
+    readonly pnpm: readonly ["pnpm", "exec"];
+    readonly yarn: readonly ["yarn"];
+    readonly npm: readonly ["npx"];
+};
+/** A package manager a project runs its own binaries through. */
+export type ExecPackageManager = keyof typeof PACKAGE_EXEC;
+/**
+ * **A built command, run through the project's own package manager** — the `pithy` the project installed, never
+ * a global one, which may be an older CLI than the line is about. Takes a {@link Command}, so what follows the
+ * prefix was built and runs as written.
+ */
+export declare function viaPackageManager(pm: ExecPackageManager, command: Command): Command;
+/** `a`, `a or b`, `a, b or c`, each in code: commands a reader picks one of. */
+export declare function commandAlternatives(commands: readonly string[]): string;
+/** `a`, `a and b`, `a, b and c`, each in code: commands that all run. */
+export declare function commandSequence(commands: readonly string[]): string;
+export {};
+//# sourceMappingURL=command.d.ts.map