@triflare/fx 1.0.2 → 2.0.0

package/src/cli/commands/build.js

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+import { build } from "../../build.js";
+import { outputDirectory, sourceExtension } from "../../brand.js";
+import { slugify } from "../../package.js";
+import { loadProjectState } from "../context.js";
+import { formatDuration } from "../format.js";
+
+const EXTENSION = sourceExtension();
+
+export const buildCommand = {
+  name: "build",
+  aliases: ["b"],
+  group: "Core Commands:",
+  summary: "Compile sources into a .pmp",
+  description: `Compile a source file, or every ${EXTENSION} file in a directory
+(defaults to the working directory), into one .pmp archive.`,
+  arguments: [`[input${EXTENSION}|dir]`],
+  options: [{ flags: "-o, --output <file>", description: "Output .pmp path" }],
+  examples: [
+    "fx build",
+    "fx build src/main.tfx -o build/game.pmp",
+    "fx build examples/player --no-config",
+  ],
+  async run({ args, options, cwd, reporter, prompts }) {
+    const started = performance.now();
+    const state = await loadProjectState({
+      input: args[0],
+      cwd,
+      options,
+      reporter,
+      prompts,
+    });
+    const { target, loaded, catalog, extensionUrls } = state;
+
+    const result = build({
+      ...target,
+      projectConfig: loaded.project,
+      fxConfig: loaded.fx,
+      catalog,
+      extensionUrls,
+      useConfigFile: false,
+    });
+    for (const warning of result.warnings) reporter.warn(warning);
+
+    const explicit = options.output;
+    let output;
+    if (explicit) {
+      output = path.resolve(cwd, explicit);
+    } else if (target.file) {
+      output = target.file.toLowerCase().endsWith(EXTENSION.toLowerCase())
+        ? `${target.file.slice(0, -EXTENSION.length)}.pmp`
+        : `${target.file}.pmp`;
+    } else {
+      output = path.join(
+        target.dir,
+        outputDirectory(),
+        `${slugify(result.config.name || path.basename(target.dir))}.pmp`,
+      );
+    }
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(output, result.sb3);
+
+    const blockCount = result.project.targets.reduce(
+      (sum, item) => sum + Object.keys(item.blocks).length,
+      0,
+    );
+    const durationMs = Math.round(performance.now() - started);
+
+    reporter.success(`Built ${output}`);
+    reporter.text("");
+    reporter.detail("Sources", `${result.files.length} file(s)`);
+    reporter.detail("Targets", result.project.targets.length);
+    reporter.detail("Blocks", blockCount);
+    reporter.detail("Assets", result.assets.size);
+    reporter.detail(
+      "Extensions",
+      result.project.extensions.join(", ") || "(none)",
+    );
+    reporter.detail("Time", formatDuration(durationMs));
+    if (state.unsandboxed.length)
+      reporter.detail(
+        "Unsandboxed",
+        `${state.unsandboxed.join(", ")} (must be allowed in the editor)`,
+      );
+
+    return {
+      output,
+      sources: result.files,
+      targets: result.project.targets.length,
+      blocks: blockCount,
+      assets: result.assets.size,
+      extensions: result.project.extensions,
+      unsandboxed: state.unsandboxed,
+      durationMs,
+    };
+  },
+};

package/src/cli/commands/catalog.js

@@ -0,0 +1,42 @@
+import { CATALOG, blockNames } from "../../catalog.js";
+import { loadProjectState } from "../context.js";
+
+export const catalogCommand = {
+  name: "catalog",
+  aliases: ["l", "blocks"],
+  group: "Core Commands:",
+  summary: "List available blocks",
+  description: `List block names, including blocks from extensions configured in the
+project.`,
+  arguments: ["[dir]"],
+  examples: ["fx catalog", "fx catalog --json"],
+  async run({ args, cwd, options, reporter, product, prompts }) {
+    const state = await loadProjectState({
+      input: args[0],
+      cwd,
+      options,
+      reporter,
+      prompts,
+    });
+    const merged = { ...CATALOG, ...state.catalog };
+    const names = Object.keys(merged).sort();
+    const builtIn = blockNames().length;
+
+    reporter.heading(
+      `${product.name} catalog (${names.length} blocks` +
+        (names.length > builtIn
+          ? `, ${names.length - builtIn} from extensions`
+          : "") +
+        "):",
+    );
+    for (const name of names) {
+      const entry = merged[name];
+      reporter.item(name, `-> ${entry.opcode} [${entry.kind}]`, {
+        width: 32,
+        suffix: entry.extension ? `(ext ${entry.extension})` : "",
+      });
+    }
+
+    return merged;
+  },
+};

