agy-plugin-porter 0.0.0-stage → 0.2.0

package/lib/hook-compiler.mjs

@@ -0,0 +1,208 @@
+// Compiles Claude Code / Gemini CLI hook configs into Antigravity's named-hook
+// shape. Every handler is routed through scripts/hook-shim.mjs, which looks up
+// the original command in scripts/hook-shim.json. The original command never
+// goes on agy's command line, so agy's Windows quote mangling can't reach it.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { AGY_TOOLS, TOOLS, unmappedToolReason } from './tool-map.mjs';
+
+export const SHIM_PATH = 'scripts/hook-shim.mjs';
+export const SHIM_CONFIG_PATH = 'scripts/hook-shim.json';
+const SHIM_SOURCE = fileURLToPath(new URL('../scripts/hook-shim.mjs', import.meta.url));
+
+// Events agy has, keyed by source event name. Matcher-grouped events first.
+const GROUPED = new Set(['PreToolUse', 'PostToolUse']);
+const EVENTS = {
+  claude: { PreToolUse: 'PreToolUse', PostToolUse: 'PostToolUse', PostToolUseFailure: 'PostToolUse', SessionStart: 'SessionStart', Stop: 'Stop' },
+  gemini: { BeforeTool: 'PreToolUse', AfterTool: 'PostToolUse', SessionStart: 'SessionStart' },
+};
+const UNPORTED_EVENTS = {
+  UserPromptSubmit: 'agy has no user-prompt event (PreInvocation runs before every model call and carries no prompt)',
+  BeforeAgent: 'agy has no user-prompt event (PreInvocation runs before every model call and carries no prompt)',
+};
+
+const REGEX_META = /[.*+?^${}()[\]\\]/;
+const MCP_PREFIX_RE = /^(?:\^|\(\?:|\()*mcp__/;
+const UNSAFE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+// Splits a matcher on top-level `|` only (outside `(...)` and `[...]`).
+function splitTopLevelAlternatives(raw) {
+  const out = [];
+  let paren = 0;
+  let bracket = false;
+  let start = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (ch === '\\') { i++; continue; }
+    if (ch === '[' && !bracket) bracket = true;
+    else if (ch === ']' && bracket) bracket = false;
+    else if (!bracket && ch === '(') paren++;
+    else if (!bracket && ch === ')') paren = Math.max(0, paren - 1);
+    else if (!bracket && paren === 0 && ch === '|') {
+      out.push(raw.slice(start, i).trim());
+      start = i + 1;
+    }
+  }
+  out.push(raw.slice(start).trim());
+  return out.filter(Boolean);
+}
+
+// Rewrites a source matcher into an agy matcher. Returns the agy matcher (or
+// null when nothing maps) and the alternatives that didn't map.
+export function remapMatcher(matcher, dialect = 'claude') {
+  const raw = (matcher ?? '').trim();
+  if (raw === '' || raw === '*' || raw === '.*') return { matcher: '*', unmapped: [] };
+  const map = TOOLS[dialect];
+  const alternatives = splitTopLevelAlternatives(raw);
+  const mapped = new Set();
+  const unmapped = [];
+  for (const alt of alternatives) {
+    if (Object.hasOwn(map, alt)) map[alt].forEach((t) => mapped.add(t));
+    else if (AGY_TOOLS.has(alt) || alt === 'call_mcp_tool' || alt === 'mcp_tool') mapped.add(alt);
+    else if (MCP_PREFIX_RE.test(alt)) {
+      if (REGEX_META.test(alt)) {
+        try { new RegExp(`^(?:${alt})$`); } catch { unmapped.push(alt); continue; }
+      }
+      mapped.add('call_mcp_tool');
+      mapped.add('mcp_tool');
+      const eager = alt.replace(/^\^?mcp__/, 'mcp_').replace(/__/g, '_');
+      mapped.add(eager.endsWith('_') ? `${eager}.*` : eager);
+    } else if (REGEX_META.test(alt)) {
+      let re;
+      try { re = new RegExp(`^(?:${alt})$`); } catch { unmapped.push(alt); continue; }
+      const hits = Object.keys(map).filter((name) => re.test(name));
+      const matchesMcp = /\bmcp__/.test(alt) && (re.test('mcp__server__tool') || MCP_PREFIX_RE.test(alt));
+      if (matchesMcp) {
+        mapped.add('call_mcp_tool');
+        mapped.add('mcp_tool');
+      }
+      if (hits.length === 0 && !matchesMcp) unmapped.push(alt);
+      hits.forEach((name) => map[name].forEach((t) => mapped.add(t)));
+    } else unmapped.push(alt);
+  }
+  return { matcher: mapped.size ? [...mapped].sort().join('|') : null, unmapped };
+}
+
+// Claude SessionStart matchers name the session source; agy only fires on new sessions.
+function sessionStartFilter(matcher) {
+  const raw = (matcher ?? '').trim();
+  if (raw === '' || raw === '*') return { ok: true };
+  const sources = raw.split('|').map((s) => s.trim());
+  if (!sources.includes('startup')) return { ok: false };
+  return { ok: true, dropped: sources.filter((s) => s !== 'startup') };
+}
+
+// Seconds the shim gives the script. Claude counts seconds, Gemini milliseconds.
+function scriptTimeout(handler, dialect) {
+  const t = Number(handler.timeout);
+  if (!Number.isFinite(t) || t <= 0) return 60;
+  return dialect === 'gemini' ? Math.max(1, Math.ceil(t / 1000)) : t;
+}
+
+export function compileHooks(sources, { slug }) {
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(slug ?? '')) throw new Error(`invalid slug: ${slug}`);
+  const report = { ported: [], unported: [], warnings: [] };
+  const events = {};
+  const shimHooks = {};
+  const counters = {};
+  const warnOnce = (text) => { if (!report.warnings.includes(text)) report.warnings.push(text); };
+
+  for (const source of sources) {
+    const dialect = source.dialect ?? 'claude';
+    if (source.error) {
+      report.unported.push({ item: `hooks:${source.path}`, reason: `can't parse: ${source.error}` });
+      continue;
+    }
+    const config = source.config ?? {};
+    // A config's "modules" (Claude Code UI mods) are lib/mod-compiler.mjs's job.
+    for (const key of Object.keys(config)) {
+      if (!['hooks', 'modules', 'description'].includes(key)) warnOnce(`${source.path}: ignored top-level key "${key}"`);
+    }
+    const sourceEvents = config.hooks ?? {};
+    for (const [sourceEvent, groups] of Object.entries(sourceEvents)) {
+      if (UNSAFE_KEYS.has(sourceEvent)) continue;
+      const dialectEvents = EVENTS[dialect] ?? {};
+      const event = Object.hasOwn(dialectEvents, sourceEvent) ? dialectEvents[sourceEvent] : null;
+      if (!event) {
+        report.unported.push({
+          item: `hook:${sourceEvent}`,
+          reason: Object.hasOwn(UNPORTED_EVENTS, sourceEvent) ? UNPORTED_EVENTS[sourceEvent] : `agy has no ${sourceEvent} event`,
+        });
+        continue;
+      }
+      (Array.isArray(groups) ? groups : []).forEach((group, gi) => {
+        const label = `hook:${sourceEvent}#${gi}${group.matcher ? ` (${group.matcher})` : ''}`;
+        let matcher;
+        if (GROUPED.has(event)) {
+          const remap = remapMatcher(group.matcher, dialect);
+          for (const name of remap.unmapped) {
+            report.unported.push({ item: `${label} matcher ${name}`, reason: unmappedToolReason(name) });
+          }
+          if (!remap.matcher) return;
+          matcher = remap.matcher;
+        } else if (event === 'SessionStart' && dialect === 'claude') {
+          const filter = sessionStartFilter(group.matcher);
+          if (!filter.ok) {
+            report.unported.push({ item: label, reason: 'agy SessionStart fires only on new sessions (startup)' });
+            return;
+          }
+          if (filter.dropped?.length) warnOnce(`${label}: fires on startup only; ${filter.dropped.join(', ')} have no agy equivalent`);
+        }
+        const handlers = [];
+        (Array.isArray(group.hooks) ? group.hooks : []).forEach((handler, hi) => {
+          const item = `${label}.${hi}`;
+          if ((handler.type ?? 'command') !== 'command' || typeof handler.command !== 'string' || !handler.command.trim()) {
+            report.unported.push({ item, reason: `only command hooks can be ported (type: ${handler.type ?? 'none'})` });
+            return;
+          }
+          counters[event] = (counters[event] ?? 0) + 1;
+          const id = `${event.toLowerCase()}-${counters[event]}`;
+          const timeout = scriptTimeout(handler, dialect);
+          const rawMatcher = GROUPED.has(event) && typeof group.matcher === 'string' ? group.matcher.trim() : '';
+          shimHooks[id] = {
+            event, sourceEvent, dialect, command: handler.command, timeout,
+            ...(rawMatcher && rawMatcher !== '*' && rawMatcher !== '.*' ? { matcher: rawMatcher } : {}),
+          };
+          handlers.push({ type: 'command', command: `node ${SHIM_PATH} --event ${event} --hook ${id}`, timeout: timeout + 5 });
+          report.ported.push(item);
+        });
+        if (handlers.length === 0) return;
+        events[event] ??= [];
+        // agy rejects the whole file if a non-tool event uses the grouped shape.
+        if (GROUPED.has(event)) events[event].push({ matcher, hooks: handlers });
+        else events[event].push(...handlers);
+        if (event === 'PostToolUse') warnOnce('PostToolUse: agy sends no tool result, so tool_response is empty and block feedback is dropped');
+        if (event === 'Stop') warnOnce('Stop: stop_hook_active is approximated from agy\'s executionNum');
+      });
+    }
+  }
+
+  const hasHooks = Object.keys(shimHooks).length > 0;
+  return {
+    hooks: hasHooks ? { [slug]: events } : null,
+    shimConfig: hasHooks ? { version: 1, hooks: shimHooks } : null,
+    report,
+  };
+}
+
+// Writes the compiled hooks into a staged plugin dir: root hooks.json, the shim
+// and its config. Removes the foreign-shaped copies agy staged, including a
+// UI mod's hooks/hooks.json (lib/mod-compiler.mjs writes a mod's hooks itself).
+export function writeHookPort(pluginDir, compiled) {
+  const rootHooks = join(pluginDir, 'hooks.json');
+  const shimTarget = join(pluginDir, SHIM_PATH);
+  if (!compiled.hooks) {
+    rmSync(rootHooks, { force: true });
+  } else {
+    if (existsSync(shimTarget) && readFileSync(shimTarget, 'utf8') !== readFileSync(SHIM_SOURCE, 'utf8')) {
+      throw new Error(`${SHIM_PATH} already exists in the plugin and isn't the porter's shim`);
+    }
+    mkdirSync(dirname(shimTarget), { recursive: true });
+    copyFileSync(SHIM_SOURCE, shimTarget);
+    writeFileSync(join(pluginDir, SHIM_CONFIG_PATH), `${JSON.stringify(compiled.shimConfig, null, 2)}\n`);
+    writeFileSync(rootHooks, `${JSON.stringify(compiled.hooks, null, 2)}\n`);
+  }
+  rmSync(join(pluginDir, 'hooks', 'hooks.json'), { force: true });
+}

