@iglooinsure/agent-plugin 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# Igloo Agent Plugin
+
+Universal compatibility installer for Claude-style agent plugin marketplaces.
+
+`igloo-agent-plugin` reads a Claude Code marketplace (`.claude-plugin/marketplace.json`), normalizes plugin metadata and skills, then installs the portable skill subset into Claude, Codex, or Cursor layouts.
+
+## Install
+
+```bash
+npm install -g @iglooinsure/agent-plugin
+```
+
+The package exposes two commands:
+
+```bash
+igloo-agent-plugin --help
+iap --help
+```
+
+## Quick Start
+
+```bash
+igloo-agent-plugin marketplace add .
+igloo-agent-plugin marketplace list
+igloo-agent-plugin search
+igloo-agent-plugin doctor ops-toolkit
+igloo-agent-plugin install ops-toolkit --target codex --dry-run
+igloo-agent-plugin install ops-toolkit --target codex
+```
+
+## Commands
+
+### Marketplace
+
+```bash
+igloo-agent-plugin marketplace add <source>
+igloo-agent-plugin marketplace list
+igloo-agent-plugin marketplace refresh [name]
+```
+
+Supported sources:
+
+- Local marketplace root containing `.claude-plugin/marketplace.json`
+- Direct path to `.claude-plugin/marketplace.json`
+- Git URL
+
+CLI state is stored under `~/.igloo-agent-plugin` by default. Set `IGLOO_AGENT_PLUGIN_HOME` to override it.
+
+### Search
+
+```bash
+igloo-agent-plugin search [query]
+igloo-agent-plugin search kubernetes --target codex
+```
+
+Search lists marketplace plugin entries and compatibility status when a target is provided.
+
+### Install
+
+```bash
+igloo-agent-plugin install <plugin[@marketplace]> --target codex
+igloo-agent-plugin install <plugin[@marketplace]> --target cursor
+igloo-agent-plugin install <plugin[@marketplace]> --target claude
+igloo-agent-plugin install <plugin[@marketplace]> --target all
+```
+
+Common options:
+
+```text
+--scope user|project
+--dry-run
+--force
+--symlink
+--layout namespaced|flat
+```
+
+Codex installs are generated at:
+
+```text
+~/.codex/plugins/<plugin-name>/
+  .codex-plugin/plugin.json
+  skills/<skill-name>/SKILL.md
+
+~/.agents/plugins/
+  marketplace.json
+  <plugin-name>/
+```
+
+Cursor installs the skill subset at:
+
+```text
+~/.cursor/skills/<plugin-name>/<skill-name>/SKILL.md
+```
+
+Claude support is currently a passthrough guide because Claude Code owns its native plugin install state.
+
+### Uninstall
+
+```bash
+igloo-agent-plugin uninstall <plugin> --target codex
+igloo-agent-plugin uninstall <plugin> --target cursor
+```
+
+Uninstall only removes paths recorded in this CLI's install manifest.
+
+### Doctor
+
+```bash
+igloo-agent-plugin doctor
+igloo-agent-plugin doctor --all
+igloo-agent-plugin doctor ops-toolkit --target cursor
+```
+
+Doctor reports skill availability and warns about unsupported cross-tool components such as hooks, agents, MCP, LSP, monitors, commands, `bin`, and settings.
+
+## Development
+
+This implementation intentionally has no runtime dependencies.
+
+```bash
+npm test
+```
+
+The tests use temporary `HOME` and `IGLOO_AGENT_PLUGIN_HOME` directories so they do not modify your real tool configuration.

