@triflare/fx 1.0.3 → 2.0.0

package/src/cli/define-command.js

@@ -0,0 +1,140 @@
+/**
+ * Shared command registration and result handling.
+ */
+
+import path from "node:path";
+import { Command } from "commander";
+import { createPrompts } from "./prompts.js";
+import { createReporter } from "./reporter.js";
+
+function resolveColor(options) {
+  if (options.color === false || options.color === "never") return "never";
+  if (options.color === "always") return "always";
+  return "auto";
+}
+
+/** Build the per-command context from global and command options. */
+export function createContext({ command, product }) {
+  const options = command.optsWithGlobals();
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const json = Boolean(options.json);
+  const noInput = options.input === false || json;
+  const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const reporter = createReporter({
+    product,
+    json,
+    quiet: Boolean(options.quiet),
+    verbose: Boolean(options.verbose),
+    color: resolveColor(options),
+  });
+  const prompts = createPrompts({
+    reporter,
+    product,
+    tty,
+    noInput,
+    json,
+  });
+
+  return {
+    command,
+    product,
+    options,
+    args: command.processedArgs,
+    cwd,
+    json,
+    yes: Boolean(options.yes),
+    reporter,
+    prompts,
+  };
+}
+
+/** Mark a command result with an explicit exit status. */
+export function outcome({ data = null, exitCode = 0, error = null } = {}) {
+  return {
+    __outcome: true,
+    ok: exitCode === 0 && !error,
+    exitCode,
+    data,
+    error,
+  };
+}
+
+function normalizeOutcome(result) {
+  if (result && result.__outcome) return result;
+  return { ok: true, exitCode: 0, data: result ?? null, error: null };
+}
+
+function configure(command, spec) {
+  command.description(spec.summary ?? spec.description ?? "");
+  if (spec.aliases?.length) command.aliases(spec.aliases);
+  if (spec.group) command.helpGroup(spec.group);
+  for (const argument of spec.arguments ?? []) command.argument(argument);
+  for (const option of spec.options ?? []) {
+    if (option.defaultValue === undefined)
+      command.option(option.flags, option.description);
+    else command.option(option.flags, option.description, option.defaultValue);
+  }
+  const details = [];
+  if (spec.description && spec.description !== spec.summary)
+    details.push(spec.description);
+  if (spec.examples?.length)
+    details.push(
+      `Examples:\n${spec.examples.map((example) => `  ${example}`).join("\n")}`,
+    );
+  if (details.length)
+    command.addHelpText("after", `\n${details.join("\n\n")}\n`);
+  return command;
+}
+
+/** Full command path, such as "vendor list", for diagnostics and JSON. */
+function commandPath(command) {
+  const parts = [];
+  for (let current = command; current?.parent; current = current.parent)
+    parts.unshift(current.name());
+  return parts.join(" ");
+}
+
+/**
+ * Register one command (or subcommand) with shared error, JSON, and output
+ * handling.
+ *
+ * @param {Command} parent
+ * @param {object} spec
+ * @param {{state: {exitCode: number, command?: string}, product: object}} options
+ */
+export function defineCommand(parent, spec, { state, product }) {
+  const command = configure(new Command(spec.name), spec);
+  command.copyInheritedSettings(parent);
+
+  command.action(async function action() {
+    const command = this;
+    const name = commandPath(command);
+    const context = createContext({ command, product });
+    state.command = name;
+    try {
+      const result = await spec.run(context);
+      const normalized = normalizeOutcome(result);
+      if (context.options.json && !spec.jsonEvents) {
+        const payload = {
+          schemaVersion: 1,
+          command: name,
+          ok: normalized.ok,
+          warnings: context.reporter.warnings,
+        };
+        if (normalized.error) payload.error = normalized.error;
+        else payload.data = normalized.data;
+        context.reporter.document(payload);
+      }
+      state.exitCode = normalized.exitCode;
+    } catch (error) {
+      if (error && typeof error === "object") {
+        error.command ??= name;
+        error.warnings ??= context.reporter.warnings;
+      }
+      throw error;
+    }
+  });
+
+  parent.addCommand(command, { hidden: Boolean(spec.hidden) });
+  return command;
+}

package/src/cli/errors.js

