@triflare/fx 2.0.0 → 2.1.0-beta.1

package/src/config.js

@@ -11,6 +11,7 @@ import fs from "node:fs";
 import path from "node:path";
 import * as yaml from "js-yaml";
 import { configFilename, configFilenames, productName } from "./brand.js";
+import { DEFAULT_LINT, normalizeLintConfig } from "./lint/config.js";
 
 export const DEFAULT_PROJECT = {
   name: `${productName()} Project`,
@@ -32,6 +33,7 @@ export const DEFAULT_PROJECT = {
 export const DEFAULT_FX = {
   partialSprites: false,
   vendorDir: "extensions",
+  lint: { ...DEFAULT_LINT, rules: { ...DEFAULT_LINT.rules } },
 };
 
 /** Default directory that receives vendored extension sources. */
@@ -121,6 +123,32 @@ export function normalizeVendorEntry(name, raw) {
   };
 }
 
+/**
+ * Normalize the top-level `features:` mapping. Values are file paths (or
+ * `{ file }` mappings), relative to the config directory.
+ *
+ * @param {unknown} raw
+ * @returns {Array<{name: string, file: string}>}
+ */
+export function normalizeFeatures(raw = {}) {
+  if (raw == null) return [];
+  if (!isPlainObject(raw))
+    throw new Error(`${configFilename()}: "features" must be a mapping`);
+  return Object.entries(raw).map(([name, value]) => {
+    const file =
+      typeof value === "string"
+        ? value
+        : isPlainObject(value) && typeof value.file === "string"
+          ? value.file
+          : null;
+    if (!file || file.trim() === "")
+      throw new Error(
+        `${configFilename()}: features.${name} must be a file path or { file: "<path>" }`,
+      );
+    return { name: String(name), file: file.trim() };
+  });
+}
+
 /**
  * Normalize the top-level `vendor:` mapping. Order is load order, so this is an
  * array rather than a plain object.
@@ -381,7 +409,7 @@ export function normalizeProject(raw = {}) {
  * @returns {typeof DEFAULT_FX}
  */
 export function normalizeFx(raw = {}) {
-  const fx = { ...DEFAULT_FX };
+  const fx = { ...DEFAULT_FX, lint: { ...DEFAULT_LINT, rules: {} } };
   if (raw && typeof raw === "object" && !Array.isArray(raw)) {
     if (raw.partialSprites != null)
       fx.partialSprites = Boolean(raw.partialSprites);
@@ -390,6 +418,10 @@ export function normalizeFx(raw = {}) {
         throw new Error(`${configFilename()}: fx.vendorDir must be a path`);
       fx.vendorDir = raw.vendorDir.trim();
     }
+    fx.lint = normalizeLintConfig(
+      raw.lint,
+      (message) => new Error(`${configFilename()}: ${message}`),
+    );
   }
   return fx;
 }
@@ -420,6 +452,7 @@ export function parseConfig(text) {
     fx,
     package: normalizePackage(raw.package || {}),
     vendor: normalizeVendor(raw.vendor || {}),
+    features: normalizeFeatures(raw.features || {}),
     vendorDir: fx.vendorDir,
     raw,
   };
@@ -459,6 +492,7 @@ export function loadConfigFrom(dir) {
       fx,
       package: pkg,
       vendor,
+      features,
       vendorDir,
       raw,
     } = parseConfig(fs.readFileSync(found, "utf8"));
@@ -467,6 +501,7 @@ export function loadConfigFrom(dir) {
       fx,
       package: pkg,
       vendor,
+      features,
       vendorDir,
       raw,
       path: found,
@@ -477,6 +512,7 @@ export function loadConfigFrom(dir) {
     fx: { ...DEFAULT_FX },
     package: normalizePackage({}),
     vendor: [],
+    features: [],
     vendorDir: DEFAULT_VENDOR_DIR,
     raw: {},
     path: null,

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