package/bin/igloo-agent-plugin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@iglooinsure/agent-plugin",
+  "version": "0.1.0",
+  "description": "Universal compatibility installer for Claude-style agent plugin marketplaces.",
+  "type": "module",
+  "bin": {
+    "igloo-agent-plugin": "./bin/igloo-agent-plugin.js",
+    "iap": "./bin/igloo-agent-plugin.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/src/adapters/claude.js

@@ -0,0 +1,23 @@
+import { compatibility, defaultInstallPlan } from "./common.js";
+
+export const claudeAdapter = {
+  name: "claude",
+
+  doctor(pkg) {
+    return compatibility(pkg, "claude");
+  },
+
+  async planInstall(pkg, opts) {
+    const command = `claude plugin install ${pkg.name}@${pkg.marketplace} --scope ${opts.scope || "user"}`;
+    return defaultInstallPlan("claude", pkg, opts, [], [
+      `Claude is the source format. Run native install command: ${command}`,
+    ]);
+  },
+
+  async planUninstall(installRef) {
+    const command = `claude plugin uninstall ${installRef.plugin} --scope ${installRef.scope || "user"}`;
+    return defaultInstallPlan("claude", { name: installRef.plugin, marketplace: installRef.marketplace }, installRef, [], [
+      `Run native Claude command: ${command}`,
+    ]);
+  },
+};

package/src/adapters/codex.js

@@ -0,0 +1,111 @@
+import os from "node:os";
+import path from "node:path";
+import { op } from "../operations.js";
+import { exists, readJson } from "../utils.js";
+import { compatibility, defaultInstallPlan } from "./common.js";
+
+export const codexAdapter = {
+  name: "codex",
+
+  doctor(pkg) {
+    return compatibility(pkg, "codex");
+  },
+
+  async planInstall(pkg, opts) {
+    const home = os.homedir();
+    const pluginDir = path.join(home, ".codex", "plugins", pkg.name);
+    const marketplaceRoot = path.join(home, ".agents", "plugins");
+    const marketplacePath = path.join(marketplaceRoot, "marketplace.json");
+    const linkPath = path.join(marketplaceRoot, pkg.name);
+    const operations = [
+      op("mkdir", { path: pluginDir }),
+      ...pkg.skills.map((skill) =>
+        op("copy", {
+          from: skill.path,
+          to: path.join(pluginDir, "skills", skill.directoryName),
+        }),
+      ),
+      op("write_json", {
+        to: path.join(pluginDir, ".codex-plugin", "plugin.json"),
+        value: {
+          name: pkg.name,
+          version: pkg.version || "0.0.0-local",
+          description: pkg.description,
+          skills: "./skills/",
+        },
+      }),
+    ];
+
+    if (opts.symlink) operations.push(op("symlink", { from: pluginDir, to: linkPath }));
+    else operations.push(op("copy", { from: pluginDir, to: linkPath }));
+
+    operations.push(
+      op("write_json", {
+        to: marketplacePath,
+        value: await nextCodexMarketplace(marketplacePath, pkg),
+        allowExisting: true,
+      }),
+    );
+
+    const report = this.doctor(pkg);
+    return defaultInstallPlan(
+      "codex",
+      pkg,
+      { ...opts, recordPaths: [pluginDir, linkPath, marketplacePath] },
+      operations,
+      report.warnings,
+    );
+  },
+
+  async planUninstall(installRef) {
+    const home = os.homedir();
+    const pluginDir = path.join(home, ".codex", "plugins", installRef.plugin);
+    const marketplaceRoot = path.join(home, ".agents", "plugins");
+    const linkPath = path.join(marketplaceRoot, installRef.plugin);
+    const marketplacePath = path.join(marketplaceRoot, "marketplace.json");
+    const operations = [
+      op("remove", { path: pluginDir }),
+      op("remove", { path: linkPath }),
+    ];
+    if (await exists(marketplacePath)) {
+      operations.push(
+        op("write_json", {
+          to: marketplacePath,
+          value: await removeCodexMarketplaceEntry(marketplacePath, installRef.plugin),
+        }),
+      );
+    }
+    return defaultInstallPlan(
+      "codex",
+      { name: installRef.plugin, marketplace: installRef.marketplace },
+      { scope: installRef.scope, recordPaths: [pluginDir, linkPath, marketplacePath] },
+      operations,
+      [],
+    );
+  },
+};
+
+async function nextCodexMarketplace(filePath, pkg) {
+  const current = (await exists(filePath))
+    ? await readJson(filePath)
+    : { name: "igloo-agent-plugin-local", plugins: [] };
+  current.name ||= "igloo-agent-plugin-local";
+  current.plugins ||= [];
+  const entry = {
+    name: pkg.name,
+    description: pkg.description,
+    source: { source: "local", path: `./${pkg.name}` },
+    policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+    category: pkg.entry?.category || "Agent Skills",
+  };
+  const index = current.plugins.findIndex((item) => item.name === pkg.name);
+  if (index >= 0) current.plugins[index] = { ...current.plugins[index], ...entry };
+  else current.plugins.push(entry);
+  return current;
+}
+
+async function removeCodexMarketplaceEntry(filePath, pluginName) {
+  const current = await readJson(filePath);
+  current.plugins = (current.plugins || []).filter((item) => item.name !== pluginName);
+  return current;
+}

package/src/adapters/common.js

@@ -0,0 +1,28 @@
+import { unsupportedComponents } from "../plugin.js";
+
+export function compatibility(pkg, target) {
+  const unsupported = unsupportedComponents(pkg, target);
+  const warnings = [];
+  if (pkg.skills.length === 0) warnings.push("plugin contains no skills/SKILL.md files");
+  if (unsupported.length > 0) {
+    warnings.push(`${target} install supports the skill subset only; unsupported components: ${unsupported.join(", ")}`);
+  }
+  return {
+    target,
+    status: pkg.skills.length === 0 ? "unsupported" : unsupported.length > 0 ? "partial" : "yes",
+    unsupported,
+    warnings,
+  };
+}
+
+export function defaultInstallPlan(target, pkg, opts, operations, warnings = []) {
+  return {
+    target,
+    plugin: pkg.name,
+    marketplace: pkg.marketplace,
+    scope: opts.scope || "user",
+    operations,
+    warnings,
+    recordPaths: opts.recordPaths,
+  };
+}

package/src/adapters/cursor.js

@@ -0,0 +1,45 @@
+import os from "node:os";
+import path from "node:path";
+import { op } from "../operations.js";
+import { compatibility, defaultInstallPlan } from "./common.js";
+
+export const cursorAdapter = {
+  name: "cursor",
+
+  doctor(pkg) {
+    const report = compatibility(pkg, "cursor");
+    if (report.status === "yes") report.status = "partial";
+    report.warnings.push("cursor does not support Claude marketplace metadata directly; installed skills only");
+    return report;
+  },
+
+  async planInstall(pkg, opts) {
+    const layout = opts.layout || "namespaced";
+    const base =
+      opts.scope === "project"
+        ? path.join(process.cwd(), ".cursor", "skills")
+        : path.join(os.homedir(), ".cursor", "skills");
+    const operations = [];
+    const recordPaths = [];
+    for (const skill of pkg.skills) {
+      const destination =
+        layout === "flat"
+          ? path.join(base, `${pkg.name}-${skill.directoryName}`)
+          : path.join(base, pkg.name, skill.directoryName);
+      operations.push(op("copy", { from: skill.path, to: destination }));
+      recordPaths.push(destination);
+    }
+    const report = this.doctor(pkg);
+    return defaultInstallPlan("cursor", pkg, { ...opts, recordPaths }, operations, report.warnings);
+  },
+
+  async planUninstall(installRef) {
+    return defaultInstallPlan(
+      "cursor",
+      { name: installRef.plugin, marketplace: installRef.marketplace },
+      { scope: installRef.scope },
+      installRef.paths.map((targetPath) => op("remove", { path: targetPath })),
+      [],
+    );
+  },
+};

package/src/adapters/index.js

@@ -0,0 +1,15 @@
+import { claudeAdapter } from "./claude.js";
+import { codexAdapter } from "./codex.js";
+import { cursorAdapter } from "./cursor.js";
+
+export const adapters = {
+  claude: claudeAdapter,
+  codex: codexAdapter,
+  cursor: cursorAdapter,
+};
+
+export function targetsFromOption(target) {
+  if (!target || target === "all") return ["claude", "codex", "cursor"];
+  if (!adapters[target]) throw new Error(`error: unsupported target "${target}"\n\nUse one of: claude, codex, cursor, all`);
+  return [target];
+}

package/src/cli.js

@@ -0,0 +1,251 @@
+import { addMarketplace, listMarketplaces, loadMarketplaces, refreshMarketplaces } from "./marketplace.js";
+import { loadPluginPackage } from "./plugin.js";
+import { adapters, targetsFromOption } from "./adapters/index.js";
+import { executePlan, pathsFromPlan, validatePlan } from "./operations.js";
+import { loadInstalls, saveInstalls } from "./config.js";
+import { formatDoctor, formatPlan, table } from "./format.js";
+
+export async function main(argv) {
+  const parsed = parseArgs(argv);
+  const [command, subcommand] = parsed.positionals;
+
+  if (!command || parsed.flags.help) {
+    printHelp();
+    return;
+  }
+
+  if (command === "marketplace") {
+    await marketplaceCommand(subcommand, parsed);
+    return;
+  }
+  if (command === "search") {
+    await searchCommand(parsed);
+    return;
+  }
+  if (command === "install") {
+    await installCommand(parsed);
+    return;
+  }
+  if (command === "uninstall") {
+    await uninstallCommand(parsed);
+    return;
+  }
+  if (command === "doctor") {
+    await doctorCommand(parsed);
+    return;
+  }
+
+  throw new Error(`error: unknown command "${command}"\n\nRun:\n  igloo-agent-plugin --help`);
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const raw = arg.slice(2);
+    const [key, inlineValue] = raw.split("=", 2);
+    if (key.startsWith("no-")) {
+      flags[key.slice(3)] = false;
+    } else if (inlineValue !== undefined) {
+      flags[key] = inlineValue;
+    } else if (["target", "scope", "layout"].includes(key)) {
+      flags[key] = argv[++index];
+    } else {
+      flags[key] = true;
+    }
+  }
+  return { flags, positionals };
+}
+
+async function marketplaceCommand(subcommand, parsed) {
+  if (subcommand === "add") {
+    const source = parsed.positionals[2];
+    if (!source) throw new Error("error: marketplace add requires a source");
+    const added = await addMarketplace(source);
+    console.log(`Added marketplace ${added.name} (${added.plugins} plugins)\nSource: ${added.source}`);
+    console.log("\nOnly add marketplace sources you trust. Plugin scripts and MCP configs are copied but not executed by this CLI.");
+    return;
+  }
+
+  if (subcommand === "list") {
+    const rows = await listMarketplaces();
+    console.log(table(["NAME", "SOURCE", "STATUS", "PLUGINS"], rows.map((row) => [
+      row.name,
+      row.source,
+      row.status,
+      row.plugins,
+    ])));
+    return;
+  }
+
+  if (subcommand === "refresh") {
+    const name = parsed.positionals[2];
+    const rows = await refreshMarketplaces(name);
+    console.log(table(["NAME", "STATUS", "PLUGINS"], rows.map((row) => [row.name, row.status, row.plugins])));
+    return;
+  }
+
+  throw new Error("error: marketplace command must be one of: add, list, refresh");
+}
+
+async function searchCommand(parsed) {
+  const query = (parsed.positionals[1] || "").toLowerCase();
+  const target = parsed.flags.target;
+  const marketplaces = await loadMarketplaces();
+  const rows = [];
+  for (const marketplace of marketplaces) {
+    for (const entry of marketplace.plugins) {
+      const haystack = `${entry.name} ${entry.description} ${entry.category} ${(entry.tags || []).join(" ")}`.toLowerCase();
+      if (query && !haystack.includes(query)) continue;
+      const compatibility = target ? await compatibilityFor(entry.name, marketplace.name, target) : {};
+      rows.push([
+        entry.name,
+        marketplace.name,
+        compatibility.claude || (target ? "" : "yes"),
+        compatibility.codex || "",
+        compatibility.cursor || "",
+        entry.description,
+      ]);
+    }
+  }
+  console.log(table(["PLUGIN", "MARKETPLACE", "CLAUDE", "CODEX", "CURSOR", "DESCRIPTION"], rows));
+}
+
+async function compatibilityFor(pluginName, marketplaceName, target) {
+  const pkg = await loadPluginPackage(`${pluginName}@${marketplaceName}`);
+  const result = {};
+  for (const targetName of targetsFromOption(target)) {
+    result[targetName] = adapters[targetName].doctor(pkg).status;
+  }
+  return result;
+}
+
+async function installCommand(parsed) {
+  const pluginRef = parsed.positionals[1];
+  if (!pluginRef) throw new Error("error: install requires a plugin name");
+  const targets = targetsFromOption(parsed.flags.target || "codex");
+  const pkg = await loadPluginPackage(pluginRef);
+  const installs = await loadInstalls();
+  const plans = [];
+
+  for (const target of targets) {
+    const adapter = adapters[target];
+    const plan = await adapter.planInstall(pkg, {
+      target,
+      scope: parsed.flags.scope || "user",
+      dryRun: Boolean(parsed.flags["dry-run"]),
+      force: Boolean(parsed.flags.force),
+      symlink: parsed.flags.symlink === true,
+      layout: parsed.flags.layout || "namespaced",
+    });
+    const managedPaths = installs.installed
+      .filter((item) => item.plugin === pkg.name && item.target === target)
+      .flatMap((item) => item.paths || []);
+    await validatePlan(plan, { force: parsed.flags.force, managedPaths });
+    plans.push(plan);
+  }
+
+  if (parsed.flags["dry-run"]) {
+    for (const plan of plans) console.log(formatPlan(plan));
+    return;
+  }
+
+  for (const plan of plans) {
+    await executePlan(plan);
+    installs.installed = installs.installed.filter(
+      (item) => !(item.plugin === pkg.name && item.target === plan.target && item.scope === plan.scope),
+    );
+    installs.installed.push({
+      plugin: pkg.name,
+      marketplace: pkg.marketplace,
+      target: plan.target,
+      scope: plan.scope,
+      installedAt: new Date().toISOString(),
+      sourceHash: pkg.sourceHash,
+      paths: pathsFromPlan(plan),
+    });
+  }
+  await saveInstalls(installs);
+
+  console.log(`Installed ${pkg.name}:`);
+  for (const plan of plans) {
+    const status = plan.warnings.length > 0 ? "partial" : "ok";
+    console.log(`- ${plan.target}: ${status}`);
+  }
+  const warnings = plans.flatMap((plan) => plan.warnings.map((warning) => `${plan.target}: ${warning}`));
+  if (warnings.length > 0) {
+    console.log("\nWarnings:");
+    for (const warning of warnings) console.log(`- ${warning}`);
+  }
+}
+
+async function uninstallCommand(parsed) {
+  const plugin = parsed.positionals[1];
+  if (!plugin) throw new Error("error: uninstall requires a plugin name");
+  const targets = targetsFromOption(parsed.flags.target || "codex");
+  const installs = await loadInstalls();
+  const selected = installs.installed.filter((item) => item.plugin === plugin && targets.includes(item.target));
+  if (selected.length === 0) throw new Error(`error: no managed install found for "${plugin}"`);
+
+  const plans = [];
+  for (const installRef of selected) {
+    const plan = await adapters[installRef.target].planUninstall(installRef, { force: parsed.flags.force });
+    plans.push(plan);
+  }
+  if (parsed.flags["dry-run"]) {
+    for (const plan of plans) console.log(formatPlan(plan));
+    return;
+  }
+  for (const plan of plans) await executePlan(plan);
+  installs.installed = installs.installed.filter((item) => !selected.includes(item));
+  await saveInstalls(installs);
+  console.log(`Uninstalled ${plugin}: ${selected.map((item) => item.target).join(", ")}`);
+}
+
+async function doctorCommand(parsed) {
+  const pluginRef = parsed.positionals[1];
+  const target = parsed.flags.target || "all";
+  const targetNames = targetsFromOption(target);
+
+  if (parsed.flags.all || !pluginRef) {
+    const marketplaces = await loadMarketplaces();
+    const rows = [];
+    for (const marketplace of marketplaces) {
+      for (const entry of marketplace.plugins) {
+        const pkg = await loadPluginPackage(`${entry.name}@${marketplace.name}`);
+        rows.push([
+          entry.name,
+          marketplace.name,
+          ...targetNames.map((targetName) => adapters[targetName].doctor(pkg).status),
+        ]);
+      }
+    }
+    console.log(table(["PLUGIN", "MARKETPLACE", ...targetNames.map((name) => name.toUpperCase())], rows));
+    return;
+  }
+
+  const pkg = await loadPluginPackage(pluginRef);
+  const reports = targetNames.map((targetName) => adapters[targetName].doctor(pkg));
+  console.log(formatDoctor(pkg, reports));
+}
+
+function printHelp() {
+  console.log(`igloo-agent-plugin
+
+Usage:
+  igloo-agent-plugin marketplace add <source>
+  igloo-agent-plugin marketplace list
+  igloo-agent-plugin marketplace refresh [name]
+  igloo-agent-plugin search [query] [--target claude|codex|cursor|all]
+  igloo-agent-plugin install <plugin[@marketplace]> [--target codex|cursor|claude|all] [--scope user|project] [--dry-run] [--force] [--symlink]
+  igloo-agent-plugin uninstall <plugin> [--target codex|cursor|claude|all] [--dry-run]
+  igloo-agent-plugin doctor [plugin] [--target codex|cursor|claude|all] [--all]
+
+State:
+  ${process.env.IGLOO_AGENT_PLUGIN_HOME || "~/.igloo-agent-plugin"}`);
+}

