padrone 1.0.0-beta.2

package/src/parse.ts

@@ -0,0 +1,222 @@
+type ParseParts = {
+  /**
+   * An alphanumeric term representing a command, subcommand, or positional argument.
+   * Note that a term can be ambiguous until fully matched within the command hierarchy.
+   * We cannot fully distinguish between a nested command or a positional argument until
+   * the command structure is known.
+   */
+  term: {
+    type: 'term';
+    value: string;
+  };
+  /**
+   * A positional argument provided to the command.
+   * Unlike `term`, this is definitively an argument. This can be determined when
+   * the argument is non-alphanumeric, like a path or a number.
+   */
+  arg: {
+    type: 'arg';
+    value: string;
+  };
+  /**
+   * An option provided to the command, prefixed with `--`.
+   * If the option has an `=` sign, the value after it is used as the option's value.
+   * Otherwise, the value is obtained from the next part or set to `true` if no value is provided.
+   */
+  option: {
+    type: 'option';
+    key: string;
+    value?: string | string[];
+    negated?: boolean;
+  };
+  /**
+   * An alias option provided to the command, prefixed with `-`.
+   * Which option it maps to cannot be determined until the command structure is known.
+   */
+  alias: {
+    type: 'alias';
+    key: string;
+    value?: string | string[];
+  };
+};
+
+type ParsePart = ParseParts[keyof ParseParts];
+
+/**
+ * Tokenizes input string respecting quoted strings and bracket arrays.
+ * Supports single quotes, double quotes, backticks, and square brackets.
+ */
+function tokenizeInput(input: string): string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let inQuote: '"' | "'" | '`' | null = null;
+  let bracketDepth = 0;
+  let i = 0;
+
+  while (i < input.length) {
+    const char = input[i];
+
+    if (inQuote) {
+      // Check for escape sequences within quotes
+      if (char === '\\' && i + 1 < input.length) {
+        const nextChar = input[i + 1];
+        // Handle escape sequences
+        if (nextChar === inQuote || nextChar === '\\') {
+          current += nextChar;
+          i += 2;
+          continue;
+        }
+      }
+
+      if (char === inQuote) {
+        // End of quoted string
+        inQuote = null;
+      } else {
+        current += char;
+      }
+    } else if (char === '[') {
+      bracketDepth++;
+      current += char;
+    } else if (char === ']') {
+      bracketDepth = Math.max(0, bracketDepth - 1);
+      current += char;
+    } else if (bracketDepth > 0) {
+      // Inside brackets - include everything including spaces
+      current += char;
+    } else if (char === '"' || char === "'" || char === '`') {
+      // Start of quoted string
+      inQuote = char;
+    } else if (char === ' ' || char === '\t') {
+      // Whitespace outside quotes and brackets - end current token
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+    i++;
+  }
+
+  // Add the last token if any
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+export function parseCliInputToParts(input: string): ParsePart[] {
+  const parts = tokenizeInput(input.trim());
+  const result: ParsePart[] = [];
+
+  let pendingValue: ParseParts['option'] | ParseParts['alias'] | undefined;
+  let allowTerm = true;
+
+  for (const part of parts) {
+    if (!part) continue;
+    const wasPending = pendingValue;
+    pendingValue = undefined;
+
+    if (part.startsWith('--no-') && part.length > 5) {
+      // Negated boolean option (--no-verbose)
+      const key = part.slice(5);
+      const p = { type: 'option' as const, key, value: undefined, negated: true };
+      result.push(p);
+    } else if (part.startsWith('--')) {
+      const [key = '', value] = splitOptionValue(part.slice(2));
+
+      const p = { type: 'option' as const, key, value };
+      if (typeof value === 'undefined') pendingValue = p;
+      result.push(p);
+    } else if (part.startsWith('-') && part.length > 1 && !/^-\d/.test(part)) {
+      // Short option (but not negative numbers like -5)
+      const [key = '', value] = splitOptionValue(part.slice(1));
+
+      const p = { type: 'alias' as const, key, value };
+      if (typeof value === 'undefined') pendingValue = p;
+      result.push(p);
+    } else if (wasPending) {
+      wasPending.value = part;
+    } else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) {
+      result.push({ type: 'term', value: part });
+    } else {
+      result.push({ type: 'arg', value: part });
+      allowTerm = false;
+    }
+  }
+  return result;
+}
+
+/**
+ * Split option key and value, handling quoted values after =.
+ */
+function splitOptionValue(str: string): [string, string | string[] | undefined] {
+  const eqIndex = str.indexOf('=');
+  if (eqIndex === -1) return [str, undefined];
+
+  const key = str.slice(0, eqIndex);
+  let value = str.slice(eqIndex + 1);
+
+  // Remove surrounding quotes from value if present
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'")) ||
+    (value.startsWith('`') && value.endsWith('`'))
+  ) {
+    value = value.slice(1, -1);
+    return [key, value];
+  }
+
+  // Handle array syntax: [a,b,c] -> ['a', 'b', 'c']
+  if (value.startsWith('[') && value.endsWith(']')) {
+    const inner = value.slice(1, -1);
+    if (inner === '') return [key, []];
+    const items = parseArrayItems(inner);
+    return [key, items];
+  }
+
+  return [key, value];
+}
+
+/**
+ * Parse comma-separated items, respecting quotes within items.
+ */
+function parseArrayItems(input: string): string[] {
+  const items: string[] = [];
+  let current = '';
+  let inQuote: '"' | "'" | '`' | null = null;
+  let i = 0;
+
+  while (i < input.length) {
+    const char = input[i];
+
+    if (inQuote) {
+      if (char === '\\' && i + 1 < input.length && input[i + 1] === inQuote) {
+        current += input[i + 1];
+        i += 2;
+        continue;
+      }
+      if (char === inQuote) {
+        inQuote = null;
+      } else {
+        current += char;
+      }
+    } else if (char === '"' || char === "'" || char === '`') {
+      inQuote = char;
+    } else if (char === ',') {
+      items.push(current.trim());
+      current = '';
+    } else {
+      current += char;
+    }
+    i++;
+  }
+
+  // Add the last item
+  if (current || items.length > 0) {
+    items.push(current.trim());
+  }
+
+  return items;
+}

