agy-plugin-porter 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# agy-plugin-porter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 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.
+
+**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).
+
+---
+
+## Quick start
+
+```bash
+npx agy-plugin-porter --source ./my-claude-plugin --out ./ported --validate
+agy plugin install ./ported
+```
+
+`--source` also takes a GitHub repo pinned to a tag, branch or commit: `owner/repo@<ref>`, plus `--path <subfolder>` for monorepos. `--install` runs `agy plugin install` on the output for you. Restart Antigravity afterwards so it discovers the new plugin directory.
+
+```
+agy-porter --source <path|owner/repo@ref> [--path <dir>] [--slug <name>] [--out <dir>]
+           [--force] [--validate] [--install] [--agy <path>] [--json]
+```
+
+Every run prints a **port report**:
+- what was ported
+- what wasn't, with the reason
+- warnings
+- static-audit flags
+- an inferred capability tier, using the same `TIER_1_TELEMETRY` / `TIER_2_LOCAL_TOOLING` / `TIER_3_AGENT_CONTROL` meaning as Hangar
+
+Nothing is dropped silently.
+
+## Requirements
+
+- Node.js 20 or newer.
+- `agy` on `PATH` for Claude Code and Gemini CLI sources. The porter stages them with `agy plugin install`, always against a **throwaway home** (`HOME`/`USERPROFILE` set to a temp dir), so your real Antigravity profile is never read or written. Cursor, Roo/Kilo and Codex sources don't need agy. `--validate` runs `agy plugin validate`, also in a throwaway home.
+
+## What gets ported
+
+| Source | Becomes |
+| :-- | :-- |
+| Claude `hooks/hooks.json`, Gemini hooks | Native named-hook `hooks.json`. Events and tool matchers are remapped (`Bash` → `run_command`, `Edit\|Write` → …), and every handler runs through `scripts/hook-shim.mjs`. |
+| Claude/Gemini commands | Skills with a proper `name`. Claude-only frontmatter is stripped, and argument placeholders are rewritten. |
+| `.mcp.json`, inline `mcpServers`, extension MCP | `mcp_config.json`, with `${CLAUDE_PLUGIN_ROOT}` / `${extensionPath}` → `${PLUGIN_ROOT}` |
+| Claude `agents/*.md` | agy agents, with agy tool names and model tiers |
+| Roo/Kilo `.roomodes` | agy agents. Tool groups are mapped, and mode rules are folded into the body. |
+| `CLAUDE.md`, `GEMINI.md`, Codex `AGENTS.md` | `rules/AGENTS.md` |
+| 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. |
+
+### The hook shim
+
+agy's hook contract differs from Claude Code's and Gemini CLI's: camelCase payloads, a JSON decision on stdout, and fail-closed on any nonzero exit. The shim ships inside each ported plugin and bridges the two:
+- **Payload:** translates it to the source's snake_case shape, with the source's tool names and argument names.
+- **Plugin paths:** expands `${CLAUDE_PLUGIN_ROOT}` and friends.
+- **Results:**
+  - exit 2 → `{"decision":"deny","reason":<stderr>}`
+  - plain SessionStart text → injected context
+  - other failures → allow plus a warning, matching the source's non-blocking semantics
+
+The original commands live in `scripts/hook-shim.json`, so they never pass through agy's command line, which mangles quoted paths on Windows.
+
+### Static audit
+
+Before writing the output, the porter:
+- strips Unicode tag characters (U+E0000–E007F)
+- 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
+
+## Library
+
+```js
+import { portPackage } from 'agy-plugin-porter';
+
+const { report, tier } = await portPackage({
+  source: 'owner/repo@v1.2.3', // or srcDir: '/path/to/plugin'
+  outDir: '/tmp/ported',
+  slug: 'my-plugin',
+  validate: true,
+});
+```
+
+Subpath exports cover the individual stages: `./detector`, `./hook-compiler`, `./manifest-sanitizer`, `./skill-compiler`, `./rules-compiler`, `./mode-compiler`, `./static-auditor` and `./transpiler-engine`.
+
+## Development
+
+```bash
+npm test           # unit + end-to-end tests over test/fixtures/
+npm run test:pack  # packs the tarball, installs it in an empty project, and runs it
+```
+
+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`).
+
+## License
+
+[MIT](LICENSE)

package/bin/agy-porter.mjs

@@ -0,0 +1,91 @@
+#!/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';
+
+const USAGE = `Usage: agy-porter --source <path|owner/repo@ref> [options]
+
+Ports a Claude Code, Gemini CLI, Cursor, Roo/Kilo or Codex plugin into a native
+Antigravity plugin and prints a port report.
+
+Options:
+  --source <spec>   local folder, or GitHub owner/repo[@tag|branch|sha]
+  --path <dir>      subfolder of the source that holds the plugin
+  --slug <name>     plugin name in Antigravity (default: the source's name)
+  --out <dir>       where to write the ported plugin (required unless --install)
+  --force           replace a non-empty --out
+  --validate        run \`agy plugin validate\` on the output (throwaway home)
+  --install         install the output with \`agy plugin install\` (your real profile)
+  --agy <path>      agy executable (default: agy)
+  --json            print the report as JSON
+  -h, --help        show this help`;
+
+function printReport(report) {
+  const lines = [`agy-porter: ${report.slug} (${report.ecosystems.join(' + ')}), ${report.tier}`];
+  if (report.sourceCommit) lines.push(`  source commit ${report.sourceCommit}`);
+  lines.push(`  ported (${report.ported.length}):`, ...report.ported.map((p) => `    ✔ ${p}`));
+  if (report.unported.length) lines.push(`  unported (${report.unported.length}):`, ...report.unported.map((u) => `    ✗ ${u.item}: ${u.reason}`));
+  if (report.warnings.length) lines.push(`  warnings (${report.warnings.length}):`, ...report.warnings.map((w) => `    ⚠ ${w}`));
+  if (report.flags.length) {
+    lines.push(`  audit flags (${report.flags.length}):`,
+      ...report.flags.map((f) => `    ! [${f.severity}] ${f.kind}${f.file ? ` ${f.file}${f.line ? `:${f.line}` : ''}` : ''}${f.excerpt ? `  ${f.excerpt}` : ''}`));
+  }
+  if (report.tierReasons.length) lines.push(`  tier because: ${report.tierReasons.join('; ')}`);
+  if (report.validation) {
+    const v = report.validation;
+    lines.push(`  agy plugin validate: ${v.ok ? 'passed' : 'FAILED'} (${v.errors.length} errors, ${v.warnings.length} warnings)`);
+    for (const f of [...v.errors, ...v.warnings]) lines.push(`    ${f.severity === 'error' ? '✗' : '⚠'} ${f.file ?? ''}: ${f.message}`);
+    if (v.output) lines.push(`    ${v.output}`);
+  }
+  console.log(lines.join('\n'));
+}
+
+async function main() {
+  let opts;
+  try {
+    ({ values: opts } = parseArgs({
+      options: {
+        source: { type: 'string' }, path: { type: 'string' }, slug: { type: 'string' }, out: { type: 'string' },
+        force: { type: 'boolean' }, validate: { type: 'boolean' }, install: { type: 'boolean' },
+        agy: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+      },
+    }));
+  } catch (err) {
+    console.error(`${err.message}\n\n${USAGE}`);
+    return 1;
+  }
+  if (opts.help) { console.log(USAGE); return 0; }
+  if (!opts.source || (!opts.out && !opts.install)) { console.error(USAGE); return 1; }
+
+  const outDir = opts.out ?? mkdtempSync(join(tmpdir(), 'agy-porter-out-'));
+  try {
+    const { report } = await portPackage({
+      source: opts.source, path: opts.path, outDir, slug: opts.slug, agy: opts.agy, force: opts.force, validate: opts.validate,
+    });
+    if (opts.json) console.log(JSON.stringify({ outDir: opts.out ?? null, ...report }, null, 2));
+    else {
+      printReport(report);
+      if (opts.out) console.log(`  written to ${outDir}`);
+    }
+    if (report.validation && !report.validation.ok) return 2;
+    if (opts.install) {
+      const run = spawnSync(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.');
+    }
+    return 0;
+  } catch (err) {
+    console.error(`agy-porter: ${err.message}`);
+    return 1;
+  } finally {
+    if (!opts.out) rmSync(outDir, { recursive: true, force: true });
+  }
+}
+
+process.exitCode = await main();

package/lib/detector.mjs

@@ -0,0 +1,91 @@
+// Works out which plugin ecosystem(s) a source directory contains, where its
+// hook configs live, and which of those are Claude Code UI mods.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const MARKERS = {
+  claude: ['.claude-plugin/plugin.json'],
+  gemini: ['gemini-extension.json'],
+  cursor: ['.cursor/rules', '.cursorrules'],
+  roo: ['.roomodes', '.kilocodemodes'],
+  codex: ['.agents/skills'],
+};
+
+export function readJson(file) {
+  const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+  return JSON.parse(text);
+}
+
+const toPosix = (p) => p.split('\\').join('/');
+
+// A Claude Code UI mod uses the classic hooks file name with a `modules` key.
+export function isUiMod(config) {
+  return Boolean(config) && typeof config === 'object' && Array.isArray(config.modules);
+}
+
+// Hook configs a Claude plugin can declare: hooks/hooks.json, plus the
+// manifest's `hooks` field (a path, a list of paths, or an inline object).
+function claudeHookSources(srcDir, manifest) {
+  const sources = [];
+  const seen = new Set();
+  const addFile = (rel) => {
+    const file = join(srcDir, rel);
+    const key = toPosix(relative(srcDir, file));
+    if (seen.has(key) || !existsSync(file)) return;
+    seen.add(key);
+    let config = null;
+    let error = null;
+    try { config = readJson(file); } catch (err) { error = err.message; }
+    sources.push({ path: key, config, error });
+  };
+  addFile('hooks/hooks.json');
+  const declared = manifest?.hooks;
+  if (typeof declared === 'string') addFile(declared);
+  else if (Array.isArray(declared)) declared.filter((p) => typeof p === 'string').forEach(addFile);
+  else if (declared && typeof declared === 'object') {
+    sources.push({ path: '.claude-plugin/plugin.json#hooks', config: declared, error: null });
+  }
+  return sources;
+}
+
+export function detect(srcDir) {
+  if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
+    throw new Error(`not a directory: ${srcDir}`);
+  }
+  const ecosystems = Object.keys(MARKERS)
+    .filter((eco) => MARKERS[eco].some((m) => existsSync(join(srcDir, m))));
+  if (ecosystems.length === 0 && existsSync(join(srcDir, 'plugin.json'))) ecosystems.push('antigravity');
+  // Claude Code's manifest is optional: marketplace entries can declare a
+  // plugin that only has the default component folders.
+  const manifestless = ecosystems.length === 0 && hasClaudeComponents(srcDir);
+  if (manifestless) ecosystems.push('claude');
+
+  const hookSources = [];
+  if (ecosystems.includes('claude')) {
+    let manifest = null;
+    try { manifest = readJson(join(srcDir, '.claude-plugin/plugin.json')); } catch {}
+    hookSources.push(...claudeHookSources(srcDir, manifest).map((s) => ({ ...s, dialect: 'claude' })));
+  }
+  if (ecosystems.includes('gemini') && existsSync(join(srcDir, 'hooks/hooks.json'))
+      && !hookSources.some((s) => s.path === 'hooks/hooks.json')) {
+    let config = null;
+    let error = null;
+    try { config = readJson(join(srcDir, 'hooks/hooks.json')); } catch (err) { error = err.message; }
+    hookSources.push({ path: 'hooks/hooks.json', config, error, dialect: 'gemini' });
+  }
+
+  const uiMods = hookSources
+    .filter((s) => isUiMod(s.config))
+    .map((s) => ({ path: s.path, modules: s.config.modules, hasHooks: Boolean(s.config.hooks) }));
+
+  return { ecosystems, hookSources, uiMods, manifestless };
+}
+
+function hasClaudeComponents(srcDir) {
+  const list = (rel) => (existsSync(join(srcDir, rel)) && statSync(join(srcDir, rel)).isDirectory() ? readdirSync(join(srcDir, rel)) : []);
+  return list('commands').some((f) => f.endsWith('.md'))
+    || 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'));
+}

