padrone 1.0.0-beta.2

package/index.d.mts

@@ -0,0 +1,384 @@
+import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+import { Tool } from "ai";
+
+//#region src/formatter.d.ts
+type HelpFormat = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json';
+type HelpDetail = 'minimal' | 'standard' | 'full';
+/**
+ * Information about a single positional argument.
+ */
+type HelpArgumentInfo = {
+  name: string;
+  description?: string;
+  optional: boolean;
+  default?: unknown;
+  type?: string;
+};
+/**
+ * Information about a single option/flag.
+ */
+type HelpOptionInfo = {
+  name: string;
+  description?: string;
+  optional: boolean;
+  default?: unknown;
+  type?: string;
+  enum?: string[];
+  aliases?: string[];
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  examples?: unknown[];
+  /** Environment variable(s) this option can be set from */
+  env?: string | string[];
+  /** Whether this option is an array type (shown as <type...>) */
+  variadic?: boolean;
+  /** Whether this option is a boolean (shown as --[no-]option) */
+  negatable?: boolean;
+  /** Config file key that maps to this option */
+  configKey?: string;
+};
+/**
+ * Information about a subcommand (minimal info for listing).
+ */
+type HelpSubcommandInfo = {
+  name: string;
+  title?: string;
+  description?: string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+};
+/**
+ * Comprehensive JSON structure for help information.
+ * This is the single source of truth that all formatters use.
+ */
+type HelpInfo = {
+  /** The full command name (e.g., "cli serve" or "<root>") */
+  name: string;
+  /** Short title for the command */
+  title?: string;
+  /** Command description */
+  description?: string;
+  /** Whether the command is deprecated */
+  deprecated?: boolean | string;
+  /** Whether the command is hidden */
+  hidden?: boolean;
+  /** Usage string parts for flexible formatting */
+  usage: {
+    command: string;
+    hasSubcommands: boolean;
+    hasArguments: boolean;
+    hasOptions: boolean;
+  };
+  /** List of subcommands */
+  subcommands?: HelpSubcommandInfo[];
+  /** Positional arguments */
+  arguments?: HelpArgumentInfo[];
+  /** Options/flags (only visible ones, hidden filtered out) */
+  options?: HelpOptionInfo[];
+  /** Full help info for nested commands (used in 'full' detail mode) */
+  nestedCommands?: HelpInfo[];
+};
+//#endregion
+//#region src/help.d.ts
+type HelpOptions = {
+  format?: HelpFormat | 'auto';
+  detail?: HelpDetail;
+};
+//#endregion
+//#region src/options.d.ts
+interface PadroneOptionsMeta {
+  description?: string;
+  alias?: string[] | string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  examples?: unknown[];
+  /**
+   * Environment variable name(s) to bind this option to.
+   * Can be a single string or array of env var names (checked in order).
+   */
+  env?: string | string[];
+  /**
+   * Key path in config file that maps to this option.
+   * Supports dot notation for nested keys (e.g., 'server.port').
+   */
+  configKey?: string;
+}
+type PositionalArgs<TObj> = TObj extends Record<string, any> ? { [K in keyof TObj]: TObj[K] extends Array<any> ? `...${K & string}` : K & string }[keyof TObj] : string;
+/**
+ * Meta configuration for options including positional arguments.
+ * The `positional` array defines which options are positional arguments and their order.
+ * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ *
+ * @example
+ * ```ts
+ * .options(schema, {
+ *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
+ * })
+ * ```
+ */
+interface PadroneMeta<TObj = Record<string, any>> {
+  /**
+   * Array of option names that should be treated as positional arguments.
+   * Order in array determines position. Use '...name' prefix for variadic args.
+   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
+   */
+  positional?: PositionalArgs<TObj>[];
+  /**
+   * Per-option metadata.
+   */
+  options?: { [K in keyof TObj]?: PadroneOptionsMeta };
+}
+//#endregion
+//#region src/type-utils.d.ts
+type SafeString = string & {};
+type IsUnknown<T> = unknown extends T ? true : false;
+type IsAny<T> = any extends T ? true : false;
+type IsNever<T> = [T] extends [never] ? true : false;
+type SplitString<TName extends string, TSplitBy extends string = ' '> = TName extends `${infer FirstPart}${TSplitBy}${infer RestParts}` ? [FirstPart, ...SplitString<RestParts, TSplitBy>] : [TName];
+type JoinString<TParts extends string[], TJoinBy extends string = ' '> = TParts extends [infer FirstPart extends string, ...infer RestParts extends string[]] ? RestParts extends [] ? FirstPart : `${FirstPart}${TJoinBy}${JoinString<RestParts, TJoinBy>}` : TParts extends [] ? '' : TParts[number];
+type SplitLastSpace<S extends string> = SplitString<S> extends [...infer Init extends string[], infer Last extends string] ? Init extends [] ? [S, never] : [JoinString<Init>, Last] : [S, never];
+type AnyPartExtends<U, T> = [U] extends [never] ? false : U extends any ? (U extends T ? true : never) : never extends true ? true : false;
+type FullCommandName<TName extends string, TParentName extends string = ''> = TParentName extends '' ? TName : `${TParentName} ${TName}`;
+type PickCommandByName<TCommands extends AnyPadroneCommand[], TName extends string | AnyPadroneCommand> = TName extends AnyPadroneCommand ? TName : Extract<FlattenCommands<TCommands>, {
+  path: TName;
+}>;
+type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends [infer FirstCommand, ...infer RestCommands] ? FirstCommand extends AnyPadroneCommand ? (RestCommands extends AnyPadroneCommand[] ? FlattenCommands<RestCommands> : never) | FlattenCommands<FirstCommand['~types']['commands']> | FirstCommand : RestCommands extends AnyPadroneCommand[] ? FlattenCommands<RestCommands> : never : TCommands[number];
+type GetCommandNames<TCommands extends AnyPadroneCommand[]> = FlattenCommands<TCommands>['path'];
+/**
+ * Find all the commands that are prefixed with a command name.
+ * This is needed to avoid matching other commands when followed by a space and another word.
+ * For example, let's say `level1` and `level1 level2` are commands.
+ * Then `level1 ${string}` would also match `level1 level2`,
+ * and it would cause `level1 level2` to not show up in the autocomplete.
+ * By excluding those cases, we can ensure autocomplete works correctly.
+ */
+type PrefixedCommands<TCommands extends AnyPadroneCommand[]> = GetCommandNames<TCommands> extends infer CommandNames ? CommandNames extends string ? AnyPartExtends<GetCommandNames<TCommands>, `${CommandNames} ${string}`> extends true ? never : `${CommandNames} ${string}` : never : never;
+/**
+ * The possible commands are the commands that can be parsed by the program.
+ * This includes the string that are exact matches to a command name, and strings that are prefixed with a command name.
+ */
+type PossibleCommands<TCommands extends AnyPadroneCommand[]> = GetCommandNames<TCommands> | PrefixedCommands<TCommands> | SafeString;
+/**
+ * Match a string to a command by the possible commands.
+ * This is done by recursively splitting the string by the last space, and then checking if the prefix is a valid command name.
+ * This is needed to avoid matching the top-level command when there are nested commands.
+ */
+type PickCommandByPossibleCommands<TCommands extends AnyPadroneCommand[], TCommand extends PossibleCommands<TCommands>> = IsAny<TCommand> extends true ? TCommands[number] : TCommand extends GetCommandNames<TCommands> ? PickCommandByName<TCommands, TCommand> : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest] ? IsNever<Rest> extends true ? PickCommandByName<TCommands, Prefix> : PickCommandByPossibleCommands<TCommands, Prefix> : never;
+//#endregion
+//#region src/types.d.ts
+type UnknownRecord = Record<string, unknown>;
+type EmptyRecord = Record<string, never>;
+type DefaultOpts = UnknownRecord | void;
+/**
+ * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
+ * This is the type required for command arguments and options in Padrone.
+ */
+type PadroneSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+type PadroneCommand<TName extends string = string, TParentName extends string = '', TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = []> = {
+  name: TName;
+  path: FullCommandName<TName, TParentName>;
+  title?: string;
+  description?: string;
+  version?: string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  needsApproval?: boolean | ((options: TOpts) => Promise<boolean> | boolean);
+  options?: PadroneSchema;
+  meta?: GetMeta<TOpts>;
+  handler?: (options: StandardSchemaV1.InferOutput<TOpts>) => TRes;
+  /** List of possible config file names to search for. */
+  configFiles?: string[];
+  parent?: AnyPadroneCommand;
+  commands?: TCommands;
+  /** @deprecated Internal use only */
+  '~types': {
+    name: TName;
+    parentName: TParentName;
+    path: FullCommandName<TName, TParentName>;
+    optionsInput: StandardSchemaV1.InferInput<TOpts>;
+    optionsOutput: StandardSchemaV1.InferOutput<TOpts>;
+    result: TRes;
+    commands: TCommands;
+  };
+};
+type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]]>;
+/**
+ * Configuration options for a command.
+ */
+type PadroneCommandConfig = {
+  /** A short title for the command, displayed in help. */
+  title?: string;
+  /** A longer description of what the command does. */
+  description?: string;
+  /** The version of the command. */
+  version?: string;
+  /** Whether the command is deprecated, or a message explaining the deprecation. */
+  deprecated?: boolean | string;
+  /** Whether the command should be hidden from help output. */
+  hidden?: boolean;
+  /**
+   * List of possible config file names to search for.
+   * When the CLI runs, it will search for these files in the current directory
+   * and apply the first one found.
+   *
+   * - `undefined`: Inherit from parent command (default)
+   * - `['file1', 'file2']`: Use these config files
+   * - `[]`: Explicitly disable config file loading (no inheritance)
+   *
+   * @example ['myapp.config.json', 'myapp.config.yaml', '.myapprc']
+   */
+  configFiles?: string[];
+};
+type PadroneCommandBuilder<TName extends string = string, TParentName extends string = '', TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = []> = {
+  /**
+   * Configures command properties like title, description, version, deprecated, and hidden.
+   * @example
+   * ```ts
+   * .configure({
+   *   title: 'Build Project',
+   *   description: 'Compiles the project',
+   *   deprecated: 'Use "compile" instead',
+   * })
+   * ```
+   */
+  configure: (config: PadroneCommandConfig) => PadroneCommandBuilder<TName, TParentName, TOpts, TRes, TCommands>;
+  /**
+   * Defines the options schema for the command, including positional arguments.
+   * Use the `positional` array in meta to specify which options are positional args.
+   * Use '...name' prefix for variadic (rest) arguments, matching JS/TS rest syntax.
+   *
+   * @example
+   * ```ts
+   * .options(z.object({
+   *   source: z.string(),
+   *   files: z.string().array(),
+   *   dest: z.string(),
+   *   recursive: z.boolean().default(false),
+   * }), {
+   *   positional: ['source', '...files', 'dest'],
+   * })
+   * ```
+   */
+  options: <TOpts extends PadroneSchema = PadroneSchema<void>>(options?: TOpts, meta?: GetMeta<TOpts>) => PadroneCommandBuilder<TName, TParentName, TOpts, TRes, TCommands>;
+  /**
+   * Defines the handler function to be executed when the command is run.
+   */
+  action: <TRes>(handler?: (options: StandardSchemaV1.InferOutput<TOpts>) => TRes) => PadroneCommandBuilder<TName, TParentName, TOpts, TRes, TCommands>;
+  /**
+   * Creates a nested command within the current command with the given name and builder function.
+   */
+  command: <TNameNested extends string, TBuilder extends PadroneCommandBuilder<TNameNested, FullCommandName<TName, TParentName>, any, any, any>>(name: TNameNested, builderFn?: (builder: PadroneCommandBuilder<TNameNested, FullCommandName<TName, TParentName>>) => TBuilder) => PadroneCommandBuilder<TName, TParentName, TOpts, TRes, [...TCommands, TBuilder['~types']['command']]>;
+  /** @deprecated Internal use only */
+  '~types': {
+    name: TName;
+    parentName: TParentName;
+    path: FullCommandName<TName, TParentName>;
+    options: TOpts;
+    result: TRes;
+    commands: TCommands;
+    command: PadroneCommand<TName, TParentName, TOpts, TRes, TCommands>;
+  };
+};
+type PadroneProgram<TName extends string = string, TOpts extends PadroneSchema = PadroneSchema<DefaultOpts>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TCmd extends PadroneCommand<'', '', TOpts, TRes, TCommands> = PadroneCommand<'', '', TOpts, TRes, TCommands>> = Omit<PadroneCommandBuilder<TName, '', TOpts, TRes, TCommands>, 'command' | 'configure'> & {
+  /**
+   * Configures program properties like title, description, version, deprecated, hidden, and configFiles.
+   * @example
+   * ```ts
+   * .configure({
+   *   description: 'My CLI application',
+   *   version: '1.0.0',
+   *   configFiles: ['myapp.config.json', '.myapprc'],
+   * })
+   * ```
+   */
+  configure: (config: PadroneCommandConfig) => PadroneProgram<TName, TOpts, TRes, TCommands>;
+  /**
+   * Creates a command within the program with the given name and builder function.
+   */
+  command: <TNameNested extends string, TBuilder extends PadroneCommandBuilder<TNameNested, '', any, any, any>>(name: TNameNested, builderFn?: (builder: PadroneCommandBuilder<TNameNested, ''>) => TBuilder) => PadroneProgram<TName, TOpts, TRes, [...TCommands, TBuilder['~types']['command']]>;
+  /**
+   * Runs a command programmatically by name with provided options (including positional args).
+   */
+  run: <const TCommand extends GetCommandNames<[TCmd]> | FlattenCommands<[TCmd]>>(name: TCommand, options: NoInfer<GetOptions<'in', PickCommandByName<[TCmd], TCommand>>>) => PadroneCommandResult<PickCommandByName<[TCmd], TCommand>>;
+  /**
+   * Runs the program as a CLI application, parsing `process.argv` or provided input.
+   */
+  cli: <const TCommand extends PossibleCommands<[TCmd]>>(input?: TCommand, options?: PadroneParseOptions) => PadroneCommandResult<PickCommandByPossibleCommands<[TCmd], TCommand>>;
+  /**
+   * Parses CLI input (or the provided input string) into command, args, and options without executing anything.
+   */
+  parse: <const TCommand extends PossibleCommands<[TCmd]>>(input?: TCommand, options?: PadroneParseOptions) => PadroneParseResult<PickCommandByPossibleCommands<[TCmd], TCommand>>;
+  /**
+   * Converts command and options back into a CLI string.
+   */
+  stringify: <const TCommand extends GetCommandNames<TCommands> = ''>(command?: TCommand, options?: GetOptions<'out', PickCommandByPossibleCommands<[TCmd], TCommand>>) => string;
+  /**
+   * Finds a command by name, returning `undefined` if not found.
+   */
+  find: <const TName extends GetCommandNames<[TCmd]>>(command: TName | (string & {})) => IsUnknown<TName> extends false ? TName extends string ? PickCommandByName<[TCmd], TName> : FlattenCommands<[TCmd]> | undefined : FlattenCommands<[TCmd]> | undefined;
+  /**
+   * Generates a type-safe API for invoking commands programmatically.
+   */
+  api: () => PadroneAPI<TCmd>;
+  /**
+   * Starts an interactive prompt to run commands.
+   */
+  /**
+   * Starts a REPL (Read-Eval-Print Loop) for running commands interactively.
+   */
+  /**
+   * Returns a tool definition that can be passed to AI SDK.
+   */
+  tool: () => Tool<{
+    command: string;
+  }>;
+  /**
+   * Returns the help information for the program or a specific command.
+   */
+  help: <const TCommand extends GetCommandNames<[TCmd]> | FlattenCommands<[TCmd]>>(command?: TCommand, options?: HelpOptions) => string;
+  /**
+   * Reflection information about the program.
+   * Avoid using this in application code, unless you know what you're doing.
+   * @deprecated Internal use only
+   */
+  '~types': {
+    command: TCmd;
+    commands: TCommands;
+  };
+};
+type AnyPadroneProgram = PadroneProgram<string, any, any, [...AnyPadroneCommand[]]>;
+type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = PadroneParseResult<TCommand> & {
+  result: GetResults<TCommand>;
+};
+/**
+ * Options for parsing CLI input.
+ */
+type PadroneParseOptions = {
+  /**
+   * Custom environment variables to use for env binding.
+   * If not provided, process.env will be used.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Config file data to use for config binding.
+   * This should be the parsed content of a config file (JSON, YAML, etc.).
+   */
+  configData?: Record<string, unknown>;
+};
+type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
+  command: TCommand;
+  options?: GetOptions<'out', TCommand>;
+  optionsResult?: StandardSchemaV1.Result<GetOptions<'out', TCommand>>;
+};
+type PadroneAPI<TCommand extends AnyPadroneCommand> = PadroneAPICommand<TCommand> & { [K in TCommand['~types']['commands'][number] as K['name']]: PadroneAPI<K> };
+type PadroneAPICommand<TCommand extends AnyPadroneCommand> = (options: GetOptions<'in', TCommand>) => GetResults<TCommand>;
+type NormalizeOptions<TOptions> = IsUnknown<TOptions> extends true ? void | EmptyRecord : TOptions;
+type GetOptions<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in' ? NormalizeOptions<TCommand['~types']['optionsInput']> : NormalizeOptions<TCommand['~types']['optionsOutput']>;
+type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['handler']>>;
+type GetMeta<TOpts extends PadroneSchema> = PadroneMeta<NonNullable<StandardSchemaV1.InferInput<TOpts>>>;
+//#endregion
+//#region src/index.d.ts
+declare function createPadrone(name: string): PadroneProgram;
+//#endregion
+export { type AnyPadroneCommand, type AnyPadroneProgram, type HelpArgumentInfo, type HelpFormat, type HelpInfo, type HelpOptionInfo, type HelpOptions, type HelpSubcommandInfo, type PadroneCommand, type PadroneCommandBuilder, type PadroneCommandConfig, type PadroneCommandResult, type PadroneOptionsMeta, type PadroneParseOptions, type PadroneParseResult, type PadroneProgram, createPadrone };
+//# sourceMappingURL=index.d.mts.map