@triflare/fx 1.0.3 → 2.0.0

package/src/cli/commands/vendor/outdated.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { outdatedVendor } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import { outcome } from "../../define-command.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorOutdatedCommand = {
+  name: "outdated",
+  summary: "Compare upstream sources with fx.lock",
+  description: "Check whether any vendored extension changed upstream.",
+  examples: ["fx vendor outdated"],
+  async run({ cwd, reporter, product }) {
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+    if (loaded.vendor.length === 0)
+      throw new UsageError(`No vendor entries in ${path.basename(configPath)}`);
+
+    const results = await outdatedVendor({ configDir, config: loaded });
+    let outdated = 0;
+    let errors = 0;
+    for (const result of results) {
+      if (result.status === "outdated") outdated += 1;
+      if (result.status === "error") errors += 1;
+      const label =
+        result.status === "outdated"
+          ? "outdated"
+          : result.status === "error"
+            ? "error"
+            : "up to date";
+      const tone =
+        result.status === "outdated"
+          ? "warning"
+          : result.status === "error"
+            ? "danger"
+            : "success";
+      reporter.item(result.name, reporter.tone(tone, label), { width: 24 });
+      if (result.error) reporter.warn(result.error);
+    }
+    if (outdated > 0)
+      reporter.warn(
+        `${outdated} extension(s) changed upstream; run "${product.command} vendor update"`,
+      );
+    else if (errors === 0) reporter.success("Everything is up to date");
+
+    return outcome({
+      data: results,
+      exitCode: errors > 0 ? 1 : 0,
+    });
+  },
+};

package/src/cli/commands/vendor/remove.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { removeVendoredExtension } from "../../../vendor.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorRemoveCommand = {
+  name: "remove",
+  summary: "Remove a vendored extension",
+  description:
+    "Remove an extension from the project config, fx.lock, and the vendor directory.",
+  arguments: ["<name>"],
+  examples: ["fx vendor remove signals"],
+  async run({ args, cwd, reporter, prompts, yes, product }) {
+    const name = args[0];
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+
+    await prompts.confirmDestructive({
+      message: `Remove vendored extension ${JSON.stringify(name)}?`,
+      yes,
+    });
+
+    const result = removeVendoredExtension({
+      configPath,
+      configDir,
+      config: loaded,
+      name,
+    });
+    reporter.success(
+      `Removed ${name} from ${path.basename(configPath)}, fx.lock and ${result.file}`,
+    );
+    return { name, file: result.file };
+  },
+};

package/src/cli/commands/vendor/update.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { updateVendor } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorUpdateCommand = {
+  name: "update",
+  summary: "Update vendored extensions and show diffs",
+  description: `Re-fetch upstream sources, update the vendored copies, and show a
+diff for each change. Use --dry-run to preview without writing.`,
+  arguments: ["[name]"],
+  options: [
+    { flags: "--dry-run", description: "Show diffs without writing files" },
+  ],
+  examples: ["fx vendor update", "fx vendor update signals --dry-run"],
+  async run({ args, options, cwd, reporter, product }) {
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+    if (loaded.vendor.length === 0)
+      throw new UsageError(`No vendor entries in ${path.basename(configPath)}`);
+
+    const result = await updateVendor({
+      configPath,
+      configDir,
+      config: loaded,
+      name: args[0],
+      write: !options.dryRun,
+    });
+    for (const entry of result.entries) {
+      if (!entry.changed) {
+        reporter.info(`${entry.name} is up to date`);
+        continue;
+      }
+      reporter.text(entry.diff);
+    }
+    if (options.dryRun && result.changed > 0)
+      reporter.info(`Dry run: ${result.changed} extension(s) would change`);
+    else if (result.changed > 0)
+      reporter.success(`Updated ${result.changed} extension(s)`);
+    else reporter.success("Everything is up to date");
+
+    return {
+      dryRun: Boolean(options.dryRun),
+      changed: result.changed,
+      entries: result.entries.map(({ name, changed }) => ({ name, changed })),
+    };
+  },
+};

package/src/cli/commands/vendor/verify.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { LOCK_FILENAME, verifyVendor } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import { outcome } from "../../define-command.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorVerifyCommand = {
+  name: "verify",
+  summary: "Check vendored files against fx.lock offline",
+  description:
+    "Verify every vendored extension without making network requests.",
+  examples: ["fx vendor verify"],
+  run({ cwd, reporter, product }) {
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+    if (loaded.vendor.length === 0)
+      throw new UsageError(`No vendor entries in ${path.basename(configPath)}`);
+
+    const result = verifyVendor({ configDir, config: loaded });
+    for (const warning of result.warnings) reporter.warn(warning);
+    for (const entry of result.entries)
+      if (entry.status === "ok")
+        reporter.item(entry.name, entry.file, { width: 24 });
+
+    if (!result.ok) {
+      for (const problem of result.problems) reporter.error(problem);
+      return outcome({
+        exitCode: 1,
+        data: { entries: result.entries, problems: result.problems },
+        error: {
+          code: "VENDOR_VERIFY_FAILED",
+          message: `Vendor verification failed for ${result.problems.length} extension(s)`,
+          details: { problems: result.problems },
+        },
+      });
+    }
+
+    reporter.success(
+      `Verified ${result.entries.length} extension(s) against ${LOCK_FILENAME}`,
+    );
+    return { entries: result.entries };
+  },
+};

package/src/cli/completion/bash.js

@@ -0,0 +1,10 @@
+/** Generate a bash completion script. */
+export function bashCompletion(command) {
+  return `# bash completion for ${command}
+_${command}_complete() {
+  local IFS=$'\\n'
+  COMPREPLY=( $("${command}" __complete bash -- "\${COMP_WORDS[@]:1}") )
+}
+complete -o bashdefault -o default -F _${command}_complete ${command}
+`;
+}

package/src/cli/completion/fish.js

@@ -0,0 +1,9 @@
+/** Generate a fish completion script. */
+export function fishCompletion(command) {
+  return `# fish completion for ${command}
+function __${command}_complete
+  ${command} __complete fish -- (commandline -opc)[2..-1]
+end
+complete -c ${command} -f -a '(__${command}_complete)'
+`;
+}

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