@triflare/fx 1.0.3 → 2.0.0

package/src/cli/commands/dev.js

@@ -0,0 +1,179 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { build } from "../../build.js";
+import { sourceExtension } from "../../brand.js";
+import { packageSignature, resolvePackageConfig } from "../../package.js";
+import { packageProject } from "../../packager.js";
+import { startDevServer } from "../../dev.js";
+import { loadProjectState, resolveInput } from "../context.js";
+import { EXIT, UsageError, errorToJson } from "../errors.js";
+
+const EXTENSION = sourceExtension();
+
+export const devCommand = {
+  name: "dev",
+  group: "Core Commands:",
+  summary: "Serve a live build and reload on changes",
+  description: `Build and serve the project as HTML, rebuilding when sources or
+configuration change.`,
+  arguments: [`[input${EXTENSION}|dir]`],
+  options: [
+    { flags: "--host [host]", description: "Dev server host" },
+    { flags: "--lan", description: "Listen on all interfaces" },
+    { flags: "--port <port>", description: "Dev server port (default 3000)" },
+    {
+      flags: "--strict-port",
+      description: "Fail instead of choosing the next free port",
+    },
+  ],
+  examples: ["fx dev", "fx dev --lan --port 8080", "fx dev --json"],
+  jsonEvents: true,
+  async run({ args, options, cwd, reporter, prompts, product }) {
+    const target = resolveInput(args[0], cwd);
+    if (target.file && path.extname(target.file).toLowerCase() === ".pmp")
+      throw new UsageError(
+        "fx dev needs .tfx sources or a directory, not a .pmp archive",
+      );
+
+    let host = "127.0.0.1";
+    if (options.lan) host = "0.0.0.0";
+    else if (options.host === true) host = "0.0.0.0";
+    else if (typeof options.host === "string") host = options.host;
+
+    if (options.port === true) throw new UsageError("--port needs a number");
+    const port = options.port === undefined ? 3000 : Number(options.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+      throw new UsageError("--port must be an integer between 0 and 65535");
+
+    const initialState = await loadProjectState({
+      input: args[0],
+      cwd,
+      options,
+      reporter,
+      prompts,
+      includeExtensions: false,
+    });
+    const watchDir = initialState.configDir;
+
+    let lastSb3Hash = null;
+    let lastSignature = null;
+    let lastHtml = null;
+
+    const buildForDev = async () => {
+      const started = performance.now();
+      const state = await loadProjectState({
+        input: args[0],
+        cwd,
+        options,
+        reporter,
+        prompts,
+        includeExtensions: true,
+      });
+      const result = build({
+        ...state.target,
+        projectConfig: state.loaded.project,
+        fxConfig: state.loaded.fx,
+        catalog: state.catalog,
+        extensionUrls: state.extensionUrls,
+        useConfigFile: false,
+      });
+      for (const warning of result.warnings) reporter.warn(warning);
+
+      const pkg = resolvePackageConfig(state.loaded.package, {
+        baseDir: state.configDir,
+        projectName: result.config.name,
+      });
+      pkg.target = "html";
+
+      const signature = packageSignature(pkg);
+      const sb3Hash = crypto
+        .createHash("sha256")
+        .update(result.sb3)
+        .digest("hex");
+      if (
+        lastHtml != null &&
+        sb3Hash === lastSb3Hash &&
+        signature === lastSignature
+      )
+        return lastHtml;
+
+      const spinner = prompts.spinner();
+      spinner.start("Packaging project...");
+      let packaged;
+      try {
+        packaged = await packageProject({
+          sb3: result.sb3,
+          projectName: result.config.name,
+          packageConfig: pkg,
+          onProgress: (message) => spinner.message(String(message)),
+        });
+      } finally {
+        spinner.stop();
+      }
+      lastSb3Hash = sb3Hash;
+      lastSignature = signature;
+      lastHtml = packaged.html ?? packaged.data.toString("utf8");
+      reporter.event("build", {
+        durationMs: Math.round(performance.now() - started),
+        targets: result.project.targets.length,
+      });
+      return lastHtml;
+    };
+
+    const server = await startDevServer({
+      watchDir,
+      build: buildForDev,
+      host,
+      port,
+      strictPort: Boolean(options.strictPort),
+      log: {
+        error: (message) => {
+          reporter.error(message);
+          reporter.event("error", {
+            error: errorToJson(new Error(String(message))),
+          });
+        },
+        success: (message) => reporter.success(message),
+        warn: (message) => reporter.warn(message),
+        info: (message) => reporter.info(message),
+      },
+    });
+
+    const startup = {
+      url: server.url,
+      localUrls: server.localUrls,
+      networkUrls: server.networkUrls,
+      host,
+      port: server.port ?? port,
+    };
+    reporter.event("start", startup);
+
+    if (!reporter.json) {
+      reporter.text("");
+      reporter.text(
+        `  ${reporter.brand(product.name)} ${reporter.muted("dev")}`,
+      );
+      for (const url of server.localUrls)
+        reporter.detail("Local", url, { width: 9 });
+      for (const url of server.networkUrls)
+        reporter.detail("Network", url, { width: 9 });
+      reporter.text(`  ${reporter.muted("Press Ctrl+C to stop.")}`);
+    }
+
+    let stopping = false;
+    const shutdown = (signal) => {
+      if (stopping) return;
+      stopping = true;
+      server
+        .close()
+        .finally(() =>
+          process.exit(signal === "SIGINT" ? EXIT.INTERRUPTED : EXIT.OK),
+        );
+    };
+    process.once("SIGINT", () => shutdown("SIGINT"));
+    process.once("SIGTERM", () => shutdown("SIGTERM"));
+
+    await server.ready;
+    return startup;
+  },
+};

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