@outfitter/cli 0.1.0-rc.2 → 0.1.0

package/README.md

@@ -11,7 +11,9 @@ bun add @outfitter/cli
 ## Quick Start
 
 ```typescript
-import { output, collectIds, loadCursor, saveCursor } from "@outfitter/cli";
+import { output } from "@outfitter/cli/output";
+import { collectIds } from "@outfitter/cli/input";
+import { loadCursor, saveCursor } from "@outfitter/cli/pagination";
 
 // Output data with automatic mode detection
 output({ id: "123", name: "Example" });
@@ -37,7 +39,7 @@ Output data to the console with automatic mode selection.
 Defaults to human-friendly output for TTY, JSON for non-TTY. Override via `mode` option or `OUTFITTER_JSON`/`OUTFITTER_JSONL` environment variables.
 
 ```typescript
-import { output } from "@outfitter/cli";
+import { output } from "@outfitter/cli/output";
 
 // Basic usage - mode auto-detected
 output(results);
@@ -73,7 +75,7 @@ output(errors, { stream: process.stderr });
 Exit the process with an error message and appropriate exit code.
 
 ```typescript
-import { exitWithError } from "@outfitter/cli";
+import { exitWithError } from "@outfitter/cli/output";
 
 try {
   await riskyOperation();
@@ -89,7 +91,7 @@ try {
 Collect IDs from various input formats: space-separated, comma-separated, repeated flags, `@file`, and stdin.
 
 ```typescript
-import { collectIds } from "@outfitter/cli";
+import { collectIds } from "@outfitter/cli/input";
 
 // All these produce the same result:
 // myapp show id1 id2 id3
