@pithy-sh/core 0.8.0 → 0.10.0

package/dist/cli/command.js

@@ -0,0 +1,418 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+import { InternalError } from "../error/pithyError.js";
+import { COMMANDS, GLOBAL_FLAGS, GROUPS } from "./commandCatalog.generated.js";
+import { CONFIRMATIONS, CONFIRM_FLAGS, CREDENTIAL_FLAGS, DESTRUCTIVE_COMMANDS, DESTRUCTIVE_FLAGS, EVERY_ENVIRONMENT_ALWAYS, EVERY_ENVIRONMENT_WITHOUT_ENV, MEANING_FLAGS, MEANING_ONLY_WITH, NO_WORKER_MODES, PRODUCTION_CONFIRMS, PRODUCTION_ENVIRONMENTS, REQUIRED_BESIDE, WORKER_SCOPED } from "./commandFacts.js";
+//#region src/cli/command.ts
+/** The CLI itself: the first word of every line built here, and what a line names when it means no command. */
+const CLI = "pithy";
+/**
+* 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.
+*/
+function workerDirOf(worker) {
+	const name = worker.dir.split(/[\\/]/).filter((part) => part.length > 0).at(-1);
+	if (name === void 0) throw new InternalError({
+		message: "A Worker directory has a name.",
+		detail: worker.dir
+	});
+	return name;
+}
+/** Whether `path` is a command the CLI runs. */
+function isCommandPath(path) {
+	return Object.hasOwn(COMMANDS, path);
+}
+/** Whether `path` is a group. */
+function isGroupPath(path) {
+	return GROUPS.includes(path);
+}
+/**
+* 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.
+*/
+function commandFlag(path, flag) {
+	if (!isCommandPath(path)) return void 0;
+	return COMMANDS[path].flags[flag];
+}
+/** A value nobody can run: a `<placeholder>`, or nothing at all. */
+function isPlaceholder(value, options) {
+	if (value.trim().length === 0) return true;
+	return (value.match(/<[^>]*>/g) ?? []).some((mark) => !(options.interpolated === true && mark === "<x>"));
+}
+/** Whether the environment a line names is a production one. */
+function isProduction(env, options) {
+	const name = env.trim().toLowerCase();
+	return [...PRODUCTION_ENVIRONMENTS, ...options.productionEnvironments ?? []].some((one) => one.trim().toLowerCase() === name);
+}
+/**
+* **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.
+*/
+function commandFaults(path, parts = {}, options = {}) {
+	const shown = `${CLI} ${path}`;
+	if (!isCommandPath(path)) return [isGroupPath(path) ? `\`${shown}\` is a group, which runs nothing.` : `\`${shown}\` is not a command.`];
+	const def = COMMANDS[path];
+	const faults = [];
+	const args = parts.args ?? [];
+	const flags = Object.entries(parts.flags ?? {}).filter((entry) => entry[1] !== void 0);
+	const named = new Set(flags.map(([flag]) => flag));
+	const required = def.positionals.filter((one) => one.required).length;
+	const variadic = def.positionals.some((one) => one.variadic);
+	if (args.length < required) faults.push(`\`${shown}\` needs its ${def.positionals[args.length]?.name} argument.`);
+	if (!variadic && args.length > def.positionals.length) faults.push(`\`${shown}\` takes ${def.positionals.length} arguments.`);
+	for (const arg of options.spelled === true ? args : []) if (isPlaceholder(arg, options)) faults.push(`\`${shown}\` is given "${arg}", which nobody can run.`);
+	const global = new Set(GLOBAL_FLAGS);
+	for (const [flag, value] of flags) {
+		const flagDef = def.flags[flag];
+		if (flagDef === void 0) {
+			if (!global.has(flag)) faults.push(`\`${shown}\` has no ${flag}.`);
+			continue;
+		}
+		const values = typeof value === "string" ? [value] : value === true ? [] : [...value];
+		if (flagDef.type === "boolean" && value !== true) faults.push(`\`${shown} ${flag}\` takes no value.`);
+		if (flagDef.type === "string" && (value === true || values.length === 0)) faults.push(`\`${shown} ${flag}\` needs a value.`);
+		if (values.length > 1 && !flagDef.repeatable) faults.push(`\`${shown} ${flag}\` is passed once.`);
+		for (const one of values) if (options.spelled === true && isPlaceholder(one, options)) faults.push(`\`${shown} ${flag}\` is given "${one}", which nobody can run.`);
+		else if (options.given !== true && flagDef.enum !== void 0 && !flagDef.enum.includes(one) && !(options.interpolated && one === "<x>")) faults.push(`\`${shown} ${flag}\` takes ${flagDef.enum.join(", ")}, not ${one}.`);
+	}
+	const confirms = new Set(CONFIRM_FLAGS);
+	for (const flag of named) {
+		if (confirms.has(flag)) faults.push(`\`${shown} ${flag}\` carries a confirmation only a person gives.`);
+		if (CREDENTIAL_FLAGS.includes(flag)) faults.push(`\`${shown} ${flag}\` carries a credential, which no line repeats.`);
+	}
+	for (const [flag, flagDef] of Object.entries(def.flags)) {
+		if (named.has(flag)) continue;
+		if (flagDef.required && !(options.person === true && confirms.has(flag))) faults.push(`\`${shown}\` is refused without ${flag}.`);
+		const onlyWith = MEANING_ONLY_WITH[path];
+		const meaningful = onlyWith === void 0 || named.has(onlyWith);
+		if (MEANING_FLAGS.includes(flag) && flagDef.default !== void 0 && meaningful) faults.push(`\`${shown}\` without ${flag} acts on ${flagDef.default}; a line names the one it is about.`);
+	}
+	for (const group of def.groups) faults.push(...groupFaults(shown, group, named));
+	for (const rule of REQUIRED_BESIDE) if (rule.path === path && named.has(rule.with) && !named.has(rule.unless) && !named.has(rule.needs)) faults.push(`\`${shown} ${rule.with}\` is refused without ${rule.needs}.`);
+	const noWorker = (NO_WORKER_MODES[path] ?? []).some((flag) => named.has(flag));
+	if (WORKER_SCOPED.includes(path) && !noWorker && !named.has("--worker") && !options.runtime) faults.push(`\`${shown}\` acts on one Worker and names none.`);
+	if (options.person !== true) for (const consequence of consequencesOf(path, parts, options)) faults.push(`\`${shown}\` ${consequence}: a person's decision.`);
+	return faults;
+}
+/**
+* **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.
+*/
+function consequencesOf(path, parts = {}, options = {}) {
+	const consequences = [];
+	if (Object.hasOwn(DESTRUCTIVE_COMMANDS, path)) consequences.push(`deletes ${DESTRUCTIVE_COMMANDS[path]}`);
+	for (const [flag, value] of Object.entries(parts.flags ?? {})) if (value !== void 0 && Object.hasOwn(DESTRUCTIVE_FLAGS, flag)) consequences.push(`deletes ${DESTRUCTIVE_FLAGS[flag]}`);
+	const env = parts.flags?.["--env"];
+	if (Object.hasOwn(PRODUCTION_CONFIRMS, path) && typeof env === "string" && isProduction(env, options)) consequences.push(`runs against ${env}, a production environment`);
+	if (env === void 0 && actsOnEveryEnvironment(path) || actsOnEveryEnvironmentAlways(path)) consequences.push("runs against every environment, production included");
+	return consequences;
+}
+/**
+* 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.
+*/
+function actsOnEveryEnvironment(path) {
+	return EVERY_ENVIRONMENT_WITHOUT_ENV.includes(path);
+}
+/**
+* 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.
+*/
+function actsOnEveryEnvironmentAlways(path) {
+	return EVERY_ENVIRONMENT_ALWAYS.includes(path);
+}
+/** What one rule over several flags says about the flags a line names. */
+function groupFaults(shown, group, named) {
+	const among = (group.flags ?? []).filter((flag) => named.has(flag));
+	const list = (group.flags ?? []).join(", ");
+	switch (group.kind) {
+		case "exactlyOne": return among.length === 1 ? [] : [`\`${shown}\` takes exactly one of ${list}.`];
+		case "atMostOne": return among.length <= 1 ? [] : [`\`${shown}\` takes at most one of ${list}.`];
+		case "allOrNone": return among.length === 0 || among.length === (group.flags ?? []).length ? [] : [`\`${shown}\` takes all of ${list}, or none.`];
+		case "requires": {
+			if (group.flag === void 0 || !named.has(group.flag)) return [];
+			const needs = group.needs ?? [];
+			return (group.any === true ? needs.some((flag) => named.has(flag)) : needs.every((flag) => named.has(flag))) ? [] : [`\`${shown} ${group.flag}\` needs ${needs.join(group.any === true ? " or " : " and ")}.`];
+		}
+	}
+}
+/** A word as a shell reads it back: quoted only when it has to be. */
+function shellWord(word) {
+	return /^[A-Za-z0-9_@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
+}
+/** The line, spelled: arguments first, then each flag in the order the caller wrote it. */
+function spell(path, parts) {
+	const words = [
+		CLI,
+		path,
+		...(parts.args ?? []).map(shellWord)
+	];
+	for (const [flag, value] of Object.entries(parts.flags ?? {})) {
+		if (value === void 0) continue;
+		if (value === true) words.push(flag);
+		else for (const one of typeof value === "string" ? [value] : value) words.push(flag, shellWord(one));
+	}
+	return words.join(" ");
+}
+/** Throw what {@link commandFaults} found, or hand back nothing. */
+function refuseFaults(path, parts, options) {
+	const faults = commandFaults(path, parts, options);
+	if (faults.length > 0) throw new InternalError({
+		message: `A line names a command that does not run as written: ${faults.join(" ")}`,
+		detail: spell(path, parts)
+	});
+}
+/**
+* **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.
+*/
+function pithyCommand(path, ...parts) {
+	return build(path, parts[0] ?? {}, {});
+}
+/** Check a line's shape, and spell it. */
+function build(path, parts, options) {
+	refuseFaults(path, parts, options);
+	return spell(path, parts);
+}
+/** Whether a production run of `path` is a person's decision, so its `--env` decides what kind of line it is. */
+function isProductionPath(path) {
+	return Object.hasOwn(PRODUCTION_CONFIRMS, path);
+}
+function pithyCommandOf(path, parts = {}, options = {}) {
+	if (parts.flags?.["--env"] !== void 0 && (options.runtime === true || isProductionPath(path))) throw new InternalError({ message: `A line names an environment it read through remedy, never through pithyCommandOf: \`${spell(path, parts)}\`.` });
+	return build(path, parts, options);
+}
+/**
+* **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.
+*/
+function personDecision(path, parts, options = {}) {
+	if (!(Object.hasOwn(DESTRUCTIVE_COMMANDS, path) || Object.entries(parts.flags ?? {}).some(([flag, value]) => value !== void 0 && Object.hasOwn(DESTRUCTIVE_FLAGS, flag)))) throw new InternalError({ message: `\`${spell(path, parts)}\` destroys nothing; a person's decision names what it destroys, and a production run is remedy's to say.` });
+	return decision(path, parts, options);
+}
+/** The sentence {@link personDecision} says, for any command with something a person must decide. */
+function decision(path, parts, options) {
+	refuseFaults(path, parts, {
+		...options,
+		person: true
+	});
+	const consequences = consequencesOf(path, parts, options);
+	if (consequences.length === 0) throw new InternalError({ message: `\`${spell(path, parts)}\` has nothing a person must decide; build it as a command.` });
+	const named = Object.keys(parts.flags ?? {});
+	const env = parts.flags?.["--env"];
+	const flags = CONFIRMATIONS.filter((one) => one.path === path && (one.when === void 0 || named.includes(one.when)) && !(typeof env === "string" && (one.unlessEnv ?? []).includes(env))).map((one) => one.flag);
+	const production = PRODUCTION_CONFIRMS[path];
+	const everyEnvironment = env === void 0 && actsOnEveryEnvironment(path) || actsOnEveryEnvironmentAlways(path);
+	if (typeof production === "string" && (typeof env === "string" && isProduction(env, options) || everyEnvironment)) flags.push(production);
+	const confirm = flags.length === 0 ? "" : ` with its ${[...new Set(flags)].join(" and ")} ${flags.length === 1 ? "phrase" : "phrases"}, which only a person gives,`;
+	const deleted = consequences.filter((one) => one.startsWith("deletes ")).map((one) => one.slice(8));
+	const said = [...deleted.length === 0 ? [] : [`deletes ${deleted.join(" and ")}`], ...consequences.filter((one) => !one.startsWith("deletes "))];
+	return `\`${spell(path, parts)}\`${confirm} ${said.join(" and ")}. That is a person's decision, not a fix.`;
+}
+/**
+* **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.
+*/
+function remedy(path, parts = {}, options = {}) {
+	return remedyOf(path, parts, options);
+}
+/** {@link remedy}, with what a builder knows about where the values came from. */
+function remedyOf(path, parts, options) {
+	if (isCommandPath(path) && consequencesOf(path, parts, options).length > 0) {
+		const sentence = decision(path, parts, options);
+		return {
+			fix: void 0,
+			say: () => sentence
+		};
+	}
+	const command = build(path, parts, options);
+	return {
+		fix: command,
+		say: (wrap) => wrap(command)
+	};
+}
+/** `key=value` entries, by key; an entry with no `=` names nothing. */
+function setEntries(entries) {
+	const list = typeof entries === "string" ? [entries] : Array.isArray(entries) ? entries : [];
+	const values = {};
+	for (const entry of list) {
+		if (typeof entry !== "string") continue;
+		const at = entry.indexOf("=");
+		if (at > 0) values[entry.slice(0, at)] = entry.slice(at + 1);
+	}
+	return values;
+}
+/**
+* **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.
+*/
+function callerOf(path, given, context = {}) {
+	return {
+		path,
+		given,
+		set: setEntries(context.set ?? given.set),
+		answered: new Set(context.answered ?? [])
+	};
+}
+/** The same caller, with what the run settled on its way — a prompt's answers — carried as `--set` too. */
+function settledBy(caller, values) {
+	return {
+		...caller,
+		set: {
+			...caller.set,
+			...values
+		}
+	};
+}
+/** The same caller, with the options its Worker's config answers. */
+function answeredBy(caller, keys) {
+	return {
+		...caller,
+		answered: /* @__PURE__ */ new Set([...caller.answered, ...keys])
+	};
+}
+/**
+* A run again, as parts: each flag the command declares, carried when it was given — a boolean when true, a value
+* when it differs from its default or when its default would change the meaning (`--env`, where the command reads
+* it). A confirmation or a credential is never carried: each is a person's to give again.
+*/
+function rerunParts(caller, options) {
+	const { path, given } = caller;
+	const def = COMMANDS[path];
+	const flags = {};
+	for (const [flag, flagDef] of Object.entries(def.flags)) {
+		if (CONFIRM_FLAGS.includes(flag)) continue;
+		if (CREDENTIAL_FLAGS.includes(flag)) continue;
+		const value = flag === "--set" ? Object.entries(caller.set).map(([key, one]) => `${key}=${one}`) : given[flag.slice(2)];
+		if (flagDef.type === "boolean") {
+			if (value === true) flags[flag] = true;
+			continue;
+		}
+		if (Array.isArray(value)) {
+			const values = value.filter((one) => typeof one === "string" && one.length > 0);
+			if (values.length > 0) flags[flag] = values;
+			continue;
+		}
+		if (typeof value !== "string" || value.length === 0) continue;
+		const onlyWith = MEANING_ONLY_WITH[path];
+		const meaning = MEANING_FLAGS.includes(flag) && (onlyWith === void 0 || given[onlyWith.slice(2)] === true);
+		if (value !== flagDef.default || meaning) flags[flag] = value;
+	}
+	return {
+		args: options.args ?? [],
+		flags: {
+			...flags,
+			...options.flags
+		}
+	};
+}
+/**
+* **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.
+*/
+function rerunCommand(caller, options = {}) {
+	const path = caller.path;
+	if (!isCommandPath(path)) return pithyCommandOf(path);
+	if (Object.hasOwn(DESTRUCTIVE_COMMANDS, path) || Object.hasOwn(PRODUCTION_CONFIRMS, path)) throw new InternalError({ message: `\`${commandName(path)}\` may be a person's decision to run again; name it with rerunRemedy.` });
+	return build(path, rerunParts(caller, options), { given: true });
+}
+/**
+* **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.
+*/
+function rerunRemedy(caller, options = {}) {
+	const { path, given } = caller;
+	if (!isCommandPath(path)) return remedy(path);
+	const found = remedyOf(path, rerunParts(caller, options), {
+		productionEnvironments: options.productionEnvironments ?? [],
+		given: true
+	});
+	const withheld = CREDENTIAL_FLAGS.filter((flag) => {
+		const value = given[flag.slice(2)];
+		return typeof value === "string" && value.length > 0;
+	});
+	const credentials = withheld.join(" and ");
+	if (found.fix === void 0) {
+		const sentence = found.say((command) => command);
+		return {
+			fix: void 0,
+			say: () => withheld.length === 0 ? sentence : `${sentence} It takes the ${credentials} this run was given.`
+		};
+	}
+	const line = withheld.length === 0 ? `\`${found.fix}\`` : `\`${found.fix}\` with the ${credentials} this run was given`;
+	return {
+		fix: found.fix,
+		say: (wrap) => wrap(line)
+	};
+}
+/**
+* **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}.
+*/
+function commandName(path) {
+	return `${CLI} ${path}`;
+}
+/** {@link commandName}, for a path that is a value: refused when the CLI has no such command or group. */
+function commandNameOf(path) {
+	if (!isCommandPath(path) && !isGroupPath(path)) throw new InternalError({ message: `A line names \`pithy ${path}\`, which is not a command.` });
+	return `${CLI} ${path}`;
+}
+/**
+* {@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.
+*/
+function commandNameOfPath(path) {
+	return path.length === 0 ? CLI : commandNameOf(path.join(" "));
+}
+/**
+* **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.
+*/
+function cliAtVersion(version) {
+	return `${CLI} ${version}`;
+}
+/**
+* **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.
+*/
+const PACKAGE_EXEC = {
+	bun: ["bun", "x"],
+	pnpm: ["pnpm", "exec"],
+	yarn: ["yarn"],
+	npm: ["npx"]
+};
+/**
+* **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.
+*/
+function viaPackageManager(pm, command) {
+	return [...PACKAGE_EXEC[pm], command].join(" ");
+}
+/** `a`, `a or b`, `a, b or c`, each in code: commands a reader picks one of. */
+function commandAlternatives(commands) {
+	const coded = commands.map((command) => `\`${command}\``);
+	return coded.length <= 1 ? coded.join("") : `${coded.slice(0, -1).join(", ")} or ${coded.at(-1)}`;
+}
+/** `a`, `a and b`, `a, b and c`, each in code: commands that all run. */
+function commandSequence(commands) {
+	const coded = commands.map((command) => `\`${command}\``);
+	return coded.length <= 1 ? coded.join("") : `${coded.slice(0, -1).join(", ")} and ${coded.at(-1)}`;
+}
+//#endregion
+export { PACKAGE_EXEC, actsOnEveryEnvironment, actsOnEveryEnvironmentAlways, answeredBy, callerOf, cliAtVersion, commandAlternatives, commandFaults, commandFlag, commandName, commandNameOf, commandNameOfPath, commandSequence, consequencesOf, isCommandPath, isGroupPath, personDecision, pithyCommand, pithyCommandOf, remedy, rerunCommand, rerunRemedy, settledBy, viaPackageManager, workerDirOf };