agy-plugin-porter 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,20 @@
 # agy-plugin-porter
 
+<p>
+  <a href="https://www.npmjs.com/package/agy-plugin-porter"><img src="https://img.shields.io/npm/v/agy-plugin-porter?logo=npm&color=cb3837" alt="npm version" height="20"></a>
+  <a href="https://github.com/arthurcavallari/agy-plugin-porter/actions/workflows/test.yml"><img src="https://github.com/arthurcavallari/agy-plugin-porter/actions/workflows/test.yml/badge.svg" alt="Tests" height="20"></a>
+  <img src="https://img.shields.io/node/v/agy-plugin-porter?logo=nodedotjs&logoColor=white&color=339933" alt="Node.js version" height="20">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" height="20"></a>
+  <a href="https://github.com/sponsors/arthurcavallari"><img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors&logoColor=white" alt="Sponsor on GitHub" height="20"></a>
+</p>
+
 > Ports Claude Code, Gemini CLI, Cursor, Roo/Kilo and Codex plugins to native **Google Antigravity** plugins, and tells you exactly what did and didn't carry over.
 
 `agy plugin install` already stages Claude Code and Gemini CLI plugins, but much of what it stages never runs. Hooks keep their foreign shape, `${CLAUDE_PLUGIN_ROOT}` stays unexpanded, and Claude agents are skipped by the loader. `CLAUDE.md` is never loaded either. agy still reports success. Cursor, Roo/Kilo and Codex sources aren't detected at all.
 
