reverseport 0.0.0-stage → 1.0.0

package/port/src/symbols.mjs

@@ -0,0 +1,201 @@
+// Source-code structure for many languages without compilers or dependencies: classes, functions, signals,
+// exported fields and the raw dependencies each file names. Pattern-based (fast, tolerant of broken code);
+// precise enough to plan a port and to check that nothing was forgotten.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { countLines, isText } from './util.mjs';
+
+export const LANGUAGE_BY_EXT = {
+  '.gd': 'gdscript', '.cs': 'csharp', '.c': 'c', '.h': 'c-header', '.cpp': 'cpp', '.cc': 'cpp', '.cxx': 'cpp', '.hpp': 'cpp', '.hh': 'cpp', '.hxx': 'cpp', '.inl': 'cpp',
+  '.py': 'python', '.pyw': 'python', '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.jsx': 'javascript', '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+  '.vue': 'javascript', '.svelte': 'javascript', '.lua': 'lua', '.java': 'java', '.kt': 'kotlin', '.kts': 'kotlin', '.go': 'go', '.rs': 'rust', '.swift': 'swift', '.rb': 'ruby', '.php': 'php',
+  '.gdshader': 'shader', '.gdshaderinc': 'shader', '.shader': 'shader', '.hlsl': 'shader', '.glsl': 'shader', '.vert': 'shader', '.frag': 'shader', '.compute': 'shader', '.cginc': 'shader', '.usf': 'shader', '.ush': 'shader', '.wgsl': 'shader',
+  '.tscn': 'godot-scene', '.tres': 'godot-resource', '.unity': 'unity-scene', '.prefab': 'unity-prefab', '.rpy': 'renpy', '.hx': 'haxe', '.dart': 'dart', '.m': 'objc', '.mm': 'objc', '.gml': 'gml',
+  '.vb': 'vbnet', '.fs': 'fsharp', '.pas': 'pascal', '.as': 'actionscript', '.coffee': 'coffeescript', '.zig': 'zig', '.nim': 'nim', '.cr': 'crystal', '.scala': 'scala', '.ex': 'elixir', '.exs': 'elixir', '.erl': 'erlang', '.clj': 'clojure',
+};
+export const CODE_LANGUAGES = new Set(Object.values(LANGUAGE_BY_EXT).filter(l => !['godot-scene', 'godot-resource', 'unity-scene', 'unity-prefab'].includes(l)));
+const C_STYLE = new Set(['csharp', 'c', 'c-header', 'cpp', 'javascript', 'typescript', 'java', 'kotlin', 'go', 'rust', 'swift', 'php', 'shader', 'haxe', 'dart', 'objc', 'gml', 'actionscript', 'zig', 'scala']);
+const HASH_STYLE = new Set(['python', 'gdscript', 'ruby', 'renpy', 'coffeescript', 'nim', 'crystal', 'elixir']);
+const KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'return', 'new', 'else', 'catch', 'using', 'lock', 'foreach', 'sizeof', 'typeof', 'nameof', 'do', 'try', 'case', 'throw', 'await', 'yield', 'delete', 'function', 'constructor', 'elif', 'match', 'when', 'in', 'is', 'as', 'default', 'static', 'super', 'this', 'base', 'operator', 'defined', 'decltype', 'alignof', 'static_assert', 'with', 'fixed', 'checked', 'unchecked', 'get', 'set']);
+
+export function languageOf(file) { return LANGUAGE_BY_EXT[path.extname(file).toLowerCase()] ?? null; }
+
+/** Blank out comments (keeping strings and line numbers). */
+export function stripComments(text, language) {
+  const cStyle = C_STYLE.has(language), hash = HASH_STYLE.has(language), lua = language === 'lua';
+  if (!cStyle && !hash && !lua) return text;
+  const out = text.split('');
+  const n = text.length;
+  const blank = (a, b) => { for (let k = a; k < b; k++) if (out[k] !== '\n') out[k] = ' '; };
+  for (let i = 0; i < n; i++) {
+    const c = text[i], d = text[i + 1];
+    if (c === '"' || c === "'" || (c === '`' && cStyle)) {
+      if (hash && text.startsWith(c.repeat(3), i)) { const end = text.indexOf(c.repeat(3), i + 3); i = end < 0 ? n : end + 2; continue; }
+      if (cStyle && c === "'" && ['rust', 'c', 'cpp', 'c-header'].includes(language)) { const m = text.slice(i, i + 12).match(/^'(\\.|[^'\\\n]){1,4}'/); if (m) { i += m[0].length - 1; } continue; }
+      for (i++; i < n && text[i] !== c; i++) { if (text[i] === '\\') i++; else if (text[i] === '\n' && c !== '`') break; }
+      continue;
+    }
+    if (cStyle && c === '/' && d === '/') { const end = text.indexOf('\n', i); blank(i, end < 0 ? n : end); i = end < 0 ? n : end; continue; }
+    if (cStyle && c === '/' && d === '*') { const end = text.indexOf('*/', i + 2); blank(i, end < 0 ? n : end + 2); i = end < 0 ? n : end + 1; continue; }
+    if (hash && c === '#') { const end = text.indexOf('\n', i); blank(i, end < 0 ? n : end); i = end < 0 ? n : end; continue; }
+    if (lua && c === '-' && d === '-') {
+      const long = text.slice(i + 2).match(/^\[(=*)\[/);
+      const end = long ? text.indexOf(`]${long[1]}]`, i) + long[1].length + 2 : text.indexOf('\n', i);
+      blank(i, end < 0 ? n : end); i = end < 0 ? n : end; continue;
+    }
+  }
+  return out.join('');
+}
+
+function lineIndex(text) {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) starts.push(i + 1);
+  return idx => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= idx) lo = mid; else hi = mid - 1; } return lo + 1; };
+}
+
+const all = (re, text) => [...text.matchAll(re)];
+
+export function extractSymbols(text, language) {
+  const code = stripComments(text, language);
+  const line = lineIndex(code);
+  const out = { classes: [], functions: [], deps: [] };
+  const fn = (name, m, extra = {}) => { if (name && !KEYWORDS.has(name)) out.functions.push({ name, line: line(m.index), ...extra }); };
+  const cls = (name, m, extra = {}) => { if (name && !KEYWORDS.has(name)) out.classes.push({ name, line: line(m.index), ...extra }); };
+  const dep = (spec, kind = 'import') => { if (spec) out.deps.push({ spec, kind }); };
+  switch (language) {
+    case 'gdscript': {
+      const cn = code.match(/^class_name\s+(\w+)/m); if (cn) out.className = cn[1];
+      const ex = code.match(/^extends\s+("[^"]+"|[\w.]+)/m); if (ex) out.extends = ex[1].replace(/"/g, '');
+      if (out.className || out.extends) out.classes.push({ name: out.className ?? null, extends: out.extends ?? null, line: 1, script: true });
+      for (const m of all(/^class\s+(\w+)(?:\s+extends\s+([\w.]+))?\s*:/gm, code)) cls(m[1], m, { extends: m[2] ?? null, inner: true });
+      for (const m of all(/^([ \t]*)(static\s+)?func\s+(\w+)\s*\(([^)]*)\)\s*(?:->\s*([\w[\].]+))?/gm, code)) fn(m[3], m, { params: m[4].trim(), ...(m[5] ? { returns: m[5] } : {}), ...(m[2] ? { static: true } : {}), ...(m[1] ? { indented: true } : {}) });
+      out.signals = all(/^signal\s+(\w+)(?:\(([^)]*)\))?/gm, code).map(m => ({ name: m[1], params: (m[2] ?? '').trim(), line: line(m.index) }));
+      out.exports = [...all(/^@export[^\n]*?\bvar\s+(\w+)/gm, code), ...all(/^export(?:\([^)]*\))?\s+var\s+(\w+)/gm, code)].map(m => m[1]);
+      out.nodeRefs = [...new Set([...all(/\$("[^"]+"|%?[\w/]+)/g, code), ...all(/get_node(?:_or_null)?\(\s*"([^"]+)"/g, code)].map(m => m[1].replace(/"/g, '')))].slice(0, 100);
+      for (const m of all(/\b(?:preload|load|ResourceLoader\.load)\(\s*"([^"]+)"/g, code)) dep(m[1], 'load');
+      if (/^res:\/\//.test(out.extends ?? '')) dep(out.extends, 'extends');
+      break;
+    }
+    case 'csharp': {
+      const ns = code.match(/\bnamespace\s+([\w.]+)/); if (ns) out.namespace = ns[1];
+      for (const m of all(/\b(class|struct|interface|enum|record)\s+(\w+)(?:<[^>{]*>)?(?:\s*\([^)]*\))?(?:\s*:\s*([^{\n;]+))?/g, code)) {
+        if (/\bnew\s*$/.test(code.slice(Math.max(0, m.index - 8), m.index))) continue;
+        cls(m[2], m, { kind: m[1], ...(m[3] ? { extends: m[3].split(',')[0].replace(/\bwhere\b.*$/, '').trim() } : {}) });
+      }
+      for (const m of all(/^[ \t]*(?:\[[^\]\n]*\]\s*)*((?:(?:public|private|protected|internal|static|virtual|override|abstract|async|sealed|extern|unsafe|new|partial|readonly)\s+)*)([\w<>[\],.?]+(?:<[^>\n]*>)?)\s+(\w+)\s*(?:<[^>\n]*>)?\s*\(([^)]*)\)\s*(?:where[^{\n]*)?(?:\{|=>|\n\s*\{)/gm, code)) {
+        if (KEYWORDS.has(m[2]) || m[2] === 'else') continue;
+        fn(m[3], m, { returns: m[2], ...(m[1].trim() ? { modifiers: m[1].trim() } : {}) });
+      }
+      for (const m of all(/^[ \t]*(?:public|private|protected|internal)\s+(?:static\s+)?(\w+)\s*\(([^)]*)\)\s*(?::\s*(?:base|this)\([^)]*\)\s*)?\{/gm, code)) fn(m[1], m, { constructor: true });
+      for (const m of all(/^\s*using\s+(?:static\s+)?([\w.]+)\s*;/gm, code)) dep(m[1], 'namespace');
+      out.exports = all(/\[(?:SerializeField|Export)[^\]]*\][^;=(]*?\s(\w+)\s*(?:=[^;]*)?;/g, code).map(m => m[1]);
+      out.signals = all(/\[Signal\]\s*(?:public\s+)?delegate\s+\w+\s+(\w+)EventHandler/g, code).map(m => ({ name: m[1], line: line(m.index) }));
+      break;
+    }
+    case 'c': case 'c-header': case 'cpp': case 'objc': {
+      for (const m of all(/^\s*#\s*(?:include|import)\s*"([^"]+)"/gm, code)) dep(m[1], 'include');
+      for (const m of all(/^\s*#\s*(?:include|import)\s*<([^>]+)>/gm, code)) dep(m[1], 'system');
+      for (const m of all(/^\s*(?:template\s*<[^>]*>\s*)?(class|struct|union)\s+(?:[A-Z_][A-Z0-9_]*_API\s+|alignas\([^)]*\)\s+)?(\w+)(?:\s+final)?\s*(?::\s*([^{;]+))?\{/gm, code)) cls(m[2], m, { kind: m[1], ...(m[3] ? { extends: m[3].replace(/\b(public|private|protected|virtual)\b/g, '').split(',')[0].trim() } : {}) });
+      for (const m of all(/^[ \t]*(?:[\w:<>,*&~]+[ \t*&]+)+?([\w:~]+)\s*\(([^;{}()]*(?:\([^)]*\)[^;{}()]*)*)\)\s*(?:const\s*)?(?:override\s*)?(?:noexcept\s*)?(?:->\s*[\w:<>*&]+\s*)?\{/gm, code)) {
+        const name = m[1].split('::').pop();
+        if (KEYWORDS.has(name)) continue;
+        fn(name, m, { ...(m[1].includes('::') ? { qualified: m[1] } : {}) });
+      }
+      const ue = { uclass: (code.match(/\bUCLASS\s*\(/g) ?? []).length, ufunction: (code.match(/\bUFUNCTION\s*\(/g) ?? []).length, uproperty: (code.match(/\bUPROPERTY\s*\(/g) ?? []).length };
+      if (ue.uclass + ue.ufunction + ue.uproperty) out.unreal = ue;
+      break;
+    }
+    case 'python': {
+      for (const m of all(/^([ \t]*)class\s+(\w+)(?:\(([^)]*)\))?\s*:/gm, code)) cls(m[2], m, { ...(m[3] ? { extends: m[3].split(',')[0].trim() } : {}), ...(m[1] ? { indented: true } : {}) });
+      for (const m of all(/^([ \t]*)(?:async\s+)?def\s+(\w+)\s*\(/gm, code)) fn(m[2], m, m[1] ? { indented: true } : {});
+      for (const m of all(/^\s*import\s+([\w.]+(?:\s+as\s+\w+)?(?:\s*,\s*[\w.]+(?:\s+as\s+\w+)?)*)/gm, code)) for (const part of m[1].split(',')) dep(part.trim().split(/\s+/)[0]);
+      for (const m of all(/^\s*from\s+(\.*[\w.]*)\s+import\s+\(?([\w\s,*]+)/gm, code)) dep(m[1], m[1].startsWith('.') ? 'relative' : 'import');
+      if (/^if\s+__name__\s*==\s*['"]__main__['"]/m.test(code)) out.entry = true;
+      break;
+    }
+    case 'javascript': case 'typescript': case 'coffeescript': {
+      for (const m of all(/(?:^|[^.\w])(?:import|export)\s+(?:type\s+)?(?:[^'"`;]*?\s+from\s+)?['"]([^'"]+)['"]/g, code)) dep(m[1]);
+      for (const m of all(/\b(?:require|import)\(\s*['"]([^'"]+)['"]\s*\)/g, code)) dep(m[1], 'dynamic');
+      for (const m of all(/\bclass\s+(\w+)(?:<[^>]*>)?(?:\s+extends\s+([\w.]+))?/g, code)) cls(m[1], m, m[2] ? { extends: m[2] } : {});
+      for (const m of all(/\bfunction\s*\*?\s*(\w+)\s*\(/g, code)) fn(m[1], m);
+      for (const m of all(/\b(?:const|let|var)\s+(\w+)\s*(?::[^=]+)?=\s*(?:async\s*)?(?:\([^)]*\)|\w+)\s*(?::\s*[^=]+)?=>/g, code)) fn(m[1], m, { arrow: true });
+      for (const m of all(/^[ \t]+(?:(?:static|async|get|set|public|private|protected|readonly|override)\s+)*\*?\s*(#?\w+)\s*\([^)\n]*\)\s*(?::\s*[^{\n]+)?\{/gm, code)) fn(m[1], m, { method: true });
+      if (/\bexport\s+default\b/.test(code)) out.defaultExport = true;
+      break;
+    }
+    case 'lua': {
+      for (const m of all(/\bfunction\s+([\w.:]+)\s*\(/g, code)) fn(m[1].split(/[.:]/).pop(), m, { qualified: m[1] });
+      for (const m of all(/\blocal\s+function\s+(\w+)/g, code)) fn(m[1], m, { local: true });
+      for (const m of all(/([\w.:]+)\s*=\s*function\s*\(/g, code)) fn(m[1].split(/[.:]/).pop(), m, { qualified: m[1] });
+      for (const m of all(/\brequire\s*\(?\s*['"]([^'"]+)['"]/g, code)) dep(m[1]);
+      break;
+    }
+    case 'java': case 'kotlin': case 'scala': {
+      const pkg = code.match(/^\s*package\s+([\w.]+)/m); if (pkg) out.namespace = pkg[1];
+      for (const m of all(/^\s*import\s+(?:static\s+)?([\w.*]+)/gm, code)) dep(m[1], 'import');
+      for (const m of all(/\b(class|interface|enum|record|object|trait)\s+(\w+)(?:<[^>{]*>)?(?:\s*(?:extends|:)\s*([\w.<>]+))?/g, code)) cls(m[2], m, { kind: m[1], ...(m[3] ? { extends: m[3] } : {}) });
+      if (language === 'java') for (const m of all(/^[ \t]*(?:@\w+(?:\([^)]*\))?\s*)*(?:(?:public|private|protected|static|final|abstract|synchronized|native|default)\s+)*(?:<[^>]+>\s+)?([\w<>[\],.?]+)\s+(\w+)\s*\(([^)]*)\)\s*(?:throws[^{]*)?\{/gm, code)) { if (!KEYWORDS.has(m[1])) fn(m[2], m, { returns: m[1] }); }
+      else for (const m of all(/\b(?:fun|def)\s+(?:<[^>]+>\s*)?(?:[\w.]+\.)?(\w+)\s*[([]/g, code)) fn(m[1], m);
+      break;
+    }
+    case 'go': {
+      const pkg = code.match(/^package\s+(\w+)/m); if (pkg) { out.namespace = pkg[1]; if (pkg[1] === 'main') out.entry = /^func\s+main\s*\(/m.test(code); }
+      for (const m of all(/^func\s+(?:\(([^)]*)\)\s*)?(\w+)/gm, code)) fn(m[2], m, m[1] ? { receiver: m[1].trim().split(/\s+/).pop() } : {});
+      for (const m of all(/^type\s+(\w+)\s+(struct|interface)/gm, code)) cls(m[1], m, { kind: m[2] });
+      for (const m of all(/^import\s+(?:\w+\s+)?"([^"]+)"/gm, code)) dep(m[1]);
+      for (const m of all(/^import\s*\(([\s\S]*?)\)/gm, code)) for (const im of m[1].matchAll(/"([^"]+)"/g)) dep(im[1]);
+      break;
+    }
+    case 'rust': {
+      for (const m of all(/\bfn\s+(\w+)/g, code)) fn(m[1], m);
+      for (const m of all(/\b(struct|enum|trait|union)\s+(\w+)/g, code)) cls(m[2], m, { kind: m[1] });
+      for (const m of all(/^\s*(?:pub(?:\([^)]*\))?\s+)?mod\s+(\w+)\s*;/gm, code)) dep(m[1], 'mod');
+      for (const m of all(/^\s*(?:pub\s+)?use\s+([\w:]+)/gm, code)) dep(m[1], 'use');
+      if (/\bfn\s+main\s*\(/.test(code)) out.entry = true;
+      break;
+    }
+    case 'shader': {
+      const st = code.match(/^\s*shader_type\s+(\w+)/m); if (st) out.shaderType = st[1];
+      for (const m of all(/^[ \t]*(?:\w+[ \t]+)+(\w+)\s*\([^;{)]*\)\s*(?::\s*\w+\s*)?\{/gm, code)) fn(m[1], m);
+      out.uniforms = all(/\buniform\s+(?:\w+\s+)?\w+\s+(\w+)/g, code).map(m => m[1]);
+      for (const m of all(/#\s*include\s*["<]([^">]+)[">]/g, code)) dep(m[1], 'include');
+      break;
+    }
+    case 'renpy': {
+      for (const m of all(/^\s*label\s+([\w.]+)\s*:/gm, code)) fn(m[1], m, { label: true });
+      for (const m of all(/^\s*screen\s+(\w+)/gm, code)) cls(m[1], m, { kind: 'screen' });
+      break;
+    }
+    case 'gml': {
+      for (const m of all(/\bfunction\s+(\w+)\s*\(/g, code)) fn(m[1], m);
+      break;
+    }
+    default: {
+      for (const m of all(/\b(?:function|func|fn|def|sub|procedure)\s+(\w+)/g, code)) fn(m[1], m);
+      for (const m of all(/\b(?:class|struct|interface|module)\s+(\w+)/g, code)) cls(m[1], m);
+    }
+  }
+  const seen = new Set();
+  out.functions = out.functions.filter(f => { const k = `${f.name}:${f.line}`; if (seen.has(k)) return false; seen.add(k); return true; });
+  return out;
+}
+
+const MAX_SOURCE = 4 * 1024 * 1024;
+
+/** Read and analyse one source file. Returns null for non-code or oversized files. */
+export async function fileSymbols(abs, language = languageOf(abs)) {
+  if (!language || !CODE_LANGUAGES.has(language)) return null;
+  const st = await fs.stat(abs);
+  if (st.size > MAX_SOURCE) return { language, lines: null, skipped: 'larger than 4 MiB', classes: [], functions: [], deps: [] };
+  const buf = await fs.readFile(abs);
+  if (!isText(buf)) return null;
+  const text = buf.toString('utf8');
+  return { language, lines: countLines(text), ...extractSymbols(text, language) };
+}
+
+/** Identifiers used in a file (for type-index dependency resolution). */
+export function identifiers(text) {
+  const set = new Set();
+  for (const m of text.matchAll(/\b[A-Z_][A-Za-z0-9_]{2,}\b/g)) set.add(m[0]);
+  return set;
+}

package/port/src/tools.mjs

@@ -0,0 +1,193 @@
+// The tool surface shared by every door (MCP, HTTP/OpenAPI, CLI): one schema list, one dispatcher.
+import { readFileSync } from 'node:fs';
+import { RPError } from './util.mjs';
+import { scanProject } from './scan.mjs';
+import { graphTool, symbolsTool } from './graph.mjs';
+import { readScene } from './scene.mjs';
+import { inspectBinary } from './binary.mjs';
+import { archiveTool } from './archive.mjs';
+import { probe, carve, compare, report } from './compare.mjs';
+import { portMapTool } from './knowledge.mjs';
+import { convert, SYSTEMS } from './convert.mjs';
+import { planPort, portUnit, portWrite, portScene, portStatus, portVerify, portCopyAssets, TARGETS } from './plan.mjs';
+import { lookupTool, SOURCES } from './lookup.mjs';
+import { blueprintTool, ARCHETYPE_IDS } from './blueprint.mjs';
+import { annotationsFor, closest, formatTools, shareFeedback } from './agent.mjs';
+
+/** One version for the whole package: the root package.json. */
+export const VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+
+const str = (description, extra = {}) => ({ type: 'string', description, ...extra });
+const int = (description, extra = {}) => ({ type: 'integer', description, ...extra });
+const num = description => ({ type: 'number', description });
+const bool = description => ({ type: 'boolean', description });
+const vec = (n, description) => ({ type: 'array', items: { type: 'number' }, minItems: n, maxItems: n, description });
+const obj = (properties, required = [], description) => ({ type: 'object', ...(description ? { description } : {}), properties, required, additionalProperties: false });
+const planId = str('Port plan id from port_plan (port_status lists them).');
+const unit = str('Unit id (u001…), or its source/target path. Omit for the next unit in dependency order.');
+const engines = [...TARGETS];
+const ENGINE_TARGETS_DOC = TARGETS.join(', ');
+
+export const tools = [
+  // ------------------------------------------------------------ reverse engineering
+  { name: 're_scan', brief: 'Start here: engine and version, languages and entry points of a project or exported game folder.', title: 'Scan a project or game folder',
+    description: 'Reconnaissance of a folder: detects the engine/framework (Godot, Unity, Unreal, GameMaker, RPG Maker, Ren\'Py, LÖVE, Defold, Bevy, MonoGame, three.js/Phaser/Electron, Flutter, .NET, Go, Rust, Python…) for source projects AND exported game builds, languages with line counts, file categories, entry points, biggest files and binaries. Start here.',
+    inputSchema: obj({ path: str('Folder to scan.'), maxFiles: int('Stop after this many files (default 50000).', { minimum: 100, maximum: 500000 }) }, ['path']) },
+  { name: 're_graph', brief: 'Dependency graph of a project: entry points, cycles, most-used files and the port order.', title: 'Dependency graph and port order',
+    description: 'Builds the dependency graph of a project: imports/includes/requires, Godot res:// loads and scene resources, Unity script/prefab GUIDs, and type references (C#, GDScript class_name/autoloads, Java…). Returns entry points, cycles, orphans, most-used files, external packages and the port order (dependencies first). format:"mermaid" adds a diagram.',
+    inputSchema: obj({ path: str('Project folder.'), limit: int('Files in portOrder (default 80; edges 40). Larger values return more.', { minimum: 10, maximum: 5000 }), format: str('json (default), mermaid or both.', { enum: ['json', 'mermaid', 'both'] }) }, ['path']) },
+  { name: 're_symbols', brief: 'Classes, functions, signals and exported fields of a file or folder; match filters by name.', title: 'Classes, functions, signals',
+    description: 'Code structure for one file or a whole folder (30+ languages: GDScript, C#, C/C++ incl. Unreal macros, Python, JS/TS, Lua, Java/Kotlin, Go, Rust, Swift, shaders, Ren\'Py…): classes with base classes, functions with lines, signals/events, exported/serialized fields, dependencies, node paths. match filters by name (substring or * wildcard).',
+    inputSchema: obj({ path: str('File or folder.'), match: str('Filter names (e.g. "player", "*_process").'), limit: int('Max files (default 60).', { minimum: 1, maximum: 5000 }) }, ['path']) },
+  { name: 're_scene', brief: 'Read a Godot or Unity scene/prefab/project file as a tree with transforms and connections.', title: 'Read a scene, prefab or project file',
+    description: 'Reads Godot .tscn/.tres/project.godot (Godot 3 and 4) and Unity .unity/.prefab/.asset (text serialization) into one neutral tree: node names, types, scripts, transforms (position, quaternion, scale), components, groups/tags, instanced scenes/prefabs (resolved through .meta GUIDs), signal connections, plus a mermaid diagram.',
+    inputSchema: obj({ file: str('Scene/prefab/project file.') }, ['file']) },
+  { name: 're_binary', brief: 'Inspect an executable or bytecode file: format, sections, imports, .NET types, strings, hints.', title: 'Inspect an executable or bytecode',
+    description: 'Inspects PE/EXE/DLL (incl. .NET assemblies: runtime, types and methods), ELF, Mach-O (incl. universal), WebAssembly, Java .class, Android .dex, Lua/LuaJIT and Python bytecode: architecture, sections with entropy, imports/exports, PDB path, signing, overlay data (e.g. an embedded game pack), toolchain/engine hints and strings. Read-only: it does not unpack, decrypt or patch.',
+    inputSchema: obj({ file: str('Binary file.'), strings: obj({ min: int('Minimum string length (default 6).', { minimum: 3, maximum: 64 }), limit: int('Strings to return (default 120).', { minimum: 1, maximum: 5000 }), match: str('Filter strings: substring, glob (*.dll) or /regex/i.'), maxMB: int('Scan this many MiB for strings (default 64).', { minimum: 1, maximum: 256 }), raw: bool('Include strings that look like byte noise (default false).') }, [], 'String options: min, limit, match, maxMB, raw.'), names: obj({ match: str('Filter import/export names: substring, glob or /regex/i.'), limit: int('Import and export names to return each (default 100).', { minimum: 1, maximum: 5000 }) }, [], 'Import/export name options: match, limit.'), maxTypes: int('.NET types to list (default 300).', { minimum: 1, maximum: 5000 }) }, ['file']) },
+  { name: 're_archive', brief: 'List or extract a pack/archive: Godot .pck (also inside .exe), zip/apk/jar, tar.gz, asar.', title: 'List or extract a pack/archive',
+    description: 'Lists or extracts Godot .pck packs (also packs embedded in an exported .exe/.x86_64), ZIP family (apk, jar, ipa, nupkg, docx), tar and tar.gz (.unitypackage), and Electron .asar. Identifies Unity bundles and Unreal paks (header only). Godot entries are MD5-checked on extraction. Encrypted packs/entries are reported, never decrypted. Extraction goes to the ReversePort workspace unless out is given.',
+    inputSchema: obj({ file: str('Archive/pack/executable.'), action: str('list (default) or extract.', { enum: ['list', 'extract'] }), match: str('Only entries matching: substring, glob (*.gd, scenes/*.tscn) or /regex/.'), limit: int('Max entries listed/extracted (default 500).', { minimum: 1, maximum: 20000 }), out: str('Extraction folder (default: workspace/extracted/<file>).'), maxBytes: int('Extraction budget in bytes (default 4 GiB).', { minimum: 1 }) }, ['file']) },
+  { name: 're_probe', brief: 'Identify unknown data: hex, entropy map, embedded files and record strides.', title: 'Probe unknown data',
+    description: 'For unknown or custom formats: identifies the format at an offset, hex view, entropy map (text/code/compressed regions), embedded files (PNG, OGG, WAV, ZIP, GDPC, glTF, DDS, ELF/PE…) with offsets and sizes, and likely record strides for tables. Works on multi-GB files.',
+    inputSchema: obj({ file: str('File to probe.'), offset: int('Start offset (default 0).', { minimum: 0 }), length: int('Bytes in the hex view (default 256, max 4096).', { minimum: 16, maximum: 4096 }), maxMB: int('MiB to scan for entropy/embedded files (default 512).', { minimum: 1, maximum: 65536 }) }, ['file']) },
+  { name: 're_extract', brief: 'Carve a byte range out of a file (for whole archives use re_archive action:"extract").', title: 'Carve bytes out of a file',
+    description: 'Copies a byte range (e.g. an embedded PNG/WAV/glb/ZIP found by re_probe) into the workspace as its own file. length is optional when the embedded format stores its size (RIFF/WAV, glb, PNG). To unpack a whole archive or pack, use re_archive with action:"extract" instead.',
+    inputSchema: obj({ file: str('Source file.'), offset: int('Start offset.', { minimum: 0 }), length: int('Bytes to copy.', { minimum: 1 }), name: str('Output file name.') }, ['file', 'offset']) },
+  { name: 're_compare', brief: 'What changed between two folders, packs, binaries or files.', title: 'Diff two builds, packs, binaries or folders',
+    description: 'Compares two folders (added/removed/changed files), two packs/archives (entries, MD5 for Godot packs), two executables (imports, exports, sections) or any two files (first difference, changed regions). Use it to see what changed between builds or versions.',
+    inputSchema: obj({ a: str('First folder/file (old).'), b: str('Second folder/file (new).'), limit: int('Max items per list (default 300).', { minimum: 10, maximum: 5000 }) }, ['a', 'b']) },
+  { name: 're_report', brief: 'Write ARCHITECTURE.md for a project folder.', title: 'Write an architecture report',
+    description: 'Writes ARCHITECTURE.md for a project: stack, languages, entry points, mermaid module graph, cycles, most-used files, scene trees of the entry scenes, class table, possibly unused files and external dependencies.',
+    inputSchema: obj({ path: str('Project folder.'), out: str('Output .md path (default: workspace/reports).') }, ['path']) },
+  // ------------------------------------------------------------ recon without files and rebuilds
+  { name: 're_lookup', brief: 'No files: look up a game, app, site or repo from public sources (engine, stack, structure).', title: 'Look up a game, app or site from public sources (no files)',
+    description: 'Recon without files: give one of query (a name), url (store/web/GitHub page), steamAppId, appStoreId or github. Reads public sources only (Steam store API, PCGamingWiki, Wikidata, Apple App Store, GitHub, the web page itself) and returns a dossier: identity (developer, release, platforms, genres), tech (engine with confidence and sources, languages, graphics APIs, middleware, web stack and hosting fingerprint), material (where its files live and how they are structured: install layout and formats of its engine, save/config locations, scripts/wasm/data files a web page loads, a public repo\'s structure and detected engine), references (screenshots, videos, pages), and open-source reimplementations, remakes and tools. mirror:true downloads a public GitHub repo\'s source text so re_graph, re_symbols and port_plan can read it. Returns a lookupId for re_blueprint. Cached for a day (fresh:true refetches).',
+    inputSchema: obj({ query: str('Name of the game, app or software.'), url: str('Steam, App Store, Google Play, GitHub or any public web page URL.'), steamAppId: str('Steam app id.'), appStoreId: str('Apple App Store id.'), github: str('Public GitHub repo: owner/repo or URL.'), kind: str('auto (default), game, app or software.', { enum: ['auto', 'game', 'app', 'software'] }), sources: { type: 'array', items: { type: 'string', enum: SOURCES }, description: `Limit sources (default all): ${SOURCES.join(', ')}.` }, mirror: bool('GitHub: download the source text (code, scenes, configs) into the workspace.'), maxFiles: int('mirror: max files (default 400).', { minimum: 10, maximum: 5000 }), fresh: bool('Skip the one-day cache.') }) },
+  { name: 're_blueprint', brief: 'Clean-room rebuild spec with parameters to measure, a parity table and a project skeleton.', title: 'Precise rebuild spec for an existing game or app',
+    description: `Turns a re_lookup dossier (lookupId) and/or name, genres, tags and a description into a clean-room rebuild spec that matches the original in function and feel: the systems it is made of, and per system the parameters to measure on the original (speeds, jump arcs, timings, frame data, camera, economy tables, UI layout fractions…) with how to measure them; target engine with conventions (same engine as the original by default); milestones; capture/measure/verify method; clean-room rules (own code, art, audio, text and name). Writes BLUEPRINT.md, parity.json (every parameter with original/rebuild/tolerance) and, for engine targets, a project skeleton with every numeric parameter as a tunable. Archetypes: ${ARCHETYPE_IDS.join(', ')}.`,
+    inputSchema: obj({ lookupId: str('Dossier id from re_lookup.'), name: str('Name of the original (when there is no lookupId).'), kind: str('game or app (default from the lookup, else game).', { enum: ['game', 'app'] }), genres: { type: 'array', items: { type: 'string' }, description: 'Genres (e.g. ["platformer"]).' }, tags: { type: 'array', items: { type: 'string' }, description: 'Tags/categories (e.g. ["multiplayer", "controller support"]).' }, description: str('What the original is and does.'), engine: str('Engine of the original, if known.'), target: str(`Target: ${ENGINE_TARGETS_DOC}, or web, flutter, react-native, swift, kotlin, electron, or a language.`), perspective: str('2d or 3d (default from the lookup).'), archetypes: { type: 'array', items: { type: 'string', enum: ARCHETYPE_IDS }, description: 'Force archetypes.' }, output: str('Project skeleton folder (new or empty; default workspace/blueprints/<name>/project-<target>).'), scaffold: bool('Write the project skeleton (default true for engine targets).') }) },
+  // ------------------------------------------------------------ porting
+  { name: 'port_map', brief: 'Engine conventions and API map for a port (e.g. from godot to unity).', title: 'Engine/API porting map',
+    description: `Curated porting knowledge: engine conventions (axes, units, handedness, Euler order, FOV, physics tick, lifecycle) and API maps with notes and pitfalls. Without arguments: lists engines and maps. Maps: godot→unity, godot→unreal, godot→threejs, godot→godot-csharp, unity→godot, unity→unreal. query/topic filter entries.`,
+    inputSchema: obj({ from: str('Source engine (godot, godot-csharp, unity, unreal, threejs).'), to: str('Target engine.'), query: str('Filter entries (e.g. "signal", "input", "physics").'), topic: str('Exact topic (lifecycle, input, physics, events, scene tree, rendering…).') }) },
+  { name: 'port_convert', brief: 'Convert positions, rotations, scale and FOV between engines.', title: 'Convert coordinates between engines',
+    description: `Converts positions, rotations (quaternion [x,y,z,w] or Euler degrees in the source engine's convention), scales and camera FOV between ${Object.keys(SYSTEMS).join(', ')}. Returns target quaternion plus Euler in the target's convention (Godot rotation_degrees, Unity eulerAngles, three.js), the axis matrix and unit factor (Unreal ×100).`,
+    inputSchema: obj({ from: str('Source system.', { enum: Object.keys(SYSTEMS) }), to: str('Target system.', { enum: Object.keys(SYSTEMS) }), position: vec(3, '[x, y, z] in source units.'), rotation: vec(4, 'Quaternion [x, y, z, w].'), euler: vec(3, 'Euler degrees in the source convention (godot, unity, threejs).'), scale: vec(3, '[x, y, z].'), fov: num('Camera FOV in degrees (vertical; horizontal for unreal).'), aspect: num('Aspect ratio for FOV conversion (default 16/9).') }, ['from', 'to']) },
+  { name: 'port_plan', brief: 'Plan a port to another engine or language and create the output project.', title: 'Plan a port',
+    description: `Plans a port of a project to another engine or language and creates the output project (scaffold). Every source file becomes a unit with a target path, action (translate, convert-scene, copy, rebuild), dependencies, API-usage count and risk, ordered dependencies-first. Engines: ${engines.join(', ')}; or a language (typescript, python, csharp, cpp, rust, go…). The source is never modified; output must be a new or empty folder.`,
+    inputSchema: obj({ source: str('Source project folder.'), to: str(`Target: ${engines.join(', ')} or a language.`), output: str('Output folder (default: workspace/ports/<id>/output).'), name: str('Project name for the target.'), include: str('Regex: only source paths matching.'), exclude: str('Regex: skip source paths matching.'), unrealVersion: str('EngineAssociation for Unreal targets (default 5.5).') }, ['source', 'to']) },
+  { name: 'port_unit', brief: 'Next unit to port: its source, API hints with line numbers and the exact next call.', title: 'Get the next unit to port',
+    description: 'Returns one unit with everything needed to port it: source text, symbols, the engine APIs it uses with their mapped equivalents and line numbers (apiHints), conventions, target path and naming rules, dependencies with the symbols of their already-ported targets, and a checklist. Marks it in_progress.',
+    inputSchema: obj({ planId, unit, full: bool('Repeat the conventions and checklist even after the first finished unit (they are shortened after that).') }, ['planId']) },
+  { name: 'port_write', brief: 'Write a ported unit (content, files or copy:true); reports leftovers and the next call.', title: 'Write a ported unit',
+    description: 'Writes the ported file(s) for a unit into the output project (never outside it) and records progress. Returns leftovers (source-engine APIs still present), PORT/TODO markers, source functions/signals missing in the port, and the next unit. copy:true copies an asset unchanged. Give exactly one of content, files or copy. status partial/skipped with notes when something cannot be ported yet.',
+    inputSchema: obj({ planId, unit: str('Unit id or path.'), content: str('File content for the unit target.'), files: { type: 'array', maxItems: 20, items: obj({ path: str('Path inside the output project (default: unit target).'), content: str('File content.') }, ['content']), description: 'Several files (e.g. Unreal .h and .cpp).' }, copy: bool('Copy the source file unchanged (assets).'), status: str('done (default), partial or skipped.', { enum: ['done', 'partial', 'skipped'] }), notes: str('What is left or why it was skipped.') }, ['planId', 'unit']) },
+  { name: 'port_scene', brief: 'Convert a scene/prefab automatically.', title: 'Convert a scene/prefab',
+    description: 'Converts a scene deterministically: Godot .tscn → Unity prefab/scene spec (+ editor builder menu), three.js TypeScript builder module, Unreal scene spec (cm, Z-up) or Godot C# (script paths swapped); Unity .unity/.prefab → Godot .tscn (bodies, colliders, primitive meshes, cameras, lights, scripts, prefab instances). Transforms are converted between coordinate systems. With planId it writes the unit; with file+to it writes into the workspace.',
+    inputSchema: obj({ planId, unit, file: str('Scene file (without a plan).'), to: str('Target engine (without a plan).', { enum: engines }), out: str('Output file (without a plan).') }) },
+  { name: 'port_copy_assets', brief: 'Copy all asset units of a plan.', title: 'Copy all asset units',
+    description: 'Copies every pending asset unit (textures, audio, models, fonts, video) of a plan into the output project. match limits it with a regex.',
+    inputSchema: obj({ planId, match: str('Regex over source paths.') }, ['planId']) },
+  { name: 'port_status', brief: 'Port progress, or the list of plans.', title: 'Port progress',
+    description: 'Without planId: lists all port plans in the workspace with progress. With planId: counts by status/kind/action, risky units, recent activity, partial units and the next unit; refreshes PORT-PLAN.md in the output folder.',
+    inputSchema: obj({ planId }) },
+  { name: 'port_verify', brief: 'Check a port: missing files, leftovers, missing functions, markers.', title: 'Verify a port',
+    description: 'Checks a port: missing output files, units not ported yet, source-engine API leftovers, functions and signals from the source that do not exist in the port (lifecycle renames understood), PORT/TODO markers, partial units. passed is true only when everything is ported and clean.',
+    inputSchema: obj({ planId }, ['planId']) },
+  // ------------------------------------------------------------ for agents
+  { name: 'share_feedback', brief: 'Optional: tell the maintainers what helped or got in your way.', title: 'Tell the maintainers what helped or got in the way',
+    description: 'Optional, any time: note what worked, what was confusing or slow, and what would help next time. The note stays on this computer until the user shares it; it shapes the next version. It never changes your task.',
+    inputSchema: obj({ tool: str('Tool the note is about (if any).'), rating: int('How well it served the task, 1 (poorly) to 5 (very well).', { minimum: 1, maximum: 5 }), worked: str('What helped.'), friction: str('What got in the way: unclear text, wasted calls, too much output, errors without a next step…'), suggestion: str('What would help.'), agent: str('Who you are, if you like (client, model).') }) },
+];
+
+for (const t of tools) t.annotations = annotationsFor(t.name);
+
+const handlers = {
+  re_scan: scanProject, re_graph: graphTool, re_symbols: symbolsTool, re_scene: a => readScene(a.file), re_binary: inspectBinary,
+  re_archive: archiveTool, re_probe: probe, re_extract: carve, re_compare: compare, re_report: report, re_lookup: lookupTool, re_blueprint: blueprintTool,
+  port_map: portMapTool, port_convert: convert, port_plan: planPort, port_unit: portUnit, port_write: portWrite, port_scene: portScene,
+  port_copy_assets: portCopyAssets, port_status: portStatus, port_verify: portVerify, share_feedback: shareFeedback,
+};
+
+function validate(schema, args, where = 'arguments') {
+  if (schema.type === 'object') {
+    if (!args || typeof args !== 'object' || Array.isArray(args)) throw new RPError('INVALID_ARGUMENT', `${where} must be an object.`);
+    const allowed = Object.keys(schema.properties ?? {});
+    const unknown = Object.keys(args).filter(k => !schema.properties?.[k]);
+    if (unknown.length && schema.additionalProperties === false) {
+      const hints = unknown.map(k => { const near = closest(k, allowed, 3) ?? (schema.required ?? []).find(r => args[r] === undefined); return near ? `"${k}" (did you mean "${near}"?)` : `"${k}"`; });
+      throw new RPError('INVALID_ARGUMENT', `Unknown argument ${hints.join(', ')}${where === 'arguments' ? '' : ` in ${where}`}. Allowed: ${allowed.join(', ')}.`);
+    }
+    for (const r of schema.required ?? []) if (args[r] === undefined || args[r] === null || args[r] === '') {
+      const d = schema.properties?.[r]?.description;
+      throw new RPError('INVALID_ARGUMENT', `Missing ${r}${d ? ` (${d.replace(/\.$/, '')})` : ''}.`);
+    }
+    for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== null && schema.properties?.[k]) validate(schema.properties[k], v, k);
+    return;
+  }
+  if (schema.type === 'string') { if (typeof args !== 'string') throw new RPError('INVALID_ARGUMENT', `${where} must be a string.`); if (schema.enum && !schema.enum.includes(args)) throw new RPError('INVALID_ARGUMENT', `${where} must be one of ${schema.enum.join(', ')}.`); return; }
+  if (schema.type === 'integer') { if (!Number.isInteger(args)) throw new RPError('INVALID_ARGUMENT', `${where} must be an integer.`); if (schema.minimum !== undefined && args < schema.minimum) throw new RPError('INVALID_ARGUMENT', `${where} must be ≥ ${schema.minimum}.`); if (schema.maximum !== undefined && args > schema.maximum) throw new RPError('INVALID_ARGUMENT', `${where} must be ≤ ${schema.maximum}.`); return; }
+  if (schema.type === 'number') { if (typeof args !== 'number' || !Number.isFinite(args)) throw new RPError('INVALID_ARGUMENT', `${where} must be a number.`); return; }
+  if (schema.type === 'boolean') { if (typeof args !== 'boolean') throw new RPError('INVALID_ARGUMENT', `${where} must be true or false.`); return; }
+  if (schema.type === 'array') {
+    if (!Array.isArray(args)) throw new RPError('INVALID_ARGUMENT', `${where} must be an array.`);
+    if (schema.minItems !== undefined && args.length < schema.minItems) throw new RPError('INVALID_ARGUMENT', `${where} needs at least ${schema.minItems} items.`);
+    if (schema.maxItems !== undefined && args.length > schema.maxItems) throw new RPError('INVALID_ARGUMENT', `${where} allows at most ${schema.maxItems} items.`);
+    args.forEach((x, i) => validate(schema.items, x, `${where}[${i}]`));
+  }
+}
+
+export async function callTool(name, args = {}) {
+  const tool = tools.find(t => t.name === name);
+  if (!tool) throw new RPError('UNKNOWN_TOOL', `Unknown tool ${name}. Tools: ${tools.map(t => t.name).join(', ')}`);
+  const adjusted = {};
+  const input = coerce(tool.inputSchema, args ?? {}, adjusted, '');
+  validate(tool.inputSchema, input);
+  const result = await handlers[name](input);
+  return Object.keys(adjusted).length && result && typeof result === 'object' && !Array.isArray(result) ? { adjusted, ...result } : result;
+}
+
+/**
+ * Forgive the common slips of smaller models and strict-mode clients: "20" for 20, "true" for true, a JSON string for
+ * an object, null for "not given" (unless the schema allows null). Values that are still wrong fail validation.
+ */
+export function coerceArgs(schema, value) {
+  return coerce(schema, value, null, '');
+}
+
+const allowsNull = s => s && (s.type === 'null' || (Array.isArray(s.type) && s.type.includes('null')) || (s.anyOf ?? s.oneOf ?? []).some(x => x?.type === 'null'));
+
+function coerce(schema, value, adjusted = null, at = '') {
+  if (value === null || value === undefined) return value;
+  if (schema?.type === 'object' && typeof value === 'string' && /^\s*\{/.test(value)) { try { value = JSON.parse(value); } catch { return value; } }
+  if (schema?.type === 'object' && value && typeof value === 'object' && !Array.isArray(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) { if (v === null && !(schema.required ?? []).includes(k) && !allowsNull(schema.properties?.[k])) continue; out[k] = schema.properties?.[k] ? coerce(schema.properties[k], v, adjusted, at ? `${at}.${k}` : k) : v; }
+    return out;
+  }
+  if ((schema?.type === 'integer' || schema?.type === 'number') && adjusted && typeof value !== 'boolean') {
+    let n = typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)) ? Number(value) : value;
+    if (typeof n === 'number' && Number.isFinite(n)) {
+      if (schema.type === 'integer' && !Number.isInteger(n)) { n = Math.round(n); adjusted[at] = `rounded to ${n}`; }
+      if (schema.minimum !== undefined && n < schema.minimum) { adjusted[at] = `raised to the minimum ${schema.minimum}`; n = schema.minimum; }
+      if (schema.maximum !== undefined && n > schema.maximum) { adjusted[at] = `lowered to the maximum ${schema.maximum}`; n = schema.maximum; }
+      return n;
+    }
+  }
+  if ((schema?.type === 'integer' && typeof value === 'string' && /^-?\d+$/.test(value.trim())) || (schema?.type === 'number' && typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)))) return Number(value);
+  if (schema?.type === 'boolean' && (value === 'true' || value === 'false')) return value === 'true';
+  if (schema?.type === 'array' && Array.isArray(value)) return value.map((v, i) => coerce(schema.items, v, adjusted, `${at}[${i}]`));
+  return value;
+}
+
+/** OpenAI function-calling format. */
+export const openaiTools = () => formatTools(tools, 'openai');
+
+export function openapi(port) {
+  const paths = {};
+  for (const t of tools) {
+    paths[`/api/agent/tools/${t.name}`] = { post: { operationId: t.name, summary: t.title, description: t.description, requestBody: { required: true, content: { 'application/json': { schema: t.inputSchema } } }, responses: { 200: { description: 'Result', content: { 'application/json': { schema: { type: 'object' } } } }, 400: { description: 'Error' } } } };
+  }
+  return { openapi: '3.1.0', info: { title: 'ReversePort', version: VERSION, description: 'Reverse engineer anything. Port it anywhere. Local tools for agents.' }, servers: [{ url: `http://127.0.0.1:${port}` }], paths };
+}

package/port/src/util.mjs

@@ -0,0 +1,162 @@
+// Shared helpers: errors, file access with limits, hashing, entropy, walking a tree, naming.
+import fs from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+export class RPError extends Error {
+  constructor(code, message, details) { super(message); this.code = code; if (details) this.details = details; }
+}
+
+export const MiB = 1024 * 1024;
+
+/** Folders that never hold source a port needs (caches, build output, VCS, package stores). */
+export const IGNORED_DIRS = new Set([
+  '.git', '.svn', '.hg', 'node_modules', '.godot', '.import', 'Library', 'Temp', 'Logs', 'UserSettings', 'obj',
+  '__pycache__', '.venv', 'venv', '.gradle', '.idea', '.vs', '.vscode', 'DerivedDataCache', 'Intermediate', 'Saved',
+  '.mono', '.reverseport', '.cache', '.next', '.nuxt', '.parcel-cache', '.turbo', 'Pods', '.dart_tool',
+]);
+
+export async function statOrNull(file) { try { return await fs.stat(file); } catch { return null; } }
+
+export async function requireFile(file, what = 'file') {
+  if (typeof file !== 'string' || !file.trim()) throw new RPError('INVALID_ARGUMENT', `Give the ${what} path.`);
+  const abs = path.resolve(file);
+  const st = await statOrNull(abs);
+  if (!st) throw new RPError('NOT_FOUND', `${what} not found: ${abs}`);
+  if (!st.isFile()) throw new RPError('NOT_A_FILE', `Not a file: ${abs}`);
+  return { abs, size: st.size };
+}
+
+export async function requireDir(dir, what = 'folder') {
+  if (typeof dir !== 'string' || !dir.trim()) throw new RPError('INVALID_ARGUMENT', `Give the ${what} path.`);
+  const abs = path.resolve(dir);
+  const st = await statOrNull(abs);
+  if (!st) throw new RPError('NOT_FOUND', `${what} not found: ${abs}`);
+  if (!st.isDirectory()) throw new RPError('NOT_A_FOLDER', `Not a folder: ${abs}`);
+  return abs;
+}
+
+/** Read `length` bytes at `offset` (clamped to the file). */
+export async function readAt(file, offset, length) {
+  const fh = await fs.open(file, 'r');
+  try {
+    const buf = Buffer.alloc(Math.max(0, length));
+    const { bytesRead } = await fh.read(buf, 0, buf.length, offset);
+    return buf.subarray(0, bytesRead);
+  } finally { await fh.close(); }
+}
+
+/** Read the start of a file, at most `max` bytes. */
+export async function readHead(file, max) {
+  const st = await fs.stat(file);
+  return readAt(file, 0, Math.min(st.size, max));
+}
+
+export function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    createReadStream(file).on('data', d => hash.update(d)).on('error', reject).on('end', () => resolve(hash.digest('hex')));
+  });
+}
+
+export const sha256 = buf => crypto.createHash('sha256').update(buf).digest('hex');
+
+/** Shannon entropy in bits per byte (0 = constant, 8 = random/compressed/encrypted). */
+export function entropy(buf) {
+  if (!buf?.length) return 0;
+  const counts = new Uint32Array(256);
+  for (let i = 0; i < buf.length; i++) counts[buf[i]]++;
+  let e = 0;
+  for (const c of counts) if (c) { const p = c / buf.length; e -= p * Math.log2(p); }
+  return Math.round(e * 1000) / 1000;
+}
+
+/** Heuristic: is this buffer text (UTF-8/ASCII) rather than binary? */
+export function isText(buf) {
+  const n = Math.min(buf.length, 8192);
+  if (!n) return true;
+  let odd = 0;
+  for (let i = 0; i < n; i++) {
+    const b = buf[i];
+    if (b === 0) return false;
+    if (b < 7 || (b > 13 && b < 32 && b !== 27)) odd++;
+  }
+  return odd / n < 0.02;
+}
+
+export const toPosix = p => p.split(path.sep).join('/');
+
+/** Walk a folder. Returns files with posix relative paths; skips IGNORED_DIRS and symlinks. */
+export async function walk(root, { maxFiles = 50000, ignore = IGNORED_DIRS, maxDepth = 40 } = {}) {
+  const files = [];
+  const skipped = new Set();
+  const unreadable = [];
+  let truncated = false;
+  async function visit(dir, depth) {
+    if (truncated || depth > maxDepth) return;
+    let entries;
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch (e) { if (unreadable.length < 50) unreadable.push({ path: toPosix(path.relative(root, dir)) || '.', code: e.code ?? 'ERROR' }); return; }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      if (truncated) return;
+      const abs = path.join(dir, e.name);
+      if (e.isSymbolicLink()) continue;
+      if (e.isDirectory()) {
+        if (ignore.has(e.name)) { skipped.add(toPosix(path.relative(root, abs))); continue; }
+        await visit(abs, depth + 1);
+      } else if (e.isFile()) {
+        if (files.length >= maxFiles) { truncated = true; return; }
+        let size = 0;
+        try { size = (await fs.stat(abs)).size; } catch { continue; }
+        files.push({ rel: toPosix(path.relative(root, abs)), abs, size, ext: path.extname(e.name).toLowerCase() });
+      }
+    }
+  }
+  await visit(root, 0);
+  return { files, truncated, skippedDirs: [...skipped].sort(), unreadable };
+}
+
+export function limit(list, max) {
+  return list.length > max ? { items: list.slice(0, max), truncated: true, total: list.length } : { items: list, truncated: false, total: list.length };
+}
+
+export const countLines = text => (text ? text.split('\n').length - (text.endsWith('\n') ? 1 : 0) : 0);
+
+const words = s => String(s).replace(/\.[^.]+$/, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/).filter(Boolean);
+export const pascalCase = s => words(s).map(w => w[0].toUpperCase() + w.slice(1)).join('') || 'Unnamed';
+export const camelCase = s => { const p = pascalCase(s); return p[0].toLowerCase() + p.slice(1); };
+export const kebabCase = s => words(s).map(w => w.toLowerCase()).join('-') || 'unnamed';
+export const snakeCase = s => words(s).map(w => w.toLowerCase()).join('_') || 'unnamed';
+/** Name key used to compare symbols across languages: `_physics_process`, `PhysicsProcess`, `physicsProcess` → `physicsprocess`. */
+export const nameKey = s => String(s).replace(/[^A-Za-z0-9]/g, '').toLowerCase();
+
+export const hex = (n, width = 0) => '0x' + Number(n).toString(16).padStart(width, '0');
+
+export function compileMatcher(match) {
+  if (!match) return () => true;
+  if (typeof match !== 'string' || match.length > 300) throw new RPError('INVALID_ARGUMENT', 'match must be a string (≤ 300 chars).');
+  if (match.startsWith('/') && match.lastIndexOf('/') > 0) {
+    const end = match.lastIndexOf('/');
+    let re;
+    try { re = new RegExp(match.slice(1, end), match.slice(end + 1).replace(/[^imsu]/g, '')); } catch (e) { throw new RPError('INVALID_ARGUMENT', `Bad regular expression: ${e.message}`); }
+    return s => re.test(s);
+  }
+  if (/[*?]/.test(match)) {
+    const re = new RegExp('^' + match.split('').map(c => (c === '*' ? '.*' : c === '?' ? '.' : c.replace(/[.+^${}()|[\]\\]/g, '\\$&'))).join('') + '$', 'i');
+    return s => re.test(s) || re.test(s.split('/').pop());
+  }
+  const needle = match.toLowerCase();
+  return s => s.toLowerCase().includes(needle);
+}
+
+export async function readJson(file, fallback) {
+  try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return fallback; }
+}
+
+export async function writeJson(file, value) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(value, null, 2) + '\n');
+  await fs.rename(tmp, file);
+}