@triflare/fx 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@triflare/fx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Code PenguinMod projects with text.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "src/index.js",
+  "bin": {
+    "fx": "bin/fx.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./catalog": "./src/catalog.js",
+    "./language": "./src/language.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor/pm-packager-dist",
+    "product.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "npm run test; npm run lint; npm run format:check",
+    "test": "node --test test/*.test.js",
+    "build:example": "node bin/fx.js build examples/player -o build/player.pmp",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build": "npm run build:packager",
+    "build:packager": "node scripts/build-packager.js",
+    "prepack": "node scripts/build-packager.js --if-missing"
+  },
+  "dependencies": {
+    "js-yaml": "^5.4.3",
+    "quickjs-emscripten": "^0.32.0",
+    "@fiahfy/icns": "0.0.7",
+    "@turbowarp/sbdl": "^7.0.0",
+    "cross-fetch": "^4.1.0",
+    "jszip": "^3.10.1",
+    "sha.js": "^2.4.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.13.0",
+    "prettier": "^3.9.10",
+    "scratch-vm": "github:PenguinMod/PenguinMod-Vm#75ef6994e55270b9c2a2f3cb2edf6a5bf31cdf2a"
+  },
+  "overrides": {
+    "minimatch": "^11.0.4",
+    "taffydb": "file:vendor/taffydb",
+    "dompurify": "^3.4.17",
+    "immutable": "^3.8.4",
+    "webpack": "^5.111.1",
+    "scratch-parser": {
+      "ajv": "^6.15.0",
+      "jszip": "^3.10.2"
+    }
+  }
+}

package/product.yml

@@ -0,0 +1,28 @@
+# Identity
+name: "Triflare Fx"
+command: "fx"
+version: "1.0.0"
+tagline: "Code PenguinMod projects with text."
+author: "Triflare"
+homepage: "https://github.com/triflare/fx"
+
+# Branding
+branding:
+  colors:
+    primary: "#8B5CF6"
+    secondary: "#5D1CF2"
+    tertiary: "#420BC0"
+
+# Terminal Glyphs
+symbols:
+  success: "✓"
+  error: "✗"
+  progress: "~"
+  bullet: "•"
+
+# Defaults
+defaults:
+  configFilename: "fx.yml"
+  sourceExtension: ".tfx"
+  sourceDirectory: "src"
+  outputDirectory: "build"

package/src/brand.js

