@triflare/fx 1.0.2 → 2.0.0

package/src/cli/commands/extension.js

@@ -0,0 +1,110 @@
+import path from "node:path";
+import { Command } from "commander";
+import {
+  addProjectExtension,
+  findConfigPath,
+  readProjectExtensions,
+  removeProjectExtension,
+} from "../../config.js";
+import { defineCommand } from "../define-command.js";
+import { UsageError } from "../errors.js";
+
+function requireConfigPath(cwd, product) {
+  const found = findConfigPath(cwd);
+  if (!found)
+    throw new UsageError("No project config found.", {
+      hint: `run "${product.command} init" first`,
+    });
+  return found;
+}
+
+function deprecation(reporter, product) {
+  reporter.warn(
+    `"${product.command} extension ..." is deprecated and will be removed in a future major version.`,
+  );
+  reporter.hint(
+    `run "${product.command} vendor migrate", then use "${product.command} vendor ..." commands`,
+  );
+}
+
+const extensionAddCommand = {
+  name: "add",
+  summary: "Add a legacy project.extensions entry",
+  arguments: ["<source>"],
+  options: [
+    {
+      flags: "--unsandboxed <id>",
+      description: "Allow an extension id to run unsandboxed",
+    },
+  ],
+  run({ args, options, cwd, reporter, product }) {
+    deprecation(reporter, product);
+    const source = args[0];
+    const configPath = requireConfigPath(cwd, product);
+    const unsandboxed =
+      typeof options.unsandboxed === "string" ? options.unsandboxed : null;
+    const result = addProjectExtension(configPath, source, { unsandboxed });
+    if (result.added)
+      reporter.success(`Added ${source} to ${path.basename(configPath)}`);
+    else
+      reporter.info(
+        `${source} is already listed in ${path.basename(configPath)}`,
+      );
+    if (unsandboxed && result.unsandboxedAdded)
+      reporter.success(`Allowed ${unsandboxed} to run unsandboxed`);
+    return { source, config: configPath, ...result };
+  },
+};
+
+const extensionRemoveCommand = {
+  name: "remove",
+  summary: "Remove a legacy project.extensions entry",
+  arguments: ["<source|id>"],
+  run({ args, cwd, reporter, product }) {
+    deprecation(reporter, product);
+    const target = args[0];
+    const configPath = requireConfigPath(cwd, product);
+    const result = removeProjectExtension(configPath, target);
+    if (result.extensions.length > 0)
+      reporter.success(
+        `Removed ${result.extensions.join(", ")} from ${path.basename(configPath)}`,
+      );
+    if (result.unsandboxedRemoved)
+      reporter.success(`Removed ${target} from the unsandboxed list`);
+    return { target, config: configPath, ...result };
+  },
+};
+
+const extensionListCommand = {
+  name: "list",
+  summary: "List legacy project.extensions entries",
+  run({ cwd, reporter, product }) {
+    deprecation(reporter, product);
+    const configPath = requireConfigPath(cwd, product);
+    const { extensions, unsandboxed } = readProjectExtensions(configPath);
+    reporter.heading(
+      `${path.basename(configPath)}: ${extensions.length} extension(s)`,
+    );
+    for (const entry of extensions) reporter.item(entry, "", { width: 0 });
+    reporter.detail("Unsandboxed", unsandboxed.join(", ") || "(none)", {
+      width: 12,
+    });
+    return { extensions, unsandboxed };
+  },
+};
+
+export function registerExtension(program, options) {
+  const extension = new Command("extension")
+    .description("Deprecated legacy project.extensions commands.")
+    .helpGroup("Legacy Commands:");
+  extension.copyInheritedSettings(program);
+  extension.action(() => extension.outputHelp());
+  program.addCommand(extension, { hidden: true });
+  for (const spec of [
+    extensionAddCommand,
+    extensionRemoveCommand,
+    extensionListCommand,
+  ])
+    defineCommand(extension, spec, options);
+  return extension;
+}

package/src/cli/commands/index.js

@@ -0,0 +1,39 @@
+import { completeCommand, completionCommand } from "./completion.js";
+import { buildCommand } from "./build.js";
+import { catalogCommand } from "./catalog.js";
+import { checkCommand } from "./check.js";
+import { decompileCommand } from "./decompile.js";
+import { devCommand } from "./dev.js";
+import { registerExtension } from "./extension.js";
+import { initCommand } from "./init.js";
+import { packageCommand } from "./package.js";
+import { registerSprite } from "./sprite/index.js";
+import { registerVendor } from "./vendor/index.js";
+import { defineCommand } from "../define-command.js";
+
+const TOP_LEVEL = [
+  buildCommand,
+  devCommand,
+  packageCommand,
+  decompileCommand,
+  checkCommand,
+  catalogCommand,
+  initCommand,
+  completionCommand,
+];
+
+/**
+ * Register every command on the root program.
+ *
+ * @param {import("commander").Command} program
+ * @param {{state: object, product: object}} options
+ */
+export function registerCommands(program, options) {
+  program.commandsGroup("Core Commands:");
+  for (const spec of TOP_LEVEL) defineCommand(program, spec, options);
+  registerVendor(program, options);
+  registerSprite(program, options);
+  defineCommand(program, completeCommand, options);
+  registerExtension(program, options);
+  return program;
+}

