@triflare/fx 1.0.3 → 2.0.0

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

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+import { findConfigPath } from "../../../config.js";
+import { sourceExtension } from "../../../brand.js";
+import { slugify } from "../../../package.js";
+import { parse } from "../../../parser.js";
+import { readSprite, spriteSource } from "../../../sprite.js";
+import { CliError } from "../../errors.js";
+import {
+  readInputBytes,
+  spriteNames,
+  spriteRoot,
+  spriteSourceDir,
+} from "./helpers.js";
+
+export const spriteAddCommand = {
+  name: "add",
+  summary: "Import a .sprite3/.pms sprite as source",
+  description: `Import a sprite archive, write its assets, and generate a .tfx
+source file.`,
+  arguments: ["<source>"],
+  options: [
+    { flags: "--name <name>", description: "Override the sprite name" },
+    { flags: "--force", description: "Overwrite an existing source file" },
+  ],
+  examples: [
+    "fx sprite add robot.sprite3",
+    "fx sprite add https://example.com/cat.pms --name Cat",
+  ],
+  async run({ args, options, cwd, reporter, product }) {
+    const source = args[0];
+    const configPath = findConfigPath(cwd);
+    const rootDir = spriteRoot(cwd, configPath);
+
+    const { sprite, assets } = readSprite(await readInputBytes(source, cwd));
+    const name = typeof options.name === "string" ? options.name : sprite.name;
+    if (!name)
+      throw new CliError("sprite add could not read a sprite name", {
+        code: "SPRITE_NAME_MISSING",
+        hint: "pass --name <name>",
+      });
+    sprite.name = name;
+
+    const existing = spriteNames(rootDir).find((entry) => entry.name === name);
+    if (existing)
+      throw new CliError(
+        `A sprite named ${JSON.stringify(name)} already exists in ${existing.file}`,
+        {
+          code: "SPRITE_EXISTS",
+          hint: "remove it first, or choose another name with --name",
+        },
+      );
+
+    const sourceDir = spriteSourceDir(rootDir, product);
+    const file = path.join(
+      sourceDir,
+      `${slugify(name)}${sourceExtension(product)}`,
+    );
+    if (fs.existsSync(file) && !options.force)
+      throw new CliError(`${file} already exists`, {
+        code: "SPRITE_FILE_EXISTS",
+        hint: "pass --force to overwrite",
+      });
+
+    const assetsDir = path.join(rootDir, "assets");
+    const relative = path.relative(sourceDir, assetsDir).replace(/\\/g, "/");
+    const text = spriteSource(sprite, {
+      assetPrefix: relative ? `${relative}/` : "",
+    });
+    parse(text, file);
+
+    fs.mkdirSync(assetsDir, { recursive: true });
+    for (const [assetName, data] of assets)
+      fs.writeFileSync(path.join(assetsDir, assetName), data);
+    fs.mkdirSync(sourceDir, { recursive: true });
+    fs.writeFileSync(file, text);
+
+    reporter.success(`Added sprite ${name} -> ${path.relative(rootDir, file)}`);
+    return {
+      name,
+      file,
+      assets: [...assets.keys()],
+    };
+  },
+};

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

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+import { build } from "../../../build.js";
+import { outputDirectory } from "../../../brand.js";
+import { slugify } from "../../../package.js";
+import { spriteArchive } from "../../../sprite.js";
+import { loadProjectState } from "../../context.js";
+import { CliError } from "../../errors.js";
+
+export const spriteBuildCommand = {
+  name: "build",
+  summary: "Compile one sprite into a .pms archive",
+  description:
+    "Build a single sprite from the current project into a .pms file.",
+  arguments: ["<name>"],
+  options: [{ flags: "-o, --output <file>", description: "Output .pms path" }],
+  examples: ["fx sprite build Cat", "fx sprite build Cat -o cat.pms"],
+  async run({ args, options, cwd, reporter, prompts }) {
+    const name = args[0];
+    const state = await loadProjectState({
+      input: undefined,
+      cwd,
+      options,
+      reporter,
+      prompts,
+    });
+    const result = build({
+      ...state.target,
+      projectConfig: state.loaded.project,
+      fxConfig: state.loaded.fx,
+      catalog: state.catalog,
+      extensionUrls: state.extensionUrls,
+      useConfigFile: false,
+    });
+
+    const sprite = result.project.targets.find(
+      (target) => !target.isStage && target.name === name,
+    );
+    if (!sprite) {
+      const available = result.project.targets
+        .filter((target) => !target.isStage)
+        .map((target) => target.name);
+      throw new CliError(
+        `No sprite named ${JSON.stringify(name)}. ` +
+          (available.length
+            ? `Available: ${available.join(", ")}`
+            : "The project has no sprites."),
+        { code: "SPRITE_NOT_FOUND" },
+      );
+    }
+
+    const output =
+      options.output !== undefined
+        ? path.resolve(cwd, options.output)
+        : path.join(cwd, outputDirectory(), `${slugify(name)}.pms`);
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(output, spriteArchive(sprite, result.assets));
+
+    reporter.success(`Built sprite ${name} -> ${output}`);
+    return { name, output };
+  },
+};

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

