@rbbtsn0w/adg 0.1.0-alpha.1

package/src/marketplace.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import type { Marketplace, MarketplacePlugin } from "./types.ts";
+
+export function emptyMarketplace(name: string): Marketplace {
+  return { name, plugins: [] };
+}
+
+/**
+ * Read a marketplace file. This file is the runtime-facing export (consumed by
+ * Codex), kept in the de-facto shape; ADG never treats it as its own control
+ * surface (that is the lock). The reader is tolerant: only structural fields are
+ * checked and unknown fields are preserved.
+ */
+export function readMarketplace(file: string, fallbackName: string): Marketplace {
+  if (!existsSync(file)) return emptyMarketplace(fallbackName);
+  const raw = JSON.parse(readFileSync(file, "utf8")) as Marketplace;
+  if (typeof raw.name !== "string" || !Array.isArray(raw.plugins)) {
+    throw new Error(`${file} is not a valid marketplace.json`);
+  }
+  return raw;
+}
+
+export function writeMarketplace(file: string, market: Marketplace): void {
+  writeFileSync(file, JSON.stringify(market, null, 2) + "\n");
+}
+
+/** Insert or replace a plugin entry by name, preserving array order. */
+export function upsertMarketplacePlugin(market: Marketplace, plugin: MarketplacePlugin): Marketplace {
+  const idx = market.plugins.findIndex((p) => p.name === plugin.name);
+  if (idx >= 0) market.plugins[idx] = plugin;
+  else market.plugins.push(plugin);
+  return market;
+}
+
+/** Remove a plugin entry by name. Returns true if one was removed. */
+export function removeMarketplacePlugin(market: Marketplace, name: string): boolean {
+  const idx = market.plugins.findIndex((p) => p.name === name);
+  if (idx < 0) return false;
+  market.plugins.splice(idx, 1);
+  return true;
+}

package/src/package.ts

@@ -0,0 +1,74 @@
+import type { AdgManifest } from "./types.ts";
+
+/**
+ * Manifest-driven packaging allowlist.
+ *
+ * A plugin ships only its *declared* payload — the component directories named
+ * in the manifest plus a small set of canonical metadata files — never the
+ * authoring repo's dev cruft (`src/`, `test/`, `docs/`, CI config, …). This is a
+ * default-deny model: anything not derivable from the manifest is dropped, which
+ * is both safer (no accidental secret/dev-file leakage) and consistent with the
+ * lock's content hash.
+ */
+
+/** Top-level metadata files always shipped with a plugin, matched case-insensitively. */
+const META_RE = /^(README|LICEN[CS]E|CHANGELOG|NOTICE)(\..+)?$/i;
+
+/** Generated runtime projections — shipped, but excluded from the content hash. */
+export const PROJECTION_DIRS = [".claude-plugin", ".codex-plugin"];
+
+/** Extract the first path segment of a manifest component value (e.g. "./skills/" -> "skills"). */
+function topSegment(p: string): string {
+  return p.replace(/^\.?[/\\]/, "").split(/[/\\]/)[0] ?? "";
+}
+
+/**
+ * The set of root-level entry names that constitute the authored plugin payload,
+ * derived from the manifest's declared components plus the canonical `.agents/`
+ * manifest home.
+ */
+export function packagedRoots(manifest: AdgManifest): Set<string> {
+  // `.agents` is the canonical manifest home; `.adg-plugin` keeps legacy plugins
+  // shippable during the deprecation window.
+  const roots = new Set<string>([".agents", ".adg-plugin"]);
+  const components: Array<string | string[] | undefined> = [
+    manifest.skills,
+    manifest.agents,
+    manifest.commands,
+    manifest.mcp,
+    manifest.hooks,
+    manifest.apps,
+  ];
+  for (const c of components) {
+    if (c === undefined) continue;
+    for (const p of Array.isArray(c) ? c : [c]) {
+      const seg = topSegment(p);
+      if (seg) roots.add(seg);
+    }
+  }
+  return roots;
+}
+
+/**
+ * Build a predicate over a root-relative path: whether it belongs to the
+ * packaged plugin. Used by both the copy step and the content hash so an
+ * in-place plugin (copy skipped) and a copied install hash identically.
+ *
+ * `includeProjections` controls whether the generated runtime manifests count:
+ * true when copying (they ship), false when hashing (so re-adapting is stable).
+ */
+export function packageFilter(
+  manifest: AdgManifest,
+  opts: { includeProjections: boolean },
+): (relPath: string) => boolean {
+  const roots = packagedRoots(manifest);
+  return (relPath: string): boolean => {
+    if (relPath === "") return true; // the plugin root itself
+    const segments = relPath.split(/[/\\]/);
+    const first = segments[0]!;
+    if (roots.has(first)) return true;
+    if (opts.includeProjections && PROJECTION_DIRS.includes(first)) return true;
+    // Metadata files only count at the root level (a single segment).
+    return segments.length === 1 && META_RE.test(first);
+  };
+}

