@triflare/fx 1.0.3 → 2.1.0-beta.1

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

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { LOCK_FILENAME, installVendor } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import { addVendor } from "./add.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorInstallCommand = {
+  name: "install",
+  summary: "Restore vendored extensions from fx.lock",
+  description: `Fetch only the vendored files that are missing, verifying them
+against fx.lock. Without a source, restores every configured entry.`,
+  arguments: ["[source]"],
+  options: [
+    { flags: "--as <name>", description: "Name for the vendored extension" },
+    {
+      flags: "--unsandboxed",
+      description: "Allow the extension to run unsandboxed",
+    },
+    { flags: "--force", description: "Replace an existing entry with the name" },
+  ],
+  examples: ["fx vendor install", "fx vendor add https://example.com/ext.js"],
+  async run(context) {
+    const { args, options, cwd, reporter, product } = context;
+    const source = args[0];
+    if (source) {
+      reporter.warn(
+        '"vendor install <source>" is deprecated; use "vendor add <source>".',
+      );
+      return addVendor({ source, 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)}.`,
+        {
+          hint: `add one with "${product.command} vendor add <url|path>"`,
+        },
+      );
+
+    const result = await installVendor({
+      configPath,
+      configDir,
+      config: loaded,
+    });
+    for (const warning of result.warnings) reporter.warn(warning);
+    for (const entry of result.entries)
+      reporter.success(`${entry.name}: ${entry.status} (${entry.file})`);
+    reporter.success(
+      `Installed ${result.entries.length} extension(s) from ${LOCK_FILENAME}`,
+    );
+
+    return {
+      lock: LOCK_FILENAME,
+      entries: result.entries.map(({ name, status, file }) => ({
+        name,
+        status,
+        file,
+      })),
+    };
+  },
+};

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

@@ -0,0 +1,45 @@
+import path from "node:path";
+import { readLock } from "../../../vendor.js";
+import {
+  loadVendorConfig,
+  requireConfigPath,
+  vendorEntriesWithLock,
+} from "./helpers.js";
+
+export const vendorListCommand = {
+  name: "list",
+  summary: "List vendored extensions",
+  description: "List every extension declared in the vendor config.",
+  examples: ["fx vendor list", "fx vendor list --json"],
+  run({ cwd, reporter, product }) {
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+    const lock = readLock(configDir);
+    const entries = vendorEntriesWithLock(loaded, lock, configDir);
+
+    reporter.heading(
+      `${path.basename(configPath)}: ${entries.length} vendored extension(s) in ${
+        loaded.vendorDir || "extensions"
+      }/`,
+    );
+    for (const entry of entries) {
+      const flags = [
+        entry.remote ? "remote" : entry.local ? "local" : "embedded",
+        entry.volatile ? "volatile" : null,
+        entry.unsandboxed ? "unsandboxed" : null,
+      ]
+        .filter(Boolean)
+        .join(", ");
+      reporter.item(entry.name, entry.file, {
+        width: 24,
+        suffix: flags ? `[${flags}]` : "",
+      });
+    }
+
+    return {
+      vendorDir: loaded.vendorDir || "extensions",
+      extensions: entries,
+    };
+  },
+};

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

@@ -0,0 +1,47 @@
+import path from "node:path";
+import { migrateProjectExtensions } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import { loadVendorConfig, requireConfigPath } from "./helpers.js";
+
+export const vendorMigrateCommand = {
+  name: "migrate",
+  summary: "Move project.extensions under vendor:",
+  description: `Move legacy project.extensions entries into the vendor system,
+writing a .bak copy of the config first.`,
+  examples: ["fx vendor migrate", "fx vendor migrate --yes"],
+  async run({ cwd, reporter, prompts, yes, product }) {
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    const loaded = loadVendorConfig(configPath);
+    if (loaded.project.extensions.length === 0)
+      throw new UsageError(
+        `No project.extensions to migrate in ${path.basename(configPath)}`,
+      );
+
+    const interactive = prompts.enabled && !yes;
+    const result = await migrateProjectExtensions({
+      configPath,
+      configDir,
+      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);
+    reporter.success(`Backed up ${path.basename(configPath)} -> ${result.backup}`);
+    reporter.success(`Migrated ${result.migrated.length} extension(s) to vendor:`);
+    for (const entry of result.migrated)
+      reporter.item(entry.name, entry.file, { width: 24 });
+
+    return {
+      backup: result.backup,
+      migrated: result.migrated.map(({ name, file }) => ({ name, file })),
+      warnings: result.warnings,
+    };
+  },
+};

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