scratch-pseudocode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adonis Canada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# scratch-pseudocode
+
+A command-line utility for generating pseudocode from public [MIT Scratch](https://scratch.mit.edu/) projects. 
+I created this tool to experiment with AI feedback generation for student Scratch projects, tuned for Anthropic Claude.
+
+Given a project URL, it fetches the project and prints each sprite's variables, lists, costumes, and scripts in Python-style pseudocode.
+This is especially useful for sending Scratch projects to AI agents for analysis, reading through project logic without opening the editor, or for diffing and reviewing projects in plain text.
+This package is based on the library I made for [MixGit](https://github.com/HunterCogan/mixgit), where I used pseudocode to reduce input tokens by [__87%__](https://github.com/HunterCogan/mixgit/pull/55).
+
+Rewritten with simplicity in mind and to work with zero runtime dependencies.
+
+## Install
+
+Run in the command-line:
+
+```
+npx scratch-pseudocode https://scratch.mit.edu/projects/1327031806
+```
+
+It can be installed globally:
+
+```
+npm install -g scratch-pseudocode
+scratch-pseudocode https://scratch.mit.edu/projects/847915138
+```
+
+Requires Node.js 20 or later.
+
+## Usage
+
+```
+scratch-pseudocode [-t <name>]... <url>
+```
+
+The Scratch project URL must contain a project ID, and the project must be public and shared. Path segments are accepted:
+
+```
+scratch-pseudocode https://scratch.mit.edu/projects/847915138/editor/
+```
+
+### Options
+
+Include `-t, --target <name>` to only output the named target. Repeat the flag to include multiple:
+
+```
+scratch-pseudocode -t Stage https://scratch.mit.edu/projects/1218216947
+```
+
+When excluded, all targets are printed.
+
+## Demo
+
+Redirect output to a text file and read a snippet:
+
+```
+scratch-pseudocode -t Stage -t plane https://scratch.mit.edu/projects/847915138 > pseudocode.txt
+head -n 20 pseudocode.txt
+```
+
+### Output
+
+```
+Target: `Stage`
+Variables: [SCORE=`156`, SPEED=`1`, ☁ HIGHSCORE=`1953`]
+Costumes: [`backdrop1`]
+event_whenflagclicked():
+        event_broadcast(BROADCAST_INPUT=`home screen`)
+        control_forever():
+                sound_playuntildone(`What What?! Wowow!`)
+
+Target: `plane`
+Variables: [gravity=`-21.260000000000005`]
+Costumes: [`costume1`]
+event_whenbroadcastreceived(BROADCAST_OPTION=`play game`):
+        data_setvariableto(VARIABLE=`SCORE`, VALUE=`0`)
+        data_setvariableto(VARIABLE=`SPEED`, VALUE=`0`)
+        data_setvariableto(VARIABLE=`gravity`, VALUE=`0`)
+        motion_gotoxy(X=`-70`, Y=`0`)
+        looks_show()
+        control_forever():
+                motion_changeyby(DY=(`0.06` * (sensing_mousey() - motion_yposition())))
+                motion_pointindirection(DIRECTION=(((motion_yposition() - sensing_mousey()) / `9`) + `90`))
+```
+
+Each target begins with a header containing local variables, lists, and costumes.
+Then, scripts are shown block-by-block.
+
+Most of the blocks are rendered with the code, inputs, and fields from the fetched `project.json`.
+Procedures, operators, and shadow blocks are an exception, restructured for readability.
+In the above example, you can see that `operator_subtract(NUM1=motion_yposition(), NUM2=sensing_mousey())` was simplified to `(motion_yposition() - sensing_mousey())`.
+These choices were made to improve Anthropic Claude's comprehension of student projects; I plan to add more output options soon!

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+var VALUE_TRUNCATE = 50;
+var LIST_TRUNCATE = 30;
+var USAGE = "Usage: scratch-pseudocode [-t <name>]... <url>";
+var HELP = `Generate pseudocode from public Scratch projects.
+
+${USAGE}
+
+Arguments:
+  url                  A Scratch project URL containing a numeric project ID,
+                       e.g. https://scratch.mit.edu/projects/60917032
+                       The project must be public and shared.
+
+Options:
+  -t, --target <name>  Only output the named target.
+                       Repeat the flag to include several.
+  -h, --help           Show this help.`;
+var operatorCodes = {
+  operator_add: "%s + %s",
+  operator_subtract: "%s - %s",
+  operator_multiply: "%s * %s",
+  operator_divide: "%s / %s",
+  operator_mod: "%s mod %s",
+  operator_round: "round %s",
+  operator_mathop: "%s of %s",
+  operator_random: "pick random %s to %s",
+  operator_lt: "%s < %s",
+  operator_equals: "%s == %s",
+  operator_gt: "%s > %s",
+  operator_and: "%s and %s",
+  operator_or: "%s or %s",
+  operator_not: "not %s",
+  operator_join: "join %s %s",
+  operator_letter_of: "letter %s of %s",
+  operator_length: "length of %s",
+  operator_contains: "%s contains %s"
+};
+var values;
+var positionals;
+try {
+  ({ values, positionals } = parseArgs({
+    options: {
+      target: {
+        type: "string",
+        short: "t",
+        multiple: true
+      },
+      help: {
+        type: "boolean",
+        short: "h"
+      }
+    },
+    allowPositionals: true
+  }));
+} catch (err) {
+  console.error(USAGE);
+  process.exit(1);
+}
+if (values.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+var input = positionals[0];
+if (!input) {
+  console.error(USAGE);
+  process.exit(1);
+}
+var match = input.trim().match(/scratch\.mit\.edu\/projects\/(\d+)/);
+if (!match) {
+  console.error(USAGE);
+  process.exit(1);
+}
+var projectId = match[1];
+if (!projectId) {
+  console.error(USAGE);
+  process.exit(1);
+}
+async function fetchProject(projectId2) {
+  const metaRes = await fetch(
+    `https://api.scratch.mit.edu/projects/${projectId2}`
+  );
+  const projectMeta = await metaRes.json();
+  const token = projectMeta?.project_token;
+  const projectRes = await fetch(
+    `https://projects.scratch.mit.edu/${projectId2}?token=${encodeURIComponent(
+      token
+    )}`
+  );
+  const project = await projectRes.json();
+  return { project, projectMeta };
+}
+function formatValue(value, len) {
+  const fmt = `\`${value.toString()}\``;
+  return `${fmt.slice(0, len)}${fmt.length > len ? `... (${fmt.length} chars)` : ""}`;
+}
+function formatList(items, cap, len) {
+  const fmt = items.map((i) => {
+    return formatValue(i, len);
+  });
+  return `[${fmt.slice(0, cap).join(", ")}${fmt.length > cap ? `... (${fmt.length} items)` : ""}]`;
+}
+function parseProcedure(proccode, args) {
+  let i = 0;
+  return proccode.replace(/%[snb]/g, () => `${args[i++]}`);
+}
+function parseOperator(operator, args) {
+  return `(${parseProcedure(operatorCodes[operator] ?? operator, args)})`;
+}
+function collectBlocks(startId, blockMap, collected) {
+  let currentId = startId;
+  while (currentId !== null) {
+    const block = blockMap[currentId];
+    if (!block) break;
+    const stamped = { ...block, id: currentId };
+    collected.push(stamped);
+    for (const key of ["SUBSTACK", "SUBSTACK2"]) {
+      const bodyId = stamped.inputs[key]?.[1];
+      if (typeof bodyId === "string") {
+        collectBlocks(bodyId, blockMap, collected);
+      }
+    }
+    currentId = block.next;
+  }
+}
+function getScripts(project) {
+  const result = {};
+  for (const target of project.targets) {
+    const scripts = [];
+    for (const [id, block] of Object.entries(target.blocks)) {
+      if (block.topLevel && !block.shadow) {
+        const script = [];
+        collectBlocks(id, target.blocks, script);
+        scripts.push(script);
+      }
+    }
+    result[target.name] = scripts;
+  }
+  return result;
+}
+function formatInput(input2, blocks, variables, lists) {
+  if (typeof input2[1] === "string") {
+    const id = input2[1];
+    if (blocks[id] && (blocks[id].shadow || blocks[id]?.opcode.startsWith("argument"))) {
+      const values2 = Object.values(blocks[id].fields).map(
+        (field) => `${formatValue(field[0], VALUE_TRUNCATE)}`
+      );
+      return values2.join(" ");
+    }
+    return toLine(blocks, input2[1], variables, lists);
+  }
+  return input2[1] ? formatValue(input2[1][1], VALUE_TRUNCATE) : "";
+}
+function getIndents(script) {
+  const blocks = new Map(script.map((block) => [block.id, block]));
+  const memo = /* @__PURE__ */ new Map();
+  function depth(id) {
+    const m = memo.get(id);
+    if (m !== void 0) return m;
+    const block = blocks.get(id);
+    let result = 0;
+    if (block && block.parent) {
+      const parent = blocks.get(block.parent);
+      if (parent) {
+        if (parent.next === id) {
+          result = Math.max(depth(block.parent), 1);
+        } else {
+          result = depth(block.parent) + 1;
+        }
+      }
+    }
+    memo.set(id, result);
+    return result;
+  }
+  return new Map([...blocks.keys()].map((id) => [id, depth(id)]));
+}
+function toLine(blocks, id, variables, lists) {
+  if (!blocks[id]) return "";
+  const fields = Object.entries(blocks[id].fields);
+  const inputs = Object.entries(blocks[id].inputs);
+  const fieldParts = fields.map(([key, [name, ref]]) => {
+    if (blocks[id]?.opcode.startsWith("operator")) {
+      return formatValue(name, VALUE_TRUNCATE);
+    }
+    if (key === "VARIABLE" && ref) {
+      return `${key}=${variables[ref] ? formatValue(variables[ref][0], VALUE_TRUNCATE) : "undefined"}`;
+    }
+    if (key === "LIST" && ref) {
+      return `${key}=${lists[ref] ? formatList(lists[ref][1], 10, VALUE_TRUNCATE) : "undefined"}`;
+    }
+    return `${key}=${formatValue(name, VALUE_TRUNCATE)}`;
+  });
+  const inputParts = inputs.filter(([key, _]) => {
+    return !key.startsWith("SUBSTACK");
+  }).map(([key, input2]) => {
+    if (blocks[id]?.opcode.startsWith("operator") || blocks[id]?.opcode.startsWith("argument") || typeof input2[1] === "string" && blocks[input2[1]]?.shadow) {
+      return formatInput(input2, blocks, variables, lists);
+    }
+    return `${key}=${formatInput(input2, blocks, variables, lists)}`;
+  });
+  const start = blocks[id].topLevel || inputs.some(([key, _]) => key.startsWith("SUBSTACK"));
+  if (blocks[id].opcode.startsWith("procedures")) {
+    let args;
+    if (blocks[id].mutation) {
+      const arr = JSON.parse(blocks[id].mutation.argumentids);
+      args = arr.map((arg) => {
+        if (blocks[id]?.inputs[arg]) {
+          return formatInput(
+            blocks[id].inputs[arg],
+            blocks,
+            variables,
+            lists
+          );
+        }
+      }).filter((arg) => arg !== void 0);
+      return `${blocks[id].opcode}(${parseProcedure(
+        blocks[id].mutation.proccode,
+        args
+      )})`;
+    }
+    const ref = blocks[id].inputs["custom_block"];
+    if (ref && typeof ref[1] === "string") {
+      const proc = blocks[ref[1]];
+      if (proc && proc.mutation && proc.mutation.argumentnames) {
+        const args2 = JSON.parse(proc.mutation.argumentnames);
+        return `${blocks[id].opcode}(${parseProcedure(
+          proc.mutation.proccode,
+          args2
+        )})`;
+      }
+    }
+  }
+  if (blocks[id].opcode.startsWith("operator")) {
+    const args = [...fieldParts, ...inputParts];
+    if (args[0]) {
+      return parseOperator(blocks[id].opcode, args);
+    }
+  }
+  return `${blocks[id].opcode}(${[...fieldParts, ...inputParts].join(", ")})${start ? ":" : ""}`;
+}
+function toPseudocode(project, targets) {
+  const scripts = getScripts(project);
+  let pseudocode = "";
+  for (const [targetName, targetScripts] of Object.entries(scripts)) {
+    if (!targets || targets.includes(targetName)) {
+      const target = project.targets.find((t) => t.name === targetName);
+      if (target) {
+        const variables = target.isStage ? target.variables : {
+          ...target.variables,
+          ...project.targets.find((t) => t.isStage)?.variables
+        };
+        const lists = target.isStage ? target.lists : {
+          ...target.lists,
+          ...project.targets.find((t) => t.isStage)?.lists
+        };
+        pseudocode += `
+Target: ${formatValue(target.name, VALUE_TRUNCATE)}
+`;
+        if (Object.values(target.variables).length > 0) {
+          pseudocode += `Variables: [${Object.values(target.variables).map((v) => `${v[0]}=${formatValue(v[1], VALUE_TRUNCATE)}`).join(", ")}]
+`;
+        }
+        if (Object.values(target.lists).length > 0) {
+          pseudocode += `Lists: [${Object.values(target.lists).map(
+            ([name, items]) => `${name}=${formatList(items, LIST_TRUNCATE, VALUE_TRUNCATE)}`
+          )}]
+`;
+        }
+        if (Object.values(target.costumes).length > 0) {
+          pseudocode += `Costumes: ${formatList(
+            Object.values(target.costumes).map((costume) => costume.name),
+            LIST_TRUNCATE,
+            VALUE_TRUNCATE
+          )}
+`;
+        }
+        if (targetScripts.length > 0) {
+          for (const script of targetScripts) {
+            const indents = getIndents(script);
+            for (const [i, block] of script.entries()) {
+              const line = toLine(target.blocks, block.id, variables, lists);
+              const indent = indents.get(block.id) ?? 0;
+              pseudocode += `${`	`.repeat(indent ?? 0)}${line}
+`;
+            }
+          }
+        }
+      }
+    }
+  }
+  return pseudocode.trim();
+}
+async function main(projectId2) {
+  const { project, projectMeta } = await fetchProject(projectId2);
+  console.log(toPseudocode(project, values.target));
+}
+main(projectId);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "scratch-pseudocode",
+  "version": "1.0.0",
+  "description": "A utility for generating pseudocode from public Scratch projects.",
+  "keywords": [
+    "scratch",
+    "scratch-mit",
+    "pseudocode",
+    "parser",
+    "sb3"
+  ],
+  "homepage": "https://github.com/adoniscanada/scratch-pseudocode#readme",
+  "bugs": {
+    "url": "https://github.com/adoniscanada/scratch-pseudocode/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adoniscanada/scratch-pseudocode.git"
+  },
+  "license": "MIT",
+  "author": "Adonis Canada",
+  "type": "module",
+  "bin": {
+    "scratch-pseudocode": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}