@triflare/fx 1.0.3 → 2.1.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflare/fx",
-  "version": "1.0.3",
+  "version": "2.1.0-beta.1",
   "description": "Code PenguinMod projects with text.",
   "type": "module",
   "license": "Apache-2.0",
@@ -15,12 +15,14 @@
   "exports": {
     ".": "./src/index.js",
     "./catalog": "./src/catalog.js",
-    "./language": "./src/language.js"
+    "./language": "./src/language.js",
+    "./lint": "./src/lint/analyze.js"
   },
   "files": [
     "bin",
     "src",
     "vendor/pm-packager-dist",
+    "vendor/tempvars",
     "product.yml",
     "README.md"
   ],
@@ -40,12 +42,14 @@
     "prepack": "node scripts/build-packager.js --if-missing"
   },
   "dependencies": {
-    "js-yaml": "^5.4.3",
-    "quickjs-emscripten": "^0.32.0",
+    "@clack/prompts": "^1.8.1",
     "@fiahfy/icns": "0.0.7",
     "@turbowarp/sbdl": "^7.0.0",
+    "commander": "^15.0.0",
     "cross-fetch": "^4.1.0",
+    "js-yaml": "^5.4.3",
     "jszip": "^3.10.1",
+    "quickjs-emscripten": "^0.32.0",
     "sha.js": "^2.4.12"
   },
   "devDependencies": {

package/product.yml

@@ -1,7 +1,7 @@
 # Identity
 name: "Triflare Fx"
 command: "fx"
-version: "1.0.3"
+version: "2.1.0-beta.1"
 tagline: "Code PenguinMod projects with text."
 author: "Triflare"
 homepage: "https://github.com/triflare/fx"

package/src/brand.js

@@ -62,9 +62,10 @@ 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) {
+function colorize(text, color, stream, force = false) {
   if (!HEX_COLOR.test(color)) return styleText(color, text, { stream });
-  if (!styleText("red", "\u0000", { stream }).includes("\u001b")) return text;
+  if (!force && !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
@@ -76,7 +77,11 @@ function colorize(text, color, stream) {
 // 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) {
+export function brandText(
+  text,
+  stream = process.stdout,
+  { force = false } = {},
+) {
   const { primary, secondary, tertiary } = brandingColors();
   const palette = [primary, secondary, tertiary];
   const chars = Array.from(text);
@@ -96,6 +101,7 @@ export function brandText(text, stream = process.stdout) {
           chars.slice(start, index).join(""),
           palette[bandFor(start)],
           stream,
+          force,
         ),
       );
       start = index;

package/src/catalog.js

@@ -610,6 +610,109 @@ const CORE_CATALOG = {
     kind: "boolean",
     fields: { VALUE: ["is penguinmod?", null] },
   },
+
+  // ------------------------------------------------- temporary variables
+  // The Fx fork of Temporary Variables (`fxTempVars`). Entries are marked
+  // `requiresExtension` so the compiler can refuse to emit blocks whose
+  // extension is not loaded, and so the linter can point at the feature.
+  "tempvars.setThread": {
+    opcode: "fxTempVars_setThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      STRING: { type: "string", default: "0" },
+    },
+  },
+  "tempvars.changeThread": {
+    opcode: "fxTempVars_changeThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      NUM: { type: "number", default: "1" },
+    },
+  },
+  "tempvars.thread": {
+    opcode: "fxTempVars_getThreadVariable",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.threadExists": {
+    opcode: "fxTempVars_threadVariableExists",
+    kind: "boolean",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.forEachThread": {
+    opcode: "fxTempVars_forEachThreadVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "thread variable" },
+      NUM: { type: "number", default: "10" },
+      SUBSTACK: SUBSTACK,
+    },
+  },
+  "tempvars.threads": {
+    opcode: "fxTempVars_listThreadVariables",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
+  "tempvars.setRuntime": {
+    opcode: "fxTempVars_setRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      STRING: { type: "string", default: "0" },
+    },
+  },
+  "tempvars.changeRuntime": {
+    opcode: "fxTempVars_changeRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: {
+      VAR: { type: "string", default: "variable" },
+      // Upstream declares NUM as a string input; keep it so block JSON matches.
+      NUM: { type: "string", default: "1" },
+    },
+  },
+  "tempvars.runtime": {
+    opcode: "fxTempVars_getRuntimeVariable",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.runtimeExists": {
+    opcode: "fxTempVars_runtimeVariableExists",
+    kind: "boolean",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.deleteRuntime": {
+    opcode: "fxTempVars_deleteRuntimeVariable",
+    extension: "fxTempVars",
+    requiresExtension: true,
+    inputs: { VAR: { type: "string", default: "variable" } },
+  },
+  "tempvars.deleteAllRuntime": {
+    opcode: "fxTempVars_deleteAllRuntimeVariables",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
+  "tempvars.runtimes": {
+    opcode: "fxTempVars_listRuntimeVariables",
+    kind: "reporter",
+    extension: "fxTempVars",
+    requiresExtension: true,
+  },
 };
 
 /**

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