@outfitter/cli 0.5.3 → 1.0.0

package/dist/shared/@outfitter/cli-6shkwxdc.js

@@ -0,0 +1,28 @@
+// @bun
+// packages/cli/src/internal/input-helpers.ts
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    if (typeof chunk === "string") {
+      chunks.push(chunk);
+    } else if (Buffer.isBuffer(chunk)) {
+      chunks.push(chunk.toString("utf-8"));
+    } else if (chunk instanceof Uint8Array) {
+      chunks.push(Buffer.from(chunk).toString("utf-8"));
+    }
+  }
+  return chunks.join("");
+}
+function splitIds(input) {
+  return input.split(",").flatMap((part) => part.trim().split(/\s+/)).map((id) => id.trim()).filter(Boolean);
+}
+async function isDirectory(dirPath) {
+  try {
+    const result = await Bun.$`test -d ${dirPath}`.quiet();
+    return result.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+export { readStdin, splitIds, isDirectory };

package/dist/shared/@outfitter/cli-89335n9a.js

@@ -0,0 +1,16 @@
+// @bun
+import {
+  unwrapZodField
+} from "./cli-3jta1h1h.js";
+
+// packages/cli/src/hints.ts
+function schemaHintParams(schema) {
+  const params = {};
+  for (const [fieldName, field] of Object.entries(schema.shape)) {
+    const info = unwrapZodField(field);
+    params[fieldName] = info.description ?? info.baseType;
+  }
+  return params;
+}
+
+export { schemaHintParams };

package/dist/shared/@outfitter/cli-8999qjdd.js

@@ -0,0 +1,3 @@
+export { composePresets, createPreset, createSchemaPreset, isSchemaPreset } from "../../internal/flag-types.js";
+export { booleanFlagPreset, enumFlagPreset, numberFlagPreset, stringListFlagPreset } from "../../internal/flag-builders.js";
+export { colorPreset, cwdPreset, dryRunPreset, executionPreset, forcePreset, interactionPreset, paginationPreset, projectionPreset, strictPreset, timeWindowPreset, verbosePreset } from "../../internal/presets.js";

package/dist/shared/@outfitter/cli-8cfxdady.js

@@ -0,0 +1,60 @@
+// @bun
+// packages/cli/src/internal/flag-types.ts
+var PRESET_IDS = Symbol("presetIds");
+function createPreset(config) {
+  const preset = {
+    id: config.id,
+    options: config.options,
+    resolve: config.resolve
+  };
+  preset[PRESET_IDS] = [config.id];
+  return preset;
+}
+function createSchemaPreset(config) {
+  return {
+    id: config.id,
+    schema: config.schema,
+    resolve: config.resolve
+  };
+}
+function isSchemaPreset(preset) {
+  return "schema" in preset && !("options" in preset);
+}
+function getPresetIds(preset) {
+  const ids = preset[PRESET_IDS];
+  return ids && ids.length > 0 ? ids : [preset.id];
+}
+function composePresets(...presets) {
+  const seen = new Set;
+  const mergedIds = [];
+  const mergedOptions = [];
+  const resolvers = [];
+  for (const preset of presets) {
+    const presetIds = getPresetIds(preset);
+    if (presetIds.every((id) => seen.has(id)))
+      continue;
+    for (const id of presetIds) {
+      if (seen.has(id))
+        continue;
+      seen.add(id);
+      mergedIds.push(id);
+    }
+    mergedOptions.push(...preset.options);
+    resolvers.push(preset.resolve);
+  }
+  const composed = {
+    id: mergedIds.join("+"),
+    options: mergedOptions,
+    resolve: (flags) => {
+      let result = {};
+      for (const resolver of resolvers) {
+        result = { ...result, ...resolver(flags) };
+      }
+      return result;
+    }
+  };
+  composed[PRESET_IDS] = mergedIds;
+  return composed;
+}
+
+export { createPreset, createSchemaPreset, isSchemaPreset, composePresets };

package/dist/shared/@outfitter/cli-bcajqy33.d.ts

@@ -0,0 +1,25 @@
+import { CollectIdsOptions } from "./cli-x6qr7bnd.js";
+/**
+* Collect IDs from various input formats.
+*
+* Handles space-separated, comma-separated, repeated flags, @file, and stdin.
+*
+* @param input - Raw input from CLI arguments
+* @param options - Collection options
+* @returns Array of collected IDs
+*
+* @example
+* ```typescript
+* // All these produce the same result:
+* // wm show id1 id2 id3
+* // wm show id1,id2,id3
+* // wm show --ids id1 --ids id2
+* // wm show @ids.txt
+* const ids = await collectIds(args.ids, {
+*   allowFile: true,
+*   allowStdin: true,
+* });
+* ```
+*/
+declare function collectIds(input: string | readonly string[], options?: CollectIdsOptions): Promise<string[]>;
+export { collectIds };

package/dist/shared/@outfitter/cli-c09332vm.d.ts

@@ -0,0 +1,39 @@
+import { RunHandlerOptions } from "./cli-30mt7c5w.js";
+/**
+* Bridge the full CommandBuilder lifecycle: context factory → handler
+* invocation → Result unwrap → envelope construction → output
+* formatting → exit code mapping.
+*
+* On success:
+* - Builds a `{ ok: true, command, result, hints? }` envelope
+* - Outputs to stdout (JSON or human-readable)
+* - Returns normally (exit code 0)
+*
+* On error:
+* - Builds a `{ ok: false, command, error: { category, message }, hints? }` envelope
+* - Outputs to stderr (JSON or human-readable)
+* - Exits with mapped exit code from error taxonomy
+*
+* @example
+* ```typescript
+* command("deploy")
+*   .input(z.object({ env: z.string() }))
+*   .action(async ({ input }) => {
+*     await runHandler({
+*       command: "deploy",
+*       handler: async (input) => deployService(input),
+*       input,
+*       format: outputMode,
+*       hints: (result, input) => [
+*         { description: "Check status", command: `deploy status --env ${input.env}` },
+*       ],
+*     });
+*   });
+* ```
+*/
+declare function runHandler<
+	TInput = unknown,
+	TOutput = unknown,
+	TContext = unknown
+>(options: RunHandlerOptions<TInput, TOutput, TContext>): Promise<void>;
+export { runHandler };

package/dist/shared/@outfitter/cli-cgha038c.d.ts

@@ -0,0 +1,3 @@
+import { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions } from "@outfitter/schema";
+import { generateManifest } from "@outfitter/schema";
+export { ActionManifest, ActionManifestEntry, ActionSource, GenerateManifestOptions, generateManifest };

package/dist/shared/@outfitter/{cli-zahqsaby.js → cli-d40m2x1d.js}

@@ -1,4 +1,11 @@
 // @bun
+import {
+  buildCommandTree
+} from "./cli-htzez8v2.js";
+import {
+  output
+} from "./cli-4h85mpth.js";
+
 // packages/cli/src/cli.ts
 import { Command } from "commander";
 function isCommanderHelp(error) {
@@ -13,7 +20,7 @@ function createCLI(config) {
       return;
     }
     if (bridgedJsonEnvPrevious === undefined) {
-      process.env["OUTFITTER_JSON"] = undefined;
+      delete process.env["OUTFITTER_JSON"];
     } else {
       process.env["OUTFITTER_JSON"] = bridgedJsonEnvPrevious;
     }
@@ -24,10 +31,10 @@ function createCLI(config) {
   if (config.description) {
     program.description(config.description);
   }
-  program.option("--json", "Output as JSON", false);
+  program.option("--json", "Output as JSON");
   program.hook("preAction", (thisCommand) => {
     const allOpts = thisCommand.optsWithGlobals();
-    if (allOpts["json"] && !bridgedJsonEnvActive) {
+    if (allOpts["json"] === true && !bridgedJsonEnvActive) {
       bridgedJsonEnvPrevious = process.env["OUTFITTER_JSON"];
       process.env["OUTFITTER_JSON"] = "1";
       bridgedJsonEnvActive = true;
@@ -38,6 +45,15 @@ function createCLI(config) {
   });
   const exit = config.onExit ?? ((code) => void process.exit(code));
   program.exitOverride();
+  program.action(async () => {
+    const isJsonMode = program.opts()["json"] === true || process.env["OUTFITTER_JSON"] === "1" || process.env["OUTFITTER_JSONL"] === "1" || !process.stdout.isTTY;
+    if (isJsonMode) {
+      const tree = buildCommandTree(program);
+      await output(tree, "json");
+    } else {
+      program.outputHelp();
+    }
+  });
   const parse = async (argv) => {
     try {
       await program.parseAsync(argv ?? process.argv);

package/dist/shared/@outfitter/cli-dg0cz7rw.js

@@ -0,0 +1,127 @@
+// @bun
+// packages/cli/src/internal/output-formatting.ts
+import {
+  safeStringify as contractsSafeStringify,
+  exitCodeMap
+} from "@outfitter/contracts";
+var DEFAULT_EXIT_CODE = 1;
+function detectMode(format) {
+  if (format) {
+    return format;
+  }
+  const envJsonl = process.env["OUTFITTER_JSONL"];
+  const envJson = process.env["OUTFITTER_JSON"];
+  if (envJsonl === "1")
+    return "jsonl";
+  if (envJson === "1")
+    return "json";
+  if (envJsonl === "0" || envJson === "0")
+    return "human";
+  return "human";
+}
+function cliStringify(value, pretty) {
+  const wrappedValue = value === undefined ? null : value;
+  return contractsSafeStringify(wrappedValue, pretty ? 2 : undefined);
+}
+function formatHuman(data) {
+  if (data === null || data === undefined) {
+    return "";
+  }
+  if (typeof data === "string") {
+    return data;
+  }
+  if (typeof data === "number" || typeof data === "boolean") {
+    return String(data);
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => formatHuman(item)).join(`
+`);
+  }
+  if (typeof data === "object") {
+    const lines = [];
+    for (const [key, value] of Object.entries(data)) {
+      lines.push(`${key}: ${formatHuman(value)}`);
+    }
+    return lines.join(`
+`);
+  }
+  return String(data);
+}
+function getErrorProperties(error) {
+  const errorObj = error;
+  return {
+    _tag: errorObj._tag,
+    category: errorObj.category,
+    context: errorObj.context
+  };
+}
+function isValidCategory(category) {
+  return category in exitCodeMap;
+}
+function getExitCode(error) {
+  const { category } = getErrorProperties(error);
+  if (category !== undefined && isValidCategory(category)) {
+    return exitCodeMap[category];
+  }
+  return DEFAULT_EXIT_CODE;
+}
+function serializeErrorToJson(error) {
+  const { _tag, category, context } = getErrorProperties(error);
+  const result = {
+    message: error.message
+  };
+  if (_tag !== undefined) {
+    result._tag = _tag;
+  }
+  if (category !== undefined) {
+    result.category = category;
+  }
+  if (context !== undefined) {
+    result.context = context;
+  }
+  return JSON.stringify(result);
+}
+function formatErrorHuman(error) {
+  const { _tag } = getErrorProperties(error);
+  if (_tag) {
+    return `${_tag}: ${error.message}`;
+  }
+  return error.message;
+}
+function applyOutputTruncation(data, truncation) {
+  if (!truncation || !Array.isArray(data)) {
+    return data;
+  }
+  const rawOffset = truncation.offset;
+  const offset = typeof rawOffset === "number" && Number.isFinite(rawOffset) ? Math.max(0, rawOffset) : 0;
+  const rawLimit = truncation.limit;
+  if (typeof rawLimit !== "number" || !Number.isFinite(rawLimit)) {
+    return data;
+  }
+  const limit = Math.max(0, rawLimit);
+  return data.slice(offset, offset + limit);
+}
+function writeWithBackpressure(stream, data) {
+  return new Promise((resolve, reject) => {
+    const canContinue = stream.write(data, (error) => {
+      if (error)
+        reject(error);
+    });
+    if (canContinue) {
+      resolve();
+    } else {
+      const onDrain = () => {
+        stream.removeListener("error", onError);
+        resolve();
+      };
+      const onError = (err) => {
+        stream.removeListener("drain", onDrain);
+        reject(err);
+      };
+      stream.once("drain", onDrain);
+      stream.once("error", onError);
+    }
+  });
+}
+
+export { detectMode, cliStringify, formatHuman, getExitCode, serializeErrorToJson, formatErrorHuman, applyOutputTruncation, writeWithBackpressure };

package/dist/shared/@outfitter/cli-dv8kk4jw.d.ts

@@ -0,0 +1,24 @@
+import { BooleanFlagPresetConfig, EnumFlagPresetConfig, FlagPreset, NumberFlagPresetConfig, StringListFlagPresetConfig } from "./cli-x6qr7bnd.js";
+/**
+* Generic boolean custom-flag builder.
+*
+* Supports normal sources and negated sources so `--no-foo` patterns can
+* resolve consistently across Commander flag-shape differences.
+*/
+declare function booleanFlagPreset<TKey extends string>(config: BooleanFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : boolean }>;
+/**
+* Generic enum custom-flag builder.
+*/
+declare function enumFlagPreset<
+	TKey extends string,
+	TValue extends string
+>(config: EnumFlagPresetConfig<TKey, TValue>): FlagPreset<{ [K in TKey] : TValue }>;
+/**
+* Generic number custom-flag builder.
+*/
+declare function numberFlagPreset<TKey extends string>(config: NumberFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : number }>;
+/**
+* Generic string-list custom-flag builder.
+*/
+declare function stringListFlagPreset<TKey extends string>(config: StringListFlagPresetConfig<TKey>): FlagPreset<{ [K in TKey] : string[] | undefined }>;
+export { booleanFlagPreset, enumFlagPreset, numberFlagPreset, stringListFlagPreset };

package/dist/shared/@outfitter/cli-g43887b7.js

@@ -0,0 +1,20 @@
+// @bun
+import {
+  cliStringify
+} from "./cli-dg0cz7rw.js";
+
+// packages/cli/src/streaming.ts
+function writeNdjsonLine(data) {
+  process.stdout.write(`${cliStringify(data)}
+`);
+}
+function writeStreamEnvelope(envelope) {
+  writeNdjsonLine(envelope);
+}
+function createNdjsonProgress(_commandName) {
+  return (event) => {
+    writeNdjsonLine(event);
+  };
+}
+
+export { writeNdjsonLine, writeStreamEnvelope, createNdjsonProgress };

package/dist/shared/@outfitter/cli-gqtkhgw4.js

@@ -0,0 +1,52 @@
+// @bun
+import {
+  isSecurePath
+} from "./cli-sy99pjyj.js";
+import {
+  readStdin,
+  splitIds
+} from "./cli-6shkwxdc.js";
+
+// packages/cli/src/internal/input-normalization.ts
+async function collectIds(input, options) {
+  const { allowFile = true, allowStdin = true } = options ?? {};
+  const ids = [];
+  const inputs = Array.isArray(input) ? input : [input];
+  for (const item of inputs) {
+    if (!item)
+      continue;
+    if (item.startsWith("@")) {
+      const filePath = item.slice(1);
+      if (filePath === "-") {
+        if (!allowStdin) {
+          throw new Error("Reading from stdin is not allowed");
+        }
+        const stdinContent = await readStdin();
+        const stdinIds = stdinContent.split(`
+`).map((line) => line.trim()).filter(Boolean);
+        ids.push(...stdinIds);
+      } else {
+        if (!allowFile) {
+          throw new Error("File references are not allowed");
+        }
+        if (!isSecurePath(filePath, true)) {
+          throw new Error(`Security error: path traversal not allowed: ${filePath}`);
+        }
+        const file = Bun.file(filePath);
+        const exists = await file.exists();
+        if (!exists) {
+          throw new Error(`File not found: ${filePath}`);
+        }
+        const content = await file.text();
+        const fileIds = content.split(`
+`).map((line) => line.trim()).filter(Boolean);
+        ids.push(...fileIds);
+      }
+    } else {
+      ids.push(...splitIds(item));
+    }
+  }
+  return [...new Set(ids)];
+}
+
+export { collectIds };

package/dist/shared/@outfitter/cli-h4ejpmjs.d.ts

@@ -0,0 +1,104 @@
+import { ExpandFileOptions, FilterExpression, KeyValuePair, ParseGlobOptions, Range, SortCriteria } from "./cli-x6qr7bnd.js";
+import { ValidationError } from "@outfitter/contracts";
+import { Result } from "better-result";
+/**
+* Expand @file references to file contents.
+*
+* If the input starts with @, reads the file and returns its contents.
+* Otherwise, returns the input unchanged.
+*
+* @param input - Raw input that may be a @file reference
+* @param options - Expansion options
+* @returns File contents or original input
+*
+* @example
+* ```typescript
+* // wm create @template.md
+* const content = await expandFileArg(args.content);
+* ```
+*/
+declare function expandFileArg(input: string, options?: ExpandFileOptions): Promise<string>;
+/**
+* Parse and expand glob patterns.
+*
+* Uses Bun.Glob with workspace constraints.
+*
+* @param pattern - Glob pattern to expand
+* @param options - Glob options
+* @returns Array of matched file paths
+*
+* @example
+* ```typescript
+* // wm index "src/**\/*.ts"
+* const files = await parseGlob(args.pattern, {
+*   cwd: workspaceRoot,
+*   ignore: ["node_modules/**"],
+* });
+* ```
+*/
+declare function parseGlob(pattern: string, options?: ParseGlobOptions): Promise<string[]>;
+/**
+* Parse key=value pairs from CLI input.
+*
+* @param input - Raw input containing key=value pairs
+* @returns Array of parsed key-value pairs
+*
+* @example
+* ```typescript
+* // --set key=value --set key2=value2
+* // --set key=value,key2=value2
+* const pairs = parseKeyValue(args.set);
+* // => [{ key: "key", value: "value" }, { key: "key2", value: "value2" }]
+* ```
+*/
+declare function parseKeyValue(input: string | readonly string[]): Result<KeyValuePair[], InstanceType<typeof ValidationError>>;
+/**
+* Parse range inputs (numeric or date).
+*
+* @param input - Range string (e.g., "1-10" or "2024-01-01..2024-12-31")
+* @param type - Type of range to parse
+* @returns Parsed range
+*
+* @example
+* ```typescript
+* parseRange("1-10", "number");
+* // => Result<{ type: "number", min: 1, max: 10 }, ValidationError>
+*
+* parseRange("2024-01-01..2024-12-31", "date");
+* // => Result<{ type: "date", start: Date, end: Date }, ValidationError>
+* ```
+*/
+declare function parseRange(input: string, type: "number" | "date"): Result<Range, InstanceType<typeof ValidationError>>;
+/**
+* Parse filter expressions from CLI input.
+*
+* @param input - Filter string (e.g., "status:active,priority:high")
+* @returns Array of parsed filter expressions
+*
+* @example
+* ```typescript
+* parseFilter("status:active,priority:high");
+* // => Result<[
+* //   { field: "status", value: "active" },
+* //   { field: "priority", value: "high" }
+* // ], ValidationError>
+* ```
+*/
+declare function parseFilter(input: string): Result<FilterExpression[], InstanceType<typeof ValidationError>>;
+/**
+* Parse sort specification from CLI input.
+*
+* @param input - Sort string (e.g., "modified:desc,title:asc")
+* @returns Array of parsed sort criteria
+*
+* @example
+* ```typescript
+* parseSortSpec("modified:desc,title:asc");
+* // => Result<[
+* //   { field: "modified", direction: "desc" },
+* //   { field: "title", direction: "asc" }
+* // ], ValidationError>
+* ```
+*/
+declare function parseSortSpec(input: string): Result<SortCriteria[], InstanceType<typeof ValidationError>>;
+export { expandFileArg, parseGlob, parseKeyValue, parseRange, parseFilter, parseSortSpec };

package/dist/shared/@outfitter/cli-htzez8v2.js

@@ -0,0 +1,70 @@
+// @bun
+// packages/cli/src/internal/hint-command-tree.ts
+function isHiddenCommand(cmd) {
+  return cmd.hidden === true;
+}
+function buildCommandNode(cmd) {
+  const options = cmd.options.filter((opt) => !opt.hidden).map((opt) => {
+    const entry = {
+      flags: opt.flags,
+      description: opt.description
+    };
+    if (opt.defaultValue !== undefined) {
+      return { ...entry, defaultValue: opt.defaultValue };
+    }
+    if (opt.required) {
+      return { ...entry, required: true };
+    }
+    return entry;
+  });
+  const subcommands = cmd.commands.filter((sub) => !isHiddenCommand(sub)).map((sub) => buildCommandNode(sub));
+  const metadata = cmd.__metadata;
+  const node = {
+    name: cmd.name()
+  };
+  const description = cmd.description();
+  if (description) {
+    return {
+      ...node,
+      description,
+      ...metadata ? { metadata } : {},
+      ...options.length > 0 ? { options } : {},
+      ...subcommands.length > 0 ? { subcommands } : {}
+    };
+  }
+  return {
+    ...node,
+    ...metadata ? { metadata } : {},
+    ...options.length > 0 ? { options } : {},
+    ...subcommands.length > 0 ? { subcommands } : {}
+  };
+}
+function buildCommandTree(program) {
+  const version = program.version() ?? "0.0.0";
+  const commands = program.commands.filter((cmd) => !isHiddenCommand(cmd)).map((cmd) => buildCommandNode(cmd));
+  const description = program.description();
+  const tree = {
+    name: program.name(),
+    version,
+    ...description ? { description } : {},
+    commands
+  };
+  return tree;
+}
+function commandTreeHints(tree) {
+  const hints = [];
+  function walkCommands(nodes, pathPrefix) {
+    for (const node of nodes) {
+      const fullCommand = `${pathPrefix} ${node.name}`.trim();
+      const description = node.description ?? `Run ${node.name} command`;
+      hints.push({ description, command: fullCommand });
+      if (node.subcommands && node.subcommands.length > 0) {
+        walkCommands(node.subcommands, fullCommand);
+      }
+    }
+  }
+  walkCommands(tree.commands, tree.name);
+  return hints;
+}
+
+export { buildCommandTree, commandTreeHints };