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

package/dist/src/manifest.js

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ADG_SCHEMA_VERSION } from "./types.js";
+/** Canonical, vendor-neutral source manifest location (a plugin). */
+export const ADG_MANIFEST_PATH = join(".agents", ".plugin.json");
+/** Canonical, vendor-neutral source catalog location (a marketplace). */
+export const ADG_MARKETPLACE_PATH = join(".agents", ".marketplace.json");
+/** Legacy location, still read (deprecated) so pre-`.agents/` plugins resolve. */
+export const LEGACY_MANIFEST_PATH = join(".adg-plugin", "plugin.json");
+/**
+ * Resolve a plugin's manifest file, preferring the canonical `.agents/.plugin.json`
+ * and falling back to the legacy `.adg-plugin/plugin.json`. Returns undefined
+ * when neither exists.
+ */
+export function findManifestFile(pluginDir) {
+    const primary = join(pluginDir, ADG_MANIFEST_PATH);
+    if (existsSync(primary))
+        return primary;
+    const legacy = join(pluginDir, LEGACY_MANIFEST_PATH);
+    if (existsSync(legacy))
+        return legacy;
+    return undefined;
+}
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+export class ManifestError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid ADG manifest:\n  - ${issues.join("\n  - ")}`);
+        this.name = "ManifestError";
+        this.issues = issues;
+    }
+}
+/** Read and validate a plugin's `.agents/.plugin.json` (or legacy fallback). */
+export function readManifest(pluginDir) {
+    const file = findManifestFile(pluginDir);
+    if (!file) {
+        throw new ManifestError([`${ADG_MANIFEST_PATH} not found in ${pluginDir}`]);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new ManifestError([`${file} is not valid JSON: ${err.message}`]);
+    }
+    return validateManifest(raw);
+}
+/** Validate an already-parsed manifest object, throwing ManifestError on failure. */
+export function validateManifest(raw) {
+    const issues = collectIssues(raw);
+    if (issues.length > 0)
+        throw new ManifestError(issues);
+    return raw;
+}
+/** Collect validation issues without throwing (used by the `validate` command). */
+export function collectIssues(raw) {
+    const issues = [];
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return ["manifest must be a JSON object"];
+    }
+    const m = raw;
+    if (m.schemaVersion !== ADG_SCHEMA_VERSION) {
+        issues.push(`schemaVersion must be "${ADG_SCHEMA_VERSION}"`);
+    }
+    if (typeof m.name !== "string" || !NAME_RE.test(m.name)) {
+        issues.push("name is required and must be kebab-case (^[a-z0-9]+(-[a-z0-9]+)*$)");
+    }
+    if (typeof m.version !== "string" || !SEMVER_RE.test(m.version)) {
+        issues.push("version is required and must be semantic (e.g. 0.1.0)");
+    }
+    if (typeof m.description !== "string" || m.description.length === 0) {
+        issues.push("description is required and must be a non-empty string");
+    }
+    if (m.skills !== undefined && typeof m.skills !== "string" && !isStringArray(m.skills)) {
+        issues.push("skills must be a string or an array of strings");
+    }
+    for (const key of ["agents", "commands", "apps", "hooks", "mcp", "homepage", "changelog", "license", "category"]) {
+        if (m[key] !== undefined && typeof m[key] !== "string") {
+            issues.push(`${key} must be a string`);
+        }
+    }
+    if (m.strict !== undefined && typeof m.strict !== "boolean") {
+        issues.push("strict must be a boolean");
+    }
+    if (m.dependencies !== undefined) {
+        if (!Array.isArray(m.dependencies)) {
+            issues.push("dependencies must be an array");
+        }
+        else {
+            m.dependencies.forEach((dep, i) => {
+                if (typeof dep !== "object" || dep === null) {
+                    issues.push(`dependencies[${i}] must be an object`);
+                    return;
+                }
+                const d = dep;
+                if (typeof d.name !== "string")
+                    issues.push(`dependencies[${i}].name must be a string`);
+                if (typeof d.version !== "string")
+                    issues.push(`dependencies[${i}].version must be a string`);
+            });
+        }
+    }
+    // `adapters` is no longer part of the DSL. A stray one from an old manifest is
+    // tolerated (ignored) rather than rejected — output paths are ADG-internal.
+    return issues;
+}
+function isStringArray(v) {
+    return Array.isArray(v) && v.every((x) => typeof x === "string");
+}

package/dist/src/marketplace.js

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+export function emptyMarketplace(name) {
+    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, fallbackName) {
+    if (!existsSync(file))
+        return emptyMarketplace(fallbackName);
+    const raw = JSON.parse(readFileSync(file, "utf8"));
+    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, market) {
+    writeFileSync(file, JSON.stringify(market, null, 2) + "\n");
+}
+/** Insert or replace a plugin entry by name, preserving array order. */
+export function upsertMarketplacePlugin(market, plugin) {
+    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, name) {
+    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 → dist/src/package.js}

@@ -1,5 +1,3 @@
-import type { AdgManifest } from "./types.ts";
-
 /**
  * Manifest-driven packaging allowlist.
  *
@@ -10,45 +8,42 @@ import type { AdgManifest } from "./types.ts";
  * 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] ?? "";
+function topSegment(p) {
+    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);
+export function packagedRoots(manifest) {
+    // `.agents` is the canonical manifest home; `.adg-plugin` keeps legacy plugins
+    // shippable during the deprecation window.
+    const roots = new Set([".agents", ".adg-plugin"]);
+    const components = [
+        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;
+    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
@@ -57,18 +52,18 @@ export function packagedRoots(manifest: AdgManifest): Set<string> {
  * `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);
