hacksh 0.11.0 → 0.13.0

package/README.md

@@ -1,7 +1,8 @@
 # hacksh
 
 Define a type-safe command-line interface with a Zod 4 object schema. The same schema parses and
-validates arguments, infers the value passed to `run`, and generates help.
+validates arguments, infers the value passed to `run`, and generates help. Run external commands
+with the context’s `exec`, and use its `logger` for progress and interactive prompts.
 
 The name comes from 拍手 (_hakushu_), the Japanese word for "clap", as a nod to
 [clap](https://github.com/clap-rs/clap), the command-line argument parser for Rust. It is spelled
@@ -30,21 +31,22 @@ import { z } from "zod";
 import { defineCommand, runMain } from "hacksh";
 
 const main = defineCommand({
-  name: "gh-pr-commits",
+  name: "git-summary",
   version: "0.1.0",
-  description: "List commits in a GitHub pull request",
+  description: "Show a commit summary",
   args: z.object({
-    _: z.tuple([
-      z.coerce.number().int().optional().describe("Pull request number").meta({ title: "PR" }),
-    ]),
-    repo: z.string().optional().describe("Repository in OWNER/REPO format"),
-    verbose: z.boolean().default(false).describe("Show details"),
+    _: z.tuple([z.string().default("HEAD").describe("Commit to inspect").meta({ title: "REF" })]),
+    repo: z.string().optional().describe("Repository directory"),
   }),
-  argOptions: { repo: { alias: "R" }, verbose: { alias: ["v", "V"] } },
-  async run({ args, rawArgs, extraArgs, passthrough, logger }) {
-    // args is { _: [number?]; repo?: string; verbose: boolean }
-    logger.info("Loading commits for {repo}", { repo: args.repo ?? "the current repository" });
-    logger.debug("Invocation arguments", { rawArgs, extraArgs, passthrough });
+  argOptions: { repo: { alias: "C" } },
+  async run({ args, exec }) {
+    const [ref] = args._;
+    const { stdout } = await exec(
+      "git",
+      ["show", "--no-patch", "--format=%h %s", "--end-of-options", ref],
+      { cwd: args.repo },
+    );
+    console.log(stdout);
   },
 });
 
@@ -52,11 +54,22 @@ await runMain(main);
 ```
 
 ```sh
-gh-pr-commits 42 -R owner/repo --verbose
-gh-pr-commits --help
-gh-pr-commits --version
+git-summary
+git-summary HEAD~1 -C ./my-repo
+git-summary --help
+git-summary --version
 ```
 
+Use an `async run` handler and its `exec` for external commands. It captures output, removes one
+final newline, throws on failure, and observes invocation cancellation. Pass arguments as an array;
+there is no command string to quote or split. You do not need a `node:child_process` import or a
+custom process wrapper for these behaviors. See [External commands](#external-commands) for expected
+nonzero exits, stdin, and terminal access.
+
+`console.log` above writes the command’s data to stdout. Direct stdout writes are not converted
+to JSON by hacksh’s output mode. Logger events go through the printer; their stream depends on
+the level, so informational logs also share stdout by default.
+
 `--version` is a root-only builtin. It prints the root command's `version`. When the root has
 none, `runMain` resolves the executable (`process.argv[1]`) through symlinks and prints the
 `version` of the nearest ancestor `package.json` that declares one, so a published CLI reports its
@@ -67,8 +80,8 @@ are accepted (`--dryRun` and `--dry-run`). Every boolean flag also accepts a `--
 that sets it to `false`, such as `--no-verbose`, which is how a default-on flag is disabled.
 Boolean flags also accept the explicit forms `--verbose=true` and
 `--verbose=false`; other inline values and values on a negated flag (such as
-`--no-verbose=false`) are validation errors. Value options accept `--repo owner/repo` and
-`--repo=owner/repo`; values such as `false` remain strings for non-boolean fields.
+`--no-verbose=false`) are validation errors. Value options accept `--repo ./my-repo` and
+`--repo=./my-repo`; values such as `false` remain strings for non-boolean fields.
 
 ## Positional arguments
 
@@ -98,8 +111,58 @@ copy out a.txt b.txt   # { _: ["out", "a.txt", "b.txt"] }
 Help and validation errors label each item with its `.meta({ title })`, such as `<DESTINATION>` and
 `[FILES...]`. Untitled items are labeled by position (`ARG1`, `ARG2`, ...) and an untitled rest is
 labeled `ARGS`. Use `z.array` instead of a tuple to accept only variadic values. Without a rest,
-additional positional arguments are kept in `extraArgs`. Unknown options are also kept in
-`extraArgs`; arguments after `--` are kept in `passthrough`.
+additional positional arguments are rejected by default, as are unknown options.
+
+### Unknown arguments and forwarding
+
+A command rejects unknown options and excess positional arguments before its `run` handler or
+schema transforms execute. For ordinary commands, declare the accepted arguments in `args`;
+there is no need to inspect `extraArgs` manually. Errors are `HackshValidationError` instances,
+with each rejected token in `issues[].arg`.
+
+Everything after `--` is always collected unchanged in `passthrough`, independently of this policy.
+Use that explicit boundary when forwarding arguments to another executable:
+
+```ts
+const forward = defineCommand({
+  name: "git-forward",
+  async run({ exec, passthrough }) {
+    const { stdout } = await exec("git", passthrough);
+    console.log(stdout);
+  },
+});
+// git-forward -- status --short
+```
+
+For a wrapper that also accepts undeclared arguments before `--`, set `allowUnknownArgs: true`:
+
+```ts
+const wrapper = defineCommand({
+  allowUnknownArgs: true,
+  async run({ extraArgs, passthrough, exec }) {
+    await exec("some-tool", [...extraArgs, ...passthrough]);
+  },
+});
+```
+
+`extraArgs` preserves the order of unknown option tokens and excess positional values. Unknown
+options do not consume a following value: if the schema has an unfilled positional slot, that
+value fills it. Known options are still parsed and validated. Use `--` when a child's arguments
+must not be interpreted by this command. A handler that does not use `passthrough` ignores those
+arguments; commands that require rejecting them can check `passthrough.length` explicitly.
+
+`allowUnknownArgs` defaults to `false`, inherits down the selected subcommand route, and can be
+overridden by each child. A child's setting does not change validation of its parent's arguments.
+Definitions are not mutated, so reusing a child under another root does not retain inherited settings.
+Standalone `parseArgs` uses the supplied command's setting and does not resolve a parent route.
+
+Once routing succeeds, help and root version output take precedence over argument validation,
+including unknown arguments. Routing errors such as an unknown subcommand still fail. A child's
+undeclared `--version` is an unknown argument, since the version builtin belongs to the root.
+
+**Migrating from 0.11.0:** unknown input was previously accepted by default. Add
+`allowUnknownArgs: true` to commands that intentionally use `extraArgs`, or to their shared parent.
+No migration is needed for `--` forwarding.
 
 ## Argument options
 
@@ -325,21 +388,27 @@ positive `columns` value, the renderer conservatively counts explicit lines only
 Every `run` context has an `exec` function that starts an executable with an argument array. It
 never uses a shell, so spaces, quotes, `$`, `;`, `|`, and `*` in arguments reach the child
 unchanged. By default it resolves with the captured output and rejects with `HackshExecError`
-when the command fails. Pass `reject: false` to receive failures as results instead.
+when the command fails. Pass `reject: false` to receive failures as results instead. Prefer this
+context API to `spawnSync` or a custom subprocess wrapper inside a command handler so execution
+uses the invocation’s environment, cancellation, and printer.
 
 ```ts
-const sync = defineCommand({
-  name: "sync",
+const check = defineCommand({
+  name: "check-head",
   async run({ exec, logger }) {
-    const { stdout: branch } = await exec("git", ["branch", "--show-current"]);
-    const upstream = await exec("git", ["rev-parse", "--abbrev-ref", "@{upstream}"], {
+    const head = await exec("git", ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"], {
       reject: false,
     });
-    if (upstream.status === "failed") {
-      logger.warn("{branch} has no upstream", { branch });
-      return;
+    if (head.status === "failed") {
+      // Only this specific exit means that the revision was not found.
+      if (head.reason === "exit-code" && head.exitCode === 1) {
+        logger.warn("The repository has no HEAD commit");
+        return;
+      }
+      // Missing executables, cancellation, and other failures must still fail the command.
+      throw new Error("Could not inspect HEAD", { cause: head });
     }
-    await exec("git", ["pull", "--ff-only"], { cwd: "/path/to/repo", timeout: 60_000 });
+    logger.info("HEAD is {commit}", { commit: head.stdout });
   },
 });
 ```
@@ -352,10 +421,24 @@ UTF-8 `stdout` and `stderr` with one final newline removed. A failure's `reason`
 gives `ExecSuccess`, while `false` or a `boolean` variable gives `ExecResult`, which must be
 narrowed before reading `exitCode`.
 
+### Working with captured output
+
+Use `stdout` directly for a single value such as a commit ID or repository path. Do not call
+`.trim()` on paths: surrounding whitespace can be part of the name. `exec` already removes one
+final LF or CRLF; it preserves other whitespace and NUL separators.
+
+Interpret structured output according to the child command’s format. If it offers JSON, request
+that format and parse it with `JSON.parse` (and a Zod schema when validation is needed). For Git’s
+`--porcelain -z` output, keep the NUL delimiters and parse the records in a named, application-specific
+helper. Splitting that format on newlines would break paths containing newlines. hacksh does not
+parse Git records or infer whether stdout is text, JSON, or a list.
+
+### Execution options
+
 Options are `cwd`, `env`, `input`, `reject`, `timeout` (milliseconds), `signal` (an
-`AbortSignal`), `maxBuffer` (bytes per stream, default 100,000,000), and `forceKillAfterDelay`
-(milliseconds, default 5,000). Every call also stops with `aborted` when the invocation's `signal`
-aborts. `input` is written to stdin and closed; otherwise stdin is empty.
+`AbortSignal`), `maxBuffer` (bytes per stream, default 100,000,000), `forceKillAfterDelay`
+(milliseconds, default 5,000), and `dryRun`. Every call also stops with `aborted` when the
+invocation's `signal` aborts. `input` is written to stdin and closed; otherwise stdin is empty.
 Output beyond `maxBuffer` is truncated to that many bytes. On timeout, abort, or output limit,
 hacksh sends `SIGTERM` to the child it started and `SIGKILL` after `forceKillAfterDelay`; it does
 not stop grandchildren, and it does not wait for them to close inherited pipes. Invalid arguments