package/src/paths.ts

@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import type { PluginSource } from "./types.ts";
+
+export const LOCK_FILENAME = ".plugin-lock.json";
+export const MARKETPLACE_FILENAME = "marketplace.json";
+
+/**
+ * Resolve the global plugins directory.
+ *
+ * Honors ADG_PLUGINS_HOME, then XDG_STATE_HOME/.agents/plugins, falling back to
+ * ~/.agents/plugins. Only the `plugins/` subtree is ever managed by ADG — the
+ * sibling AGENTS.md and skills/ are never read or written by this tool.
+ */
+export function globalPluginsDir(env: NodeJS.ProcessEnv = process.env): string {
+  if (env.ADG_PLUGINS_HOME) return env.ADG_PLUGINS_HOME;
+  if (env.XDG_STATE_HOME) return join(env.XDG_STATE_HOME, ".agents", "plugins");
+  return join(homedir(), ".agents", "plugins");
+}
+
+/**
+ * Resolve the project plugins directory by walking up from `start` to find a
+ * `.agents/plugins` directory or a repo root (`.git`); defaults to
+ * `<start>/.agents/plugins` when none is found.
+ */
+export function projectPluginsDir(start: string = process.cwd()): string {
+  let dir = start;
+  while (true) {
+    const candidate = join(dir, ".agents", "plugins");
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, ".git"))) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) return join(start, ".agents", "plugins");
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve Claude's skills-directory plugin root, where a symlinked plugin
+ * auto-loads as `<name>@skills-dir`. Global → ~/.claude/skills, project →
+ * <cwd>/.claude/skills. This is Claude's own directory, distinct from the
+ * never-touched ~/.agents/skills.
+ */
+export function claudeSkillsDir(global: boolean, cwd: string = process.cwd()): string {
+  return global ? join(homedir(), ".claude", "skills") : join(cwd, ".claude", "skills");
+}
+
+export function lockPath(pluginsDir: string): string {
+  return join(pluginsDir, LOCK_FILENAME);
+}
+
+export function marketplacePath(pluginsDir: string): string {
+  return join(pluginsDir, MARKETPLACE_FILENAME);
+}
+
+/**
+ * Make a filesystem-safe single path segment out of a git URL by replacing the
+ * scheme/host/path separators with `__` and dropping a trailing `.git`.
+ */
+function sanitizeGitUrl(url: string): string {
+  return url
+    .replace(/\.git$/, "")
+    .replace(/[:/@]+/g, "__")
+    .replace(/^_+|_+$/g, "");
+}
+
+/**
+ * The directory bucket a plugin's files live under, grouped by the source it
+ * came from: remote sources nest beneath a per-marketplace segment
+ * (`owner/repo` → `owner__repo`), while local installs stay flat (return null).
+ * This is the on-disk grouping only — plugin name remains the unique key in the
+ * lock and marketplace.json.
+ */
+export function sourceDirSegment(origin: PluginSource): string | null {
+  switch (origin.type) {
+    case "local":
+      return null;
+    case "github":
+      return origin.repo.replaceAll("/", "__");
+    case "git":
+      return sanitizeGitUrl(origin.url);
+  }
+}
+
+/**
+ * Resolve where a plugin's files are installed: `<pluginsDir>/<segment>/<name>`
+ * for remote sources, or the flat `<pluginsDir>/<name>` for local installs.
+ */
+export function pluginDir(pluginsDir: string, name: string, origin: PluginSource): string {
+  const seg = sourceDirSegment(origin);
+  return seg ? join(pluginsDir, seg, name) : join(pluginsDir, name);
+}
+
+/**
+ * Resolve a plugin's *actual* on-disk directory. Prefers the canonical
+ * per-marketplace nested path, but falls back to the flat `<pluginsDir>/<name>`
+ * for installs made before the nested layout (and not yet `migrate`d). Returns
+ * the canonical nested path when neither exists.
+ */
+export function installedPluginDir(pluginsDir: string, name: string, origin: PluginSource): string {
+  const nested = pluginDir(pluginsDir, name, origin);
+  if (existsSync(nested)) return nested;
+  const flat = join(pluginsDir, name);
+  if (existsSync(flat)) return flat;
+  return nested;
+}
+
+/**
+ * The `source.path` to record in marketplace.json for a plugin at `dest`.
+ *
+ * For the canonical store layout `<root>/.agents/plugins`, Codex discovers the
+ * marketplace via the root that *contains* `.agents/` and resolves each entry's
+ * `source.path` relative to that root — so the path keeps its `.agents/plugins/`
+ * prefix (e.g. `./.agents/plugins/owner__repo/name`) for `codex plugin add` to
+ * find it.
+ *
+ * Any other store (an explicit `--dir <path>`) has no `.agents/` ancestor to
+ * resolve against; `dest` always lives *inside* `pluginsDir`, so we record a
+ * path relative to the store dir itself (e.g. `./name` or `./segment/name`).
+ * This stays correct regardless of where or how deep the store sits, instead of
+ * leaking parent-directory names from a fixed two-levels-up assumption.
+ */
+export function marketplaceSourcePath(pluginsDir: string, dest: string): string {
+  const isCanonical =
+    basename(pluginsDir) === "plugins" && basename(dirname(pluginsDir)) === ".agents";
+  const root = isCanonical ? dirname(dirname(pluginsDir)) : pluginsDir;
+  return `./${relative(root, dest).split("\\").join("/")}`;
+}

