@rbbtsn0w/adg 0.2.1 → 0.3.0-beta.1

package/README.md

@@ -361,6 +361,12 @@ Debugging tips:
 - GitHub clone/sparse logic is injectable (`gitRunner`) and covered offline by
   the test suite; live network clones are exercised by `import owner/repo`.
 
+## Contributing
+
+All feature/fix pull requests target the **`beta`** integration branch; `main`
+is reserved for stable releases. See [CONTRIBUTING.md](CONTRIBUTING.md) and
+[docs/branching-and-release.md](docs/branching-and-release.md).
+
 ## License
 
 MIT

package/dist/bin/adg.js

@@ -1,7 +1,9 @@
 #!/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";
@@ -21,9 +23,24 @@ 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, projectPluginsDir } from "../src/paths.js";
+import { globalPluginsDir, installedPluginDir, projectPluginsDir } from "../src/paths.js";
 import { COMPONENT_TYPES } from "../src/types.js";
-import { getAgent } from "../src/agents/index.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),
+};
 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
@@ -208,7 +225,7 @@ function wantsHelp(args) {
     return args.includes("-h") || args.includes("--help");
 }
 function fail(msg) {
-    console.error(`error: ${msg}\n`);
+    console.error(`${ui.err("error:")} ${msg}\n`);
     console.error(TOP_USAGE);
     process.exit(1);
 }
