@pithy-sh/core 0.1.2 → 0.1.3

package/dist/capability/manifest.js

@@ -0,0 +1,356 @@
+import { BindingSpec } from "./bindings.js";
+import { ValidationError } from "../error/pithyError.js";
+import { manifestRecord } from "./vanishingKey.js";
+import { DevSecret } from "./devSecret.js";
+import { NAMESPACE_PATTERN } from "../migrations/registry.js";
+import { DeclaredSecret } from "./secretOrigin.js";
+import { z } from "zod";
+//#region src/capability/manifest.ts
+/**
+* Whether a string prints as a double-quoted literal Biome leaves exactly as written.
+*
+* Two sequences are out, and only two. A `"` inside the value makes `JSON.stringify` escape it, and
+* Biome's formatter then reprints the whole literal in single quotes to avoid the escape —
+* `"he said \"hi\""` becomes `'he said "hi"'`, a formatting diff on a file the adopter never opened.
+* And `${` trips `lint/suspicious/noTemplateCurlyInString`, which is noise in the same place.
+*
+* An apostrophe stays legal: with no `"` to escape, Biome keeps the double quotes. So do a backslash, a
+* tab, a newline, and any non-ASCII character — every one of these checked by running Biome over the
+* rendered output, because the whole defect class this closes is guessing what Biome would print.
+*/
+function isPrintableString(value) {
+	return !value.includes("\"") && !value.includes("${");
+}
+/** A number whose `String()` form is already the literal Biome prints: a plain decimal, no exponent. */
+const PLAIN_DECIMAL = /^-?\d+(?:\.\d+)?$/;
+/**
+* Whether a number prints as a numeric literal Biome leaves exactly as written.
+*
+* `String(1e21)` is `"1e+21"`, which Biome normalizes to `1e21`. Rather than carry a copy of its numeric
+* normalizer, a default is held to a plain decimal — which is every number a worked example has any
+* business carrying. `NaN` and `Infinity` fall out of the same rule, and JSON cannot state either.
+*/
+function isPrintableNumber(value) {
+	return PLAIN_DECIMAL.test(String(value));
+}
+/** A string a manifest may state, and an object key it may use: one {@link renderConfigValue} can print. */
+const PrintableString = z.string().refine(isPrintableString, { error: "A rendered value may not contain a double quote or \"${\" — Biome reprints the first and lints the second." });
+/** A number a manifest may state: one whose `String()` form is the literal Biome prints. */
+const PrintableNumber = z.number().refine(isPrintableNumber, { error: "A rendered number must be a plain decimal — Biome prints 1e21 where JavaScript prints 1e+21." });
+const ConfigOptionValue = z.lazy(() => z.union([
+	PrintableString,
+	PrintableNumber,
+	z.boolean(),
+	z.array(ConfigOptionValue),
+	manifestRecord(z.record(PrintableString, ConfigOptionValue))
+])).describe("An option's rendered value: a JSON scalar, or a minimal worked example the adopter replaces.");
+/**
+* An object key that can be written bare in a TypeScript object literal.
+*
+* ASCII only, which is narrower than JavaScript: `café` is a legal bare identifier and Biome keeps it,
+* checked by running Biome over it. It stays out because this is also the shape a *config option's* key
+* is held to, and an option name an English keyboard cannot type is not one a capability should ship.
+* Reserved words are in — `{ default: 1 }` and `{ class: 1 }` are both legal property names, checked the
+* same way — so nothing here needs a keyword list to keep in step with the language.
+*/
+const BARE_KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+/**
+* The characters that end a `//` comment. All four are line terminators to a JavaScript parser, so a
+* `describe` carrying one puts everything after it into `pithy.config.ts` as bare code — Biome's first
+* report on the generated file is a parse error, not a lint (#174). U+2028 and U+2029 are here because
+* they really do terminate the comment; that was measured with Biome, not assumed.
+*/
+const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+/**
+* Whether a string prints as a `//` comment Biome leaves exactly as written.
+*
+* Two things break it, and only two. A line terminator ends the comment, so the rest of the `describe`
+* lands as code. And trailing whitespace parses fine and then fails `biome format`, which is a diff on a
+* file the adopter never opened — the same failure mode #171 closed for values.
+*
+* Everything else stays legal, each one checked by running Biome over the rendered comment: leading
+* whitespace, an interior tab, a block-comment terminator, `${x}`, non-ASCII, and a line of any length.
+* A `//` comment ends at the line and nowhere else, and Biome never reflows one, so there is no width
+* rule here either.
+*/
+function isPrintableComment(value) {
+	return !LINE_TERMINATOR.test(value) && value === value.trimEnd();
+}
+/** Print one string as source, refusing the two sequences {@link isPrintableString} keeps out. */
+function renderString(value) {
+	if (!isPrintableString(value)) throw new ValidationError({
+		message: "A config value may not contain a double quote or \"${\".",
+		action: "Pick a value carrying neither, or write the option by hand in pithy.config.ts.",
+		detail: `Rendered as ${JSON.stringify(value)}, Biome would reprint or lint the line, so the generated pithy.config.ts would fail the scaffold's own biome check.`
+	});
+	return JSON.stringify(value);
+}
+/** Print one number as source, refusing anything {@link isPrintableNumber} keeps out. */
+function renderNumber(value) {
+	if (!isPrintableNumber(value)) throw new ValidationError({
+		message: "A config number must be a plain decimal.",
+		action: "Write it without an exponent.",
+		detail: `${String(value)} is not the numeric literal Biome prints for it, so the generated pithy.config.ts would fail the scaffold's own biome check.`
+	});
+	return String(value);
+}
+/**
+* Render a manifest default as TypeScript source, on one line.
+*
+* `pithy add` writes this straight into the adopter's `pithy.config.ts`, which the scaffold's own
+* `biome check` then reads — so *valid* TypeScript is not the bar. It has to be the TypeScript Biome
+* would have printed. `JSON.stringify` is not: it quotes every key, and Biome's `quoteProperties`
+* default rewrites `{"code":"chips"}` to `{ code: "chips" }`, failing the lint gate on a project the
+* adopter has not touched. This prints Biome's shape directly — bare keys wherever they are legal,
+* spaces inside braces, `, ` between entries, `{}` and `[]` for the empty literals #161 relies on.
+*
+* **Total over what {@link ConfigOptionValue} *parses*, which is narrower than what it types.** The two
+* shapes the schema refuses — a string carrying `"` or `${`, a number no plain decimal spells — are
+* refused here too, with a `ValidationError`. A manifest cannot reach that path, since every manifest is
+* parsed before it is rendered; `pithy add --set` can, because a flag's string goes straight through. A
+* refusal at the command beats a config file that fails the adopter's first `bun run lint`.
+*
+* One line, always. Biome breaks any literal past {@link CONFIG_LINE_WIDTH}, and a broken literal is a
+* `biome check` failure on a project the adopter has not touched — #161 and #168 both. That rule used to
+* be this sentence and nothing else, with multiplayer's seed sitting at 98 columns of 120; it is now a
+* test over every shipped manifest default, rendered by {@link renderConfigOptionLine} at the indent the
+* writers really use (#171).
+*/
+function renderConfigValue(value) {
+	if (typeof value === "string") return renderString(value);
+	if (typeof value === "number") return renderNumber(value);
+	if (typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return `[${value.map(renderConfigValue).join(", ")}]`;
+	const entries = Object.entries(value).map(([key, nested]) => `${BARE_KEY.test(key) ? key : renderString(key)}: ${renderConfigValue(nested)}`);
+	return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`;
+}
+/**
+* The column Biome wraps at — `formatter.lineWidth` in the `biome.jsonc` that `pithy init` scaffolds.
+*
+* A line of exactly this width survives untouched; one character more and Biome explodes the literal
+* across a dozen lines, so `biome check` fails on a file the adopter never opened. Measured by running
+* Biome over generated lines of 118 through 122 columns, not read off a docs page.
+*/
+const CONFIG_LINE_WIDTH = 120;
+/**
+* The indent both writers render an option line at in a scaffolded project: the managed-region marker
+* sits four columns in, and an option sits two further.
+*
+* Each writer takes its real indent from the file it is editing, so an adopter who nested `capabilities`
+* deeper gets a longer line than this. This is the scaffold's indent, and the scaffold is what the width
+* rule is measured against — a default that does not fit here fits nowhere.
+*/
+const CONFIG_OPTION_INDENT = "      ";
+/** Whether a rendered value is a reference to one of the scaffold's constants rather than a literal. */
+function isConstantRef(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && "constant" in value;
+}
+function renderConfigOptionLine(key, value, indent) {
+	if (!BARE_KEY.test(key)) throw new ValidationError({
+		message: `A config option key must be a bare identifier, and "${key}" is not.`,
+		action: "Rename the option, or write it by hand in pithy.config.ts.",
+		detail: `Rendered as ${JSON.stringify(`${key}: …`)}, the generated pithy.config.ts would not parse as TypeScript — a key is written bare, so it cannot carry a hyphen, a space, a quote, or a leading digit.`
+	});
+	return `${indent}${key}: ${isConstantRef(value) ? CONFIG_CONSTANTS[value.constant] : renderConfigValue(value)},`;
+}
+/**
+* The comment line both writers put above an option: its `describe`, verbatim, as a `//` comment.
+*
+* The rationale is the whole reason the generated config documents itself, and it comes out of a manifest
+* read from `node_modules` — third-party text reaching generated source. Both writers used to build this
+* line themselves, which is the arrangement that let `pithy add` and `pithy upgrade` disagree about the
+* line *below* it (#171); they now share this, so a rule stated here holds for both.
+*
+* Total over what {@link ConfigOption} parses, exactly as {@link renderConfigOptionLine} is: a manifest
+* cannot reach the throw, because every manifest is parsed before it is rendered.
+*/
+function renderConfigOptionComment(describe, indent) {
+	if (!isPrintableComment(describe)) throw new ValidationError({
+		message: "A config option's rationale must be one line, with no trailing whitespace.",
+		action: "Put it on one line, or write the option by hand in pithy.config.ts.",
+		detail: `Rendered as ${JSON.stringify(`// ${describe}`)}, the generated pithy.config.ts would either not parse — a line break ends the comment and the rest becomes code — or fail biome format on the trailing whitespace.`
+	});
+	return `${indent}// ${describe}`;
+}
+/**
+* A capability's own name, as generated source carries it.
+*
+* The same shape a config option's key is held to, and for the same reason: it is written **bare**, and
+* twice — as the binding of the import statement (`import { auth } from …`) and as the registration call
+* (`auth(),`). Neither position quotes anything, so a name that is not an identifier is not a syntax
+* error in a string, it is a hole. `audit }) ; evil(` closed the capabilities array and opened a call
+* (#183).
+*
+* It is also the leaf of the fork directory `pithy add --eject` writes (`./capabilities/<name>`), so the
+* same rule keeps a name from carrying a path separator or a `..`.
+*/
+const CAPABILITY_NAME = BARE_KEY;
+/**
+* The npm package name a capability ships under, as the import specifier carries it.
+*
+* Rendered inside a double-quoted specifier — `"@pithy-sh/auth/src/index"` — where the required shape is
+* an npm package name and not a bare identifier. The registry's own grammar is narrower than "no quote
+* in it", so that is what is stated: an optional `@scope/`, then a name starting alphanumeric and made of
+* letters, digits, `.`, `_` and `-`. Uppercase is admitted because npm still serves the legacy names that
+* carry it; everything npm forbids outright — a leading `.` or `_`, a space, a second `/`, a quote — is
+* out, and with it the escape `@pithy-sh/audit"; evil(); //` used to close the specifier and append a
+* statement (#183).
+*
+* 214 is npm's own length cap, checked separately so the refusal can say which rule was broken.
+*/
+const PACKAGE_NAME = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** npm's own limit on a package name, counted across the scope and the separator. */
+const PACKAGE_NAME_MAX = 214;
+/**
+* Whether a module specifier prints inside a double-quoted literal Biome leaves exactly as written.
+*
+* The same two sequences {@link isPrintableString} keeps out of a value, plus the line terminators that
+* would end the statement early. A specifier is not a manifest field — it is composed from one
+* ({@link CapabilityManifest.package}) or from the fork path — so it is checked here rather than at the
+* schema, and the check is what makes {@link renderCapabilityImport} total over both callers.
+*/
+function isPrintableSpecifier(value) {
+	return value.length > 0 && isPrintableString(value) && !LINE_TERMINATOR.test(value);
+}
+/** Refuse a capability name generated source cannot carry. Total over what {@link CapabilityManifest} parses. */
+function requireCapabilityName(name) {
+	if (CAPABILITY_NAME.test(name)) return;
+	throw new ValidationError({
+		message: `A capability name must be a bare identifier, and ${JSON.stringify(name)} is not.`,
+		action: "Rename the capability, or wire it by hand in pithy.config.ts.",
+		detail: `It is written bare into the generated pithy.config.ts twice — as the import binding and as the registration call — so ${JSON.stringify(name)} would produce a file that does not parse as TypeScript.`
+	});
+}
+/**
+* The one import line a capability's wiring is written as.
+*
+* Both halves are interpolated raw, and both used to be `z.string().min(1)`: `pithy add` wrote
+* `import { audit }) ; evil( } from "@pithy-sh/audit/src/index";` from a manifest that parsed, and
+* reported `Done.` (#183). The line has one producer now, for the same reason
+* {@link renderConfigOptionLine} does — a rule stated at one call site is a rule the next call site does
+* not have.
+*
+* Total over what {@link CapabilityManifest} parses. A parsed manifest cannot reach either throw; the
+* fork path `pithy add --eject` composes can, which is why the specifier is checked rather than assumed.
+*/
+function renderCapabilityImport(name, specifier) {
+	requireCapabilityName(name);
+	if (!isPrintableSpecifier(specifier)) throw new ValidationError({
+		message: `A capability's import specifier may not be empty, span lines, or contain a double quote or "\${".`,
+		action: "Correct the capability's package name, or write the import by hand in pithy.config.ts.",
+		detail: `Rendered as ${JSON.stringify(`from "${specifier}"`)}, the generated pithy.config.ts would either not parse or fail the scaffold's own biome check.`
+	});
+	return `import { ${name} } from "${specifier}";`;
+}
+/**
+* The registration both writers put in `pithy.config.ts` for one capability — `auth(),` with no options,
+* the block form with them.
+*
+* The name is the only thing here that comes from a manifest, and it is the thing that reached generated
+* source unchecked (#183). One producer, so the rule holds for `pithy add`'s whole-entry write and for
+* `pithy upgrade`'s conversion of a one-liner into a block alike.
+*/
+function renderCapabilityRegistration({ name, indent, optionLines = [], trailingComma = true }) {
+	requireCapabilityName(name);
+	const end = trailingComma ? "," : "";
+	if (optionLines.length === 0) return `${indent}${name}()${end}`;
+	return [
+		`${indent}${name}({`,
+		...optionLines,
+		`${indent}})${end}`
+	].join("\n");
+}
+/**
+* One configurable option a capability exposes. `pithy add` renders each as
+* `cap({ key: default })` in `pithy.config.ts`, with `describe` as the comment
+* above it — the self-documenting config surface (docs/CLI.md §Config). The
+* mount-point model rides on options like this (e.g. `basePath`), so handlers
+* stay in the package and the user owns the wiring.
+*
+* **Every option the capability's config type requires belongs here.** The manifest is the only thing
+* `pithy add` reads, so an option it omits is an option the generated config omits — see
+* {@link ConfigOptionValue} for the one that got away.
+*
+* **All three fields are narrowed to what the renderer can print, not just the value.** #171 held
+* `default` to shapes Biome prints unchanged and left `key` and `describe` as `z.string().min(1)`, so a
+* manifest could still state `content-type` — rendered `content-type: "x",`, which is not TypeScript at
+* all — or a `describe` with a newline in it, whose second line landed in `pithy.config.ts` as bare code.
+* A manifest is third-party data read from `node_modules`, and an option key is that data interpolated
+* into generated source; `}) ; evil(` is the shape that makes the point. Narrowing here is what lets
+* {@link renderConfigOptionLine} and {@link renderConfigOptionComment} guarantee the whole line rather
+* than its right-hand side (#174).
+*/
+/**
+* The constants a scaffolded `pithy.config.ts` defines, that a manifest option may name instead of
+* stating a literal — identifier by key, so the manifest carries a **name from a closed set** and never
+* an expression.
+*
+* That is the whole security argument, and it is the same one #183 settled for a capability's name: a
+* manifest is third-party data read out of `node_modules` and written into the adopter's TypeScript, so
+* anything it states unquoted must come from a list this package controls. An `expression` field would
+* put arbitrary code in the adopter's config on the strength of a package they installed.
+*
+* One entry today. `PUBLIC_ORIGIN` is the Worker's address for the environment it composes in, derived
+* by `originFor(compositionEnvironment(), DOMAINS)` in the scaffolded config — the line that exists so no
+* capability ever asks an adopter to write an origin down again.
+*/
+const CONFIG_CONSTANTS = { publicOrigin: "PUBLIC_ORIGIN" };
+/** Which scaffolded constant an option's value is, by key. */
+const ConfigConstant = z.enum(Object.keys(CONFIG_CONSTANTS)).describe("A constant the scaffolded pithy.config.ts defines, named from a closed set rather than spelled out.");
+const ConfigOption = z.object({
+	key: z.string().regex(BARE_KEY, { error: (issue) => `A config option key must be a bare identifier, and ${JSON.stringify(issue.input)} is not — it is written bare into pithy.config.ts.` }).describe("Option name passed to the capability factory (e.g. \"basePath\"); a bare identifier."),
+	default: ConfigOptionValue.optional().describe("The value rendered into pithy.config.ts when no override is given — and **its absence is what makes an option required**. There is no flag beside it saying so: an option that states a default has an answer the kit is willing to pick, and an option that states none has one only the adopter can. A required option is settled before a byte is written — a prompt asks it with nothing to accept by pressing enter, `--set key=value` answers it non-interactively, and a run carrying neither is refused naming the flag. Nothing is guessed, because a decision worth refusing over is one that is expensive to reverse: payments' `billingSubject` decides whether an entitlement is held by a person or a company, and it lands in a column and a UNIQUE index."),
+	choices: z.array(PrintableString).min(1).optional().describe("The values this option accepts, when they are a closed set. Three things follow from stating them, and none of them can be had without: the prompt is a select rather than free text, `--set` refuses a value outside them instead of writing it into the config, and a refusal can name what is legal — which is the whole of what a caller needs in order to answer a required option. Held to the same printable-string rule as a default, because a choice becomes the value written into the adopter's TypeScript."),
+	choicesNeedingCode: manifestRecord(z.record(PrintableString, z.string().min(1))).optional().describe("Choices `pithy add` must refuse, each mapped to the sentence telling the adopter what to do instead — a value whose composition needs a seam only they can write. `pithy add` renders JSON into `pithy.config.ts`; it cannot render a function, so a choice whose validity depends on one is a choice it can write and the kit will then refuse to load. `payments`' `billingSubject: \"organization\"` is the one: it requires a `resolveSubject` saying which organization a caller acts for, deliberately has no default because a capability that guessed would key a company's plan to whoever signed in first, and so a config carrying the choice without the seam is refused at assembly — bricking every later command in the project, since they all begin by loading the config (#483). Refusing the choice up front costs the adopter one hand-edit; writing it costs them the project."),
+	constant: ConfigConstant.optional().describe("A constant the scaffolded pithy.config.ts defines, rendered *unquoted* in place of `default` when the target config declares it. The one that exists is `publicOrigin` — `PUBLIC_ORIGIN`, this Worker's address for the environment it composes in. An option whose value is an origin must name it rather than state a URL, because a URL written down is production's URL written into staging: it is what mailed staging's testers magic links into production and unsubscribed them there (#256). `default` is still required *for such an option* and is what a config with no such constant gets, so an older project is never handed an identifier it does not define — the one place the absent-default rule does not reach, and it is checked rather than trusted."),
+	describe: z.string().min(1).refine(isPrintableComment, { error: (issue) => `A config option's rationale must be one line with no trailing whitespace, and ${JSON.stringify(issue.input)} is not — it is written into pithy.config.ts as a // comment.` }).describe("Rationale rendered as the comment above this option in pithy.config.ts; one line.")
+}).check((ctx) => {
+	const option = ctx.value;
+	if (option.choices && option.default !== void 0 && !option.choices.includes(option.default)) ctx.issues.push({
+		code: "custom",
+		input: option.default,
+		path: ["default"],
+		message: `A config option's default must be one of its choices, and ${JSON.stringify(option.default)} is not — ${option.key} offers ${JSON.stringify(option.choices)}.`
+	});
+	for (const choice of Object.keys(option.choicesNeedingCode ?? {})) if (!option.choices?.includes(choice)) ctx.issues.push({
+		code: "custom",
+		input: choice,
+		path: ["choicesNeedingCode", choice],
+		message: `A choice needing code must be one this option offers, and ${JSON.stringify(choice)} is not — ${option.key} offers ${JSON.stringify(option.choices ?? [])}.`
+	});
+	if (option.constant !== void 0 && option.default === void 0) ctx.issues.push({
+		code: "custom",
+		input: option.constant,
+		path: ["default"],
+		message: `A config option naming a constant must still carry a default, and ${option.key} names ${JSON.stringify(option.constant)} with none — a project whose pithy.config.ts predates the constant gets the default instead, so an option with no default would hand it an identifier nothing declares.`
+	});
+}).describe("A configurable option a capability exposes (key, default, choices, rationale).");
+/**
+* Declarative, CLI-facing description of a capability. Lives at `pithy.manifest.json` in
+* each capability package; read by `pithy add`/`upgrade` to wire bindings into
+* `wrangler.jsonc` and scaffold config — without executing the package. Plain data, so
+* it's a validated Zod object. `requiredBindings` reuse the `BindingSpec` contract, so a
+* manifest's bindings are normalized (and rejected) exactly like a capability's own.
+*
+* **The invariant, stated here rather than at the writers: every string a manifest states that reaches
+* generated source is constrained to what the renderer can print.** Three rounds got there one field at a
+* time — #171 narrowed an option's `default`, #174 its `key` and `describe`, #183 the capability's own
+* `name` and `package` — because each time the rule lived at the call site that had just been fixed. It
+* lives here now, and `manifest.test.ts` walks this schema and fails the build on a string field that is
+* neither constrained nor declared prose the CLI only ever prints.
+*/
+const CapabilityManifest = z.object({
+	name: z.string().regex(CAPABILITY_NAME, { error: (issue) => `A capability name must be a bare identifier, and ${JSON.stringify(issue.input)} is not — it is written bare into pithy.config.ts as both the import binding and the registration call.` }).describe("Capability name, e.g. \"auth\"; a bare identifier."),
+	package: z.string().max(PACKAGE_NAME_MAX).regex(PACKAGE_NAME, { error: (issue) => `A capability's package must be an npm package name, and ${JSON.stringify(issue.input)} is not — it is written into pithy.config.ts as the import specifier.` }).describe("npm package providing this capability, e.g. \"@pithy-sh/auth\"."),
+	requiredBindings: z.array(BindingSpec).describe("Bindings the CLI must wire into wrangler.jsonc (normalized via BindingSpec)."),
+	peerCapabilities: z.array(z.string().regex(CAPABILITY_NAME, { error: (issue) => `A peer capability is named by its capability name, and ${JSON.stringify(issue.input)} is not a bare identifier.` })).default([]).describe("Capabilities that must also be present (e.g. auth ⇒ email)."),
+	optionalCapabilities: z.array(z.string().regex(CAPABILITY_NAME, { error: (issue) => `An optional capability is named by its capability name, and ${JSON.stringify(issue.input)} is not a bare identifier.` })).default([]).describe("Capabilities that, if present, get wired together (e.g. turnstile onto auth)."),
+	migrationNamespace: z.string().regex(NAMESPACE_PATTERN).optional().describe("Namespace prefix for this capability's migrations — must match the registry's format (e.g. \"auth\")."),
+	devSecrets: z.array(DevSecret).default([]).describe("Secrets from this capability's registry whose dev value `pithy add` mints into `.dev.vars`."),
+	secrets: z.array(DeclaredSecret).default([]).describe("Every secret from this capability's registry that declares how it comes to exist and how it is replaced. The route `devSecrets` proved: a client reads it without executing the package, so `pithy doctor` says *not set — run this* or *not set — get it here*, and no client keeps its own table of names. A secret declaring neither axis is absent, which reads as *nothing is known*, not as *nothing can help*."),
+	scaffold: z.array(z.string()).default([]).describe("Human-readable scaffold steps the CLI performs or explains."),
+	configOptions: z.array(ConfigOption).default([]).describe("Config options the capability exposes; `pithy add` renders each as `cap({ key: default })`."),
+	whenToEnable: z.string().optional().describe("Self-documenting rationale the CLI surfaces when offering this capability.")
+}).describe("Declarative, CLI-facing description of a capability (pithy.manifest.json).");
+//#endregion
+export { CONFIG_CONSTANTS, CONFIG_LINE_WIDTH, CONFIG_OPTION_INDENT, CapabilityManifest, ConfigConstant, ConfigOption, ConfigOptionValue, renderCapabilityImport, renderCapabilityRegistration, renderConfigOptionComment, renderConfigOptionLine, renderConfigValue };

package/dist/capability/secretOrigin.d.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+/**
+ * How a secret's value comes to exist, and how it is replaced.
+ *
+ * A secret the kit cannot mint leaves an adopter on their own. The registry has always known which
+ * those are — no `devValue` — and nothing about how a human is supposed to get one, so every client
+ * that wanted to help had to carry its own table of names, and a capability added tomorrow silently
+ * fell off it.
+ *
+ * It lives in core, and in its own module, for the reason `devSecret.ts` does: both ends need it and
+ * neither can import the other. The owning capability declares it on its `@pithy-sh/secrets` registry
+ * entry; a client — `pithy doctor`, `pithy secrets ls`, a management dashboard — reads the same
+ * declaration off `pithy.manifest.json`, which it must, since `pithy add` wires a capability without
+ * ever executing it.
+ *
+ * **A function cannot cross into the manifest. A tag can.** So everything here is data, and the code
+ * that knows what `random` means stays in the CLI — exactly as it already does for `devValue`.
+ */
+export declare const SecretIssuer: z.ZodEnum<{
+    apple: "apple";
+    atlassian: "atlassian";
+    cloudflare: "cloudflare";
+    facebook: "facebook";
+    github: "github";
+    gitlab: "gitlab";
+    google: "google";
+    lemonSqueezy: "lemonSqueezy";
+    microsoft: "microsoft";
+    other: "other";
+    paddle: "paddle";
+    project: "project";
+    stripe: "stripe";
+}>;
+export type SecretIssuer = z.output<typeof SecretIssuer>;
+export declare const SecretRecipe: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"random">;
+    bytes: z.ZodInt;
+    encoding: z.ZodEnum<{
+        base64: "base64";
+        base64url: "base64url";
+        hex: "hex";
+    }>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"encryptionConfig">;
+}, z.core.$strip>], "kind">;
+export type SecretRecipe = z.output<typeof SecretRecipe>;
+export declare const SecretOrigin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"minted">;
+    recipe: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"random">;
+        bytes: z.ZodInt;
+        encoding: z.ZodEnum<{
+            base64: "base64";
+            base64url: "base64url";
+            hex: "hex";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"encryptionConfig">;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"helped">;
+    issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+    needs: z.ZodPipe<z.ZodCustom<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>, z.ZodType<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>, z.core.$ZodTypeInternals<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>>>;
+    documentation: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"obtained">;
+    issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+    documentation: z.ZodURL;
+}, z.core.$strip>], "kind">;
+export type SecretOrigin = z.output<typeof SecretOrigin>;
+export declare const SecretRotation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"provider">;
+    issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+    documentation: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+    issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+    documentation: z.ZodURL;
+}, z.core.$strip>], "kind">;
+export type SecretRotation = z.output<typeof SecretRotation>;
+export declare const DeclaredSecret: z.ZodObject<{
+    name: z.ZodString;
+    origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"minted">;
+        recipe: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"random">;
+            bytes: z.ZodInt;
+            encoding: z.ZodEnum<{
+                base64: "base64";
+                base64url: "base64url";
+                hex: "hex";
+            }>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"encryptionConfig">;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"helped">;
+        issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+        needs: z.ZodPipe<z.ZodCustom<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>, z.ZodType<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>, z.core.$ZodTypeInternals<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>>>;
+        documentation: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"obtained">;
+        issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+        documentation: z.ZodURL;
+    }, z.core.$strip>], "kind">;
+    rotation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"local">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"provider">;
+        issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+        documentation: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"manual">;
+        issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+        documentation: z.ZodURL;
+    }, z.core.$strip>], "kind">;
+}, z.core.$strip>;
+export type DeclaredSecret = z.output<typeof DeclaredSecret>;
+//# sourceMappingURL=secretOrigin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secretOrigin.d.ts","sourceRoot":"","sources":["../../src/capability/secretOrigin.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;EAkBtB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAsEzD,eAAO,MAAM,YAAY;;;;;;;;;;2BAoCtB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;2BA0CtB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,eAAO,MAAM,cAAc;;;;;;;;;;2BAsCxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAaxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/capability/secretOrigin.js

