@rbbtsn0w/adg 0.1.0-alpha.1 → 0.1.0-beta.1

package/dist/src/adapters/anthropic.js

@@ -0,0 +1,54 @@
+import { join } from "node:path";
+import { resolveSkills } from "../skills.js";
+import { isExposed } from "../components.js";
+/**
+ * Generate a Claude (.claude-plugin/plugin.json) manifest from an ADG manifest.
+ *
+ * Maps the universal fields onto Claude's plugin shape. When `strict` is false,
+ * skills are listed explicitly so a skill-bundle marketplace entry can be built.
+ * An optional `selection` narrows what is exposed (partial install): categories
+ * outside it are dropped and skills are pinned to an explicit subset list.
+ */
+export function toAnthropicManifest(pluginDir, manifest, selection) {
+    const out = {
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+    };
+    if (manifest.author)
+        out.author = manifest.author;
+    if (manifest.homepage)
+        out.homepage = manifest.homepage;
+    if (manifest.license)
+        out.license = manifest.license;
+    if (manifest.category)
+        out.category = manifest.category;
+    if (manifest.commands && isExposed(selection, "commands"))
+        out.commands = manifest.commands;
+    if (manifest.agents && isExposed(selection, "agents"))
+        out.agents = manifest.agents;
+    if (manifest.hooks && isExposed(selection, "hooks"))
+        out.hooks = manifest.hooks;
+    if (manifest.mcp && isExposed(selection, "mcp"))
+        out.mcp = manifest.mcp;
+    if (selection) {
+        // Partial install: always an explicit (possibly empty) skill list.
+        out.strict = false;
+        const names = isExposed(selection, "skills")
+            ? selection.skills ?? resolveSkills(pluginDir, manifest)
+            : [];
+        out.skills = names.map((name) => `./skills/${name}`);
+    }
+    else {
+        const strict = manifest.strict !== false;
+        if (strict && manifest.skills !== undefined) {
+            out.skills = manifest.skills;
+        }
+        else {
+            // skill-bundle form: explicit list, strict:false
+            out.strict = false;
+            out.skills = resolveSkills(pluginDir, manifest).map((name) => `./skills/${name}`);
+        }
+    }
+    return { defaultPath: join(".claude-plugin", "plugin.json"), manifest: out };
+}

package/dist/src/adapters/index.js

@@ -0,0 +1,10 @@
+import { toAnthropicManifest } from "./anthropic.js";
+import { toCodexManifest } from "./openai.js";
+export const ADAPTERS = {
+    claude: toAnthropicManifest,
+    anthropic: toAnthropicManifest,
+    codex: toCodexManifest,
+    openai: toCodexManifest,
+};
+export const ADAPTER_TARGETS = ["claude", "codex"];
+export { toAnthropicManifest, toCodexManifest };

package/dist/src/adapters/openai.js

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { resolveSkills } from "../skills.js";
+import { isExposed } from "../components.js";
+/**
+ * Generate a Codex (.codex-plugin/plugin.json) manifest from an ADG manifest.
+ *
+ * Codex's minimal manifest requires name, version, description and skills. The
+ * skills field is emitted as an explicit array of skill identifiers. An optional
+ * `selection` narrows the exposed skills (Codex only consumes skills).
+ */
+export function toCodexManifest(pluginDir, manifest, selection) {
+    const skills = !selection
+        ? resolveSkills(pluginDir, manifest)
+        : isExposed(selection, "skills")
+            ? selection.skills ?? resolveSkills(pluginDir, manifest)
+            : [];
+    const out = {
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+        skills,
+    };
+    if (manifest.author)
+        out.author = manifest.author;
+    if (manifest.homepage)
+        out.homepage = manifest.homepage;
+    if (manifest.license)
+        out.license = manifest.license;
+    return { defaultPath: join(".codex-plugin", "plugin.json"), manifest: out };
+}

package/dist/src/adapters/reverse.js