@@ -231,9 +248,9 @@ function reportAgents(agents, verb) {
     for (const r of agents ?? []) {
         const name = getAgent(r.agent)?.displayName ?? r.agent;
         if (r.affected.length > 0)
-            console.log(`${verb} in ${name}: ${r.affected.join(", ")}`);
+            console.log(`${ui.ok(verb)} in ${ui.name(name)}: ${r.affected.join(", ")}`);
         else if (r.skipped)
-            console.log(`note: \`${r.agent}\` CLI not found — run \`adg plugins link --target ${r.agent}\` after installing it.`);
+            console.log(ui.warn(`note: \`${r.agent}\` CLI not found — run \`adg plugins link --target ${r.agent}\` after installing it.`));
     }
 }
 function resolveTargets(target) {
@@ -264,7 +281,7 @@ function parseVerb(name, flags, rest) {
         return { values: values, positionals };
     }
     catch (err) {
-        console.error(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+        console.error(`${ui.err("error:")} ${err instanceof Error ? err.message : String(err)}\n`);
         console.error(renderVerbHelp(name));
         process.exit(1);
     }
@@ -290,12 +307,21 @@ function formatColumns(items, opts = {}) {
     }
     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)}${type} (${names.length}):`);
+        console.log(`${" ".repeat(headerIndent)}${ui.name(type)} ${ui.meta(`(${names.length}):`)}`);
         console.log(formatColumns(names, { indent: headerIndent + 2, maxColWidth }));
     }
 }
@@ -308,7 +334,7 @@ async function runPlugins(rawVerb, rest) {
     const verb = PLUGIN_ALIASES[rawVerb] ?? rawVerb;
     const cmd = PLUGIN_COMMANDS[verb];
     if (!cmd) {
-        console.error(`error: unknown plugins subcommand: ${rawVerb}\n`);
+        console.error(`${ui.err("error:")} unknown plugins subcommand: ${rawVerb}\n`);
         console.error(renderPluginsHelp());
         process.exit(1);
     }
@@ -330,16 +356,16 @@ async function runPlugins(rawVerb, rest) {
                 fail(`invalid --type "${values.type}" (expected plugin|marketplace|all)`);
             }
             const res = initScaffold({ name, dir, type, description: values.description, author: values.author, skill: values.skill?.[0] });
-            console.log(`created ${type} at ${res.pluginDir}`);
+            console.log(`${ui.ok(`created ${type}`)} at ${ui.name(res.pluginDir)}`);
             for (const f of res.created)
-                console.log(`  + ${f}`);
+                console.log(ui.meta(`  + ${f}`));
             return;
         }
         case "adapt": {
             const { values, positionals } = parseVerb(verb, cmd.flags, rest);
             const pluginDir = resolve(positionals[0] ?? process.cwd());
             for (const r of adaptPlugin(pluginDir, resolveTargets(values.target))) {
-                console.log(`adapted ${r.target} -> ${r.file}`);
+                console.log(`${ui.ok("adapted")} ${ui.name(r.target)} ${ui.meta(`-> ${r.file}`)}`);
             }
             return;
         }
@@ -348,12 +374,12 @@ async function runPlugins(rawVerb, rest) {
             const pluginDir = resolve(positionals[0] ?? process.cwd());
             const res = validatePlugin(pluginDir);
             if (res.ok) {
-                console.log(`ok: ${pluginDir} is a valid ADG plugin`);
+                console.log(`${ui.ok("ok:")} ${ui.name(pluginDir)} is a valid ADG plugin`);
             }
             else {
-                console.error(`invalid: ${pluginDir}`);
+                console.error(`${ui.err("invalid:")} ${ui.name(pluginDir)}`);
                 for (const i of res.issues)
-                    console.error(`  - ${i}`);
+                    console.error(ui.warn(`  - ${i}`));
                 process.exit(1);
             }
             return;
@@ -404,14 +430,14 @@ async function runPlugins(rawVerb, rest) {
                 scope: global ? "user" : "project",
             });
             for (const name of converted)
-                console.log(`converted native manifest -> .agents/.plugin.json: ${name}`);
+                console.log(ui.meta(`converted native manifest -> .agents/.plugin.json: ${name}`));
             if (order.length > 1)
-                console.log(`install order: ${order.join(" -> ")}`);
+                console.log(ui.meta(`install order: ${order.join(" -> ")}`));
             for (const res of installed) {
-                console.log(`added ${res.name} -> ${res.installedTo}`);
-                console.log(`  folderHash: ${res.folderHash}`);
+                console.log(`${ui.ok("added")} ${ui.name(res.name)} ${ui.meta(`-> ${res.installedTo}`)}`);
+                console.log(ui.meta(`  folderHash: ${res.folderHash}`));
                 for (const f of res.adapted)
-                    console.log(`  adapted: ${f}`);
+                    console.log(ui.meta(`  adapted: ${f}`));
             }
             reportAgents(agents, "enabled");
             return;
@@ -430,7 +456,7 @@ async function runPlugins(rawVerb, rest) {
                 pluginsDir: resolveScopeDir(values),
                 description: values.description,
             });
-            console.log(`imported skills into ${res.name} -> ${res.installedTo}`);
+            console.log(`${ui.ok("imported skills into")} ${ui.name(res.name)} ${ui.meta(`-> ${res.installedTo}`)}`);
             return;
         }
         case "link": {
@@ -440,12 +466,12 @@ async function runPlugins(rawVerb, rest) {
                 fail("plugins link requires --target claude|codex");
             const res = linkPlugins({ pluginsDir: resolveScopeDir(values), target, global: Boolean(values.global) });
             for (const a of res.actions) {
-                console.log(`linked ${a.name} [${res.target}]${a.linkedTo ? ` -> ${a.linkedTo}` : ""}`);
+                console.log(`${ui.ok("linked")} ${ui.name(a.name)} ${ui.meta(`[${res.target}]`)}${a.linkedTo ? ui.meta(` -> ${a.linkedTo}`) : ""}`);
                 for (const f of a.adapted)
-                    console.log(`  adapted: ${f}`);
+                    console.log(ui.meta(`  adapted: ${f}`));
             }
             if (res.cliSkipped) {
-                console.log(`note: \`${target}\` CLI not found — manifests were generated, but nothing was enabled in ${target}.`);
+                console.log(ui.warn(`note: \`${target}\` CLI not found — manifests were generated, but nothing was enabled in ${target}.`));
             }
             return;
         }
@@ -456,9 +482,9 @@ async function runPlugins(rawVerb, rest) {
                 scope: scopeOf(values),
             });
             for (const r of results)
-                console.log(`${r.changed ? "updated" : "unchanged"} ${r.name}@${r.version}`);
+                console.log(`${r.changed ? ui.ok("updated") : ui.meta("unchanged")} ${ui.name(`${r.name}@${r.version}`)}`);
             for (const m of missing)
-                console.error(`  ! missing directory for locked plugin: ${m}`);
+                console.error(ui.warn(`  ! missing directory for locked plugin: ${m}`));
             reportAgents(agents, "re-synced");
             return;
         }
@@ -475,17 +501,17 @@ async function runPlugins(rawVerb, rest) {
                 scope: scopeOf(values),
             });
             if (res.removedDir)
-                console.log(`removed ${res.name} -> ${res.removedDir}`);
+                console.log(`${ui.ok("removed")} ${ui.name(res.name)} ${ui.meta(`-> ${res.removedDir}`)}`);
             else