package/src/cli/commands/init.js

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import path from "node:path";
+import { normalizePackageTarget } from "../../config.js";
+import { UsageError } from "../errors.js";
+import {
+  initFiles,
+  STAGE_SIZES,
+  TARGETS,
+  TEMPLATES,
+} from "../templates/index.js";
+
+const TEMPLATE_VALUES = new Set(TEMPLATES.map((entry) => entry.value));
+const TARGET_VALUES = new Set(TARGETS.map((entry) => entry.value));
+
+function parseSize(value) {
+  const match = /^(\d+)x(\d+)$/i.exec(String(value).trim());
+  if (!match)
+    throw new UsageError(
+      `--size must look like 480x360, received ${JSON.stringify(value)}`,
+    );
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+function sizeValue(width, height) {
+  return `${width}x${height}`;
+}
+
+export const initCommand = {
+  name: "init",
+  aliases: ["i"],
+  group: "Core Commands:",
+  summary: "Create a new project",
+  description: `Scaffold a project config, a source file, and optional starter
+assets. On a terminal this opens a short wizard; use --yes for defaults.`,
+  arguments: ["[dir]"],
+  options: [
+    { flags: "--name <name>", description: "Project name" },
+    {
+      flags: "--template <template>",
+      description: "Template: cat, empty, or blank",
+    },
+    {
+      flags: "--target <target>",
+      description: "Package target: none, html, or zip",
+    },
+    {
+      flags: "--size <WxH>",
+      description: "Stage size (default 480x360)",
+    },
+    { flags: "--force", description: "Overwrite existing files" },
+  ],
+  examples: [
+    "fx init",
+    "fx init examples/demo --yes",
+    "fx init --template blank --target zip",
+  ],
+  async run({ args, options, cwd, reporter, prompts, product, yes }) {
+    const directory = path.resolve(cwd, args[0] || ".");
+    const defaultName = `My ${product.name} Project`;
+    const interactive = prompts.enabled && !yes;
+
+    if (interactive) prompts.intro("Create a new project");
+
+    const name =
+      options.name ??
+      (interactive
+        ? await prompts.text({
+            message: "Project name",
+            defaultValue: defaultName,
+          })
+        : defaultName);
+
+    let template = options.template ?? "cat";
+    if (!TEMPLATE_VALUES.has(template))
+      throw new UsageError(
+        `--template must be one of: ${[...TEMPLATE_VALUES].join(", ")}`,
+      );
+    if (interactive && options.template === undefined)
+      template = await prompts.select({
+        message: "Template",
+        options: TEMPLATES,
+        initialValue: template,
+      });
+
+    let size = options.size ?? "480x360";
+    if (interactive && options.size === undefined)
+      size = await prompts.select({
+        message: "Stage size",
+        options: STAGE_SIZES,
+        initialValue: "480x360",
+      });
+    const { width, height } = parseSize(size);
+
+    let target = options.target ?? "html";
+    if (!TARGET_VALUES.has(target)) {
+      try {
+        target = normalizePackageTarget(target);
+      } catch {
+        throw new UsageError(
+          `--target must be one of: ${[...TARGET_VALUES].join(", ")}`,
+        );
+      }
+    }
+    if (interactive && options.target === undefined)
+      target = await prompts.select({
+        message: "Package target",
+        options: TARGETS,
+        initialValue: target,
+      });
+
+    const files = initFiles({
+      product,
+      name,
+      template,
+      width,
+      height,
+      target,
+    });
+    const conflicts = Object.keys(files).filter((relative) =>
+      fs.existsSync(path.join(directory, relative)),
+    );
+
+    let force = Boolean(options.force);
+    if (conflicts.length > 0 && !force) {
+      if (interactive) {
+        const overwrite = await prompts.confirm({
+          message: `Overwrite ${conflicts.length} existing file(s)?`,
+          initialValue: false,
+        });
+        force = Boolean(overwrite);
+      }
+      if (!force)
+        reporter.warn(
+          `Skipping ${conflicts.length} existing file(s); pass --force to overwrite`,
+        );
+    }
+
+    const written = [];
+    for (const relative of Object.keys(files).sort()) {
+      const destination = path.join(directory, relative);
+      if (fs.existsSync(destination) && !force) {
+        written.push({ path: relative, status: "skipped" });
+        continue;
+      }
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.writeFileSync(destination, files[relative]);
+      written.push({ path: relative, status: "written" });
+      reporter.bullet(relative);
+    }
+
+    const count = written.filter((entry) => entry.status === "written").length;
+    reporter.success(
+      `Created ${count} file(s) in ${path.relative(cwd, directory) || "."}`,
+    );
+    if (interactive)
+      prompts.outro(
+        `Run "${product.command} build" or "${product.command} dev" next.`,
+      );
+
+    return {
+      directory,
+      name,
+      template,
+      target,
+      size: sizeValue(width, height),
+      files: written,
+    };
+  },
+};

package/src/cli/commands/package.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+import { build } from "../../build.js";
+import { normalizePackageTarget } from "../../config.js";
+import { packageProject } from "../../packager.js";
+import {
+  extractArchive,
+  packageOutputPath,
+  resolvePackageConfig,
+} from "../../package.js";
+import { loadProjectState } from "../context.js";
+import { UsageError } from "../errors.js";
+import { formatBytes, formatDuration } from "../format.js";
+
+function isArchive(file) {
+  return path.extname(file).toLowerCase() === ".pmp";
+}
+
+export const packageCommand = {
+  name: "package",
+  aliases: ["p", "pack"],
+  group: "Core Commands:",
+  summary: "Package into HTML, ZIP, or a desktop build",
+  description: `Package a source, project archive, or directory into HTML, a ZIP
+archive, or a desktop build (Windows/macOS/Linux use Electron).`,
+  arguments: ["[input.tfx|input.pmp|dir]"],
+  options: [
+    { flags: "-o, --output <file>", description: "Output file or directory" },
+    { flags: "--target <target>", description: "Packaging target" },
+    { flags: "--extract", description: "Extract a packaged archive" },
+  ],
+  examples: [
+    "fx package",
+    "fx package --target html",
+    "fx package build/game.pmp --target windows --extract",
+  ],
+  async run({ args, options, cwd, reporter, prompts }) {
+    const started = performance.now();
+    const input = args[0];
+    const archiveInput = input ? isArchive(path.resolve(cwd, input)) : false;
+    const state = await loadProjectState({
+      input,
+      cwd,
+      options,
+      reporter,
+      prompts,
+      includeExtensions: !archiveInput,
+    });
+    const { target, loaded, searchDir } = state;
+
+    let sb3;
+    let projectName;
+    if (target.file && isArchive(target.file)) {
+      sb3 = fs.readFileSync(target.file);
+      projectName = path.basename(target.file, path.extname(target.file));
+    } else {
+      const result = build({
+        ...target,
+        projectConfig: loaded.project,
+        fxConfig: loaded.fx,
+        catalog: state.catalog,
+        extensionUrls: state.extensionUrls,
+        useConfigFile: false,
+      });
+      for (const warning of result.warnings) reporter.warn(warning);
+      sb3 = result.sb3;
+      projectName = result.config.name;
+    }
+
+    const baseDir = loaded.path ? path.dirname(loaded.path) : searchDir;
+    const pkg = resolvePackageConfig(loaded.package, {
+      baseDir,
+      projectName,
+    });
+
+    if (typeof options.target === "string")
+      pkg.target = normalizePackageTarget(options.target);
+    if (typeof options.output === "string")
+      pkg.output = path.resolve(cwd, options.output);
+    const extract = Boolean(options.extract) || pkg.extract;
+    if (extract && pkg.target === "html")
+      throw new UsageError("--extract only applies to zip and desktop targets");
+
+    const output = packageOutputPath({
+      target: pkg.target,
+      output: pkg.output,
+      name: pkg.name || projectName,
+      dir: baseDir,
+    });
+
+    const spinner = prompts.spinner();
+    spinner.start("Packaging project...");
+    let result;
+    try {
+      result = await packageProject({
+        sb3,
+        projectName,
+        packageConfig: pkg,
+        onProgress: (message) => spinner.message(String(message)),
+      });
+    } finally {
+      spinner.stop();
+    }
+
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(output, result.data);
+    const durationMs = Math.round(performance.now() - started);
+
+    reporter.success(`Packaged ${output}`);
+    reporter.text("");
+    reporter.detail("Target", result.target);
+    reporter.detail("Type", result.type);
+    reporter.detail("Size", formatBytes(result.data.length));
+    reporter.detail("Time", formatDuration(durationMs));
+
+    let extracted = null;
+    if (extract) {
+      const extension = path.extname(output);
+      const extractDir = path.join(
+        path.dirname(output),
+        path.basename(output, extension),
+      );
+      const files = await extractArchive(result.data, extractDir);
+      extracted = { directory: extractDir, files };
+      reporter.success(`Extracted ${files.length} file(s) to ${extractDir}`);
+    }
+
+    return {
+      output,
+      target: result.target,
+      type: result.type,
+      size: result.data.length,
+      extracted,
+      durationMs,
+    };
+  },
+};

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