package/src/semver.ts

@@ -0,0 +1,67 @@
+/**
+ * Minimal semver comparison and range satisfaction.
+ *
+ * Supports the range forms ADG manifests use: exact (`1.2.3`), caret (`^1.2.3`),
+ * tilde (`~1.2.3`), wildcard (`*` / `x`), and simple comparators
+ * (`>=`, `>`, `<=`, `<`, `=`). Pre-release and build metadata are ignored for
+ * comparison.
+ */
+export type Semver = [number, number, number];
+
+export function parseVersion(v: string): Semver {
+  const core = v.trim().replace(/^[v=]/, "").split(/[-+]/)[0] ?? "";
+  const parts = core.split(".");
+  if (parts.length !== 3 || parts.some((p) => !/^\d+$/.test(p))) {
+    throw new Error(`invalid semantic version: "${v}"`);
+  }
+  return [Number(parts[0]), Number(parts[1]), Number(parts[2])];
+}
+
+export function compare(a: Semver, b: Semver): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i]! !== b[i]!) return a[i]! < b[i]! ? -1 : 1;
+  }
+  return 0;
+}
+
+export function satisfies(version: string, range: string): boolean {
+  const v = parseVersion(version);
+  const r = range.trim();
+
+  if (r === "" || r === "*" || r === "x" || r === "X") return true;
+
+  const cmp = r.match(/^(>=|<=|>|<|=)\s*(.+)$/);
+  if (cmp) {
+    const target = parseVersion(cmp[2]!);
+    const c = compare(v, target);
+    switch (cmp[1]) {
+      case ">=": return c >= 0;
+      case "<=": return c <= 0;
+      case ">": return c > 0;
+      case "<": return c < 0;
+      case "=": return c === 0;
+    }
+  }
+
+  if (r.startsWith("^")) {
+    const base = parseVersion(r.slice(1));
+    if (compare(v, base) < 0) return false;
+    const upper = caretUpperBound(base);
+    return compare(v, upper) < 0;
+  }
+
+  if (r.startsWith("~")) {
+    const base = parseVersion(r.slice(1));
+    if (compare(v, base) < 0) return false;
+    return compare(v, [base[0], base[1] + 1, 0]) < 0;
+  }
+
+  return compare(v, parseVersion(r)) === 0;
+}
+
+/** npm caret semantics: first non-zero leftmost component is the boundary. */
+function caretUpperBound([major, minor, patch]: Semver): Semver {
+  if (major > 0) return [major + 1, 0, 0];
+  if (minor > 0) return [0, minor + 1, 0];
+  return [0, 0, patch + 1];
+}

