@outfitter/cli 0.5.2 → 1.0.0

package/dist/shared/@outfitter/cli-1q5redaj.js

@@ -0,0 +1,267 @@
+// @bun
+import {
+  isSecureGlobPattern,
+  isSecurePath,
+  isWithinWorkspace
+} from "./cli-sy99pjyj.js";
+import {
+  isDirectory,
+  readStdin
+} from "./cli-6shkwxdc.js";
+
+// packages/cli/src/internal/input-parsers.ts
+import path from "path";
+import { ValidationError } from "@outfitter/contracts";
+import { Err, Ok } from "better-result";
+async function expandFileArg(input, options) {
+  const {
+    encoding: _encoding = "utf-8",
+    maxSize,
+    trim = false
+  } = options ?? {};
+  if (!input.startsWith("@")) {
+    return input;
+  }
+  const filePath = input.slice(1);
+  if (filePath === "-") {
+    let content2 = await readStdin();
+    if (trim) {
+      content2 = content2.trim();
+    }
+    return content2;
+  }
+  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}`);
+  }
+  if (maxSize !== undefined) {
+    const size = file.size;
+    if (size > maxSize) {
+      throw new Error(`File exceeds maximum size of ${maxSize} bytes`);
+    }
+  }
+  let content = await file.text();
+  if (trim) {
+    content = content.trim();
+  }
+  return content;
+}
+async function parseGlob(pattern, options) {
+  const {
+    cwd = process.cwd(),
+    ignore = [],
+    onlyFiles = false,
+    onlyDirectories = false,
+    followSymlinks = false
+  } = options ?? {};
+  if (!isSecureGlobPattern(pattern)) {
+    throw new Error(`Security error: glob pattern may escape workspace: ${pattern}`);
+  }
+  const resolvedCwd = path.resolve(cwd);
+  const glob = new Bun.Glob(pattern);
+  const matches = [];
+  const scanOptions = {
+    cwd,
+    followSymlinks,
+    onlyFiles: onlyFiles === true
+  };
+  for await (const match of glob.scan(scanOptions)) {
+    const fullPath = path.resolve(cwd, match);
+    if (!isWithinWorkspace(fullPath, resolvedCwd)) {
+      continue;
+    }
+    let shouldIgnore = false;
+    for (const ignorePattern of ignore) {
+      const ignoreGlob = new Bun.Glob(ignorePattern);
+      if (ignoreGlob.match(match)) {
+        shouldIgnore = true;
+        break;
+      }
+    }
+    if (shouldIgnore)
+      continue;
+    if (onlyDirectories) {
+      const isDir = await isDirectory(fullPath);
+      if (!isDir)
+        continue;
+    }
+    matches.push(match);
+  }
+  return matches;
+}
+function parseKeyValue(input) {
+  const pairs = [];
+  const inputs = Array.isArray(input) ? input : [input];
+  for (const item of inputs) {
+    if (!item)
+      continue;
+    const parts = item.split(",");
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (!trimmed)
+        continue;
+      const eqIndex = trimmed.indexOf("=");
+      if (eqIndex === -1) {
+        return new Err(new ValidationError({
+          message: `Missing '=' in key-value pair: ${trimmed}`
+        }));
+      }
+      const key = trimmed.slice(0, eqIndex).trim();
+      const value = trimmed.slice(eqIndex + 1);
+      if (!key) {
+        return new Err(new ValidationError({ message: "Empty key in key-value pair" }));
+      }
+      pairs.push({ key, value });
+    }
+  }
+  return new Ok(pairs);
+}
+function parseRange(input, type) {
+  const trimmed = input.trim();
+  if (type === "date") {
+    const parts = trimmed.split("..");
+    if (parts.length === 1) {
+      const dateStr = parts[0];
+      if (dateStr === undefined) {
+        return new Err(new ValidationError({ message: "Empty date input" }));
+      }
+      const date = new Date(dateStr.trim());
+      if (Number.isNaN(date.getTime())) {
+        return new Err(new ValidationError({ message: `Invalid date format: ${dateStr}` }));
+      }
+      return new Ok({ type: "date", start: date, end: date });
+    }
+    if (parts.length === 2) {
+      const startStr = parts[0];
+      const endStr = parts[1];
+      if (startStr === undefined || endStr === undefined) {
+        return new Err(new ValidationError({ message: "Invalid date range format" }));
+      }
+      const start = new Date(startStr.trim());
+      const end = new Date(endStr.trim());
+      if (Number.isNaN(start.getTime())) {
+        return new Err(new ValidationError({ message: `Invalid date format: ${startStr}` }));
+      }
+      if (Number.isNaN(end.getTime())) {
+        return new Err(new ValidationError({ message: `Invalid date format: ${endStr}` }));
+      }
+      if (start.getTime() > end.getTime()) {
+        return new Err(new ValidationError({
+          message: "Start date must be before or equal to end date"
+        }));
+      }
+      return new Ok({ type: "date", start, end });
+    }
+    return new Err(new ValidationError({ message: `Invalid date range format: ${input}` }));
+  }
+  const singleNum = Number(trimmed);
+  if (!(Number.isNaN(singleNum) || trimmed.includes("-", trimmed.startsWith("-") ? 1 : 0))) {
+    return new Ok({ type: "number", min: singleNum, max: singleNum });
+  }
+  let separatorIndex = -1;
+  for (let i = 1;i < trimmed.length; i++) {
+    const char = trimmed[i];
+    const prevChar = trimmed[i - 1];
+    if (char === "-" && prevChar !== undefined && /[\d\s]/.test(prevChar)) {
+      separatorIndex = i;
+      break;
+    }
+  }
+  if (separatorIndex === -1) {
+    return new Err(new ValidationError({ message: `Invalid numeric range format: ${input}` }));
+  }
+  const minStr = trimmed.slice(0, separatorIndex).trim();
+  const maxStr = trimmed.slice(separatorIndex + 1).trim();
+  const min = Number(minStr);
+  const max = Number(maxStr);
+  if (Number.isNaN(min)) {
+    return new Err(new ValidationError({ message: `Invalid number: ${minStr}` }));
+  }
+  if (Number.isNaN(max)) {
+    return new Err(new ValidationError({ message: `Invalid number: ${maxStr}` }));
+  }
+  if (min > max) {
+    return new Err(new ValidationError({ message: "Min must be less than or equal to max" }));
+  }
+  return new Ok({ type: "number", min, max });
+}
+function parseFilter(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return new Ok([]);
+  }
+  const filters = [];
+  const parts = trimmed.split(",");
+  for (const part of parts) {
+    let partTrimmed = part.trim();
+    if (!partTrimmed)
+      continue;
+    let isNegated = false;
+    if (partTrimmed.startsWith("!")) {
+      isNegated = true;
+      partTrimmed = partTrimmed.slice(1).trim();
+    }
+    const colonIndex = partTrimmed.indexOf(":");
+    if (colonIndex === -1) {
+      return new Err(new ValidationError({
+        message: `Missing ':' in filter expression: ${part.trim()}`
+      }));
+    }
+    const field = partTrimmed.slice(0, colonIndex).trim();
+    let value = partTrimmed.slice(colonIndex + 1).trim();
+    let operator;
+    if (isNegated) {
+      operator = "ne";
+    } else if (value.startsWith(">=")) {
+      operator = "gte";
+      value = value.slice(2).trim();
+    } else if (value.startsWith("<=")) {
+      operator = "lte";
+      value = value.slice(2).trim();
+    } else if (value.startsWith(">")) {
+      operator = "gt";
+      value = value.slice(1).trim();
+    } else if (value.startsWith("<")) {
+      operator = "lt";
+      value = value.slice(1).trim();
+    } else if (value.startsWith("~")) {
+      operator = "contains";
+      value = value.slice(1).trim();
+    }
+    filters.push(operator ? { field, operator, value } : { field, value });
+  }
+  return new Ok(filters);
+}
+function parseSortSpec(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return new Ok([]);
+  }
+  const criteria = [];
+  const parts = trimmed.split(",");
+  for (const part of parts) {
+    const partTrimmed = part.trim();
+    if (!partTrimmed)
+      continue;
+    const colonIndex = partTrimmed.indexOf(":");
+    if (colonIndex === -1) {
+      criteria.push({ field: partTrimmed, direction: "asc" });
+    } else {
+      const field = partTrimmed.slice(0, colonIndex).trim();
+      const direction = partTrimmed.slice(colonIndex + 1).trim().toLowerCase();
+      if (direction !== "asc" && direction !== "desc") {
+        return new Err(new ValidationError({
+          message: `Invalid sort direction: ${direction}. Must be 'asc' or 'desc'.`
+        }));
+      }
+      criteria.push({ field, direction });
+    }
+  }
+  return new Ok(criteria);
+}
+
+export { expandFileArg, parseGlob, parseKeyValue, parseRange, parseFilter, parseSortSpec };

package/dist/shared/@outfitter/cli-2dfxs239.js

@@ -0,0 +1,98 @@
+// @bun
+// packages/cli/src/internal/hint-error-recovery.ts
+import {
+  retryableMap
+} from "@outfitter/contracts";
+var CATEGORY_RECOVERY_MAP = {
+  validation: (cliName) => [
+    {
+      description: "Check input parameters and try again",
+      command: cliName ? `${cliName} --help` : "--help",
+      params: { retryable: retryableMap.validation }
+    }
+  ],
+  not_found: (cliName) => [
+    {
+      description: "Verify the resource identifier exists",
+      command: cliName ? `${cliName} list` : "list",
+      params: { retryable: retryableMap.not_found }
+    }
+  ],
+  conflict: (cliName, commandName) => {
+    const cmd = commandName || "<previous-command>";
+    return [
+      {
+        description: "Resolve the conflict and retry",
+        command: cliName ? `${cliName} ${cmd} --force` : `${cmd} --force`,
+        params: { retryable: retryableMap.conflict }
+      }
+    ];
+  },
+  permission: (cliName) => [
+    {
+      description: "Check your permissions or request access",
+      command: cliName ? `${cliName} auth status` : "auth status",
+      params: { retryable: retryableMap.permission }
+    }
+  ],
+  timeout: (cliName, commandName) => {
+    const cmd = commandName || "<previous-command>";
+    return [
+      {
+        description: "Retry the operation \u2014 transient timeout may resolve",
+        command: cliName ? `${cliName} ${cmd}` : cmd,
+        params: { retryable: retryableMap.timeout }
+      }
+    ];
+  },
+  rate_limit: (cliName, commandName) => {
+    const cmd = commandName || "<previous-command>";
+    return [
+      {
+        description: "Wait and retry \u2014 rate limit will reset",
+        command: cliName ? `${cliName} ${cmd}` : cmd,
+        params: { retryable: retryableMap.rate_limit }
+      }
+    ];
+  },
+  network: (cliName, commandName) => {
+    const cmd = commandName || "<previous-command>";
+    return [
+      {
+        description: "Retry the operation \u2014 network issue may be transient",
+        command: cliName ? `${cliName} ${cmd}` : cmd,
+        params: { retryable: retryableMap.network }
+      }
+    ];
+  },
+  internal: (cliName) => [
+    {
+      description: "Report this error \u2014 unexpected internal failure",
+      command: cliName ? `${cliName} --help` : "--help",
+      params: { retryable: retryableMap.internal }
+    }
+  ],
+  auth: (cliName) => [
+    {
+      description: "Authenticate or refresh your credentials",
+      command: cliName ? `${cliName} auth login` : "auth login",
+      params: { retryable: retryableMap.auth }
+    }
+  ],
+  cancelled: (cliName, commandName) => {
+    const cmd = commandName || "<previous-command>";
+    return [
+      {
+        description: "Operation was cancelled \u2014 re-run to try again",
+        command: cliName ? `${cliName} ${cmd}` : cmd,
+        params: { retryable: retryableMap.cancelled }
+      }
+    ];
+  }
+};
+function errorRecoveryHints(category, cliName, commandName) {
+  const factory = CATEGORY_RECOVERY_MAP[category];
+  return factory(cliName, commandName);
+}
+
+export { errorRecoveryHints };

package/dist/shared/@outfitter/cli-30mt7c5w.d.ts

@@ -0,0 +1,112 @@
+import { OutputMode } from "./cli-x6qr7bnd.js";
+import { CLIHint, ErrorCategory, OutfitterError } from "@outfitter/contracts";
+import { Result } from "better-result";
+/**
+* Structured success envelope wrapping a command result.
+*
+* The `hints` field is absent (not an empty array) when there are no hints.
+* This avoids Clippy-style noise in terminal output.
+*/
+interface SuccessEnvelope<T = unknown> {
+	readonly ok: true;
+	readonly command: string;
+	readonly result: T;
+	readonly hints?: CLIHint[];
+}
+/**
+* Structured error envelope wrapping a command failure.
+*
+* The `hints` field is absent (not an empty array) when there are no hints.
+* The `retryable` field indicates whether the error is transient and safe to retry.
+* The `retry_after` field is only present for rate_limit errors with a known delay.
+*/
+interface ErrorEnvelope {
+	readonly ok: false;
+	readonly command: string;
+	readonly error: {
+		readonly category: ErrorCategory;
+		readonly message: string;
+		readonly retryable: boolean;
+		readonly retry_after?: number;
+	};
+	readonly hints?: CLIHint[];
+}
+/**
+* Discriminated union of success and error envelopes.
+*
+* Use `envelope.ok` to narrow:
+* ```typescript
+* if (envelope.ok) {
+*   // SuccessEnvelope — envelope.result is available
+* } else {
+*   // ErrorEnvelope — envelope.error is available
+* }
+* ```
+*/
+type CommandEnvelope<T = unknown> = SuccessEnvelope<T> | ErrorEnvelope;
+/**
+* Options for the runHandler lifecycle bridge.
+*
+* @typeParam TInput - Type of validated input
+* @typeParam TOutput - Type of handler result
+* @typeParam TContext - Type of context object
+*/
+interface RunHandlerOptions<
+	TInput = unknown,
+	TOutput = unknown,
+	TContext = unknown
+> {
+	/** Command name for the envelope */
+	readonly command: string;
+	/**
+	* Handler function returning a Result.
+	*
+	* When a context factory is provided, receives (input, context).
+	* When no context factory, receives (input, undefined).
+	*/
+	readonly handler: (input: TInput, context: TContext) => Promise<Result<TOutput, OutfitterError>>;
+	/** Validated input to pass to context factory and handler */
+	readonly input?: TInput;
+	/** Output format (json, jsonl, human) */
+	readonly format?: OutputMode;
+	/**
+	* Async factory for constructing handler context.
+	* Called before the handler with the validated input.
+	*/
+	readonly contextFactory?: (input: TInput) => Promise<TContext> | TContext;
+	/** Success hint function — called with (result, input) */
+	readonly hints?: (result: unknown, input: TInput) => CLIHint[];
+	/** Error hint function — called with (error, input) */
+	readonly onError?: (error: unknown, input: TInput) => CLIHint[];
+	/**
+	* Enable NDJSON streaming mode.
+	*
+	* When `true`, the handler receives a `progress` callback via context
+	* and the CLI writes progress events as NDJSON lines to stdout.
+	* The final line is the standard command envelope (success or error).
+	* The CLI owns the initial `start` event, so handlers should emit only
+	* `step` and `progress` events through `ctx.progress`.
+	*
+	* `--stream` is orthogonal to output mode — it controls delivery, not serialization.
+	*/
+	readonly stream?: boolean;
+	/**
+	* Indicate that this is a dry-run invocation of a destructive command.
+	*
+	* When `true`, the success envelope includes a CLIHint with the command
+	* to execute without `--dry-run` (preview-then-commit pattern).
+	*
+	* The handler is responsible for checking the dry-run flag and performing
+	* preview-only logic. This option only controls hint generation in the envelope.
+	*/
+	readonly dryRun?: boolean;
+	/**
+	* Parsed argv to use for dry-run hint generation.
+	*
+	* Defaults to `process.argv.slice(2)`. Pass explicit argv when using
+	* `cli.parse(customArgv)` to ensure the dry-run hint reconstructs the
+	* correct command.
+	*/
+	readonly argv?: readonly string[];
+}
+export { SuccessEnvelope, ErrorEnvelope, CommandEnvelope, RunHandlerOptions };

package/dist/shared/@outfitter/cli-3jta1h1h.js

@@ -0,0 +1,134 @@
+// @bun
+// packages/cli/src/schema-input.ts
+import { ValidationError } from "@outfitter/contracts";
+import { Option } from "commander";
+function camelToKebab(str) {
+  return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+function unwrapZodField(field) {
+  let current = field;
+  let description = current.description;
+  let defaultValue = undefined;
+  let hasDefault = false;
+  let isOptional = false;
+  while (true) {
+    if (description === undefined) {
+      description = current.description;
+    }
+    const def = current._zod?.def;
+    if (!def?.type)
+      break;
+    if (def.type === "default") {
+      hasDefault = true;
+      defaultValue = def.defaultValue;
+      current = def.innerType;
+      continue;
+    }
+    if (def.type === "optional" || def.type === "nullable") {
+      isOptional = true;
+      current = def.innerType;
+      continue;
+    }
+    return {
+      baseType: def.type,
+      description,
+      hasDefault,
+      defaultValue,
+      isOptional,
+      enumValues: def.type === "enum" ? current.options : undefined
+    };
+  }
+  return {
+    baseType: "unknown",
+    description,
+    hasDefault,
+    defaultValue,
+    isOptional,
+    enumValues: undefined
+  };
+}
+function deriveFlags(schema, explicitLongFlags) {
+  const flags = [];
+  for (const [fieldName, field] of Object.entries(schema.shape)) {
+    const kebabName = camelToKebab(fieldName);
+    const longFlag = `--${kebabName}`;
+    if (explicitLongFlags.has(longFlag))
+      continue;
+    const info = unwrapZodField(field);
+    const desc = info.description ?? fieldName;
+    let flagString;
+    let isBoolean = false;
+    const isRequired = !info.hasDefault && !info.isOptional;
+    switch (info.baseType) {
+      case "boolean":
+        flagString = longFlag;
+        isBoolean = true;
+        break;
+      case "number":
+        flagString = `${longFlag} <n>`;
+        break;
+      case "enum":
+        flagString = `${longFlag} <value>`;
+        break;
+      default:
+        flagString = `${longFlag} <value>`;
+        break;
+    }
+    flags.push({
+      name: fieldName,
+      longFlag,
+      flagString,
+      description: desc,
+      defaultValue: info.hasDefault ? info.defaultValue : undefined,
+      isBoolean,
+      isRequired
+    });
+  }
+  return flags;
+}
+function createCommanderOption(flag, schema) {
+  const option = new Option(flag.flagString, flag.description);
+  if (flag.defaultValue !== undefined) {
+    option.default(flag.defaultValue);
+  }
+  const fieldInfo = unwrapZodField(schema.shape[flag.name]);
+  if (fieldInfo.baseType === "enum" && fieldInfo.enumValues) {
+    option.choices(fieldInfo.enumValues);
+  }
+  if (fieldInfo.baseType === "number") {
+    option.argParser(Number);
+  }
+  if (flag.isRequired) {
+    option.makeOptionMandatory(true);
+  }
+  return option;
+}
+function validateInput(flags, schema) {
+  const input = {};
+  for (const fieldName of Object.keys(schema.shape)) {
+    if (fieldName in flags && flags[fieldName] !== undefined) {
+      input[fieldName] = flags[fieldName];
+    }
+  }
+  const result = schema.safeParse(input);
+  if (result.success) {
+    return result.data;
+  }
+  const rawError = result.error;
+  const rawIssues = rawError?.issues ?? [];
+  const issues = rawIssues.map((issue) => ({
+    field: (issue.path ?? []).join("."),
+    expected: issue.expected,
+    message: issue.message ?? "Unknown validation error",
+    code: issue.code
+  }));
+  const fieldNames = issues.map((i) => i.field).filter(Boolean);
+  const summary = fieldNames.length > 0 ? `Invalid input: ${fieldNames.join(", ")}` : "Invalid input";
+  const detail = issues.map((i) => i.field ? `  ${i.field}: ${i.message}` : `  ${i.message}`).join(`
+`);
+  const message = detail ? `${summary}
+${detail}` : summary;
+  throw ValidationError.fromMessage(message, { issues });
+}
+
+export { camelToKebab, unwrapZodField, deriveFlags, createCommanderOption, validateInput };

package/dist/shared/@outfitter/cli-4h85mpth.js

@@ -0,0 +1,76 @@
+// @bun
+import {
+  applyOutputTruncation,
+  cliStringify,
+  detectMode,
+  formatErrorHuman,
+  formatHuman,
+  getExitCode,
+  serializeErrorToJson,
+  writeWithBackpressure
+} from "./cli-dg0cz7rw.js";
+
+// packages/cli/src/output.ts
+import { getEnvironment, getEnvironmentDefaults } from "@outfitter/config";
+async function output(data, format, options) {
+  const mode = detectMode(format);
+  const stream = options?.stream ?? process.stdout;
+  const renderedData = applyOutputTruncation(data, options?.truncation);
+  let outputText;
+  switch (mode) {
+    case "json": {
+      const jsonData = renderedData === undefined ? null : renderedData;
+      outputText = cliStringify(jsonData, options?.pretty);
+      break;
+    }
+    case "jsonl": {
+      if (Array.isArray(renderedData)) {
+        if (renderedData.length === 0) {
+          outputText = "";
+        } else {
+          outputText = renderedData.map((item) => cliStringify(item)).join(`
+`);
+        }
+      } else {
+        outputText = cliStringify(renderedData);
+      }
+      break;
+    }
+    default: {
+      outputText = formatHuman(renderedData);
+      break;
+    }
+  }
+  if (outputText) {
+    await writeWithBackpressure(stream, `${outputText}
+`);
+  }
+}
+function exitWithError(error, format) {
+  const exitCode = getExitCode(error);
+  const mode = detectMode(format);
+  const isJsonMode = mode === "json" || mode === "jsonl";
+  if (isJsonMode) {
+    process.stderr.write(`${serializeErrorToJson(error)}
+`);
+  } else {
+    process.stderr.write(`${formatErrorHuman(error)}
+`);
+  }
+  process.exit(exitCode);
+}
+function resolveVerbose(verbose) {
+  const envVerbose = process.env["OUTFITTER_VERBOSE"];
+  if (envVerbose === "1")
+    return true;
+  if (envVerbose === "0")
+    return false;
+  if (verbose !== undefined) {
+    return verbose;
+  }
+  const env = getEnvironment();
+  const defaults = getEnvironmentDefaults(env);
+  return defaults.verbose;
+}
+
+export { output, exitWithError, resolveVerbose };