-`agy-plugin-porter` fills those gaps and audits the result. It's zero-dependency, pure Node.js (`>= 20.0.0`) ESM, and it's built to be the porting engine for [**Antigravity Hangar**](https://github.com/arthurcavallari/antigravity-hangar)'s plugin installs. That integration is planned and not built yet.
+`agy-plugin-porter` fills those gaps and audits the result. It's zero-dependency (`esbuild` is optional, for TS/TSX UI mods), pure Node.js (`>= 20.0.0`) ESM, and it's the porting engine behind [**Antigravity Hangar**](https://github.com/arthurcavallari/antigravity-hangar)'s plugin installs (Hangar 1.2.0 and later).
 
-**Status: 0.x.** Phases 0–2 of [`docs/plan.md`](docs/plan.md) are done. What agy itself handles was measured against agy 1.4.5 and is recorded in [`docs/agy-baseline.md`](docs/agy-baseline.md).
+**Status: 0.x.** Phases 0–2 of [`docs/plan.md`](docs/plan.md) are done, plus Phase 2.5 (Claude Code UI mods, [`docs/phase-2.5-ui-mods-plan.md`](docs/phase-2.5-ui-mods-plan.md)) and Phase 4 ([the porter inside Antigravity](#the-porter-inside-antigravity)). What agy itself handles was measured against agy 1.4.5 and is recorded in [`docs/agy-baseline.md`](docs/agy-baseline.md).
 
 ---
 
@@ -51,7 +59,7 @@ Nothing is dropped silently.
 | Cursor `.mdc` | Always-on rules, `model_decision` rules, or skills (glob-scoped and manual rules) |
 | `.cursorrules`, Roo/Cline/Kilo rules | Always-on rules |
 | Codex `.agents/skills` | Skills |
-| Claude Code UI mods (`hooks.json` with `modules`) | Detected and reported as unported. Nothing is copied or run. |
+| Claude Code UI mods (`hooks.json` with `modules`) | A plugin sidecar per mod, with its pane in Antigravity's side panel. See [UI mods](#ui-mods). |
 
 ### The hook shim
 
@@ -65,6 +73,20 @@ agy's hook contract differs from Claude Code's and Gemini CLI's: camelCase paylo
 
 The original commands live in `scripts/hook-shim.json`, so they never pass through agy's command line, which mangles quoted paths on Windows.
 
+### UI mods
+
+A Claude Code UI mod is a JS/TS module whose `register(on)` draws panes and hooks into the agent loop. The porter compiles each one into a plugin sidecar:
+- **Pane:** the mod's `Pane` renders in a view in Antigravity's side panel. Open it from the `sidecar://` link a command's reply carries, or from its tab.
+- **Events:** `session.start`, `turn.start`, `turn.complete` and `tool.call` run from agy hooks forwarded to the sidecar. A `tool.call` handler can observe and deny built-in tool calls (live-tested). It can also rewrite their input, which is implemented but not yet live-tested.
+- **Commands and tools:** each `$.command.register` becomes a skill plus a button in the view's toolbar. Each `$.tool.register` becomes an MCP tool.
+- **Report:** a mod is ported clean, partially (each fallback listed), or refused (for example, a mod that only draws into the transcript). A static scan lists every `$` call, and the runtime exposes only those.
+
+What maps fully, partially and not at all, tested live against three real mods, is in [`docs/ui-mods-baseline.md`](docs/ui-mods-baseline.md).
+
+TS/TSX mods need [`esbuild`](https://esbuild.github.io/), an optional dependency installed with the porter. Without it, those mods are reported unported. Plain JS mods need nothing. A ported mod is a full Node process outside agy's permission prompts, so it's always at least Tier 2.
+
+**Uninstalling:** switch the plugin off in **Customizations > Plugins** before `agy plugin uninstall`. On Windows a running sidecar holds its folder open, and the uninstall fails halfway.
+
 ### Static audit
 
 Before writing the output, the porter:
@@ -72,6 +94,33 @@ Before writing the output, the porter:
 - flags `curl | sh`-style pipes, decode-and-execute patterns, encoded PowerShell, bidi controls and high-entropy strings
 - checks agy's 24 KB per-rule and 20k-token always-on rules budgets
 
+## The porter inside Antigravity
+
+The porter also ships as an Antigravity plugin, so you can port from inside the app. GitHub releases after 0.1.0 carry it as `agy-plugin-porter-plugin-<version>.tgz`, with a `.sha256` beside it. Unpack it and install the folder:
+
+```bash
+tar -xzf agy-plugin-porter-plugin-<version>.tgz
+agy plugin install ./agy-plugin-porter
+```
+
+To build it from a checkout instead, run `npm run build:plugin` and install `dist/plugin/agy-plugin-porter`.
+
+The plugin adds:
+- **A detector.** When a conversation starts in a workspace that holds a Claude Code, Gemini CLI, Cursor, Roo/Kilo or Codex plugin, the agent is told once per workspace. It mentions the plugin and doesn't port anything unasked.
+- **A skill, an agent and rules** for porting with the porter, never by hand.
+- **Two MCP tools**, `port_preview` and `port_install` (server `agy-plugin-porter_cli`).
+- **The Plugin Porter pane.** Enter a folder or `owner/repo@<tag>`, read the full port report, then install.
+
+**Consent.** Every install starts with a preview, which ports into a temp folder and shows the report. An install takes only that preview's output, and only when it gets back the preview's tier and audit-findings digest. That's the same rule Hangar's installer uses. The pane asks you in a confirm dialog. The agent is told to show you the report and wait for your yes, but only the pane's dialog is enforced. Previews are kept in a folder only you can access (`%LOCALAPPDATA%\agy-plugin-porter\previews` on Windows, `~/.cache/agy-plugin-porter/previews` elsewhere), never in the shared temp folder, and expire after an hour.
+
+**Limits:**
+- There's no `esbuild` inside the plugin, so TS/TSX UI mods are reported unported. Port those with `npx agy-plugin-porter`.
+- Claude Code and Gemini CLI sources need `agy` on the app's PATH, and GitHub sources need `git`. Both were there in the live run.
+
+**Uninstalling:** switch it off in **Customizations > Plugins** first, then run `agy plugin uninstall agy-plugin-porter`.
+
+What was tested live, and what the app leaves behind after an uninstall, is in [`docs/plugin-baseline.md`](docs/plugin-baseline.md).
+
 ## Library
 
 ```js
@@ -85,7 +134,7 @@ const { report, tier } = await portPackage({
 });
 ```
 
-Subpath exports cover the individual stages: `./detector`, `./hook-compiler`, `./manifest-sanitizer`, `./skill-compiler`, `./rules-compiler`, `./mode-compiler`, `./static-auditor` and `./transpiler-engine`.
+Subpath exports cover the individual stages: `./detector`, `./hook-compiler`, `./manifest-sanitizer`, `./mod-compiler`, `./skill-compiler`, `./rules-compiler`, `./mode-compiler`, `./static-auditor` and `./transpiler-engine`.
 
 ## Development
 
@@ -96,6 +145,12 @@ npm run test:pack  # packs the tarball, installs it in an empty project, and run
 
 The tests that need agy (Claude/Gemini staging and `agy plugin validate`) skip when `agy` isn't on `PATH`, as on the CI runners. Run `npm test` locally with agy installed to cover them. Releases publish from a `v*` tag through npm trusted publishing (`.github/workflows/publish.yml`).
 
+## Support
+
+Built and maintained in my spare time (with constant keyboard supervision from my three cats, **Snow** 🤍, **Eevee** 🦊, and **Merlin** 🧙‍♂️).
+
+If **agy-plugin-porter** saves you time porting and auditing plugins for Antigravity, consider [❤️ sponsoring me on GitHub Sponsors](https://github.com/sponsors/arthurcavallari) to help fund ongoing maintenance, new transpiler support, and the household Churu treat budget!
+
 ## License
 
 [MIT](LICENSE)

package/bin/agy-porter.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // agy-porter --source <path|owner/repo@ref> [--path <dir>] [--slug <s>] [--out <dir>]
 //            [--force] [--validate] [--install] [--json]
-import { spawnSync } from 'node:child_process';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { portPackage } from '../lib/index.mjs';
+import { spawnAgy } from '../lib/transpiler-engine.mjs';
 
 const USAGE = `Usage: agy-porter --source <path|owner/repo@ref> [options]
 
@@ -75,7 +75,7 @@ async function main() {
     }
     if (report.validation && !report.validation.ok) return 2;
     if (opts.install) {
-      const run = spawnSync(opts.agy ?? 'agy', ['plugin', 'install', outDir], { stdio: 'inherit' });
+      const run = spawnAgy(opts.agy ?? 'agy', ['plugin', 'install', outDir], { stdio: 'inherit' });
       if (run.status !== 0) return run.status ?? 1;
       console.log('Installed. Restart Antigravity to load a new plugin directory.');
     }

package/lib/consent.mjs

@@ -0,0 +1,122 @@
+// Previews and consent for installing a port into the user's Antigravity profile.
+// A preview ports a source into a private folder and records its report; an install
+// takes only that folder, and only when the caller hands back the tier and the
+// audit-findings digest the preview showed (the same rule as Hangar's installer).
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { removeTree } from './source.mjs';
+import { TIERS } from './static-auditor.mjs';
+import { spawnAgy } from './transpiler-engine.mjs';
+
+const BIN = fileURLToPath(new URL('../bin/agy-porter.mjs', import.meta.url));
+const ID = /^[a-f0-9]{16}$/;
+export const PREVIEW_TTL_MS = 60 * 60 * 1000;
+
+// Previews live in a per-user cache folder, never the shared temp dir: on a
+// multi-user machine, another user who made /tmp/agy-plugin-porter first could
+// swap a preview's report or output between the preview and the install.
+export function previewsDir() {
+  if (process.env.AGY_PORTER_PREVIEWS_DIR) return process.env.AGY_PORTER_PREVIEWS_DIR;
+  const base = process.platform === 'win32'
+    ? process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+    : process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'agy-plugin-porter', 'previews');
+}
+export const agyCommand = () => process.env.AGY_PORTER_AGY || 'agy';
+const hasAgy = (agy) => spawnAgy(agy, ['--version'], { encoding: 'utf8', timeout: 15_000 }).status === 0;
+
+// Same digest as Hangar's flagsDigest (antigravity-sidecar-hub lib/plugin-installer.mjs),
+// so consent given in one can be checked by the other.
+export function flagsDigest(flags = []) {
+  if (!flags.length) return '';
+  const keys = flags.map((f) => [f.kind, f.severity, f.file || '', f.line || 0].join(':')).sort();
+  return createHash('sha256').update(keys.join('\n')).digest('hex').slice(0, 16);
+}
+
+// Deletes previews older than the TTL. Returns the ones left, newest first.
+export function listPreviews({ now = Date.now() } = {}) {
+  const dir = previewsDir();
+  if (!existsSync(dir)) return [];
+  const kept = [];
+  for (const id of readdirSync(dir)) {
+    const preview = readPreview(id);
+    if (!preview || now - preview.createdAt > PREVIEW_TTL_MS) removeTree(join(dir, id));
+    else kept.push(preview);
+  }
+  return kept.sort((a, b) => b.createdAt - a.createdAt);
+}
+
+export function readPreview(id) {
+  if (!ID.test(String(id))) return null;
+  try { return JSON.parse(readFileSync(join(previewsDir(), id, 'preview.json'), 'utf8')); } catch { return null; }
+}
+
+// Runs the porter's CLI in a child process, so the caller's event loop stays free.
+function runPorter(args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [BIN, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', (err) => resolve({ code: 1, stdout, stderr: err.message }));
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+// Ports `source` (a path or owner/repo@ref) into a fresh preview folder. Validates
+// with agy when it's on PATH. Resolves to the preview record; rejects with the
+// porter's error when the port fails.
+export async function createPreview({ source, path, slug } = {}) {
+  if (typeof source !== 'string' || !source.trim()) throw new Error('source is required: a folder path or owner/repo@ref');
+  listPreviews();
+  const id = randomBytes(8).toString('hex');
+  const dir = join(previewsDir(), id);
+  const outDir = join(dir, 'out');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const agy = agyCommand();
+  const validate = hasAgy(agy);
+  const args = ['--source', source.trim(), '--out', outDir, '--json', '--agy', agy];
+  if (path) args.push('--path', String(path));
+  if (slug) args.push('--slug', String(slug));
+  if (validate) args.push('--validate');
+  const run = await runPorter(args);
+  let report = null;
+  try { report = JSON.parse(run.stdout); } catch {}
+  if (!report) {
+    removeTree(dir);
+    throw new Error((run.stderr || run.stdout).trim().replace(/^agy-porter: /, '') || `the porter exited with ${run.code}`);
+  }
+  delete report.outDir;
+  const preview = {
+    id, createdAt: Date.now(), source: source.trim(), path: path || null, slug: report.slug,
+    tier: report.tier, flagsDigest: flagsDigest(report.flags), validated: validate, report,
+  };
+  writeFileSync(join(dir, 'preview.json'), JSON.stringify(preview, null, 2));
+  return preview;
+}
+
+// Installs a preview's output with `agy plugin install`, if the caller's consent
+// covers it. Resolves to {slug, output}; rejects with the reason it refused.
+export async function installPreview({ previewId, acceptedTier, acceptedFlags = '' } = {}) {
+  const preview = readPreview(previewId);
+  if (!preview || Date.now() - preview.createdAt > PREVIEW_TTL_MS) throw new Error('no such preview (they expire after an hour): run a new preview');
+  const accepted = TIERS.indexOf(acceptedTier);
+  if (accepted < TIERS.indexOf(preview.tier)) throw new Error(`the port is ${preview.tier}, which is above the accepted ${acceptedTier || 'none'}`);
+  if ((acceptedFlags || '') !== preview.flagsDigest) throw new Error('the accepted audit findings differ from this preview\'s: show the user the preview again');
+  if (!preview.validated) throw new Error('this preview wasn\'t validated, because agy isn\'t on PATH; agy is needed to install');
+  if (!preview.report.validation?.ok) throw new Error('the port failed `agy plugin validate`, so it can\'t be installed');
+  const dir = join(previewsDir(), preview.id);
+  const outDir = join(dir, 'out');
+  if (!existsSync(outDir) || !statSync(outDir).isDirectory()) throw new Error('the preview\'s output is gone: run a new preview');
+  const run = spawnAgy(agyCommand(), ['plugin', 'install', outDir], { encoding: 'utf8', timeout: 120_000 });
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`.trim();
+  if (run.error || run.status !== 0) throw new Error(`agy plugin install failed: ${run.error?.message ?? output}`);
+  removeTree(dir);
+  return { slug: preview.slug, output };
+}

package/lib/detector.mjs

@@ -87,5 +87,6 @@ function hasClaudeComponents(srcDir) {
     || list('agents').some((f) => f.endsWith('.md'))
     || list('skills').some((d) => existsSync(join(srcDir, 'skills', d, 'SKILL.md')))
     || existsSync(join(srcDir, 'hooks/hooks.json'))
-    || existsSync(join(srcDir, '.mcp.json'));
+    || existsSync(join(srcDir, '.mcp.json'))
+    || existsSync(join(srcDir, 'mcp.json'));
 }

package/lib/hook-compiler.mjs

@@ -3,10 +3,9 @@
 // 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, posix } from 'node:path';
+import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { isUiMod } from './detector.mjs';
 import { AGY_TOOLS, TOOLS, unmappedToolReason } from './tool-map.mjs';
 
 export const SHIM_PATH = 'scripts/hook-shim.mjs';
@@ -25,6 +24,30 @@ const UNPORTED_EVENTS = {
 };
 
 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.
@@ -32,17 +55,30 @@ export function remapMatcher(matcher, dialect = 'claude') {
   const raw = (matcher ?? '').trim();
   if (raw === '' || raw === '*' || raw === '.*') return { matcher: '*', unmapped: [] };
   const map = TOOLS[dialect];
-  const alternatives = raw.includes('(') ? [raw] : raw.split('|').map((a) => a.trim()).filter(Boolean);
+  const alternatives = splitTopLevelAlternatives(raw);
   const mapped = new Set();
   const unmapped = [];
   for (const alt of alternatives) {
-    if (map[alt]) map[alt].forEach((t) => mapped.add(t));
-    else if (AGY_TOOLS.has(alt)) mapped.add(alt);
-    else if (!alt.startsWith('mcp__') && REGEX_META.test(alt)) {
+    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));
-      if (hits.length === 0) unmapped.push(alt);
+      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);
   }
@@ -80,23 +116,19 @@ export function compileHooks(sources, { slug }) {
       continue;
     }
     const config = source.config ?? {};
-    if (isUiMod(config)) {
-      const base = posix.dirname(source.path.split('#')[0]);
-      for (const mod of config.modules) {
-        const path = posix.normalize(posix.join(base, String(mod)));
-        report.unported.push({ item: `ui-mod:${path}`, reason: 'Claude Code UI mods are not ported yet' });
-      }
-    }
+    // 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)) {
-      const event = EVENTS[dialect][sourceEvent];
+      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: UNPORTED_EVENTS[sourceEvent] ?? `agy has no ${sourceEvent} event`,
+          reason: Object.hasOwn(UNPORTED_EVENTS, sourceEvent) ? UNPORTED_EVENTS[sourceEvent] : `agy has no ${sourceEvent} event`,
         });
         continue;
       }
@@ -128,7 +160,11 @@ export function compileHooks(sources, { slug }) {
           counters[event] = (counters[event] ?? 0) + 1;
           const id = `${event.toLowerCase()}-${counters[event]}`;
           const timeout = scriptTimeout(handler, dialect);
-          shimHooks[id] = { event, sourceEvent, dialect, command: handler.command, timeout };
+          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);
         });
