@outfitter/cli 0.4.0 → 0.5.0

package/README.md

@@ -361,6 +361,31 @@ if (flags.reset) {
 }
 ```
 
+## Conventions
+
+Composable flag presets provide typed, reusable CLI flag definitions. See the [full conventions guide](../../docs/CLI-CONVENTIONS.md) for the complete catalog.
+
+```typescript
+import { composePresets, verbosePreset, cwdPreset, forcePreset } from "@outfitter/cli/flags";
+import { outputModePreset } from "@outfitter/cli/query";
+
+const preset = composePresets(verbosePreset(), cwdPreset(), forcePreset());
+
+command("deploy")
+  .preset(preset)
+  .action(async ({ flags }) => {
+    const { verbose, cwd, force } = preset.resolve(flags);
+    // All typed, all composable
+  });
+```
+
+**Available presets:** `verbosePreset`, `cwdPreset`, `dryRunPreset`, `forcePreset`, `interactionPreset`, `strictPreset`, `colorPreset`, `projectionPreset`, `paginationPreset`, `timeWindowPreset`, `executionPreset`, `outputModePreset`, `jqPreset`
+
+**Additional modules:**
+- `@outfitter/cli/verbs` — Standard verb families (`create`, `modify`, `remove`, `list`, `show`)
+- `@outfitter/cli/query` — Output mode and jq expression presets
+- `@outfitter/cli/completion` — Shell completion script generation
+
 ## Configuration
 
 ### Environment Variables

package/dist/actions.d.ts

@@ -1,3 +1,4 @@
+import { SchemaCommandOptions } from "./shared/@outfitter/cli-n1k0d23k";
 import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
 import { Command } from "commander";
 interface BuildCliCommandsOptions {
@@ -7,6 +8,7 @@ interface BuildCliCommandsOptions {
 		flags: Record<string, unknown>;
 	}) => HandlerContext;
 	readonly includeSurfaces?: readonly ActionSurface[];
+	readonly schema?: boolean | SchemaCommandOptions;
 }
 type ActionSource = ActionRegistry | readonly AnyActionSpec[];
 declare function buildCliCommands(source: ActionSource, options?: BuildCliCommandsOptions): Command[];

package/dist/actions.js

@@ -1,4 +1,8 @@
 // @bun
+import {
+  createSchemaCommand
+} from "./shared/@outfitter/cli-g0sn0r0b.js";
+
 // packages/cli/src/actions.ts
 import {
   createContext as createHandlerContext,
@@ -163,6 +167,13 @@ function buildCliCommands(source, options = {}) {
     }
     commands.push(groupCommand);
   }
+  if (options.schema !== false) {
+    const hasSchemaCommand = commands.some((cmd) => cmd.name() === "schema");
+    if (!hasSchemaCommand) {
+      const schemaOptions = typeof options.schema === "object" ? options.schema : undefined;
+      commands.push(createSchemaCommand(source, schemaOptions));
+    }
+  }
   return commands;
 }
 function isActionRegistry(source) {

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig } from "./shared/@outfitter/cli-02kyvj7h";
+import { CLI, CLIConfig } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Create a new CLI instance with the given configuration.
 *

package/dist/command.d.ts

@@ -1,4 +1,4 @@
-import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags } from "./shared/@outfitter/cli-02kyvj7h";
+import { CLI, CLIConfig, CommandAction, CommandBuilder, CommandConfig, CommandFlags, FlagPreset } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Create a CLI instance with a portable return type from this module.
 */
@@ -40,4 +40,4 @@ declare function createCLI(config: CLIConfig): CLI;
 * ```
 */
 declare function command(name: string): CommandBuilder;
-export { createCLI, command, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI };
+export { createCLI, command, FlagPreset, CommandFlags, CommandConfig, CommandBuilder, CommandAction, CLIConfig, CLI };

package/dist/command.js

@@ -47,6 +47,16 @@ class CommandBuilderImpl {
     this.command.alias(alias);
     return this;
   }
