hacksh 0.5.4 → 0.7.0

package/README.md

@@ -311,6 +311,94 @@ Physical rows are calculated from explicit newlines, ANSI-free Unicode display w
 `stdout.columns`, including terminal wrapping. When a custom output writer does not expose a
 positive `columns` value, the renderer conservatively counts explicit lines only.
 
+## External commands
+
+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.
+
+```ts
+const sync = defineCommand({
+  name: "sync",
+  async run({ exec, logger }) {
+    const { stdout: branch } = await exec("git", ["branch", "--show-current"]);
+    const upstream = await exec("git", ["rev-parse", "--abbrev-ref", "@{upstream}"], {
+      reject: false,
+    });
+    if (upstream.status === "failed") {
+      logger.warn("{branch} has no upstream", { branch });
+      return;
+    }
+    await exec("git", ["pull", "--ff-only"], { cwd: "/path/to/repo", timeout: 60_000 });
+  },
+});
+```
+
+Results have `status` `"succeeded"` or `"failed"`, the `command` (`file`, `args`, `cwd`), and
+UTF-8 `stdout` and `stderr` with one final newline removed. A failure's `reason` is `exit-code`
+(with `exitCode`), `signal` (a signal the child received from elsewhere, with `signal`), `spawn`
+(the executable or cwd could not be used, with `error`), or one of `timeout`, `aborted`, and
+`output-limit` when hacksh stopped the child. The return type follows `reject`: omitted or `true`
+gives `ExecSuccess`, while `false` or a `boolean` variable gives `ExecResult`, which must be
+narrowed before reading `exitCode`.
+
+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). `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
+or options reject with `TypeError` without starting anything, even with `reject: false`.
+
+The child's environment starts from the invocation's `env` option on `runCommand` or `runMain`, or
+from `process.env` when that is absent. The `env` option on `exec` sets variables and removes those
+set to `undefined`. Concurrent invocations with different `env` options do not share settings.
+`HackshExecError` messages include the command and the reason but never the child's output; read
+`error.result` for the full failure, which error summaries and JSON error events omit.
+
+Before starting a child, `exec` prints an `exec` event through the invocation's printer, on stderr
+in both formats. Pretty output shows `$` followed by the command line and, when set, its `cwd`. The
+JSON event has `phase: "start"`, `command` (`file`, `args`, and `cwd` when set), `stdio`, and
+`interactive`; it never includes `env` or `input`. Pass `display: false` to hide one call. Pass
+`redact` with secret values to replace every occurrence in the file, arguments, and cwd with `***`
+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.
+
+```ts
+await exec("git", ["worktree", "add", path, branch], { cwd: repository });
+await exec("gh", ["auth", "login", "--with-token"], { input: token, display: false });
+await exec("curl", ["-H", `Authorization: Bearer ${token}`, url], { redact: [token] });
+```
+
+Child output is captured by default and never written to the terminal by hacksh. Set `stdin`,
+`stdout`, or `stderr` to `"inherit"` to hand that stream of the parent process to the child; an
+inherited stream bypasses the printer and any `stdout`/`stderr` writers given to `runMain` or
+`runCommand`, and its result field is `""`. `input` cannot be combined with `stdin: "inherit"`.
+Set `interactive: true` when the child talks to the user through the terminal, including tools
+that open `/dev/tty` themselves; hacksh cannot detect that, and it does not create a PTY.
+
+```ts
+// Select a row: the table goes to stdin, the selection comes back on stdout.
+const { stdout: picked } = await exec("fzf", [], { input: table, interactive: true });
+// Hand the whole terminal to a long-running command.
+await exec("gh", ["run", "watch", id], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+```
+
+These calls fail before starting the child, without an `exec` event, and follow `reject` like any
+other failure: `json-output` when a stream is inherited in JSON mode, `non-interactive` when
+`interactive: true` is used outside an interactive mode (the same rule as prompts), and
+`overlapping` when a call that uses the terminal (interactive or inheriting a stream) starts while
+a prompt or another such call is active. A prompt started during such a call fails with
+`HackshPromptError` reason `overlapping`. Captured calls can run alongside prompts. Signals such
+as Ctrl-C reach the whole foreground process group; hacksh does not forward them or manage jobs.
+
+On Deno, `exec` needs `--allow-run` and unscoped `--allow-env`, because Deno's `node:child_process`
+reads the whole environment to start a process.
+
+To test a command without starting processes, call its `run` with a context whose `exec` is your own
+function of type `Exec`.
+
 ## Output formats
 
 `runMain` and `runCommand` resolve one output mode before command routing, parsing, or execution.
@@ -338,7 +426,8 @@ capabilities. A stream without those readable operations fails with an `input-er
 is attempted.
 
 JSON output contains exactly one `PrintEvent` object per line. Help and version events and
-trace/debug/info logs go to stdout; errors and warning/error/fatal logs go to stderr. Usage attached
+trace/debug/info logs go to stdout; errors, warning/error/fatal logs, and `exec` events go to
+stderr. Usage attached
 to an error retains its `stderr` stream. Every log level is emitted by default. JSON strings have
 terminal control sequences removed, and the printer never serializes executable command or Zod
 schema objects.

package/dist/index.d.ts

@@ -26,6 +26,12 @@ declare class HackshPromptError extends Error {
   readonly prompt: PromptErrorDetails;
   constructor(reason: HackshPromptErrorReason, prompt: PromptErrorDetails, message: string, options?: ErrorOptions);
 }
+/** An external command that did not succeed; `result` is not enumerable so error summaries omit child output. */
+declare class HackshExecError extends Error {
+  #private;
+  constructor(message: string, result: ExecFailure, options?: ErrorOptions);
+  get result(): ExecFailure;
+}
 type HackshErrorKind = "error" | "prompt" | "usage" | "validation" | "thrown";
 interface ValidationIssueSummary {
   arg: string;
@@ -45,6 +51,60 @@ interface HackshErrorSummary {
   value?: unknown;
 }
 //#endregion
+//#region src/prompts.d.ts
+interface SelectOption<T extends string> {
+  value: T;
+  label?: string;
+  hint?: string;
+}
+interface SelectOptions<T extends string> {
+  message: string;
+  options: readonly SelectOption<T>[];
+  initialValue?: T;
+}
+interface ConfirmOptions {
+  message: string;
+  initialValue?: boolean;
+}
+interface TextOptions {
+  message: string;
+  placeholder?: string;
+  validate?(value: string): string | undefined;
+}
+interface Prompter {
+  select<const T extends string>(options: SelectOptions<T>): Promise<T>;
+  confirm(options: ConfirmOptions): Promise<boolean>;
+  text(options: TextOptions): Promise<string>;
+}
+//#endregion
+//#region src/logger.d.ts
+type LogLevel = "trace" | "debug" | "info" | "warning" | "error" | "fatal";
+type LogKind = "message" | "step" | "success";
+type LogProperties = Record<string, unknown>;
+/** A structured message emitted by a command's logger. */
+interface LogRecord {
+  level: LogLevel;
+  kind: LogKind;
+  category: readonly string[];
+  message: string;
+  rawMessage: string;
+  properties: LogProperties;
+  timestamp: number;
+}
+interface Logger extends Prompter {
+  readonly category: readonly string[];
+  trace(message: string, properties?: LogProperties): void;
+  debug(message: string, properties?: LogProperties): void;
+  info(message: string, properties?: LogProperties): void;
+  warn(message: string, properties?: LogProperties): void;
+  error(message: string | Error, properties?: LogProperties): void;
+  fatal(message: string | Error, properties?: LogProperties): void;
+  step(message: string, properties?: LogProperties): void;
+  success(message: string, properties?: LogProperties): void;
+  with(properties: LogProperties): Logger;
+  getChild(category: string): Logger;
+}
+//#endregion
 //#region src/output.d.ts
 interface OutputOptions {
   output?: OutputPreference;
@@ -175,8 +235,21 @@ interface PromptPrintEvent {
   type: "prompt";
   prompt: PromptState;
 }
+interface ExecPrintEvent {
+  type: "exec";
+  phase: "start";
+  command: Omit<ExecCommand, "cwd"> & {
+    cwd?: string;
+  };
+  stdio: {
+    stdin: "ignore" | "input" | "inherit";
+    stdout: "pipe" | "inherit";
+    stderr: "pipe" | "inherit";
+  };
+  interactive: boolean;
+}
 /** A semantic, command- and schema-free output value emitted by hacksh. */
-type PrintEvent = UsagePrintEvent | VersionPrintEvent | ErrorPrintEvent | LogPrintEvent | PromptPrintEvent;
+type PrintEvent = UsagePrintEvent | VersionPrintEvent | ErrorPrintEvent | LogPrintEvent | PromptPrintEvent | ExecPrintEvent;
 /** Receives every output event produced by one command invocation. */
 interface Printer {
   print(event: PrintEvent): void | Promise<void>;
@@ -213,59 +286,63 @@ declare function createStreamPrinter(options: StreamPrinterOptions): Printer;
 /** Create a one-semantic-event-per-line JSON printer. */
 declare function createJsonPrinter(options?: JsonPrinterOptions): Printer;
 //#endregion
-//#region src/prompts.d.ts
-interface SelectOption<T extends string> {
-  value: T;
-  label?: string;
-  hint?: string;
-}
-interface SelectOptions<T extends string> {
-  message: string;
-  options: readonly SelectOption<T>[];
-  initialValue?: T;
-}
-interface ConfirmOptions {
-  message: string;
-  initialValue?: boolean;
-}
-interface TextOptions {
-  message: string;
-  placeholder?: string;
-  validate?(value: string): string | undefined;
-}
-interface Prompter {
-  select<const T extends string>(options: SelectOptions<T>): Promise<T>;
-  confirm(options: ConfirmOptions): Promise<boolean>;
-  text(options: TextOptions): Promise<string>;
-}
-//#endregion
-//#region src/logger.d.ts
-type LogLevel = "trace" | "debug" | "info" | "warning" | "error" | "fatal";
-type LogKind = "message" | "step" | "success";
-type LogProperties = Record<string, unknown>;
-/** A structured message emitted by a command's logger. */
-interface LogRecord {
-  level: LogLevel;
-  kind: LogKind;
-  category: readonly string[];
-  message: string;
-  rawMessage: string;
-  properties: LogProperties;
-  timestamp: number;
-}
-interface Logger extends Prompter {
-  readonly category: readonly string[];
-  trace(message: string, properties?: LogProperties): void;
-  debug(message: string, properties?: LogProperties): void;
-  info(message: string, properties?: LogProperties): void;
-  warn(message: string, properties?: LogProperties): void;
-  error(message: string | Error, properties?: LogProperties): void;
-  fatal(message: string | Error, properties?: LogProperties): void;
-  step(message: string, properties?: LogProperties): void;
-  success(message: string, properties?: LogProperties): void;
-  with(properties: LogProperties): Logger;
-  getChild(category: string): Logger;
-}
+//#region src/exec.d.ts
+type Environment = Readonly<Record<string, string | undefined>>;
+interface ExecOptions {
+  cwd?: string;
+  env?: Environment;
+  input?: string;
+  reject?: boolean;
+  timeout?: number;
+  signal?: AbortSignal;
+  maxBuffer?: number;
+  forceKillAfterDelay?: number;
+  stdin?: "pipe" | "inherit";
+  stdout?: "pipe" | "inherit";
+  stderr?: "pipe" | "inherit";
+  interactive?: boolean;
+  display?: boolean;
+  redact?: readonly string[];
+}
+interface ExecCommand {
+  file: string;
+  args: readonly string[];
+  cwd: string | undefined;
+}
+interface ExecSuccess {
+  status: "succeeded";
+  command: ExecCommand;
+  stdout: string;
+  stderr: string;
+  exitCode: 0;
+}
+type ExecFailure = {
+  status: "failed";
+  command: ExecCommand;
+  stdout: string;
+  stderr: string;
+} & ({
+  reason: "exit-code";
+  exitCode: number;
+} | {
+  reason: "signal";
+  signal: string;
+} | {
+  reason: "spawn";
+  error: Error;
+} | {
+  reason: "timeout" | "aborted" | "output-limit";
+} | {
+  reason: "json-output" | "non-interactive" | "overlapping";
+});
+type ExecFailureReason = ExecFailure["reason"];
+type ExecResult = ExecSuccess | ExecFailure;
+type ExecReturn<O extends ExecOptions> = "reject" extends keyof O ? false extends O["reject"] ? ExecResult : ExecSuccess : ExecSuccess;
+type RejectInheritedInput<O> = O extends {
+  input: string;
+  stdin: "inherit";
+} ? never : unknown;
+type Exec = <const O extends ExecOptions = {}>(file: string, args?: readonly string[], options?: O & { [K in Exclude<keyof O, keyof ExecOptions>]: never; } & RejectInheritedInput<O>) => Promise<ExecReturn<O>>;
 //#endregion
 //#region src/schema.d.ts
 type ArgsSchema = $ZodObject;
@@ -289,6 +366,7 @@ interface CommandContext<S extends ArgsSchema> {
   passthrough: string[];
   extraArgs: string[];
   logger: Logger;
+  exec: Exec;
 }
 interface CommandDef<S extends ArgsSchema = EmptyArgs> {
   name?: string;
@@ -337,5 +415,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 HackshErrorKind, type HackshErrorSummary, 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 ExecSuccess, type HackshErrorKind, type HackshErrorSummary, HackshExecError, 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