agy-plugin-porter 0.0.0-stage → 0.2.0

package/lib/rules-compiler.mjs

@@ -0,0 +1,205 @@
+// Builds rules/ for agy:
+// - CLAUDE.md, GEMINI.md (or gemini-extension.json `contextFileName`) and
+//   Codex's AGENTS.md -> rules/AGENTS.md, plain Markdown and always on
+// - Cursor .mdc: alwaysApply -> an always_on rule; description only -> a
+//   model_decision rule (agy lists it with its description, live-tested);
+//   globs or nothing -> a skill, because agy 1.4.5 never applies a plugin's
+//   glob or manual rules (live-tested on view and edit, though `agy plugin
+//   validate` accepts them)
+// - .cursorrules and Roo/Cline/Kilo workspace rules -> always_on rules
+// A rule over agy's 24 KB per-file limit is reported unported instead of being
+// silently truncated.
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { readJson } from './detector.mjs';
+import { slugifyName } from './skill-compiler.mjs';
+import { formatFrontmatter, splitFrontmatter } from './yaml-lite.mjs';
+
+export const RULE_BYTES = 24_000;
+export const RULES_BUDGET_TOKENS = 20_000;
+
+const read = (file) => readFileSync(file, 'utf8').replace(/^/, '').replace(/\r\n?/g, '\n');
+const isFile = (file) => existsSync(file) && !lstatSync(file).isSymbolicLink() && statSync(file).isFile();
+const mdFiles = (dir) => {
+  if (!existsSync(dir) || lstatSync(dir).isSymbolicLink() || !statSync(dir).isDirectory()) return [];
+  const out = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const full = join(dir, entry);
+    if (lstatSync(full).isSymbolicLink()) continue;
+    const st = statSync(full);
+    if (st.isDirectory()) out.push(...mdFiles(full));
+    else if (/\.(md|mdc|txt)$/i.test(entry)) out.push(full);
+  }
+  return out;
+};
+
+function geminiContextFiles(srcDir) {
+  let names = ['GEMINI.md'];
+  try {
+    const declared = readJson(join(srcDir, 'gemini-extension.json')).contextFileName;
+    if (typeof declared === 'string') names = [declared];
+    else if (Array.isArray(declared)) names = declared.filter((n) => typeof n === 'string');
+  } catch {}
+  return names;
+}
+
+export function cursorTrigger(data) {
+  const globs = Array.isArray(data.globs) ? data.globs.filter(Boolean).join(',') : (typeof data.globs === 'string' ? data.globs.trim() : '');
+  const description = typeof data.description === 'string' ? data.description.trim() : '';
+  if (data.alwaysApply === true) return { trigger: 'always_on' };
+  if (globs) return { trigger: 'glob', globs, ...(description ? { description } : {}) };
+  if (description) return { trigger: 'model_decision', description };
+  return { trigger: 'manual' };
+}
+
+const RULE_VAR_RE = /(?:\$\{(?:CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT|extensionPath|GEMINI_PLUGIN_PATH)\}|\$(?:CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT|extensionPath|GEMINI_PLUGIN_PATH)\b)((?:[\\/]|\$\{\/\})+)([^\s"'`<>|*?()[\]{}]*)/g;
+const RULE_VAR_BARE_RE = /\$\{(?:CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT|extensionPath|GEMINI_PLUGIN_PATH)\}|\$(?:CLAUDE_PLUGIN_ROOT|PLUGIN_ROOT|extensionPath|GEMINI_PLUGIN_PATH)\b/g;
+
+export function rewriteRuleVars(text, label, report) {
+  if (typeof text !== 'string') return text;
+  let count = 0;
+  let out = text.replace(RULE_VAR_RE, (_, _sep, tail) => {
+    count++;
+    const normalizedTail = (tail ?? '').replace(/(?:\$\{\/\}|[\\/])+/g, '/');
+    return `./${normalizedTail}`;
+  });
+  out = out.replace(RULE_VAR_BARE_RE, () => {
+    count++;
+    return '.';
+  });
+  if (count > 0 && report) {
+    const msg = `${label}: rewrote plugin-root variable(s) to relative path(s)`;
+    if (!report.warnings.includes(msg)) report.warnings.push(msg);
+  }
+  return out;
+}
+
+// A glob-scoped or manual Cursor rule becomes a skill the agent can pull in.
+function mdcToSkill(pluginDir, base, trigger, body, item, report) {
+  let name = slugifyName(base);
+  for (let n = 2; existsSync(join(pluginDir, 'skills', name)); n++) name = `${slugifyName(base)}-${n}`;
+  const rawDescription = trigger.trigger === 'glob'
+    ? `Use when working on files matching ${trigger.globs}.${trigger.description ? ` ${trigger.description}` : ''}`
+    : `Use only when the user asks for the "${base}" rule.`;
+  const description = rewriteRuleVars(rawDescription, item, report);
+  const cleanBody = rewriteRuleVars(body, item, report);
+  mkdirSync(join(pluginDir, 'skills', name), { recursive: true });
+  writeFileSync(join(pluginDir, 'skills', name, 'SKILL.md'), formatFrontmatter({ name, description }, `\n${cleanBody.trim()}\n`));
+  report.ported.push(`${item} → skills/${name}`);
+}
+
+export function compileRules(pluginDir, { srcDir, ecosystems }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const rulesDir = join(pluginDir, 'rules');
+  const outputs = [];
+  const used = new Set(existsSync(rulesDir) ? readdirSync(rulesDir).map((f) => f.toLowerCase()) : []);
+  const add = (file, rawContent, item, alwaysOn) => {
+    const content = rewriteRuleVars(rawContent, item, report);
+    if (Buffer.byteLength(content) > RULE_BYTES) {
+      report.unported.push({ item, reason: `over agy's 24 KB per-rule limit (${Buffer.byteLength(content)} bytes); agy would truncate it` });
+      return;
+    }
+    let name = file;
+    for (let n = 2; used.has(name.toLowerCase()); n++) name = file.replace(/\.md$/, `-${n}.md`);
+    used.add(name.toLowerCase());
+    outputs.push({ name, content, alwaysOn });
+    report.ported.push(`${item} → rules/${name}`);
+  };
+
+  const preExisting = existsSync(rulesDir)
+    ? readdirSync(rulesDir).filter((f) => /\.md$/i.test(f) && isFile(join(rulesDir, f)))
+    : [];
+
+  // Always-on context files become one rules/AGENTS.md.
+  const context = [];
+  if (ecosystems.includes('claude')) context.push('CLAUDE.md');
+  if (ecosystems.includes('gemini')) context.push(...geminiContextFiles(srcDir));
+  if (ecosystems.includes('codex')) context.push('AGENTS.md');
+  const sections = [];
+  const sources = [];
+  for (const name of [...new Set(context)]) {
+    const file = join(srcDir, name);
+    if (!isFile(file)) continue;
+    const text = read(file).trim();
+    if (!text) continue;
+    if (/^@(?!\[)\S+/m.test(text)) report.warnings.push(`${name}: "@path" imports aren't expanded by agy (it uses @[label](path))`);
+    sections.push(text);
+    sources.push(name);
+  }
+  if (sections.length) {
+    // Merge with a rules/AGENTS.md the source already shipped.
+    if (isFile(join(rulesDir, 'AGENTS.md'))) sections.unshift(read(join(rulesDir, 'AGENTS.md')).trim());
+    used.delete('agents.md');
+    add('AGENTS.md', `${sections.join('\n\n')}\n`, sources.join(' + '), true);
+  }
+
+  for (const f of preExisting) {
+    if (sections.length && f.toLowerCase() === 'agents.md') continue;
+    const full = join(rulesDir, f);
+    const raw = read(full);
+    const item = `rules/${f}`;
+    const content = rewriteRuleVars(raw, item, report);
+    if (Buffer.byteLength(content) > RULE_BYTES) {
+      rmSync(full, { force: true });
+      used.delete(f.toLowerCase());
+      report.unported.push({ item, reason: `over agy's 24 KB per-rule limit (${Buffer.byteLength(content)} bytes); agy would truncate it` });
+      continue;
+    }
+    if (content !== raw) writeFileSync(full, content);
+    let alwaysOn = true;
+    try {
+      const fm = splitFrontmatter(content);
+      if (fm.hasFrontmatter && fm.data.trigger && fm.data.trigger !== 'always_on') alwaysOn = false;
+    } catch {}
+    outputs.push({ name: f, content, alwaysOn, existing: true });
+  }
+
+  if (ecosystems.includes('cursor')) {
+    for (const file of mdFiles(join(srcDir, '.cursor/rules')).filter((f) => f.endsWith('.mdc'))) {
+      let parsed;
+      try { parsed = splitFrontmatter(read(file)); } catch (err) {
+        report.unported.push({ item: `.cursor/rules/${basename(file)}`, reason: `frontmatter isn't parseable: ${err.message}` });
+        continue;
+      }
+      const trigger = cursorTrigger(parsed.data);
+      const item = `.cursor/rules/${basename(file)} (${trigger.trigger})`;
+      if (/^@\S+/m.test(parsed.body)) report.warnings.push(`.cursor/rules/${basename(file)}: "@file" references aren't expanded by agy`);
+      if (trigger.trigger === 'glob' || trigger.trigger === 'manual') {
+        mdcToSkill(pluginDir, basename(file, '.mdc'), trigger, parsed.body, item, report);
+        continue;
+      }
+      if (trigger.description) trigger.description = rewriteRuleVars(trigger.description, item, report);
+      add(`${slugifyName(basename(file, '.mdc'))}.md`, formatFrontmatter(trigger, parsed.body.trim() + '\n'), item, trigger.trigger === 'always_on');
+    }
+    if (isFile(join(srcDir, '.cursorrules'))) {
+      add('cursorrules.md', formatFrontmatter({ trigger: 'always_on' }, `${read(join(srcDir, '.cursorrules')).trim()}\n`), '.cursorrules', true);
+    }
+  }
+
+  if (ecosystems.includes('roo')) {
+    const workspace = [
+      ...mdFiles(join(srcDir, '.roo/rules')), ...mdFiles(join(srcDir, '.kilocode/rules')),
+      ...mdFiles(join(srcDir, '.clinerules')),
+      ...['.roorules', '.kilocoderules', '.clinerules'].map((f) => join(srcDir, f)).filter(isFile),
+    ];
+    for (const file of workspace) {
+      const rel = file.slice(srcDir.length + 1).replace(/\\/g, '/');
+      add(`${slugifyName(rel.replace(/\.(md|txt)$/i, ''))}.md`, formatFrontmatter({ trigger: 'always_on' }, `${read(file).trim()}\n`), rel, true);
+    }
+  }
+
+  // Root context files agy staged are never loaded from there.
+  for (const name of ['CLAUDE.md', 'GEMINI.md', 'AGENTS.md', ...geminiContextFiles(srcDir)]) {
+    rmSync(join(pluginDir, name), { force: true });
+  }
+  const newOutputs = outputs.filter((o) => !o.existing);
+  if (newOutputs.length) mkdirSync(rulesDir, { recursive: true });
+  for (const { name, content } of newOutputs) writeFileSync(join(rulesDir, name), content);
+
+  const alwaysOnTokens = Math.ceil(outputs.filter((o) => o.alwaysOn).reduce((n, o) => n + Buffer.byteLength(o.content), 0) / 4);
+  if (alwaysOnTokens > RULES_BUDGET_TOKENS) {
+    report.warnings.push(`rules: about ${alwaysOnTokens} tokens of always-on rules, over agy's ${RULES_BUDGET_TOKENS}-token budget; agy shows the excess as file pointers`);
+  }
+  return report;
+}

package/lib/skill-compiler.mjs

@@ -0,0 +1,135 @@
+// Normalizes skills in a staged plugin dir so agy loads them under the right
+// name: the skills `agy plugin install` made from Claude/Gemini commands
+// (no `name`, Claude-only keys, argument placeholders) and native skills. It
+// also brings in Codex's `.agents/skills`. `commands/` is removed afterwards:
+// plugins don't load it, and agy has already converted it.
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { rewriteRuleVars } from './rules-compiler.mjs';
+import { formatFrontmatter, splitFrontmatter } from './yaml-lite.mjs';
+
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+const CLAUDE_ONLY_KEYS = ['argument-hint', 'allowed-tools', 'model', 'disable-model-invocation'];
+const ARGS = /\$ARGUMENTS\b|\{\{\s*args\s*\}\}|\$[1-9]\b/g;
+const SKILL_BYTES = 24_000;
+
+const dirs = (dir) => (existsSync(dir) ? readdirSync(dir).filter((d) => statSync(join(dir, d)).isDirectory()) : []);
+
+// Linear on any input: no regex that can backtrack over runs of "-".
+export function slugifyName(text) {
+  const slug = String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join('-').slice(0, 64);
+  return (slug.endsWith('-') ? slug.slice(0, -1) : slug) || 'skill';
+}
+
+function firstLine(body) {
+  const line = body.split('\n').map((l) => l.replace(/^#+\s*/, '').trim()).find((l) => l);
+  return line ? line.slice(0, 200) : '';
+}
+
+// Rewrites one SKILL.md in place. Returns the skill's final folder name.
+export function normalizeSkill(skillsDir, folder, report, { fromCommand = false } = {}) {
+  const file = join(skillsDir, folder, 'SKILL.md');
+  const text = readFileSync(file, 'utf8');
+  let { data, body, hasFrontmatter } = (() => {
+    try { return splitFrontmatter(text); } catch (err) {
+      report.warnings.push(`skill:${folder}: frontmatter isn't parseable (${err.message}); rebuilt from the folder name`);
+      return { data: {}, body: text.replace(/\r\n?/g, '\n').replace(/^---\n[\s\S]*?\n---\n?/, ''), hasFrontmatter: false };
+    }
+  })();
+  const notes = [];
+  let name = typeof data.name === 'string' && SKILL_NAME.test(data.name) ? data.name : null;
+  let finalFolder = folder;
+  if (name && name !== folder) {
+    if (!existsSync(join(skillsDir, name))) {
+      renameSync(join(skillsDir, folder), join(skillsDir, name));
+      finalFolder = name;
+    } else {
+      notes.push(`renamed from "${name}" to match its folder`);
+      name = folder;
+    }
+  }
+  if (!name) name = SKILL_NAME.test(folder) ? folder : slugifyName(folder);
+  if (name !== finalFolder && !existsSync(join(skillsDir, name))) {
+    // agy names a skill after its frontmatter and wants the folder to match.
+    renameSync(join(skillsDir, finalFolder), join(skillsDir, name));
+    finalFolder = name;
+  } else if (name !== finalFolder) {
+    name = finalFolder;
+  }
+  const out = { name, ...data };
+  out.name = name;
+  const dropped = CLAUDE_ONLY_KEYS.filter((k) => k in out);
+  dropped.forEach((k) => delete out[k]);
+  if (dropped.length) notes.push(`dropped ${dropped.join(', ')}`);
+  if (typeof out.description !== 'string' || !out.description.trim()) {
+    out.description = firstLine(body) || `Ported skill ${name}.`;
+    notes.push('description taken from the body');
+  }
+  const replaced = body.match(ARGS);
+  if (replaced) {
+    body = body.replace(ARGS, "the user's request");
+    notes.push(`replaced ${[...new Set(replaced)].join(', ')} with "the user's request" (skills take no arguments)`);
+  }
+  if (/^!`|!\{[^}]*\}/m.test(body)) {
+    report.warnings.push(`skill:${name}: inline shell execution (!\`…\` / !{…}) isn't supported by agy and is left as text`);
+  }
+  out.description = rewriteRuleVars(out.description, `skill:${name}`, report);
+  body = rewriteRuleVars(body, `skill:${name}`, report);
+  const rewritten = formatFrontmatter(out, body);
+  const changed = !hasFrontmatter || rewritten !== text.replace(/^/, '').replace(/\r\n?/g, '\n');
+  if (changed) writeFileSync(join(skillsDir, finalFolder, 'SKILL.md'), rewritten);
+  if (Buffer.byteLength(body) > SKILL_BYTES) report.warnings.push(`skill:${name}: body is over agy's 24 KB skill limit`);
+  if (notes.length) report.warnings.push(`skill:${name}: ${notes.join('; ')}`);
+  report.ported.push(fromCommand ? `command → skill:${name}` : `skill:${name}`);
+  return finalFolder;
+}
+
+// Command skills agy made: Claude's are `<plugin>-cmd-<x>`, Gemini's are named
+// after the .toml file. Anything that came from commands/ is "fromCommand".
+function commandNames(srcDir) {
+  const names = new Set();
+  const walk = (dir) => {
+    for (const entry of existsSync(dir) ? readdirSync(dir) : []) {
+      const full = join(dir, entry);
+      if (statSync(full).isDirectory()) walk(full);
+      else names.add(entry.replace(/\.(md|toml)$/i, ''));
+    }
+  };
+  walk(join(srcDir, 'commands'));
+  return names;
+}
+
+export function compileSkills(pluginDir, { srcDir, ecosystems }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const skillsDir = join(pluginDir, 'skills');
+  const commands = commandNames(srcDir);
+
+  if (ecosystems.includes('codex')) {
+    for (const folder of dirs(join(srcDir, '.agents/skills'))) {
+      if (!existsSync(join(srcDir, '.agents/skills', folder, 'SKILL.md'))) continue;
+      if (existsSync(join(skillsDir, folder))) {
+        report.unported.push({ item: `skill:${folder}`, reason: 'a skill with this name already exists in the plugin' });
+        continue;
+      }
+      cpSync(join(srcDir, '.agents/skills', folder), join(skillsDir, folder), { recursive: true });
+    }
+  }
+
+  for (const folder of dirs(skillsDir)) {
+    if (!existsSync(join(skillsDir, folder, 'SKILL.md'))) {
+      report.warnings.push(`skills/${folder}: no SKILL.md, so agy ignores it`);
+      continue;
+    }
+    const fromCommand = commands.has(folder) || [...commands].some((c) => folder.endsWith(`-cmd-${c}`));
+    normalizeSkill(skillsDir, folder, report, { fromCommand });
+  }
+  if (existsSync(join(pluginDir, 'commands'))) {
+    const converted = report.ported.filter((p) => p.startsWith('command')).length;
+    if (converted < commands.size) {
+      report.unported.push({ item: 'commands/', reason: `${commands.size - converted} command(s) weren't converted to skills by agy` });
+    }
+    rmSync(join(pluginDir, 'commands'), { recursive: true, force: true });
+  }
+  return report;
+}

package/lib/source.mjs

@@ -0,0 +1,81 @@
+// Resolves a --source: a local path, or `owner/repo[@ref]` fetched from GitHub
+// at that ref (tag, branch or commit SHA) into a temp dir.
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+
+// Owner, repo and ref can't start with "-", so none of them can reach git as an
+// option (e.g. a ref of `--upload-pack=<cmd>`). Refs are limited to the
+// characters tag, branch and SHA names use.
+const GITHUB = /^([A-Za-z0-9][A-Za-z0-9-]*)\/([A-Za-z0-9_.][A-Za-z0-9_.-]*?)(?:\.git)?(?:@([A-Za-z0-9_][A-Za-z0-9_./-]*))?$/;
+
+function git(args, cwd) {
+  const run = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 300_000 });
+  if (run.error) throw new Error(`can't run git: ${run.error.message}`);
+  if (run.status !== 0) throw new Error(`git ${args[0]} failed: ${run.stderr.trim()}`);
+  return run.stdout.trim();
+}
+
+function makeWritable(dir) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) makeWritable(p);
+    else if (e.isFile()) chmodSync(p, 0o666);
+  }
+}
+
+// rmSync -r -f, except that Node 24's rmSync (agy-node's) can't delete read-only
+// files on Windows, which a git clone's pack files are: on EPERM, make every file
+// writable and try once more.
+export function removeTree(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch (err) {
+    if (err.code !== 'EPERM' || !existsSync(dir)) throw err;
+    makeWritable(dir);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+export function parseSourceSpec(spec) {
+  if (existsSync(spec)) return { kind: 'path', path: resolve(spec) };
+  const m = GITHUB.exec(spec);
+  if (!m || m[3]?.includes('..')) throw new Error(`source "${spec}" is neither an existing path nor owner/repo[@ref]`);
+  return { kind: 'github', owner: m[1], repo: m[2], ref: m[3] ?? null };
+}
+
+// Returns {dir, commit, cleanup}. `subPath` picks a folder inside the source.
+export function resolveSource(spec, { subPath } = {}) {
+  const parsed = parseSourceSpec(spec);
+  let root;
+  let commit = null;
+  let cleanup = () => {};
+  if (parsed.kind === 'path') {
+    root = parsed.path;
+  } else {
+    root = mkdtempSync(join(tmpdir(), 'agy-porter-src-'));
+    cleanup = () => removeTree(root);
+    try {
+      const ref = parsed.ref ?? 'HEAD';
+      if (ref.startsWith('-')) throw new Error(`invalid ref "${ref}"`);
+      git(['init', '-q'], root);
+      // Keep the upstream's line endings: on Windows, autocrlf would rewrite every file.
+      git(['config', 'core.autocrlf', 'false'], root);
+      // "--": git reads everything after it as a repository or refspec, never an option.
+      git(['fetch', '-q', '--depth', '1', '--', `https://github.com/${parsed.owner}/${parsed.repo}.git`, ref], root);
+      git(['checkout', '-q', 'FETCH_HEAD'], root);
+      commit = git(['rev-parse', 'HEAD'], root);
+    } catch (err) {
+      cleanup();
+      throw err;
+    }
+  }
+  const dir = subPath ? resolve(root, subPath) : root;
+  const rel = relative(root, dir);
+  if (rel.startsWith('..') || isAbsolute(rel) || !existsSync(dir) || !statSync(dir).isDirectory()) {
+    cleanup();
+    throw new Error(`no folder "${subPath}" in ${spec}`);
+  }
+  return { dir, commit, unpinned: parsed.kind === 'github' && !parsed.ref, cleanup };
+}

package/lib/static-auditor.mjs

@@ -0,0 +1,179 @@
+// Scans a ported plugin dir before it's installed. It strips Unicode tag
+// characters (U+E0000–E007F, invisible prompt-injection carriers), flags risky
+// patterns, checks agy's rule and skill size limits, and infers the capability
+// tier with the same names and meaning as Hangar's TIER_*.
+import { closeSync, existsSync, fstatSync, ftruncateSync, lstatSync, openSync, readdirSync, readFileSync, writeSync } from 'node:fs';
+import { extname, join } from 'node:path';
+
+import { extractServerMap } from './manifest-sanitizer.mjs';
+import { RULE_BYTES, RULES_BUDGET_TOKENS } from './rules-compiler.mjs';
+import { splitFrontmatter } from './yaml-lite.mjs';
+
+export const TIERS = ['TIER_1_TELEMETRY', 'TIER_2_LOCAL_TOOLING', 'TIER_3_AGENT_CONTROL'];
+const MAX_SCAN_BYTES = 1_000_000;
+const BINARY_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.pdf', '.zip', '.gz', '.wasm', '.woff', '.woff2', '.ttf', '.exe', '.dll', '.so', '.dylib']);
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+const TAGS = /[\u{E0000}-\u{E007F}]/gu;
+const BIDI = /[\u202A-\u202E\u2066-\u2069]/;
+const PATTERNS = [
+  ['pipe-to-shell', 'high', /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(ba|z|da|k)?sh\b/i],
+  ['pipe-to-shell', 'high', /\b(iwr|irm|Invoke-WebRequest|Invoke-RestMethod)\b[^\n|]*\|\s*(iex|Invoke-Expression)\b/i],
+  ['decode-and-exec', 'high', /base64\s+(-d|--decode)\b[^\n]*\|\s*(ba|z)?sh\b/i],
+  ['decode-and-exec', 'high', /\b(eval|exec|Function)\s*\(\s*(atob|Buffer\.from|base64\.b64decode)\s*\(/],
+  ['decode-and-exec', 'high', /FromBase64String\([^\n]*\)[^\n]*(iex|Invoke-Expression)/i],
+  ['encoded-powershell', 'high', /\bpowershell(\.exe)?\b[^\n]*\s-(e|ec|enc|encodedcommand)\s+[A-Za-z0-9+/=]{20,}/i],
+];
+const TOKEN = /[A-Za-z0-9+/=_-]{40,}/g;
+
+export function shannon(s) {
+  const counts = {};
+  for (const c of s) counts[c] = (counts[c] ?? 0) + 1;
+  return Object.values(counts).reduce((h, n) => h - (n / s.length) * Math.log2(n / s.length), 0);
+}
+
+// A long token that reads like a key or an encoded payload, not like an
+// alphabet table, a URL path or a subresource-integrity hash.
+export function looksRandom(token, before = '') {
+  if (shannon(token) <= 4.5) return false;
+  if (!/[A-Z]/.test(token) || !/[a-z]/.test(token) || !/\d/.test(token)) return false;
+  if (/sha(256|384|512)-$/.test(before) || /^sha(256|384|512)-/.test(token)) return false;
+  if ((token.match(/\//g) ?? []).length >= 2 && !/[+=]/.test(token)) return false;
+  for (let i = 0, run = 1; i < token.length - 1; i++) {
+    run = token.charCodeAt(i + 1) === token.charCodeAt(i) + 1 ? run + 1 : 1;
+    if (run >= 6) return false;
+  }
+  return true;
+}
+
+function* walk(dir, rel = '') {
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const full = join(dir, entry);
+    let lst;
+    try { lst = lstatSync(full); } catch { continue; }
+    if (lst.isSymbolicLink()) continue;
+    const path = rel ? `${rel}/${entry}` : entry;
+    if (lst.isDirectory()) yield* walk(full, path);
+    else if (lst.isFile()) yield { full, path };
+  }
+}
+
+const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+
+export function auditText(path, text) {
+  const flags = [];
+  for (const [kind, severity, re] of PATTERNS) {
+    const m = re.exec(text);
+    if (m) flags.push({ kind, severity, file: path, line: lineOf(text, m.index), excerpt: m[0].slice(0, 120) });
+  }
+  if (BIDI.test(text)) flags.push({ kind: 'bidi-control', severity: 'medium', file: path, line: lineOf(text, text.search(BIDI)) });
+  // Lockfiles and source maps are full of hashes; skip them for entropy.
+  if (!/(\.lock|lock\.json|\.map)$/i.test(path)) {
+    for (const m of text.matchAll(TOKEN)) {
+      if (looksRandom(m[0], text.slice(Math.max(0, m.index - 7), m.index))) {
+        flags.push({ kind: 'high-entropy', severity: 'medium', file: path, line: lineOf(text, m.index), excerpt: `${m[0].slice(0, 12)}…` });
+        break;
+      }
+    }
+  }
+  return flags;
+}
+
+function readJsonIf(file) {
+  try { return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null; } catch { return null; }
+}
+
+function collectHookEvents(obj, events) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return;
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === 'enabled' || k === 'description' || k === 'modules') continue;
+    if (Array.isArray(v)) events.add(k);
+    else if (v && typeof v === 'object') collectHookEvents(v, events);
+  }
+}
+
+// TIER_2: anything that runs a local command (hooks, stdio MCP servers, sidecars).
+// TIER_3: subagents, or hooks that steer the agent loop (Stop, PostInvocation).
+export function inferTier(pluginDir) {
+  const reasons = [];
+  let rank = 0;
+  const events = new Set();
+  for (const rel of ['hooks.json', 'hooks/hooks.json', '.claude-plugin/hooks.json']) {
+    collectHookEvents(readJsonIf(join(pluginDir, rel)), events);
+  }
+  for (const rel of ['plugin.json', '.claude-plugin/plugin.json']) {
+    const manifest = readJsonIf(join(pluginDir, rel));
+    if (manifest?.hooks && typeof manifest.hooks === 'object') collectHookEvents(manifest.hooks, events);
+  }
+  if (events.size) { rank = Math.max(rank, 1); reasons.push(`hooks: ${[...events].join(', ')}`); }
+  if (events.has('Stop') || events.has('PostInvocation')) { rank = 2; reasons.push('a hook can keep the agent running'); }
+  const mcpMap = {};
+  for (const rel of ['mcp_config.json', '.mcp.json', 'mcp.json']) {
+    Object.assign(mcpMap, extractServerMap(readJsonIf(join(pluginDir, rel))));
+  }
+  for (const rel of ['plugin.json', '.claude-plugin/plugin.json', 'gemini-extension.json']) {
+    const manifest = readJsonIf(join(pluginDir, rel));
+    if (manifest?.mcpServers && typeof manifest.mcpServers === 'object' && !Array.isArray(manifest.mcpServers)) {
+      Object.assign(mcpMap, extractServerMap({ mcpServers: manifest.mcpServers }));
+    }
+  }
+  const servers = Object.entries(mcpMap);
+  if (servers.length) {
+    rank = Math.max(rank, 1);
+    reasons.push(`MCP servers: ${servers.map(([n]) => n).join(', ')}`);
+  }
+  const agentsDir = join(pluginDir, 'agents');
+  const agents = existsSync(agentsDir) ? readdirSync(agentsDir).filter((f) => f.endsWith('.md')) : [];
+  if (agents.length) { rank = 2; reasons.push(`agents: ${agents.map((f) => f.replace(/\.md$/, '')).join(', ')}`); }
+  // Sidecars, including ported UI mods, whose mod.json lists their scan's Tier 3 reasons.
+  const sidecarsDir = join(pluginDir, 'sidecars');
+  const sidecars = existsSync(sidecarsDir) ? readdirSync(sidecarsDir).filter((d) => existsSync(join(sidecarsDir, d, 'sidecar.json'))) : [];
+  if (sidecars.length) { rank = Math.max(rank, 1); reasons.push(`sidecars: ${sidecars.join(', ')} (a full Node process outside agy's permission prompts)`); }
+  for (const id of sidecars) {
+    const mod = readJsonIf(join(sidecarsDir, id, 'mod.json'));
+    if (mod?.tier !== TIERS[2]) continue;
+    rank = 2;
+    reasons.push(`UI mod ${id}: ${(mod.tierReasons ?? []).slice(1).join(', ')}`);
+  }
+  return { tier: TIERS[rank], reasons };
+}
+
+export function auditPlugin(pluginDir) {
+  const flags = [];
+  const warnings = [];
+  let alwaysOnBytes = 0;
+  for (const { full, path } of walk(pluginDir)) {
+    if (BINARY_EXT.has(extname(path).toLowerCase())) continue;
+    // One descriptor for the size check, the read and the rewrite, so the file
+    // can't be swapped between them.
+    const fd = openSync(full, 'r+');
+    let text;
+    try {
+      if (fstatSync(fd).size > MAX_SCAN_BYTES) { warnings.push(`audit: ${path} is over 1 MB and wasn't scanned`); continue; }
+      const buffer = readFileSync(fd);
+      if (buffer.includes(0)) continue;
+      text = buffer.toString('utf8');
+      const tags = text.match(TAGS);
+      if (tags) {
+        text = text.replace(TAGS, '');
+        const stripped = Buffer.from(text, 'utf8');
+        ftruncateSync(fd, 0);
+        writeSync(fd, stripped, 0, stripped.length, 0);
+        flags.push({ kind: 'unicode-tags-stripped', severity: 'high', file: path, count: tags.length });
+      }
+    } finally {
+      closeSync(fd);
+    }
+    flags.push(...auditText(path, text));
+    if (/^rules\/[^/]+\.md$/i.test(path)) {
+      if (Buffer.byteLength(text) > RULE_BYTES) flags.push({ kind: 'rule-over-limit', severity: 'medium', file: path, bytes: Buffer.byteLength(text) });
+      let alwaysOn = /^rules\/agents\.md$/i.test(path);
+      try { alwaysOn ||= splitFrontmatter(text).data.trigger === 'always_on'; } catch {}
+      if (alwaysOn) alwaysOnBytes += Buffer.byteLength(text);
+    }
+  }
+  const tokens = Math.ceil(alwaysOnBytes / 4);
+  if (tokens > RULES_BUDGET_TOKENS) flags.push({ kind: 'rules-over-budget', severity: 'medium', tokens });
+  return { flags, warnings, ...inferTier(pluginDir) };
+}

package/lib/tool-map.mjs

@@ -0,0 +1,46 @@
+// Source tool names -> agy tool names. Claude's comes from `agy plugin validate`
+// 1.4.5 (docs/agy-baseline.md, "Tool names"); where the CLI and the IDE name a
+// tool differently, both are listed. scripts/hook-shim.mjs keeps its own reverse
+// copy because it ships alone inside each ported plugin.
+export const TOOLS = {
+  claude: {
+    Bash: ['run_command'],
+    Read: ['view_file', 'read_file'],
+    Write: ['write_to_file', 'write_file'],
+    Edit: ['replace_file_content', 'edit_file'],
+    MultiEdit: ['multi_replace_file_content', 'edit_file'],
+    Grep: ['grep_search'],
+    Glob: ['find_by_name'],
+    LS: ['list_dir'],
+    WebFetch: ['read_url_content'],
+    WebSearch: ['search_web'],
+    NotebookEdit: ['notebook_edit'],
+    Task: ['invoke_subagent'],
+    Agent: ['invoke_subagent'],
+  },
+  gemini: {
+    run_shell_command: ['run_command'],
+    read_file: ['view_file', 'read_file'],
+    write_file: ['write_to_file', 'write_file'],
+    replace: ['replace_file_content', 'edit_file'],
+    glob: ['find_by_name'],
+    search_file_content: ['grep_search'],
+    list_directory: ['list_dir'],
+    web_fetch: ['read_url_content'],
+    google_web_search: ['search_web'],
+  },
+};
+
+export const AGY_TOOLS = new Set(Object.values(TOOLS).flatMap((m) => Object.values(m).flat()));
+
+// Roo/Kilo/Cline mode tool groups.
+export const ROO_GROUPS = {
+  read: ['view_file', 'read_file', 'list_dir', 'grep_search', 'find_by_name'],
+  edit: ['write_to_file', 'write_file', 'replace_file_content', 'edit_file', 'multi_replace_file_content'],
+  command: ['run_command'],
+};
+
+export function unmappedToolReason(name) {
+  if (name === 'TodoWrite' || /^Task(Create|Get|List|Update|Output|Stop)$/.test(name)) return 'agy has no built-in tool that does the same job';
+  return 'no agy tool with this name';
+}