hacksh 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -1,410 +1,5 @@
-import { $ZodIssue, $ZodObject, output } from "zod/v4/core";
-//#region src/errors.d.ts
-interface HackshIssue {
-  arg: string;
-  message: string;
-  issue?: $ZodIssue;
-}
-declare class HackshUsageError extends Error {
-  readonly command: AnyCommandDef;
-  constructor(message: string, command: AnyCommandDef, options?: ErrorOptions);
-}
-declare class HackshValidationError extends HackshUsageError {
-  readonly issues: ReadonlyArray<HackshIssue>;
-  constructor(command: AnyCommandDef, issues: ReadonlyArray<HackshIssue>);
-}
-type PromptKind = "select" | "confirm" | "text";
-type HackshPromptErrorReason = "non-interactive" | "cancelled" | "aborted" | "eof" | "overlapping" | "invalid-options" | "input-error" | "printer-error";
-interface PromptErrorDetails {
-  kind: PromptKind;
-  message: string;
-  choices?: readonly string[];
-}
-/** An input request that could not be completed safely. */
-declare class HackshPromptError extends Error {
-  readonly reason: HackshPromptErrorReason;
-  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;
-}
-/** A requested process exit status; `runMain` exits with it and reports only a non-empty message. */
-declare class HackshExitError extends Error {
-  readonly exitCode: number;
-  constructor(exitCode: number, message?: string, options?: ErrorOptions);
-}
-type HackshErrorKind = "error" | "prompt" | "usage" | "validation" | "thrown";
-interface ValidationIssueSummary {
-  arg: string;
-  message: string;
-  code?: string;
-  path?: readonly PropertyKey[];
-  details?: Readonly<Record<string, unknown>>;
-}
-interface HackshErrorSummary {
-  kind: HackshErrorKind;
-  name: string;
-  message: string;
-  stack?: string;
-  cause?: unknown;
-  issues?: readonly ValidationIssueSummary[];
-  properties?: Readonly<Record<string, unknown>>;
-  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;
-  /** Use Unicode presentation symbols in pretty output. Defaults to true. */
-  unicode?: boolean;
-  env?: Readonly<Record<string, string | undefined>>;
-  stdin?: TerminalInput;
-  stdout?: TerminalOutput;
-  stderr?: OutputWriter;
-}
-//#endregion
-//#region src/usage.d.ts
-interface UsageArgumentSummary {
-  name: string;
-  required: boolean;
-  variadic: boolean;
-  description?: string;
-  choices?: readonly string[];
-  defaultValue?: unknown;
-}
-interface UsageOptionSummary {
-  name: string;
-  flags: readonly string[];
-  takesValue: boolean;
-  /** Whether the long flag also accepts a `--no-` prefixed form. */
-  negatable: boolean;
-  valueName?: string;
-  required: boolean;
-  description?: string;
-  choices?: readonly string[];
-  defaultValue?: unknown;
-  env?: string;
-}
-interface UsageCommandSummary {
-  name: string;
-  description?: string;
-}
-/** A schema-free description of the useful help metadata for a command. */
-interface UsageSummary {
-  name: string;
-  heading?: string;
-  version?: string;
-  description?: string;
-  synopsis: string;
-  arguments: readonly UsageArgumentSummary[];
-  options: readonly UsageOptionSummary[];
-  commands: readonly UsageCommandSummary[];
-}
-/** Build a serializable help summary without retaining command or schema objects. */
-declare function summarizeUsage(command: AnyCommandDef): UsageSummary;
-type UsageWriter = (text: string) => void | Promise<void>;
-interface ShowUsageOptions extends OutputOptions {
-  write?: UsageWriter;
-  printer?: Printer;
-  stream?: PrintStream;
-}
-type UsageOutput = Required<Pick<ShowUsageOptions, "write">>;
-type ShowUsageCallback = (command: AnyCommandDef, output: UsageOutput) => void | Promise<void>;
-/** Generate usage text without writing to stdout or stderr. */
-declare function renderUsage(command: AnyCommandDef): Promise<string>;
-/** Generate and write usage text, awaiting asynchronous writers. */
-declare function showUsage(command: AnyCommandDef, options?: ShowUsageOptions): Promise<void>;
-//#endregion
-//#region src/printer.d.ts
-type PrintStream = "stdout" | "stderr";
-type OutputPreference = "auto" | "pretty" | "json";
-type OutputFormat = Exclude<OutputPreference, "auto">;
-interface OutputMode {
-  format: OutputFormat;
-  interactive: boolean;
-  color: boolean;
-}
-interface ResolveOutputModeOptions {
-  output?: OutputPreference;
-  env?: Readonly<Record<string, string | undefined>>;
-  inputIsTTY?: boolean;
-  outputIsTTY?: boolean;
-}
-/** Resolve output behavior once, before command routing or argument parsing. */
-declare function resolveOutputMode(options?: ResolveOutputModeOptions): OutputMode;
-interface UsagePrintEvent {
-  type: "usage";
-  usage: UsageSummary;
-  text: string;
-  stream: PrintStream;
-}
-interface VersionPrintEvent {
-  type: "version";
-  version: string;
-}
-interface ErrorPrintEvent {
-  type: "error";
-  error: HackshErrorSummary;
-}
-interface LogPrintEvent {
-  type: "log";
-  record: LogRecord;
-}
-interface PromptChoiceState {
-  value: string;
-  label: string;
-  hint?: string;
-  selected: boolean;
-}
-type PromptStatus = "active" | "error" | "submitted" | "closed";
-interface PromptStateBase {
-  message: string;
-  status: PromptStatus;
-  error?: string;
-}
-interface SelectPromptState extends PromptStateBase {
-  kind: "select";
-  choices: readonly PromptChoiceState[];
-  value: string;
-}
-interface ConfirmPromptState extends PromptStateBase {
-  kind: "confirm";
-  value: boolean;
-  defaultValue?: boolean;
-}
-interface TextPromptState extends PromptStateBase {
-  kind: "text";
-  value: string;
-  placeholder?: string;
-}
-type PromptState = SelectPromptState | ConfirmPromptState | TextPromptState;
-interface PromptPrintEvent {
-  type: "prompt";
-  prompt: PromptState;
-}
-interface ExecPrintEvent {
-  type: "exec";
-  phase: "start" | "skip";
-  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 | ExecPrintEvent;
-/** Receives every output event produced by one command invocation. */
-interface Printer {
-  print(event: PrintEvent): void | Promise<void>;
-}
-/** Undecorated console compatibility adapter; automatic output uses the selected format printer. */
-declare const consolePrinter: Printer;
-interface OutputWriter {
-  write(text: string): unknown;
-}
-interface TerminalInput {
-  readonly isTTY?: boolean;
-  readonly isRaw?: boolean;
-  readonly readableFlowing?: boolean | null;
-  setRawMode?(mode: boolean): unknown;
-  resume(): unknown;
-  pause(): unknown;
-  on(event: string, listener: (...args: never[]) => void): unknown;
-  removeListener(event: string, listener: (...args: never[]) => void): unknown;
-}
-interface TerminalOutput extends OutputWriter {
-  readonly isTTY?: boolean;
-  readonly columns?: number;
-}
-interface JsonPrinterOptions {
-  stdout?: OutputWriter;
-  stderr?: OutputWriter;
-}
-interface StreamPrinterOptions {
-  stdout: OutputWriter;
-  stderr: OutputWriter;
-}
-/** Create an undecorated stream-backed compatibility adapter. */
-declare function createStreamPrinter(options: StreamPrinterOptions): Printer;
-/** Create a one-semantic-event-per-line JSON printer. */
-declare function createJsonPrinter(options?: JsonPrinterOptions): Printer;
-//#endregion
-//#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[];
-  dryRun?: boolean;
-}
-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;
-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";
-} ? 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;
-type EmptyArgs = $ZodObject<{}>;
-type ShapeOf<S extends ArgsSchema> = S["_zod"]["def"]["shape"];
-type ArgKey<S extends ArgsSchema> = Extract<keyof ShapeOf<S>, string>;
-type OptionKey<S extends ArgsSchema> = Exclude<ArgKey<S>, typeof POSITIONALS_KEY>;
-declare const POSITIONALS_KEY = "_";
-//#endregion
-//#region src/command.d.ts
-interface ArgOptions {
-  alias?: string | readonly string[];
-  valueName?: string;
-  env?: string | false;
-}
-type ArgOptionsMap<S extends ArgsSchema> = Partial<Record<OptionKey<S>, ArgOptions>>;
-interface CommandContext<S extends ArgsSchema> {
-  cmd: CommandDef<S>;
-  args: output<S>;
-  rawArgs: string[];
-  passthrough: string[];
-  extraArgs: string[];
-  logger: Logger;
-  exec: Exec;
-  signal: AbortSignal;
-}
-interface CommandDef<S extends ArgsSchema = EmptyArgs> {
-  name?: string;
-  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>>;
-  run?(context: CommandContext<S>): unknown;
-}
-type AnyCommandDef = CommandDef<ArgsSchema>;
-declare function defineCommand<S extends ArgsSchema = EmptyArgs>(def: CommandDef<S>): CommandDef<S>;
-//#endregion
+import { D as OutputPreference, G as ShowUsageOptions, O as OutputWriter, Q as summarizeUsage, R as TerminalInput, X as renderUsage, Z as showUsage, _ as ExecReturn, a as ArgsSchema, c as SelectOption, ct as HackshIssue, d as Exec, dt as HackshUsageError, f as ExecCommand, ft as HackshValidationError, g as ExecResult, h as ExecOptions, i as defineCommand, j as Printer, l as SelectOptions, lt as HackshPromptError, m as ExecFailureReason, mt as PromptKind, n as CommandContext, o as ConfirmOptions, ot as HackshExecError, p as ExecFailure, pt as PromptErrorDetails, r as CommandDef, rt as Logger, s as Prompter, st as HackshExitError, t as AnyCommandDef, u as TextOptions, ut as HackshPromptErrorReason, v as ExecSkipped, y as ExecSuccess, z as TerminalOutput } from "./command-pPKGCjNA.js";
+import { output } from "zod/v4/core";
 //#region src/parser.d.ts
 /**
  * Parse and validate one command segment without routing, builtin handling, or output.
@@ -414,31 +9,35 @@ declare function parseArgs<S extends ArgsSchema>(command: CommandDef<S>, argv: s
   readonly env?: Readonly<Record<string, string | undefined>>;
 }): Promise<output<S>>;
 //#endregion
-//#region src/pretty.d.ts
-interface PrettyPrinterOptions {
-  color: boolean;
-  unicode: boolean;
+//#region src/output.d.ts
+interface OutputOptions {
+  output?: OutputPreference;
+  /** Use Unicode presentation symbols in pretty output. Defaults to true. */
+  unicode?: boolean;
+  env?: Readonly<Record<string, string | undefined>>;
+  stdin?: TerminalInput;
   stdout?: TerminalOutput;
   stderr?: OutputWriter;
 }