package/lib/index.mjs

@@ -0,0 +1,32 @@
+// Public API of agy-plugin-porter.
+import { resolveSource } from './source.mjs';
+import { transpile } from './transpiler-engine.mjs';
+
+export { detect } from './detector.mjs';
+export { createPreview, flagsDigest, installPreview, listPreviews, readPreview } from './consent.mjs';
+export { compileHooks, remapMatcher, writeHookPort } from './hook-compiler.mjs';
+export { sanitizeManifest } from './manifest-sanitizer.mjs';
+export { compileMods } from './mod-compiler.mjs';
+export { assess as assessMod, scanMod } from './mod-scan.mjs';
+export { compileModes } from './mode-compiler.mjs';
+export { compileRules } from './rules-compiler.mjs';
+export { compileSkills } from './skill-compiler.mjs';
+export { auditPlugin, inferTier, TIERS } from './static-auditor.mjs';
+export { resolveSource } from './source.mjs';
+export { transpile, validateWithAgy } from './transpiler-engine.mjs';
+
+// portPackage({srcDir, outDir, slug}) -> {report, tier}. `srcDir` is a local path
+// (or, with `source`, a path or owner/repo@ref to fetch first; `path` picks a
+// subfolder). Pass `validate: true` to run `agy plugin validate` on the output.
+export async function portPackage({ srcDir, source, path, outDir, slug, agy, force = false, validate = false }) {
+  if (!outDir) throw new Error('outDir is required');
+  const resolved = resolveSource(source ?? srcDir, { subPath: path });
+  try {
+    const report = transpile({ srcDir: resolved.dir, outDir, slug, agy, force, validate });
+    if (resolved.commit) report.sourceCommit = resolved.commit;
+    if (resolved.unpinned) report.warnings.push('source: no @ref given, so the port used the default branch; pin a tag or SHA for reproducible ports');
+    return { report, tier: report.tier };
+  } finally {
+    resolved.cleanup();
+  }
+}