package/src/skills.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import type { AdgManifest } from "./types.ts";
+
+/** A resolved skill: its kebab-case name and the SKILL.md path (if one exists). */
+export interface SkillEntry {
+  name: string;
+  skillMd?: string;
+}
+
+/**
+ * Resolve the skills a plugin exposes, paired with their SKILL.md paths.
+ *
+ * - `skills` array → each entry's basename, SKILL.md resolved under the entry.
+ * - otherwise → auto-scan the skills root for sub-dirs that contain a SKILL.md.
+ */
+export function resolveSkillEntries(pluginDir: string, manifest: AdgManifest): SkillEntry[] {
+  const skills = manifest.skills;
+  if (Array.isArray(skills)) {
+    return skills.map((p) => {
+      const rel = p.replace(/\/+$/, "");
+      const name = rel.split("/").pop() ?? p;
+      const abs = join(pluginDir, rel);
+      let skillMd: string | undefined;
+      if (existsSync(abs)) {
+        const md = statSync(abs).isDirectory() ? join(abs, "SKILL.md") : abs;
+        if (existsSync(md)) skillMd = md;
+      }
+      return { name, skillMd };
+    });
+  }
+  const root = typeof skills === "string" ? skills : "./skills/";
+  const abs = join(pluginDir, root);
+  if (!existsSync(abs)) return [];
+  return readdirSync(abs, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(abs, e.name, "SKILL.md")))
+    .map((e) => ({ name: e.name, skillMd: join(abs, e.name, "SKILL.md") }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Resolve the list of skill names a plugin exposes.
+ *
+ * - `strict !== false` with an explicit `skills` array → that array (basenames).
+ * - otherwise → auto-scan the skills root directory for sub-dirs that contain a
+ *   SKILL.md file (skill names are the kebab-case directory names).
+ */
+export function resolveSkills(pluginDir: string, manifest: AdgManifest): string[] {
+  return resolveSkillEntries(pluginDir, manifest).map((e) => e.name);
+}
+
+/** Read a SKILL.md's `description` from its YAML frontmatter (undefined if absent). */
+export function readSkillDescription(skillMd: string): string | undefined {
+  try {
+    const head = readFileSync(skillMd, "utf8").slice(0, 4096);
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(head);
+    if (!m) return undefined;
+    const fm = parseYaml(m[1] ?? "") as { description?: unknown } | null;
+    const d = fm?.description;
+    return typeof d === "string" && d.trim() ? d.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build a lazy, cached description reader keyed by skill name. Files are only
+ * read on the first lookup of each name (and never for skills the user doesn't
+ * inspect), keeping the interactive picker free of upfront SKILL.md parsing.
+ */
+export function skillDescriptionLoader(
+  pluginDir: string,
+  manifest: AdgManifest,
+): (name: string) => string | undefined {
+  let paths: Map<string, string | undefined> | undefined;
+  const cache = new Map<string, string | undefined>();
+  return (name) => {
+    if (cache.has(name)) return cache.get(name);
+    if (!paths) {
+      paths = new Map(resolveSkillEntries(pluginDir, manifest).map((e) => [e.name, e.skillMd]));
+    }
+    const md = paths.get(name);
+    const desc = md ? readSkillDescription(md) : undefined;
+    cache.set(name, desc);
+    return desc;
+  };
+}

package/src/sources.ts

@@ -0,0 +1,159 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readManifest, findManifestFile } from "./manifest.ts";
+import type { PluginCandidate } from "./deps.ts";
+
+export interface GitHubSource {
+  kind: "github";
+  /** Normalized "owner/repo". */
+  source: string;
+  owner: string;
+  repo: string;
+  ref?: string;
+  sourceUrl: string;
+}
+
+export interface LocalSource {
+  kind: "local";
+  dir: string;
+}
+
+export type ParsedSource = GitHubSource | LocalSource;
+
+const GH_SHORTHAND = /^([\w.-]+)\/([\w.-]+?)(?:@(.+))?$/;
+const GH_URL = /^(?:https?:\/\/github\.com\/|git@github\.com:)([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:@(.+))?$/;
+
+/**
+ * Parse an install spec into a local directory or a GitHub source.
+ *
+ * An existing local directory always wins; otherwise the spec is matched
+ * against `owner/repo[@ref]` shorthand or a github.com URL.
+ */
+export function parseSource(spec: string): ParsedSource {
+  if (existsSync(spec)) return { kind: "local", dir: spec };
+
+  const url = spec.match(GH_URL);
+  if (url) {
+    const [, owner, repo, ref] = url;
+    return gh(owner!, repo!, ref);
+  }
+  const short = spec.match(GH_SHORTHAND);
+  if (short) {
+    const [, owner, repo, ref] = short;
+    return gh(owner!, repo!, ref);
+  }
+  throw new Error(`cannot parse install source: "${spec}" (expected a local path or owner/repo[@ref])`);
+}
+
+function gh(owner: string, repo: string, ref?: string): GitHubSource {
+  return {
+    kind: "github",
+    source: `${owner}/${repo}`,
+    owner,
+    repo,
+    ref,
+    sourceUrl: `https://github.com/${owner}/${repo}.git`,
+  };
+}
+
+/**
+ * Shallow-clone a GitHub source into `dest`, optionally restricting the working
+ * tree to `sparse` sub-paths (cone-mode sparse checkout) for large monorepos.
+ * The git runner is injectable so the flow can be exercised offline in tests.
+ */
+export function cloneGitHub(
+  src: GitHubSource,
+  dest: string,
+  opts: { sparse?: string[]; runner?: GitRunner } = {},
+): string {
+  const runner = opts.runner ?? defaultGitRunner;
+  const sparse = opts.sparse?.filter(Boolean) ?? [];
+
+  const clone = ["clone", "--depth", "1"];
+  if (src.ref) clone.push("--branch", src.ref);
+  if (sparse.length > 0) clone.push("--filter=blob:none", "--sparse");
+  clone.push(src.sourceUrl, dest);
+  runner(clone);
+
+  if (sparse.length > 0) {
+    runner(["-C", dest, "sparse-checkout", "set", ...sparse]);
+  }
+  return dest;
+}
+
+export type GitRunner = (args: string[]) => void;
+
+const defaultGitRunner: GitRunner = (args) => {
+  execFileSync("git", args, { stdio: "pipe" });
+};
+
+/**
+ * Recursively find ADG plugins under `root` (directories containing
+ * `.agents/.plugin.json`, or the legacy `.adg-plugin/plugin.json`), keyed by
+ * manifest name. Used as the resolution universe for dependency ordering.
+ */
+export function scanPlugins(root: string): Map<string, PluginCandidate> {
+  const found = new Map<string, PluginCandidate>();
+  walk(root, root, found);
+  return found;
+}
+
+function walk(root: string, current: string, out: Map<string, PluginCandidate>): void {
+  if (findManifestFile(current)) {
+    const manifest = readManifest(current);
+    if (!out.has(manifest.name)) out.set(manifest.name, { dir: current, manifest });
+    return; // do not descend into a plugin directory
+  }
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === ".git" || entry.name === "node_modules") continue;
+    walk(root, join(current, entry.name), out);
+  }
+}
+
+export const CODEX_MANIFEST_PATH = join(".codex-plugin", "plugin.json");
+export const CLAUDE_MANIFEST_PATH = join(".claude-plugin", "plugin.json");
+
+export interface NativePlugin {
+  dir: string;
+  /** Which runtime-native manifest was found. */
+  kind: "adg" | "openai" | "anthropic";
+  /** Path to the native manifest file. */
+  manifestFile: string;
+}
+
+/**
+ * Recursively find plugin directories under `root`, recognizing ADG, Codex and
+ * Claude manifests. Used by `import` to discover existing plugins to convert.
+ */
+export function scanNativePlugins(root: string): NativePlugin[] {
+  const found: NativePlugin[] = [];
+  walkNative(root, found);
+  return found;
+}
+
+function walkNative(current: string, out: NativePlugin[]): void {
+  // Resolution priority: canonical .agents/.plugin.json first, then Claude, then
+  // Codex. Only matters when a single dir exposes more than one manifest.
+  const adg = findManifestFile(current);
+  const claude = join(current, CLAUDE_MANIFEST_PATH);
+  const codex = join(current, CODEX_MANIFEST_PATH);
+  if (adg) {
+    out.push({ dir: current, kind: "adg", manifestFile: adg });
+    return;
+  }
+  if (existsSync(claude)) {
+    out.push({ dir: current, kind: "anthropic", manifestFile: claude });
+    return;
+  }
+  if (existsSync(codex)) {
+    out.push({ dir: current, kind: "openai", manifestFile: codex });
+    return;
+  }
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name === ".git" || entry.name === "node_modules") continue;
+    walkNative(join(current, entry.name), out);
+  }
+}