@triflare/fx 1.0.2 → 2.0.0

package/src/cli/templates/index.js

@@ -0,0 +1,112 @@
+/**
+ * Scaffolding templates used by `fx init`.
+ */
+
+import {
+  configFilename,
+  sourceDirectory,
+  sourceExtension,
+} from "../../brand.js";
+
+const CAT_ASSET = `<svg xmlns="http://www.w3.org/2000/svg" width="95" height="101" viewBox="0 0 95 101">
+  <ellipse cx="47" cy="60" rx="35" ry="35" fill="#ffab19" stroke="#cf8b17" stroke-width="4"/>
+  <circle cx="35" cy="50" r="6" fill="#000"/>
+  <circle cx="60" cy="50" r="6" fill="#000"/>
+</svg>
+`;
+
+function configText({ name, width, height, target }) {
+  const lines = [
+    "project:",
+    `  name: ${JSON.stringify(name)}`,
+    "  fps: 60",
+    `  width: ${width}`,
+    `  height: ${height}`,
+    "  turbo: false",
+    "  interpolation: true",
+    "fx:",
+    "  partialSprites: false",
+  ];
+  if (target !== "none") {
+    lines.push("package:", `  target: ${target}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+const CAT_SOURCE = `sprite "Cat" {
+    costumes: {
+        cat: "../assets/cat.svg"
+    };
+
+    let score = 0;
+
+    when greenFlag {
+        motion.goToXY(0, 0);
+        control.forever {
+            motion.turnRight(1);
+        }
+    }
+
+    when keyPressed("space") {
+        score += 1;
+        looks.sayForSecs(operators.join("Score: ", score), 1);
+    }
+}
+`;
+
+const EMPTY_SOURCE = `// Your project starts here.
+when greenFlag {
+    looks.say("Hello, world!");
+}
+`;
+
+const BLANK_SOURCE = `// Your project starts here.
+`;
+
+/**
+ * Build the file map for an init run.
+ *
+ * @param {{
+ *   product: object,
+ *   name: string,
+ *   template: "cat"|"empty"|"blank",
+ *   width: number,
+ *   height: number,
+ *   target: string,
+ * }} options
+ */
+export function initFiles({ product, name, template, width, height, target }) {
+  const files = {
+    [configFilename(product)]: configText({ name, width, height, target }),
+    [`${sourceDirectory(product)}/main${sourceExtension(product)}`]:
+      template === "cat"
+        ? CAT_SOURCE
+        : template === "empty"
+          ? EMPTY_SOURCE
+          : BLANK_SOURCE,
+  };
+  if (template === "cat") files["assets/cat.svg"] = CAT_ASSET;
+  return files;
+}
+
+export const TEMPLATES = [
+  {
+    value: "cat",
+    label: "Cat demo",
+    hint: "sprite, costumes, events, variables",
+  },
+  { value: "empty", label: "Empty project", hint: "one green-flag script" },
+  { value: "blank", label: "Blank", hint: "just the config and a source file" },
+];
+
+export const TARGETS = [
+  { value: "none", label: "None", hint: "source only" },
+  { value: "html", label: "HTML", hint: "single-file web build" },
+  { value: "zip", label: "ZIP", hint: "packaged archive" },
+];
+
+export const STAGE_SIZES = [
+  { value: "480x360", label: "480 × 360", hint: "Scratch default" },
+  { value: "640x360", label: "640 × 360", hint: "wide" },
+  { value: "1920x1080", label: "1920 × 1080", hint: "full HD" },
+];

package/src/cli/theme.js

@@ -0,0 +1,84 @@
+/**
+ * Terminal theme shared by help output and the reporter.
+ *
+ * Colors are derived from the product palette so a rebrand reaches the CLI
+ * too. Everything falls back to plain text when the stream cannot show color.
+ */
+
+import { styleText } from "node:util";
+import { brandingColors } from "../brand.js";
+
+const STATUS_COLORS = {
+  success: "#34D399",
+  warning: "#FBBF24",
+  danger: "#F87171",
+};
+
+function rgb(hex) {
+  const digits =
+    hex.length === 4 ? hex.slice(1).replace(/./g, "$&$&") : hex.slice(1);
+  return digits.match(/../g).map((part) => parseInt(part, 16));
+}
+
+function mix(from, to, amount) {
+  const [r1, g1, b1] = rgb(from);
+  const [r2, g2, b2] = rgb(to);
+  const channel = (a, b) => Math.round(a + (b - a) * amount);
+  return [channel(r1, r2), channel(g1, g2), channel(b1, b2)];
+}
+
+function supportsColor(stream) {
+  if (!stream?.isTTY) return false;
+  if (process.env.NO_COLOR) return false;
+  if (process.env.TERM === "dumb") return false;
+  return styleText("red", "x", { stream }).includes("\x1b");
+}
+
+/**
+ * @param {{ product?: object, color?: "auto"|"always"|"never", stream?: NodeJS.WriteStream }} [options]
+ */
+export function createTheme({
+  product,
+  color = "auto",
+  stream = process.stdout,
+} = {}) {
+  const palette = brandingColors(product);
+  const enabled =
+    color === "always" || (color !== "never" && supportsColor(stream));
+
+  const paint = (text, codes) => {
+    if (!enabled || codes.length === 0) return String(text);
+    return `\x1b[${codes.join(";")}m${text}\x1b[0m`;
+  };
+
+  const foreground = (colorValue) => {
+    const [r, g, b] = Array.isArray(colorValue) ? colorValue : rgb(colorValue);
+    return `38;2;${r};${g};${b}`;
+  };
+
+  const command = mix(palette.primary, "#FFFFFF", 0.35);
+  const heading = mix(palette.primary, "#FFFFFF", 0.2);
+  const option = mix(palette.primary, "#FFFFFF", 0.58);
+  const argument = mix(palette.primary, "#FFFFFF", 0.74);
+
+  return {
+    enabled,
+    stream,
+
+    accent: (text) => paint(text, [foreground(palette.primary)]),
+    command: (text) => paint(text, ["1", foreground(command)]),
+    heading: (text) => paint(text, ["1", foreground(heading)]),
+    option: (text) => paint(text, [foreground(option)]),
+    argument: (text) => paint(text, [foreground(argument)]),
+    muted: (text) => paint(text, ["2"]),
+    bold: (text) => paint(text, ["1"]),
+    success: (text) => paint(text, [foreground(STATUS_COLORS.success)]),
+    warning: (text) => paint(text, [foreground(STATUS_COLORS.warning)]),
+    danger: (text) => paint(text, [foreground(STATUS_COLORS.danger)]),
+
+    tone(name, text) {
+      const value = STATUS_COLORS[name] ?? palette.primary;
+      return paint(text, [foreground(value)]);
+    },
+  };
+}

package/src/compiler.js

@@ -25,6 +25,11 @@ const HAT_ALIASES = {
   timerGreaterThan: "events.timerGreaterThan",
 };
 
+// `dataFormat` values Scratch 3 can load (see the `VM.Costume` / `VM.Sound`
+// types). Anything else is still written through, but may not load.
+const COSTUME_FORMATS = new Set(["svg", "png", "jpg"]);
+const SOUND_FORMATS = new Set(["wav", "mp3"]);
+
 const NUMBER_TYPES = {
   number: 4,
   positive: 5,
@@ -133,6 +138,8 @@ export class Compiler {
     this.catalog = catalog ? { ...CATALOG, ...catalog } : CATALOG;
     this.extensionUrls = extensionUrls;
     this.file = file;
+    /** @type {string[]} Non-fatal problems worth surfacing to the user. */
+    this.warnings = [];
 
     // opcode -> extension id, derived from the (merged) catalog. This lets
     // synthesized extension blocks declare an id that isn't inferable from
@@ -463,12 +470,20 @@ export class Compiler {
   applyCostumes(ctx, property) {
     for (const entry of property.value) {
       const format = detectFormat(entry.value);
+      if (!COSTUME_FORMATS.has(format))
+        this.warnings.push(
+          `costume ${JSON.stringify(entry.key)} uses dataFormat ` +
+            `"${format}"; Scratch 3 costumes are svg, png or jpg`,
+        );
       const buffer = this.readAsset(entry.value, entry.loc);
       const { width, height } = imageSize(buffer, format);
       const asset = this.registerAsset(buffer, format);
       ctx.target.costumes.push({
         name: entry.key,
-        bitmapResolution: 1,
+        // Scratch 3 saves bitmap costumes at 2x; the VM converts a 1 to 2 on
+        // load anyway (`import/load-costume.js`), and the renderer's
+        // BitmapSkin defaults to 2. SVGs are always 1.
+        bitmapResolution: format === "svg" ? 1 : 2,
         dataFormat: format,
         assetId: asset.assetId,
         md5ext: asset.md5ext,
@@ -481,6 +496,11 @@ export class Compiler {
   applySounds(ctx, property) {
     for (const entry of property.value) {
       const format = detectFormat(entry.value);
+      if (!SOUND_FORMATS.has(format))
+        this.warnings.push(
+          `sound ${JSON.stringify(entry.key)} uses dataFormat ` +
+            `"${format}"; Scratch 3 sounds are wav or mp3`,
+        );
       const buffer = this.readAsset(entry.value, entry.loc);
       const info =
         format === "wav" ? wavInfo(buffer) : { rate: 48000, sampleCount: 0 };
@@ -577,7 +597,7 @@ export class Compiler {
         }
       } else if (spec.input) {
         inputs[spec.input] = this.buildInputForSpec(
-          { type: spec.type || "any" },
+          { type: spec.type || "any", default: spec.default },
           argExpr,
           null,
         );
@@ -1110,7 +1130,16 @@ export class Compiler {
   }
 
   defaultPrim(spec) {
-    switch (spec.type) {
+    const prim = this.defaultPrimForType(spec.type);
+    // Extensions declare the value a call falls back to when it omits an
+    // argument; built-in catalog entries never set `default`.
+    if (spec.default !== undefined && spec.default !== null)
+      prim[1] = String(spec.default);
+    return prim;
+  }
+
+  defaultPrimForType(type) {
+    switch (type) {
       case "number":
         return [4, "0"];
       case "positive":

package/src/config-edit.js

@@ -54,7 +54,8 @@ function childKey(lines, start, end, key) {
 }
 
 function childIndent(lines, start, end) {
-  for (let index = start + 1; index < end; index++) {
+  const limit = Math.min(end, lines.length);
+  for (let index = start + 1; index < limit; index++) {
     const match = /^([ \t]+)\S/.exec(content(lines[index]));
     if (match) return match[1];
   }
@@ -336,3 +337,281 @@ export function removeProjectExtension(configPath, target) {
     unsandboxedRemoved: unsandboxedRemoved.length > 0,
   };
 }
+
+/**
+ * Remove `project.extensions` entirely (used by migration).
+ *
+ * Unlike {@link removeProjectExtension}, this drops the key itself instead of
+ * leaving an empty list, so a fully migrated file has no legacy section left.
+ */
+export function removeProjectExtensions(configPath) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const project = topLevel(lines, "project");
+  if (!project) return [];
+  const { value: rest, comment } = splitComment(project.rest);
+
+  if (rest.startsWith("{")) {
+    if (!rest.endsWith("}"))
+      throw new Error("project must be a mapping to edit it");
+    const mapping = parseValue(rest);
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping))
+      throw new Error("project must be a mapping to edit it");
+    if (!Object.hasOwn(mapping, "extensions")) return [];
+
+    const removed = stringList(mapping.extensions);
+    delete mapping.extensions;
+    const line = lines[project.index];
+    lines[project.index] =
+      `project: ${JSON.stringify(mapping)}` +
+      `${comment ? ` ${comment}` : ""}${ending(line) || eolOf(text)}`;
+    writeDocument(configPath, lines.join(""));
+    return removed;
+  }
+
+  const bounds = projectBounds(lines);
+  if (!bounds) return [];
+  const list = readList(lines, "extensions", bounds.index, bounds.end);
+  if (!list) return [];
+
+  const removed = [...list.values];
+  if (list.style === "block") {
+    const end = Math.max(list.keyLine.index, list.lastLine) + 1;
+    lines.splice(list.keyLine.index, end - list.keyLine.index);
+  } else {
+    lines.splice(list.keyLine.index, 1);
+  }
+  writeDocument(configPath, lines.join(""));
+  return removed;
+}
+
+// --------------------------------------------------------------- vendor edits
+
+const SAFE_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+
+/** Quote a mapping key when YAML would otherwise parse it as non-text. */
+function quoteKey(key) {
+  // YAML 1.1 treats bare yes/no/on/off/null as non-strings.
+  return SAFE_KEY.test(key) &&
+    !/^(?:y|yes|n|no|on|off|null|true|false)$/i.test(key)
+    ? key
+    : JSON.stringify(String(key));
+}
+
+/** Serialize one vendor entry, expanding options only when needed. */
+function vendorEntryLines(name, source, options, indent, eol) {
+  const extra = [];
+  if (options.unsandboxed) extra.push(`${indent}  unsandboxed: true${eol}`);
+  if (options.volatile !== undefined)
+    extra.push(`${indent}  volatile: ${Boolean(options.volatile)}${eol}`);
+  if (extra.length === 0)
+    return [`${indent}${quoteKey(name)}: ${quote(source)}${eol}`];
+  return [
+    `${indent}${quoteKey(name)}:${eol}`,
+    `${indent}  url: ${quote(source)}${eol}`,
+    ...extra,
+  ];
+}
+
+/** Locate a top-level mapping, accepting an inline flow mapping. */
+function topLevelBounds(lines, key) {
+  const found = topLevel(lines, key);
+  if (!found) return null;
+  const { value: rest, comment } = splitComment(found.rest);
+  if (rest !== "") {
+    // A flow mapping can be expanded losslessly (comments on the line aside).
+    if (rest.startsWith("{") && rest.endsWith("}")) {
+      const mapping = parseValue(rest);
+      if (mapping && typeof mapping === "object" && !Array.isArray(mapping))
+        return {
+          index: found.index,
+          end: found.index + 1,
+          inline: rest,
+          comment,
+        };
+    }
+    throw new Error(`${key} must be a block mapping to edit it`);
+  }
+  return {
+    index: found.index,
+    end: sectionEnd(lines, found.index),
+    inline: null,
+    comment,
+  };
+}
+
+/** Find direct child entries and their line ranges in a mapping. */
+function mappingEntrySpans(lines, start, end) {
+  const indent = childIndent(lines, start, end);
+  const spans = [];
+  const limit = Math.min(end, lines.length);
+  for (let index = start + 1; index < limit; index++) {
+    const text = content(lines[index]);
+    if (text.trim() === "" || /^[ \t]*#/.test(text)) continue;
+    const outer = /^([ \t]+)(.*)$/.exec(text);
+    if (!outer || outer[1] !== indent) continue;
+    const match = /^(.+?)[ \t]*:[ \t]*(.*)$/.exec(outer[2]);
+    if (!match) continue;
+    let key;
+    try {
+      const parsed = yaml.load(`${match[1]}: null`);
+      key =
+        parsed && typeof parsed === "object" ? Object.keys(parsed)[0] : null;
+    } catch {
+      continue;
+    }
+    if (key == null) continue;
+    spans.push({ index, indent, key: String(key), rest: match[2] });
+  }
+  for (let index = 0; index < spans.length; index++)
+    spans[index].end = index + 1 < spans.length ? spans[index + 1].index : end;
+  return spans;
+}
+
+/** Replace a half-open line range in place. */
+function replaceRange(lines, start, end, added) {
+  lines.splice(start, end - start, ...added);
+}
+
+/**
+ * Add or replace a `vendor:` entry without reformatting the rest of fx.yml.
+ *
+ * @param {string} configPath
+ * @param {string} name
+ * @param {string} source
+ * @param {{unsandboxed?: boolean, volatile?: boolean}} [options]
+ * @returns {{added: boolean, updated: boolean}}
+ */
+export function addVendorEntry(configPath, name, source, options = {}) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const eol = eolOf(text);
+  const key = String(name);
+  let added = false;
+  let updated = false;
+
+  const bounds = topLevelBounds(lines, "vendor");
+  if (!bounds) {
+    if (lines.length > 0 && !lines[lines.length - 1].endsWith("\n"))
+      lines[lines.length - 1] += eol;
+    lines.push(
+      `vendor:${eol}`,
+      ...vendorEntryLines(key, source, options, "  ", eol),
+    );
+    added = true;
+  } else if (bounds.inline) {
+    const mapping = parseValue(bounds.inline) || {};
+    updated = Object.hasOwn(mapping, key);
+    added = !updated;
+    mapping[key] =
+      options.unsandboxed || options.volatile !== undefined
+        ? {
+            url: source,
+            ...(options.unsandboxed ? { unsandboxed: true } : {}),
+            ...(options.volatile !== undefined
+              ? { volatile: Boolean(options.volatile) }
+              : {}),
+          }
+        : source;
+    const dumped = yaml
+      .dump({ vendor: mapping }, { lineWidth: -1, noRefs: true })
+      .split("\n")
+      .filter((line, index, all) => !(index === all.length - 1 && line === ""))
+      .map((line) => `${line}${eol}`);
+    if (bounds.comment) dumped[0] = `vendor: ${bounds.comment}${eol}`;
+    replaceRange(lines, bounds.index, bounds.index + 1, dumped);
+  } else {
+    const spans = mappingEntrySpans(lines, bounds.index, bounds.end);
+    const existing = spans.find((span) => span.key === key);
+    if (existing) {
+      replaceRange(
+        lines,
+        existing.index,
+        existing.end,
+        vendorEntryLines(key, source, options, existing.indent, eol),
+      );
+      updated = true;
+    } else {
+      const indent = childIndent(lines, bounds.index, bounds.end);
+      insertAt(
+        lines,
+        bounds.end,
+        vendorEntryLines(key, source, options, indent, eol),
+        eol,
+      );
+      added = true;
+    }
+  }
+
+  if (added || updated) writeDocument(configPath, lines.join(""));
+  return { added, updated };
+}
+
+/**
+ * Remove a `vendor:` entry.
+ * @param {string} configPath
+ * @param {string} name
+ * @returns {{removed: string|null}}
+ */
+export function removeVendorEntry(configPath, name) {
+  const text = fs.readFileSync(configPath, "utf8");
+  const lines = splitLines(text);
+  const eol = eolOf(text);
+  const key = String(name);
+  const bounds = topLevelBounds(lines, "vendor");
+  if (!bounds) return { removed: null };
+
+  if (bounds.inline) {
+    const mapping = parseValue(bounds.inline);
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping))
+      return { removed: null };
+    if (!Object.hasOwn(mapping, key)) return { removed: null };
+    const source =
+      typeof mapping[key] === "string"
+        ? mapping[key]
+        : (mapping[key]?.url ?? mapping[key]?.source ?? null);
+    delete mapping[key];
+    const rest = Object.keys(mapping).length
+      ? ` ${JSON.stringify(mapping)}`
+      : " {}";
+    const comment = bounds.comment ? ` ${bounds.comment}` : "";
+    const line = lines[bounds.index];
+    lines[bounds.index] = `vendor:${rest}${comment}${
+      /\r?\n$/.test(line) ? ending(line) : eol
+    }`;
+    writeDocument(configPath, lines.join(""));
+    return { removed: source };
+  }
+
+  const spans = mappingEntrySpans(lines, bounds.index, bounds.end);
+  const existing = spans.find((span) => span.key === key);
+  if (!existing) return { removed: null };
+
+  let source = null;
+  try {
+    const parsed = yaml.load(
+      [
+        content(lines[bounds.index]),
+        ...lines.slice(existing.index, existing.end),
+      ]
+        .join("\n")
+        .replace(/^vendor:/, "vendor:"),
+    );
+    const entry = parsed?.vendor?.[key];
+    source =
+      typeof entry === "string"
+        ? entry
+        : (entry?.url ?? entry?.source ?? entry?.path ?? null);
+  } catch {
+    // The entry is removed either way.
+  }
+
+  replaceRange(lines, existing.index, existing.end, []);
+  const end = bounds.end - (existing.end - existing.index);
+  const remaining = mappingEntrySpans(lines, bounds.index, end);
+  if (remaining.length === 0) {
+    replaceRange(lines, bounds.index, end, [`vendor: {}${eol}`]);
+  }
+  writeDocument(configPath, lines.join(""));
+  return { removed: source ?? key };
+}