hacksh 0.6.0 → 0.8.0

package/README.md

@@ -57,6 +57,11 @@ gh-pr-commits --help
 gh-pr-commits --version
 ```
 
+`--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
+package version without repeating it in code. `runCommand` does not search the filesystem.
+
 Boolean fields are flags and other fields take a value. Both a schema key and its kebab-case form
 are accepted (`--dryRun` and `--dry-run`). Every boolean flag also accepts a `--no-` prefixed form
 that sets it to `false`, such as `--no-verbose`, which is how a default-on flag is disabled.
@@ -357,6 +362,42 @@ set to `undefined`. Concurrent invocations with different `env` options do not s
 `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.
 
@@ -390,7 +431,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

@@ -1,50 +1,4 @@
 import { $ZodIssue, $ZodObject, output } from "zod/v4/core";
-//#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;
-}
-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";
-});
-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 Exec = <const O extends ExecOptions = {}>(file: string, args?: readonly string[], options?: O & { [K in Exclude<keyof O, keyof ExecOptions>]: never; }) => Promise<ExecReturn<O>>;
-//#endregion
 //#region src/errors.d.ts
 interface HackshIssue {
   arg: string;
@@ -97,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;
@@ -227,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>;
@@ -265,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>;
+//#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[];
 }
-//#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 ExecCommand {
+  file: string;
+  args: readonly string[];
+  cwd: string | undefined;
 }
-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;
+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;
@@ -390,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 Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, 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 };
+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