package/src/type-utils.ts

@@ -0,0 +1,99 @@
+import type { AnyPadroneCommand } from './types';
+
+/**
+ * Use this type instead of `any` when you intend to fix it later
+ * @deprecated Please replace with an actual type
+ */
+export type TODO<TCast = any, _TReason = unknown> = TCast;
+
+type SafeString = string & {};
+export 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;
+
+export type FullCommandName<TName extends string, TParentName extends string = ''> = TParentName extends ''
+  ? TName
+  : `${TParentName} ${TName}`;
+
+export type PickCommandByName<
+  TCommands extends AnyPadroneCommand[],
+  TName extends string | AnyPadroneCommand,
+> = TName extends AnyPadroneCommand ? TName : Extract<FlattenCommands<TCommands>, { path: TName }>;
+
+export 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];
+
+export 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.
+ */
+export 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.
+ */
+export 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;

package/src/types.ts

@@ -0,0 +1,313 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
+import type { Tool } from 'ai';
+import type { HelpOptions } from './help';
+import type { PadroneMeta } from './options';
+import type {
+  FlattenCommands,
+  FullCommandName,
+  GetCommandNames,
+  IsUnknown,
+  PickCommandByName,
+  PickCommandByPossibleCommands,
+  PossibleCommands,
+} from './type-utils';
+
+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>;
+
+export 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;
+  };
+};
+
+export type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]]>;
+
+/**
+ * Configuration options for a command.
+ */
+export 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[];
+};
+
+export 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>;
+  };
+};
+
+export 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>;
+
+  // TODO: implement interactive and repl methods
+
+  /**
+   * Starts an interactive prompt to run commands.
+   */
+  // interactive: () => Promise<PadroneCommandResult<FlattenCommands<[TCmd]>> | undefined>;
+
+  /**
+   * Starts a REPL (Read-Eval-Print Loop) for running commands interactively.
+   */
+  // repl: () => Promise<PadroneCommandResult<FlattenCommands<[TCmd]>>[]>;
+
+  /**
+   * 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;
+  };
+};
+
+export type AnyPadroneProgram = PadroneProgram<string, any, any, [...AnyPadroneCommand[]]>;
+
+export type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = PadroneParseResult<TCommand> & {
+  result: GetResults<TCommand>;
+};
+
+/**
+ * Options for parsing CLI input.
+ */
+export 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>;
+};
+
+export type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
+  command: TCommand;
+  options?: GetOptions<'out', TCommand>;
+  optionsResult?: StandardSchemaV1.Result<GetOptions<'out', TCommand>>;
+};
+
+export 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>>>;