package/lib/hook-compiler.mjs

@@ -0,0 +1,172 @@
+// 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, posix } 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';
+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 = /[.*+?^${}()[\]\\]/;
+
+// 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 = raw.includes('(') ? [raw] : raw.split('|').map((a) => a.trim()).filter(Boolean);
+  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)) {
+      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);
+      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 ?? {};
+    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' });
+      }
+    }
+    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 (!event) {
+        report.unported.push({
+          item: `hook:${sourceEvent}`,
+          reason: 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);
+          shimHooks[id] = { event, sourceEvent, dialect, command: handler.command, timeout };
+          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 (UI mods are reported, never copied).
+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,29 @@
+// Public API of agy-plugin-porter.
+import { resolveSource } from './source.mjs';
+import { transpile } from './transpiler-engine.mjs';
+
+export { detect } from './detector.mjs';
+export { compileHooks, remapMatcher, writeHookPort } from './hook-compiler.mjs';
+export { sanitizeManifest } from './manifest-sanitizer.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,151 @@
+// 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'];
+
+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;
+}
+
+// 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 === 'string') {
+    const file = readIf(join(srcDir, declared));
+    if (file) return file.mcpServers ?? 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}'],
+  [/\$\{CLAUDE_PLUGIN_DATA\}|\$CLAUDE_PLUGIN_DATA\b/g, '${PLUGIN_DATA}'],
+  [/\$\{extensionPath\}/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') 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.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.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 = { ...(readIf(configFile)?.mcpServers ?? {}) };
+  if (ecosystems.includes('claude')) {
+    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 (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;
+}