-/** Create the fixed human-readable renderer used for pretty output. */
-declare function createPrettyPrinter(options: PrettyPrinterOptions): Printer;
 //#endregion
 //#region src/run.d.ts
 interface RunCommandOptions extends OutputOptions {
   printer?: Printer;
   signal?: AbortSignal;
-  showUsage?: ShowUsageCallback;
 }
-declare function runCommand<S extends ArgsSchema>(root: CommandDef<S>, argv: string[], options?: RunCommandOptions): Promise<unknown>;
+type HandlerResult<C> = C extends {
+  run?: infer Handler;
+} ? Handler extends ((...args: never[]) => infer R) ? Awaited<R> : never : never;
+type CommandResult<C> = HandlerResult<C> | (C extends {
+  subCommands?: infer Children;
+} ? Children extends Record<string, AnyCommandDef> ? string extends keyof Children ? unknown : CommandResult<Children[keyof Children]> : never : never);
+declare function runCommand<C extends AnyCommandDef>(root: C, argv: string[], options?: RunCommandOptions): Promise<CommandResult<C> | undefined>;
 interface RunMainOptions extends OutputOptions {
   onError?: (error: unknown) => void | Promise<void>;
   argv?: string[];
   printer?: Printer;
-  showUsage?: ShowUsageCallback;
 }
 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 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 };
+export { type CommandContext, type CommandDef, type ConfirmOptions, type Exec, type ExecCommand, type ExecFailure, type ExecFailureReason, type ExecOptions, type ExecResult, type ExecReturn, type ExecSkipped, type ExecSuccess, HackshExecError, HackshExitError, type HackshIssue, HackshPromptError, type HackshPromptErrorReason, HackshUsageError, HackshValidationError, type Logger, type OutputOptions, type PromptErrorDetails, type PromptKind, type Prompter, type RunCommandOptions, type RunMainOptions, type SelectOption, type SelectOptions, type ShowUsageOptions, type TextOptions, defineCommand, parseArgs, renderUsage, runCommand, runMain, showUsage, summarizeUsage };
 //# sourceMappingURL=index.d.ts.map