agy-plugin-porter 0.0.0-stage → 0.1.0

package/lib/mode-compiler.mjs

@@ -0,0 +1,185 @@
+// Turns Claude Code agents and Roo/Kilo modes into agy agents (agents/<name>.md).
+// agy 1.4.x skips a Claude agent outright: `tools: Read, Grep` is a string
+// where agy wants a list, and `model: sonnet` isn't an agy model tier. So
+// tools are mapped to agy tool names, and models to agy's tiers (pro, flash,
+// flash_lite, inherit). Anything that can't be mapped is reported.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { slugifyName } from './skill-compiler.mjs';
+import { ROO_GROUPS, TOOLS, unmappedToolReason } from './tool-map.mjs';
+import { formatFrontmatter, parseYaml, splitFrontmatter } from './yaml-lite.mjs';
+
+// Names agy reserves for built-in agents (seen in agy 1.4.5's subagent list).
+const RESERVED = new Set(['self', 'research', 'image-generator']);
+const CLAUDE_AGENT_KEYS = new Set(['name', 'description', 'tools', 'model']);
+
+export function mapClaudeModel(model) {
+  if (model === undefined || model === null || model === '') return { tier: undefined };
+  const m = String(model).toLowerCase();
+  if (m === 'inherit') return { tier: 'inherit' };
+  if (m.includes('haiku')) return { tier: 'flash' };
+  if (m.includes('opus') || m.includes('sonnet')) return { tier: 'pro' };
+  return { tier: undefined, dropped: true };
+}
+
+// Splits `Read, Bash(git diff:*), Agent(a, b)` on top-level commas only.
+export function splitToolList(text) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '(') depth++;
+    else if (text[i] === ')') depth = Math.max(0, depth - 1);
+    else if (text[i] === ',' && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+export function mapClaudeTools(tools) {
+  const list = Array.isArray(tools) ? tools : splitToolList(String(tools));
+  const mapped = new Set();
+  const unmapped = [];
+  let mcp = false;
+  for (const raw of list.map((t) => String(t).trim()).filter(Boolean)) {
+    // `Bash(git diff:*)` -> `Bash`, without a regex that backtracks over "(".
+    const paren = raw.indexOf('(');
+    const name = (paren > 0 && raw.endsWith(')') ? raw.slice(0, paren) : raw).trim();
+    if (name.startsWith('mcp__')) mcp = true;
+    else if (TOOLS.claude[name]) TOOLS.claude[name].forEach((t) => mapped.add(t));
+    else unmapped.push(name);
+  }
+  return { tools: [...mapped].sort(), unmapped, mcp };
+}
+
+function agentName(raw, slug, report, item) {
+  let name = slugifyName(raw);
+  if (RESERVED.has(name)) {
+    report.warnings.push(`${item}: "${name}" is a built-in agy agent name; renamed to "${slug}-${name}"`);
+    name = `${slug}-${name}`;
+  }
+  return name;
+}
+
+function compileClaudeAgents(pluginDir, { slug, report, taken }) {
+  const dir = join(pluginDir, 'agents');
+  if (!existsSync(dir)) return;
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+    const item = `agent:${basename(file, '.md')}`;
+    let parsed;
+    try { parsed = splitFrontmatter(readFileSync(join(dir, file), 'utf8')); } catch (err) {
+      report.unported.push({ item, reason: `frontmatter isn't parseable: ${err.message}` });
+      rmSync(join(dir, file));
+      continue;
+    }
+    const { data, body } = parsed;
+    const name = agentName(data.name ?? basename(file, '.md'), slug, report, item);
+    const out = { name, description: typeof data.description === 'string' && data.description.trim() ? data.description : `Ported agent ${name}.` };
+    if (data.tools !== undefined && data.tools !== null && data.tools !== '*') {
+      const mapped = mapClaudeTools(data.tools);
+      out.tools = mapped.tools;
+      for (const t of mapped.unmapped) report.unported.push({ item: `${item} tool ${t}`, reason: unmappedToolReason(t) });
+      if (mapped.mcp) {
+        out.inheritMcp = true;
+        report.warnings.push(`${item}: MCP tools in "tools" became inheritMcp: true (all MCP tools, not just the listed ones)`);
+      }
+    }
+    const model = mapClaudeModel(data.model);
+    if (model.tier) out.model = model.tier;
+    if (model.dropped) report.warnings.push(`${item}: model "${data.model}" has no agy tier; the agent inherits the session's model`);
+    out.subagent = true;
+    const extra = Object.keys(data).filter((k) => !CLAUDE_AGENT_KEYS.has(k));
+    if (extra.length) report.warnings.push(`${item}: dropped ${extra.join(', ')}`);
+    rmSync(join(dir, file));
+    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, body));
+    taken.add(name);
+    report.ported.push(`${item} → agents/${name}.md`);
+  }
+}
+
+function readModes(srcDir, report) {
+  const modes = [];
+  for (const file of ['.roomodes', '.kilocodemodes']) {
+    const path = join(srcDir, file);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, 'utf8').replace(/^/, '');
+    let parsed;
+    try { parsed = text.trim().startsWith('{') ? JSON.parse(text) : parseYaml(text); } catch (err) {
+      report.unported.push({ item: file, reason: `can't parse: ${err.message}` });
+      continue;
+    }
+    for (const mode of parsed?.customModes ?? []) modes.push({ ...mode, file });
+  }
+  return modes;
+}
+
+function modeRules(srcDir, slug) {
+  const texts = [];
+  for (const dir of [`.roo/rules-${slug}`, `.kilocode/rules-${slug}`]) {
+    const full = join(srcDir, dir);
+    if (!existsSync(full)) continue;
+    for (const f of readdirSync(full).filter((x) => /\.(md|txt)$/i.test(x)).sort()) texts.push(readFileSync(join(full, f), 'utf8').trim());
+  }
+  for (const f of [`.roorules-${slug}`, `.clinerules-${slug}`]) {
+    if (existsSync(join(srcDir, f))) texts.push(readFileSync(join(srcDir, f), 'utf8').trim());
+  }
+  return texts.filter(Boolean);
+}
+
+// Restricted edit groups (`fileRegex`) aren't granted: agy agents can't limit
+// edits to a pattern, and widening a mode's permissions silently is worse than
+// reporting the gap.
+export function mapRooGroups(groups, item, report) {
+  const tools = new Set();
+  let mcp = false;
+  for (const group of Array.isArray(groups) ? groups : []) {
+    const [kind, options] = Array.isArray(group) ? group : [group, null];
+    if (kind === 'mcp') { mcp = true; continue; }
+    if (!ROO_GROUPS[kind]) {
+      report.unported.push({ item: `${item} group ${kind}`, reason: kind === 'browser' ? "agy's browser tool names aren't mapped yet" : 'unknown tool group' });
+      continue;
+    }
+    if (options?.fileRegex) {
+      report.unported.push({ item: `${item} group ${kind} (${options.fileRegex})`, reason: "agy agents can't restrict edits to a file pattern, so the group isn't granted" });
+      continue;
+    }
+    ROO_GROUPS[kind].forEach((t) => tools.add(t));
+  }
+  return { tools: [...tools].sort(), mcp };
+}
+
+function compileRooModes(pluginDir, { srcDir, slug, report, taken }) {
+  const modes = readModes(srcDir, report);
+  if (!modes.length) return;
+  const dir = join(pluginDir, 'agents');
+  mkdirSync(dir, { recursive: true });
+  for (const mode of modes) {
+    const item = `mode:${mode.slug ?? '?'}`;
+    if (typeof mode.slug !== 'string' || typeof mode.roleDefinition !== 'string') {
+      report.unported.push({ item, reason: 'a mode needs slug and roleDefinition' });
+      continue;
+    }
+    const name = agentName(mode.slug, slug, report, item);
+    if (taken.has(name)) {
+      report.unported.push({ item, reason: `an agent named ${name} already exists in the plugin` });
+      continue;
+    }
+    const { tools, mcp } = mapRooGroups(mode.groups, item, report);
+    const description = mode.whenToUse || mode.description || mode.roleDefinition.split(/(?<=\.)\s/)[0];
+    const out = { name, description, tools, ...(mcp ? { inheritMcp: true } : {}), mainAgent: true, subagent: true };
+    const body = [`# ${mode.name ?? mode.slug}`, mode.roleDefinition.trim(), mode.customInstructions?.trim(), ...modeRules(srcDir, mode.slug)]
+      .filter(Boolean).join('\n\n');
+    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, `\n${body}\n`));
+    taken.add(name);
+    report.ported.push(`${item} → agents/${name}.md`);
+  }
+}
+
+export function compileModes(pluginDir, { srcDir, ecosystems, slug }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const taken = new Set();
+  if (ecosystems.includes('claude')) compileClaudeAgents(pluginDir, { slug, report, taken });
+  if (ecosystems.includes('roo')) compileRooModes(pluginDir, { srcDir, slug, report, taken });
+  return report;
+}

