agy-plugin-porter 0.1.0 → 0.2.0

package/lib/mod-compiler.mjs

@@ -0,0 +1,210 @@
+// Compiles Claude Code UI mods into Antigravity plugin sidecars (plan §5, §6). Each
+// module listed under a hooks config's "modules" becomes sidecars/<id>/: the porter's
+// runtime (scripts/mod-runtime/), the transformed mod and a mod.json with what the
+// static scan found. It also writes the mod's MCP server, one skill per command and
+// the hooks that forward agy events to the sidecar.
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { remapMatcher } from './hook-compiler.mjs';
+import { assess, importsOf, scanMod } from './mod-scan.mjs';
+import { collectGraph, loadEsbuild, needsTransform, outName, transformFile } from './mod-transform.mjs';
+import { slugifyName } from './skill-compiler.mjs';
+import { unmappedToolReason } from './tool-map.mjs';
+
+export const RUNTIME_DIR = fileURLToPath(new URL('../scripts/mod-runtime/', import.meta.url));
+const LICENSES = ['LICENSE', 'LICENSE.md', 'LICENSE.txt', 'COPYING'];
+
+const readJsonIf = (file) => { try { return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null; } catch { return null; } };
+const writeJson = (file, value) => { mkdirSync(dirname(file), { recursive: true }); writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`); };
+
+// The agy hooks a scanned mod needs (plan §5.4). Returns {events, unmapped}.
+export function modHooks(scan, id, ownMcpServer = null) {
+  const has = (name) => scan.events.some((e) => e.event === name);
+  const cmd = (event, timeout) => ({ type: 'command', command: `agy-node sidecars/${id}/hook.mjs ${event}`, timeout });
+  const ownPrefix = ownMcpServer ? `mcp__${ownMcpServer}__` : null;
+  const ownToolNames = new Set((scan.tools ?? []).map((t) => t.name));
+  const isOwnMcpTool = (t) => {
+    if (!t.startsWith('mcp__')) return false;
+    if (ownPrefix && t.startsWith(ownPrefix)) return true;
+    const parts = t.split('__');
+    return parts.length >= 3 && ownToolNames.has(parts.slice(2).join('__'));
+  };
+  const calls = scan.events.filter((e) => e.event === 'tool.call');
+  const tools = new Set();
+  const unmapped = [];
+  for (const call of calls) {
+    const rawMatcher = String(call.matcher?.tool ?? '*').trim() || '*';
+    const alts = rawMatcher.split('|').map((a) => a.trim()).filter((a) => a && !isOwnMcpTool(a));
+    if (alts.length === 0) continue;
+    const remap = remapMatcher(alts.join('|'), 'claude');
+    unmapped.push(...remap.unmapped);
+    for (const t of remap.matcher?.split('|') ?? []) tools.add(t);
+  }
+  // SessionStart, PreInvocation and Stop are flat; tool events are grouped by matcher.
+  const events = { SessionStart: [cmd('SessionStart', 5)] };
+  const perTurn = has('turn.start') || has('prompt.context');
+  if (perTurn) events.PreInvocation = [cmd('PreInvocation', 5)];
+  if (tools.size) {
+    const matcher = tools.has('*') ? '*' : [...tools].sort().join('|');
+    events.PreToolUse = [{ matcher, hooks: [cmd('PreToolUse', 10)] }];
+    events.PostToolUse = [{ matcher, hooks: [cmd('PostToolUse', 10)] }];
+  }
+  // Stop ends the turn, so the next PreInvocation counts as a turn's first (live, 2.5B)
+  if (perTurn || has('turn.complete') || tools.size) events.Stop = [cmd('Stop', 5)];
+  return { events, unmapped: [...new Set(unmapped)] };
+}
+
+function skillFor(c, { title, slug, id }) {
+  return [
+    '---',
+    `name: ${slugifyName(c.name)}`,
+    `description: Runs the /${c.name} command of the ${title} mod.${c.description ? ` ${c.description}` : ''} Use when the user types /${c.name} or asks for ${title}.`.replace(/\s+/g, ' '),
+    '---',
+    '',
+    `# /${c.name}`,
+    '',
+    `This command belongs to ${title}, a Claude Code mod ported to Antigravity. Its pane is at \`sidecar://${slug}/${id}/ui.html\`.`,
+    '',
+    `1. Call the \`slash_${c.name}\` tool. Pass the text after \`/${c.name}\` as \`args\`${c.argumentHint ? ` (${c.argumentHint})` : ''}, or an empty string.`,
+    "2. Reply with the tool's text. It ends with a `sidecar://` link that opens the pane: put that link on its own line, exactly as given.",
+    '',
+  ].join('\n');
+}
+
+// Writes one compiled mod into pluginDir. Returns its MCP server name, or null.
+function emit(pluginDir, { id, files, transformed, scan, verdict, meta, report, item }) {
+  const side = join(pluginDir, 'sidecars', id);
+  rmSync(side, { recursive: true, force: true });
+  mkdirSync(join(side, 'mod'), { recursive: true });
+  for (const f of readdirSync(RUNTIME_DIR)) copyFileSync(join(RUNTIME_DIR, f), join(side, f));
+  files.forEach((f, i) => { const out = join(side, 'mod', outName(f.rel)); mkdirSync(dirname(out), { recursive: true }); writeFileSync(out, transformed[i]); });
+  const license = LICENSES.find((l) => existsSync(join(meta.srcDir, l)));
+  if (license) copyFileSync(join(meta.srcDir, license), join(side, 'mod', license));
+
+  const hasServer = scan.tools.length > 0 || scan.commands.length > 0;
+  const config = readJsonIf(join(pluginDir, 'mcp_config.json')) ?? { mcpServers: {} };
+  config.mcpServers ??= {};
+  let mcpServer = meta.mcpServer;
+  if (hasServer && Object.hasOwn(config.mcpServers, mcpServer)) {
+    report.warnings.push(`${item}: an MCP server named ${mcpServer} exists already, so the mod's is ${mcpServer}-mod and its mcp__${mcpServer}__* tool names change`);
+    mcpServer = `${mcpServer}-mod`;
+  }
+  writeJson(join(side, 'mod.json'), {
+    plugin: meta.slug, sidecar: id, title: meta.title, pluginName: meta.sourceName, version: meta.version, mcpServer,
+    entry: `mod/${outName(meta.entryRel)}`, hasPane: verdict.hasPane, allow: [...scan.calls].sort(), options: meta.options,
+    commands: scan.commands, tools: scan.tools, verdict: verdict.verdict, tier: verdict.tier, tierReasons: verdict.tierReasons,
+  });
+  writeJson(join(side, 'sidecar.json'), {
+    command: 'node', args: ['server.mjs'], description: `${meta.title}, a Claude Code mod ported by agy-plugin-porter.`,
+    display_name: meta.title, has_web_ui: true, restart_policy: 'always',
+    ui_config: { display_name: meta.title, views: [{ entrypoint: 'SIDECAR_UI_ENTRYPOINT_AUX_PANE', path: '/ui.html', title: meta.title }] },
+  });
+  if (hasServer) {
+    config.mcpServers[mcpServer] = { command: 'agy-node', args: [`\${PLUGIN_ROOT}/sidecars/${id}/mcp-entry.mjs`] };
+    writeJson(join(pluginDir, 'mcp_config.json'), config);
+    report.ported.push(`mcp:${mcpServer}`);
+  }
+  for (const c of scan.commands) {
+    const file = join(pluginDir, 'skills', slugifyName(c.name), 'SKILL.md');
+    mkdirSync(dirname(file), { recursive: true });
+    try {
+      writeFileSync(file, skillFor(c, { title: meta.title, slug: meta.slug, id }), { flag: 'wx' }); // never replaces the plugin's own skill
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      report.warnings.push(`${item}: skills/${slugifyName(c.name)} exists already, so /${c.name} has no skill (the pane's button still runs it)`);
+      continue;
+    }
+    report.ported.push(`command:/${c.name}`);
+  }
+  const hooks = modHooks(scan, id, mcpServer);
+  for (const name of hooks.unmapped) report.unported.push({ item: `${item} tool.call ${name}`, reason: unmappedToolReason(name) });
+  const all = readJsonIf(join(pluginDir, 'hooks.json')) ?? {};
+  all[`${meta.slug}-mod-${id}`] = hooks.events;
+  writeJson(join(pluginDir, 'hooks.json'), all);
+}
+
+// A Claude manifest's userConfig defaults, which Claude Code passes to register(on,
+// options). Antigravity has no settings UI for them, so the port uses the defaults.
+export function userConfigDefaults(userConfig) {
+  if (!userConfig || typeof userConfig !== 'object') return {};
+  return Object.fromEntries(Object.entries(userConfig).filter(([, v]) => v && typeof v === 'object' && 'default' in v).map(([k, v]) => [k, v.default]));
+}
+
+// uiMods: detect()'s list ({path, modules}). Returns {ported, unported, warnings}.
+export function compileMods(uiMods, { srcDir, pluginDir, slug, sourceName, title, version, esbuild, options = {} }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const entries = uiMods.flatMap((mod) => mod.modules.map((m) => posix.normalize(posix.join(posix.dirname(mod.path.split('#')[0]), String(m)))));
+  let esb = esbuild;
+  const getEsbuild = () => (esb === undefined ? (esb = loadEsbuild()) : esb);
+  const name = sourceName || slug;
+  const ids = new Set();
+  entries.forEach((entryRel, n) => {
+    const item = `ui-mod:${entryRel}`;
+    const stem = posix.basename(entryRel).replace(/\.[^.]+$/, '');
+    let id = entries.length === 1 ? 'pane' : `pane-${slugifyName(stem)}`;
+    if (ids.has(id)) id = `${id}-${n + 1}`;
+    ids.add(id);
+    let files;
+    let transformed;
+    try {
+      files = collectGraph(srcDir, entryRel);
+    } catch (err) {
+      report.unported.push({ item, reason: `can't read the mod: ${err.message}` });
+      return;
+    }
+    for (const f of files) rmSync(join(pluginDir, f.rel), { force: true }); // agy staged the raw source
+    const scan = scanMod(files.map((f) => ({ path: f.rel, src: f.src })));
+    const verdict = assess(scan);
+    if (verdict.verdict === 'refused') {
+      report.unported.push({ item, reason: `not ported: it ${verdict.refusals.join('; it ')}` });
+      return;
+    }
+    try {
+      const tool = needsTransform(files) ? getEsbuild() : null;
+      transformed = files.map((f) => transformFile(srcDir, f, tool));
+    } catch (err) {
+      report.unported.push({ item, reason: err.message });
+      return;
+    }
+    if (entries.length > 1) report.warnings.push(`${item}: one of several mods, so its MCP server is ${name}-${id}`);
+    const meta = {
+      srcDir, slug, sourceName: name, title: entries.length === 1 ? title || name : `${title || name} (${stem})`,
+      version: version ?? '0.0.0', entryRel, mcpServer: entries.length === 1 ? name : `${name}-${id}`, options,
+    };
+    if (Object.keys(options).length) report.warnings.push(`${item}: userConfig (${Object.keys(options).join(', ')}) uses its defaults; Antigravity has no settings for it`);
+    emit(pluginDir, { id, files, transformed, scan, verdict, meta, report, item });
+    report.ported.push(`${item} (${verdict.verdict}, sidecar ${id}, sidecar://${slug}/${id}/ui.html)`);
+    for (const f of verdict.findings) {
+      if (f.level === 'none') report.unported.push({ item: `${item} ${f.item}`, reason: f.reason });
+      else report.warnings.push(`${item}: ${f.item}${f.level === 'partial' ? ' is partial' : ''}: ${f.reason}`);
+    }
+    for (const w of verdict.warnings) report.warnings.push(`${item}: ${w}`);
+  });
+  if (entries.length) dropModLeftovers(pluginDir, entries, report);
+  return report;
+}
+
+const CODE = /\.(m?[jt]sx?|cjs|mts)$/;
+const walk = (dir, rel = '') => readdirSync(join(dir, rel), { withFileTypes: true }).flatMap((e) => {
+  const path = rel ? `${rel}/${e.name}` : e.name;
+  if (e.isDirectory()) return ['sidecars', 'node_modules', '.git'].includes(path) ? [] : walk(dir, path);
+  return [path];
+});
+
+// Staged files that only run inside Claude Code: the mod's tests and helpers that
+// import 'claude-code' (or 'claude-code/testing') or the mod, and its tsconfig.json. The ported mod lives in
+// sidecars/ now, so these would ship raw source nothing can run.
+function dropModLeftovers(pluginDir, entries, report) {
+  const modFiles = new Set(entries);
+  const dropped = [];
+  for (const rel of walk(pluginDir).filter((p) => CODE.test(p))) {
+    let specs;
+    try { specs = importsOf(readFileSync(join(pluginDir, rel), 'utf8')); } catch { continue; }
+    const usesMod = specs.some((s) => s === 'claude-code' || s.startsWith('claude-code/') || (/^\.{1,2}\//.test(s) && [...modFiles].some((m) => posix.normalize(posix.join(posix.dirname(rel), s)).replace(/\.[^./]+$/, '') === m.replace(/\.[^./]+$/, ''))));
+    if (usesMod) { rmSync(join(pluginDir, rel), { force: true }); dropped.push(rel); }
+  }
+  if (existsSync(join(pluginDir, 'tsconfig.json'))) { rmSync(join(pluginDir, 'tsconfig.json')); dropped.push('tsconfig.json'); }
+  if (dropped.length) report.warnings.push(`dropped files that only run inside Claude Code: ${dropped.sort().join(', ')}`);
+}

package/lib/mod-lexer.mjs

@@ -0,0 +1,143 @@
+// A small JS/TS lexer for the mod scanner. It doesn't parse: it blanks comments and
+// the insides of strings, template text and regex literals, so structure (on(...),
+// $.noun.method, brackets) can be matched with plain regexes on the result, and
+// literal values read back from the source at the same offsets.
+// A `/` after one of these starts a regex. `<` is left out so JSX's `</Tag>` stays code.
+const REGEX_BEFORE = /[(,=:[!&|?{};+\-*%~^]$|(?:^|[^\w$])(?:return|typeof|case|do|else|in|of|void|yield|await)$/;
+
+export function blank(src) {
+  const out = src.split('');
+  const fill = (from, to) => { for (let k = from; k < to; k++) if (out[k] !== '\n') out[k] = ' '; };
+  const templates = []; // brace depth at each open `${`
+  let depth = 0;
+  let i = 0;
+  const skipString = (q) => {
+    const start = i++;
+    while (i < src.length && src[i] !== q && src[i] !== '\n') i += src[i] === '\\' ? 2 : 1;
+    fill(start + 1, i);
+    i++;
+  };
+  // Template text from i (just past ` or }) to the closing ` or the next ${.
+  const skipTemplate = () => {
+    const start = i;
+    while (i < src.length && src[i] !== '`' && !(src[i] === '$' && src[i + 1] === '{')) i += src[i] === '\\' ? 2 : 1;
+    fill(start, i);
+    if (src[i] === '`') { i++; return; }
+    templates.push(depth);
+    depth++;
+    i += 2;
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') {
+      const end = src.indexOf('\n', i);
+      fill(i, end < 0 ? src.length : end);
+      i = end < 0 ? src.length : end;
+    } else if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      fill(i, end < 0 ? src.length : end + 2);
+      i = end < 0 ? src.length : end + 2;
+    } else if (c === '"' || c === "'") {
+      skipString(c);
+    } else if (c === '`') {
+      i++;
+      skipTemplate();
+    } else if (c === '/' && REGEX_BEFORE.test(out.slice(Math.max(0, i - 12), i).join('').trimEnd() || ';')) {
+      const start = i++;
+      let inClass = false;
+      while (i < src.length && src[i] !== '\n' && (inClass || src[i] !== '/')) {
+        if (src[i] === '\\') i++;
+        else if (src[i] === '[') inClass = true;
+        else if (src[i] === ']') inClass = false;
+        i++;
+      }
+      fill(start + 1, i);
+      i++;
+    } else {
+      if (c === '{') depth++;
+      else if (c === '}') {
+        depth--;
+        if (templates.length && templates.at(-1) === depth) {
+          templates.pop();
+          i++;
+          skipTemplate();
+          continue;
+        }
+      }
+      i++;
+    }
+  }
+  return out.join('');
+}
+
+const PAIRS = { '(': ')', '[': ']', '{': '}' };
+
+// Index of the bracket that closes the one at `open` in blanked code, or -1.
+export function closeOf(code, open) {
+  const stack = [];
+  for (let i = open; i < code.length; i++) {
+    const c = code[i];
+    if (PAIRS[c]) stack.push(PAIRS[c]);
+    else if (c === ')' || c === ']' || c === '}') {
+      if (stack.pop() !== c) return -1;
+      if (!stack.length) return i;
+    }
+  }
+  return -1;
+}
+
+// The string literal whose opening quote is at `at` in code: {value, end} or null.
+// Template literals count only without ${...} parts.
+export function literalAt(code, src, at) {
+  const q = code[at];
+  if (q !== '"' && q !== "'" && q !== '`') return null;
+  const end = code.indexOf(q, at + 1);
+  if (end < 0) return null;
+  const body = src.slice(at + 1, end);
+  if (q === '`' && body.includes('${')) return null;
+  const value = body.replace(/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[\s\S])/g, (_, e) => {
+    if (e[0] === 'u' || e[0] === 'x') return String.fromCodePoint(Number.parseInt(e.replace(/[ux{}]/g, ''), 16));
+    return { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', 0: '\0', '\n': '' }[e] ?? e;
+  });
+  return { value, end };
+}
+
+// Top-level fields of the object literal at `open` (a `{` in code). Each value is
+// {literal}, {ident} or {other}.
+export function objectFields(code, src, open) {
+  const close = closeOf(code, open);
+  const fields = {};
+  if (close < 0) return fields;
+  let i = open + 1;
+  while (i < close) {
+    const key = /^\s*(?:([A-Za-z_$][\w$]*)|(["']))\s*/.exec(code.slice(i, close));
+    if (!key) break;
+    let name = key[1];
+    let j = i + key[0].length;
+    if (!name) {
+      const lit = literalAt(code, src, i + key[0].indexOf(key[2]));
+      if (!lit) break;
+      name = lit.value;
+      j = lit.end + 1;
+      j += /^\s*/.exec(code.slice(j))[0].length;
+    }
+    let end = j;
+    if (code[j] === ':') {
+      end = j + 1 + /^\s*/.exec(code.slice(j + 1))[0].length;
+      const lit = literalAt(code, src, end);
+      const ident = /^[A-Za-z_$][\w$]*/.exec(code.slice(end));
+      const after = (k) => /^\s*(?:as\s+const\s*)?[,}]/.test(code.slice(k, close + 1));
+      if (lit && after(lit.end + 1)) fields[name] = { literal: lit.value };
+      else if (ident && after(end + ident[0].length)) fields[name] = { ident: ident[0] };
+      else fields[name] = { other: true };
+    } else {
+      fields[name] = { ident: name }; // shorthand { name }
+    }
+    // Skip to the next top-level comma.
+    for (let k = end; k <= close; k++) {
+      if (PAIRS[code[k]]) { k = closeOf(code, k); if (k < 0) return fields; continue; }
+      if (code[k] === ',' || k === close) { i = k + 1; break; }
+    }
+  }
+  return fields;
+}

package/lib/mod-scan.mjs

@@ -0,0 +1,169 @@
+// Static scan of a Claude Code UI mod. Claude Code reads `on(...)` and
+// `$.noun.method(...)` literally from a mod's source (blast-radius's header), so the
+// porter can list a mod's events, host calls, commands, tools and render sites
+// without running it, then judge how well it ports (plan §5.5, §5.6).
+import { blank, closeOf, literalAt, objectFields } from './mod-lexer.mjs';
+
+// Antigravity's side of each Claude event (plan §5.4, scorecard in ui-mods-baseline.md).
+const EVENTS = {
+  'session.start': null,
+  'turn.start': null,
+  'turn.complete': null,
+  'tool.call': null,
+  'ui.render': null,
+  'command.run': ['partial', 'a generated skill calls its slash_<name> tool (one model turn), plus a button in the pane'],
+  'tool.describe': ['partial', 'applied once at tools/list; isDeferred has no equivalent'],
+  'prompt.context': ['partial', 'added once per turn as a systemMessage step, which shows in the transcript'],
+  'ui.close': ['partial', "only the pane's own × reports a close; closing Antigravity's pane tab sends nothing"],
+  'prompt.submit': ['none', 'agy has no user-prompt event'],
+  'prompt.compose': ['none', 'agy has no user-prompt event'],
+};
+const WORKS = new Set(['ui.resolve', 'ui.invalidate', 'ui.close', 'ui.toast', 'ui.status', 'ui.copy', 'store.keys', 'store.get',
+  'store.set', 'store.delete', 'state.get', 'state.set', 'clock.now', 'fs.read', 'session.cwd', 'session.id',
+  'command.register', 'tool.register', 'plugin.name']);
+const PARTIAL = {
+  'ui.open': 'only the person can show the pane, through a sidecar:// link or its tab',
+  'ui.panes': 'isPlaced and isShown count only views the person can see',
+  'prompt.fill': 'copies the text and asks the person to paste it; it never drafts or sends',
+};
+const NO_OPS = new Set(['ui.blit', 'ui.selection', 'session.messages']);
+const NO_OP_NOUNS = new Set(['model', 'agent']);
+const TIER3 = [/^process\.run$/, /^fs\.write$/, /^http\./, /^prompt\./];
+// Every ported pane mod gets these; they don't make a port partial (scorecard: task-board is clean).
+const FALLBACKS = new Set(['event command.run', '$.ui.open']);
+const SITES = { Pane: null, AbovePrompt: 'drawn as a strip above the pane', PromptHint: 'drawn as a strip above the pane' };
+
+export const isTranscriptSite = (component) => component !== '*' && !Object.hasOwn(SITES, component);
+
+function constants(code, src) {
+  const out = {};
+  for (const m of code.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?=['"`])/g)) {
+    const lit = literalAt(code, src, m.index + m[0].length);
+    if (lit && /^\s*(?:as\s+const\s*)?(?:;|\n|$)/.test(code.slice(lit.end + 1))) out[m[1]] = lit.value;
+  }
+  return out;
+}
+
+const valueOf = (field, consts) => (field?.literal !== undefined ? field.literal : field?.ident && Object.hasOwn(consts, field.ident) ? consts[field.ident] : undefined);
+
+// Specifiers a file imports at runtime (type-only imports are erased by the transform).
+export function importsOf(src) {
+  const code = blank(src);
+  const out = [];
+  const at = (i) => literalAt(code, src, i)?.value;
+  // The clause between the keyword and the next quote is checked with plain string
+  // tests, not one backtracking regex: `import x from 'y'`, `import 'y'`, `export * from 'y'`.
+  for (const m of code.matchAll(/\b(import|export)\b/g)) {
+    const start = m.index + m[0].length;
+    const quote = [code.indexOf("'", start), code.indexOf('"', start)].filter((i) => i >= 0);
+    if (!quote.length) continue;
+    const q = Math.min(...quote);
+    const clause = code.slice(start, q);
+    if (!/^[\w$*{}\s,]*$/.test(clause)) continue;
+    const from = /\bfrom\s*$/.test(clause);
+    if (m[1] === 'export' ? !from : !from && clause.trim() !== '') continue;
+    if (/^\s+type\s/.test(clause)) continue; // type-only
+    const spec = at(q);
+    if (spec !== undefined) out.push(spec);
+  }
+  for (const m of code.matchAll(/(?<![\w$.])(?:import|require)\s*\(\s*(?=['"`])/g)) {
+    const spec = at(m.index + m[0].length);
+    if (spec !== undefined) out.push(spec);
+  }
+  return out;
+}
+
+// files: [{path, src}], the mod's module and the helpers it imports.
+export function scanMod(files) {
+  const scan = { events: [], calls: new Set(), commands: [], tools: [], renderSites: new Set(), imports: [], warnings: [], steersBuiltinTools: false };
+  for (const { path, src } of files) {
+    const code = blank(src);
+    const consts = constants(code, src);
+    for (const spec of importsOf(src)) scan.imports.push({ file: path, spec });
+
+    for (const m of code.matchAll(/(?<![\w$.])on\(\s*(?=['"])/g)) {
+      const lit = literalAt(code, src, m.index + m[0].length);
+      if (!lit) continue;
+      const paren = code.lastIndexOf('(', m.index + m[0].length);
+      const close = closeOf(code, paren);
+      const rest = /^\s*,\s*/.exec(code.slice(lit.end + 1));
+      const matcher = {};
+      if (rest && code[lit.end + 1 + rest[0].length] === '{') {
+        for (const [k, f] of Object.entries(objectFields(code, src, lit.end + 1 + rest[0].length))) {
+          const v = valueOf(f, consts);
+          matcher[k] = v ?? null;
+          if (v === undefined) scan.warnings.push(`${path}: on('${lit.value}') matcher "${k}" isn't a literal`);
+        }
+      }
+      const body = close > 0 ? code.slice(lit.end, close) : '';
+      scan.events.push({ event: lit.value, matcher, file: path });
+      if (lit.value === 'ui.render') scan.renderSites.add(matcher.component ?? '*');
+      const builtin = lit.value === 'tool.call' && !String(matcher.tool ?? '').startsWith('mcp__');
+      if (builtin && /\bdeny\s*:|\bnext\(\s*\{/.test(body)) scan.steersBuiltinTools = true;
+    }
+
+    for (const m of code.matchAll(/(?<![\w$.])\$\s*\.\s*([A-Za-z_$][\w$]*)(?:\s*\.\s*([A-Za-z_$][\w$]*))?/g)) {
+      if (m[2]) scan.calls.add(`${m[1]}.${m[2]}`);
+      else scan.warnings.push(`${path}: $.${m[1]} is used without a method, so its calls can't be scanned and will throw`);
+    }
+    if (/(?<![\w$.])\$\s*\[/.test(code) || /\}\s*=\s*\$(?![\w$.])/.test(code)) {
+      scan.warnings.push(`${path}: $ is accessed dynamically; calls the scan can't see will throw`);
+    }
+
+    for (const [kind, list] of [['command', scan.commands], ['tool', scan.tools]]) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])\\$\\.${kind}\\.register\\(\\s*`, 'g'))) {
+        const at = m.index + m[0].length;
+        if (code[at] !== '{') { scan.warnings.push(`${path}: a $.${kind}.register argument isn't an object literal`); continue; }
+        const f = objectFields(code, src, at);
+        const def = { name: valueOf(f.name, consts), description: valueOf(f.description, consts), argumentHint: valueOf(f.argumentHint, consts) };
+        if (typeof def.name !== 'string') { scan.warnings.push(`${path}: a $.${kind}.register name isn't a literal`); continue; }
+        if (kind === 'tool') delete def.argumentHint;
+        if (!list.some((d) => d.name === def.name)) list.push(Object.fromEntries(Object.entries(def).filter(([, v]) => typeof v === 'string')));
+      }
+    }
+  }
+  // The runtime's 'claude-code' stand-in keeps atoms in $.state.
+  if (scan.imports.some((i) => i.spec === 'claude-code')) { scan.calls.add('state.get'); scan.calls.add('state.set'); }
+  scan.warnings = [...new Set(scan.warnings)];
+  return scan;
+}
+
+// Verdict, per-item findings and tier for a scan. `findings` are {item, level, reason}:
+// 'fallback' (every pane mod gets it, and the scorecard still calls the mod clean),
+// 'partial' or 'none'.
+export function assess(scan) {
+  const findings = [];
+  const refusals = [];
+  const add = (item, level, reason) => { if (FALLBACKS.has(item)) level = 'fallback'; if (!findings.some((f) => f.item === item)) findings.push({ item, level, reason }); };
+  for (const { event } of scan.events) {
+    const known = Object.hasOwn(EVENTS, event) ? EVENTS[event] : ['none', 'no Antigravity equivalent; the handler never runs'];
+    if (known) add(`event ${event}`, ...known);
+  }
+  for (const call of scan.calls) {
+    const [noun] = call.split('.');
+    if (WORKS.has(call)) continue;
+    if (Object.hasOwn(PARTIAL, call)) add(`$.${call}`, 'partial', PARTIAL[call]);
+    else if (NO_OPS.has(call) || NO_OP_NOUNS.has(noun)) add(`$.${call}`, 'partial', 'returns nothing in the Antigravity port');
+    else add(`$.${call}`, 'none', 'not available in the Antigravity port (calls reject)');
+  }
+  const sites = [...scan.renderSites];
+  for (const site of sites) {
+    if (isTranscriptSite(site)) add(`render ${site}`, 'none', 'transcript render sites have no Antigravity equivalent');
+    else if (SITES[site]) add(`render ${site}`, 'partial', SITES[site]);
+  }
+  if (sites.length && sites.every(isTranscriptSite)) {
+    refusals.push(`draws only into transcript sites (${sites.join(', ')}), which Antigravity has no equivalent for`);
+  }
+  const bare = [...new Set(scan.imports.filter((i) => !/^\.{1,2}\//.test(i.spec) && i.spec !== 'claude-code').map((i) => i.spec))];
+  if (bare.length) refusals.push(`imports ${bare.join(', ')}, which a ported mod can't load (only relative files and 'claude-code')`);
+  const hasPane = scan.renderSites.has('Pane') || scan.renderSites.has('*');
+  const warnings = [...scan.warnings];
+  if (!hasPane && sites.some((s) => SITES[s])) warnings.push('no Pane: AbovePrompt/PromptHint draw only while the pane is open');
+
+  const tierReasons = ['a sidecar is a full Node process outside agy\'s permission prompts'];
+  for (const call of scan.calls) if (TIER3.some((re) => re.test(call))) tierReasons.push(`$.${call}`);
+  if (scan.steersBuiltinTools) tierReasons.push('tool.call can deny or rewrite built-in tool calls');
+  const tier = tierReasons.length > 1 ? 'TIER_3_AGENT_CONTROL' : 'TIER_2_LOCAL_TOOLING';
+  const verdict = refusals.length ? 'refused' : findings.some((f) => f.level !== 'fallback') ? 'partial' : 'clean';
+  return { verdict, refusals, findings, warnings, hasPane, tier, tierReasons };
+}

package/lib/mod-transform.mjs

@@ -0,0 +1,84 @@
+// Collects a UI mod's module graph and turns it into files a sidecar can import.
+// TS/TSX/JSX go through esbuild, an optional dependency of the porter loaded only for
+// them (plan §5.8, picked by the 2.5A scorecard). Plain .js/.mjs mods need nothing.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { extname, join, posix, relative } from 'node:path';
+
+import { importsOf } from './mod-scan.mjs';
+
+export const NEEDS_TRANSFORM = new Set(['.ts', '.tsx', '.jsx', '.mts']);
+const TRY_EXT = ['', '.ts', '.tsx', '.js', '.mjs', '.jsx', '/index.ts', '/index.tsx', '/index.js', '/index.mjs'];
+
+// esbuild, or null when it isn't installed.
+export function loadEsbuild() {
+  try { return createRequire(import.meta.url)('esbuild'); } catch { return null; }
+}
+
+const isFile = (p) => existsSync(p) && statSync(p).isFile();
+
+// Resolves a relative specifier from `fromRel` (posix, relative to root). A `.js`
+// specifier may name a `.ts` file (TypeScript's convention). Type declarations
+// (.d.ts) resolve to null: imports of them are erased by the transform.
+export function resolveSpec(root, fromRel, spec) {
+  const base = posix.normalize(posix.join(posix.dirname(fromRel), spec));
+  if (base.startsWith('../') || base === '..') throw new Error(`${fromRel} imports ${spec}, outside the plugin`);
+  const stem = /\.(m?js|jsx)$/.test(base) ? base.replace(/\.(m?js|jsx)$/, '') : null;
+  for (const cand of [...TRY_EXT.map((e) => base + e), ...(stem ? ['.ts', '.tsx', '.mts'].map((e) => stem + e) : [])]) {
+    if (cand.endsWith('.d.ts')) continue;
+    if (isFile(join(root, cand))) return cand;
+  }
+  for (const e of ['.d.ts', '/index.d.ts']) if (isFile(join(root, base + e))) return null;
+  throw new Error(`${fromRel} imports ${spec}, which isn't in the plugin`);
+}
+
+// The module and every relative file it imports at runtime: [{rel, src}].
+export function collectGraph(root, entryRel) {
+  const files = new Map();
+  const queue = [entryRel];
+  while (queue.length) {
+    const rel = queue.shift();
+    if (files.has(rel)) continue;
+    const src = readFileSync(join(root, rel), 'utf8').replace(/^\uFEFF/, '');
+    files.set(rel, src);
+    for (const spec of importsOf(src)) {
+      if (!/^\.{1,2}\//.test(spec)) continue;
+      const target = resolveSpec(root, rel, spec);
+      if (target) queue.push(target);
+    }
+  }
+  return [...files].map(([rel, src]) => ({ rel, src }));
+}
+
+// Output name inside the sidecar's mod/ folder: always .mjs, so Node loads every file
+// as ESM whatever its version.
+export const outName = (rel) => rel.replace(/\.(tsx?|mts|jsx|m?js)$/, '') + '.mjs';
+
+export const needsTransform = (files) => files.some((f) => NEEDS_TRANSFORM.has(extname(f.rel)));
+
+// Transforms one file and points its imports at the output names: relative files at
+// their .mjs copies, 'claude-code' at the runtime's stand-in next to mod/.
+export function transformFile(root, file, esbuild) {
+  const ext = extname(file.rel);
+  let code = file.src;
+  if (NEEDS_TRANSFORM.has(ext)) {
+    if (!esbuild) throw new Error('needs esbuild to transform TS/TSX: port it with `npx agy-plugin-porter`, which installs esbuild as an optional dependency');
+    code = esbuild.transformSync(file.src, {
+      loader: ext === '.mts' ? 'ts' : ext.slice(1), format: 'esm', jsx: 'transform', jsxFactory: 'h', jsxFragment: 'Fragment',
+      target: 'node20', sourcefile: file.rel,
+    }).code;
+  }
+  const outDir = posix.dirname(`mod/${outName(file.rel)}`);
+  const stand = posix.relative(outDir, 'claude-code.mjs');
+  const rewrite = (spec) => {
+    if (spec === 'claude-code') return stand.startsWith('.') ? stand : `./${stand}`;
+    if (!/^\.{1,2}\//.test(spec)) return spec;
+    const target = resolveSpec(root, file.rel, spec);
+    if (!target) return spec;
+    const r = posix.relative(posix.dirname(file.rel), outName(target));
+    return r.startsWith('.') ? r : `./${r}`;
+  };
+  return code.replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([^'"\n]+)\2/g, (whole, lead, q, spec) => `${lead}${q}${rewrite(spec)}${q}`);
+}
+
+export const relPosix = (from, to) => relative(from, to).split('\\').join('/');

package/lib/mode-compiler.mjs

@@ -6,6 +6,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
 
+import { rewriteRuleVars } from './rules-compiler.mjs';
 import { slugifyName } from './skill-compiler.mjs';
 import { ROO_GROUPS, TOOLS, unmappedToolReason } from './tool-map.mjs';
 import { formatFrontmatter, parseYaml, splitFrontmatter } from './yaml-lite.mjs';
@@ -75,7 +76,8 @@ function compileClaudeAgents(pluginDir, { slug, report, taken }) {
     }
     const { data, body } = parsed;
     const name = agentName(data.name ?? basename(file, '.md'), slug, report, item);
-    const out = { name, description: typeof data.description === 'string' && data.description.trim() ? data.description : `Ported agent ${name}.` };
+    const rawDesc = typeof data.description === 'string' && data.description.trim() ? data.description : `Ported agent ${name}.`;
+    const out = { name, description: rewriteRuleVars(rawDesc, item, report) };
     if (data.tools !== undefined && data.tools !== null && data.tools !== '*') {
       const mapped = mapClaudeTools(data.tools);
       out.tools = mapped.tools;
@@ -92,7 +94,8 @@ function compileClaudeAgents(pluginDir, { slug, report, taken }) {
     const extra = Object.keys(data).filter((k) => !CLAUDE_AGENT_KEYS.has(k));
     if (extra.length) report.warnings.push(`${item}: dropped ${extra.join(', ')}`);
     rmSync(join(dir, file));
-    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, body));
+    const cleanBody = rewriteRuleVars(body, item, report);
+    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, cleanBody));
     taken.add(name);
     report.ported.push(`${item} → agents/${name}.md`);
   }
@@ -166,13 +169,20 @@ function compileRooModes(pluginDir, { srcDir, slug, report, taken }) {
       continue;
     }
     const { tools, mcp } = mapRooGroups(mode.groups, item, report);
-    const description = mode.whenToUse || mode.description || mode.roleDefinition.split(/(?<=\.)\s/)[0];
+    const rawDesc = mode.whenToUse || mode.description || mode.roleDefinition.split(/(?<=\.)\s/)[0];
+    const description = rewriteRuleVars(rawDesc, item, report);
     const out = { name, description, tools, ...(mcp ? { inheritMcp: true } : {}), mainAgent: true, subagent: true };
-    const body = [`# ${mode.name ?? mode.slug}`, mode.roleDefinition.trim(), mode.customInstructions?.trim(), ...modeRules(srcDir, mode.slug)]
+    const rawBody = [`# ${mode.name ?? mode.slug}`, mode.roleDefinition.trim(), mode.customInstructions?.trim(), ...modeRules(srcDir, mode.slug)]
       .filter(Boolean).join('\n\n');
+    const body = rewriteRuleVars(rawBody, item, report);
     writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, `\n${body}\n`));
     taken.add(name);
     report.ported.push(`${item} → agents/${name}.md`);
+    for (const f of [`.roo/system-prompt-${mode.slug}`, `.kilocode/system-prompt-${mode.slug}`]) {
+      if (existsSync(join(srcDir, f))) {
+        report.unported.push({ item: `${item} ${f}`, reason: "it replaces the whole system prompt, which an agy agent can't do; the agent has only the mode's role definition and instructions" });
+      }
+    }
   }
 }