agy-plugin-porter 0.0.0-stage → 0.2.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,156 @@
-# 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.
+<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 (`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, 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).
+
+---
+
+## 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`) | A plugin sidecar per mod, with its pane in Antigravity's side panel. See [UI mods](#ui-mods). |
+
+### 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.
+
+### 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:
+- 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
+
+## 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
+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`, `./mod-compiler`, `./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`).
+
+## 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

@@ -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 { 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]
+
+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 = 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.');
+    }
+    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/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

@@ -0,0 +1,92 @@
+// 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'))
+    || existsSync(join(srcDir, 'mcp.json'));
+}