+  preset(preset) {
+    for (const opt of preset.options) {
+      if (opt.required) {
+        this.command.requiredOption(opt.flags, opt.description, opt.defaultValue);
+      } else {
+        this.command.option(opt.flags, opt.description, opt.defaultValue);
+      }
+    }
+    return this;
+  }
   action(handler) {
     this.command.action(async (...args) => {
       const command = args.at(-1);

package/dist/completion.d.ts

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+/**
+* Configuration for the completion command.
+*/
+interface CompletionConfig {
+	/** Supported shells (default: bash, zsh, fish) */
+	readonly shells?: readonly ("bash" | "zsh" | "fish")[];
+	/** Program name for completion scripts (inferred from CLI name if not provided) */
+	readonly programName?: string;
+}
+/**
+* Generate a completion script for the given shell.
+*
+* @param shell - Target shell
+* @param programName - CLI program name
+* @returns The completion script string, or undefined for unsupported shells
+*/
+declare function generateCompletion(shell: string, programName: string): string | undefined;
+/**
+* Create a `completion <shell>` command that outputs install-ready
+* completion scripts.
+*
+* @param config - Optional configuration
+* @returns A Commander command instance
+*
+* @example
+* ```typescript
+* import { createCLI } from "@outfitter/cli";
+* import { createCompletionCommand } from "@outfitter/cli/completion";
+*
+* const cli = createCLI({ name: "mycli", version: "1.0.0" });
+* cli.register(createCompletionCommand({ programName: "mycli" }));
+* ```
+*/
+declare function createCompletionCommand(config?: CompletionConfig): Command;
+export { generateCompletion, createCompletionCommand, CompletionConfig };

package/dist/completion.js

@@ -0,0 +1,91 @@
+// @bun
+// packages/cli/src/completion.ts
+import { Command } from "commander";
+var SHELL_SAFE_PROGRAM_NAME = /^[A-Za-z0-9._-]+$/;
+function assertSafeProgramName(programName) {
+  if (SHELL_SAFE_PROGRAM_NAME.test(programName))
+    return;
+  throw new Error(`Invalid program name for shell completion: "${programName}".` + " Must match /^[A-Za-z0-9._-]+$/.");
+}
+function toShellIdentifier(programName) {
+  assertSafeProgramName(programName);
+  return programName.replaceAll(/[^A-Za-z0-9_]/g, "_");
+}
+function generateBashCompletion(programName) {
+  assertSafeProgramName(programName);
+  const shellIdentifier = toShellIdentifier(programName);
+  return `# bash completion for ${programName}
+# Add to ~/.bashrc or ~/.bash_profile:
+#   eval "$(${programName} completion bash)"
+
+_${shellIdentifier}_completions() {
+  local cur
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+
+  COMPREPLY=( $(compgen -W "$(${programName} --help 2>/dev/null | grep -oE '^  [a-z][-a-z]*' | tr -d ' ')" -- "\${cur}") )
+}
+
+complete -F _${shellIdentifier}_completions ${programName}
+`;
+}
+function generateZshCompletion(programName) {
+  assertSafeProgramName(programName);
+  const shellIdentifier = toShellIdentifier(programName);
+  return `#compdef ${programName}
+# zsh completion for ${programName}
+# Add to ~/.zshrc:
+#   eval "$(${programName} completion zsh)"
+
+_${shellIdentifier}() {
+  local -a commands
+  commands=($(${programName} --help 2>/dev/null | grep -oE '^  [a-z][-a-z]*' | tr -d ' '))
+
+  _arguments \\
+    '1:command:compadd -a commands' \\
+    '*::arg:->args'
+}
+
+compdef _${shellIdentifier} ${programName}
+`;
+}
+function generateFishCompletion(programName) {
+  assertSafeProgramName(programName);
+  return `# fish completion for ${programName}
+# Add to ~/.config/fish/completions/${programName}.fish:
+#   ${programName} completion fish > ~/.config/fish/completions/${programName}.fish
+
+complete -c ${programName} -f
+complete -c ${programName} -n "__fish_use_subcommand" -a "(${programName} --help 2>/dev/null | string match -r '^  [a-z][-a-z]*' | string trim)"
+`;
+}
+var GENERATORS = {
+  bash: generateBashCompletion,
+  zsh: generateZshCompletion,
+  fish: generateFishCompletion
+};
+function generateCompletion(shell, programName) {
+  const generator = Object.hasOwn(GENERATORS, shell) ? GENERATORS[shell] : undefined;
+  return generator?.(programName);
+}
+function createCompletionCommand(config) {
+  const shells = config?.shells ?? ["bash", "zsh", "fish"];
+  const shellSet = new Set(shells);
+  const cmd = new Command("completion").description(`Generate shell completion script (${shells.join(", ")})`).argument("<shell>", `Shell type (${shells.join(", ")})`).action((shell) => {
+    if (!shellSet.has(shell)) {
+      cmd.error(`error: unsupported shell '${shell}'. Supported: ${shells.join(", ")}`);
+      return;
+    }
+    const generator = GENERATORS[shell];
+    if (generator) {
+      const programName = config?.programName ?? cmd.parent?.name() ?? "program";
+      assertSafeProgramName(programName);
+      const script = generator(programName);
+      process.stdout.write(script);
+    }
+  });
+  return cmd;
+}
+export {
+  generateCompletion,
+  createCompletionCommand
+};

package/dist/flags.d.ts

@@ -0,0 +1,167 @@
+import { ColorFlags, ColorMode, ComposedPreset, ExecutionFlags, ExecutionPresetConfig, FlagPreset, FlagPresetConfig, InteractionFlags, PaginationFlags, PaginationPresetConfig, ProjectionFlags, StrictFlags, TimeWindowFlags, TimeWindowPresetConfig } from "./shared/@outfitter/cli-md9347gn";
+/**
+* Create a typed flag preset.
+*
+* @param config - Preset configuration with id, options, and resolver
+* @returns A flag preset that can be applied to commands or composed
+*
+* @example
+* ```typescript
+* const myPreset = createPreset({
+*   id: "output-format",
+*   options: [{ flags: "--format <type>", description: "Output format" }],
+*   resolve: (flags) => ({
+*     format: String(flags["format"] ?? "text"),
+*   }),
+* });
+* ```
+*/
+declare function createPreset<TResolved extends Record<string, unknown>>(config: FlagPresetConfig<TResolved>): FlagPreset<TResolved>;
+type ResolvedType<T> = T extends FlagPreset<infer R> ? R : never;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/**
+* Resolves the merged type from a tuple of presets.
+* Falls back to Record<string, unknown> when the tuple is empty
+* (since UnionToIntersection<never> produces unknown).
+*/
+type MergedPresetResult<TPresets extends readonly FlagPreset<Record<string, unknown>>[]> = UnionToIntersection<ResolvedType<TPresets[number]>> extends Record<string, unknown> ? UnionToIntersection<ResolvedType<TPresets[number]>> : Record<string, unknown>;
+/**
+* Compose multiple presets into one, deduplicating by id (first wins).
+*
+* @param presets - Presets to compose together
+* @returns A single preset merging all options and resolvers
+*
+* @example
+* ```typescript
+* const composed = composePresets(
+*   verbosePreset(),
+*   cwdPreset(),
+*   forcePreset(),
+* );
+* // composed.resolve({ verbose: true, cwd: "/tmp", force: false })
+* // => { verbose: true, cwd: "/tmp", force: false }
+* ```
+*/
+declare function composePresets<TPresets extends readonly FlagPreset<Record<string, unknown>>[]>(...presets: TPresets): ComposedPreset<MergedPresetResult<TPresets>>;
+/**
+* Verbose output flag preset.
+*
+* Adds: `-v, --verbose`
+* Resolves: `{ verbose: boolean }`
+*/
+declare function verbosePreset(): FlagPreset<{
+	verbose: boolean;
+}>;
+/**
+* Working directory flag preset.
+*
+* Adds: `--cwd <path>`
+* Resolves: `{ cwd: string }` (defaults to `process.cwd()`)
+*/
+declare function cwdPreset(): FlagPreset<{
+	cwd: string;
+}>;
+/**
+* Dry-run flag preset.
+*
+* Adds: `--dry-run`
+* Resolves: `{ dryRun: boolean }`
+*/
+declare function dryRunPreset(): FlagPreset<{
+	dryRun: boolean;
+}>;
+/**
+* Force flag preset.
+*
+* Adds: `-f, --force`
+* Resolves: `{ force: boolean }`
+*/
+declare function forcePreset(): FlagPreset<{
+	force: boolean;
+}>;
+/**
+* Interaction mode flag preset.
+*
+* Adds: `--non-interactive`, `--no-input`, `-y, --yes`
+* Resolves: `{ interactive: boolean, yes: boolean }`
+*
+* `interactive` defaults to `true` and is set to `false` when
+* `--non-interactive` or `--no-input` is passed. The two flags
+* are synonyms for user convenience.
+*/
+declare function interactionPreset(): FlagPreset<InteractionFlags>;
+/**
+* Strict mode flag preset.
+*
+* Adds: `--strict`
+* Resolves: `{ strict: boolean }`
+*/
+declare function strictPreset(): FlagPreset<StrictFlags>;
+/**
+* Color mode flag preset.
+*
+* Adds: `--color [mode]`, `--no-color`
+* Resolves: `{ color: "auto" | "always" | "never" }`
+*
+* Commander's `--no-color` negation sets `flags["color"]` to `false`,
+* which resolves to `"never"`. Invalid values default to `"auto"`.
+*
+* This preset resolves the user's *intent*. Consumers should compose
+* with terminal detection (`supportsColor()`, `resolveColorEnv()`)
+* to determine actual color output behavior.
+*/
+declare function colorPreset(): FlagPreset<ColorFlags>;
+/**
+* Projection flag preset.
+*
+* Adds: `--fields <fields>`, `--exclude-fields <fields>`, `--count`
+* Resolves: `{ fields: string[] | undefined, excludeFields: string[] | undefined, count: boolean }`
+*
+* Fields are parsed as comma-separated strings with whitespace trimming.
+* `undefined` when not provided (not empty array) to distinguish
+* "not specified" from "empty".
+*
+* Conflict between `--fields` and `--exclude-fields` is a handler
+* concern (documented, not enforced).
+*/
+declare function projectionPreset(): FlagPreset<ProjectionFlags>;
+/**
+* Time-window flag preset.
+*
+* Adds: `--since <date>`, `--until <date>`
+* Resolves: `{ since: Date | undefined, until: Date | undefined }`
+*
+* Accepts ISO 8601 dates (`2024-01-15`) or relative durations
+* (`7d`, `24h`, `30m`, `2w`). Durations are past-relative
+* (subtracted from now).
+*
+* Returns `undefined` for unparseable values (does not throw).
+* When `config.maxRange` is set and both bounds are provided,
+* ranges above the limit are treated as invalid.
+*/
+declare function timeWindowPreset(config?: TimeWindowPresetConfig): FlagPreset<TimeWindowFlags>;
+/**
+* Execution flag preset.
+*
+* Adds: `--timeout <ms>`, `--retries <n>`, `--offline`
+* Resolves: `{ timeout: number | undefined, retries: number, offline: boolean }`
+*
+* Timeout is parsed as a positive integer in milliseconds.
+* Retries are parsed as a non-negative integer, clamped to maxRetries.
+*/
+declare function executionPreset(config?: ExecutionPresetConfig): FlagPreset<ExecutionFlags>;
+/**
+* Pagination flag preset.
+*
+* Adds: `-l, --limit <n>`, `--next`, `--reset`
+* Resolves: `{ limit: number, next: boolean, reset: boolean }`
+*
+* Limit is parsed as an integer, clamped to maxLimit, and defaults
+* to defaultLimit on invalid input. Mutual exclusivity of --next
+* and --reset is a handler concern (not enforced here).
+*
+* Integrates with loadCursor/saveCursor/clearCursor from
+* `@outfitter/cli/pagination`.
+*/
+declare function paginationPreset(config?: PaginationPresetConfig): FlagPreset<PaginationFlags>;
+export { verbosePreset, timeWindowPreset, strictPreset, projectionPreset, paginationPreset, interactionPreset, forcePreset, executionPreset, dryRunPreset, cwdPreset, createPreset, composePresets, colorPreset, TimeWindowPresetConfig, TimeWindowFlags, StrictFlags, ProjectionFlags, PaginationPresetConfig, PaginationFlags, InteractionFlags, FlagPresetConfig, FlagPreset, ExecutionPresetConfig, ExecutionFlags, ComposedPreset, ColorMode, ColorFlags };

package/dist/flags.js

@@ -0,0 +1,31 @@
+// @bun
+import {
+  colorPreset,
+  composePresets,
+  createPreset,
+  cwdPreset,
+  dryRunPreset,
+  executionPreset,
+  forcePreset,
+  interactionPreset,
+  paginationPreset,
+  projectionPreset,
+  strictPreset,
+  timeWindowPreset,
+  verbosePreset
+} from "./shared/@outfitter/cli-b2zk8fb3.js";
+export {
+  verbosePreset,
+  timeWindowPreset,
+  strictPreset,
+  projectionPreset,
+  paginationPreset,
+  interactionPreset,
+  forcePreset,
+  executionPreset,
+  dryRunPreset,
+  cwdPreset,
+  createPreset,
+  composePresets,
+  colorPreset
+};

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import "./shared/@outfitter/cli-qz47jk6d";
 import { ANSI, Theme, Tokens, createTheme } from "./shared/@outfitter/cli-xppg982q";
-import { output } from "./shared/@outfitter/cli-f79bwzsp";
-import { OutputMode } from "./shared/@outfitter/cli-02kyvj7h";
-export { output, createTheme, Tokens, Theme, OutputMode, ANSI };
+import { exitWithError, output } from "./shared/@outfitter/cli-k0yvzn6d";
+import { OutputMode } from "./shared/@outfitter/cli-md9347gn";
+export { output, exitWithError, createTheme, Tokens, Theme, OutputMode, ANSI };

package/dist/index.js

@@ -6,10 +6,12 @@ import {
 } from "./shared/@outfitter/cli-rk9zagkm.js";
 import"./shared/@outfitter/cli-jbj78ac5.js";
 import {
+  exitWithError,
   output
 } from "./shared/@outfitter/cli-7wp5nj0s.js";
 export {
   output,
+  exitWithError,
   createTheme,
   ANSI
 };

package/dist/input.d.ts

@@ -1,4 +1,4 @@
-import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-02kyvj7h";
+import { CollectIdsOptions, ExpandFileOptions, FilterExpression, KeyValuePair, NormalizeIdOptions, ParseGlobOptions, Range, SortCriteria } from "./shared/@outfitter/cli-md9347gn";
 import { ValidationError } from "@outfitter/contracts";
 import { Result } from "better-result";
 /**

package/dist/output.d.ts

@@ -1,3 +1,3 @@
-import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-f79bwzsp";
-import "./shared/@outfitter/cli-02kyvj7h";
+import { exitWithError, output, resolveVerbose } from "./shared/@outfitter/cli-k0yvzn6d";
+import "./shared/@outfitter/cli-md9347gn";
 export { resolveVerbose, output, exitWithError };

package/dist/pagination.d.ts

@@ -1,4 +1,4 @@
-import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-02kyvj7h";
+import { CursorOptions, PaginationState } from "./shared/@outfitter/cli-md9347gn";
 /**
 * Load persisted pagination state for a command.
 *

package/dist/query.d.ts

@@ -0,0 +1,50 @@
+import { FlagPreset, OutputMode } from "./shared/@outfitter/cli-md9347gn";
+/**
+* Configuration for the output mode preset.
+*/
+interface OutputModePresetConfig {
+	/** Allowed output modes (default: ["human", "json"]) */
+	readonly modes?: readonly OutputMode[];
+	/** Default mode when not specified (default: "human") */
+	readonly defaultMode?: OutputMode;
+	/** Whether to include "jsonl" in allowed modes (default: false) */
+	readonly includeJsonl?: boolean;
+}
+/**
+* Resolved output mode from CLI input.
+*/
+type OutputModeFlags = {
+	/** The resolved output mode */
+	readonly outputMode: OutputMode;
+};
+/**
+* Output mode flag preset.
+*
+* Adds: `-o, --output <mode>`
+* Resolves: `{ outputMode: string }`
+*
+* Replaces ad-hoc `--json`/`--jsonl` handling with a single
+* `--output` flag that accepts a mode name. Invalid modes
+* fall back to the configured default.
+*
+* @param config - Optional configuration for allowed modes and default
+*/
+declare function outputModePreset(config?: OutputModePresetConfig): FlagPreset<OutputModeFlags>;
+/**
+* Resolved jq expression from CLI input.
+*/
+type JqFlags = {
+	/** The jq expression, or undefined if not provided */
+	readonly jq: string | undefined;
+};
+/**
+* JQ expression flag preset.
+*
+* Adds: `--jq <expr>`
+* Resolves: `{ jq: string | undefined }`
+*
+* The resolver returns the expression string or `undefined`.
+* Actual jq execution is a consumer concern.
+*/
+declare function jqPreset(): FlagPreset<JqFlags>;
+export { outputModePreset, jqPreset, OutputModePresetConfig, OutputModeFlags, JqFlags };

package/dist/query.js

@@ -0,0 +1,51 @@
+// @bun
+import {
+  createPreset
+} from "./shared/@outfitter/cli-b2zk8fb3.js";
+
+// packages/cli/src/query.ts
+function outputModePreset(config) {
+  const defaultMode = config?.defaultMode ?? "human";
+  const baseModes = config?.modes ?? ["human", "json"];
+  const modes = new Set(config?.includeJsonl ? [...baseModes, "jsonl"] : baseModes);
+  modes.add(defaultMode);
+  return createPreset({
+    id: "outputMode",
+    options: [
+      {
+        flags: "-o, --output <mode>",
+        description: `Output mode (${[...modes].join(", ")})`,
+        defaultValue: defaultMode
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["output"];
+      if (typeof raw === "string" && modes.has(raw)) {
+        return { outputMode: raw };
+      }
+      return { outputMode: defaultMode };
+    }
+  });
+}
+function jqPreset() {
+  return createPreset({
+    id: "jq",
+    options: [
+      {
+        flags: "--jq <expr>",
+        description: "Filter JSON output with a jq expression"
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["jq"];
+      if (typeof raw === "string" && raw.length > 0) {
+        return { jq: raw };
+      }
+      return { jq: undefined };
+    }
+  });
+}
+export {
+  outputModePreset,
+  jqPreset
+};

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions, SchemaCommandOptions, SurfaceCommandOptions, createSchemaCommand, formatManifestHuman, generateManifest } from "./shared/@outfitter/cli-n1k0d23k";
+export { generateManifest, formatManifestHuman, createSchemaCommand, SurfaceCommandOptions, SchemaCommandOptions, GenerateManifestOptions, ActionSource, ActionManifestEntry, ActionManifest };

package/dist/schema.js

@@ -0,0 +1,11 @@
+// @bun
+import {
+  createSchemaCommand,
+  formatManifestHuman,
+  generateManifest
+} from "./shared/@outfitter/cli-g0sn0r0b.js";
+export {
+  generateManifest,
+  formatManifestHuman,
+  createSchemaCommand
+};