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

package/src/adapters/anthropic.ts

@@ -1,54 +0,0 @@
-import { join } from "node:path";
-import type { AdgManifest, PluginSelection } from "../types.ts";
-import { resolveSkills } from "../skills.ts";
-import { isExposed } from "../components.ts";
-import type { AdapterResult } from "./index.ts";
-
-/**
- * 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: string,
-  manifest: AdgManifest,
-  selection?: PluginSelection,
-): AdapterResult {
-  const out: Record<string, unknown> = {
-    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/src/adapters/index.ts

@@ -1,24 +0,0 @@
-import type { AdgManifest, PluginSelection } from "../types.ts";
-import { toAnthropicManifest } from "./anthropic.ts";
-import { toCodexManifest } from "./openai.ts";
-
-export interface AdapterResult {
-  /** Default manifest path relative to the plugin directory. */
-  defaultPath: string;
-  /** The generated runtime-specific manifest object. */
-  manifest: Record<string, unknown>;
-}
-
-export type AdapterFn = (pluginDir: string, manifest: AdgManifest, selection?: PluginSelection) => AdapterResult;
-
-export const ADAPTERS: Record<string, AdapterFn> = {
-  claude: toAnthropicManifest,
-  anthropic: toAnthropicManifest,
-  codex: toCodexManifest,
-  openai: toCodexManifest,
-};
-
-export const ADAPTER_TARGETS = ["claude", "codex"] as const;
-export type AdapterTarget = (typeof ADAPTER_TARGETS)[number];
-
-export { toAnthropicManifest, toCodexManifest };

package/src/adapters/openai.ts