@@ -153,7 +189,7 @@ export function compileHooks(sources, { slug }) {
 
 // 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 (UI mods are reported, never copied).
+// 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);

package/lib/index.mjs

@@ -3,8 +3,11 @@ 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';

package/lib/manifest-sanitizer.mjs

@@ -14,7 +14,7 @@ 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'];
+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; }
@@ -57,14 +57,24 @@ export function buildManifest(source, { slug, ecosystems, pluginDir, report }) {
   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 declared;
+  if (typeof declared === 'object' && !Array.isArray(declared)) return extractServerMap({ mcpServers: declared });
   if (typeof declared === 'string') {
     const file = readIf(join(srcDir, declared));
-    if (file) return file.mcpServers ?? file;
+    if (file) return extractServerMap(file);
     report.unported.push({ item: `mcp:${declared}`, reason: "can't read the MCP config the manifest points to" });
   }
   return {};
@@ -72,8 +82,11 @@ function inlineServers(source, srcDir, report) {
 
 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}'],
-  [/\$\{extensionPath\}/g, '${PLUGIN_ROOT}'],
+  [/\$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, '\\$&');
@@ -94,13 +107,30 @@ 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') continue;
+    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}')) {
@@ -110,7 +140,7 @@ export function fixMcpServers(servers, { stagedPaths = [], report }) {
       s.command = command;
     }
     const others = new Set();
-    for (const text of [s.command, s.url, ...(s.args ?? []), ...Object.values(s.env ?? {}), ...Object.values(s.headers ?? {})]) {
+    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) {
@@ -130,11 +160,17 @@ export function sanitizeManifest(pluginDir, { srcDir, ecosystems, slug, stagedPa
   report.ported.push('manifest');
 
   const configFile = join(pluginDir, 'mcp_config.json');
-  const servers = { ...(readIf(configFile)?.mcpServers ?? {}) };
-  if (ecosystems.includes('claude')) {
+  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) report.warnings.push(`mcp:${name}: defined in both .mcp.json and plugin.json; kept .mcp.json's`);
-      else servers[name] = server;
+      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')) {