@triflare/fx 1.0.3 → 2.1.0-beta.1

package/src/decompiler.js

@@ -49,6 +49,8 @@ const LIST_OPCODE_METHOD = {
   data_listcontainsitem: { method: "contains", inputs: ["ITEM"] },
 };
 
+const SAFE_TEMP_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
 function escapeString(value) {
   return String(value)
     .replace(/\\/g, "\\\\")
@@ -172,6 +174,14 @@ class Decompiler {
     }
     if (block.opcode === "data_variable") return block.fields.VARIABLE[0];
     if (block.opcode === "data_listcontents") return block.fields.LIST[0];
+    if (block.opcode === "fxTempVars_getThreadVariable") {
+      const name = this.tempVarName(block);
+      if (name != null && SAFE_TEMP_NAME.test(name)) return `$${name}`;
+    }
+    if (block.opcode === "fxTempVars_getRuntimeVariable") {
+      const name = this.tempVarName(block);
+      if (name != null && SAFE_TEMP_NAME.test(name)) return `$$${name}`;
+    }
     if (
       Object.prototype.hasOwnProperty.call(LIST_OPCODE_METHOD, block.opcode)
     ) {
@@ -254,6 +264,27 @@ class Decompiler {
     return lines.filter(Boolean).join("\n");
   }
 
+  /** Literal name stored in a temporary-variable block's VAR input. */
+  tempVarName(block) {
+    const raw = (block.inputs || {}).VAR;
+    const inner = Array.isArray(raw) ? raw[1] : null;
+    if (!Array.isArray(inner) || ![4, 5, 6, 7, 8, 9, 10, 11].includes(inner[0]))
+      return null;
+    return inner[1] == null ? null : String(inner[1]);
+  }
+
+  /** Render set/change on a temporary variable, with sugar when the name is safe. */
+  renderTempVarAssign(block, pad, prefix, op, catalogName) {
+    const name = this.tempVarName(block);
+    const value = this.renderExpression(
+      block.inputs.STRING ?? block.inputs.NUM,
+    );
+    if (name != null && SAFE_TEMP_NAME.test(name))
+      return `${pad}${prefix}${name} ${op} ${value};`;
+    const input = this.renderExpression(block.inputs.VAR);
+    return `${pad}tempvars.${catalogName}(${input}, ${value});`;
+  }
+
   renderStatement(block, indent) {
     const pad = "    ".repeat(indent);
     const sub = (firstId) => {
@@ -289,6 +320,20 @@ class Decompiler {
         return `${pad}${this.renderProcedureCall(block)};`;
       case "control_stop":
         return `${pad}control.stop("${block.fields.STOP_OPTION[0]}");`;
+      case "fxTempVars_setThreadVariable":
+        return this.renderTempVarAssign(block, pad, "$", "=", "setThread");
+      case "fxTempVars_changeThreadVariable":
+        return this.renderTempVarAssign(block, pad, "$", "+=", "changeThread");
+      case "fxTempVars_setRuntimeVariable":
+        return this.renderTempVarAssign(block, pad, "$$", "=", "setRuntime");
+      case "fxTempVars_changeRuntimeVariable":
+        return this.renderTempVarAssign(
+          block,
+          pad,
+          "$$",
+          "+=",
+          "changeRuntime",
+        );
       default: {
         if (
           Object.prototype.hasOwnProperty.call(LIST_OPCODE_METHOD, block.opcode)

package/src/extensions.js

@@ -757,6 +757,7 @@ const BASE64_PAYLOAD = /^[A-Za-z0-9+/=\s]*$/;
  * @param {string} source
  * @returns {string}
  */
+/** Encode extension source as a self-contained JavaScript data URI. */
 export function extensionDataUri(source) {
   const base64 = Buffer.from(String(source), "utf8").toString("base64");
   return `data:text/javascript;base64,${base64}`;
@@ -782,8 +783,13 @@ export function readExtensionDataUri(uri) {
   }
 }
 
-/** Resolve a config entry to source text. */
-async function resolveSource(entry, baseDir, fetchImpl) {
+/**
+ * Resolve a config entry to source text and the original bytes.
+ *
+ * The raw buffer is retained so vendoring can lock exactly what the server
+ * returned, even when the text decoder strips a byte-order mark.
+ */
+export async function resolveSource(entry, baseDir, fetchImpl) {
   const value = String(entry);
   if (/^data:/i.test(value)) {
     const source = readExtensionDataUri(value);
@@ -791,7 +797,13 @@ async function resolveSource(entry, baseDir, fetchImpl) {
       throw new Error(
         "unsupported data URI; expected base64 or percent-encoded JavaScript",
       );
-    return { source, remote: false, dataUri: true, url: value };
+    return {
+      source,
+      buffer: Buffer.from(source, "utf8"),
+      remote: false,
+      dataUri: true,
+      url: value,
+    };
   }
   if (/^https?:\/\//i.test(value)) {
     const fetchFn = fetchImpl || globalThis.fetch;
@@ -800,13 +812,24 @@ async function resolveSource(entry, baseDir, fetchImpl) {
     const response = await fetchFn(value);
     if (!response.ok)
       throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
-    return { source: await response.text(), remote: true, url: value };
+    const buffer =
+      typeof response.arrayBuffer === "function"
+        ? Buffer.from(await response.arrayBuffer())
+        : Buffer.from(await response.text(), "utf8");
+    return {
+      source: buffer.toString("utf8").replace(/^\uFEFF/, ""),
+      buffer,
+      remote: true,
+      url: value,
+    };
   }
   const resolved = path.isAbsolute(value)
     ? value
     : path.resolve(baseDir, value);
+  const buffer = fs.readFileSync(resolved);
   return {
-    source: fs.readFileSync(resolved, "utf8"),
+    source: buffer.toString("utf8"),
+    buffer,
     remote: false,
     url: value,
     file: resolved,
@@ -850,19 +873,39 @@ async function evaluateExtensionAny(source, filename) {
   }
 }
 
+/**
+ * Inspect extension source without running it in the Node.js process.
+ * Useful to propose an extension id while vendoring or migrating.
+ * @param {string} source
+ * @param {string} [filename]
+ * @returns {Promise<{infos: object[], unsandboxed: boolean}>}
+ */
+export async function inspectExtension(source, filename = "extension") {
+  return evaluateExtensionAny(source, filename);
+}
+
 /**
  * Load a list of extension references.
  *
  * @param {Array<string>} list Paths, `http(s)://` URLs or `data:` URIs.
- * @param {{baseDir?: string, fetchImpl?: typeof fetch, expectUnsandboxed?: string|string[]}} [options]
+ * @param {{baseDir?: string, fetchImpl?: typeof fetch, expectUnsandboxed?: string|string[], reportUnmatchedUnsandboxed?: boolean}} [options]
  *   `expectUnsandboxed` acknowledges extensions that are known to require
- *   unsandboxed mode, silencing the warning for them.
- * @returns {Promise<{catalog: Record<string, object>, extensionUrls: Record<string, string>, warnings: string[], ids: string[], unsandboxed: string[]}>}
+ *   unsandboxed mode, silencing the warning for them. Set
+ *   `reportUnmatchedUnsandboxed` to false when a caller combines declarations
+ *   from several loaders and reports unmatched names itself.
+ * @returns {Promise<{catalog: Record<string, object>, extensionUrls: Record<string, string>, warnings: string[], ids: string[], unsandboxed: string[], matchedUnsandboxed: string[], unnecessaryUnsandboxed: string[]}>}
  *   `unsandboxed` holds the ids of extensions that only load unsandboxed.
+ *   `matchedUnsandboxed` and `unnecessaryUnsandboxed` let callers combine
+ *   declarations across multiple loaders without double-reporting them.
  */
 export async function loadExtensions(
   list,
-  { baseDir = process.cwd(), fetchImpl, expectUnsandboxed = [] } = {},
+  {
+    baseDir = process.cwd(),
+    fetchImpl,
+    expectUnsandboxed = [],
+    reportUnmatchedUnsandboxed = true,
+  } = {},
 ) {
   const catalog = {};
   const extensionUrls = {};
@@ -941,17 +984,27 @@ export async function loadExtensions(
         "project.unsandboxed in fx.yml once you trust it)",
     );
   }
-  for (const name of declared) {
-    if (declaredNotNeeded.has(name)) {
-      warnings.push(
-        `project.unsandboxed entry "${name}" loads in the sandbox; remove it from fx.yml`,
-      );
-    } else if (!declaredSeen.has(name)) {
-      warnings.push(
-        `project.unsandboxed entry "${name}" does not match any loaded extension`,
-      );
+  if (reportUnmatchedUnsandboxed) {
+    for (const name of declared) {
+      if (declaredNotNeeded.has(name)) {
+        warnings.push(
+          `project.unsandboxed entry "${name}" loads in the sandbox; remove it from fx.yml`,
+        );
+      } else if (!declaredSeen.has(name)) {
+        warnings.push(
+          `project.unsandboxed entry "${name}" does not match any loaded extension`,
+        );
+      }
     }
   }
 
-  return { catalog, extensionUrls, warnings, ids, unsandboxed };
+  return {
+    catalog,
+    extensionUrls,
+    warnings,
+    ids,
+    unsandboxed,
+    matchedUnsandboxed: [...declaredSeen],
+    unnecessaryUnsandboxed: [...declaredNotNeeded],
+  };
 }

package/src/features.js

@@ -0,0 +1,339 @@
+/**
+ * Built-in, project-local features.
+ *
+ * `fx feature <name> enable` copies a feature's extension source into the
+ * project and records that file under `features:` in `fx.yml`. Builds load the
+ * committed file, so an Fx upgrade never changes a project's feature code, and
+ * the project keeps working offline (and in Fx versions that predate the
+ * feature system) because the extension is an ordinary JavaScript file.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseConfig } from "./config.js";
+import { addFeatureEntry, removeFeatureEntry } from "./config-edit.js";
+import { loadExtensions } from "./extensions.js";
+import { formatDiff } from "./vendor.js";
+
+export class FeatureError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "FeatureError";
+  }
+}
+
+/**
+ * Feature registry. `source` points at the fork that ships with Fx; `enable`
+ * copies it into the project so the project owns (and pins) the bytes.
+ */
+export const FEATURES = {
+  temporaryvariables: {
+    name: "temporaryvariables",
+    title: "Temporary Variables",
+    summary: "Disposable per-thread and per-run variables.",
+    extensionId: "fxTempVars",
+    filename: "fx-tempvars.js",
+    source: fileURLToPath(
+      new URL("../vendor/tempvars/fx-tempvars.js", import.meta.url),
+    ),
+  },
+};
+
+/** List feature names for help and error messages. */
+export function featureNames() {
+  return Object.keys(FEATURES).sort();
+}
+
+/** Resolve one feature by name. */
+export function getFeature(name) {
+  const key = String(name ?? "");
+  const feature = FEATURES[key];
+  if (!feature)
+    throw new FeatureError(
+      `Unknown feature ${JSON.stringify(key)}. Available features: ${featureNames().join(", ")}.`,
+    );
+  return feature;
+}
+
+/** Absolute path of the extension source Fx ships for a feature. */
+export function featureSourcePath(name) {
+  return getFeature(name).source;
+}
+
+/** Read the packaged feature source. */
+export function readFeatureSource(name) {
+  const feature = getFeature(name);
+  try {
+    return fs.readFileSync(feature.source);
+  } catch (error) {
+    throw new FeatureError(
+      `Could not read the bundled source for ${feature.title}: ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+function posix(value) {
+  return String(value).replace(/\\/g, "/");
+}
+
+/** Relative, project-facing path with a leading `./`. */
+function relativeProjectPath(configDir, file) {
+  const rel = posix(path.relative(configDir, file));
+  if (rel === "") return ".";
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+/** True when `target` is strictly below `base`. Both paths are lexical. */
+function isBelow(base, target) {
+  const rel = path.relative(base, target);
+  return (
+    rel !== "" &&
+    rel !== ".." &&
+    !rel.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(rel)
+  );
+}
+
+/**
+ * Refuse paths that escape the project directory, including through a
+ * symlinked ancestor. The longest existing prefix is resolved, so a target
+ * that does not exist yet is checked against where it would be created.
+ */
+function assertInside(configDir, target, label) {
+  const base = path.resolve(configDir);
+  const absolute = path.resolve(target);
+  const message = `Refusing to use ${label} ${JSON.stringify(absolute)}: it must be inside the project directory`;
+  if (!isBelow(base, absolute)) throw new FeatureError(message);
+
+  let probe = absolute;
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+
+  let baseReal;
+  let probeReal;
+  try {
+    baseReal = fs.realpathSync(base);
+    probeReal = fs.realpathSync(probe);
+  } catch (error) {
+    throw new FeatureError(message, { cause: error });
+  }
+  const rel = path.relative(baseReal, probeReal);
+  if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+    throw new FeatureError(
+      `${message} (it resolves outside the project through a symlink)`,
+    );
+  return absolute;
+}
+
+/** Replace a file atomically so an interrupted write cannot truncate it. */
+function writeFileAtomic(file, data) {
+  const temp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  try {
+    fs.writeFileSync(temp, data, { flag: "wx" });
+    fs.renameSync(temp, file);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+/** Read the `features:` list from a config file. */
+function readFeatureEntries(configPath) {
+  return parseConfig(fs.readFileSync(configPath, "utf8")).features;
+}
+
+/**
+ * Install a feature into a project: copy the packaged extension to the vendor
+ * directory and record the file under `features:`.
+ *
+ * @param {object} options
+ * @param {string} options.configPath
+ * @param {string} options.configDir
+ * @param {string} options.name
+ * @param {string} [options.vendorDir]
+ * @param {boolean} [options.force] replace a modified copy
+ * @returns {{feature: object, name: string, file: string, path: string, changed: boolean, configChanged: boolean}}
+ */
+export function enableFeature({
+  configPath,
+  configDir,
+  name,
+  vendorDir = "extensions",
+  force = false,
+} = {}) {
+  const feature = getFeature(name);
+  const dir = assertInside(
+    configDir,
+    path.resolve(configDir, String(vendorDir || "extensions")),
+    "feature directory",
+  );
+  const target = path.join(dir, feature.filename);
+  const source = readFeatureSource(feature.name);
+  const existing = fs.existsSync(target) ? fs.readFileSync(target) : null;
+  const changed = !existing || !existing.equals(source);
+  if (existing && changed && !force)
+    throw new FeatureError(
+      `${feature.title} is already installed at ${relativeProjectPath(
+        configDir,
+        target,
+      )} with different contents. Run "fx feature ${feature.name} update" to replace it.`,
+    );
+
+  if (changed) {
+    fs.mkdirSync(dir, { recursive: true });
+    writeFileAtomic(target, source);
+  }
+  const file = relativeProjectPath(configDir, target);
+  const configured = readFeatureEntries(configPath).find(
+    (entry) => entry.name === feature.name,
+  );
+  const needsEntry = !configured || configured.file !== file;
+  if (needsEntry) addFeatureEntry(configPath, feature.name, file);
+  return {
+    feature,
+    name: feature.name,
+    file,
+    path: target,
+    changed,
+    configChanged: needsEntry,
+  };
+}
+
+/**
+ * Remove a feature from `fx.yml` and delete the copy Fx installed.
+ *
+ * A file is deleted only when its name and bytes match the packaged feature
+ * source that `enable`/`update` write. A hand-pointed or edited project file is
+ * user-owned and survives, even though its `features:` entry is removed.
+ */
+export function disableFeature({ configPath, configDir, name } = {}) {
+  const feature = getFeature(name);
+  const entry = readFeatureEntries(configPath).find(
+    (candidate) => candidate.name === feature.name,
+  );
+  if (!entry)
+    throw new FeatureError(
+      `${feature.title} is not enabled. Run "fx feature ${feature.name} enable" first.`,
+    );
+
+  const target = assertInside(
+    configDir,
+    path.resolve(configDir, entry.file),
+    "feature file",
+  );
+  const managedName = path.basename(target) === feature.filename;
+  const fileExists = managedName && fs.existsSync(target);
+  let installedByFx = false;
+  if (fileExists) {
+    try {
+      installedByFx = fs
+        .readFileSync(target)
+        .equals(readFeatureSource(feature.name));
+    } catch {
+      installedByFx = false;
+    }
+  }
+  removeFeatureEntry(configPath, feature.name);
+  if (installedByFx) fs.rmSync(target, { force: true });
+  return {
+    feature,
+    name: feature.name,
+    file: entry.file,
+    fileRemoved: installedByFx,
+    filePreserved: fileExists && !installedByFx,
+  };
+}
+
+/**
+ * Replace a project's feature copy with the one bundled in this Fx version.
+ * Nothing changes unless this command (or `enable --force`) runs.
+ */
+export function updateFeature({
+  configPath,
+  configDir,
+  name,
+  dryRun = false,
+} = {}) {
+  const feature = getFeature(name);
+  const entry = readFeatureEntries(configPath).find(
+    (candidate) => candidate.name === feature.name,
+  );
+  if (!entry)
+    throw new FeatureError(
+      `${feature.title} is not enabled. Run "fx feature ${feature.name} enable" first.`,
+    );
+
+  const target = assertInside(
+    configDir,
+    path.resolve(configDir, entry.file),
+    "feature file",
+  );
+  const after = readFeatureSource(feature.name);
+  const before = fs.existsSync(target)
+    ? fs.readFileSync(target)
+    : Buffer.alloc(0);
+  if (before.equals(after))
+    return {
+      feature,
+      name: feature.name,
+      file: entry.file,
+      changed: false,
+      dryRun: Boolean(dryRun),
+      diff: "",
+    };
+
+  const diff = formatDiff(
+    before.toString("utf8"),
+    after.toString("utf8"),
+    entry.file,
+  );
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    writeFileAtomic(target, after);
+  }
+  return {
+    feature,
+    name: feature.name,
+    file: entry.file,
+    changed: true,
+    dryRun: Boolean(dryRun),
+    diff,
+  };
+}
+
+/**
+ * Load every configured feature extension.
+ * @returns {Promise<{catalog: Record<string, object>, extensionUrls: Record<string, string>, warnings: string[], ids: string[], unsandboxed: string[]}>}
+ */
+export async function loadFeatureExtensions({ configDir, config } = {}) {
+  const catalog = {};
+  const extensionUrls = {};
+  const warnings = [];
+  const ids = [];
+  const unsandboxed = [];
+
+  for (const entry of config?.features || []) {
+    const absolute = path.resolve(configDir, entry.file);
+    if (!fs.existsSync(absolute)) {
+      warnings.push(
+        `feature "${entry.name}": ${entry.file} is missing; run "fx feature ${entry.name} enable"`,
+      );
+      continue;
+    }
+    const loaded = await loadExtensions([absolute], {
+      baseDir: configDir,
+      reportUnmatchedUnsandboxed: false,
+    });
+    Object.assign(catalog, loaded.catalog);
+    Object.assign(extensionUrls, loaded.extensionUrls);
+    warnings.push(...loaded.warnings);
+    ids.push(...loaded.ids);
+    unsandboxed.push(...loaded.unsandboxed);
+  }
+
+  return { catalog, extensionUrls, warnings, ids, unsandboxed };
+}