@triflare/fx 1.0.3 → 2.1.0-beta.1

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

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/feature.js

@@ -0,0 +1,114 @@
+import path from "node:path";
+import {
+  disableFeature,
+  enableFeature,
+  updateFeature,
+} from "../../features.js";
+import { loadVendorConfig, requireConfigPath } from "./vendor/helpers.js";
+import { UsageError } from "../errors.js";
+
+const ACTIONS = ["enable", "disable", "update"];
+
+export const featureCommand = {
+  name: "feature",
+  group: "Core Commands:",
+  summary: "Install, update or remove a built-in language feature",
+  description: `Features are extension-backed language additions. "enable" copies the\nfeature's file into the project and records it under "features:" in fx.yml;\n"update" replaces that copy with the one bundled in this Fx version; and\n"disable" removes both. The file is committed, so Fx upgrades never change it.`,
+  arguments: ["<name>", "<action>"],
+  options: [
+    {
+      flags: "--force",
+      description: "Replace an installed copy that was edited (enable)",
+    },
+    { flags: "--dry-run", description: "Preview update without writing files" },
+  ],
+  examples: [
+    "fx feature temporaryvariables enable",
+    "fx feature temporaryvariables update --dry-run",
+    "fx feature temporaryvariables disable",
+  ],
+  async run({ args, options, cwd, reporter, prompts, yes, product }) {
+    const [name, action] = args;
+    if (!ACTIONS.includes(action))
+      throw new UsageError(
+        `Unknown feature action ${JSON.stringify(action)} for ${JSON.stringify(name)}.`,
+        { hint: `use one of: ${ACTIONS.join(", ")}` },
+      );
+
+    const configPath = requireConfigPath(cwd, product);
+    const configDir = path.dirname(configPath);
+    if (action === "enable") {
+      const loaded = loadVendorConfig(configPath);
+      const result = enableFeature({
+        configPath,
+        configDir,
+        name,
+        vendorDir: loaded.vendorDir,
+        force: Boolean(options.force),
+      });
+      if (result.changed)
+        reporter.success(`${result.feature.title} enabled (${result.file})`);
+      else reporter.info(`${result.feature.title} is already installed`);
+      if (result.configChanged)
+        reporter.info(`Recorded the feature in ${path.basename(configPath)}`);
+      return {
+        feature: result.name,
+        action,
+        file: result.file,
+        changed: result.changed,
+      };
+    }
+
+    if (action === "disable") {
+      await prompts.confirmDestructive({
+        message: `Disable ${name} and delete its installed file?`,
+        yes,
+      });
+      const result = disableFeature({ configPath, configDir, name });
+      if (result.fileRemoved)
+        reporter.success(
+          `Disabled ${result.feature.title} (${result.file}) and deleted its copy`,
+        );
+      else
+        reporter.success(`Disabled ${result.feature.title} (${result.file})`);
+      if (result.filePreserved)
+        reporter.info(
+          `Kept ${result.file}: it is not the copy Fx installs, so it may be user-owned`,
+        );
+      return {
+        feature: result.name,
+        action,
+        file: result.file,
+        fileRemoved: result.fileRemoved,
+        filePreserved: result.filePreserved,
+      };
+    }
+
+    const result = updateFeature({
+      configPath,
+      configDir,
+      name,
+      dryRun: Boolean(options.dryRun),
+    });
+    if (!result.changed) {
+      reporter.info(`${result.feature.title} is already up to date`);
+      return {
+        feature: result.name,
+        action,
+        file: result.file,
+        changed: false,
+      };
+    }
+    reporter.text(result.diff);
+    if (result.dryRun)
+      reporter.info(`Dry run: ${result.file} would be replaced`);
+    else reporter.success(`Updated ${result.feature.title} (${result.file})`);
+    return {
+      feature: result.name,
+      action,
+      file: result.file,
+      changed: true,
+      dryRun: result.dryRun,
+    };
+  },
+};