@@ -116,7 +118,7 @@ const ids = await collectIds(args.ids, {
 Expand `@file` references to file contents. Returns input unchanged if not a file reference.
 
 ```typescript
-import { expandFileArg } from "@outfitter/cli";
+import { expandFileArg } from "@outfitter/cli/input";
 
 // myapp create @template.md
 const content = await expandFileArg(args.content);
@@ -141,7 +143,7 @@ const content = await expandFileArg(args.content, {
 Parse and expand glob patterns using `Bun.Glob`.
 
 ```typescript
-import { parseGlob } from "@outfitter/cli";
+import { parseGlob } from "@outfitter/cli/input";
 
 const files = await parseGlob("src/**/*.ts", {
   cwd: workspaceRoot,
@@ -165,7 +167,7 @@ const files = await parseGlob("src/**/*.ts", {
 Parse `key=value` pairs from CLI input.
 
 ```typescript
-import { parseKeyValue } from "@outfitter/cli";
+import { parseKeyValue } from "@outfitter/cli/input";
 
 // --set key=value --set key2=value2
 // --set key=value,key2=value2
@@ -182,7 +184,7 @@ if (result.isOk()) {
 Parse numeric or date range inputs.
 
 ```typescript
-import { parseRange } from "@outfitter/cli";
+import { parseRange } from "@outfitter/cli/input";
 
 // Numeric range
 const numResult = parseRange("1-10", "number");
@@ -202,7 +204,7 @@ const single = parseRange("5", "number");
 Parse filter expressions from CLI input.
 
 ```typescript
-import { parseFilter } from "@outfitter/cli";
+import { parseFilter } from "@outfitter/cli/input";
 
 const result = parseFilter("status:active,priority:>=high,!archived:true");
 
@@ -232,7 +234,7 @@ if (result.isOk()) {
 Parse sort specification from CLI input.
 
 ```typescript
-import { parseSortSpec } from "@outfitter/cli";
+import { parseSortSpec } from "@outfitter/cli/input";
 
 const result = parseSortSpec("modified:desc,title:asc");
 
@@ -249,7 +251,7 @@ if (result.isOk()) {
 Normalize an identifier with validation.
 
 ```typescript
-import { normalizeId } from "@outfitter/cli";
+import { normalizeId } from "@outfitter/cli/input";
 
 const result = normalizeId("  MY-ID  ", {
   trim: true,
@@ -279,7 +281,7 @@ if (result.isOk()) {
 Prompt for confirmation before destructive operations. Respects `--yes` flag for non-interactive mode.
 
 ```typescript
-import { confirmDestructive } from "@outfitter/cli";
+import { confirmDestructive } from "@outfitter/cli/input";
 
 const result = await confirmDestructive({
   message: "Delete 5 notes?",
@@ -311,7 +313,7 @@ $XDG_STATE_HOME/{toolName}/cursors/{command}[/{context}]/cursor.json
 Load persisted pagination state for a command.
 
 ```typescript
-import { loadCursor } from "@outfitter/cli";
+import { loadCursor } from "@outfitter/cli/pagination";
 
 const state = loadCursor({
   command: "list",
@@ -331,7 +333,7 @@ if (state) {
 Save pagination state for a command.
 
 ```typescript
-import { saveCursor } from "@outfitter/cli";
+import { saveCursor } from "@outfitter/cli/pagination";
 
 const results = await listNotes({ limit: 20 });
 
@@ -348,7 +350,7 @@ if (results.hasMore) {
 Clear persisted pagination state for a command.
 
 ```typescript
-import { clearCursor } from "@outfitter/cli";
+import { clearCursor } from "@outfitter/cli/pagination";
 
 // User passed --reset flag
 if (flags.reset) {
@@ -412,23 +414,10 @@ exitWithError(error); // Exits with code 2
 All types are exported for TypeScript consumers:
 
 ```typescript
-import type {
-  // Core types
-  CLIConfig,
-  CommandConfig,
-  CommandAction,
-  CommandFlags,
-  // Output types
-  OutputMode,
-  OutputOptions,
-  // Input types
-  CollectIdsOptions,
-  ExpandFileOptions,
-  ParseGlobOptions,
-  // Pagination types
-  PaginationState,
-  CursorOptions,
-} from "@outfitter/cli";
+import type { CLIConfig, CommandConfig, CommandAction, CommandFlags } from "@outfitter/cli/command";
+import type { OutputMode, OutputOptions } from "@outfitter/cli/output";
+import type { CollectIdsOptions, ExpandFileOptions, ParseGlobOptions } from "@outfitter/cli/input";
+import type { PaginationState, CursorOptions } from "@outfitter/cli/pagination";
 ```
 
 ## License

package/dist/actions.d.ts

@@ -1,2 +1,13 @@
-import { BuildCliCommandsOptions, buildCliCommands } from "./shared/@outfitter/cli-afecwfrn";
+import { ActionRegistry, ActionSurface, AnyActionSpec, HandlerContext } from "@outfitter/contracts";
+import { Command } from "commander";
+interface BuildCliCommandsOptions {
+	readonly createContext?: (input: {
+		action: AnyActionSpec;
+		args: readonly string[];
+		flags: Record<string, unknown>;
+	}) => HandlerContext;
+	readonly includeSurfaces?: readonly ActionSurface[];
+}
+type ActionSource = ActionRegistry | readonly AnyActionSpec[];
+declare function buildCliCommands(source: ActionSource, options?: BuildCliCommandsOptions): Command[];
 export { buildCliCommands, BuildCliCommandsOptions };

package/dist/actions.js

@@ -1,8 +1,175 @@
 // @bun
+import"./shared/@outfitter/cli-v1tzwxkt.js";
+
+// packages/cli/src/actions.ts
 import {
-  buildCliCommands
-} from "./shared/@outfitter/cli-p0m2fc51.js";
-import"./shared/@outfitter/cli-bt423m6y.js";
+  createContext as createHandlerContext,
+  DEFAULT_REGISTRY_SURFACES,
+  validateInput
+} from "@outfitter/contracts";
+import { Command } from "commander";
+var ARGUMENT_PREFIXES = ["<", "["];
+function isArgumentToken(token) {
+  if (!token) {
+    return false;
+  }
+  return ARGUMENT_PREFIXES.some((prefix) => token.startsWith(prefix));
+}
+function splitCommandSpec(spec) {
+  const parts = spec.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) {
+    return { name: undefined, args: [] };
+  }
+  return { name: parts[0], args: parts.slice(1) };
+}
+function applyArguments(command, args) {
+  for (const arg of args) {
+    command.argument(arg);
+  }
+}
+function applyCliOptions(command, action) {
+  const options = action.cli?.options ?? [];
+  for (const option of options) {
+    if (option.required) {
+      command.requiredOption(option.flags, option.description, option.defaultValue);
+    } else {
+      command.option(option.flags, option.description, option.defaultValue);
+    }
+  }
+}
+function resolveDescription(action) {
+  return action.cli?.description ?? action.description ?? action.id;
+}
+function resolveAliases(action) {
+  return action.cli?.aliases ?? [];
+}
+function resolveCommandSpec(action) {
+  return action.cli?.command ?? action.id;
+}
+function resolveFlags(command) {
+  return command.optsWithGlobals?.() ?? command.opts();
+}
+function resolveInput(action, context) {
+  if (action.cli?.mapInput) {
+    return action.cli.mapInput(context);
+  }
+  const hasFlags = Object.keys(context.flags).length > 0;
+  if (!hasFlags && context.args.length === 0) {
+    return {};
+  }
+  return {
+    ...context.flags,
+    ...context.args.length > 0 ? { args: context.args } : {}
+  };
+}
+async function runAction(action, command, createContext) {
+  const flags = resolveFlags(command);
+  const args = command.args;
+  const inputContext = { args, flags };
+  const input = resolveInput(action, inputContext);
+  const validation = validateInput(action.input, input);
+  if (validation.isErr()) {
+    throw validation.error;
+  }
+  const ctx = createContext({ action, args, flags });
+  const result = await action.handler(validation.value, ctx);
+  if (result.isErr()) {
+    throw result.error;
+  }
+}
+function createCommand(action, createContext, spec) {
+  const commandSpec = spec ?? resolveCommandSpec(action);
+  const { name, args } = splitCommandSpec(commandSpec);
+  if (!name) {
+    throw new Error(`Missing CLI command name for action ${action.id}`);
+  }
+  const command = new Command(name);
+  command.description(resolveDescription(action));
+  applyCliOptions(command, action);
+  applyArguments(command, args);
+  for (const alias of resolveAliases(action)) {
+    command.alias(alias);
+  }
+  command.action(async (...argsList) => {
+    const commandInstance = argsList.at(-1);
+    await runAction(action, commandInstance, createContext);
+  });
+  return command;
+}
+function buildCliCommands(source, options = {}) {
+  const actions = isActionRegistry(source) ? source.list() : source;
+  const includeSurfaces = options.includeSurfaces ?? [
+    "cli"
+  ];
+  const commands = [];
+  const createContext = options.createContext ?? ((_input) => createHandlerContext({
+    cwd: process.cwd(),
+    env: process.env
+  }));
+  const grouped = new Map;
+  const ungrouped = [];
+  for (const action of actions) {
+    const surfaces = action.surfaces ?? DEFAULT_REGISTRY_SURFACES;
+    if (!surfaces.some((surface) => includeSurfaces.includes(surface))) {
+      continue;
+    }
+    const group = action.cli?.group;
+    if (group) {
+      const groupActions = grouped.get(group) ?? [];
+      groupActions.push(action);
+      grouped.set(group, groupActions);
+    } else {
+      ungrouped.push(action);
+    }
+  }
+  for (const action of ungrouped) {
+    commands.push(createCommand(action, createContext));
+  }
+  for (const [groupName, groupActions] of grouped.entries()) {
+    const groupCommand = new Command(groupName);
+    let baseAction;
+    const subcommands = [];
+    for (const action of groupActions) {
+      const spec = action.cli?.command?.trim() ?? "";
+      const { name, args } = splitCommandSpec(spec);
+      if (!name || isArgumentToken(name)) {
+        if (baseAction) {
+          throw new Error(`Group '${groupName}' defines multiple base actions: '${baseAction.id}' and '${action.id}'.`);
+        }
+        baseAction = action;
+        groupCommand.description(resolveDescription(action));
+        applyCliOptions(groupCommand, action);
+        applyArguments(groupCommand, name ? [name, ...args] : args);
+        for (const alias of resolveAliases(action)) {
+          groupCommand.alias(alias);
+        }
+        groupCommand.action(async (...argsList) => {
+          const commandInstance = argsList.at(-1);
+          await runAction(action, commandInstance, createContext);
+        });
+      } else {
+        subcommands.push(action);
+      }
+    }
+    for (const action of subcommands) {
+      const spec = resolveCommandSpec(action);
+      const { name, args } = splitCommandSpec(spec);
+      if (!name) {
+        continue;
+      }
+      const subcommand = createCommand(action, createContext, [name, ...args].join(" "));
+      groupCommand.addCommand(subcommand);
+    }
+    if (!baseAction) {
+      groupCommand.description(groupName);
+    }
+    commands.push(groupCommand);
+  }
+  return commands;
+}
+function isActionRegistry(source) {
+  return "list" in source;
+}
 export {
   buildCliCommands
 };

package/dist/borders/index.d.ts

@@ -0,0 +1,3 @@
+import "../shared/@outfitter/cli-w7w7ta31";
+import { BORDERS, BorderCharacters, BorderStyle, LinePosition, drawHorizontalLine, getBorderCharacters } from "../shared/@outfitter/cli-fakncnjp";
+export { getBorderCharacters, drawHorizontalLine, LinePosition, BorderStyle, BorderCharacters, BORDERS };

package/dist/borders/index.js

@@ -0,0 +1,13 @@
+// @bun
+import"../shared/@outfitter/cli-ktqme80d.js";
+import {
+  BORDERS,
+  drawHorizontalLine,
+  getBorderCharacters
+} from "../shared/@outfitter/cli-85fg2vr5.js";
+import"../shared/@outfitter/cli-v1tzwxkt.js";
+export {
+  getBorderCharacters,
+  drawHorizontalLine,
+  BORDERS
+};

package/dist/box/index.d.ts

@@ -0,0 +1,4 @@
+import "../shared/@outfitter/cli-zfqz333z";
+import { BoxAlign, BoxOptions, renderBox } from "../shared/@outfitter/cli-8xsmsbbd";
+import "../shared/@outfitter/cli-fakncnjp";
+export { renderBox, BoxOptions, BoxAlign };

package/dist/box/index.js

@@ -0,0 +1,13 @@
+// @bun
+import"../shared/@outfitter/cli-f75h8e94.js";
+import {
+  renderBox
+} from "../shared/@outfitter/cli-vp88gxev.js";
+import"../shared/@outfitter/cli-jjemfdta.js";
+import"../shared/@outfitter/cli-85fg2vr5.js";
+import"../shared/@outfitter/cli-9nbyj2bt.js";
+import"../shared/@outfitter/cli-d9ad0rqj.js";
+import"../shared/@outfitter/cli-v1tzwxkt.js";
+export {
+  renderBox
+};

package/dist/cli.js

@@ -2,7 +2,7 @@
 import {
   createCLI
 } from "./shared/@outfitter/cli-efy6jfcj.js";
-import"./shared/@outfitter/cli-bt423m6y.js";
+import"./shared/@outfitter/cli-v1tzwxkt.js";
 export {
   createCLI
 };

package/dist/colors/index.d.ts

@@ -0,0 +1,3 @@
+import "../shared/@outfitter/cli-qz47jk6d";
+import { ANSI, ColorName, Theme, TokenOptions, Tokens, applyColor, createTheme, createTokens, resolveTokenColorEnabled } from "../shared/@outfitter/cli-xsaheemc";
+export { resolveTokenColorEnabled, createTokens, createTheme, applyColor, Tokens, TokenOptions, Theme, ColorName, ANSI };

package/dist/colors/index.js

@@ -0,0 +1,18 @@
+// @bun
+import"../shared/@outfitter/cli-0psys2vm.js";
+import {
+  ANSI,
+  applyColor,
+  createTheme,
+  createTokens,
+  resolveTokenColorEnabled
+} from "../shared/@outfitter/cli-9nbyj2bt.js";
+import"../shared/@outfitter/cli-d9ad0rqj.js";
+import"../shared/@outfitter/cli-v1tzwxkt.js";
+export {
+  resolveTokenColorEnabled,
+  createTokens,
+  createTheme,
+  applyColor,
+  ANSI
+};

package/dist/command.d.ts

@@ -1,3 +1,40 @@
-import { command } from "./shared/@outfitter/cli-2yq94zst";
-import "./shared/@outfitter/cli-ttt7r0j7";
-export { command };
+import { createCLI } from "./shared/@outfitter/cli-mhamvbty";
+import { CommandBuilder } from "./shared/@outfitter/cli-ttt7r0j7";
+/**
+* Create a new command builder with the given name.
+*
+* The command builder provides a fluent API for defining CLI commands
+* with typed flags, arguments, and actions.
+*
+* @param name - Command name and optional argument syntax (e.g., "list" or "get <id>")
+* @returns A CommandBuilder instance for fluent configuration
+*
+* @example
+* ```typescript
+* import { command, output } from "@outfitter/cli";
+*
+* const list = command("list")
+*   .description("List all notes")
+*   .option("--limit <n>", "Max results", "20")
+*   .option("--json", "Output as JSON")
+*   .option("--next", "Continue from last position")
+*   .action(async ({ flags }) => {
+*     const results = await listNotes(flags);
+*     output(results);
+*   });
+* ```
+*
+* @example
+* ```typescript
+* // Command with required argument
+* const get = command("get <id>")
+*   .description("Get a note by ID")
+*   .action(async ({ args }) => {
+*     const [id] = args;
+*     const note = await getNote(id);
+*     output(note);
+*   });
+* ```
+*/
+declare function command(name: string): CommandBuilder;
+export { createCLI, command };

package/dist/command.js

@@ -1,8 +1,50 @@
 // @bun
 import {
-  command
-} from "./shared/@outfitter/cli-8r0bnyyx.js";
-import"./shared/@outfitter/cli-bt423m6y.js";
+  createCLI
+} from "./shared/@outfitter/cli-efy6jfcj.js";
+import"./shared/@outfitter/cli-v1tzwxkt.js";
+
+// packages/cli/src/command.ts
+import { Command } from "commander";
+
+class CommandBuilderImpl {
+  command;
+  constructor(name) {
+    this.command = new Command(name);
+  }
+  description(text) {
+    this.command.description(text);
+    return this;
+  }
+  option(flags, description, defaultValue) {
+    this.command.option(flags, description, defaultValue);
+    return this;
+  }
+  requiredOption(flags, description, defaultValue) {
+    this.command.requiredOption(flags, description, defaultValue);
+    return this;
+  }
+  alias(alias) {
+    this.command.alias(alias);
+    return this;
+  }
+  action(handler) {
+    this.command.action(async (...args) => {
+      const command = args.at(-1);
+      const flags = command.optsWithGlobals?.() ?? command.opts();
+      const positional = command.args;
+      await handler({ args: positional, flags, command });
+    });
+    return this;
+  }
+  build() {
+    return this.command;
+  }
+}
+function command(name) {
+  return new CommandBuilderImpl(name);
+}
 export {
+  createCLI,
   command
 };

package/dist/demo/index.d.ts

@@ -0,0 +1,78 @@
+import { BORDER_STYLE_META, LIST_STYLE_META, PRIMITIVE_META, SPINNER_STYLE_META, THEME_METHOD_META, getBorderStyles, getListStyles, getPrimitiveIds, getSpinnerStyles, getThemeMethodsByCategory } from "../shared/@outfitter/cli-96b2p4td";
+import "../shared/@outfitter/cli-e5ms1y0x";
+import "../shared/@outfitter/cli-b0tzqgnf";
+import "../shared/@outfitter/cli-fakncnjp";
+import { SectionOptions, SubsectionOptions, codeBlock, demoContent, demoSection, demoSubsection, description } from "../shared/@outfitter/cli-d7jpshq5";
+import "../shared/@outfitter/cli-6bztk73z";
+import "../shared/@outfitter/cli-2g8bx1aq";
+import { DEFAULT_EXAMPLES, getExample } from "../shared/@outfitter/cli-7nm6edvh";
+import { DemoConfig, DemoRegistryEntry, DemoRenderer, ExampleTexts, PrimitiveId, PrimitiveMeta, ThemeMethodCategory, ThemeMethodMeta, VariantMeta, isPrimitiveId } from "../shared/@outfitter/cli-qjfc3j11";
+import "../shared/@outfitter/cli-xsaheemc";
+/**
+* Renders a demo for a specific primitive.
+*
+* @param id - The primitive to demo
+* @param config - Optional configuration for customization
+* @returns Formatted demo output string
+*
+* @example
+* ```typescript
+* // Default examples
+* console.log(renderDemo("colors"));
+*
+* // Custom examples
+* console.log(renderDemo("colors", {
+*   examples: { success: "Build completed" }
+* }));
+*
+* // No code examples
+* console.log(renderDemo("table", { showCode: false }));
+* ```
+*/
+declare function renderDemo(id: PrimitiveId, config?: DemoConfig): string;
+/**
+* Renders demos for all primitives.
+*
+* @param config - Optional configuration applied to all demos
+* @returns Combined output from all demos, separated by blank lines
+*
+* @example
+* ```typescript
+* console.log(renderAllDemos());
+*
+* // With custom config
+* console.log(renderAllDemos({
+*   showCode: false,
+*   showDescriptions: true,
+* }));
+* ```
+*/
+declare function renderAllDemos(config?: DemoConfig): string;
+/**
+* Gets metadata for a specific primitive.
+*
+* @param id - The primitive ID
+* @returns Primitive metadata including name, description, and import example
+*
+* @example
+* ```typescript
+* const meta = getPrimitive("colors");
+* console.log(meta.name); // "Colors"
+* console.log(meta.importExample); // 'import { createTheme } from "@outfitter/cli/render";'
+* ```
+*/
+declare function getPrimitive(id: PrimitiveId): PrimitiveMeta;
+/**
+* Gets all primitives with their metadata.
+*
+* @returns Array of all primitive metadata
+*/
+declare function getAllPrimitives(): PrimitiveMeta[];
+/**
+* Gets a registry entry with both metadata and renderer.
+*
+* @param id - The primitive ID
+* @returns Registry entry with meta and render function
+*/
+declare function getDemoEntry(id: PrimitiveId): DemoRegistryEntry;
+export { renderDemo, renderAllDemos, isPrimitiveId, getThemeMethodsByCategory, getSpinnerStyles, getPrimitiveIds, getPrimitive, getListStyles, getExample, getDemoEntry, getBorderStyles, getAllPrimitives, description, demoSubsection, demoSection, demoContent, codeBlock, VariantMeta, ThemeMethodMeta, ThemeMethodCategory, THEME_METHOD_META, SubsectionOptions, SectionOptions, SPINNER_STYLE_META, PrimitiveMeta, PrimitiveId, PRIMITIVE_META, LIST_STYLE_META, ExampleTexts, DemoRenderer, DemoRegistryEntry, DemoConfig, DEFAULT_EXAMPLES, BORDER_STYLE_META };