@@ -0,0 +1,134 @@
+import { manifestRecord } from "./vanishingKey.js";
+import { z } from "zod";
+//#region src/capability/secretOrigin.ts
+/**
+* How a secret's value comes to exist, and how it is replaced.
+*
+* A secret the kit cannot mint leaves an adopter on their own. The registry has always known which
+* those are — no `devValue` — and nothing about how a human is supposed to get one, so every client
+* that wanted to help had to carry its own table of names, and a capability added tomorrow silently
+* fell off it.
+*
+* It lives in core, and in its own module, for the reason `devSecret.ts` does: both ends need it and
+* neither can import the other. The owning capability declares it on its `@pithy-sh/secrets` registry
+* entry; a client — `pithy doctor`, `pithy secrets ls`, a management dashboard — reads the same
+* declaration off `pithy.manifest.json`, which it must, since `pithy add` wires a capability without
+* ever executing it.
+*
+* **A function cannot cross into the manifest. A tag can.** So everything here is data, and the code
+* that knows what `random` means stays in the CLI — exactly as it already does for `devValue`.
+*/
+const SecretIssuer = z.enum([
+	"project",
+	"cloudflare",
+	"apple",
+	"google",
+	"github",
+	"facebook",
+	"microsoft",
+	"stripe",
+	"lemonSqueezy",
+	"paddle",
+	"gitlab",
+	"atlassian",
+	"other"
+]).describe("Who issues this value. `project` means it is arbitrary and ours to make. Every other member is a third party whose console or API is the only source: payments rails, auth's social providers, `cloudflare` for R2, Turnstile and API tokens, and the repository hosts an adopter may rotate CI credentials against. `other` is the floor an unrecognized issuer lands on, so a capability added tomorrow is renderable by a client built today.");
+/**
+* The issuer **as a field**, with its one degradation rule attached.
+*
+* **An unrecognized issuer degrades to `other` rather than failing.** A manifest is read from
+* `node_modules`, so it can be newer than the client reading it — and a client that threw on an issuer
+* it had not been built against would blank a pane over a name it did not need to understand. `other`
+* is the honest answer: *somebody issues this, and I cannot help you with them.*
+*
+* A field holds one value, so rewriting it destroys nothing. {@link IssuerKey} is the same name in the
+* one position where that is false.
+*/
+const IssuerName = SecretIssuer.catch("other");
+/** The issuer as a field, with the sentence that site needs. The rule comes from {@link IssuerName}. */
+function issuedBy(description) {
+	return IssuerName.describe(description);
+}
+/**
+* The issuer **as a record key**, where the field's degradation rule would destroy data.
+*
+* **A key cannot degrade the way a field does, and the attempt to share one rule between them was the
+* defect.** `SecretIssuer.catch("other")` rewrites what it parses. On a field that is a rename; on a key
+* it is a *merge*, and the merge is silent. Keyed by the field's rule, `{ vercel: ["a"], netlify: ["b"] }`
+* parsed to `{ other: ["b"] }` — vercel's requirement gone, the parse successful, nothing anywhere
+* reporting it. Requirements lost without a word are worse than a manifest that refuses to parse, because
+* a refusal is at least visible.
+*
+* So a key keeps the name it was written with. What a client loses by that is nothing it had: a reader
+* that branches on the closed set runs `SecretIssuer.safeParse(key)` at the point of use and falls back to
+* `other` for rendering, which is the same answer the schema used to force on it — except that the scopes
+* are still there beside it, and a second unknown issuer is still a second entry.
+*
+* A preserved key reaches a rendered command and a rendered heading unchanged, so it is held to the shape
+* of a name. That constraint is not a degradation path: an issuer a client has never heard of is still
+* spelled like an issuer, and anything that is not is hostile data rather than a newer manifest.
+*/
+const IssuerKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]*$/).describe("An issuer, as the key of a record. Preserved exactly as written — unlike the field, which degrades to `other` — because two unrecognized issuers rewritten to one key overwrite each other's requirements with no error. A client that only knows the closed set narrows this with `SecretIssuer.safeParse` where it renders.");
+/** The characters a secret name may hold. Excludes `/`, which separates a keyspace from a member key. */
+const SECRET_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+/** What a helper must supply, per item. Permission groups and scope names, and nothing that reads as code. */
+const HELPER_NEED = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]*$/;
+/**
+* A documentation link, held to `https:` and nothing else.
+*
+* `z.url()` on its own is not enough here: it accepts `javascript:alert(1)`, and it accepts `http:`. A
+* manifest is third-party data read out of `node_modules`, and this is the one field in it whose whole
+* purpose is to be turned into an anchor an operator clicks. So the scheme is constrained at the schema,
+* where a client cannot forget to.
+*/
+const DOCUMENTATION_URL = /^https:\/\//;
+/** The documentation field, wherever it appears: a real URL, and an `https:` one. */
+function documentedAt(description) {
+	return z.url().regex(DOCUMENTATION_URL).describe(description);
+}
+const SecretRecipe = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("random").describe("Random bytes rendered as a string. Any value works, because nothing outside the project reads it."),
+	bytes: z.int().positive().describe("Entropy before encoding. Stated because 32 and 16 are not interchangeable — a value sized for AES-256 that arrives half that long fails at decrypt, not at write, and by then it is stored."),
+	encoding: z.enum([
+		"base64url",
+		"base64",
+		"hex"
+	]).describe("How the bytes are rendered. The kit mints `base64url`, unpadded, so a value survives a `.dev.vars` line, a shell export and a URL without quoting.")
+}).describe("A minted value the kit makes from entropy: how many bytes, and how they are rendered."), z.object({ kind: z.literal("encryptionConfig").describe("An `EncryptionConfig` — `currentVersion`, a `versions` map, `lastRotatedAt` — minted by `initialMasterKeyConfig`. `SECRETS_ENCRYPTION_KEYS` is the one, and the reason this is a union rather than an enum: it is minted, and a random string is not one of these. It states no `bytes` or `encoding` because the structure states its own.") }).describe("A minted structure rather than a string. The tag is the whole recipe; nothing about it is configurable.")]).describe("What produces a minted value. A tag the CLI resolves to code, never the code itself, because this crosses into the manifest.");
+const SecretOrigin = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("minted").describe("The kit produces this value. Nothing outside the project has to agree with it."),
+		recipe: SecretRecipe.describe("What produces it.")
+	}).describe("Minted by the kit. The recipe says how, and no third party has to agree with the result."),
+	z.object({
+		kind: z.literal("helped").describe("The kit cannot produce it, but knows enough to compose the command that does — a Cloudflare API token, whose permission groups an operator should not have to look up."),
+		issuer: issuedBy("Whose console or API issues it."),
+		needs: manifestRecord(z.partialRecord(IssuerKey, z.array(z.string().regex(HELPER_NEED)))).describe("What a helper must supply, keyed by issuer. Cloudflare's key is its permission groups. Keyed rather than flat so a second issuer does not widen a shape every consumer must handle. An unrecognized key is kept verbatim rather than degraded — see `IssuerKey`: rewriting two of them onto `other` loses one issuer's requirements silently. Wrapped in `manifestRecord` so the key rule is given every key the manifest wrote, including the one a parse would otherwise drop before the rule ran."),
+		documentation: documentedAt("Where the command's arguments come from, for an operator who would rather check them by hand.").optional()
+	}).describe("Issued elsewhere, but the kit knows enough to compose the command that asks for it."),
+	z.object({
+		kind: z.literal("obtained").describe("A human gets it from a third party and there is no command. An OAuth client secret is the case, and always will be."),
+		issuer: issuedBy("Whose console issues it."),
+		documentation: documentedAt("Where a human goes. The specific settings page, not a product homepage — the point is to end a search, not to start one.")
+	}).describe("Fetched by a human from a third party. There is no command, and the link is the whole help.")
+]).describe("How this secret's value first comes to exist. Closed, so a consumer branches rather than parses, and so an unhandled member is a type error rather than a blank screen.");
+const SecretRotation = z.discriminatedUnion("kind", [
+	z.object({ kind: z.literal("local").describe("Replaced by producing a new value the same way it was minted. Every `origin.kind: \"minted\"` secret, and nothing else — if the kit can make one it can make another.") }).describe("Rotated by the kit, on its own. The tag carries everything; there is nobody to call."),
+	z.object({
+		kind: z.literal("provider").describe("Replaced by calling the issuer, which returns the new value. The kit cannot invent this call; the capability or the adopter supplies it, and it changes state in somebody else's system."),
+		issuer: issuedBy("Who is called."),
+		documentation: documentedAt("What the call does, for an operator deciding whether to trust it with a live credential.").optional()
+	}).describe("Rotated by calling the issuer. The new value comes back from somebody else's system."),
+	z.object({
+		kind: z.literal("manual").describe("A human, in a console. No API returns the new value — a GitHub or Google OAuth client secret. This is a real answer, not a missing one."),
+		issuer: issuedBy("Whose console."),
+		documentation: documentedAt("The page where it is done.")
+	}).describe("Rotated by a human, in a console. A real answer, and the page is the whole help.")
+]).describe("How this secret is replaced, declared separately from `origin` because neither follows from the other: a GitLab token is `obtained` and rotates by `provider`, while an OAuth client secret is `obtained` and rotates only by `manual`. Declared per secret, never per issuer — some Cloudflare secrets roll and some do not.");
+const DeclaredSecret = z.object({
+	name: z.string().regex(SECRET_NAME).describe("The registry name the secret is declared under. Constrained, because a manifest is third-party data read from `node_modules` and this name reaches a rendered command."),
+	origin: SecretOrigin.describe("How its value first comes to exist. Must match the registry entry's `origin`."),
+	rotation: SecretRotation.describe("How it is replaced. Must match the registry entry's `rotation`.")
+}).describe("One declared secret, as a manifest carries it: its registry name and both axes. Both, always — an origin without a rotation answers half of what an operator holding an overdue secret needs to know. The manifest's projection of the registry entry, and each capability's own tests assert the two agree.");
+//#endregion
+export { DeclaredSecret, SecretIssuer, SecretOrigin, SecretRecipe, SecretRotation };