-                console.log(`removed ${res.name} (no directory on disk)`);
+                console.log(`${ui.ok("removed")} ${ui.name(res.name)} ${ui.meta("(no directory on disk)")}`);
             for (const link of res.unlinked)
-                console.log(`  unlinked: ${link}`);
+                console.log(ui.meta(`  unlinked: ${link}`));
             for (const r of res.agents ?? []) {
                 if (r.affected.length > 0)
-                    console.log(`  disabled in ${getAgent(r.agent)?.displayName ?? r.agent}`);
+                    console.log(ui.meta(`  disabled in ${getAgent(r.agent)?.displayName ?? r.agent}`));
             }
             if (!res.removedFromLock && !res.removedDir) {
-                console.log(`  ${res.name} was not recorded in the lock`);
+                console.log(ui.warn(`  ${res.name} was not recorded in the lock`));
             }
             return;
         }
@@ -494,21 +520,42 @@ async function runPlugins(rawVerb, rest) {
             const pluginsDir = resolveScopeDir(values);
             const plugins = listPlugins(pluginsDir);
             if (plugins.length === 0) {
-                console.log(`no plugins recorded in ${pluginsDir}`);
+                console.log(ui.meta(`no plugins recorded in ${pluginsDir}`));
                 return;
             }
-            for (const p of plugins) {
-                const partial = p.selection ? "  (partial)" : "";
-                console.log(`${p.name}@${p.version}  [${p.origin.type}] ${p.folderHash.slice(0, 19)}${partial}`);
-                const entries = Object.entries(p.contents ?? {}).filter(([, names]) => names.length > 0);
-                if (entries.length === 0)
-                    continue;
-                if (values.verbose) {
-                    printContents(p.contents, 2);
-                }
-                else {
-                    console.log(`  ${entries.map(([type, names]) => `${type}: ${names.length}`).join("  ")}`);
-                }
+            // 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);
             }
             return;
         }
@@ -516,11 +563,11 @@ async function runPlugins(rawVerb, rest) {
             const { values } = parseVerb(verb, cmd.flags, rest);
             const res = migrateLayout(resolveScopeDir(values));
             for (const m of res.moved)
-                console.log(`moved ${m.name}: ${m.from} -> ${m.to}`);
+                console.log(`${ui.ok("moved")} ${ui.name(m.name)}: ${ui.meta(`${m.from} -> ${m.to}`)}`);
             for (const m of res.missing)
-                console.error(`  ! missing directory for locked plugin: ${m}`);
+                console.error(ui.warn(`  ! missing directory for locked plugin: ${m}`));
             if (res.moved.length === 0)
-                console.log(`nothing to migrate (${res.unchanged.length} already in place)`);
+                console.log(ui.meta(`nothing to migrate (${res.unchanged.length} already in place)`));
             return;
         }
         case "marketplace":
@@ -563,7 +610,7 @@ async function runMarketplace(args) {
             const dir = resolveScopeDir(values);
             const groups = marketplaceList({ pluginsDir: dir });
             if (groups.length === 0) {
-                console.log("No plugins installed.");
+                console.log(ui.meta("No plugins installed."));
                 return;
             }
             // Verbose: drill each plugin down to its components (reuses `plugins list -v`).
@@ -571,12 +618,12 @@ async function runMarketplace(args) {
             for (const g of groups) {
                 const ref = g.ref ? `@${g.ref}` : "";
                 const n = g.installed.length;
-                const tag = g.remote ? "" : "  (local — re-run add to update)";
-                console.log(`${g.source}${ref}  (${n} plugin${n !== 1 ? "s" : ""})${tag}`);
+                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(`  ${name}${p?.selection ? "  (partial)" : ""}`);
+                        console.log(`  ${ui.name(name)}${p?.selection ? ui.meta("  (partial)") : ""}`);
                         printContents(p?.contents, 4);
                     }
                 }
@@ -599,11 +646,11 @@ async function runMarketplace(args) {
             });
             for (const r of results) {
                 const conv = r.converted.length ? ` (${r.converted.length} converted from native)` : "";
-                console.log(`upgraded ${r.source}: ${r.updated.length} plugin(s)${conv}`);
+                console.log(`${ui.ok("upgraded")} ${ui.name(r.source)}: ${r.updated.length} plugin(s)${ui.meta(conv)}`);
                 for (const p of r.updated)
-                    console.log(`  ${p.name} -> ${p.installedTo}`);
+                    console.log(`  ${ui.name(p.name)} ${ui.meta(`-> ${p.installedTo}`)}`);
                 if (r.available.length > 0) {
-                    console.log(`  ${r.available.length} more available (use --all): ${r.available.join(", ")}`);
+                    console.log(ui.meta(`  ${r.available.length} more available (use --all): ${r.available.join(", ")}`));
                 }
             }
             return;