package/lib/manifest-sanitizer.mjs

@@ -0,0 +1,187 @@
+// Writes the 7-key plugin.json and fixes MCP configs for agy:
+// - rescues Claude's inline `mcpServers`, which `agy plugin install` drops
+// - rewrites ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} to ${PLUGIN_ROOT} /
+//   ${PLUGIN_DATA}, which agy expands in `args`, `env` and `cwd` (live-tested
+//   for args on 1.4.5)
+// - turns absolute staging paths (agy expands Gemini's ${extensionPath} at
+//   install time) back into ${PLUGIN_ROOT}, so the output doesn't point into
+//   the throwaway staging home
+// - drops the source manifests agy leaves behind
+import { existsSync, rmSync, writeFileSync } from 'node:fs';
+import { extname, isAbsolute, join, normalize } from 'node:path';
+
+import { readJson } from './detector.mjs';
+
+export const MANIFEST_KEYS = ['name', 'displayName', 'description', 'version', 'logo', 'suggestedPrompts', 'disabled'];
+const LOGO_EXT = new Set(['.png', '.svg', '.jpg', '.jpeg', '.webp']);
+const SOURCE_ARTIFACTS = ['.claude-plugin', 'gemini-extension.json', '.mcp.json', 'mcp.json'];
+
+function readIf(file) {
+  try { return existsSync(file) ? readJson(file) : null; } catch { return null; }
+}
+
+export function sourceManifest(srcDir, ecosystems) {
+  if (ecosystems.includes('claude')) return readIf(join(srcDir, '.claude-plugin/plugin.json')) ?? {};
+  if (ecosystems.includes('gemini')) return readIf(join(srcDir, 'gemini-extension.json')) ?? {};
+  return readIf(join(srcDir, 'plugin.json')) ?? {};
+}
+
+export function buildManifest(source, { slug, ecosystems, pluginDir, report }) {
+  const out = { name: slug };
+  if (typeof source.displayName === 'string') out.displayName = source.displayName;
+  else if (typeof source.name === 'string' && source.name !== slug) out.displayName = source.name;
+  out.description = typeof source.description === 'string' && source.description.trim()
+    ? source.description.trim()
+    : `Ported from ${ecosystems.join(' + ')} by agy-plugin-porter.`;
+  if (typeof source.version === 'string') out.version = source.version;
+  if (typeof source.logo === 'string') {
+    const ok = !isAbsolute(source.logo) && !/^[a-z]+:/i.test(source.logo) && LOGO_EXT.has(extname(source.logo).toLowerCase())
+      && existsSync(join(pluginDir, source.logo));
+    if (ok) out.logo = source.logo;
+    else report.warnings.push(`plugin.json: dropped logo "${source.logo}" (must be a relative .png/.svg/.jpg/.jpeg/.webp in the plugin)`);
+  }
+  if (Array.isArray(source.suggestedPrompts)) {
+    const prompts = source.suggestedPrompts.filter((p) => typeof p === 'string' && p.trim()).slice(0, 3);
+    if (prompts.length) out.suggestedPrompts = prompts;
+  }
+  if (typeof source.disabled === 'boolean') out.disabled = source.disabled;
+  // Keys the porter consumes elsewhere aren't "dropped".
+  const consumed = new Set([...MANIFEST_KEYS, 'mcpServers', 'hooks', 'contextFileName', 'types', '$schema']);
+  const dropped = Object.keys(source).filter((k) => !consumed.has(k));
+  if (dropped.length) report.warnings.push(`plugin.json: dropped ${dropped.map((k) => `"${k}"`).join(', ')} (agy reads only ${MANIFEST_KEYS.join(', ')})`);
+  for (const key of ['commands', 'agents', 'skills', 'outputStyles']) {
+    if (key in source && typeof source[key] !== 'boolean') {
+      report.warnings.push(`plugin.json: custom "${key}" paths aren't followed; only the default folders are ported`);
+    }
+  }
+  return out;
+}
+
+export function extractServerMap(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return {};
+  if (obj.mcpServers && typeof obj.mcpServers === 'object' && !Array.isArray(obj.mcpServers)) return obj.mcpServers;
+  const entries = Object.entries(obj).filter(([k, v]) =>
+    !k.startsWith('$') && !['version', 'description', 'name'].includes(k)
+    && v && typeof v === 'object' && !Array.isArray(v)
+    && ('command' in v || 'url' in v || 'httpUrl' in v || 'serverUrl' in v));
+  return Object.fromEntries(entries);
+}
+
+// Inline servers in Claude's manifest: an object, or a path to a JSON file.
+function inlineServers(source, srcDir, report) {
+  const declared = source.mcpServers;
+  if (!declared) return {};
+  if (typeof declared === 'object' && !Array.isArray(declared)) return extractServerMap({ mcpServers: declared });
+  if (typeof declared === 'string') {
+    const file = readIf(join(srcDir, declared));
+    if (file) return extractServerMap(file);
+    report.unported.push({ item: `mcp:${declared}`, reason: "can't read the MCP config the manifest points to" });
+  }
+  return {};
+}
+
+const ROOT_VARS = [
+  [/\$\{CLAUDE_PLUGIN_ROOT\}|\$CLAUDE_PLUGIN_ROOT\b/g, '${PLUGIN_ROOT}'],
+  [/\$PLUGIN_ROOT\b/g, '${PLUGIN_ROOT}'],
+  [/\$\{CLAUDE_PLUGIN_DATA\}|\$CLAUDE_PLUGIN_DATA\b/g, '${PLUGIN_DATA}'],
+  [/\$PLUGIN_DATA\b/g, '${PLUGIN_DATA}'],
+  [/\$\{extensionPath\}|\$extensionPath\b/g, '${PLUGIN_ROOT}'],
+  [/\$\{GEMINI_PLUGIN_PATH\}|\$GEMINI_PLUGIN_PATH\b/g, '${PLUGIN_ROOT}'],
+  [/\$\{\/\}/g, '/'],
+];
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function rewriteString(value, stagedPaths) {
+  let out = value;
+  for (const [re, to] of ROOT_VARS) out = out.replace(re, to);
+  for (const staged of stagedPaths) {
+    for (const form of new Set([staged, staged.replace(/\\/g, '/'), staged.replace(/\//g, '\\')])) {
+      out = out.replace(new RegExp(escapeRe(form), process.platform === 'win32' ? 'gi' : 'g'), '${PLUGIN_ROOT}');
+    }
+  }
+  return out;
+}
+
+const PLACEHOLDER = /\$\{(?!PLUGIN_ROOT\}|PLUGIN_DATA\})([^}]+)\}/g;
+
+export function fixMcpServers(servers, { stagedPaths = [], report }) {
+  const fixed = {};
+  for (const [name, server] of Object.entries(servers)) {
+    if (!server || typeof server !== 'object' || Array.isArray(server)) continue;
+    if (name.startsWith('$') || ['__proto__', 'constructor', 'prototype'].includes(name)) continue;
+    const s = structuredClone(server);
+    if (Array.isArray(s.args)) s.args = s.args.map((a) => (typeof a === 'string' ? rewriteString(a, stagedPaths) : a));
+    if (typeof s.cwd === 'string') s.cwd = rewriteString(s.cwd, stagedPaths);
+    if (s.env && typeof s.env === 'object') {
+      s.env = Object.fromEntries(Object.entries(s.env).map(([k, v]) => [k, typeof v === 'string' ? rewriteString(v, stagedPaths) : v]));
+    }
+    if (typeof s.url === 'string' && !s.url.trim()) delete s.url;
+    if (typeof s.httpUrl === 'string' && !s.httpUrl.trim()) delete s.httpUrl;
+    const rawRemoteUrl = typeof s.url === 'string' ? s.url : (typeof s.httpUrl === 'string' ? s.httpUrl : null);
+    if (!s.serverUrl && rawRemoteUrl) {
+      s.serverUrl = rewriteString(rawRemoteUrl, stagedPaths);
+      delete s.url;
+      delete s.httpUrl;
+    } else if (typeof s.serverUrl === 'string') {
+      s.serverUrl = rewriteString(s.serverUrl, stagedPaths);
+    }
+    if (typeof s.serverUrl === 'string' && ['http', 'streamable-http', 'sse'].includes(s.type)) {
+      delete s.type;
+    }
+    if (s.headers && typeof s.headers === 'object') {
+      s.headers = Object.fromEntries(Object.entries(s.headers).map(([k, v]) => [k, typeof v === 'string' ? rewriteString(v, stagedPaths) : v]));
+    }
+    if (typeof s.command === 'string') {
+      const command = rewriteString(s.command, stagedPaths);
+      if (command.includes('${PLUGIN_ROOT}') || command.includes('${PLUGIN_DATA}')) {
+        report.unported.push({ item: `mcp:${name}`, reason: 'the command uses the plugin path, which agy expands only in args, env and cwd' });
+        continue;
+      }
+      s.command = command;
+    }
+    const others = new Set();
+    for (const text of [s.command, s.url, s.serverUrl, ...(s.args ?? []), ...Object.values(s.env ?? {}), ...Object.values(s.headers ?? {})]) {
+      if (typeof text === 'string') for (const m of text.matchAll(PLACEHOLDER)) others.add(m[1]);
+    }
+    if (others.size) {
+      report.warnings.push(`mcp:${name}: ${[...others].map((v) => `\${${v}}`).join(', ')} is passed literally unless declared in agy's "variables" (format unverified)`);
+    }
+    fixed[name] = s;
+    report.ported.push(`mcp:${name}`);
+  }
+  return fixed;
+}
+
+// Rewrites plugin.json and mcp_config.json in a staged plugin dir.
+export function sanitizeManifest(pluginDir, { srcDir, ecosystems, slug, stagedPaths = [] }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const source = sourceManifest(srcDir, ecosystems);
+  writeFileSync(join(pluginDir, 'plugin.json'), `${JSON.stringify(buildManifest(source, { slug, ecosystems, pluginDir, report }), null, 2)}\n`);
+  report.ported.push('manifest');
+
+  const configFile = join(pluginDir, 'mcp_config.json');
+  const servers = {
+    ...(srcDir ? extractServerMap(readIf(join(srcDir, 'mcp.json'))) : {}),
+    ...(srcDir ? extractServerMap(readIf(join(srcDir, '.mcp.json'))) : {}),
+    ...extractServerMap(readIf(join(pluginDir, 'mcp.json'))),
+    ...extractServerMap(readIf(join(pluginDir, '.mcp.json'))),
+    ...extractServerMap(readIf(configFile)),
+  };
+  if (ecosystems.includes('claude') || ecosystems.includes('gemini')) {
+    for (const [name, server] of Object.entries(inlineServers(source, srcDir, report))) {
+      if (name in servers && ecosystems.includes('claude')) report.warnings.push(`mcp:${name}: defined in both .mcp.json and plugin.json; kept .mcp.json's`);
+      else if (!(name in servers)) servers[name] = server;
+    }
+  }
+  if (ecosystems.includes('gemini')) {
+    for (const key of ['excludeTools', 'settings']) {
+      if (source[key]) report.unported.push({ item: `gemini:${key}`, reason: `agy has no equivalent of gemini-extension.json "${key}"` });
+    }
+  }
+  const fixed = fixMcpServers(servers, { stagedPaths: stagedPaths.map(normalize), report });
+  if (Object.keys(fixed).length) writeFileSync(configFile, `${JSON.stringify({ mcpServers: fixed }, null, 2)}\n`);
+  else rmSync(configFile, { force: true });
+
+  for (const artifact of SOURCE_ARTIFACTS) rmSync(join(pluginDir, artifact), { recursive: true, force: true });
+  return report;
+}

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(', ')}`);
+}