@@ -1,37 +0,0 @@
-import { join } from "node:path";
-import type { AdgManifest, PluginSelection } from "../types.ts";
-import { resolveSkills } from "../skills.ts";
-import { isExposed } from "../components.ts";
-import type { AdapterResult } from "./index.ts";
-
-/**
- * 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: string,
-  manifest: AdgManifest,
-  selection?: PluginSelection,
-): AdapterResult {
-  const skills = !selection
-    ? resolveSkills(pluginDir, manifest)
-    : isExposed(selection, "skills")
-      ? selection.skills ?? resolveSkills(pluginDir, manifest)
-      : [];
-
-  const out: Record<string, unknown> = {
-    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/src/adapters/reverse.ts

@@ -1,60 +0,0 @@
-import { ADG_SCHEMA_VERSION, type AdgManifest } from "../types.ts";
-import { validateManifest } from "../manifest.ts";
-
-export type NativeKind = "anthropic" | "openai";
-
-/**
- * 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: unknown, _kind: NativeKind): AdgManifest {
-  if (typeof raw !== "object" || raw === null) {
-    throw new Error("native manifest must be a JSON object");
-  }
-  const n = raw as Record<string, unknown>;
-  if (typeof n.name !== "string") throw new Error("native manifest missing string `name`");
-
-  const manifest: AdgManifest = {
-    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 as unknown as Record<string, unknown>;
-  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 as AdgManifest["author"];
-  } else if (typeof n.author === "string") {
-    manifest.author = { name: n.author };
-  }
-
-  if (typeof n.skills === "string" || isStringArray(n.skills)) {
-    manifest.skills = n.skills as string | string[];
-  } else {
-    manifest.skills = "./skills/";
-  }
-
-  manifest.strict = typeof n.strict === "boolean" ? n.strict : true;
-
-  return validateManifest(manifest);
-}
-
-function copyIfString(src: Record<string, unknown>, dst: Record<string, unknown>, key: string): void {
-  if (typeof src[key] === "string") dst[key] = src[key];
-}
-
-function isStringArray(v: unknown): v is string[] {
-  return Array.isArray(v) && v.every((x) => typeof x === "string");
-}

package/src/agents/claude.ts

@@ -1,124 +0,0 @@
-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.ts";
-import { readManifest } from "../manifest.ts";
-import { installedPluginDir, lockPath } from "../paths.ts";
-import { readLock } from "../lock.ts";
-import type { Agent, AgentContext, AgentSyncResult } from "./types.ts";
-
-/**
- * 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: string): string {
-  return p.split("\\").join("/");
-}
-
-function claudeHome(env: NodeJS.ProcessEnv): string {
-  return env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude");
-}
-
-function available(): boolean {
-  return spawnSync("claude", ["plugin", "--help"], { stdio: "ignore" }).status === 0;
-}
-
-function run(args: string[]): { ok: boolean; out: string } {
-  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: string, name: string = MARKETPLACE): { file: string; name: string } {
-  const lock = readLock(lockPath(pluginsDir));
-  const plugins: Record<string, unknown>[] = [];
-
-  for (const [pname, entry] of Object.entries(lock.plugins)) {
-    const dir = installedPluginDir(pluginsDir, pname, entry.origin);
-    let description = "";
-    let author: unknown;
-    let category: string | undefined;
-    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: string): void {
-  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: Agent = {
-  id: "claude",
-  displayName: "Claude Code",
-  adaptTarget: "claude",
-  detect: (env = process.env) => existsSync(claudeHome(env)),
-  available,
-
-  activate(ctx: AgentContext): AgentSyncResult {
-    if (!available()) return { agent: "claude", affected: [], skipped: true };
-    writeClaudeCatalog(ctx.pluginsDir);
-    syncMarketplace(ctx.pluginsDir);
-    const affected: string[] = [];
-    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: AgentContext): AgentSyncResult {
-    if (!available()) return { agent: "claude", affected: [], skipped: true };
-    const affected: string[] = [];
-    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: AgentContext): AgentSyncResult {
-    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/src/agents/codex.ts

@@ -1,67 +0,0 @@
-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.ts";
-import { readMarketplace } from "../marketplace.ts";
-import type { Agent, AgentContext, AgentSyncResult } from "./types.ts";
-
-/**
- * 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: NodeJS.ProcessEnv): string {
-  return env.CODEX_HOME?.trim() || join(homedir(), ".codex");
-}
-
-function available(): boolean {
-  return spawnSync("codex", ["plugin", "--help"], { stdio: "ignore" }).status === 0;
-}
-
-function run(args: string[]): { ok: boolean; out: string } {
-  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: string): string {
-  return readMarketplace(marketplacePath(pluginsDir), "").name;
-}
-
-export const codexAgent: Agent = {
-  id: "codex",
-  displayName: "Codex",
-  adaptTarget: "codex",
-  detect: (env = process.env) => existsSync(codexHome(env)) || existsSync("/etc/codex"),
-  available,
-
-  activate(ctx: AgentContext): AgentSyncResult {
-    const mp = marketplaceName(ctx.pluginsDir);
-    if (!available()) return { agent: "codex", affected: [], skipped: true };
-    const affected: string[] = [];
-    for (const p of ctx.plugins) {
-      if (run(["plugin", "add", `${p}@${mp}`]).ok) affected.push(p);
-    }
-    return { agent: "codex", affected, skipped: false };
-  },
-
-  deactivate(ctx: AgentContext): AgentSyncResult {
-    const mp = marketplaceName(ctx.pluginsDir);
-    if (!available()) return { agent: "codex", affected: [], skipped: true };
-    const affected: string[] = [];
-    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: AgentContext): AgentSyncResult {
-    return codexAgent.activate(ctx);
-  },
-};

package/src/agents/registry.ts

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

package/src/agents/types.ts

@@ -1,47 +0,0 @@
-import type { AdapterTarget } from "../adapters/index.ts";
-
-/** Identifier for an agent ADG can install plugins into ("claude", "codex", or a third-party id). */
-export type AgentId = string;
-
-/** Install scope within an agent. Codex is global-only and ignores it. */
-export type AgentScope = "user" | "project";
-
-/** What an agent operation acts on. Agents derive their own specifics (marketplace name, …). */
-export interface AgentContext {
-  pluginsDir: string;
-  plugins: string[];
-  scope: AgentScope;
-}
-
-/** Outcome of one agent lifecycle call. */
-export interface AgentSyncResult {
-  agent: AgentId;
-  /** Plugins enabled / disabled / refreshed. */
-  affected: string[];
-  /** True when the agent's CLI wasn't present, so the op was skipped (never a hard failure). */
-  skipped: boolean;
-}
-
-/**
- * The runtime-integration contract every agent implements. The pure manifest
- * transform stays in `src/adapters` and is *composed* via `adaptTarget` — agents
- * own only the side-effectful lifecycle (detect / available / activate / …).
- *
- * Adding an agent (including third-party) = implement this + `registerAgent()`.
- */
-export interface Agent {
-  id: AgentId;
-  displayName: string;
-  /** Manifest format to generate for this agent (keys into `ADAPTERS`). */
-  adaptTarget: AdapterTarget;
-  /** Whether the agent appears installed on this machine (config dir present). */
-  detect(env?: NodeJS.ProcessEnv): boolean;
-  /** Whether the agent's CLI is usable. */
-  available(): boolean;
-  /** Enable/install the plugins in the agent. */
-  activate(ctx: AgentContext): AgentSyncResult;
-  /** Uninstall the plugins from the agent. */
-  deactivate(ctx: AgentContext): AgentSyncResult;
-  /** Refresh the agent's cached copy after the store changed. */
-  refresh(ctx: AgentContext): AgentSyncResult;
-}

package/src/commands/adapt.ts

@@ -1,36 +0,0 @@
-import { join } from "node:path";
-import { ADAPTERS, type AdapterTarget } from "../adapters/index.ts";
-import { readManifest } from "../manifest.ts";
-import { writeJson } from "../fsutil.ts";
-import type { PluginSelection } from "../types.ts";
-
-export interface AdaptResult {
-  target: string;
-  file: string;
-}
-
-/**
- * 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: string, targets: AdapterTarget[], selection?: PluginSelection): AdaptResult[] {
-  const manifest = readManifest(pluginDir);
-  const results: AdaptResult[] = [];
-
-  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/src/commands/import.ts

@@ -1,69 +0,0 @@
-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.ts";
-import { writeJson, writeText } from "../fsutil.ts";
-import { installPlugin, type InstallResult } from "./install.ts";
-import { ADG_SCHEMA_VERSION, type AdgManifest } from "../types.ts";
-
-export interface ImportSkillsOptions {
-  /** Directory holding flat <name>/SKILL.md skill folders. */
-  skillsDir: string;
-  /** Name of the synthesized plugin. */
-  as: string;
-  /** Only include skills whose folder name starts with this prefix. */
-  prefix?: string;
-  pluginsDir: string;
-  version?: string;
-  description?: string;
-  marketplaceName?: string;
-  now?: string;
-}
-
-/**
- * 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: ImportSkillsOptions): InstallResult {
-  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: AdgManifest = {
-      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: string, to: string): void {
-  cpSync(from, to, { recursive: true });
-}