@@ -622,11 +669,11 @@ async function runMarketplace(args) {
                 force: values.force,
                 deactivate: true,
             });
-            console.log(`removed ${res.removed.length} plugin(s) from ${res.source}: ${res.removed.join(", ")}`);
+            console.log(`${ui.ok("removed")} ${res.removed.length} plugin(s) from ${ui.name(res.source)}: ${res.removed.join(", ")}`);
             return;
         }
         default: {
-            console.error(`error: unknown marketplace subcommand: ${sub}\n`);
+            console.error(`${ui.err("error:")} unknown marketplace subcommand: ${sub}\n`);
             console.error(MARKETPLACE_USAGE);
             process.exit(1);
         }
@@ -729,7 +776,7 @@ function isInvokedDirectly() {
 }
 if (isInvokedDirectly()) {
     main(process.argv.slice(2)).catch((err) => {
-        console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`${ui.err("error:")} ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     });
 }

package/dist/src/adapters/index.js

@@ -7,4 +7,15 @@ export const ADAPTERS = {
     openai: toCodexManifest,
 };
 export const ADAPTER_TARGETS = ["claude", "codex"];
+/**
+ * Component categories each adapter target can actually express, mirroring what
+ * the adapters emit: the Claude manifest carries skills/agents/commands/hooks/mcp
+ * (`toAnthropicManifest`), while Codex only consumes skills (`toCodexManifest`).
+ * `apps` is emitted by neither, so it maps to no target. Used to derive which
+ * agents a plugin is adaptable to from its exposed component types.
+ */
+export const ADAPTER_COMPONENTS = {
+    claude: ["skills", "agents", "commands", "hooks", "mcp"],
+    codex: ["skills"],
+};
 export { toAnthropicManifest, toCodexManifest };

package/dist/src/agents/index.js

@@ -6,5 +6,5 @@ import { codexAgent } from "./codex.js";
 registerAgent(claudeAgent);
 registerAgent(codexAgent);
 export * from "./types.js";
-export { registerAgent, getAgent, allAgents, detectedAgents, resolveAgents } from "./registry.js";
+export { registerAgent, getAgent, allAgents, detectedAgents, resolveAgents, agentsForComponents } from "./registry.js";
 export { writeClaudeCatalog } from "./claude.js";

package/dist/src/agents/registry.js

@@ -1,3 +1,4 @@
+import { ADAPTER_COMPONENTS } from "../adapters/index.js";
 /**
  * The agent registry — the "factory": construction/lookup only. Orchestration
  * (looping, dependency order, store writes) stays in the command layer.
@@ -16,6 +17,17 @@ export function allAgents() {
 export function detectedAgents(env) {
     return allAgents().filter((a) => a.detect(env));
 }
+/**
+ * Registered agents whose adapter can express at least one of the given exposed
+ * component types — i.e. the agents a plugin is adaptable to. An empty `types`
+ * (no manifest / nothing exposed) can't be proven incompatible, so all agents
+ * are returned.
+ */
+export function agentsForComponents(types) {
+    if (types.length === 0)
+        return allAgents();
+    return allAgents().filter((a) => (ADAPTER_COMPONENTS[a.adaptTarget] ?? []).some((c) => types.includes(c)));
+}
 /** Agents matching the given ids, or every registered agent when none are given. */
 export function resolveAgents(targets) {
     if (!targets)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbbtsn0w/adg",
-  "version": "0.2.1",
+  "version": "0.3.0-beta.1",
   "description": "Agent Directory Group (ADG) toolkit — two domains: plugins and skills.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
   },
   "scripts": {
     "adg": "node ./bin/adg.ts",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json --noCheck",
+    "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'",
     "typecheck": "tsc --noEmit",
     "prepare": "npm run typecheck",
@@ -52,6 +52,7 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/node": "^22.0.0",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
     "semantic-release": "^25.0.5",
     "typescript": "^5.6.0"
   }