@@ -0,0 +1,111 @@
+/**
+ * CLI-specific errors and exit-code mapping.
+ *
+ * Command handlers throw these instead of writing to a stream and calling
+ * `process.exit`, which keeps the CLI testable and lets `run()` decide between
+ * human and JSON diagnostics.
+ */
+
+import { FxError } from "../errors.js";
+
+/** Exit codes shared by every command. */
+export const EXIT = {
+  OK: 0,
+  FAILURE: 1,
+  USAGE: 2,
+  INTERRUPTED: 130,
+};
+
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {{
+   *   code?: string,
+   *   exitCode?: number,
+   *   hint?: string,
+   *   details?: unknown,
+   *   silent?: boolean,
+   *   cause?: unknown,
+   * }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = "CliError";
+    this.code = options.code ?? "CLI_ERROR";
+    this.exitCode = options.exitCode ?? EXIT.FAILURE;
+    this.hint = options.hint;
+    this.details = options.details;
+    this.silent = Boolean(options.silent);
+  }
+}
+
+export class UsageError extends CliError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code ?? "USAGE_ERROR",
+      exitCode: EXIT.USAGE,
+    });
+    this.name = "UsageError";
+  }
+}
+
+/** Map a thrown value to the CLI's stable JSON error shape. */
+export function errorToJson(error) {
+  if (error instanceof CliError) {
+    const result = {
+      code: error.code,
+      message: error.message,
+    };
+    if (error.hint) result.hint = error.hint;
+    if (error.details !== undefined) result.details = error.details;
+    return result;
+  }
+
+  if (error instanceof FxError) {
+    const result = {
+      code:
+        error.name === "LexError"
+          ? "LEX_ERROR"
+          : error.name === "ParseError"
+            ? "PARSE_ERROR"
+            : error.name === "CompileError"
+              ? "COMPILE_ERROR"
+              : "FX_ERROR",
+      message: error.message,
+    };
+    if (error.file != null) result.file = error.file;
+    if (error.line != null) result.line = error.line;
+    if (error.column != null) result.column = error.column;
+    return result;
+  }
+
+  return {
+    code: "COMMAND_ERROR",
+    message:
+      error instanceof Error
+        ? error.message
+        : typeof error === "string"
+          ? error
+          : String(error),
+  };
+}
+
+/** Human-readable error body, including a code frame when available. */
+export function formatError(error, { verbose = false } = {}) {
+  if (error instanceof FxError) return error.format();
+  if (error instanceof CliError) {
+    let text = error.message;
+    if (Array.isArray(error.details?.problems) && error.details.problems.length)
+      text += `\n${error.details.problems.map((line) => `  ${line}`).join("\n")}`;
+    return text;
+  }
+  if (verbose && error instanceof Error && error.stack) return error.stack;
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Exit code for an error that escaped a command handler. */
+export function exitCodeFor(error) {
+  if (error instanceof CliError) return error.exitCode;
+  return EXIT.FAILURE;
+}

package/src/cli/format.js

@@ -0,0 +1,31 @@
+/** Small formatting helpers shared by CLI commands. */
+
+/** Render a byte count using binary units. */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB"];
+  let value = bytes / 1024;
+  let unit = units[0];
+  for (let i = 1; value >= 1024 && i < units.length; i += 1) {
+    value /= 1024;
+    unit = units[i];
+  }
+  return `${value.toFixed(value >= 10 ? 1 : 2)} ${unit}`;
+}
+
+/** Render a duration in milliseconds. */
+export function formatDuration(milliseconds) {
+  if (milliseconds < 1000) return `${Math.round(milliseconds)}ms`;
+  return `${(milliseconds / 1000).toFixed(2)}s`;
+}
+
+/** Pluralize a simple English noun. */
+export function plural(count, singular, pluralForm = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+/** Shorten long text for inline diagnostics. */
+export function truncate(text, max) {
+  const value = String(text);
+  return value.length > max ? `${value.slice(0, max)}…` : value;
+}

package/src/cli/prompts.js

@@ -0,0 +1,183 @@
+/**
+ * Interactive prompt layer.
+ *
+ * `@clack/prompts` provides the widgets; this wrapper keeps Fx styling,
+ * non-interactive fallbacks, cancellation, and testability in one place.
+ */
+
+import {
+  cancel,
+  confirm as clackConfirm,
+  intro as clackIntro,
+  isCancel,
+  note as clackNote,
+  outro as clackOutro,
+  select as clackSelect,
+  spinner as clackSpinner,
+  text as clackText,
+  updateSettings,
+} from "@clack/prompts";
+import { CliError, UsageError, EXIT } from "./errors.js";
+
+updateSettings({
+  messages: {
+    cancel: "Cancelled",
+    error: "Something went wrong",
+  },
+});
+
+const CI_VARS = ["CI", "GITHUB_ACTIONS", "TRAVIS", "JENKINS_URL", "CIRCLECI"];
+
+function cancelled() {
+  return new CliError("Cancelled", {
+    code: "CANCELLED",
+    exitCode: EXIT.INTERRUPTED,
+    silent: true,
+  });
+}
+
+function unwrap(value) {
+  if (isCancel(value)) throw cancelled();
+  return value;
+}
+
+/**
+ * @param {{
+ *   reporter: ReturnType<import("./reporter.js").createReporter>,
+ *   product: object,
+ *   tty?: boolean,
+ *   noInput?: boolean,
+ *   json?: boolean,
+ *   input?: NodeJS.ReadableStream,
+ *   output?: NodeJS.WritableStream,
+ * }} options
+ */
+export function createPrompts({
+  reporter,
+  product,
+  tty = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+  noInput = false,
+  json = false,
+  input = process.stdin,
+  output = process.stdout,
+} = {}) {
+  const enabled =
+    tty && !noInput && !json && !CI_VARS.some((name) => process.env[name]);
+  const common = { input, output };
+
+  const requireFallback = (value, feature) => {
+    if (value !== undefined) return value;
+    throw new UsageError(
+      `${feature} requires an interactive terminal, --yes, or an explicit value`,
+    );
+  };
+
+  const message = (text) => reporter.accent(String(text));
+
+  return {
+    enabled,
+
+    intro(text) {
+      if (!enabled) return;
+      clackIntro(
+        reporter.brand(`${product?.name ?? "Fx"} ${product?.version ?? ""}`) +
+          (text ? `\n${message(text)}` : ""),
+        common,
+      );
+    },
+
+    outro(text) {
+      if (!enabled) return;
+      clackOutro(message(text), common);
+    },
+
+    note(text, title) {
+      if (!enabled) return;
+      clackNote(message(text), title ? message(title) : undefined, common);
+    },
+
+    async text({ message: prompt, placeholder, defaultValue, validate }) {
+      if (!enabled) return requireFallback(defaultValue, prompt);
+      return unwrap(
+        await clackText(
+          {
+            ...common,
+            message: message(prompt),
+            placeholder,
+            defaultValue,
+            validate,
+          },
+          common,
+        ),
+      );
+    },
+
+    async select({ message: prompt, options, initialValue }) {
+      if (!enabled) return requireFallback(initialValue, prompt);
+      return unwrap(
+        await clackSelect(
+          {
+            ...common,
+            message: message(prompt),
+            options,
+            initialValue,
+          },
+          common,
+        ),
+      );
+    },
+
+    async confirm({ message: prompt, initialValue = true }) {
+      if (!enabled) return initialValue;
+      return unwrap(
+        await clackConfirm(
+          {
+            ...common,
+            message: message(prompt),
+            initialValue,
+          },
+          common,
+        ),
+      );
+    },
+
+    async confirmDestructive({ message: prompt, yes = false }) {
+      if (yes) return true;
+      if (!enabled)
+        throw new UsageError(
+          `${prompt} is destructive; pass --yes to confirm in non-interactive mode`,
+        );
+      return unwrap(
+        await clackConfirm(
+          {
+            ...common,
+            message: message(prompt),
+            initialValue: false,
+          },
+          common,
+        ),
+      );
+    },
+
+    cancel(text = "Cancelled") {
+      if (!enabled) return;
+      cancel(message(text), common);
+    },
+
+    spinner() {
+      if (!enabled) {
+        return {
+          start() {},
+          stop() {},
+          message() {},
+        };
+      }
+      const spin = clackSpinner(common);
+      return {
+        start: (text) => spin.start(message(text)),
+        stop: (text) => spin.stop(text ? message(text) : undefined),
+        message: (text) => spin.message(message(text)),
+      };
+    },
+  };
+}

package/src/cli/reporter.js

@@ -0,0 +1,194 @@
+/**
+ * Human and JSON output for the CLI.
+ *
+ * Commands call semantic methods (`success`, `detail`, `warn`, ...) and never
+ * write to stdout/stderr directly. In JSON mode human output is suppressed and
+ * warnings are collected for the command envelope.
+ */
+
+import { styleText } from "node:util";
+import { brandText } from "../brand.js";
+import { createTheme } from "./theme.js";
+
+const STATUS = {
+  success: { symbol: "success", tone: "success" },
+  error: { symbol: "error", tone: "danger" },
+  warn: { symbol: "progress", tone: "warning" },
+};
+
+function canColor(stream) {
+  return styleText("red", "x", { stream }).includes("\x1b");
+}
+
+export function createReporter({
+  product,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  json = false,
+  quiet = false,
+  verbose = false,
+  color = "auto",
+} = {}) {
+  const warnings = [];
+  const errors = [];
+  const themes = new Map();
+
+  const themeFor = (stream) => {
+    if (!themes.has(stream))
+      themes.set(stream, createTheme({ product, color, stream }));
+    return themes.get(stream);
+  };
+
+  const colorEnabled = (stream) => {
+    if (color === "never") return false;
+    if (color === "always") return true;
+    return canColor(stream);
+  };
+
+  const paint = (text, tone, stream = stdout) => {
+    if (!tone || !colorEnabled(stream)) return text;
+    const options = { stream };
+    if (color === "always") options.validateStream = false;
+    return styleText(tone, text, options);
+  };
+
+  const mark = (name) => product?.symbols?.[name] ?? "";
+
+  const status = (type, message) => {
+    const { symbol, tone } = STATUS[type];
+    const glyph = mark(symbol);
+    const stream = type === "success" ? stdout : stderr;
+    const theme = themeFor(stream);
+    const text = String(message);
+    const output = text
+      .split("\n")
+      .map((line, index) => {
+        const lead =
+          index === 0
+            ? glyph
+              ? `${theme.tone(tone, glyph)} `
+              : ""
+            : glyph
+              ? "  "
+              : "";
+        const body =
+          type === "success" ? theme.bold(line) : theme.tone(tone, line);
+        return `${lead}${body}`;
+      })
+      .join("\n");
+    stream.write(`${output}\n`);
+  };
+
+  const human = !json && !quiet;
+
+  return {
+    json,
+    quiet,
+    verbose,
+    warnings,
+    errors,
+    paint,
+    brand: (text) => brandText(text, stdout, { force: color === "always" }),
+    accent: (text) => themeFor(stdout).accent(text),
+    muted: (text) => themeFor(stdout).muted(text),
+    bold: (text) => themeFor(stdout).bold(text),
+    tone: (name, text) => themeFor(stdout).tone(name, text),
+
+    success(message) {
+      if (!human) return;
+      status("success", message);
+    },
+
+    info(message) {
+      if (!human) return;
+      stdout.write(`${message}\n`);
+    },
+
+    bullet(message) {
+      if (!human) return;
+      const theme = themeFor(stdout);
+      const glyph = mark("bullet");
+      stdout.write(`  ${glyph ? `${theme.accent(glyph)} ` : ""}${message}\n`);
+    },
+
+    step(message) {
+      if (!human) return;
+      const theme = themeFor(stdout);
+      const glyph = mark("progress");
+      stdout.write(`${glyph ? `${theme.accent(glyph)} ` : ""}${message}\n`);
+    },
+
+    heading(message) {
+      if (!human) return;
+      stdout.write(`${themeFor(stdout).heading(String(message))}\n`);
+    },
+
+    /** Aligned `label  value` row used by command summaries. */
+    detail(label, value, { width = 13 } = {}) {
+      if (!human) return;
+      const theme = themeFor(stdout);
+      const text = String(value);
+      const rendered = text === "(none)" ? theme.muted(text) : theme.bold(text);
+      stdout.write(
+        `  ${theme.muted(String(label).padEnd(width))} ${rendered}\n`,
+      );
+    },
+
+    /** Aligned name + description row used by listings. */
+    item(label, value = "", { width = 24, suffix = "" } = {}) {
+      if (!human) return;
+      const theme = themeFor(stdout);
+      const text = String(label);
+      const padded = text.padEnd(Math.max(width, text.length));
+      const detail = value ? ` ${value}` : "";
+      const note = suffix ? ` ${theme.muted(suffix)}` : "";
+      stdout.write(`  ${theme.accent(padded)}${detail}${note}\n`);
+    },
+
+    /** Plain block of text with no decoration. */
+    text(message) {
+      if (!human) return;
+      stdout.write(`${message}\n`);
+    },
+
+    /** Quiet, de-emphasized line for incidental notes. */
+    note(message) {
+      if (!human) return;
+      stdout.write(`${themeFor(stdout).muted(message)}\n`);
+    },
+
+    warn(message) {
+      const text = String(message);
+      warnings.push(text);
+      if (json) return;
+      status("warn", text);
+    },
+
+    error(message) {
+      const text = String(message);
+      errors.push(text);
+      if (json) return;
+      status("error", text);
+    },
+
+    hint(message) {
+      if (!human) return;
+      const theme = themeFor(stdout);
+      stdout.write(
+        `  ${theme.accent("↳")} ${theme.muted(`hint: ${message}`)}\n`,
+      );
+    },
+
+    /** One JSON document, used for the command result envelope. */
+    document(value) {
+      if (!json) return;
+      stdout.write(`${JSON.stringify(value)}\n`);
+    },
+
+    /** One newline-delimited JSON event, used by long-running `dev`. */
+    event(type, data = {}) {
+      if (!json) return;
+      stdout.write(`${JSON.stringify({ event: type, ...data })}\n`);
+    },
+  };
+}