@triflare/fx 1.0.2 → 2.0.0

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

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { spriteGroups } from "./helpers.js";
+
+export const spriteListCommand = {
+  name: "list",
+  summary: "List declared sprites",
+  description: "List every sprite declared under a directory.",
+  arguments: ["[dir]"],
+  examples: ["fx sprite list", "fx sprite list src --json"],
+  run({ args, cwd, reporter }) {
+    const dir = path.resolve(cwd, args[0] || ".");
+    const sprites = spriteGroups(dir);
+    if (sprites.length === 0) {
+      reporter.info(`No sprites under ${dir}`);
+    } else {
+      for (const { name, files } of sprites)
+        reporter.item(
+          name,
+          files.map((file) => path.relative(dir, file) || file).join(", "),
+          { width: 24 },
+        );
+    }
+
+    return sprites.map(({ name, file, files, partial }) => ({
+      name,
+      file: path.relative(dir, file),
+      files: files.map((entry) => path.relative(dir, entry)),
+      partial,
+    }));
+  },
+};

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

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "../../../parser.js";
+import { CliError } from "../../errors.js";
+import { spriteNames } from "./helpers.js";
+
+export const spriteRemoveCommand = {
+  name: "remove",
+  summary: "Delete files that declare only one sprite",
+  description: `Delete the source file(s) that declare a sprite. Files that also
+contain other code are refused.`,
+  arguments: ["<name>"],
+  examples: ["fx sprite remove Cat"],
+  async run({ args, cwd, reporter, prompts, yes }) {
+    const name = args[0];
+    const matches = spriteNames(cwd).filter((entry) => entry.name === name);
+    if (matches.length === 0)
+      throw new CliError(
+        `No sprite named ${JSON.stringify(name)} under ${cwd}`,
+        { code: "SPRITE_NOT_FOUND" },
+      );
+
+    const files = [...new Set(matches.map((entry) => entry.file))];
+    for (const file of files) {
+      const ast = parse(fs.readFileSync(file, "utf8"), file);
+      const onlyThisSprite =
+        ast.sprites.length > 0 &&
+        ast.sprites.every((sprite) => sprite.name === name) &&
+        ast.topItems.length === 0 &&
+        !ast.stage;
+      if (!onlyThisSprite)
+        throw new CliError(
+          `${file} also declares other code; remove the sprite block by hand`,
+          { code: "SPRITE_SHARED_FILE" },
+        );
+    }
+
+    await prompts.confirmDestructive({
+      message: `Delete ${files.length} file(s) for sprite ${JSON.stringify(name)}?`,
+      yes,
+    });
+
+    for (const file of files) fs.rmSync(file);
+    reporter.success(
+      `Removed sprite ${name} (${files
+        .map((file) => path.relative(cwd, file) || file)
+        .join(", ")})`,
+    );
+    return { name, files };
+  },
+};

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

@@ -0,0 +1,98 @@
+import path from "node:path";
+import { defaultVendorName, installVendorEntry } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+import {
+  loadVendorConfig,
+  requireConfigPath,
+  vendorConfigSource,
+} from "./helpers.js";
+
+/** Shared implementation for `vendor add` and legacy `vendor install <src>`. */
+export async function addVendor({
+  source,
+  options,
+  cwd,
+  reporter,
+  product,
+}) {
+  if (!source) throw new UsageError("vendor add requires a path or URL");
+  const configPath = requireConfigPath(cwd, product);
+  const configDir = path.dirname(configPath);
+  const loaded = loadVendorConfig(configPath);
+
+  if (typeof options.as === "string" && options.as.trim() === "")
+    throw new UsageError("--as needs a non-empty name");
+  const name =
+    typeof options.as === "string" ? options.as : defaultVendorName(source);
+  const configSource = vendorConfigSource(source, configDir, cwd);
+  const existing = loaded.vendor.find((entry) => entry.name === name);
+  if (existing && existing.source !== configSource && !options.force)
+    throw new UsageError(
+      `A vendored extension named ${JSON.stringify(name)} already exists.`,
+      {
+        hint: `run "${product.command} vendor update ${name}" or pass --force to replace it`,
+      },
+    );
+
+  const rawEntry = loaded.raw?.vendor?.[name];
+  const existingVolatile =
+    rawEntry &&
+    typeof rawEntry === "object" &&
+    Object.hasOwn(rawEntry, "volatile") &&
+    rawEntry.volatile != null
+      ? Boolean(rawEntry.volatile)
+      : undefined;
+  const result = await installVendorEntry({
+    configPath,
+    configDir,
+    name,
+    source: configSource,
+    vendorDir: path.resolve(configDir, loaded.vendorDir || "extensions"),
+    unsandboxed: Boolean(options.unsandboxed) || Boolean(existing?.unsandboxed),
+    volatile: existingVolatile,
+  });
+
+  reporter.success(
+    `Vendored ${name} -> ${result.file} (${result.lockEntry.sha256.slice(0, 12)}…)`,
+  );
+  if (existing)
+    reporter.info(`Updated ${name} in ${path.basename(configPath)}`);
+  else reporter.success(`Added ${name} to ${path.basename(configPath)}`);
+
+  return {
+    name,
+    source: configSource,
+    file: result.file,
+    sha256: result.lockEntry.sha256,
+    replaced: Boolean(existing),
+  };
+}
+
+export const vendorAddCommand = {
+  name: "add",
+  summary: "Vendor an extension by URL or path",
+  description: `Copy an extension into the vendor directory, record its SHA-256 in
+fx.lock, and add it to the project config.`,
+  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 add https://example.com/signals.js --as signals",
+    "fx vendor add ./src/mything.js",
+  ],
+  run(context) {
+    return addVendor({
+      source: context.args[0],
+      options: context.options,
+      cwd: context.cwd,
+      reporter: context.reporter,
+      product: context.product,
+    });
+  },
+};

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