@@ -0,0 +1,53 @@
+import { ADG_SCHEMA_VERSION } from "../types.js";
+import { validateManifest } from "../manifest.js";
+/**
+ * Reverse-adapt a runtime-native manifest (.claude-plugin/plugin.json or
+ * .codex-plugin/plugin.json) into a canonical ADG manifest. This is the inverse
+ * of the forward adapters and is used when importing existing plugins.
+ *
+ * Missing `version` falls back to 0.0.0 (callers may override with a git SHA);
+ * skills normalize to the manifest's array/string or the default ./skills/.
+ */
+export function fromNativeManifest(raw, _kind) {
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("native manifest must be a JSON object");
+    }
+    const n = raw;
+    if (typeof n.name !== "string")
+        throw new Error("native manifest missing string `name`");
+    const manifest = {
+        schemaVersion: ADG_SCHEMA_VERSION,
+        name: n.name,
+        version: typeof n.version === "string" ? n.version : "0.0.0",
+        description: typeof n.description === "string" && n.description ? n.description : `${n.name} plugin.`,
+    };
+    const out = manifest;
+    copyIfString(n, out, "license");
+    copyIfString(n, out, "category");
+    copyIfString(n, out, "homepage");
+    copyIfString(n, out, "commands");
+    copyIfString(n, out, "agents");
+    copyIfString(n, out, "hooks");
+    copyIfString(n, out, "mcp");
+    if (typeof n.author === "object" && n.author !== null) {
+        manifest.author = n.author;
+    }
+    else if (typeof n.author === "string") {
+        manifest.author = { name: n.author };
+    }
+    if (typeof n.skills === "string" || isStringArray(n.skills)) {
+        manifest.skills = n.skills;
+    }
+    else {
+        manifest.skills = "./skills/";
+    }
+    manifest.strict = typeof n.strict === "boolean" ? n.strict : true;
+    return validateManifest(manifest);
+}
+function copyIfString(src, dst, key) {
+    if (typeof src[key] === "string")
+        dst[key] = src[key];
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}

package/dist/src/agents/claude.js

@@ -0,0 +1,118 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+import { writeJson } from "../fsutil.js";
+import { readManifest } from "../manifest.js";
+import { installedPluginDir, lockPath } from "../paths.js";
+import { readLock } from "../lock.js";
+/**
+ * Claude Code agent.
+ *
+ * Claude consumes plugins through its own marketplace system, so we emit a
+ * Claude-shaped catalog at `<pluginsDir>/.claude-plugin/marketplace.json` and
+ * drive everything through the `claude plugin` CLI (which owns ~/.claude across
+ * versions) rather than hand-editing Claude's internal state.
+ */
+const MARKETPLACE = "adg";
+function toPosix(p) {
+    return p.split("\\").join("/");
+}
+function claudeHome(env) {
+    return env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
+}
+function available() {
+    return spawnSync("claude", ["plugin", "--help"], { stdio: "ignore" }).status === 0;
+}
+function run(args) {
+    const r = spawnSync("claude", args, { encoding: "utf8" });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+}
+/**
+ * Write a Claude marketplace catalog listing every installed plugin, each
+ * `source` pointing at its on-disk directory (relative to the catalog).
+ */
+export function writeClaudeCatalog(pluginsDir, name = MARKETPLACE) {
+    const lock = readLock(lockPath(pluginsDir));
+    const plugins = [];
+    for (const [pname, entry] of Object.entries(lock.plugins)) {
+        const dir = installedPluginDir(pluginsDir, pname, entry.origin);
+        let description = "";
+        let author;
+        let category;
+        try {
+            const m = readManifest(dir);
+            description = m.description;
+            author = m.author;
+            category = m.category;
+        }
+        catch {
+            // no manifest on disk — list it minimally so the catalog stays complete
+        }
+        const rel = toPosix(relative(pluginsDir, dir)) || pname;
+        plugins.push({
+            name: pname,
+            description,
+            source: `./${rel}`,
+            ...(author ? { author } : {}),
+            ...(category ? { category } : {}),
+        });
+    }
+    const catalog = {
+        $schema: "https://anthropic.com/claude-code/marketplace.schema.json",
+        name,
+        description: "ADG-managed plugins",
+        owner: { name: "ADG" },
+        plugins,
+    };
+    const file = join(pluginsDir, ".claude-plugin", "marketplace.json");
+    writeJson(file, catalog);
+    return { file, name };
+}
+/** Register the ADG store as a Claude marketplace (add, or update if present). */
+function syncMarketplace(pluginsDir) {
+    const list = run(["plugin", "marketplace", "list"]);
+    if (list.ok && list.out.includes(MARKETPLACE))
+        run(["plugin", "marketplace", "update", MARKETPLACE]);
+    else
+        run(["plugin", "marketplace", "add", pluginsDir]);
+}
+export const claudeAgent = {
+    id: "claude",
+    displayName: "Claude Code",
+    adaptTarget: "claude",
+    detect: (env = process.env) => existsSync(claudeHome(env)),
+    available,
+    activate(ctx) {
+        if (!available())
+            return { agent: "claude", affected: [], skipped: true };
+        writeClaudeCatalog(ctx.pluginsDir);
+        syncMarketplace(ctx.pluginsDir);
+        const affected = [];
+        for (const p of ctx.plugins) {
+            if (run(["plugin", "install", `${p}@${MARKETPLACE}`, "--scope", ctx.scope]).ok)
+                affected.push(p);
+        }
+        return { agent: "claude", affected, skipped: false };
+    },
+    deactivate(ctx) {
+        if (!available())
+            return { agent: "claude", affected: [], skipped: true };
+        const affected = [];
+        for (const p of ctx.plugins) {
+            if (run(["plugin", "uninstall", p, "--scope", ctx.scope]).ok)
+                affected.push(p);
+        }
+        return { agent: "claude", affected, skipped: false };
+    },
+    refresh(ctx) {
+        if (!available())
+            return { agent: "claude", affected: [], skipped: true };
+        // Claude caches a copy on install and won't re-pull from a local marketplace,
+        // so uninstall (keeping data) then re-install to force a fresh copy.
+        for (const p of ctx.plugins)
+            run(["plugin", "uninstall", p, "--scope", ctx.scope, "--keep-data"]);
+        const act = claudeAgent.activate(ctx);
+        return { agent: "claude", affected: act.affected, skipped: act.skipped };
+    },
+};

