hacksh 0.12.0 → 0.14.0

package/dist/command-CfWrbHLN.d.ts

@@ -0,0 +1,378 @@
+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/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 {
+  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/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;
+interface ShowUsageOptions {
+  printer: Printer;
+  stream?: PrintStream;
+}
+/** Generate usage text without writing to stdout or stderr. */
+declare function renderUsage(command: AnyCommandDef): string;
+/** Generate a usage event and await its printer. */
+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>;
+}
+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;
+}
+/** 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/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/schema.d.ts
+type ArgsSchema = $ZodObject;
+type EmptyArgs = $ZodObject<{}>;
+//#endregion
+//#region src/command.d.ts
+interface CommandContext<S extends ArgsSchema> {
+  command: CommandDef<S>;
+  args: output<S>;
+  input: {
+    argv: string[];
+    unknown: string[];
+    passthrough: string[];
+  };
+  logger: Logger;
+  prompt: Prompter;
+  exec: Exec;
+  signal: AbortSignal;
+}
+interface CommandDef<S extends ArgsSchema = EmptyArgs, R = unknown, Children extends Record<string, AnyCommandDef> = Record<string, AnyCommandDef>> {
+  name?: string;
+  version?: string;
+  description?: string;
+  hidden?: boolean;
+  /** Keep unknown options and excess positionals in input.unknown. Inherits from the parent; defaults to false. */
+  allowUnknownArgs?: boolean;
+  args?: S;
+  subCommands?: Children;
+  run?(context: CommandContext<S>): R;
+}
+type AnyCommandDef = CommandDef<ArgsSchema>;
+declare function defineCommand<S extends ArgsSchema = EmptyArgs, R = never, Children extends Record<string, AnyCommandDef> = {}>(def: CommandDef<S, R, Children>): CommandDef<S, NoInfer<R>, NoInfer<Children>>;
+//#endregion
+export { LogKind as $, PrintStream as A, TextPromptState as B, JsonPrinterOptions as C, OutputPreference as D, OutputMode as E, PromptStatus as F, ShowUsageOptions as G, VersionPrintEvent as H, ResolveOutputModeOptions as I, UsageOptionSummary as J, UsageArgumentSummary as K, SelectPromptState as L, PromptChoiceState as M, PromptPrintEvent as N, OutputWriter as O, PromptState as P, summarizeUsage as Q, TerminalInput as R, ExecPrintEvent as S, OutputFormat as T, createJsonPrinter as U, UsagePrintEvent as V, resolveOutputMode as W, renderUsage as X, UsageSummary as Y, showUsage as Z, ExecReturn as _, ArgsSchema as a, HackshErrorSummary as at, ConfirmPromptState as b, SelectOption as c, HackshIssue as ct, Exec as d, HackshUsageError as dt, LogLevel as et, ExecCommand as f, HackshValidationError as ft, ExecResult as g, ExecOptions as h, ValidationIssueSummary as ht, defineCommand as i, HackshErrorKind as it, Printer as j, PrintEvent as k, SelectOptions as l, HackshPromptError as lt, ExecFailureReason as m, PromptKind as mt, CommandContext as n, LogRecord as nt, ConfirmOptions as o, HackshExecError as ot, ExecFailure as p, PromptErrorDetails as pt, UsageCommandSummary as q, CommandDef as r, Logger as rt, Prompter as s, HackshExitError as st, AnyCommandDef as t, LogProperties as tt, TextOptions as u, HackshPromptErrorReason as ut, ExecSkipped as v, LogPrintEvent as w, ErrorPrintEvent as x, ExecSuccess as y, TerminalOutput as z };
+//# sourceMappingURL=command-CfWrbHLN.d.ts.map