@triflare/fx 1.0.2 → 2.0.0

package/src/cli/completion/index.js

@@ -0,0 +1,97 @@
+/**
+ * Shell completion support.
+ *
+ * Completion is intentionally data-driven: the hidden `__complete` command
+ * walks the live commander tree, so new commands and options are completed
+ * without maintaining a second list.
+ */
+
+const VALUE_OPTIONS = {
+  "--color": ["auto", "always", "never"],
+  "--cwd": [],
+  "--config": [],
+  "--template": ["cat", "empty", "blank"],
+  "--target": ["html", "zip", "windows", "macos", "linux"],
+  "--size": ["480x360", "640x360", "1920x1080"],
+};
+
+function commandFor(program, words) {
+  let command = program;
+  for (const word of words) {
+    if (word.startsWith("-")) continue;
+    const next = command.commands.find(
+      (entry) => entry.name() === word || entry.aliases().includes(word),
+    );
+    if (!next) break;
+    command = next;
+  }
+  return command;
+}
+
+function commandWords(command) {
+  const words = new Set();
+  for (const entry of command.commands) {
+    if (entry._hidden) continue;
+    words.add(entry.name());
+    for (const alias of entry.aliases()) words.add(alias);
+  }
+  return [...words];
+}
+
+function optionWords(command) {
+  const words = new Set();
+  for (let current = command; current; current = current.parent) {
+    for (const option of current.options) {
+      if (option.hidden) continue;
+      if (option.long) words.add(option.long);
+      if (option.short) words.add(option.short);
+    }
+  }
+  return [...words];
+}
+
+/** Candidate completions for the words typed after the command name. */
+export function completionCandidates(program, words) {
+  const current = words.at(-1) ?? "";
+  const before = words.slice(0, -1).filter((word) => word !== "");
+  const command = commandFor(program, before);
+
+  // `--color=` style value completion.
+  if (current.includes("=")) {
+    const [flag, prefix] = current.split("=", 2);
+    const values = VALUE_OPTIONS[flag] ?? [];
+    return values
+      .filter((value) => value.startsWith(prefix))
+      .map((value) => `${flag}=${value}`);
+  }
+
+  // A value is expected for the previous token.
+  const previous = before.at(-1);
+  if (previous && Object.hasOwn(VALUE_OPTIONS, previous)) {
+    const values = VALUE_OPTIONS[previous];
+    return values.filter((value) => value.startsWith(current));
+  }
+
+  const candidates = new Set();
+  if (current.startsWith("-")) {
+    for (const option of optionWords(command)) {
+      if (option.startsWith(current)) candidates.add(option);
+    }
+    return [...candidates].sort();
+  }
+
+  // Groups with subcommands (the root, vendor, sprite, ...) offer their
+  // command words; leaf commands have none.
+  if (command.commands.length > 0) {
+    for (const word of commandWords(command))
+      if (word.startsWith(current)) candidates.add(word);
+  }
+
+  // Positional values that are useful and finite.
+  if (command.name() === "completion") {
+    for (const shell of ["bash", "zsh", "fish"])
+      if (shell.startsWith(current)) candidates.add(shell);
+  }
+
+  return [...candidates].sort();
+}

package/src/cli/completion/zsh.js

@@ -0,0 +1,11 @@
+/** Generate a zsh completion script. */
+export function zshCompletion(command) {
+  return `#compdef ${command}
+_${command}_complete() {
+  local -a completions
+  completions=("\${(@f)$("${command}" __complete zsh -- "\${words[@]:1}")}")
+  _describe '${command}' completions
+}
+compdef _${command}_complete ${command}
+`;
+}

package/src/cli/context.js