package/src/config.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { ensureDir, readJson, stateRoot, writeJson } from "./utils.js";
+
+export function configPath() {
+  return path.join(stateRoot(), "config.json");
+}
+
+export function installsPath() {
+  return path.join(stateRoot(), "installs.json");
+}
+
+export async function ensureState() {
+  await ensureDir(stateRoot());
+  await ensureDir(path.join(stateRoot(), "marketplaces"));
+  await ensureDir(path.join(stateRoot(), "cache"));
+  await ensureDir(path.join(stateRoot(), "logs"));
+}
+
+export async function loadConfig() {
+  await ensureState();
+  const config = await readJson(configPath(), { version: 1, marketplaces: [] });
+  config.marketplaces ||= [];
+  return config;
+}
+
+export async function saveConfig(config) {
+  await writeJson(configPath(), { version: 1, marketplaces: config.marketplaces || [] });
+}
+
+export async function loadInstalls() {
+  await ensureState();
+  const installs = await readJson(installsPath(), { version: 1, installed: [] });
+  installs.installed ||= [];
+  return installs;
+}
+
+export async function saveInstalls(installs) {
+  await writeJson(installsPath(), { version: 1, installed: installs.installed || [] });
+}

package/src/format.js

@@ -0,0 +1,46 @@
+import { operationTarget } from "./operations.js";
+
+export function table(headers, rows) {
+  const allRows = [headers, ...rows];
+  const widths = headers.map((_, index) =>
+    Math.max(...allRows.map((row) => String(row[index] ?? "").length)),
+  );
+  return allRows
+    .map((row) =>
+      row.map((cell, index) => String(cell ?? "").padEnd(widths[index])).join("  ").trimEnd(),
+    )
+    .join("\n");
+}
+
+export function formatPlan(plan) {
+  const lines = [`${plan.target}: ${plan.operations.length === 0 ? "no file operations" : "planned operations"}`];
+  for (const operation of plan.operations) {
+    if (operation.kind === "copy") lines.push(`- copy ${operation.from} -> ${operation.to}`);
+    else if (operation.kind === "write_json") lines.push(`- write_json ${operation.to}`);
+    else if (operation.kind === "mkdir") lines.push(`- mkdir ${operation.path}`);
+    else if (operation.kind === "symlink") lines.push(`- symlink ${operation.from} -> ${operation.to}`);
+    else if (operation.kind === "remove") lines.push(`- remove ${operation.path}`);
+    else lines.push(`- ${operation.kind} ${operationTarget(operation)}`);
+  }
+  if (plan.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of plan.warnings) lines.push(`- ${warning}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatDoctor(pkg, reports) {
+  const lines = [
+    `Plugin: ${pkg.name}`,
+    `Source: ${pkg.root}`,
+    `Skills: ${pkg.skills.length}`,
+    "",
+    table(["TARGET", "STATUS", "WARNINGS"], reports.map((report) => [
+      report.target,
+      report.status,
+      report.warnings.length ? report.warnings.join("; ") : "-",
+    ])),
+  ];
+  return lines.join("\n");
+}

package/src/marketplace.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import {
+  basenameFromSource,
+  ensureDir,
+  exists,
+  expandHome,
+  readJson,
+  sanitizeName,
+  stateRoot,
+} from "./utils.js";
+import { loadConfig, saveConfig } from "./config.js";
+
+const execFileAsync = promisify(execFile);
+
+export function marketplaceJsonPath(root) {
+  return path.join(root, ".claude-plugin", "marketplace.json");
+}
+
+export async function readMarketplace(root, source = {}) {
+  const filePath = marketplaceJsonPath(root);
+  if (!(await exists(filePath))) {
+    throw new Error(`error: marketplace file not found\n\nExpected:\n  ${filePath}`);
+  }
+  const raw = await readJson(filePath);
+  if (!Array.isArray(raw.plugins)) {
+    throw new Error(`error: marketplace JSON must contain a plugins array\n\nFile:\n  ${filePath}`);
+  }
+  return {
+    name: raw.name || sanitizeName(path.basename(root)) || "local-marketplace",
+    description: raw.description || "",
+    root,
+    source,
+    plugins: raw.plugins.map((plugin) => ({
+      name: plugin.name,
+      description: plugin.description || "",
+      version: plugin.version || "",
+      category: plugin.category || "",
+      tags: plugin.tags || [],
+      homepage: plugin.homepage || "",
+      source: plugin.source,
+      marketplace: raw.name || sanitizeName(path.basename(root)) || "local-marketplace",
+    })),
+  };
+}
+
+export function sourceKind(source) {
+  if (/^(git@|https?:\/\/|ssh:\/\/)/.test(source)) return "git";
+  return "local";
+}
+
+export function normalizeLocalRoot(source) {
+  const absolute = path.resolve(expandHome(source));
+  if (path.basename(absolute) === "marketplace.json") {
+    const parent = path.dirname(absolute);
+    return path.basename(parent) === ".claude-plugin" ? path.dirname(parent) : parent;
+  }
+  return absolute;
+}
+
+export async function addMarketplace(sourceInput) {
+  const source = expandHome(sourceInput);
+  const type = sourceKind(source);
+  let root;
+  let ref = "main";
+
+  if (type === "git") {
+    const initialName = basenameFromSource(source) || "marketplace";
+    root = path.join(stateRoot(), "marketplaces", initialName);
+    await ensureDir(path.dirname(root));
+    if (!(await exists(root))) {
+      await execFileAsync("git", ["clone", source, root]);
+    }
+  } else {
+    root = normalizeLocalRoot(source);
+  }
+
+  const marketplace = await readMarketplace(root, { sourceType: type, source, ref, root });
+  const config = await loadConfig();
+  const name = marketplace.name;
+  const entry = { name, sourceType: type, source, ref, root };
+  const index = config.marketplaces.findIndex((item) => item.name === name);
+  if (index >= 0) config.marketplaces[index] = entry;
+  else config.marketplaces.push(entry);
+  await saveConfig(config);
+  return { ...entry, plugins: marketplace.plugins.length };
+}
+
+export async function listMarketplaces() {
+  const config = await loadConfig();
+  const rows = [];
+  for (const entry of config.marketplaces) {
+    try {
+      const marketplace = await readMarketplace(entry.root, entry);
+      rows.push({ ...entry, status: "ok", plugins: marketplace.plugins.length });
+    } catch (error) {
+      rows.push({ ...entry, status: "error", error: error.message, plugins: 0 });
+    }
+  }
+  return rows;
+}
+
+export async function loadMarketplaces() {
+  const config = await loadConfig();
+  const marketplaces = [];
+  for (const entry of config.marketplaces) {
+    marketplaces.push(await readMarketplace(entry.root, entry));
+  }
+  return marketplaces;
+}
+
+export async function refreshMarketplaces(name) {
+  const config = await loadConfig();
+  const selected = name ? config.marketplaces.filter((item) => item.name === name) : config.marketplaces;
+  if (name && selected.length === 0) {
+    throw new Error(`error: marketplace "${name}" not found`);
+  }
+
+  const results = [];
+  for (const entry of selected) {
+    if (entry.sourceType === "git") {
+      await execFileAsync("git", ["-C", entry.root, "pull", "--ff-only"]);
+    }
+    const marketplace = await readMarketplace(entry.root, entry);
+    results.push({ name: marketplace.name, plugins: marketplace.plugins.length, status: "ok" });
+  }
+  return results;
+}

package/src/operations.js

@@ -0,0 +1,51 @@
+import path from "node:path";
+import { copyPath, ensureDir, exists, removePath, symlinkPath, writeJson } from "./utils.js";
+
+export function op(kind, fields) {
+  return { kind, ...fields };
+}
+
+export async function validatePlan(plan, opts = {}) {
+  const force = Boolean(opts.force);
+  const managedPaths = new Set(opts.managedPaths || []);
+  for (const operation of plan.operations) {
+    const target = operation.to || operation.path;
+    if (!target) continue;
+    if (operation.allowExisting) continue;
+    if (["copy", "write_json", "symlink", "mkdir"].includes(operation.kind) && (await exists(target))) {
+      if (!force && !isManagedTarget(target, managedPaths)) {
+        throw new Error(`error: target path already exists and is not managed by igloo-agent-plugin\n\nPath:\n  ${target}\n\nUse --force to overwrite, choose another scope/layout, or uninstall the existing copy first.`);
+      }
+    }
+  }
+}
+
+function isManagedTarget(target, managedPaths) {
+  const resolved = path.resolve(target);
+  for (const managedPath of managedPaths) {
+    const managed = path.resolve(managedPath);
+    const relative = path.relative(managed, resolved);
+    if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) return true;
+  }
+  return false;
+}
+
+export async function executePlan(plan) {
+  for (const operation of plan.operations) {
+    if (operation.kind === "mkdir") await ensureDir(operation.path);
+    else if (operation.kind === "copy") await copyPath(operation.from, operation.to);
+    else if (operation.kind === "write_json") await writeJson(operation.to, operation.value);
+    else if (operation.kind === "symlink") await symlinkPath(operation.from, operation.to);
+    else if (operation.kind === "remove") await removePath(operation.path);
+    else throw new Error(`error: unsupported operation kind "${operation.kind}"`);
+  }
+}
+
+export function operationTarget(operation) {
+  return operation.to || operation.path || "";
+}
+
+export function pathsFromPlan(plan) {
+  if (plan.recordPaths) return plan.recordPaths.map((item) => path.resolve(item));
+  return plan.operations.map(operationTarget).filter(Boolean).map((item) => path.resolve(item));
+}

package/src/plugin.js

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import {
+  basenameFromSource,
+  ensureDir,
+  exists,
+  hashPath,
+  listDirNames,
+  parseFrontmatter,
+  readJson,
+  sanitizeName,
+  stateRoot,
+} from "./utils.js";
+import { loadMarketplaces } from "./marketplace.js";
+
+const execFileAsync = promisify(execFile);
+
+export async function findPlugin(ref) {
+  const [pluginName, marketplaceName] = ref.split("@");
+  const marketplaces = await loadMarketplaces();
+  const matches = [];
+
+  for (const marketplace of marketplaces) {
+    if (marketplaceName && marketplace.name !== marketplaceName) continue;
+    for (const entry of marketplace.plugins) {
+      if (entry.name === pluginName) matches.push({ marketplace, entry });
+    }
+  }
+
+  if (matches.length === 0) {
+    const names = marketplaces.map((item) => `- ${item.name}`).join("\n") || "- none";
+    throw new Error(`error: plugin "${pluginName}" not found\n\nChecked marketplaces:\n${names}\n\nTry:\n  igloo-agent-plugin marketplace refresh\n  igloo-agent-plugin search ${pluginName}`);
+  }
+  if (matches.length > 1) {
+    const found = matches.map((match) => `- ${match.entry.name}@${match.marketplace.name}`).join("\n");
+    throw new Error(`error: plugin "${pluginName}" is ambiguous\n\nMatches:\n${found}\n\nUse:\n  igloo-agent-plugin install ${pluginName}@<marketplace>`);
+  }
+  return matches[0];
+}
+
+export async function resolvePluginSource(marketplace, entry) {
+  const source = entry.source;
+  if (typeof source === "string") {
+    if (/^(git@|https?:\/\/|ssh:\/\/)/.test(source)) return clonePluginSource(source);
+    return path.resolve(marketplace.root, source);
+  }
+
+  if (source && typeof source === "object") {
+    const value = source.path || source.url || source.source;
+    if (!value) throw new Error(`error: plugin "${entry.name}" has an unsupported source object`);
+    if (source.source === "url" || /^(git@|https?:\/\/|ssh:\/\/)/.test(value)) return clonePluginSource(value);
+    return path.resolve(marketplace.root, value);
+  }
+
+  throw new Error(`error: plugin "${entry.name}" has no installable source`);
+}
+
+async function clonePluginSource(source) {
+  const name = basenameFromSource(source) || "plugin";
+  const root = path.join(stateRoot(), "cache", "plugins", name);
+  await ensureDir(path.dirname(root));
+  if (!(await exists(root))) await execFileAsync("git", ["clone", source, root]);
+  return root;
+}
+
+export async function loadPluginPackage(ref) {
+  const { marketplace, entry } = await findPlugin(ref);
+  const root = await resolvePluginSource(marketplace, entry);
+  if (!(await exists(root))) {
+    throw new Error(`error: plugin source does not exist\n\nPlugin:\n  ${entry.name}\nPath:\n  ${root}`);
+  }
+
+  const manifestPath = path.join(root, ".claude-plugin", "plugin.json");
+  const manifest = (await exists(manifestPath)) ? await readJson(manifestPath) : {};
+  const scanned = await scanPlugin(root);
+  return {
+    name: manifest.name || entry.name,
+    description: manifest.description || entry.description || "",
+    version: manifest.version || entry.version || "",
+    author: manifest.author || undefined,
+    root,
+    marketplace: marketplace.name,
+    marketplaceRoot: marketplace.root,
+    entry,
+    skills: scanned.skills,
+    components: scanned.components,
+    sourceHash: await hashPath(root),
+  };
+}
+
+export async function scanPlugin(root) {
+  const skills = [];
+  const skillRoot = path.join(root, "skills");
+  const skillNames = await listDirNames(skillRoot);
+  for (const name of skillNames) {
+    const skillDir = path.join(skillRoot, name);
+    const skillMd = path.join(skillDir, "SKILL.md");
+    if (!(await exists(skillMd))) continue;
+    const content = await readFile(skillMd, "utf8");
+    const frontmatter = parseFrontmatter(content);
+    const resources = (await listDirNames(skillDir))
+      .filter((item) => item !== "SKILL.md")
+      .map((item) => path.join(skillDir, item));
+    skills.push({
+      name: sanitizeName(frontmatter.name || name) || name,
+      directoryName: name,
+      description: frontmatter.description || "",
+      path: skillDir,
+      skillFile: skillMd,
+      resources,
+    });
+  }
+
+  const rootSkill = path.join(root, "SKILL.md");
+  if (await exists(rootSkill)) {
+    const content = await readFile(rootSkill, "utf8");
+    const frontmatter = parseFrontmatter(content);
+    skills.push({
+      name: sanitizeName(frontmatter.name || path.basename(root)) || path.basename(root),
+      directoryName: sanitizeName(frontmatter.name || path.basename(root)) || path.basename(root),
+      description: frontmatter.description || "",
+      path: root,
+      skillFile: rootSkill,
+      resources: [],
+    });
+  }
+
+  const components = {
+    hasSkills: skills.length > 0,
+    hasHooks: await exists(path.join(root, "hooks", "hooks.json")),
+    hasAgents: await exists(path.join(root, "agents")),
+    hasMCP: await exists(path.join(root, ".mcp.json")),
+    hasLSP: await exists(path.join(root, ".lsp.json")),
+    hasCommands: await exists(path.join(root, "commands")),
+    hasMonitors: await exists(path.join(root, "monitors", "monitors.json")),
+    hasBin: await exists(path.join(root, "bin")),
+    hasSettings: await exists(path.join(root, "settings.json")),
+  };
+
+  return { skills, components };
+}
+
+export function unsupportedComponents(pkg, target) {
+  const unsupported = [];
+  const add = (flag, label) => {
+    if (pkg.components[flag]) unsupported.push(label);
+  };
+
+  if (target === "claude") return unsupported;
+  add("hasHooks", "hooks/hooks.json");
+  add("hasAgents", "agents/");
+  add("hasMCP", ".mcp.json");
+  add("hasLSP", ".lsp.json");
+  add("hasCommands", "commands/");
+  add("hasMonitors", "monitors/monitors.json");
+  add("hasBin", "bin/");
+  add("hasSettings", "settings.json");
+  return unsupported;
+}

package/src/utils.js

@@ -0,0 +1,127 @@
+import { createHash } from "node:crypto";
+import { access, cp, mkdir, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function stateRoot() {
+  return process.env.IGLOO_AGENT_PLUGIN_HOME || path.join(os.homedir(), ".igloo-agent-plugin");
+}
+
+export function expandHome(input) {
+  if (!input) return input;
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/")) return path.join(os.homedir(), input.slice(2));
+  return input;
+}
+
+export async function exists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDir(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    if (fallback !== undefined && error.code === "ENOENT") return fallback;
+    throw new Error(`error: failed to read JSON ${filePath}\n\n${error.message}`);
+  }
+}
+
+export async function writeJson(filePath, value) {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function sanitizeName(name) {
+  return String(name || "")
+    .trim()
+    .toLowerCase()
+    .replace(/\.git$/, "")
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export async function listDirNames(dirPath) {
+  try {
+    return await readdir(dirPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export async function copyPath(from, to) {
+  await ensureDir(path.dirname(to));
+  await cp(from, to, { recursive: true, force: true, verbatimSymlinks: false });
+}
+
+export async function removePath(target) {
+  await rm(target, { recursive: true, force: true });
+}
+
+export async function symlinkPath(from, to) {
+  await ensureDir(path.dirname(to));
+  await symlink(from, to, "dir");
+}
+
+export async function hashFile(filePath) {
+  const content = await readFile(filePath);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export async function hashPath(root) {
+  const hash = createHash("sha256");
+
+  async function visit(current) {
+    const info = await stat(current);
+    const relative = path.relative(root, current);
+    hash.update(relative);
+    if (info.isDirectory()) {
+      const names = await readdir(current);
+      names.sort();
+      for (const name of names) await visit(path.join(current, name));
+      return;
+    }
+    if (info.isFile()) hash.update(await readFile(current));
+  }
+
+  await visit(root);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+export function parseFrontmatter(markdown) {
+  if (!markdown.startsWith("---\n")) return {};
+  const end = markdown.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const block = markdown.slice(4, end);
+  const result = {};
+  for (const line of block.split(/\r?\n/)) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (match) result[match[1]] = match[2].replace(/^["']|["']$/g, "");
+  }
+  return result;
+}
+
+export function basenameFromSource(source) {
+  const cleaned = String(source).replace(/[#?].*$/, "").replace(/\/$/, "");
+  return sanitizeName(path.basename(cleaned));
+}
+
+export function uniqueByName(items) {
+  const seen = new Set();
+  return items.filter((item) => {
+    if (seen.has(item.name)) return false;
+    seen.add(item.name);
+    return true;
+  });
+}