@rbbtsn0w/adg 0.3.0-beta.2 → 0.3.0-beta.4

package/dist/bin/adg.js

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
-import pc from "picocolors";
 import { spawnSync } from "node:child_process";
 import { readFileSync, realpathSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { checkForUpdate, formatUpdateNotice } from "../src/update-check.js";
@@ -23,24 +21,11 @@ import { selectTargetsInteractive } from "../src/commands/select-agents.js";
 import { selectPluginsInteractive } from "../src/commands/select-plugins.js";
 import { selectScopeInteractive } from "../src/commands/select-scope.js";
 import { confirmFullInstall, selectComponentsInteractive } from "../src/commands/select-components.js";
-import { globalPluginsDir, installedPluginDir, projectPluginsDir } from "../src/paths.js";
+import { globalPluginsDir, projectPluginsDir } from "../src/paths.js";
 import { COMPONENT_TYPES } from "../src/types.js";
-import { agentsForComponents, getAgent } from "../src/agents/index.js";
-// ---------------------------------------------------------------------------
-// Semantic colors, mirroring `adg skills list` so output reads the same across
-// commands: cyan = primary identifiers (plugins, agents, sources), dim =
-// secondary metadata (paths, hashes, sub-details), green = success, yellow =
-// notes/warnings, red = errors, bold = section titles. picocolors auto-disables
-// on non-TTY / NO_COLOR, so piped output and tests stay plain.
-// ---------------------------------------------------------------------------
-const ui = {
-    title: (s) => pc.bold(s),
-    name: (s) => pc.cyan(s),
-    meta: (s) => pc.dim(s),
-    ok: (s) => pc.green(s),
-    warn: (s) => pc.yellow(s),
-    err: (s) => pc.red(s),
-};
+import { getAgent } from "../src/agents/index.js";
+import { ui } from "../src/render/ui.js";
+import { renderAgentReport, renderMarketplaceList, renderPluginList, } from "../src/render/plugins.js";
 const FLAGS = {
     // Short flags are first-letter aliases. Where several long flags share a
     // first letter, the highest-frequency one wins the short and the rest stay
@@ -243,16 +228,6 @@ function scopeInfo(values) {
 function scopeOf(values) {
     return values.global ? "user" : "project";
 }
-/** Print per-agent sync outcomes (enabled/disabled/re-synced) generically. */
-function reportAgents(agents, verb) {
-    for (const r of agents ?? []) {
-        const name = getAgent(r.agent)?.displayName ?? r.agent;
-        if (r.affected.length > 0)
-            console.log(`${ui.ok(verb)} in ${ui.name(name)}: ${r.affected.join(", ")}`);
-        else if (r.skipped)
-            console.log(ui.warn(`note: \`${r.agent}\` CLI not found — run \`adg plugins link --target ${r.agent}\` after installing it.`));
-    }
-}
 /** Friendly `--target` aliases mapped onto canonical adapter target ids. */
 const TARGET_ALIASES = {
     anthropic: "claude",
@@ -294,45 +269,6 @@ function parseVerb(name, flags, rest) {
         process.exit(1);
     }
 }
-/**
- * Lay items out in aligned columns sized to the terminal width (row-major).
- * Items longer than `maxColWidth` are truncated with an ellipsis. Falls back to
- * a single column on narrow terminals. Returns the block as a string.
- */
-function formatColumns(items, opts = {}) {
-    const indent = opts.indent ?? 2;
-    const gutter = opts.gutter ?? 2;
-    const maxColWidth = opts.maxColWidth ?? 24;
-    const termWidth = opts.width ?? process.stdout.columns ?? 80;
-    const cells = items.map((s) => (s.length > maxColWidth ? s.slice(0, maxColWidth - 1) + "…" : s));
-    const colWidth = Math.min(Math.max(1, ...cells.map((c) => c.length)), maxColWidth);
-    const cols = Math.max(1, Math.floor((termWidth - indent + gutter) / (colWidth + gutter)));
-    const lines = [];
-    for (let i = 0; i < cells.length; i += cols) {
-        const row = cells.slice(i, i + cols);
-        const padded = row.map((c, j) => (j === row.length - 1 ? c : c.padEnd(colWidth)));
-        lines.push(" ".repeat(indent) + padded.join(" ".repeat(gutter)));
-    }
-    return lines.join("\n");
-}
-/** Abbreviate the home-directory prefix of an absolute path to `~` (POSIX `/` or Windows `\`). */
-function abbrevHome(p) {
-    const home = homedir();
-    if (p === home)
-        return "~";
-    if (p.startsWith(home + "/") || p.startsWith(home + "\\"))
-        return "~" + p.slice(home.length);
-    return p;
-}
-/** Print a plugin's components, each expanded to its member names (verbose view). */
-function printContents(contents, headerIndent) {
-    const entries = Object.entries(contents ?? {}).filter(([, names]) => names.length > 0);
-    for (const [type, names] of entries) {
-        const maxColWidth = Math.max(1, ...names.map((n) => n.length));
-        console.log(`${" ".repeat(headerIndent)}${ui.name(type)} ${ui.meta(`(${names.length}):`)}`);
-        console.log(formatColumns(names, { indent: headerIndent + 2, maxColWidth }));
-    }
-}
 async function runPlugins(rawVerb, rest) {
     // `adg plugins` (no verb) or an explicit help request → the L1 overview.
     if (rawVerb === undefined || rawVerb === "-h" || rawVerb === "--help" || rawVerb === "help") {
@@ -447,7 +383,8 @@ async function runPlugins(rawVerb, rest) {
                 for (const f of res.adapted)
                     console.log(ui.meta(`  adapted: ${f}`));
             }
-            reportAgents(agents, "enabled");
+            for (const line of renderAgentReport(agents, "enabled"))
+                console.log(line);
             return;
         }
         case "import-skills": {
@@ -494,7 +431,8 @@ async function runPlugins(rawVerb, rest) {
                 console.log(`${r.changed ? ui.ok("updated") : ui.meta("unchanged")} ${ui.name(`${r.name}@${r.version}`)}`);
             for (const m of missing)
                 console.error(ui.warn(`  ! missing directory for locked plugin: ${m}`));
-            reportAgents(agents, "re-synced");
+            for (const line of renderAgentReport(agents, "re-synced"))
+                console.log(line);
             return;
         }
         case "remove": {
@@ -528,43 +466,8 @@ async function runPlugins(rawVerb, rest) {
             const { values } = parseVerb(verb, cmd.flags, rest);
             const pluginsDir = resolveScopeDir(values);
             const plugins = listPlugins(pluginsDir);
-            if (plugins.length === 0) {
-                console.log(ui.meta(`no plugins recorded in ${pluginsDir}`));
-                return;
-            }
-            // Pre-compute each plugin's display row so the name/path columns can be
-            // aligned across rows (à la `adg skills list`). The `Agents:` column is
-            // derived from the exposed component types — which agents can adapt it.
-            const PATH_MAX = 44;
-            const rows = plugins.map((p) => {
-                const exposed = Object.entries(p.contents ?? {}).filter(([, names]) => names.length > 0);
-                const types = exposed.map(([type]) => type);
-                const agents = agentsForComponents(types).map((a) => a.displayName);
-                return {
-                    p,
-                    label: `${p.name}@${p.version}`,
-                    path: abbrevHome(installedPluginDir(pluginsDir, p.name, p.origin)),
-                    agents: agents.length > 0 ? agents.join(", ") : "—",
-                    counts: exposed.map(([type, names]) => `${type}: ${names.length}`),
-                };
-            });
-            const nameW = Math.max(...rows.map((r) => r.label.length));
-            const pathW = Math.min(PATH_MAX, Math.max(...rows.map((r) => r.path.length)));
-            const ellip = (s, w) => (s.length > w ? "…" + s.slice(s.length - w + 1) : s);
-            // Color mirrors `adg skills list`: cyan name, dim path / dim "Agents:"
-            // label with the agent names left bright, and the provenance/counts line
-            // fully dimmed as secondary metadata. Widths are measured on the uncolored
-            // strings (above), so wrapping the padded text keeps columns aligned.
-            // picocolors auto-disables on non-TTY / NO_COLOR, so pipes stay plain.
-            for (const r of rows) {
-                const partial = r.p.selection ? "  (partial)" : "";
-                const name = ui.name(r.label.padEnd(nameW));
-                const path = ui.meta(ellip(r.path, pathW).padEnd(pathW));
-                console.log(`${name}  ${path}  ${ui.meta("Agents:")} ${r.agents}`);
-                const provenance = `[${r.p.origin.type}] ${r.p.folderHash.slice(0, 19)}${partial}`;
-                console.log(ui.meta(`  ${[provenance, ...r.counts].join("   ")}`));
-                if (values.verbose)
-                    printContents(r.p.contents, 4);
+            for (const line of renderPluginList(plugins, pluginsDir, { verbose: values.verbose })) {
+                console.log(line);
             }
             return;
         }
@@ -618,28 +521,10 @@ async function runMarketplace(args) {
             const { values } = parseVerb("marketplace", ["verbose", ...SCOPE], rest);
             const dir = resolveScopeDir(values);
             const groups = marketplaceList({ pluginsDir: dir });
-            if (groups.length === 0) {
-                console.log(ui.meta("No plugins installed."));
-                return;
-            }
             // Verbose: drill each plugin down to its components (reuses `plugins list -v`).
             const byName = values.verbose ? new Map(listPlugins(dir).map((p) => [p.name, p])) : undefined;
-            for (const g of groups) {
-                const ref = g.ref ? `@${g.ref}` : "";
-                const n = g.installed.length;
-                const tag = g.remote ? "" : ui.warn("  (local — re-run add to update)");
-                console.log(`${ui.name(`${g.source}${ref}`)}  ${ui.meta(`(${n} plugin${n !== 1 ? "s" : ""})`)}${tag}`);
-                if (byName) {
-                    for (const name of g.installed) {
-                        const p = byName.get(name);
-                        console.log(`  ${ui.name(name)}${p?.selection ? ui.meta("  (partial)") : ""}`);
-                        printContents(p?.contents, 4);
-                    }
-                }
-                else {
-                    console.log(formatColumns(g.installed));
-                }
-            }
+            for (const line of renderMarketplaceList(groups, byName))
+                console.log(line);
             return;
         }
         case "upgrade": {

package/dist/src/adapters/anthropic.js

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { resolveSkills } from "../skills.js";
+import { resolveProjectedSkills } from "../skills.js";
 import { isExposed } from "../components.js";
 /**
  * Generate a Claude (.claude-plugin/plugin.json) manifest from an ADG manifest.
@@ -31,24 +31,16 @@ export function toAnthropicManifest(pluginDir, manifest, selection) {
         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.
+    // Claude's array form is already `./skills/<id>` paths, so a strict array is
+    // passed through verbatim; an explicit id list (selection or strict:false) is
+    // mapped to paths and marks the manifest non-strict.
+    const projected = resolveProjectedSkills(pluginDir, manifest, selection, { passthroughArray: true });
+    if (projected.explicit) {
         out.strict = false;
-        const names = isExposed(selection, "skills")
-            ? selection.skills ?? resolveSkills(pluginDir, manifest)
-            : [];
-        out.skills = names.map((name) => `./skills/${name}`);
+        out.skills = projected.skills.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}`);
-        }
+        out.skills = projected.skills;
     }
     return { defaultPath: join(".claude-plugin", "plugin.json"), manifest: out };
 }

package/dist/src/adapters/{openai.js → codex.js}

@@ -1,6 +1,5 @@
 import { join } from "node:path";
-import { resolveSkills } from "../skills.js";
-import { isExposed } from "../components.js";
+import { resolveProjectedSkills } from "../skills.js";
 /**
  * Generate a Codex (.codex-plugin/plugin.json) manifest from an ADG manifest.
  *
@@ -14,18 +13,9 @@ import { isExposed } from "../components.js";
  * rather than passed through. Codex only consumes skills.
  */
 export function toCodexManifest(pluginDir, manifest, selection) {
-    let skills;
-    if (selection) {
-        skills = isExposed(selection, "skills")
-            ? selection.skills ?? resolveSkills(pluginDir, manifest)
-            : [];
-    }
-    else {
-        const strict = manifest.strict !== false;
-        skills = strict && typeof manifest.skills === "string"
-            ? manifest.skills
-            : resolveSkills(pluginDir, manifest);
-    }
+    // Codex's array form is bare ids, so a strict skills *array* is resolved to
+    // ids rather than passed through; only a declared root string passes through.
+    const { skills } = resolveProjectedSkills(pluginDir, manifest, selection, { passthroughArray: false });
     const out = {
         name: manifest.name,
         version: manifest.version,

package/dist/src/adapters/index.js

@@ -1,11 +1,13 @@
 import { toAnthropicManifest } from "./anthropic.js";
-import { toCodexManifest } from "./openai.js";
+import { toCodexManifest } from "./codex.js";
 import { toAntigravityManifest } from "./antigravity.js";
+// `anthropic` is kept as a synonym because Claude's plugin.json *is* the
+// "anthropic" manifest shape. There is deliberately no `openai` key: the runtime
+// is Codex, and an `openai` alias would imply OpenAI support that does not exist.
 export const ADAPTERS = {
     claude: toAnthropicManifest,
     anthropic: toAnthropicManifest,
     codex: toCodexManifest,
-    openai: toCodexManifest,
     antigravity: toAntigravityManifest,
     agy: toAntigravityManifest,
     gemini: toAntigravityManifest,

package/dist/src/adapters/reverse.js

@@ -1,5 +1,6 @@
 import { ADG_SCHEMA_VERSION } from "../types.js";
 import { validateManifest } from "../manifest.js";
+import { toPosix } from "../fsutil.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
@@ -7,8 +8,14 @@ import { validateManifest } from "../manifest.js";
  *
  * 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/.
+ *
+ * `kind` disambiguates the two native skills-array conventions: Claude arrays are
+ * already `./skills/<id>` paths, while Codex arrays are bare ids. Both canonicalize
+ * to ADG's path-array contract so a later cross-adapt (e.g. codex → ADG → claude)
+ * emits valid `./skills/<id>` entries instead of leaking bare ids into a Claude
+ * manifest.
  */
-export function fromNativeManifest(raw, _kind) {
+export function fromNativeManifest(raw, kind) {
     if (typeof raw !== "object" || raw === null) {
         throw new Error("native manifest must be a JSON object");
     }
@@ -35,9 +42,16 @@ export function fromNativeManifest(raw, _kind) {
     else if (typeof n.author === "string") {
         manifest.author = { name: n.author };
     }
-    if (typeof n.skills === "string" || isStringArray(n.skills)) {
+    if (typeof n.skills === "string") {
         manifest.skills = n.skills;
     }
+    else if (isStringArray(n.skills)) {
+        // Codex arrays are bare ids; map them to ADG's `./skills/<id>` path form.
+        // Claude arrays are already paths, but a Windows-authored manifest may use
+        // backslashes, so normalize separators to keep ADG manifests POSIX-pathed
+        // (downstream `resolveSkillEntries` splits on `/`).
+        manifest.skills = kind === "codex" ? n.skills.map(toSkillPath) : n.skills.map(toPosix);
+    }
     else {
         manifest.skills = "./skills/";
     }
@@ -51,3 +65,12 @@ function copyIfString(src, dst, key) {
 function isStringArray(v) {
     return Array.isArray(v) && v.every((x) => typeof x === "string");
 }
+/**
+ * Canonicalize a skill reference (bare id or path) to ADG's `./skills/<id>` form.
+ * Accepts both `/` and `\` separators so a Windows-authored native manifest
+ * (e.g. `skills\\foo`) still yields a valid `./skills/foo` entry.
+ */
+function toSkillPath(ref) {
+    const name = ref.replace(/[\\/]+$/, "").split(/[\\/]/).pop() || ref;
+    return `./skills/${name}`;
+}

package/dist/src/agents/claude.js

@@ -2,7 +2,7 @@ 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 { toPosix, writeJson } from "../fsutil.js";
 import { readManifest } from "../manifest.js";
 import { installedPluginDir, lockPath } from "../paths.js";
 import { readLock } from "../lock.js";
@@ -15,9 +15,6 @@ import { readLock } from "../lock.js";
  * 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");
 }

package/dist/src/commands/install.js

@@ -4,7 +4,7 @@ import { basename, join, relative, resolve } from "node:path";
 import { ADAPTER_TARGETS } from "../adapters/index.js";
 import { fromNativeManifest } from "../adapters/reverse.js";
 import { adaptPlugin } from "./adapt.js";
-import { copyPluginDir, writeJson } from "../fsutil.js";
+import { copyPluginDir, toPosix, writeJson } from "../fsutil.js";
 import { folderHash } from "../hash.js";
 import { packageFilter, PROJECTION_DIRS } from "../package.js";
 import { lockPath, marketplacePath, marketplaceSourcePath, pluginDir } from "../paths.js";
@@ -19,9 +19,6 @@ import { skillDescriptionLoader } from "../skills.js";
 import { resolveAgents } from "../agents/index.js";
 // Generated runtime projections never count toward a plugin's content hash.
 const HASH_IGNORE = PROJECTION_DIRS;
-function toPosix(p) {
-    return p.split("\\").join("/");
-}
 /**
  * Install a single local plugin directory into a plugins directory: copy the
  * source, generate adapter manifests, compute the folder hash, and update both

package/dist/src/fsutil.js

@@ -3,6 +3,10 @@ import { dirname, relative } from "node:path";
 export function ensureDir(dir) {
     mkdirSync(dir, { recursive: true });
 }
+/** Normalize a path to forward slashes (stable across Windows and POSIX hosts). */
+export function toPosix(p) {
+    return p.split("\\").join("/");
+}
 export function writeJson(file, value) {
     ensureDir(dirname(file));
     writeFileSync(file, JSON.stringify(value, null, 2) + "\n");

package/dist/src/render/plugins.js

@@ -0,0 +1,100 @@
+import { ui, formatColumns, abbrevHome, ellipsizeStart } from "./ui.js";
+import { installedPluginDir } from "../paths.js";
+import { agentsForComponents, getAgent } from "../agents/index.js";
+// ---------------------------------------------------------------------------
+// Presentation layer for `adg plugins`. Each function turns command-layer data
+// into terminal-ready lines (returned as string[]), so bin/adg.ts only parses
+// args, calls a command, prints the lines — and the formatting is unit-testable
+// without spawning the CLI. Color mirrors `adg skills list` throughout.
+// ---------------------------------------------------------------------------
+/** A plugin's components, each expanded to its member names (verbose view). */
+export function renderContents(contents, headerIndent) {
+    const out = [];
+    const entries = Object.entries(contents ?? {}).filter(([, names]) => names.length > 0);
+    for (const [type, names] of entries) {
+        const maxColWidth = Math.max(1, ...names.map((n) => n.length));
+        out.push(`${" ".repeat(headerIndent)}${ui.name(type)} ${ui.meta(`(${names.length}):`)}`);
+        // formatColumns returns one string with embedded newlines; split so `out`
+        // stays a flat list of single lines.
+        out.push(...formatColumns(names, { indent: headerIndent + 2, maxColWidth }).split("\n"));
+    }
+    return out;
+}
+/** Per-agent sync outcomes (enabled/disabled/re-synced), printed generically. */
+export function renderAgentReport(agents, verb) {
+    const out = [];
+    for (const r of agents ?? []) {
+        const name = getAgent(r.agent)?.displayName ?? r.agent;
+        if (r.affected.length > 0)
+            out.push(`${ui.ok(verb)} in ${ui.name(name)}: ${r.affected.join(", ")}`);
+        else if (r.skipped)
+            out.push(ui.warn(`note: \`${r.agent}\` CLI not found — run \`adg plugins link --target ${r.agent}\` after installing it.`));
+    }
+    return out;
+}
+const PATH_MAX = 44;
+/** `adg plugins list` — aligned name/path/agents rows, with optional verbose contents. */
+export function renderPluginList(plugins, pluginsDir, opts = {}) {
+    if (plugins.length === 0)
+        return [ui.meta(`no plugins recorded in ${pluginsDir}`)];
+    // Pre-compute each plugin's display row so the name/path columns can be
+    // aligned across rows (à la `adg skills list`). The `Agents:` column is
+    // derived from the exposed component types — which agents can adapt it.
+    const rows = plugins.map((p) => {
+        const exposed = Object.entries(p.contents ?? {}).filter(([, names]) => names.length > 0);
+        const types = exposed.map(([type]) => type);
+        const agents = agentsForComponents(types).map((a) => a.displayName);
+        return {
+            p,
+            label: `${p.name}@${p.version}`,
+            path: abbrevHome(installedPluginDir(pluginsDir, p.name, p.origin)),
+            agents: agents.length > 0 ? agents.join(", ") : "—",
+            counts: exposed.map(([type, names]) => `${type}: ${names.length}`),
+        };
+    });
+    const nameW = Math.max(...rows.map((r) => r.label.length));
+    const pathW = Math.min(PATH_MAX, Math.max(...rows.map((r) => r.path.length)));
+    // Color mirrors `adg skills list`: cyan name, dim path / dim "Agents:" label
+    // with the agent names left bright, and the provenance/counts line fully
+    // dimmed as secondary metadata. Widths are measured on the uncolored strings
+    // (above), so wrapping the padded text keeps columns aligned.
+    const out = [];
+    for (const r of rows) {
+        const partial = r.p.selection ? "  (partial)" : "";
+        const name = ui.name(r.label.padEnd(nameW));
+        const path = ui.meta(ellipsizeStart(r.path, pathW).padEnd(pathW));
+        out.push(`${name}  ${path}  ${ui.meta("Agents:")} ${r.agents}`);
+        const provenance = `[${r.p.origin.type}] ${(r.p.folderHash ?? "").slice(0, 19)}${partial}`;
+        out.push(ui.meta(`  ${[provenance, ...r.counts].join("   ")}`));
+        if (opts.verbose)
+            out.push(...renderContents(r.p.contents, 4));
+    }
+    return out;
+}
+/**
+ * `adg plugins marketplace list` — installed plugins grouped by source.
+ * `details` (name → ListedPlugin) enables the verbose per-plugin component drill;
+ * pass it only when --verbose is set.
+ */
+export function renderMarketplaceList(groups, details) {
+    if (groups.length === 0)
+        return [ui.meta("No plugins installed.")];
+    const out = [];
+    for (const g of groups) {
+        const ref = g.ref ? `@${g.ref}` : "";
+        const n = g.installed.length;
+        const tag = g.remote ? "" : ui.warn("  (local — re-run add to update)");
+        out.push(`${ui.name(`${g.source}${ref}`)}  ${ui.meta(`(${n} plugin${n !== 1 ? "s" : ""})`)}${tag}`);
+        if (details) {
+            for (const name of g.installed) {
+                const p = details.get(name);
+                out.push(`  ${ui.name(name)}${p?.selection ? ui.meta("  (partial)") : ""}`);
+                out.push(...renderContents(p?.contents, 4));
+            }
+        }
+        else {
+            out.push(...formatColumns(g.installed).split("\n"));
+        }
+    }
+    return out;
+}

package/dist/src/render/ui.js

@@ -0,0 +1,51 @@
+import pc from "picocolors";
+import { homedir } from "node:os";
+// ---------------------------------------------------------------------------
+// Semantic colors, mirroring `adg skills list` so output reads the same across
+// commands: cyan = primary identifiers (plugins, agents, sources), dim =
+// secondary metadata (paths, hashes, sub-details), green = success, yellow =
+// notes/warnings, red = errors, bold = section titles. picocolors auto-disables
+// on non-TTY / NO_COLOR, so piped output and tests stay plain.
+// ---------------------------------------------------------------------------
+export const ui = {
+    title: (s) => pc.bold(s),
+    name: (s) => pc.cyan(s),
+    meta: (s) => pc.dim(s),
+    ok: (s) => pc.green(s),
+    warn: (s) => pc.yellow(s),
+    err: (s) => pc.red(s),
+};
+/**
+ * Lay items out in aligned columns sized to the terminal width (row-major).
+ * Items longer than `maxColWidth` are truncated with an ellipsis. Falls back to
+ * a single column on narrow terminals. Returns the block as a string.
+ */
+export function formatColumns(items, opts = {}) {
+    const indent = opts.indent ?? 2;
+    const gutter = opts.gutter ?? 2;
+    const maxColWidth = opts.maxColWidth ?? 24;
+    const termWidth = opts.width ?? process.stdout.columns ?? 80;
+    const cells = items.map((s) => (s.length > maxColWidth ? s.slice(0, maxColWidth - 1) + "…" : s));
+    const colWidth = Math.min(Math.max(1, ...cells.map((c) => c.length)), maxColWidth);
+    const cols = Math.max(1, Math.floor((termWidth - indent + gutter) / (colWidth + gutter)));
+    const lines = [];
+    for (let i = 0; i < cells.length; i += cols) {
+        const row = cells.slice(i, i + cols);
+        const padded = row.map((c, j) => (j === row.length - 1 ? c : c.padEnd(colWidth)));
+        lines.push(" ".repeat(indent) + padded.join(" ".repeat(gutter)));
+    }
+    return lines.join("\n");
+}
+/** Abbreviate the home-directory prefix of an absolute path to `~` (POSIX `/` or Windows `\`). */
+export function abbrevHome(p) {
+    const home = homedir();
+    if (p === home)
+        return "~";
+    if (p.startsWith(home + "/") || p.startsWith(home + "\\"))
+        return "~" + p.slice(home.length);
+    return p;
+}
+/** Tail-truncate a string to width `w`, prefixing an ellipsis when it overflows. */
+export function ellipsizeStart(s, w) {
+    return s.length > w ? "…" + s.slice(s.length - w + 1) : s;
+}

package/dist/src/semver.js

@@ -19,6 +19,82 @@ export function compare(a, b) {
     }
     return 0;
 }
+/**
+ * Extract the dot-separated pre-release identifiers from a version string.
+ *
+ * Returns the segment after the first `-` (and before any `+` build metadata),
+ * with numeric-only identifiers coerced to `number`. A stable version (no
+ * pre-release) yields `[]`.
+ */
+export function parsePrerelease(v) {
+    // Drop build metadata first so a hyphen inside it (e.g. `1.2.3+build-1`) is
+    // not mistaken for the pre-release separator.
+    const withoutBuild = v.split("+")[0] ?? "";
+    const dashIndex = withoutBuild.indexOf("-");
+    if (dashIndex === -1)
+        return [];
+    const pre = withoutBuild.slice(dashIndex + 1);
+    if (pre === "")
+        return [];
+    return pre.split(".").map((id) => (/^\d+$/.test(id) ? Number(id) : id));
+}
+/**
+ * Compare two pre-release identifier lists per SemVer §11.
+ *
+ * A stable version (empty list) outranks any pre-release. Otherwise identifiers
+ * are compared left to right: numeric identifiers rank below alphanumeric ones,
+ * numerics compare numerically, strings compare by ASCII, and when every shared
+ * field is equal the longer list wins.
+ */
+export function comparePrerelease(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1; // stable > pre-release
+    if (b.length === 0)
+        return -1;
+    const len = Math.min(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const x = a[i];
+        const y = b[i];
+        if (x === y)
+            continue;
+        const xNum = typeof x === "number";
+        const yNum = typeof y === "number";
+        if (xNum && yNum)
+            return x < y ? -1 : 1;
+        if (xNum !== yNum)
+            return xNum ? -1 : 1; // numeric < alphanumeric
+        return x < y ? -1 : 1;
+    }
+    // All shared fields equal: the list with more fields has higher precedence.
+    return a.length === b.length ? 0 : a.length < b.length ? -1 : 1;
+}
+/**
+ * Full version comparison including pre-release precedence.
+ *
+ * Unlike {@link compare}, this honors the pre-release suffix so that, e.g.,
+ * `0.3.0-beta.2 < 0.3.0-beta.3 < 0.3.0`. Used by the update check; range
+ * matching ({@link satisfies}) deliberately ignores pre-release.
+ */
+export function compareVersions(a, b) {
+    const core = compare(parseVersion(a), parseVersion(b));
+    if (core !== 0)
+        return core;
+    return comparePrerelease(parsePrerelease(a), parsePrerelease(b));
+}
+/**
+ * Return the pre-release channel of a version — its first non-numeric
+ * pre-release identifier (e.g. `0.3.0-beta.2` -> `"beta"`), or `null` for a
+ * stable version. Used to pick the matching npm dist-tag.
+ */
+export function prereleaseChannel(v) {
+    for (const id of parsePrerelease(v)) {
+        if (typeof id === "string")
+            return id;
+    }
+    return null;
+}
 export function satisfies(version, range) {
     const v = parseVersion(version);
     const r = range.trim();

package/dist/src/skills.js

@@ -42,6 +42,37 @@ export function resolveSkillEntries(pluginDir, manifest) {
 export function resolveSkills(pluginDir, manifest) {
     return resolveSkillEntries(pluginDir, manifest).map((e) => e.name);
 }
+/**
+ * Decide the skills a forward adapter should project from an ADG manifest, the
+ * one strict/selection decision both adapters share (previously copy-pasted, so
+ * it could drift — see the Codex/Claude strict regression that motivated it).
+ *
+ * In the default strict case the declared skills *root* string is passed through
+ * (the runtime discovers skills from the directory); an omitted `skills` is
+ * treated as the default `./skills/` root so the strict default stays
+ * directory-discovery rather than an explicit enumeration. A `selection` or
+ * `strict: false` always yields an explicit resolved id list. A declared `skills`
+ * *array* is runtime-dependent: `passthroughArray` keeps it verbatim (Claude,
+ * whose entries are already `./skills/<id>` paths), otherwise it resolves to ids
+ * (Codex, whose array form is bare ids).
+ */
+export function resolveProjectedSkills(pluginDir, manifest, selection, opts) {
+    if (selection) {
+        const skills = selection.components.includes("skills")
+            ? selection.skills ?? resolveSkills(pluginDir, manifest)
+            : [];
+        return { skills, explicit: true };
+    }
+    const strict = manifest.strict !== false;
+    // An omitted `skills` defaults to the `./skills/` root, so a strict manifest
+    // without a declaration keeps directory discovery instead of being forced to
+    // an explicit `strict: false` enumeration.
+    const declared = manifest.skills ?? "./skills/";
+    const passthrough = strict && (typeof declared === "string" || (opts.passthroughArray && Array.isArray(declared)));
+    if (passthrough)
+        return { skills: declared, explicit: false };
+    return { skills: resolveSkills(pluginDir, manifest), explicit: true };
+}
 /** Read a SKILL.md's `description` from its YAML frontmatter (undefined if absent). */
 export function readSkillDescription(skillMd) {
     try {

package/dist/src/sources.js

@@ -105,11 +105,11 @@ function walkNative(current, out) {
         return;
     }
     if (existsSync(claude)) {
-        out.push({ dir: current, kind: "anthropic", manifestFile: claude });
+        out.push({ dir: current, kind: "claude", manifestFile: claude });
         return;
     }
     if (existsSync(codex)) {
-        out.push({ dir: current, kind: "openai", manifestFile: codex });
+        out.push({ dir: current, kind: "codex", manifestFile: codex });
         return;
     }
     for (const entry of readdirSync(current, { withFileTypes: true })) {

package/dist/src/update-check.js

@@ -10,12 +10,20 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import https from "node:https";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { compare, parseVersion } from "./semver.js";
+import { compareVersions, prereleaseChannel } from "./semver.js";
 const PACKAGE_NAME = "@rbbtsn0w/adg";
 // URL-encode the slash in the scoped package name for the npm registry API.
-const REGISTRY_URL = `https://registry.npmjs.org/@rbbtsn0w%2Fadg/latest`;
+// The abbreviated packument (vnd.npm.install-v1+json) is small and exposes
+// `dist-tags`, which we need to follow the caller's release channel (e.g. the
+// `beta` dist-tag for pre-release users, not just `latest`).
+const REGISTRY_URL = `https://registry.npmjs.org/@rbbtsn0w%2Fadg`;
+const REGISTRY_ACCEPT = "application/vnd.npm.install-v1+json";
 const CACHE_FILENAME = "update-check.json";
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+// Cap the accumulated response body. The abbreviated packument is small, but a
+// registry that ignores the abbreviated Accept header (or returns an unexpected
+// payload) could stream a much larger body; abort rather than grow unbounded.
+const MAX_RESPONSE_BYTES = 1024 * 1024; // 1 MiB
 /** Resolve the directory that holds the update-check cache file. */
 export function updateCacheDir(env = process.env) {
     const stateHome = env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
@@ -46,6 +54,29 @@ export function writeUpdateCache(cache, env = process.env) {
         // Ignore write errors (read-only FS, permissions, etc.)
     }
 }
+/**
+ * Pick the newest version relevant to the caller's release channel from the
+ * registry's `dist-tags`.
+ *
+ * Always considers `latest` (stable). When `currentVersion` is a pre-release
+ * (e.g. `0.3.0-beta.2`) it also considers the matching channel tag (e.g.
+ * `beta`), so pre-release users are notified of newer pre-releases as well as a
+ * newer stable. Returns the max candidate by pre-release-aware comparison, or
+ * `undefined` when no usable tag is present.
+ */
+export function resolveLatestForChannel(currentVersion, distTags) {
+    if (!distTags)
+        return undefined;
+    const candidates = [];
+    if (typeof distTags.latest === "string")
+        candidates.push(distTags.latest);
+    const channel = prereleaseChannel(currentVersion);
+    if (channel && typeof distTags[channel] === "string")
+        candidates.push(distTags[channel]);
+    if (candidates.length === 0)
+        return undefined;
+    return candidates.reduce((best, v) => (compareVersions(v, best) > 0 ? v : best));
+}
 /**
  * Fire-and-forget background fetch of the latest version from the npm registry.
  * The socket is unreffed so Node can exit naturally without waiting for the
@@ -53,14 +84,26 @@ export function writeUpdateCache(cache, env = process.env) {
  */
 export function scheduleUpdateCacheRefresh(currentVersion, env = process.env) {
     try {
-        const req = https.get(REGISTRY_URL, { headers: { "User-Agent": `adg/${currentVersion}`, Accept: "application/json" } }, (res) => {
+        const req = https.get(REGISTRY_URL, { headers: { "User-Agent": `adg/${currentVersion}`, Accept: REGISTRY_ACCEPT } }, (res) => {
             let body = "";
-            res.on("data", (chunk) => { body += String(chunk); });
+            let byteCount = 0;
+            res.on("data", (chunk) => {
+                byteCount += Buffer.byteLength(chunk);
+                if (byteCount > MAX_RESPONSE_BYTES) {
+                    // Oversized payload: stop reading and abort so we neither buffer
+                    // unbounded memory nor parse a partial body.
+                    body = "";
+                    req.destroy();
+                    return;
+                }
+                body += String(chunk);
+            });
             res.on("end", () => {
                 try {
                     const data = JSON.parse(body);
-                    if (typeof data.version === "string") {
-                        writeUpdateCache({ latestVersion: data.version, checkedAt: new Date().toISOString() }, env);
+                    const latestVersion = resolveLatestForChannel(currentVersion, data["dist-tags"]);
+                    if (latestVersion !== undefined) {
+                        writeUpdateCache({ latestVersion, checkedAt: new Date().toISOString() }, env);
                     }
                 }
                 catch {
@@ -103,9 +146,7 @@ export function checkForUpdate(currentVersion, env = process.env, refresh = sche
     if (!cache)
         return undefined;
     try {
-        const current = parseVersion(currentVersion);
-        const latest = parseVersion(cache.latestVersion);
-        return compare(latest, current) > 0 ? cache.latestVersion : undefined;
+        return compareVersions(cache.latestVersion, currentVersion) > 0 ? cache.latestVersion : undefined;
     }
     catch {
         return undefined;
@@ -113,6 +154,11 @@ export function checkForUpdate(currentVersion, env = process.env, refresh = sche
 }
 /** Format an update notice for display on stderr. */
 export function formatUpdateNotice(currentVersion, latestVersion) {
+    // A pre-release suggestion lives on its channel dist-tag (e.g. `beta`), not
+    // `latest`; installing `@latest` would pull the stable release instead of the
+    // advertised version. Pin to the exact version so the right artifact installs.
+    const channel = prereleaseChannel(latestVersion);
+    const installTarget = channel ? latestVersion : "latest";
     return (`\n  Update available: ${currentVersion} → ${latestVersion}\n` +
-        `  Run: npm install -g ${PACKAGE_NAME}@latest\n`);
+        `  Run: npm install -g ${PACKAGE_NAME}@${installTarget}\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbbtsn0w/adg",
-  "version": "0.3.0-beta.2",
+  "version": "0.3.0-beta.4",
   "description": "Agent Directory Group (ADG) toolkit — two domains: plugins and skills.",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,7 @@
     "adg": "node ./bin/adg.ts",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json --noCheck && node -e \"require('fs').chmodSync('dist/bin/adg.js',0o755)\"",
     "test": "node --test 'test/**/*.test.ts'",
+    "check:vendor-deps": "node scripts/check-vendor-deps.mjs",
     "typecheck": "tsc --noEmit",
     "prepare": "npm run typecheck",
     "prepack": "npm run build"
@@ -35,12 +36,12 @@
     "vendor",
     "docs"
   ],
-  "comment:dependencies": "Runtime deps below are required only by the vendored skills CLI (vendor/skills). ADG's own plugins code has zero runtime deps.",
+  "comment:dependencies": "Runtime deps below are required only by the vendored skills CLI (vendor/skills); ADG's own plugins code has zero runtime deps. Root is the single source of truth: each range MUST be >= the floor declared in vendor/skills/package.json, since that is the version the vendored source was authored against. `npm run check:vendor-deps` enforces this and fails on drift.",
   "dependencies": {
-    "@clack/prompts": "^0.7.0",
+    "@clack/prompts": "^0.11.0",
     "@vercel/detect-agent": "^1.2.3",
-    "picocolors": "^1.0.0",
-    "simple-git": "^3.0.0",
+    "picocolors": "^1.1.1",
+    "simple-git": "^3.36.0",
     "xdg-basedir": "^5.1.0",
     "yaml": "^2.8.3"
   },