@@ -0,0 +1,50 @@
+import path from "node:path";
+import { configFilename } from "../../../brand.js";
+import { findConfigPath, loadConfigFrom } from "../../../config.js";
+import { resolveVendorFiles } from "../../../vendor.js";
+import { UsageError } from "../../errors.js";
+
+/** Find the project config or explain how to create one. */
+export function requireConfigPath(cwd, product) {
+  const found = findConfigPath(cwd);
+  if (!found)
+    throw new UsageError(`No ${configFilename(product)} found.`, {
+      hint: `run "${product?.command ?? "fx"} init" first`,
+    });
+  return found;
+}
+
+export function loadVendorConfig(configPath) {
+  return loadConfigFrom(path.dirname(configPath));
+}
+
+/** Turn a command-line local path into a path relative to the config file. */
+export function vendorConfigSource(source, configDir, cwd = process.cwd()) {
+  if (/^https?:\/\//i.test(source) || /^data:/i.test(source)) return source;
+  const absolute = path.isAbsolute(source)
+    ? source
+    : path.resolve(cwd, source);
+  const relative = path.relative(configDir, absolute).split(path.sep).join("/");
+  if (!relative) return ".";
+  return relative.startsWith(".") ? relative : `./${relative}`;
+}
+
+export function vendorEntriesWithLock(loaded, lock, configDir) {
+  const dirName = loaded.vendorDir || "extensions";
+  const dir = path.resolve(configDir, dirName);
+  const files = resolveVendorFiles(configDir, dir, loaded.vendor || [], lock);
+  return (loaded.vendor || []).map((entry) => {
+    const { file } = files.get(entry.name);
+    return {
+      name: entry.name,
+      source: entry.source,
+      file,
+      remote: entry.remote,
+      local: entry.local,
+      volatile: entry.volatile,
+      unsandboxed: entry.unsandboxed,
+      sha256: lock.extensions[entry.name]?.sha256 ?? null,
+      fetched: lock.extensions[entry.name]?.fetched ?? null,
+    };
+  });
+}

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

@@ -0,0 +1,39 @@
+import { Command } from "commander";
+import { defineCommand } from "../../define-command.js";
+import { vendorAddCommand } from "./add.js";
+import { vendorInstallCommand } from "./install.js";
+import { vendorListCommand } from "./list.js";
+import { vendorMigrateCommand } from "./migrate.js";
+import { vendorOutdatedCommand } from "./outdated.js";
+import { vendorRemoveCommand } from "./remove.js";
+import { vendorUpdateCommand } from "./update.js";
+import { vendorVerifyCommand } from "./verify.js";
+
+const SUBCOMMANDS = [
+  vendorAddCommand,
+  vendorInstallCommand,
+  vendorUpdateCommand,
+  vendorOutdatedCommand,
+  vendorVerifyCommand,
+  vendorRemoveCommand,
+  vendorListCommand,
+  vendorMigrateCommand,
+];
+
+export function registerVendor(program, options) {
+  const vendor = new Command("vendor")
+    .description(
+      "Copy extensions into the vendor directory and load them from there.",
+    )
+    .helpGroup("Extension Commands:");
+  vendor.copyInheritedSettings(program);
+  vendor.addHelpText(
+    "after",
+    `\nExamples:\n  fx vendor add https://example.com/ext.js --as ext\n  fx vendor install\n  fx vendor update --dry-run\n`,
+  );
+  vendor.action(() => vendor.outputHelp());
+  program.addCommand(vendor);
+
+  for (const spec of SUBCOMMANDS) defineCommand(vendor, spec, options);
+  return vendor;
+}

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