@@ -0,0 +1,257 @@
+/**
+ * Shared project discovery for every command.
+ *
+ * Resolves the input path, the nearest (or explicitly selected) `fx.yml`, and
+ * the extension catalog once, so commands do not repeat subtly different
+ * versions of the same logic.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { configFilename, outputDirectory, sourceExtension } from "../brand.js";
+import { loadConfigFrom, parseConfig } from "../config.js";
+import { loadExtensions } from "../extensions.js";
+import { loadVendorExtensions, migrateProjectExtensions } from "../vendor.js";
+import { UsageError } from "./errors.js";
+
+const warnedLegacy = new Set();
+const migrationDeclined = new Set();
+
+/** Split a positional input into a file or directory target. */
+export function resolveInput(input, cwd = process.cwd()) {
+  if (!input) return { dir: path.resolve(cwd) };
+  const resolved = path.resolve(cwd, input);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch {
+    throw new UsageError(`input not found: ${input}`, {
+      hint: `check the path, or run from the project directory`,
+    });
+  }
+  return stat.isDirectory() ? { dir: resolved } : { file: resolved };
+}
+
+export function inputSearchDir(target) {
+  return target.file ? path.dirname(target.file) : target.dir;
+}
+
+/** Whether `--no-config` disables configuration loading. */
+export function configDisabled(options = {}) {
+  return options.config === false || options.noConfig === true;
+}
+
+/** Load configuration from an explicit path or by searching upward. */
+export function loadProjectConfig({ cwd = process.cwd(), searchDir, options }) {
+  if (configDisabled(options)) {
+    return {
+      project: null,
+      fx: null,
+      package: null,
+      vendor: [],
+      vendorDir: "extensions",
+      path: null,
+    };
+  }
+
+  const explicit = typeof options.config === "string" ? options.config : null;
+  if (!explicit) return loadConfigFrom(searchDir);
+  const explicitPath = path.resolve(cwd, explicit);
+  if (!fs.existsSync(explicitPath))
+    throw new UsageError(`config file not found: ${explicitPath}`);
+  if (!fs.statSync(explicitPath).isFile())
+    throw new UsageError(`config path is not a file: ${explicitPath}`);
+
+  try {
+    const parsed = parseConfig(fs.readFileSync(explicitPath, "utf8"));
+    return { ...parsed, path: explicitPath };
+  } catch (error) {
+    if (error instanceof UsageError) throw error;
+    throw new UsageError(error.message, { cause: error });
+  }
+}
+
+function warnLegacyExtensions(loaded, reporter) {
+  if (!loaded?.project?.extensions?.length) return;
+  const key = loaded.path ?? "<default>";
+  if (warnedLegacy.has(key)) return;
+  warnedLegacy.add(key);
+  reporter.warn(
+    `project.extensions is deprecated and will be removed in a future major version; ` +
+      `run "${configFilename()} vendor migrate" to move extensions into vendor:`,
+  );
+}
+
+/**
+ * Offer to migrate legacy project.extensions before extensions are loaded.
+ * `--yes` accepts without a terminal; otherwise the prompt only runs on one.
+ */
+async function upgradeLegacyExtensions({
+  loaded,
+  cwd,
+  searchDir,
+  options = {},
+  reporter,
+  prompts,
+}) {
+  if (!loaded?.path || !loaded.project?.extensions?.length) return loaded;
+  warnLegacyExtensions(loaded, reporter);
+  if (migrationDeclined.has(loaded.path)) return loaded;
+  if (options.upgradePrompt === false || process.env.FX_NO_PROMPT === "1")
+    return loaded;
+
+  const auto = Boolean(options.yes);
+  const interactive = !auto && Boolean(prompts?.enabled);
+  if (!auto && !interactive) return loaded;
+  if (!auto) {
+    const upgrade = await prompts.confirm({
+      message: "Upgrade project.extensions to the vendor system?",
+      initialValue: true,
+    });
+    if (!upgrade) {
+      migrationDeclined.add(loaded.path);
+      return loaded;
+    }
+  }
+
+  try {
+    const result = await migrateProjectExtensions({
+      configPath: loaded.path,
+      configDir: path.dirname(loaded.path),
+      config: loaded,
+      nameFor: interactive
+        ? (name, source) =>
+            prompts.text({
+              message: `Name for ${source}`,
+              defaultValue: name,
+            })
+        : undefined,
+    });
+    for (const warning of result.warnings) reporter.warn(warning);
+    if (result.diff) reporter.text(result.diff);
+    if (result.migrated.length > 0)
+      reporter.success(
+        `Vendored ${result.migrated.length} extension(s); backup: ${path.relative(
+          cwd,
+          result.backup,
+        )}`,
+      );
+    return loadProjectConfig({ cwd, searchDir, options, reporter });
+  } catch (error) {
+    // A failed migration would otherwise warn (and retry) on every rebuild.
+    migrationDeclined.add(loaded.path);
+    reporter.warn(`Could not migrate project.extensions: ${error.message}`);
+    return loaded;
+  }
+}
+
+/** Load vendored and legacy extensions into one catalog. */
+export async function loadProjectExtensions({ configDir, loaded, reporter }) {
+  const catalog = {};
+  const extensionUrls = {};
+  const unsandboxed = [];
+  const config = loaded?.project || {};
+  const matchedUnsandboxed = new Set();
+  const unnecessaryUnsandboxed = new Set();
+
+  if (loaded?.vendor && loaded.vendor.length > 0) {
+    const vendored = await loadVendorExtensions({ configDir, config: loaded });
+    Object.assign(catalog, vendored.catalog);
+    Object.assign(extensionUrls, vendored.extensionUrls);
+    unsandboxed.push(...vendored.unsandboxed);
+    for (const name of vendored.matchedUnsandboxed || [])
+      matchedUnsandboxed.add(name);
+    for (const name of vendored.unnecessaryUnsandboxed || [])
+      unnecessaryUnsandboxed.add(name);
+    for (const warning of vendored.warnings) reporter.warn(warning);
+  }
+
+  if (config.extensions && config.extensions.length > 0) {
+    warnLegacyExtensions(loaded, reporter);
+    const legacy = await loadExtensions(config.extensions, {
+      baseDir: configDir,
+      expectUnsandboxed: config.unsandboxed,
+      reportUnmatchedUnsandboxed: false,
+    });
+    Object.assign(catalog, legacy.catalog);
+    Object.assign(extensionUrls, legacy.extensionUrls);
+    unsandboxed.push(...legacy.unsandboxed);
+    for (const name of legacy.matchedUnsandboxed || [])
+      matchedUnsandboxed.add(name);
+    for (const name of legacy.unnecessaryUnsandboxed || [])
+      unnecessaryUnsandboxed.add(name);
+    for (const warning of legacy.warnings) reporter.warn(warning);
+  }
+
+  for (const name of new Set(config.unsandboxed || [])) {
+    if (unnecessaryUnsandboxed.has(name)) {
+      reporter.warn(
+        `project.unsandboxed entry "${name}" loads in the sandbox; remove it from fx.yml`,
+      );
+    } else if (!matchedUnsandboxed.has(name)) {
+      reporter.warn(
+        `project.unsandboxed entry "${name}" does not match any loaded extension`,
+      );
+    }
+  }
+
+  return { catalog, extensionUrls, unsandboxed };
+}
+
+/**
+ * Resolve everything a build-like command needs.
+ *
+ * @param {{
+ *   input?: string,
+ *   cwd: string,
+ *   options: object,
+ *   reporter: object,
+ *   prompts?: object,
+ *   includeExtensions?: boolean,
+ *   migrateLegacy?: boolean,
+ * }} options
+ */
+export async function loadProjectState({
+  input,
+  cwd,
+  options,
+  reporter,
+  prompts = null,
+  includeExtensions = true,
+  migrateLegacy = true,
+}) {
+  const target = resolveInput(input, cwd);
+  const searchDir = inputSearchDir(target);
+  let loaded = loadProjectConfig({ cwd, searchDir, options, reporter });
+  if (migrateLegacy)
+    loaded = await upgradeLegacyExtensions({
+      loaded,
+      cwd,
+      searchDir,
+      options,
+      reporter,
+      prompts,
+    });
+  const configDir = loaded.path ? path.dirname(loaded.path) : searchDir;
+  const extensions = includeExtensions
+    ? await loadProjectExtensions({ configDir, loaded, reporter })
+    : { catalog: {}, extensionUrls: {}, unsandboxed: [] };
+
+  return {
+    target,
+    searchDir,
+    loaded,
+    configDir,
+    ...extensions,
+  };
+}
+
+/** Default output directory for a directory build. */
+export function defaultOutputDirectory(cwd) {
+  return path.join(cwd, outputDirectory());
+}
+
+/** Source extension used in user-facing messages. */
+export function sourceSuffix() {
+  return sourceExtension();
+}

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;
+}