package/dist/src/agents/codex.js

@@ -0,0 +1,61 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { marketplacePath } from "../paths.js";
+import { readMarketplace } from "../marketplace.js";
+/**
+ * Codex agent.
+ *
+ * Codex natively discovers the `.agents/plugins/marketplace.json` ADG writes, so
+ * plugins show up as *available* — but aren't usable until installed with
+ * `codex plugin add`. We drive that via the `codex` CLI (which owns ~/.codex).
+ */
+function codexHome(env) {
+    return env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+}
+function available() {
+    return spawnSync("codex", ["plugin", "--help"], { stdio: "ignore" }).status === 0;
+}
+function run(args) {
+    const r = spawnSync("codex", args, { encoding: "utf8" });
+    return { ok: r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}` };
+}
+/** The marketplace name Codex sees, read from the generated marketplace.json. */
+function marketplaceName(pluginsDir) {
+    return readMarketplace(marketplacePath(pluginsDir), "").name;
+}
+export const codexAgent = {
+    id: "codex",
+    displayName: "Codex",
+    adaptTarget: "codex",
+    detect: (env = process.env) => existsSync(codexHome(env)) || existsSync("/etc/codex"),
+    available,
+    activate(ctx) {
+        const mp = marketplaceName(ctx.pluginsDir);
+        if (!available())
+            return { agent: "codex", affected: [], skipped: true };
+        const affected = [];
+        for (const p of ctx.plugins) {
+            if (run(["plugin", "add", `${p}@${mp}`]).ok)
+                affected.push(p);
+        }
+        return { agent: "codex", affected, skipped: false };
+    },
+    deactivate(ctx) {
+        const mp = marketplaceName(ctx.pluginsDir);
+        if (!available())
+            return { agent: "codex", affected: [], skipped: true };
+        const affected = [];
+        for (const p of ctx.plugins) {
+            if (run(["plugin", "remove", `${p}@${mp}`]).ok)
+                affected.push(p);
+        }
+        return { agent: "codex", affected, skipped: false };
+    },
+    // `codex plugin add` is idempotent and re-copies into the cache, so re-adding
+    // is the refresh.
+    refresh(ctx) {
+        return codexAgent.activate(ctx);
+    },
+};

package/{src/agents/index.ts → dist/src/agents/index.js}

@@ -1,12 +1,10 @@
-import { registerAgent } from "./registry.ts";
-import { claudeAgent } from "./claude.ts";
-import { codexAgent } from "./codex.ts";
-
+import { registerAgent } from "./registry.js";
+import { claudeAgent } from "./claude.js";
+import { codexAgent } from "./codex.js";
 // Built-in agents register on import. Third-party agents can `registerAgent()`
 // their own implementation (stage 2: discover from config without core edits).
 registerAgent(claudeAgent);
 registerAgent(codexAgent);
-
-export * from "./types.ts";
-export { registerAgent, getAgent, allAgents, detectedAgents, resolveAgents } from "./registry.ts";
-export { writeClaudeCatalog } from "./claude.ts";
+export * from "./types.js";
+export { registerAgent, getAgent, allAgents, detectedAgents, resolveAgents } from "./registry.js";
+export { writeClaudeCatalog } from "./claude.js";

package/dist/src/agents/registry.js

@@ -0,0 +1,24 @@
+/**
+ * The agent registry — the "factory": construction/lookup only. Orchestration
+ * (looping, dependency order, store writes) stays in the command layer.
+ */
+const REGISTRY = new Map();
+export function registerAgent(agent) {
+    REGISTRY.set(agent.id, agent);
+}
+export function getAgent(id) {
+    return REGISTRY.get(id);
+}
+export function allAgents() {
+    return [...REGISTRY.values()];
+}
+/** Agents that appear installed on this machine. */
+export function detectedAgents(env) {
+    return allAgents().filter((a) => a.detect(env));
+}
+/** Agents matching the given ids, or every registered agent when none are given. */
+export function resolveAgents(targets) {
+    if (!targets)
+        return allAgents();
+    return targets.map((t) => getAgent(t)).filter((a) => a !== undefined);
+}

package/dist/src/agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/commands/adapt.js

@@ -0,0 +1,26 @@
+import { join } from "node:path";
+import { ADAPTERS } from "../adapters/index.js";
+import { readManifest } from "../manifest.js";
+import { writeJson } from "../fsutil.js";
+/**
+ * Generate runtime-specific manifests for the given targets from a plugin's
+ * .agents/.plugin.json. The output path honors the manifest's `adapters`
+ * mapping when present, otherwise falls back to the adapter's default path.
+ * An optional `selection` narrows what the generated manifests expose.
+ */
+export function adaptPlugin(pluginDir, targets, selection) {
+    const manifest = readManifest(pluginDir);
+    const results = [];
+    for (const target of targets) {
+        const adapter = ADAPTERS[target];
+        if (!adapter)
+            throw new Error(`unknown adapter target: ${target}`);
+        const { defaultPath, manifest: out } = adapter(pluginDir, manifest, selection);
+        // Output paths are ADG-internal conventions, not producer-configurable: each
+        // runtime mandates its own (.claude-plugin/ , .codex-plugin/).
+        const file = join(pluginDir, defaultPath);
+        writeJson(file, out);
+        results.push({ target, file });
+    }
+    return results;
+}

package/dist/src/commands/import.js

@@ -0,0 +1,51 @@
+import { cpSync, existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { ADG_MANIFEST_PATH } from "../manifest.js";
+import { writeJson, writeText } from "../fsutil.js";
+import { installPlugin } from "./install.js";
+import { ADG_SCHEMA_VERSION } from "../types.js";
+/**
+ * Wrap a flat directory of `<name>/SKILL.md` skills into a single ADG plugin and
+ * install it. Skill folders are copied verbatim under the new plugin's skills/.
+ */
+export function importSkills(opts) {
+    const src = resolve(opts.skillsDir);
+    const names = readdirSync(src, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(src, e.name, "SKILL.md")))
+        .map((e) => e.name)
+        .filter((name) => !opts.prefix || name.startsWith(opts.prefix))
+        .sort();
+    if (names.length === 0) {
+        throw new Error(`no SKILL.md skills found in ${src}${opts.prefix ? ` with prefix "${opts.prefix}"` : ""}`);
+    }
+    const staging = mkdtempSync(join(tmpdir(), "adg-skills-"));
+    try {
+        const manifest = {
+            schemaVersion: ADG_SCHEMA_VERSION,
+            name: opts.as,
+            version: opts.version ?? "0.1.0",
+            description: opts.description ?? `Imported skills bundle (${names.length}).`,
+            skills: "./skills/",
+            strict: false,
+        };
+        writeJson(join(staging, ADG_MANIFEST_PATH), manifest);
+        for (const name of names) {
+            copySkill(join(src, name), join(staging, "skills", name));
+        }
+        writeText(join(staging, "README.md"), `# ${opts.as}\n\n${manifest.description}\n`);
+        return installPlugin({
+            source: staging,
+            pluginsDir: opts.pluginsDir,
+            origin: { type: "local", path: `./${opts.as}` },
+            marketplaceName: opts.marketplaceName,
+            now: opts.now,
+        });
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+function copySkill(from, to) {
+    cpSync(from, to, { recursive: true });
+}

package/dist/src/commands/init.js

@@ -0,0 +1,104 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { ADG_MANIFEST_PATH, ADG_MARKETPLACE_PATH } from "../manifest.js";
+import { writeJson, writeText } from "../fsutil.js";
+import { ADG_SCHEMA_VERSION } from "../types.js";
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Dispatch on the authoring scenario: a plugin (`.agents/.plugin.json`), a
+ * marketplace catalog (`.agents/.marketplace.json`), or `all` — a catalog root
+ * with one starter member plugin in a subdirectory.
+ */
+export function initScaffold(opts) {
+    switch (opts.type ?? "plugin") {
+        case "plugin":
+            return initPlugin(opts);
+        case "marketplace":
+            return initMarketplace(opts);
+        case "all":
+            return initAll(opts);
+    }
+}
+/**
+ * Scaffold a new ADG plugin directory: .agents/.plugin.json, a starter
+ * skill (SKILL.md) and README.md.
+ */
+export function initPlugin(opts) {
+    if (!NAME_RE.test(opts.name)) {
+        throw new Error(`plugin name must be kebab-case, got "${opts.name}"`);
+    }
+    const pluginDir = join(opts.dir, opts.name);
+    const manifestFile = join(pluginDir, ADG_MANIFEST_PATH);
+    if (existsSync(manifestFile)) {
+        throw new Error(`${manifestFile} already exists; refusing to overwrite`);
+    }
+    const skillName = opts.skill ?? "getting-started";
+    const manifest = {
+        schemaVersion: ADG_SCHEMA_VERSION,
+        name: opts.name,
+        version: "0.1.0",
+        description: opts.description ?? `${opts.name} plugin.`,
+        author: { name: opts.author ?? "Agent Directory Group" },
+        license: "Apache-2.0",
+        skills: "./skills/",
+        strict: true,
+    };
+    const created = [];
+    writeJson(manifestFile, manifest);
+    created.push(manifestFile);
+    const skillFile = join(pluginDir, "skills", skillName, "SKILL.md");
+    writeText(skillFile, `---\nname: ${skillName}\ndescription: Describe when this skill should trigger.\n---\n\n# ${skillName}\n\nDocument the skill's behavior here.\n`);
+    created.push(skillFile);
+    const readme = join(pluginDir, "README.md");
+    writeText(readme, `# ${opts.name}\n\n${manifest.description}\n`);
+    created.push(readme);
+    return { pluginDir, created };
+}
+/**
+ * Scaffold a marketplace catalog: .agents/.marketplace.json (empty member list)
+ * and README.md. Members are added later, or scaffold them with `--type all`.
+ */
+export function initMarketplace(opts) {
+    if (!NAME_RE.test(opts.name)) {
+        throw new Error(`marketplace name must be kebab-case, got "${opts.name}"`);
+    }
+    const catalogDir = join(opts.dir, opts.name);
+    const catalogFile = join(catalogDir, ADG_MARKETPLACE_PATH);
+    if (existsSync(catalogFile)) {
+        throw new Error(`${catalogFile} already exists; refusing to overwrite`);
+    }
+    const description = opts.description ?? `${opts.name} marketplace.`;
+    const catalog = {
+        name: opts.name,
+        description,
+        ...(opts.author ? { owner: { name: opts.author } } : {}),
+        plugins: [],
+    };
+    const created = [];
+    writeJson(catalogFile, catalog);
+    created.push(catalogFile);
+    const readme = join(catalogDir, "README.md");
+    writeText(readme, `# ${opts.name}\n\n${description}\n`);
+    created.push(readme);
+    return { pluginDir: catalogDir, created };
+}
+/**
+ * Scaffold both: a catalog root plus one starter member plugin in a
+ * subdirectory (a plugin and a marketplace cannot share one `.agents/` dir, so
+ * the member lives under `<name>/<name>/`). The catalog lists the member.
+ */
+function initAll(opts) {
+    const market = initMarketplace(opts);
+    const member = initPlugin({ ...opts, dir: join(opts.dir, opts.name) });
+    // Link the starter member into the catalog (source relative to the catalog's
+    // grandparent, i.e. the repo root that holds `.agents/`).
+    const catalogFile = join(opts.dir, opts.name, ADG_MARKETPLACE_PATH);
+    const catalog = {
+        name: opts.name,
+        description: opts.description ?? `${opts.name} marketplace.`,
+        ...(opts.author ? { owner: { name: opts.author } } : {}),
+        plugins: [{ name: opts.name, source: { source: "local", path: `./${opts.name}` } }],
+    };
+    writeJson(catalogFile, catalog);
+    return { pluginDir: join(opts.dir, opts.name), created: [...market.created, ...member.created] };
+}