@outfitter/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,357 @@
+// @bun
+// packages/cli/src/flags.ts
+function createPreset(config) {
+  const preset = {
+    id: config.id,
+    options: config.options,
+    resolve: config.resolve
+  };
+  preset[PRESET_IDS] = [config.id];
+  return preset;
+}
+var PRESET_IDS = Symbol("presetIds");
+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;
+}
+function verbosePreset() {
+  return createPreset({
+    id: "verbose",
+    options: [
+      {
+        flags: "-v, --verbose",
+        description: "Verbose output",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      verbose: Boolean(flags["verbose"])
+    })
+  });
+}
+function cwdPreset() {
+  return createPreset({
+    id: "cwd",
+    options: [
+      {
+        flags: "--cwd <path>",
+        description: "Working directory"
+      }
+    ],
+    resolve: (flags) => ({
+      cwd: typeof flags["cwd"] === "string" ? flags["cwd"] : process.cwd()
+    })
+  });
+}
+function dryRunPreset() {
+  return createPreset({
+    id: "dryRun",
+    options: [
+      {
+        flags: "--dry-run",
+        description: "Preview changes without applying",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      dryRun: Boolean(flags["dryRun"] ?? flags["dry-run"])
+    })
+  });
+}
+function forcePreset() {
+  return createPreset({
+    id: "force",
+    options: [
+      {
+        flags: "-f, --force",
+        description: "Force operation (skip confirmations)",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      force: Boolean(flags["force"])
+    })
+  });
+}
+function interactionPreset() {
+  return createPreset({
+    id: "interaction",
+    options: [
+      {
+        flags: "--non-interactive",
+        description: "Disable interactive prompts",
+        defaultValue: false
+      },
+      {
+        flags: "--no-input",
+        description: "Disable interactive prompts (alias)"
+      },
+      {
+        flags: "-y, --yes",
+        description: "Auto-confirm prompts",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      const nonInteractive = flags["input"] === false || Boolean(flags["nonInteractive"]) || Boolean(flags["non-interactive"]) || Boolean(flags["noInput"]) || Boolean(flags["no-input"]);
+      return {
+        interactive: !nonInteractive,
+        yes: Boolean(flags["yes"])
+      };
+    }
+  });
+}
+function strictPreset() {
+  return createPreset({
+    id: "strict",
+    options: [
+      {
+        flags: "--strict",
+        description: "Enable strict mode (treat warnings as errors)",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      strict: Boolean(flags["strict"])
+    })
+  });
+}
+var COLOR_MODES = new Set(["auto", "always", "never"]);
+function colorPreset() {
+  return createPreset({
+    id: "color",
+    options: [
+      {
+        flags: "--color [mode]",
+        description: "Color output mode (auto, always, never)",
+        defaultValue: "auto"
+      },
+      {
+        flags: "--no-color",
+        description: "Disable color output"
+      }
+    ],
+    resolve: (flags) => {
+      const raw = flags["color"];
+      if (raw === false)
+        return { color: "never" };
+      if (raw === true)
+        return { color: "always" };
+      if (typeof raw === "string" && COLOR_MODES.has(raw)) {
+        return { color: raw };
+      }
+      return { color: "auto" };
+    }
+  });
+}
+function parseCommaSeparated(value) {
+  if (typeof value !== "string")
+    return;
+  const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+function projectionPreset() {
+  return createPreset({
+    id: "projection",
+    options: [
+      {
+        flags: "--fields <fields>",
+        description: "Comma-separated list of fields to include"
+      },
+      {
+        flags: "--exclude-fields <fields>",
+        description: "Comma-separated list of fields to exclude"
+      },
+      {
+        flags: "--count",
+        description: "Output only the count of results",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => ({
+      fields: parseCommaSeparated(flags["fields"]),
+      excludeFields: parseCommaSeparated(flags["excludeFields"] ?? flags["exclude-fields"]),
+      count: Boolean(flags["count"])
+    })
+  });
+}
+var DURATION_SUFFIXES = {
+  w: 7 * 24 * 60 * 60 * 1000,
+  d: 24 * 60 * 60 * 1000,
+  h: 60 * 60 * 1000,
+  m: 60 * 1000
+};
+function parseDate(value, nowMs = Date.now()) {
+  if (typeof value !== "string" || value === "")
+    return;
+  const durationMatch = value.match(/^(\d+(?:\.\d+)?)(w|d|h|m)$/);
+  if (durationMatch) {
+    const amount = Number(durationMatch[1]);
+    const suffix = durationMatch[2];
+    const multiplier = suffix ? DURATION_SUFFIXES[suffix] : undefined;
+    if (amount > 0 && multiplier !== undefined) {
+      return new Date(nowMs - amount * multiplier);
+    }
+    return;
+  }
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    return;
+  return date;
+}
+function sanitizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return fallback;
+  return Math.floor(parsed);
+}
+function timeWindowPreset(config) {
+  return createPreset({
+    id: "timeWindow",
+    options: [
+      {
+        flags: "--since <date>",
+        description: "Start of time window (ISO date or duration: 7d, 24h, 2w)"
+      },
+      {
+        flags: "--until <date>",
+        description: "End of time window (ISO date or duration: 7d, 24h, 2w)"
+      }
+    ],
+    resolve: (flags) => {
+      const now = Date.now();
+      const since = parseDate(flags["since"], now);
+      const until = parseDate(flags["until"], now);
+      if (since && until && typeof config?.maxRange === "number" && Number.isFinite(config.maxRange) && config.maxRange > 0) {
+        const range = Math.abs(until.getTime() - since.getTime());
+        if (range > config.maxRange) {
+          return {
+            since: undefined,
+            until: undefined
+          };
+        }
+      }
+      return { since, until };
+    }
+  });
+}
+function executionPreset(config) {
+  const defaultTimeout = config?.defaultTimeout;
+  const defaultRetries = config?.defaultRetries ?? 0;
+  const maxRetries = config?.maxRetries ?? 10;
+  return createPreset({
+    id: "execution",
+    options: [
+      {
+        flags: "--timeout <ms>",
+        description: "Timeout in milliseconds"
+      },
+      {
+        flags: "--retries <n>",
+        description: `Number of retries (default: ${defaultRetries}, max: ${maxRetries})`
+      },
+      {
+        flags: "--offline",
+        description: "Operate in offline mode",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      let timeout = defaultTimeout;
+      const rawTimeout = flags["timeout"];
+      if (rawTimeout !== undefined) {
+        const parsed = Number(rawTimeout);
+        if (Number.isFinite(parsed) && parsed > 0) {
+          timeout = Math.floor(parsed);
+        } else {
+          timeout = undefined;
+        }
+      }
+      let retries = defaultRetries;
+      const rawRetries = flags["retries"];
+      if (rawRetries !== undefined) {
+        const parsed = Number(rawRetries);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+          retries = Math.min(Math.floor(parsed), maxRetries);
+        }
+      }
+      return {
+        timeout,
+        retries,
+        offline: Boolean(flags["offline"])
+      };
+    }
+  });
+}
+function paginationPreset(config) {
+  const maxLimit = sanitizePositiveInteger(config?.maxLimit, 100);
+  const defaultLimit = Math.min(sanitizePositiveInteger(config?.defaultLimit, 20), maxLimit);
+  return createPreset({
+    id: "pagination",
+    options: [
+      {
+        flags: "-l, --limit <n>",
+        description: `Maximum number of results (default: ${defaultLimit}, max: ${maxLimit})`
+      },
+      {
+        flags: "--next",
+        description: "Continue from last position",
+        defaultValue: false
+      },
+      {
+        flags: "--reset",
+        description: "Clear saved cursor and start fresh",
+        defaultValue: false
+      }
+    ],
+    resolve: (flags) => {
+      let limit = defaultLimit;
+      const rawLimit = flags["limit"];
+      if (rawLimit !== undefined) {
+        const parsed = Number(rawLimit);
+        if (Number.isFinite(parsed) && parsed > 0) {
+          limit = Math.min(Math.floor(parsed), maxLimit);
+        }
+      }
+      return {
+        limit,
+        next: Boolean(flags["next"]),
+        reset: Boolean(flags["reset"])
+      };
+    }
+  });
+}
+
+export { createPreset, composePresets, verbosePreset, cwdPreset, dryRunPreset, forcePreset, interactionPreset, strictPreset, colorPreset, projectionPreset, timeWindowPreset, executionPreset, paginationPreset };

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

@@ -0,0 +1,319 @@
+// @bun
+// packages/cli/src/schema.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import {
+  diffSurfaceMaps,
+  formatManifestMarkdown,
+  generateManifest,
+  generateSurfaceMap,
+  readSurfaceMap,
+  resolveSnapshotPath,
+  writeSurfaceMap
+} from "@outfitter/schema";
+import { Command } from "commander";
+import { generateManifest as generateManifest2 } from "@outfitter/schema";
+function formatManifestHuman(manifest, programName, actionId) {
+  if (actionId) {
+    return formatActionDetail(manifest, actionId);
+  }
+  return formatSummary(manifest, programName);
+}
+function formatSummary(manifest, programName) {
+  const lines = [];
+  const name = programName ?? "cli";
+  const actionCount = manifest.actions.length;
+  const surfaceCount = manifest.surfaces.length;
+  const surfaceLabel = surfaceCount === 1 ? `${surfaceCount} surface` : `${surfaceCount} surfaces`;
+  lines.push(`${name} \u2014 ${actionCount} actions across ${surfaceLabel}`);
+  lines.push("");
+  const grouped = new Map;
+  const ungrouped = [];
+  for (const action of manifest.actions) {
+    const group = action.cli?.group;
+    if (group) {
+      const existing = grouped.get(group) ?? [];
+      existing.push(action);
+      grouped.set(group, existing);
+    } else {
+      ungrouped.push(action);
+    }
+  }
+  for (const [groupName, groupActions] of grouped.entries()) {
+    lines.push(groupName);
+    for (const action of groupActions) {
+      const commandPart = action.cli?.command ?? action.id;
+      const isBase = !commandPart || commandPart.startsWith("[") || commandPart.startsWith("<");
+      const displayCommand = isBase ? `  ${groupName} ${commandPart ?? ""}`.trimEnd() : `  ${groupName} ${commandPart}`;
+      const desc = action.cli?.description ?? action.description ?? "";
+      lines.push(padCommand(displayCommand, desc));
+    }
+    lines.push("");
+  }
+  for (const action of ungrouped) {
+    const commandPart = action.cli?.command ?? action.id;
+    const desc = action.cli?.description ?? action.description ?? "";
+    lines.push(padCommand(`${commandPart}`, desc));
+  }
+  lines.push("");
+  lines.push("Use --output json for machine-readable format.");
+  lines.push("Use --surface <name> to filter (cli, mcp, api, server).");
+  return lines.join(`
+`);
+}
+function padCommand(command, description) {
+  const padding = Math.max(1, 32 - command.length);
+  return `${command}${" ".repeat(padding)}${description}`;
+}
+function formatActionDetail(manifest, actionId) {
+  const entry = manifest.actions.find((a) => a.id === actionId);
+  if (!entry) {
+    return `Unknown action: ${actionId}`;
+  }
+  const lines = [];
+  const desc = entry.cli?.description ?? entry.description ?? "";
+  lines.push(`${entry.id} \u2014 ${desc}`);
+  lines.push("");
+  if (entry.cli) {
+    const group = entry.cli.group;
+    const commandPart = entry.cli.command ?? entry.id;
+    const fullCommand = group ? `${group} ${commandPart}` : commandPart;
+    lines.push(`  Command:  ${fullCommand}`);
+  }
+  lines.push(`  Surfaces: ${entry.surfaces.join(", ")}`);
+  if (entry.cli?.group) {
+    lines.push(`  Group:    ${entry.cli.group}`);
+  }
+  if (entry.cli?.aliases && entry.cli.aliases.length > 0) {
+    lines.push(`  Aliases:  ${entry.cli.aliases.join(", ")}`);
+  }
+  if (entry.cli?.options && entry.cli.options.length > 0) {
+    lines.push("");
+    lines.push("  Options:");
+    for (const opt of entry.cli.options) {
+      const defaultStr = opt.defaultValue !== undefined ? ` [${String(opt.defaultValue)}]` : "";
+      lines.push(padCommand(`    ${opt.flags}`, `${opt.description}${defaultStr}`));
+    }
+  }
+  if (entry.mcp) {
+    lines.push("");
+    lines.push("  MCP:");
+    if (entry.mcp.tool) {
+      lines.push(`    Tool: ${entry.mcp.tool}`);
+    }
+    if (entry.mcp.description) {
+      lines.push(`    Description: ${entry.mcp.description}`);
+    }
+  }
+  return lines.join(`
+`);
+}
+function handleShow(source, programName, parentCmd, actionArg, cmdOptions) {
+  const manifestOptions = {};
+  if (cmdOptions.surface) {
+    manifestOptions.surface = cmdOptions.surface;
+  }
+  const manifest = generateManifest(source, manifestOptions);
+  if (cmdOptions.output === "json") {
+    const indent = cmdOptions.pretty ? 2 : undefined;
+    if (actionArg) {
+      const entry = manifest.actions.find((a) => a.id === actionArg);
+      if (!entry) {
+        process.stderr.write(`Unknown action: ${actionArg}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      process.stdout.write(`${JSON.stringify(entry, null, indent)}
+`);
+    } else {
+      process.stdout.write(`${JSON.stringify(manifest, null, indent)}
+`);
+    }
+    return;
+  }
+  const resolvedName = programName ?? parentCmd.parent?.name() ?? undefined;
+  const output = formatManifestHuman(manifest, resolvedName, actionArg);
+  process.stdout.write(`${output}
+`);
+}
+function createSchemaCommand(source, options) {
+  const cmd = new Command("schema").description("Show CLI schema for machine or human consumption").argument("[action]", "Show detail for a specific action").option("--output <mode>", "Output mode (human, json)", "human").option("--surface <name>", "Filter by surface (cli, mcp, api, server)").option("--pretty", "Pretty-print JSON output").action((actionArg, cmdOptions) => {
+    handleShow(source, options?.programName, cmd, actionArg, cmdOptions);
+  });
+  const showCmd = new Command("show").description("Show schema for all actions or a specific action").argument("[action]", "Show detail for a specific action").option("--output <mode>", "Output mode (human, json)", "human").option("--surface <name>", "Filter by surface (cli, mcp, api, server)").option("--pretty", "Pretty-print JSON output").action((actionArg, cmdOptions) => {
+    handleShow(source, options?.programName, cmd, actionArg, cmdOptions);
+  });
+  cmd.addCommand(showCmd);
+  if (options?.surface) {
+    const surfaceOpts = options.surface;
+    const cwd = surfaceOpts.cwd ?? process.cwd();
+    const outputDir = surfaceOpts.outputDir ?? ".outfitter";
+    const generateCmd = new Command("generate").description("Generate surface map and write to disk").option("--dry-run", "Print surface map without writing to disk").option("--snapshot <version>", "Write snapshot to .outfitter/snapshots/<version>.json").action(async (genOptions) => {
+      const surfaceMap = generateSurfaceMap(source, {
+        generator: "build"
+      });
+      if (genOptions.dryRun) {
+        process.stdout.write(`${JSON.stringify(surfaceMap, null, 2)}
+`);
+        return;
+      }
+      if (genOptions.snapshot) {
+        const snapshotPath = resolveSnapshotPath(cwd, outputDir, genOptions.snapshot);
+        await writeSurfaceMap(surfaceMap, snapshotPath);
+        process.stdout.write(`Snapshot written to ${snapshotPath}
+`);
+        return;
+      }
+      const outputPath = join(cwd, outputDir, "surface.json");
+      await writeSurfaceMap(surfaceMap, outputPath);
+      process.stdout.write(`Surface map written to ${outputPath}
+`);
+    });
+    cmd.addCommand(generateCmd);
+    const diffCmd = new Command("diff").description("Compare runtime schema against committed surface map").option("--output <mode>", "Output mode (human, json)", "human").option("--against <version>", "Compare runtime against a named snapshot").option("--from <version>", "Base snapshot for snapshot-to-snapshot diff").option("--to <version>", "Target snapshot for snapshot-to-snapshot diff").action(async (diffOptions) => {
+      let left;
+      let right;
+      if (diffOptions.from && !diffOptions.to || !diffOptions.from && diffOptions.to) {
+        process.stderr.write(`Both --from and --to are required for snapshot-to-snapshot diff.
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (diffOptions.from && diffOptions.to) {
+        const fromPath = resolveSnapshotPath(cwd, outputDir, diffOptions.from);
+        const toPath = resolveSnapshotPath(cwd, outputDir, diffOptions.to);
+        try {
+          left = await readSurfaceMap(fromPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${fromPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${fromPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          right = await readSurfaceMap(toPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${toPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${toPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+      } else if (diffOptions.against) {
+        const snapshotPath = resolveSnapshotPath(cwd, outputDir, diffOptions.against);
+        try {
+          left = await readSurfaceMap(snapshotPath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No snapshot at ${snapshotPath}
+`);
+          } else {
+            process.stderr.write(`Failed to read snapshot at ${snapshotPath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        right = generateSurfaceMap(source, { generator: "runtime" });
+      } else {
+        const surfacePath = join(cwd, outputDir, "surface.json");
+        try {
+          left = await readSurfaceMap(surfacePath);
+        } catch (err) {
+          if (err.code === "ENOENT") {
+            process.stderr.write(`No committed surface map at ${surfacePath}
+`);
+            process.stderr.write(`Run 'schema generate' first.
+`);
+          } else {
+            process.stderr.write(`Failed to read surface map at ${surfacePath}: ${err instanceof Error ? err.message : String(err)}
+`);
+          }
+          process.exitCode = 1;
+          return;
+        }
+        right = generateSurfaceMap(source, { generator: "runtime" });
+      }
+      const result = diffSurfaceMaps(left, right);
+      if (diffOptions.output === "json") {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+      } else {
+        if (!result.hasChanges) {
+          process.stdout.write(`No schema drift detected.
+`);
+          return;
+        }
+        const lines = [];
+        lines.push(`Schema drift detected:
+`);
+        if (result.added.length > 0) {
+          lines.push("  Added:");
+          for (const entry of result.added) {
+            lines.push(`    + ${entry.id}`);
+          }
+        }
+        if (result.removed.length > 0) {
+          lines.push("  Removed:");
+          for (const entry of result.removed) {
+            lines.push(`    - ${entry.id}`);
+          }
+        }
+        if (result.modified.length > 0) {
+          lines.push("  Modified:");
+          for (const entry of result.modified) {
+            lines.push(`    ~ ${entry.id} (${entry.changes.join(", ")})`);
+          }
+        }
+        if (result.metadataChanges.length > 0) {
+          lines.push("  Metadata:");
+          for (const field of result.metadataChanges) {
+            lines.push(`    ~ ${field}`);
+          }
+        }
+        process.stdout.write(`${lines.join(`
+`)}
+`);
+      }
+      if (result.hasChanges) {
+        process.exitCode = 1;
+      }
+    });
+    cmd.addCommand(diffCmd);
+    const docsCmd = new Command("docs").description("Generate markdown reference documentation").option("--surface <name>", "Which surface to document (cli, mcp)", "mcp").option("--output-dir <dir>", "Directory to write the reference doc", "docs/reference").option("--dry-run", "Print to stdout instead of writing to disk").action(async (docsOptions) => {
+      const surface = docsOptions.surface ?? "mcp";
+      if (surface !== "mcp" && surface !== "cli") {
+        process.stderr.write(`Unsupported surface for docs: "${surface}". Use "mcp" or "cli".
+`);
+        process.exitCode = 1;
+        return;
+      }
+      const manifest = generateManifest(source, { surface });
+      const markdown = formatManifestMarkdown(manifest, { surface });
+      if (docsOptions.dryRun) {
+        process.stdout.write(markdown);
+        return;
+      }
+      const outDir = docsOptions.outputDir ?? "docs/reference";
+      const outputPath = join(cwd, outDir, `${surface.toUpperCase()}_REFERENCE.md`);
+      await mkdir(dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, markdown, "utf-8");
+      process.stdout.write(`Reference written to ${outputPath}
+`);
+    });
+    cmd.addCommand(docsCmd);
+  }
+  return cmd;
+}
+
+export { formatManifestHuman, createSchemaCommand, generateManifest2 as generateManifest };

package/dist/shared/@outfitter/{cli-f79bwzsp.d.ts → cli-k0yvzn6d.d.ts}

@@ -1,4 +1,4 @@
-import { OutputOptions } from "./cli-02kyvj7h";
+import { OutputOptions } from "./cli-md9347gn";
 /**
 * Output data to the console with automatic mode selection.
 *