@@ -0,0 +1,105 @@
+import { styleText } from "node:util";
+import { loadProduct } from "./product.js";
+
+// Every user-facing name, command, and filename comes from product.yml. A
+// rebrand is a one-file change, and a stale literal can't survive a rename.
+export function brand() {
+  return loadProduct();
+}
+
+export function productName(product = brand()) {
+  return product.name;
+}
+
+export function commandName(product = brand()) {
+  return product.command;
+}
+
+export function productVersion(product = brand()) {
+  return product.version;
+}
+
+export function configFilename(product = brand()) {
+  return product.defaults?.configFilename ?? "fx.yml";
+}
+
+export function configFilenames(product = brand()) {
+  const base = configFilename(product);
+  if (base.endsWith(".yml")) return [base, `${base.slice(0, -4)}.yaml`];
+  if (base.endsWith(".yaml")) return [base, `${base.slice(0, -5)}.yml`];
+  return [base];
+}
+
+export function sourceExtension(product = brand()) {
+  return product.defaults?.sourceExtension ?? ".tfx";
+}
+
+export function sourceDirectory(product = brand()) {
+  return product.defaults?.sourceDirectory ?? "src";
+}
+
+export function outputDirectory(product = brand()) {
+  return product.defaults?.outputDirectory ?? "build";
+}
+
+const FALLBACK_COLORS = {
+  primary: "#E8590C",
+  secondary: "#BA470A",
+  tertiary: "#8B3507",
+};
+
+export function brandingColors(product = brand()) {
+  const colors = product.branding?.colors ?? {};
+  return {
+    primary: colors.primary ?? FALLBACK_COLORS.primary,
+    secondary: colors.secondary ?? FALLBACK_COLORS.secondary,
+    tertiary: colors.tertiary ?? FALLBACK_COLORS.tertiary,
+  };
+}
+
+const HEX_COLOR = /^#(?:[\da-f]{3}|[\da-f]{6})$/i;
+
+// styleText only learned hex colors in Node 24.16, and engines allow any 22, so
+// the truecolor escape is built here. The gate is styleText's own: ask it to
+// color a marker, and stay plain when it comes back untouched.
+function colorize(text, color, stream) {
+  if (!HEX_COLOR.test(color)) return styleText(color, text, { stream });
+  if (!styleText("red", "\u0000", { stream }).includes("\u001b")) return text;
+  const digits =
+    color.length === 4 ? color.slice(1).replace(/./g, "$&$&") : color.slice(1);
+  const [red, green, blue] = digits
+    .match(/../g)
+    .map((part) => parseInt(part, 16));
+  return `\u001b[38;2;${red};${green};${blue}m${text}\u001b[39m`;
+}
+
+// Paints a product name or command in three equal bands taken straight from the
+// logo palette. The colors disappear when the stream can't render them, so
+// piped output and CI logs stay plain text.
+export function brandText(text, stream = process.stdout) {
+  const { primary, secondary, tertiary } = brandingColors();
+  const palette = [primary, secondary, tertiary];
+  const chars = Array.from(text);
+  if (chars.length === 0) return text;
+
+  const bandFor = (index) =>
+    Math.min(
+      palette.length - 1,
+      Math.floor((index * palette.length) / chars.length),
+    );
+  const runs = [];
+  let start = 0;
+  for (let index = 1; index <= chars.length; index += 1) {
+    if (index === chars.length || bandFor(index) !== bandFor(start)) {
+      runs.push(
+        colorize(
+          chars.slice(start, index).join(""),
+          palette[bandFor(start)],
+          stream,
+        ),
+      );
+      start = index;
+    }
+  }
+  return runs.join("");
+}

package/src/build.js