package/src/cli/commands/check.js

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import { parse } from "../../parser.js";
+import { discoverSources, mergePrograms } from "../../project.js";
+import { sourceExtension } from "../../brand.js";
+import { loadProjectState } from "../context.js";
+import { UsageError } from "../errors.js";
+
+const EXTENSION = sourceExtension();
+
+export const checkCommand = {
+  name: "check",
+  aliases: ["c"],
+  group: "Core Commands:",
+  summary: "Parse sources and report errors",
+  description: `Parse a file, or every ${EXTENSION} file in a directory, without
+building an archive.`,
+  arguments: [`[input${EXTENSION}|dir]`],
+  examples: ["fx check", "fx check src/main.tfx"],
+  async run({ args, cwd, options, reporter }) {
+    const state = await loadProjectState({
+      input: args[0],
+      cwd,
+      options,
+      reporter,
+      includeExtensions: false,
+      migrateLegacy: false,
+    });
+    const { target, loaded } = state;
+    const files = target.file ? [target.file] : discoverSources(target.dir);
+    if (files.length === 0)
+      throw new UsageError(`No ${EXTENSION} files found under ${target.dir}`);
+
+    const entries = files.map((file) => ({
+      ast: parse(fs.readFileSync(file, "utf8"), file),
+      file,
+    }));
+    mergePrograms(entries, {
+      partialSprites: loaded.fx?.partialSprites ?? false,
+    });
+
+    reporter.success(`Checked ${files.length} file(s): OK`);
+    return { files, ok: true };
+  },
+};

package/src/cli/commands/completion.js

@@ -0,0 +1,54 @@
+import { completionCandidates } from "../completion/index.js";
+import { bashCompletion } from "../completion/bash.js";
+import { fishCompletion } from "../completion/fish.js";
+import { zshCompletion } from "../completion/zsh.js";
+import { UsageError } from "../errors.js";
+
+const SHELLS = new Set(["bash", "zsh", "fish"]);
+
+export const completionCommand = {
+  name: "completion",
+  group: "Utility Commands:",
+  summary: "Print shell completion setup",
+  description: `Print a completion script for bash, zsh, or fish. Add the script
+to your shell profile, or source it directly.`,
+  arguments: ["<shell>"],
+  examples: [
+    "fx completion bash >> ~/.bashrc",
+    "fx completion zsh > ~/.zfunc/_fx",
+    "fx completion fish > ~/.config/fish/completions/fx.fish",
+  ],
+  run({ args, reporter, product }) {
+    const shell = args[0];
+    if (!SHELLS.has(shell))
+      throw new UsageError(
+        `completion requires one of: ${[...SHELLS].join(", ")}`,
+      );
+    const command = product.command;
+    const script =
+      shell === "bash"
+        ? bashCompletion(command)
+        : shell === "zsh"
+          ? zshCompletion(command)
+          : fishCompletion(command);
+    reporter.text(script.endsWith("\n") ? script.slice(0, -1) : script);
+    return { shell, script };
+  },
+};
+
+export const completeCommand = {
+  name: "__complete",
+  hidden: true,
+  summary: "Internal shell completion protocol",
+  arguments: ["[words...]"],
+  run({ args, command, reporter }) {
+    const words = args[0] == null ? [] : args[0];
+    const list = Array.isArray(words) ? words : [words];
+    const program = command.parent ?? command;
+    // The generated shell scripts pass their own name first as a marker.
+    const input = SHELLS.has(list[0]) ? list.slice(1) : list;
+    const candidates = completionCandidates(program, input);
+    if (candidates.length > 0) reporter.text(candidates.join("\n"));
+    return { candidates };
+  },
+};

package/src/cli/commands/decompile.js