@@ -0,0 +1,66 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "../../../parser.js";
+import { discoverSources } from "../../../project.js";
+import { sourceDirectory } from "../../../brand.js";
+
+/** Read a local file or download a remote sprite archive. */
+export async function readInputBytes(source, cwd = process.cwd()) {
+  if (/^https?:\/\//i.test(source)) {
+    const response = await fetch(source, {
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok)
+      throw new Error(
+        `Could not download ${source}: ${response.status} ${response.statusText}`,
+      );
+    return Buffer.from(await response.arrayBuffer());
+  }
+  return fs.readFileSync(path.resolve(cwd, source));
+}
+
+/** Every sprite declaration under `dir`, in source order. */
+export function spriteNames(dir) {
+  const sprites = [];
+  for (const file of discoverSources(dir)) {
+    const ast = parse(fs.readFileSync(file, "utf8"), file);
+    for (const sprite of ast.sprites) {
+      sprites.push({ name: sprite.name, file, partial: sprite.partial });
+    }
+  }
+  return sprites;
+}
+
+/** Group sprite declarations by name, tracking the base declaration. */
+export function spriteGroups(dir) {
+  const groups = new Map();
+  for (const entry of spriteNames(dir)) {
+    let group = groups.get(entry.name);
+    if (!group) {
+      group = {
+        name: entry.name,
+        file: entry.file,
+        files: [],
+        partial: true,
+      };
+      groups.set(entry.name, group);
+    }
+    group.files.push(entry.file);
+    if (!entry.partial) {
+      group.file = entry.file;
+      group.partial = false;
+    }
+  }
+  for (const group of groups.values())
+    group.files = [...new Set([group.file, ...group.files])];
+  return [...groups.values()];
+}
+
+/** Root directory that owns sources and assets. */
+export function spriteRoot(cwd, configPath) {
+  return configPath ? path.dirname(configPath) : cwd;
+}
+
+export function spriteSourceDir(rootDir, product) {
+  return path.join(rootDir, sourceDirectory(product));
+}

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

@@ -0,0 +1,29 @@
+import { Command } from "commander";
+import { defineCommand } from "../../define-command.js";
+import { spriteAddCommand } from "./add.js";
+import { spriteBuildCommand } from "./build.js";
+import { spriteListCommand } from "./list.js";
+import { spriteRemoveCommand } from "./remove.js";
+
+const SUBCOMMANDS = [
+  spriteAddCommand,
+  spriteBuildCommand,
+  spriteRemoveCommand,
+  spriteListCommand,
+];
+
+export function registerSprite(program, options) {
+  const sprite = new Command("sprite")
+    .description("Import, build, list, and remove sprites.")
+    .helpGroup("Extension Commands:");
+  sprite.copyInheritedSettings(program);
+  sprite.addHelpText(
+    "after",
+    `\nExamples:\n  fx sprite add robot.sprite3\n  fx sprite build Cat\n  fx sprite list --json\n`,
+  );
+  sprite.action(() => sprite.outputHelp());
+  program.addCommand(sprite);
+
+  for (const spec of SUBCOMMANDS) defineCommand(sprite, spec, options);
+  return sprite;
+}

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