@@ -0,0 +1,181 @@
+/**
+ * High level build pipeline: `.tfx` source(s) + `fx.yml` -> `.pmp` bytes.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "./parser.js";
+import { mergePrograms, discoverSources } from "./project.js";
+import { Compiler } from "./compiler.js";
+import { zipSync } from "./sb3.js";
+import { loadConfigFrom, DEFAULT_PROJECT, DEFAULT_FX } from "./config.js";
+import { sourceExtension } from "./brand.js";
+
+/**
+ * @typedef {object} BuildOptions
+ * @property {string} [source] Triflare Fx source text.
+ * @property {string} [file] Path of a single source file.
+ * @property {string[]} [files] Paths of several source files.
+ * @property {Array<{file: string, source: string}>} [sources] Pre-read sources.
+ * @property {string} [dir] Directory to scan for `.tfx` files when no input is given.
+ * @property {object} [projectConfig] Explicit project config (overrides fx.yml).
+ * @property {object} [fxConfig] Explicit Fx-only config (overrides fx.yml).
+ * @property {string} [configDir] Directory to start the fx.yml search from.
+ * @property {Record<string, object>} [catalog] Extra catalog entries.
+ * @property {Record<string, string>} [extensionUrls] Extension id -> URL map.
+ * @property {boolean} [useConfigFile] Whether to auto-load fx.yml (default true).
+ */
+
+/**
+ * Resolve the list of source files (and their text) to compile.
+ * @param {BuildOptions} options
+ * @returns {{dir: string, entries: Array<{file: string, source: string}>}}
+ */
+function resolveSources(options) {
+  const cwd = process.cwd();
+
+  if (Array.isArray(options.sources)) {
+    const dir = path.resolve(options.dir || cwd);
+    const entries = options.sources.map((entry) => {
+      if (typeof entry === "string") {
+        const file = path.resolve(entry);
+        return { file, source: fs.readFileSync(file, "utf8") };
+      }
+      const file = path.resolve(
+        entry.file || path.join(dir, `input${sourceExtension()}`),
+      );
+      return { file, source: entry.source };
+    });
+    return { dir, entries };
+  }
+
+  if (options.source != null) {
+    const file = options.file
+      ? path.resolve(options.file)
+      : path.join(
+          path.resolve(options.dir || cwd),
+          `input${sourceExtension()}`,
+        );
+    return {
+      dir: options.dir ? path.resolve(options.dir) : path.dirname(file),
+      entries: [{ file, source: options.source }],
+    };
+  }
+
+  if (Array.isArray(options.files) && options.files.length > 0) {
+    const files = options.files.map((f) => path.resolve(f));
+    const dir = options.dir
+      ? path.resolve(options.dir)
+      : path.dirname(files[0]);
+    return {
+      dir,
+      entries: files.map((file) => ({
+        file,
+        source: fs.readFileSync(file, "utf8"),
+      })),
+    };
+  }
+
+  if (options.file) {
+    const file = path.resolve(options.file);
+    return {
+      dir: path.dirname(file),
+      entries: [{ file, source: fs.readFileSync(file, "utf8") }],
+    };
+  }
+
+  const dir = path.resolve(options.dir || cwd);
+  const files = discoverSources(dir);
+  if (files.length === 0)
+    throw new Error(`No ${sourceExtension()} files found under ${dir}`);
+  return {
+    dir,
+    entries: files.map((file) => ({
+      file,
+      source: fs.readFileSync(file, "utf8"),
+    })),
+  };
+}
+
+/**
+ * @param {BuildOptions} [options]
+ * @returns {{project: object, assets: Map<string, Buffer>, sb3: Buffer, config: object, fx: object, ast: object, files: string[]}}
+ */
+export function build(options = {}) {
+  const { dir, entries } = resolveSources(options);
+  if (entries.length === 0)
+    throw new Error("No Triflare Fx sources to compile");
+
+  let projectConfig = options.projectConfig || null;
+  let fxConfig = options.fxConfig || null;
+  let configPath = null;
+  if (!projectConfig && options.useConfigFile !== false) {
+    const loaded = loadConfigFrom(options.configDir || dir);
+    projectConfig = loaded.project;
+    fxConfig = loaded.fx;
+    configPath = loaded.path;
+  }
+  if (!projectConfig) projectConfig = { ...DEFAULT_PROJECT };
+  if (!fxConfig) fxConfig = { ...DEFAULT_FX };
+
+  const asts = entries.map(({ file, source }) => ({
+    ast: parse(source, file),
+    file,
+  }));
+  const ast = mergePrograms(asts, {
+    partialSprites: fxConfig.partialSprites,
+  });
+
+  // Assets are resolved relative to the file that references them, falling
+  // back to the config directory (or the scanned directory) for inline
+  // sources that have no path of their own.
+  const baseDir = configPath ? path.dirname(configPath) : dir;
+  const loadAsset = (assetPath, loc) => {
+    const from = loc && loc.file ? path.dirname(loc.file) : baseDir;
+    const resolved = path.isAbsolute(assetPath)
+      ? assetPath
+      : path.resolve(from, assetPath);
+    return fs.readFileSync(resolved);
+  };
+
+  const compiler = new Compiler({
+    project: projectConfig,
+    loadAsset,
+    catalog: options.catalog,
+    extensionUrls: options.extensionUrls,
+    file: entries[0].file,
+  });
+  const { project, assets } = compiler.compile(ast);
+
+  const sb3 = writeSb3(project, assets);
+  return {
+    project,
+    assets,
+    sb3,
+    config: projectConfig,
+    fx: fxConfig,
+    ast,
+    files: entries.map((e) => e.file),
+  };
+}
+
+/**
+ * Serialize project JSON + assets into a `.pmp` ZIP buffer.
+ *
+ * PenguinMod's `.pmp` files are byte-for-byte the same Scratch 3 archive as
+ * `.sb3`, so this is also what {@link writeSb3} produces.
+ * @param {object} project
+ * @param {Map<string, Buffer>} assets
+ * @returns {Buffer}
+ */
+export function writeSb3(project, assets) {
+  const files = [
+    {
+      name: "project.json",
+      data: Buffer.from(JSON.stringify(project)),
+    },
+  ];
+  for (const [md5ext, buffer] of assets) {
+    files.push({ name: md5ext, data: buffer });
+  }
+  return zipSync(files);
+}