@clo4/cli 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @clo4/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fully declarative CLI framework, lean footprint, fast, good API for completions.
+
+```ts
+import * as CLI from "@clo4/cli";
+
+const spec: CLI.Spec = {
+  name: "demo",
+  description: "Compile a project.",
+  options: [CLI.help],
+  subcommands: [
+    {
+      name: "build",
+      description: "Build a project.",
+      args: { name: "input" },
+      options: [
+        { name: "--watch", description: "Watch for changes." },
+        {
+          name: ["-o", "--output"],
+          args: { name: "dir" },
+          isRequired: true,
+          description: "Write output to this directory.",
+        },
+      ],
+      action({ args: [input], options }) {
+        console.log(`${input} -> ${options.get("--output")}`);
+      },
+    },
+  ],
+};
+
+process.exitCode = await CLI.run(spec);
+```
+
+Specs define `args`, `options`, `subcommands`, and `action` functions. Parsing and validating values stay in your code, it's not the job of the library.
+
+Option actions override command actions. That lets helpers like `--help` run even when the selected command is missing required positional arguments.
+
+Use `@clo4/cli/testing` in package tests to validate structural constraints that TypeScript cannot express, such as duplicate names, bad required/optional argument order, invalid repeatable options, and invalid option references.
+
+## Shell completion
+
+Add `CLI.completion` to a spec's `subcommands` to give the CLI a `completion <shell>` command that prints a completion script:
+
+```ts
+const spec: CLI.Spec = {
+  name: "demo",
+  options: [CLI.help],
+  subcommands: [CLI.completion /* ... */],
+};
+```
+
+```sh
+demo completion bash > /etc/bash_completion.d/demo
+demo completion zsh  > "${fpath[1]}/_demo"
+demo completion fish > ~/.config/fish/completions/demo.fish
+```
+
+Completion describes the whole CLI from the root spec regardless of where the subcommand is placed. Hidden options and subcommands are excluded; persistent options are offered on the descendants that inherit them.
+
+### Completion modes: `--runtime` (default) and `--shell`
+
+By default, `completion <shell>` emits a a shim that executes itself as `<cli> completion complete -- <commandline>`, allowing it to reuse its own parser. This is slower on average, but allows it to provide native-feeling completions that respect your nitpicky parser options. So long as you keep the startup time of your CLI acceptable, there isn't much of a downside to this.
+
+Alternatively, `completion <shell> --shell` emits a self-contained shell completion script. It can't track line state, so relationship filters like `exclusiveOn`/`isRepeatable` aren't applied. Dynamic generators still call back via `completion generate-suggestions`.
+
+In runtime mode, the bash and fish shims pass `--gate-options`, so options are only offered once the word starts with `-` (matching fish/bash convention); zsh omits it and surfaces options as usual. Flip this by editing which shims pass the option.
+
+### Argument suggestions
+
+Arguments can declare completion metadata. These are only used for completions, not parsing.
+
+```ts
+{
+  // dynamic completions: file/folder paths
+  name: "--config",
+  args: { name: "file", template: "filepaths" },
+}
+
+{
+  // static completions
+  name: "--mode",
+  args: { name: "mode", suggestions: ["debug", "release"] },
+}
+
+{
+  // fully dynamic completions using your own code
+  name: "--target",
+  args: {
+    name: "target",
+    generators: { custom: (tokens) => listTargets() },
+  },
+}
+```
+
+- `template` (`"filepaths"` / `"folders"`) completes paths.
+- `suggestions` is a static list (strings or `{ name, description }`).
+- `generators.custom(tokens)` returns dynamic suggestions: in runtime mode it runs in-process, in `--shell` mode it is reached via the hidden `completion generate-suggestions <location>` callback.

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Declarative CLI spec types.
+ *
+ * The schema is intentionally small: define commands, positional args, options,
+ * and actions. Runtime values from argv are always strings.
+ *
+ * @module
+ */
+declare const kind: unique symbol;
+/** An array with at least one value in it. */
+type NonEmptyArray<T> = readonly [T, ...T[]];
+/** A single value, or an array with at least two values. */
+type SingleOrArray<T> = T | readonly [T, T, ...T[]];
+/** A single value, or an array with either zero or at least two values. */
+type SingleOrArrayOrEmpty<T> = T | [] | readonly [T, T, ...T[]];
+/**
+ * An action associated with a subcommand or option.
+ *
+ * Actions can be sync or async. Returning `undefined` is treated as exit code 0.
+ */
+interface Action {
+  (init: ActionInit): Promise<number | void> | number | void;
+  /**
+   * This property never exists. It prevents accidental structural assignment
+   * between otherwise compatible exported interfaces.
+   *
+   * @ignore
+   */
+  [kind]?: "Action";
+}
+/** A command path, starting with the root spec. */
+type CommandPath = readonly [Spec, ...Subcommand[]];
+/** Access parsed options. */
+interface OptionArgs {
+  /** Escape hatch: the underlying map of option names to values. */
+  readonly options: Map<string, string[]>;
+  /** Get every argument supplied to a option. */
+  all(name: string): string[] | undefined;
+  /** Get the first argument supplied to a option. */
+  get(name: string): string | undefined;
+  /** Check whether a option was supplied. */
+  has(name: string): boolean;
+  /** Count option values, useful for repeatable options. */
+  count(name: string): number;
+}
+/** The data an action receives. */
+interface ActionInit {
+  /** Options found for this invocation. */
+  options: OptionArgs;
+  /** Positional arguments found for the selected command. */
+  args: string[];
+  /** Commands used leading up to the selected action. */
+  path: CommandPath;
+  /** Index of the `--` argument separator, or -1 if it was not supplied. */
+  argSeparatorIndex: number;
+  /** Get help text for the currently executing command. */
+  help(config?: {
+    /** Include the command description? Default: true. */
+    description?: boolean;
+    /** Include the usage summary? Default: true. */
+    usage?: boolean;
+    /** Suggest the closest choice for an incorrect input. */
+    didYouMean?: {
+      input: string;
+      choices: readonly string[];
+    };
+    /** Alternative command path to render help for. */
+    path?: NonEmptyArray<Subcommand>;
+  }): string;
+}
+/** A top-level command. */
+interface Spec extends Omit<Subcommand, "name"> {
+  /** Name of the CLI. */
+  name: string;
+}
+/** A subcommand that can be executed. */
+interface Subcommand {
+  /** Name or aliases used for matching. */
+  name: SingleOrArray<string>;
+  /** Description shown in help. */
+  description?: string;
+  /** Positional arguments accepted by this command. */
+  args?: SingleOrArray<Arg>;
+  /** Options accepted by this command. */
+  options?: NonEmptyArray<Option>;
+  /** Subcommands of this command. */
+  subcommands?: NonEmptyArray<Subcommand>;
+  /** Direct parser behavior. */
+  parserDirectives?: {
+    /**
+     * Treat option names literally, disabling POSIX short-option chaining and
+     * unknown option errors for tokens that look option-like.
+     */
+    flagsArePosixNoncompliant?: boolean;
+    /**
+     * Once an argument has been found, all following tokens are arguments even
+     * if they match options.
+     */
+    optionsMustPrecedeArguments?: boolean;
+    /** Separators that can attach a option argument to a option token. */
+    optionArgSeparators?: SingleOrArrayOrEmpty<string>;
+    /** Match subcommands by shortest unique prefix instead of exact name. */
+    subcommandsMatchUniquePrefix?: boolean;
+  };
+  /** Hide this command from help. */
+  hidden?: true;
+  /** Require a subcommand; without one, print usage. */
+  requiresSubcommand?: true;
+  /** Action to run when this command is selected. */
+  action?: Action;
+  /**
+   * This property never exists. It prevents accidental structural assignment
+   * between options and subcommands.
+   *
+   * @ignore
+   */
+  [kind]?: "Subcommand";
+}
+/** A option that modifies or overrides command execution. */
+interface Option {
+  /** Name or aliases, including any desired prefix such as `-`, `--`, or `/`. */
+  name: SingleOrArray<string>;
+  /** Description shown in help. */
+  description?: string;
+  /** Arguments this option accepts. */
+  args?: SingleOrArray<Arg>;
+  /** Allow this option to be used by descendant subcommands. */
+  isPersistent?: true;
+  /** Hide this option from help. */
+  hidden?: true;
+  /** Only allow arguments to be supplied with a separator. */
+  requiresSeparator?: true | string;
+  /** Allow this option to be supplied multiple times. */
+  isRepeatable?: true | number;
+  /** Require this option to be supplied before the selected action runs. */
+  isRequired?: true;
+  /** Fail parsing if these options are provided. */
+  exclusiveOn?: NonEmptyArray<string>;
+  /** Fail parsing if these options are not provided. */
+  dependsOn?: NonEmptyArray<string>;
+  /**
+   * Action performed when this option is provided.
+   *
+   * Option actions take precedence over command actions. The final parsed option
+   * action is selected.
+   */
+  action?: Action;
+  /**
+   * This property never exists. It prevents accidental structural assignment
+   * between options and subcommands.
+   *
+   * @ignore
+   */
+  [kind]?: "Option";
+}
+/**
+ * A built-in completion template.
+ *
+ * Resolves to the shell's native path completion. Completions only — no effect
+ * on parsing.
+ */
+type Template = "filepaths" | "folders" | ["folders", "filepaths"] | ["filepaths", "folders"];
+/**
+ * A single completion suggestion.
+ *
+ * This is a deliberately small subset of the Fig `Suggestion` shape — just the
+ * fields the completion engine uses. Presentational fields (icon, priority,
+ * displayName, insertValue, type) are intentionally omitted.
+ */
+interface Suggestion {
+  /** Value(s) inserted when the suggestion is accepted. */
+  name: SingleOrArray<string>;
+  /** Additional information shown next to the suggestion. */
+  description?: string;
+}
+/**
+ * Generates dynamic completion suggestions.
+ *
+ * Generators run by re-invoking the CLI's hidden `completion
+ * generate-suggestions` command, so `custom` executes in the CLI's own
+ * process. Completions only — no effect on parsing.
+ */
+interface Generator {
+  /** Produce suggestions from the current command-line tokens. */
+  custom?(tokens: string[]): (Suggestion | string)[] | Promise<(Suggestion | string)[]>;
+}
+/** Positional or option argument metadata. */
+interface Arg {
+  /** Name shown in generated help. */
+  name?: string;
+  /** Description for documentation or future help output. */
+  description?: string;
+  /** Allow this argument to take unlimited values. */
+  isVariadic?: true;
+  /** Allow this argument to be omitted. */
+  isOptional?: true;
+  /** Completions: complete file or folder paths for this argument. */
+  template?: Template;
+  /** Completions: static suggestions offered while typing this argument. */
+  suggestions?: readonly (string | Suggestion)[];
+  /** Completions: dynamically generated suggestions for this argument. */
+  generators?: SingleOrArray<Generator>;
+}
+/** Shells that {@link getCompletion} can generate scripts for. */
+type Shell = "bash" | "zsh" | "fish";
+/** A subcommand that prints a shell completion script for the whole CLI. */
+export declare const completion: Subcommand;
+/** A subcommand that prints help for its parent or a sibling command. */
+export declare const helpCommand: Subcommand;
+/** A persistent help option that prints help for the selected command. */
+export declare const help: Option;
+/**
+ * Parse argv and execute the selected action.
+ *
+ * The final command action runs unless a parsed option has an action. Option
+ * actions take precedence so helpers like `--help` can run without satisfying
+ * the selected command's required arguments.
+ */
+export declare function run(spec: Spec, args?: readonly string[]): Promise<number>;
+export declare function printError(...strings: unknown[]): void;
+declare const _default: {
+  completion: Subcommand;
+  help: Option;
+  helpCommand: Subcommand;
+  printError: typeof printError;
+  run: typeof run;
+};
+export { type Action, type ActionInit, type Arg, type CommandPath, type Generator, type NonEmptyArray, type Option, type OptionArgs, type Shell, type SingleOrArray, type SingleOrArrayOrEmpty, type Spec, type Subcommand, type Suggestion, type Template, _default as default };
+//# sourceMappingURL=index.d.ts.map