@rbbtsn0w/adg 0.1.0-beta.2 → 0.1.0

package/README.md

@@ -33,6 +33,96 @@ See [docs/authoring.md](docs/authoring.md) to author a plugin, and
 
 ---
 
+# Install and quick start
+
+Install the CLI once, then run `adg` from anywhere:
+
+```bash
+npm install -g @rbbtsn0w/adg          # stable channel
+npm install -g @rbbtsn0w/adg@beta     # pre-release channel
+# or run ad-hoc, no install:
+npx @rbbtsn0w/adg --help
+```
+
+Typical end-user flow — pull a marketplace into your global store, then load it
+into the runtimes you use:
+
+```bash
+# 1) collect plugins into the global store (~/.agents/plugins)
+adg plugins add anthropics/knowledge-work-plugins --ref main --global
+#    large monorepo? fetch only what you need:
+adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global
+
+# 2) load into the runtimes you use
+adg plugins link --target codex  --global     # Codex discovers ~/.agents/plugins natively
+adg plugins link --target claude --global     # Claude loads via ~/.claude/skills symlinks
+
+# 3) keep it current
+adg plugins update --global
+adg plugins list --global
+```
+
+`adg` is the only command you invoke — no Node build step beyond the global
+install. To hack on the CLI itself, see [Developing from source](#developing-from-source).
+
+---
+
+# Works with existing ecosystems
+
+ADG is **not** a new plugin format you have to migrate to. Any repo that already
+ships `.claude-plugin/` or `.codex-plugin/` manifests is ingested as-is: on the
+way in, `add` discovers each native manifest and **reverse-adapts** it into a
+canonical `.agents/.plugin.json` (the inverse of `adapt`), then ADG manages and
+re-projects it like any first-party plugin. No fork, no edits upstream.
+
+The two examples below are real, popular repositories — neither is ADG-native.
+
+### Example 1 — `anthropics/knowledge-work-plugins` (a category monorepo)
+
+A marketplace monorepo where each top-level category (`engineering/`,
+`marketing/`, `legal/`, …) is its own plugin with a `.claude-plugin/plugin.json`
+and a `skills/` tree. Pull the whole thing, or sparse-checkout just the
+categories you want:
+
+```bash
+# whole marketplace into the global store
+adg plugins add anthropics/knowledge-work-plugins --ref main --global
+
+# or fetch only one category from the large monorepo
+adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global
+
+# each category's .claude-plugin manifest is reverse-adapted on import,
+# then projected back onto the runtimes you use
+adg plugins link --target claude --global   # → ~/.claude/skills/<plugin>:<skill>
+adg plugins link --target codex  --global   # native, zero-copy
+adg plugins list --global
+```
+
+### Example 2 — `obra/superpowers` (a single multi-runtime plugin)
+
+A single skills plugin that already ships `.claude-plugin/`, `.codex-plugin/` and
+a `skills/` library. Because the native manifests are already present, ADG simply
+adopts it — discovery picks up the existing manifest, records provenance and a
+content hash in the lock, and from then on it updates like any ADG plugin:
+
+```bash
+adg plugins add obra/superpowers --ref main --global
+
+# now under management — same lifecycle as a first-party plugin
+adg plugins list --global
+adg plugins update --global
+adg plugins link --target claude --global
+```
+
+> Both repos are pulled by `owner/repo` shorthand over a shallow clone (sparse
+> checkout when `--sparse` is given). Provenance — `{type:"github",repo,ref,path}`
+> — plus a `sha256` integrity hash land in `.plugin-lock.json`, so the install is
+> reproducible regardless of which ecosystem the plugin originally came from. See
+> [Importing existing inventory (via `add`)](#importing-existing-inventory-via-add)
+> for the discovery and reverse-adaptation details.
+
+---
+
 # Concepts (common)
 
 These apply the same whether you run a released build or the source tree.
@@ -99,7 +189,7 @@ The command surface is identical in both modes — **only the launcher differs**
 
 | Mode | Launcher | Setup |
 |------|----------|-------|
-| Released build | `adg …` | install the package (see [Using a released build](#using-a-released-build)) |
+| Released build | `adg …` | install the package (see [Install and quick start](#install-and-quick-start)) |
 | From source (debug) | `node bin/adg.ts …` | clone + `npm install` (see [Developing from source](#developing-from-source)) |
 
 The examples below use the released `adg` launcher. **When running from source,
@@ -233,40 +323,6 @@ private discovery path:
 
 ---
 
-# Using a released build
-
-> Pre-release: not yet published to npm. This is the intended end-user flow.
-
-Install the CLI once, then use the `adg` command from anywhere:
-
-```bash
-npm install -g adg        # or: npx adg <command>
-adg --help
-```
-
-Typical end-user workflow — bring a marketplace into your global environment and
-load it into your runtimes:
-
-```bash
-# 1) collect plugins into the global store (~/.agents/plugins)
-adg plugins add anthropics/knowledge-work-plugins --ref main --global
-#    large monorepo? fetch only what you need:
-adg plugins add anthropics/knowledge-work-plugins --ref main --sparse engineering --global
-
-# 2) load into the runtimes you use
-adg plugins link --target codex  --global     # Codex discovers ~/.agents/plugins natively
-adg plugins link --target claude --global     # Claude loads via ~/.claude/skills symlinks
-
-# 3) keep it current
-adg plugins update --global
-adg plugins list --global
-```
-
-No Node toolchain step is required beyond the global install; `adg` is the only
-command you invoke.
-
----
-
 # Developing from source
 
 For working on the CLI itself, or testing a plugin before release. The CLI runs

package/dist/src/commands/remove.js

@@ -1,9 +1,8 @@
 import { existsSync, lstatSync, readdirSync, readlinkSync, rmdirSync, rmSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { claudeSkillsDir, lockPath, marketplacePath, pluginDir } from "../paths.js";
 import { readLock, removeEntry, writeLock } from "../lock.js";
 import { readMarketplace, removeMarketplacePlugin, writeMarketplace } from "../marketplace.js";
-import { basename } from "node:path";
 import { resolveAgents } from "../agents/index.js";
 /**
  * Remove an installed plugin: delete its directory, drop it from

package/dist/src/commands/update.js

@@ -12,7 +12,8 @@ import { resolveAgents } from "../agents/index.js";
  * changed are reported as `changed`. A missing plugin directory is reported as
  * an issue rather than silently dropped.
  *
- * With `resync`, changed plugins are re-adapted (honoring their selection) and
+ * Changed plugins always have their runtime manifests regenerated (honoring
+ * their selection). With `resync`, the regenerated content is additionally
  * re-installed into the agents so Claude/Codex reflect the new content.
  */
 export function updateLock(pluginsDir, now = new Date().toISOString(), opts = {}) {

package/dist/src/commands/validate.js

@@ -1,7 +1,6 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ADG_MANIFEST_PATH, collectIssues } from "../manifest.js";
-import { readFileSync } from "node:fs";
 /**
  * Validate a plugin's manifest against the ADG schema and check that the
  * directories/files it references actually exist.

package/dist/src/semver.js

@@ -1,10 +1,16 @@
 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))) {
+    // Accept partial ranges (`1`, `1.2`) by defaulting missing minor/patch to 0,
+    // matching how semver ranges are commonly written in manifests.
+    if (parts.length < 1 || 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])];
+    return [
+        Number(parts[0]),
+        parts[1] !== undefined ? Number(parts[1]) : 0,
+        parts[2] !== undefined ? Number(parts[2]) : 0,
+    ];
 }
 export function compare(a, b) {
     for (let i = 0; i < 3; i++) {

package/dist/vendor/skills/src/providers/wellknown.js

@@ -552,6 +552,13 @@ export class WellKnownProvider {
             const localExtraLength = buffer.readUInt16LE(localHeaderOffset + 28);
             const dataStart = localHeaderOffset + 30 + localFileNameLength + localExtraLength;
             const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
+            // ADG patch: reject zip bombs before decompressing. The central directory
+            // declares the uncompressed size, so check it against the running budget
+            // up front — inflateRawSync would otherwise allocate the full (potentially
+            // multi-GB) output and OOM the process before addArchiveFile's check runs.
+            if (runningTotal.bytes + uncompressedSize > MAX_ARCHIVE_UNPACKED_BYTES) {
+                throw new Error('Archive exceeds maximum unpacked size');
+            }
             let content;
             if (method === 0) {
                 content = compressed;

package/dist/vendor/skills/src/source-parser.js

@@ -72,7 +72,18 @@ export function parseOwnerRepo(ownerRepo) {
  */
 export async function isRepoPrivate(owner, repo) {
     try {
-        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
+        // ADG patch: GitHub's API rejects requests without a User-Agent (403), and
+        // authenticating raises rate limits and reaches private repos. Read the
+        // token from env directly to keep this best-effort check silent (no gh spawn).
+        const headers = {
+            'User-Agent': 'skills-cli',
+            Accept: 'application/vnd.github.v3+json',
+        };
+        const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+        if (token) {
+            headers.Authorization = `Bearer ${token}`;
+        }
+        const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers });
         // If repo doesn't exist or we don't have access, assume private to be safe
         if (!res.ok) {
             return null; // Unable to determine

package/dist/vendor/skills/src/use.js

@@ -87,23 +87,31 @@ export function buildUsePrompt(input) {
 }
 export async function materializeUseSkill(skill) {
     const tempRoot = await mkdtemp(join(tmpdir(), 'skills-use-'));
-    const skillDir = join(tempRoot, sanitizeName(skill.directoryName || skill.name));
-    if (!isPathSafe(tempRoot, skillDir)) {
-        throw new Error('Invalid skill name: potential path traversal detected');
-    }
-    await mkdir(skillDir, { recursive: true });
-    if (skill.kind === 'blob') {
-        await writeSnapshotFiles(skillDir, skill.files);
-    }
-    else if (skill.kind === 'well-known') {
-        await writeMapFiles(skillDir, skill.files);
+    // ADG patch: clean up tempRoot if any setup step fails. runUse only tracks
+    // cloneTempDir, so without this a failed materialize would leak the temp dir.
+    try {
+        const skillDir = join(tempRoot, sanitizeName(skill.directoryName || skill.name));
+        if (!isPathSafe(tempRoot, skillDir)) {
+            throw new Error('Invalid skill name: potential path traversal detected');
+        }
+        await mkdir(skillDir, { recursive: true });
+        if (skill.kind === 'blob') {
+            await writeSnapshotFiles(skillDir, skill.files);
+        }
+        else if (skill.kind === 'well-known') {
+            await writeMapFiles(skillDir, skill.files);
+        }
+        else {
+            await copySkillDirectory(skill.path, skillDir);
+        }
+        const skillMd = skill.rawContent ?? (await readFile(join(skillDir, 'SKILL.md'), 'utf-8'));
+        const hasSupportingFiles = await containsSupportingFiles(skillDir, skillDir);
+        return { tempRoot, skillDir, skillMd, hasSupportingFiles };
     }
-    else {
-        await copySkillDirectory(skill.path, skillDir);
+    catch (error) {
+        await cleanupTempDir(tempRoot).catch(() => { });
+        throw error;
     }
-    const skillMd = skill.rawContent ?? (await readFile(join(skillDir, 'SKILL.md'), 'utf-8'));
-    const hasSupportingFiles = await containsSupportingFiles(skillDir, skillDir);
-    return { tempRoot, skillDir, skillMd, hasSupportingFiles };
 }
 export async function runUse(sourceArgs, options = {}, parseErrors = []) {
     let cloneTempDir = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbbtsn0w/adg",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0",
   "description": "Agent Directory Group (ADG) toolkit — two domains: plugins and skills.",
   "type": "module",
   "license": "MIT",

package/vendor/skills/src/providers/wellknown.ts

@@ -725,6 +725,14 @@ export class WellKnownProvider implements HostProvider {
       const dataStart = localHeaderOffset + 30 + localFileNameLength + localExtraLength;
       const compressed = buffer.subarray(dataStart, dataStart + compressedSize);
 
+      // ADG patch: reject zip bombs before decompressing. The central directory
+      // declares the uncompressed size, so check it against the running budget
+      // up front — inflateRawSync would otherwise allocate the full (potentially
+      // multi-GB) output and OOM the process before addArchiveFile's check runs.
+      if (runningTotal.bytes + uncompressedSize > MAX_ARCHIVE_UNPACKED_BYTES) {
+        throw new Error('Archive exceeds maximum unpacked size');
+      }
+
       let content: Buffer;
       if (method === 0) {
         content = compressed;

package/vendor/skills/src/source-parser.ts

@@ -82,7 +82,18 @@ export function parseOwnerRepo(ownerRepo: string): { owner: string; repo: string
  */
 export async function isRepoPrivate(owner: string, repo: string): Promise<boolean | null> {
   try {
-    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
+    // ADG patch: GitHub's API rejects requests without a User-Agent (403), and
+    // authenticating raises rate limits and reaches private repos. Read the
+    // token from env directly to keep this best-effort check silent (no gh spawn).
+    const headers: Record<string, string> = {
+      'User-Agent': 'skills-cli',
+      Accept: 'application/vnd.github.v3+json',
+    };
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (token) {
+      headers.Authorization = `Bearer ${token}`;
+    }
+    const res = await fetch(`https://api.github.com/repos/${owner}/${repo}`, { headers });
 
     // If repo doesn't exist or we don't have access, assume private to be safe
     if (!res.ok) {

package/vendor/skills/src/use.ts

@@ -157,26 +157,33 @@ export function buildUsePrompt(input: {
 
 export async function materializeUseSkill(skill: UseSkill): Promise<MaterializedUseSkill> {
   const tempRoot = await mkdtemp(join(tmpdir(), 'skills-use-'));
-  const skillDir = join(tempRoot, sanitizeName(skill.directoryName || skill.name));
+  // ADG patch: clean up tempRoot if any setup step fails. runUse only tracks
+  // cloneTempDir, so without this a failed materialize would leak the temp dir.
+  try {
+    const skillDir = join(tempRoot, sanitizeName(skill.directoryName || skill.name));
 
-  if (!isPathSafe(tempRoot, skillDir)) {
-    throw new Error('Invalid skill name: potential path traversal detected');
-  }
+    if (!isPathSafe(tempRoot, skillDir)) {
+      throw new Error('Invalid skill name: potential path traversal detected');
+    }
 
-  await mkdir(skillDir, { recursive: true });
+    await mkdir(skillDir, { recursive: true });
 
-  if (skill.kind === 'blob') {
-    await writeSnapshotFiles(skillDir, skill.files);
-  } else if (skill.kind === 'well-known') {
-    await writeMapFiles(skillDir, skill.files);
-  } else {
-    await copySkillDirectory(skill.path, skillDir);
-  }
+    if (skill.kind === 'blob') {
+      await writeSnapshotFiles(skillDir, skill.files);
+    } else if (skill.kind === 'well-known') {
+      await writeMapFiles(skillDir, skill.files);
+    } else {
+      await copySkillDirectory(skill.path, skillDir);
+    }
 
-  const skillMd = skill.rawContent ?? (await readFile(join(skillDir, 'SKILL.md'), 'utf-8'));
-  const hasSupportingFiles = await containsSupportingFiles(skillDir, skillDir);
+    const skillMd = skill.rawContent ?? (await readFile(join(skillDir, 'SKILL.md'), 'utf-8'));
+    const hasSupportingFiles = await containsSupportingFiles(skillDir, skillDir);
 
-  return { tempRoot, skillDir, skillMd, hasSupportingFiles };
+    return { tempRoot, skillDir, skillMd, hasSupportingFiles };
+  } catch (error) {
+    await cleanupTempDir(tempRoot).catch(() => {});
+    throw error;
+  }
 }
 
 export async function runUse(