@@ -0,0 +1,266 @@
+import fs from "node:fs";
+import path from "node:path";
+import { decompileProject } from "../../decompiler.js";
+import { unzipSync } from "../../sb3.js";
+import { addProjectExtension } from "../../config.js";
+import { configFilename, configFilenames } from "../../brand.js";
+import { loadExtensions, readExtensionDataUri } from "../../extensions.js";
+import { truncate } from "../format.js";
+import { UsageError } from "../errors.js";
+
+/**
+ * Recover the extensions a decompiled project references.
+ *
+ * An archive only remembers extension sources through `project.extensionURLs`:
+ * Fx stores local extension files there as data URIs, and PenguinMod projects
+ * keep plain URLs. Data URIs are written next to the output and referenced
+ * from the config file; URLs stay URLs.
+ */
+function restoreExtensions(project, outDir, { fetchRemote = false } = {}) {
+  const result = { entries: [], loadEntries: [], files: [], warnings: [] };
+  const urls = project && project.extensionURLs;
+  if (!urls || typeof urls !== "object") return result;
+
+  let extensionDir = null;
+  let extensionDirProblem = null;
+  const resolveExtensionDir = () => {
+    if (extensionDir || extensionDirProblem) return;
+    const dir = path.join(outDir, "extensions");
+    const existing = fs.lstatSync(dir, { throwIfNoEntry: false });
+    if (existing && !existing.isDirectory()) {
+      extensionDirProblem = existing.isSymbolicLink()
+        ? `"${dir}" is a symlink, so the extension would land outside the output directory`
+        : `"${dir}" is not a directory`;
+      return;
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const expected = path.join(fs.realpathSync(outDir), "extensions");
+    const actual = fs.realpathSync(dir);
+    if (actual !== expected) {
+      extensionDirProblem = `"${dir}" resolves to ${actual}, outside the output directory`;
+      return;
+    }
+    extensionDir = dir;
+  };
+
+  const used = new Set();
+  for (const [id, value] of Object.entries(urls)) {
+    const uri = typeof value === "string" ? value.trim() : "";
+    if (!uri) continue;
+    if (/^https?:\/\//i.test(uri)) {
+      result.entries.push(uri);
+      if (fetchRemote) result.loadEntries.push(uri);
+      else
+        result.warnings.push(
+          `extension ${id} points at a remote URL (${truncate(uri, 48)}); ` +
+            "not fetching it, so its blocks stay unsupported — pass " +
+            "--fetch-extensions to load it",
+        );
+      continue;
+    }
+    if (!/^data:/i.test(uri)) {
+      result.warnings.push(
+        `extension ${id} uses an unsupported URL (${truncate(uri, 48)}); ` +
+          `add it to ${configFilename()} by hand`,
+      );
+      continue;
+    }
+    const source = readExtensionDataUri(uri);
+    if (source == null) {
+      result.warnings.push(
+        `extension ${id} has an unreadable data URI; ` +
+          `add it to ${configFilename()} by hand`,
+      );
+      continue;
+    }
+    const keepEmbedded = (warning) => {
+      result.loadEntries.push(uri);
+      if (outDir) result.entries.push(uri);
+      result.warnings.push(warning);
+    };
+    if (!outDir) {
+      keepEmbedded(
+        `extension ${id} is embedded in the archive; pass -o to write it out ` +
+          `and reference it from ${configFilename()}`,
+      );
+      continue;
+    }
+    resolveExtensionDir();
+    if (extensionDirProblem) {
+      keepEmbedded(
+        `extension ${id} was not written: ${extensionDirProblem}; its blocks ` +
+          "still decompile and the config keeps its source, but the extension " +
+          "file is missing from the output",
+      );
+      continue;
+    }
+    const base = extensionFileStem(id);
+    let stem = base;
+    for (let suffix = 2; used.has(stem); suffix += 1)
+      stem = `${base}-${suffix}`;
+    used.add(stem);
+    const file = path.join(extensionDir, `${stem}.js`);
+    const relative = `extensions/${stem}.js`;
+    const existing = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (existing) {
+      if (existing.isFile() && fs.readFileSync(file, "utf8") === source) {
+        result.files.push(relative);
+        result.entries.push(relative);
+        result.loadEntries.push(file);
+      } else {
+        keepEmbedded(
+          `extension ${id} not written to ${relative}: ` +
+            (existing.isSymbolicLink()
+              ? "the path is a symlink"
+              : "a different file already exists") +
+            "; the config keeps the archive's copy, so delete or rename it to " +
+            "write the extension file",
+        );
+      }
+      continue;
+    }
+    try {
+      fs.writeFileSync(file, source, { flag: "wx" });
+    } catch (err) {
+      keepEmbedded(
+        `extension ${id} not written to ${relative}: ` +
+          (err.code === "EEXIST"
+            ? "the path appeared while decompiling"
+            : `${err.code || err.message}`) +
+          "; the config keeps the archive's copy, so delete or rename it to " +
+          "write the extension file",
+      );
+      continue;
+    }
+    result.files.push(relative);
+    result.entries.push(relative);
+    result.loadEntries.push(file);
+  }
+  return result;
+}
+
+/** Sanitize an extension id into a portable file name stem. */
+function extensionFileStem(id) {
+  return (
+    String(id)
+      .replace(/[^A-Za-z0-9._-]+/g, "-")
+      .replace(/^[.-]+|[.-]+$/g, "") || "extension"
+  );
+}
+
+function writeRestoredConfig(outDir, entries) {
+  if (entries.length === 0) return null;
+  const existing = configFilenames()
+    .map((name) => path.join(outDir, name))
+    .find((file) => fs.existsSync(file));
+  if (existing) {
+    let added = 0;
+    for (const entry of entries)
+      if (addProjectExtension(existing, entry).added) added += 1;
+    return { file: existing, added };
+  }
+  const file = path.join(outDir, configFilenames()[0]);
+  const lines = ["project:", "  extensions:"];
+  for (const entry of entries) lines.push(`    - ${JSON.stringify(entry)}`);
+  lines.push("");
+  fs.writeFileSync(file, lines.join("\n"));
+  return { file, added: entries.length };
+}
+
+export const decompileCommand = {
+  name: "decompile",
+  aliases: ["d"],
+  group: "Core Commands:",
+  summary: "Convert a .pmp back into source",
+  description: `Convert a .pmp archive back into Triflare Fx source, restoring
+extensions into the project config.`,
+  arguments: ["<input.pmp>"],
+  options: [
+    { flags: "-o, --output <file>", description: "Output source file" },
+    {
+      flags: "--assets <dir>",
+      description: "Extract project assets into <dir>",
+    },
+    {
+      flags: "--fetch-extensions",
+      description: "Load remote extensions while decompiling",
+    },
+  ],
+  examples: [
+    "fx decompile build/game.pmp -o src/main.tfx --assets assets",
+    "fx decompile build/game.pmp --fetch-extensions",
+  ],
+  async run({ args, options, cwd, reporter }) {
+    const input = path.resolve(cwd, args[0]);
+    const data = fs.readFileSync(input);
+    const files = unzipSync(data);
+    const projectJson = files.get("project.json");
+    if (!projectJson)
+      throw new UsageError("Not a Scratch project: missing project.json");
+    const project = JSON.parse(projectJson.toString("utf8"));
+
+    const output = options.output ? path.resolve(cwd, options.output) : null;
+    const outDir = output ? path.dirname(output) : null;
+    const restored = restoreExtensions(project, outDir, {
+      fetchRemote: Boolean(options.fetchExtensions),
+    });
+    for (const warning of restored.warnings) reporter.warn(warning);
+
+    let catalog = {};
+    if (restored.loadEntries.length > 0) {
+      const loaded = await loadExtensions(restored.loadEntries, {
+        baseDir: outDir || cwd,
+      });
+      catalog = loaded.catalog;
+      for (const warning of loaded.warnings) reporter.warn(warning);
+    }
+
+    const assetDir = options.assets ? path.resolve(cwd, options.assets) : null;
+    let assetPrefix = "";
+    if (assetDir) {
+      fs.mkdirSync(assetDir, { recursive: true });
+      const resolvedAssetDir = fs.realpathSync(assetDir);
+      for (const [name, buffer] of files) {
+        if (!/^[0-9a-f]{32}\.[a-z0-9]+(?![\s\S])/i.test(name)) continue;
+        const destination = path.resolve(resolvedAssetDir, name);
+        if (path.dirname(destination) !== resolvedAssetDir) continue;
+        if (
+          fs.lstatSync(destination, { throwIfNoEntry: false })?.isSymbolicLink()
+        )
+          continue;
+        fs.writeFileSync(destination, buffer);
+      }
+      const rel = path.relative(outDir || cwd, assetDir).replace(/\\/g, "/");
+      assetPrefix = rel ? `${rel}/` : "";
+    }
+
+    const source = decompileProject(project, { assetPrefix, catalog });
+
+    if (!output) {
+      reporter.text(source.endsWith("\n") ? source.slice(0, -1) : source);
+      return {
+        source,
+        output: null,
+        extensions: restored.files,
+        warnings: restored.warnings,
+      };
+    }
+
+    fs.writeFileSync(output, source);
+    const config = writeRestoredConfig(outDir, restored.entries);
+    reporter.success(`Decompiled ${args[0]} -> ${options.output}`);
+    if (config)
+      reporter.success(
+        `Restored ${config.added} extension(s) -> ${
+          path.relative(cwd, config.file) || config.file
+        }`,
+      );
+
+    return {
+      output,
+      assets: assetDir ? path.resolve(assetDir) : null,
+      extensions: restored.files,
+      config: config ? { file: config.file, added: config.added } : null,
+    };
+  },
+};

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