@@ -375,6 +458,18 @@ JSON event has `phase: "start"`, `command` (`file`, `args`, and `cwd` when set),
 in the event, the result's `command`, the `HackshExecError` message, and a `spawn` failure's
 `error`. The child still receives the real values, and its captured output is returned unchanged.
 
+`dryRun: true` does not start the child and does not write `input`. The result is
+`{ status: "skipped", command }` with the redacted command and no `stdout`, `stderr`, or `exitCode`.
+The `exec` event uses `phase: "skip"` and the same command, stdio, and `interactive` flag.
+Pretty output marks that line with `#` instead of `$`. Omit `dryRun`, or pass `false`, to keep
+today's success or failure result. A boolean `dryRun` returns the union of a skip and the executed
+result, so narrow `status` before reading output. `reject` does not apply to a skip. An invocation
+signal that is already aborted still fails as `aborted` before any skip event, and `reject` applies
+to that failure. Option checks still run, including `input` together with `stdin: "inherit"`.
+JSON mode, a non-interactive environment, and a busy terminal still show the plan and return
+a skip. `display: false` hides the skip event. `dryRun` is not read from CLI flags or
+`context.args`.
+
 ```ts
 await exec("git", ["worktree", "add", path, branch], { cwd: repository });
 await exec("gh", ["auth", "login", "--with-token"], { input: token, display: false });

package/dist/index.d.ts

@@ -242,7 +242,7 @@ interface PromptPrintEvent {
 }
 interface ExecPrintEvent {
   type: "exec";
-  phase: "start";
+  phase: "start" | "skip";
   command: Omit<ExecCommand, "cwd"> & {
     cwd?: string;
   };
@@ -308,6 +308,7 @@ interface ExecOptions {
   interactive?: boolean;
   display?: boolean;
   redact?: readonly string[];
+  dryRun?: boolean;
 }
 interface ExecCommand {
   file: string;
@@ -342,7 +343,22 @@ type ExecFailure = {
 });
 type ExecFailureReason = ExecFailure["reason"];
 type ExecResult = ExecSuccess | ExecFailure;
-type ExecReturn<O extends ExecOptions> = "reject" extends keyof O ? false extends O["reject"] ? ExecResult : ExecSuccess : ExecSuccess;
+interface ExecSkipped {
+  status: "skipped";
+  command: ExecCommand;
+}
+type ExecOutcome<O extends ExecOptions> = "reject" extends keyof O ? false extends O["reject"] ? ExecResult : ExecSuccess : ExecSuccess;
+type SpecifiedDryRun<O> = "dryRun" extends keyof O ? O["dryRun"] : false;
+type ReturnsFailure<O extends ExecOptions> = "reject" extends keyof O ? false extends O["reject"] ? true : false : false;
+type AbortedFailure = {
+  status: "failed";
+  command: ExecCommand;
+  stdout: string;
+  stderr: string;
+  reason: "aborted";
+};
+type DefiniteSkip<O extends ExecOptions> = ReturnsFailure<O> extends true ? ExecSkipped | AbortedFailure : ExecSkipped;
+type ExecReturn<O extends ExecOptions> = true extends SpecifiedDryRun<O> ? false extends SpecifiedDryRun<O> ? ExecSkipped | ExecOutcome<O> : undefined extends SpecifiedDryRun<O> ? ExecSkipped | ExecOutcome<O> : DefiniteSkip<O> : ExecOutcome<O>;
 type RejectInheritedInput<O> = O extends {
   input: string;
   stdin: "inherit";
@@ -379,6 +395,8 @@ interface CommandDef<S extends ArgsSchema = EmptyArgs> {
   version?: string;
   description?: string;
   hidden?: boolean;
+  /** Keep unknown options and excess positionals in extraArgs. Inherits from the parent; defaults to false. */
+  allowUnknownArgs?: boolean;
   args?: S;
   argOptions?: ArgOptionsMap<S>;
   subCommands?: Record<string, CommandDef<ArgsSchema>>;
@@ -422,5 +440,5 @@ interface RunMainOptions extends OutputOptions {
 declare function runMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): Promise<void>;
 declare function createMain<S extends ArgsSchema>(command: CommandDef<S>, options?: RunMainOptions): (argv?: string[]) => Promise<void>;
 //#endregion
-export { type ArgOptions, type ArgOptionsMap, type CommandContext, type CommandDef, type ConfirmOptions, type ConfirmPromptState, type ErrorPrintEvent, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecPrintEvent, type ExecResult, type ExecReturn, type ExecSuccess, type HackshErrorKind, type HackshErrorSummary, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type JsonPrinterOptions, type LogKind, type LogLevel, type LogPrintEvent, type LogProperties, type LogRecord, type Logger, type OutputFormat, type OutputMode, type OutputOptions, type OutputPreference, type OutputWriter, type PrettyPrinterOptions, type PrintEvent, type PrintStream, type Printer, type PromptChoiceState, type PromptErrorDetails, type PromptKind, type PromptPrintEvent, type PromptState, type PromptStatus, type Prompter, type ResolveOutputModeOptions, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type SelectPromptState, type ShowUsageCallback, type ShowUsageOptions, type StreamPrinterOptions, type TerminalInput, type TerminalOutput, type TextOptions, type TextPromptState, type UsageArgumentSummary, type UsageCommandSummary, type UsageOptionSummary, type UsageOutput, type UsagePrintEvent, type UsageSummary, type UsageWriter, type ValidationIssueSummary, type VersionPrintEvent, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
+export { type ArgOptions, type ArgOptionsMap, type CommandContext, type CommandDef, type ConfirmOptions, type ConfirmPromptState, type ErrorPrintEvent, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecPrintEvent, type ExecResult, type ExecReturn, type ExecSkipped, type ExecSuccess, type HackshErrorKind, type HackshErrorSummary, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type JsonPrinterOptions, type LogKind, type LogLevel, type LogPrintEvent, type LogProperties, type LogRecord, type Logger, type OutputFormat, type OutputMode, type OutputOptions, type OutputPreference, type OutputWriter, type PrettyPrinterOptions, type PrintEvent, type PrintStream, type Printer, type PromptChoiceState, type PromptErrorDetails, type PromptKind, type PromptPrintEvent, type PromptState, type PromptStatus, type Prompter, type ResolveOutputModeOptions, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type SelectPromptState, type ShowUsageCallback, type ShowUsageOptions, type StreamPrinterOptions, type TerminalInput, type TerminalOutput, type TextOptions, type TextPromptState, type UsageArgumentSummary, type UsageCommandSummary, type UsageOptionSummary, type UsageOutput, type UsagePrintEvent, type UsageSummary, type UsageWriter, type ValidationIssueSummary, type VersionPrintEvent, consolePrinter, createJsonPrinter, createMain, createPrettyPrinter, createStreamPrinter, defineCommand, parseArgs, renderUsage, resolveOutputMode, runCommand, runMain, showUsage, summarizeUsage };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -108,6 +108,7 @@ function schemaShape(schema) {
 //#endregion
 //#region src/command.ts
 function defineCommand(def) {
+	if (def.allowUnknownArgs !== void 0 && typeof def.allowUnknownArgs !== "boolean") throw new TypeError("allowUnknownArgs must be a boolean");
 	const shape = def.args ? schemaShape(def.args) : {};
 	const positionals = readPositionals(shape);
 	if (positionals) {
@@ -611,6 +612,10 @@ async function parseCommandArgs(command, rawArgs, tokenized = tokenizeCommandArg
 	else if (token.kind === "unknown-option") extraArgs.push(token.value);
 	else if (positionals && (positionals.rest || positionalValues.length < positionals.items.length)) positionalValues.push(token.value);
 	else extraArgs.push(token.value);
+	if (!command.allowUnknownArgs && extraArgs.length > 0) throw new HackshValidationError(command, extraArgs.map((arg) => ({
+		arg,
+		message: "unexpected argument"
+	})));
 	const envSources = /* @__PURE__ */ new Map();
 	if (env && command.args) {
 		const shape = schemaShape(command.args);
@@ -689,7 +694,8 @@ const OPTION_KEYS = /* @__PURE__ */ new Set([
 	"stderr",
 	"interactive",
 	"display",
-	"redact"
+	"redact",
+	"dryRun"
 ]);
 const MAX_DELAY = 2147483647;
 const REFUSAL_MESSAGE = {
@@ -809,7 +815,8 @@ function parsePlan(file, args, options, context) {
 		stderr,
 		interactive: raw.interactive === void 0 ? false : readBoolean(raw.interactive, "interactive"),
 		display: raw.display === void 0 ? true : readBoolean(raw.display, "display"),
-		redact
+		redact,
+		dryRun: raw.dryRun === void 0 ? false : readBoolean(raw.dryRun, "dryRun")
 	};
 }
 function stripFinalNewline(text) {
@@ -877,6 +884,23 @@ function toResult(command, outcome, stdout, stderr) {
 function isSpawnErrno(error) {
 	return error instanceof Error && "syscall" in error;
 }
+function execEvent(plan, phase) {
+	const { file, args, cwd } = plan.reported;
+	return {
+		type: "exec",
+		phase,
+		command: cwd === void 0 ? {
+			file,
+			args
+		} : {
+			file,
+			args,
+			cwd
+		},
+		stdio: commandStdio(plan),
+		interactive: plan.interactive
+	};
+}
 function commandStdio(plan) {
 	return {
 		stdin: plan.stdin === "inherit" ? "inherit" : plan.input === void 0 ? "ignore" : "input",
@@ -1015,29 +1039,20 @@ function blockedReason(plan, context, stdio) {
 async function execute(file, args, options, context) {
 	const plan = parsePlan(file, args, options, context);
 	if (plan.signal.aborted) return complete(plan, emptyFailure(plan, "aborted"));
+	if (plan.dryRun) {
+		if (plan.display) await context.print(execEvent(plan, "skip"));
+		return {
+			status: "skipped",
+			command: plan.reported
+		};
+	}
 	const stdio = commandStdio(plan);
 	const blocked = blockedReason(plan, context, stdio);
 	if (blocked) return complete(plan, emptyFailure(plan, blocked));
 	const holdTerminal = usesTerminal(plan, stdio);
 	if (holdTerminal && !context.terminal.acquire("exec")) return complete(plan, emptyFailure(plan, "overlapping"));
 	try {
-		if (plan.display) {
-			const { file, args, cwd } = plan.reported;
-			await context.print({
-				type: "exec",
-				phase: "start",
-				command: cwd === void 0 ? {
-					file,
-					args
-				} : {
-					file,
-					args,
-					cwd
-				},
-				stdio,
-				interactive: plan.interactive
-			});
-		}
+		if (plan.display) await context.print(execEvent(plan, "start"));
 		return complete(plan, await runPlan(plan));
 	} finally {
 		if (holdTerminal) context.terminal.release();
@@ -1187,7 +1202,7 @@ function formatTextEvent(event) {
 		case "error": return event.error.kind === "usage" || event.error.kind === "validation" ? event.error.message : `Error: ${event.error.message}`;
 		case "log": return event.record.message;
 		case "prompt": return event.prompt.message;
-		case "exec": return `$ ${formatExecCommand(event.command)}`;
+		case "exec": return `${event.phase === "skip" ? "#" : "$"} ${formatExecCommand(event.command)}`;
 	}
 }
 /** Undecorated console compatibility adapter; automatic output uses the selected format printer. */
@@ -1278,7 +1293,8 @@ const unicodeSymbols = {
 		version: "●",
 		errorEvent: "■",
 		prompt: "?",
-		exec: "$"
+		exec: "$",
+		execSkip: "#"
 	}
 };
 const asciiSymbols = {
@@ -1296,7 +1312,8 @@ const asciiSymbols = {
 		version: "i",
 		errorEvent: "x",
 		prompt: "?",
-		exec: "$"
+		exec: "$",
+		execSkip: "#"
 	}
 };
 const markStyles = {
@@ -1316,7 +1333,8 @@ const markStyles = {
 	version: "blue",
 	errorEvent: "red",
 	prompt: "cyan",
-	exec: "gray"
+	exec: "gray",
+	execSkip: "gray"
 };
 function safelyInspect(value) {
 	if (typeof value === "string") return value;
@@ -1363,7 +1381,7 @@ function eventMark(event) {
 	if (event.type === "version") return "version";
 	if (event.type === "error") return "errorEvent";
 	if (event.type === "prompt") return event.prompt.status === "submitted" ? "success" : "prompt";
-	if (event.type === "exec") return "exec";
+	if (event.type === "exec") return event.phase === "skip" ? "execSkip" : "exec";
 	return event.record.kind === "message" ? event.record.level : event.record.kind;
 }
 function eventLines(event) {
@@ -2067,7 +2085,8 @@ function resolveCommand(root, rawArgs) {
 		const parentPath = commandEnvPath(command);
 		command = {
 			...child,
-			name: child.name ?? key
+			name: child.name ?? key,
+			allowUnknownArgs: child.allowUnknownArgs ?? command.allowUnknownArgs
 		};
 		registerCommandPath(command, parentPath === void 0 ? void 0 : [...parentPath, key]);
 		remaining = remaining.slice(index + 1);