package/lib/rules-compiler.mjs

@@ -0,0 +1,144 @@
+// 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, 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) && statSync(file).isFile();
+const mdFiles = (dir) => (existsSync(dir) && statSync(dir).isDirectory()
+  ? readdirSync(dir).filter((f) => /\.(md|mdc|txt)$/i.test(f)).sort().map((f) => join(dir, f))
+  : []);
+
+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' };
+}
+
+// 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 description = 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.`;
+  mkdirSync(join(pluginDir, 'skills', name), { recursive: true });
+  writeFileSync(join(pluginDir, 'skills', name, 'SKILL.md'), formatFrontmatter({ name, description }, `\n${body.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, content, item, alwaysOn) => {
+    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}`);
+  };
+
+  // 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);
+  }
+
+  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;
+      }
+      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 });
+  }
+  if (outputs.length) mkdirSync(rulesDir, { recursive: true });
+  for (const { name, content } of outputs) 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,132 @@
+// 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 { 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(/^---\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`);
+  }
+  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,58 @@
+// 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 { existsSync, mkdtempSync, 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();
+}
+
+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 = () => rmSync(root, { recursive: true, force: true });
+    try {
+      const ref = parsed.ref ?? 'HEAD';
+      if (ref.startsWith('-')) throw new Error(`invalid ref "${ref}"`);
+      git(['init', '-q'], 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,140 @@
+// 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, openSync, readdirSync, readFileSync, statSync, writeSync } from 'node:fs';
+import { extname, join } from 'node:path';
+
+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 = /[‪-‮⁦-⁩]/;
+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);
+    const path = rel ? `${rel}/${entry}` : entry;
+    if (statSync(full).isDirectory()) yield* walk(full, path);
+    else 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; }
+}
+
+// TIER_2: anything that runs a local command (hooks, stdio MCP servers).
+// TIER_3: subagents, or hooks that steer the agent loop (Stop, PostInvocation).
+export function inferTier(pluginDir) {
+  const reasons = [];
+  let rank = 0;
+  const hooks = readJsonIf(join(pluginDir, 'hooks.json')) ?? {};
+  const events = new Set(Object.values(hooks).flatMap((h) => Object.keys(h ?? {})).filter((e) => e !== 'enabled'));
+  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 servers = Object.entries(readJsonIf(join(pluginDir, 'mcp_config.json'))?.mcpServers ?? {});
+  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(', ')}`); }
+  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) };
+}