-  };
+export function packageFilter(manifest, opts) {
+    const roots = packagedRoots(manifest);
+    return (relPath) => {
+        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 → dist/src/paths.js}

@@ -1,11 +1,8 @@
 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.
  *
@@ -13,58 +10,57 @@ export const MARKETPLACE_FILENAME = "marketplace.json";
  * ~/.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");
+export function globalPluginsDir(env = process.env) {
+    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;
-  }
+export function projectPluginsDir(start = process.cwd()) {
+    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 claudeSkillsDir(global, cwd = process.cwd()) {
+    return global ? join(homedir(), ".claude", "skills") : join(cwd, ".claude", "skills");
 }
-
-export function lockPath(pluginsDir: string): string {
-  return join(pluginsDir, LOCK_FILENAME);
+export function lockPath(pluginsDir) {
+    return join(pluginsDir, LOCK_FILENAME);
 }
-
-export function marketplacePath(pluginsDir: string): string {
-  return join(pluginsDir, MARKETPLACE_FILENAME);
+export function marketplacePath(pluginsDir) {
+    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, "");
+function sanitizeGitUrl(url) {
+    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
@@ -72,40 +68,39 @@ function sanitizeGitUrl(url: string): string {
  * 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);
-  }
+export function sourceDirSegment(origin) {
+    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);
+export function pluginDir(pluginsDir, name, origin) {
+    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;
+export function installedPluginDir(pluginsDir, name, origin) {
+    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`.
  *
@@ -121,9 +116,8 @@ export function installedPluginDir(pluginsDir: string, name: string, origin: Plu
  * 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("/")}`;
+export function marketplaceSourcePath(pluginsDir, dest) {
+    const isCanonical = basename(pluginsDir) === "plugins" && basename(dirname(pluginsDir)) === ".agents";
+    const root = isCanonical ? dirname(dirname(pluginsDir)) : pluginsDir;
+    return `./${relative(root, dest).split("\\").join("/")}`;
 }

package/dist/src/semver.js

@@ -0,0 +1,55 @@
+export function parseVersion(v) {
+    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, b) {
+    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, range) {
+    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]) {
+    if (major > 0)
+        return [major + 1, 0, 0];
+    if (minor > 0)
+        return [0, minor + 1, 0];
+    return [0, 0, patch + 1];
+}

package/dist/src/skills.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * 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, manifest) {
+    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;
+            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, manifest) {
+    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) {
+    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] ?? "");
+        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, manifest) {
+    let paths;
+    const cache = new Map();
+    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;
+    };
+}