@triflare/fx 1.0.3 → 2.1.0-beta.1

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,203 @@
+/**
+ * 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`);
+    },
+
+    /**
+     * Unmodified product output, such as formatted source. Quiet does not
+     * suppress it because it is the command's result; JSON mode does.
+     */
+    raw(text) {
+      if (json) return;
+      stdout.write(String(text));
+    },
+
+    /** 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`);
+    },
+  };
+}

package/src/cli/run.js

@@ -0,0 +1,248 @@
+/**
+ * CLI entrypoint: commander setup, global options, and top-level error
+ * handling.
+ */
+
+import process from "node:process";
+import { Command, CommanderError } from "commander";
+import { brandText } from "../brand.js";
+import { loadProduct } from "../product.js";
+import { registerCommands } from "./commands/index.js";
+import {
+  CliError,
+  EXIT,
+  UsageError,
+  errorToJson,
+  formatError,
+} from "./errors.js";
+import { createReporter } from "./reporter.js";
+import { createTheme } from "./theme.js";
+
+const USAGE_CODES = new Set([
+  "commander.unknownCommand",
+  "commander.unknownOption",
+  "commander.missingArgument",
+  "commander.optionMissingArgument",
+  "commander.invalidArgument",
+  "commander.excessArguments",
+]);
+
+function resolveColor(options = {}) {
+  if (options.color === false || options.color === "never") return "never";
+  if (options.color === "always") return "always";
+  return "auto";
+}
+
+/** Read the global flags needed before commander has parsed successfully. */
+function scanGlobalFlags(argv) {
+  const result = {
+    json: false,
+    quiet: false,
+    verbose: false,
+    color: "auto",
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--json") result.json = true;
+    else if (token === "-q" || token === "--quiet") result.quiet = true;
+    else if (token === "-v" || token === "--verbose") result.verbose = true;
+    else if (token === "--no-color") result.color = "never";
+    else if (token === "--color") result.color = argv[++i] ?? "auto";
+    else if (token.startsWith("--color="))
+      result.color = token.slice("--color=".length);
+  }
+  return result;
+}
+
+function commandFromArgv(argv, program) {
+  const names = new Set();
+  for (const command of program.commands)
+    for (const name of [command.name(), ...command.aliases()]) names.add(name);
+  for (const token of argv) if (names.has(token)) return token;
+  return null;
+}
+
+function styleUsage(text, theme) {
+  return text
+    .split(" ")
+    .map((word) => {
+      if (word === "[options]") return theme.option(word);
+      if (word === "[command]") return theme.command(word);
+      if (word.startsWith("[") || word.startsWith("<"))
+        return theme.argument(word);
+      return theme.command(word);
+    })
+    .join(" ");
+}
+
+function styleOptionTerm(text, theme) {
+  return text
+    .split(" ")
+    .map((word) =>
+      word.startsWith("<") || word.startsWith("[")
+        ? theme.argument(word)
+        : theme.option(word),
+    )
+    .join(" ");
+}
+
+function styleSubcommandTerm(text, theme) {
+  return text
+    .split(" ")
+    .map((word) => {
+      if (word === "[options]") return theme.option(word);
+      if (word.startsWith("[") || word.startsWith("<"))
+        return theme.argument(word);
+      return theme.command(word);
+    })
+    .join(" ");
+}
+
+function createProgram(product, theme, color) {
+  const program = new Command();
+  program
+    .name(product.command)
+    .description(product.tagline)
+    .version(
+      `${product.name} ${product.version}`,
+      "-V, --version",
+      "Print the version",
+    )
+    .helpOption("-h, --help", "Show help")
+    .helpCommand("help [command]", "Show help for a command")
+    .showSuggestionAfterError(true)
+    .configureHelp({
+      sortCommands: false,
+      sortOptions: false,
+      showGlobalOptions: true,
+      styleTitle: (text) => theme.heading(text),
+      styleUsage: (text) => styleUsage(text, theme),
+      styleCommandText: (text) => theme.command(text),
+      styleSubcommandText: (text) => theme.command(text),
+      styleOptionText: (text) => theme.option(text),
+      styleArgumentText: (text) => theme.argument(text),
+      styleCommandDescription: (text) => theme.muted(text),
+      styleOptionDescription: (text) => theme.muted(text),
+      styleSubcommandDescription: (text) => theme.muted(text),
+      styleArgumentDescription: (text) => theme.muted(text),
+      styleOptionTerm: (text) => styleOptionTerm(text, theme),
+      styleSubcommandTerm: (text) => styleSubcommandTerm(text, theme),
+      styleArgumentTerm: (text) => theme.argument(text),
+    })
+    .optionsGroup("Global Options:")
+    .option("-v, --verbose", "Show timings, stack traces, and extra detail")
+    .option("--json", "Emit machine-readable JSON")
+    .option("-q, --quiet", "Suppress success and informational output")
+    .option("--color <mode>", "Color output: auto, always, or never", "auto")
+    .option("--no-color", "Disable color output")
+    .option("--cwd <dir>", "Run as if started in <dir>")
+    .option("--config <file>", "Use a specific config file")
+    .option("--no-config", "Ignore the project config file")
+    .option("--no-input", "Never prompt for input")
+    .option("-y, --yes", "Accept defaults and confirm destructive actions")
+    .option(
+      "--no-upgrade-prompt",
+      "Do not offer to migrate project.extensions",
+    );
+
+  program.addHelpText(
+    "before",
+    `\n  ${brandText(product.name, process.stdout, {
+      force: color === "always",
+    })} ${theme.muted(product.version)}\n  ${theme.muted(product.tagline)}\n`,
+  );
+  program.addHelpText(
+    "after",
+    `\n  ${theme.accent("↳")} Run ${theme.command(
+      `${product.command} <command> --help`,
+    )} for command details.\n`,
+  );
+
+  return program;
+}
+
+/**
+ * Run the CLI and return an exit code instead of terminating the process.
+ *
+ * @param {string[]} [argv]
+ * @returns {Promise<number>}
+ */
+export async function run(argv = process.argv.slice(2)) {
+  const product = loadProduct();
+  const raw = scanGlobalFlags(argv);
+  const color = resolveColor(raw);
+  const theme = createTheme({ product, color, stream: process.stdout });
+  const reporter = createReporter({
+    product,
+    json: raw.json,
+    quiet: raw.quiet,
+    verbose: raw.verbose,
+    color,
+  });
+  const state = { exitCode: EXIT.OK, command: null };
+  const program = createProgram(product, theme, color);
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: (text) => process.stdout.write(text),
+    writeErr: (text) => process.stderr.write(text),
+    getOutHasColors: () => theme.enabled,
+    getErrHasColors: () => theme.enabled,
+    // Keep commander's usage text out of the stream; run() renders one
+    // consistent diagnostic (or JSON document) below.
+    outputError: () => {},
+  });
+
+  registerCommands(program, { state, product });
+  // With no command, print help to stdout instead of commander's stderr usage.
+  program.action(() => program.outputHelp());
+
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return state.exitCode;
+  } catch (error) {
+    if (error instanceof CommanderError) {
+      if (
+        error.code === "commander.helpDisplayed" ||
+        error.code === "commander.help" ||
+        error.code === "commander.version"
+      )
+        return EXIT.OK;
+
+      const usage = new UsageError(error.message.replace(/^error:\s*/, ""), {
+        code: USAGE_CODES.has(error.code) ? "USAGE_ERROR" : "COMMANDER_ERROR",
+        hint: `run "${product.command} help" for usage`,
+      });
+      usage.command = state.command ?? commandFromArgv(argv, program);
+      usage.warnings = [];
+      return reportError(usage, reporter);
+    }
+
+    if (error && typeof error === "object") {
+      error.warnings ??= [];
+      error.command ??= state.command ?? commandFromArgv(argv, program);
+    }
+    return reportError(error, reporter);
+  }
+}
+
+function reportError(error, reporter) {
+  const exitCode = error instanceof CliError ? error.exitCode : EXIT.FAILURE;
+  const command = error?.command ?? null;
+
+  if (reporter.json) {
+    reporter.document({
+      schemaVersion: 1,
+      command,
+      ok: false,
+      warnings: error?.warnings ?? [],
+      error: errorToJson(error),
+    });
+    return exitCode;
+  }
+
+  if (error instanceof CliError && error.silent) return exitCode;
+
+  reporter.error(formatError(error, { verbose: reporter.verbose }));
+  if (error instanceof CliError && error.hint) reporter.hint(error.hint);
+  return exitCode;
+}