@phnx-labs/agents-cli 1.20.9 → 1.20.11

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+**`agents inspect <repo>` summary now shows what's actually inside, not just counts**
+
+- The bare repo summary gained four enrichments so it reads as an inventory instead of a tally: (1) **resource name previews** — each kind lists its first few names with a `…(+N)` tail; (2) **manifest summary** — `agents.yaml` is parsed for its `run.<agent>.strategy` and any `agents.<agent>` version pins, shown under `manifests` instead of just the filename; (3) **git detail** — last commit (sha, subject, relative time), ahead/behind upstream when non-zero, and the names of dirty files; (4) **size + file counts** — total repo size and a per-kind byte size. `--json` carries all of it (`git.lastCommit`, `git.ahead/behind`, `manifest`, `size`, and per-kind `{count, bytes, files, names}`); `--brief` still skips resources and size.
+- Fixed a path-parse bug surfaced by the dirty-files list: the shared git helper trimmed leading whitespace, which clipped the first character off the first `git status --porcelain` path; status is now read untrimmed.
+
+**`agents inspect .` reads the project `.agents/`, and plugin drill-down shows bundled skills**
+
+- `agents inspect .` (and any path to a repo root) now resolves to the project's nested `.agents/` tree when that tree is a populated DotAgents root, instead of the project root itself. Previously a top-level `agents.yaml` version-pin or an unrelated source `skills/` dir at the repo root was mistaken for a DotAgents root, so `inspect .` reported the wrong directory's resources (e.g. `plugins 0` while the real `.agents/plugins/` held a plugin). A bare `.agents`-named dir still resolves to itself, and standalone clones / extra repos that keep resources at the top level (using `.agents/` only for worktrees) are unaffected — their nested `.agents/` is not a DotAgents root, so the top level still wins.
+- `agents inspect <repo> --plugins` now reads plugin bundles through the plugin discoverer: the list shows each plugin's manifest description, and drilling into one (`--plugins <name>`) reports its bundled skills, commands, subagents, hooks, MCP servers, and version. Previously plugins were treated as opaque directories with no description and no view into what they ship.
+
 **Single-typo agent names auto-correct everywhere, not just `agents run`**
 
 - `agents view cladue` used to print `Unknown agent 'cladue'` even though `agents run cladue` auto-corrected. `resolveAgentName` — the canonical resolver behind `view`, `usage`, `inspect`, `doctor`, `sync`, `models`, `skills`, `hooks`, `import`, `sessions --agent`, and every `agent@version` spec (`agents add claud@latest`, `agents use codx@2.1.170`) — now falls back to Damerau-Levenshtein distance-1 matching against canonical ids and multi-letter aliases: `cladue` -> `claude` (transposition), `kim` -> `kimi`, `codx` -> `codex`, `gemni` -> `gemini`.

package/dist/commands/inspect.d.ts

@@ -24,6 +24,8 @@ interface ResourceItem {
     linkTarget: string;
     /** One-line description (frontmatter `description:` or first non-frontmatter line). */
     description: string;
+    /** Extra detail rows surfaced in detail mode (e.g. a plugin's bundled skills/commands). */
+    extra?: Array<[string, string]>;
 }
 interface InspectOptions {
     brief?: boolean;
@@ -54,4 +56,39 @@ export interface RepoTarget {
 export declare function resolveRepoTarget(target: string, cwd?: string): RepoTarget | null;
 /** List one resource kind from a single repo root — no layering, no overrides. */
 export declare function collectRepoKind(repo: RepoTarget, kind: DrillableKind): ResourceItem[];
+/** Recursive size + file count of a path; symlinks are not followed. */
+export declare function pathSize(p: string): {
+    bytes: number;
+    files: number;
+};
+/** Human byte size: "84 KB", "3.1 MB". */
+export declare function formatBytes(n: number): string;
+export interface ManifestSummary {
+    /** `run.<agent>.strategy` pairs from agents.yaml. */
+    strategies: Array<{
+        agent: string;
+        strategy: string;
+    }>;
+    /** `agents.<agent>` version pins from agents.yaml, when present. */
+    versions: Array<{
+        agent: string;
+        version: string;
+    }>;
+}
+/** Parse the repo's own agents.yaml into the version pins + run strategies it declares. */
+export declare function repoManifestSummary(root: string): ManifestSummary | null;
+export interface RepoGitInfo {
+    branch: string;
+    dirty: number;
+    dirtyFiles: string[];
+    url: string | null;
+    lastCommit: {
+        sha: string;
+        subject: string;
+        relative: string;
+    } | null;
+    ahead: number | null;
+    behind: number | null;
+}
+export declare function repoGitInfo(root: string): RepoGitInfo | null;
 export {};

package/dist/commands/inspect.js

@@ -23,7 +23,7 @@ import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, ge
 import { getVersionHomePath } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
-import { discoverPlugins } from '../lib/plugins.js';
+import { discoverPlugins, discoverPluginsInDir } from '../lib/plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
 /** Resource kinds the inspect command can drill into. */
@@ -161,18 +161,23 @@ export function resolveRepoTarget(target, cwd) {
     const stat = safeStat(abs);
     if (!stat || !stat.isDirectory())
         return null;
-    // A dir that is itself a DotAgents root wins over its nested .agents/ —
-    // extra repos like ~/.agents-extras keep resources at the top level and use
-    // .agents/ only for worktrees.
+    // A dir literally named `.agents` is the root itself.
+    if (path.basename(abs) === '.agents') {
+        return { label: path.basename(path.dirname(abs)), root: abs };
+    }
+    // A nested `.agents/` that is a populated DotAgents root wins over `abs` — the
+    // project case (`agents inspect .` from a repo root whose resources live under
+    // `.agents/`, while the repo's own top-level `skills/`, `agents.yaml` pin, etc.
+    // are unrelated source, not a DotAgents tree).
+    const nested = path.join(abs, '.agents');
+    if (isDotAgentsRoot(nested)) {
+        return { label: path.basename(abs), root: nested };
+    }
+    // Otherwise treat `abs` itself as the root: standalone clones and extra repos
+    // like ~/.agents-extras keep resources at the top level and use `.agents/`
+    // only for worktrees (so their nested `.agents/` is not a DotAgents root).
     if (isDotAgentsRoot(abs)) {
-        const label = path.basename(abs) === '.agents' ? path.basename(path.dirname(abs)) : path.basename(abs);
-        return { label, root: abs };
-    }
-    if (path.basename(abs) !== '.agents') {
-        const nested = path.join(abs, '.agents');
-        if (safeStat(nested)?.isDirectory()) {
-            return { label: path.basename(abs), root: nested };
-        }
+        return { label: path.basename(abs), root: abs };
     }
     return null;
 }
@@ -204,6 +209,14 @@ async function inspectRepo(repo, options) {
 }
 /** List one resource kind from a single repo root — no layering, no overrides. */
 export function collectRepoKind(repo, kind) {
+    // Plugins are bundles with a manifest + nested skills/commands/hooks — read
+    // them through the plugin discoverer so the manifest description and bundled
+    // resources surface, rather than treating each as an opaque directory.
+    if (kind === 'plugins') {
+        return discoverPluginsInDir(path.join(repo.root, 'plugins'))
+            .map(p => pluginToItem(p, repo.label))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
     const dir = path.join(repo.root, kind);
     let entries;
     try {
@@ -216,6 +229,9 @@ export function collectRepoKind(repo, kind) {
     for (const entry of entries) {
         if (entry.name.startsWith('.'))
             continue;
+        // Build/tooling caches are never resources — they only inflate counts.
+        if (entry.name === '__pycache__' || entry.name === 'node_modules')
+            continue;
         const p = path.join(dir, entry.name);
         items.push({
             name: entry.name.replace(/\.(md|yaml|yml|toml|json)$/, ''),
@@ -227,14 +243,100 @@ export function collectRepoKind(repo, kind) {
     }
     return items.sort((a, b) => a.name.localeCompare(b.name));
 }
+/** A few resource names for the at-a-glance preview, with a `…(+N)` tail. */
+function previewNames(items, n) {
+    if (items.length === 0)
+        return '';
+    const shown = items.slice(0, n).map(i => i.name);
+    const extra = items.length - shown.length;
+    return shown.join(', ') + (extra > 0 ? ` …(+${extra})` : '');
+}
+/** Recursive size + file count of a path; symlinks are not followed. */
+export function pathSize(p) {
+    let stat;
+    try {
+        stat = fs.lstatSync(p);
+    }
+    catch {
+        return { bytes: 0, files: 0 };
+    }
+    if (stat.isSymbolicLink())
+        return { bytes: 0, files: 0 };
+    if (stat.isFile())
+        return { bytes: stat.size, files: 1 };
+    if (!stat.isDirectory())
+        return { bytes: 0, files: 0 };
+    let entries;
+    try {
+        entries = fs.readdirSync(p, { withFileTypes: true });
+    }
+    catch {
+        return { bytes: 0, files: 0 };
+    }
+    let bytes = 0, files = 0;
+    for (const e of entries) {
+        const sub = pathSize(path.join(p, e.name));
+        bytes += sub.bytes;
+        files += sub.files;
+    }
+    return { bytes, files };
+}
+/** Human byte size: "84 KB", "3.1 MB". */
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let v = n / 1024, i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v >= 10 ? Math.round(v) : v.toFixed(1)} ${units[i]}`;
+}
+/** Parse the repo's own agents.yaml into the version pins + run strategies it declares. */
+export function repoManifestSummary(root) {
+    let parsed;
+    try {
+        parsed = yaml.parse(fs.readFileSync(path.join(root, 'agents.yaml'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const strategies = [];
+    if (obj.run && typeof obj.run === 'object') {
+        for (const [agent, cfg] of Object.entries(obj.run)) {
+            const strategy = cfg && typeof cfg === 'object' ? cfg.strategy : undefined;
+            if (typeof strategy === 'string')
+                strategies.push({ agent, strategy });
+        }
+    }
+    const versions = [];
+    if (obj.agents && typeof obj.agents === 'object') {
+        for (const [agent, ver] of Object.entries(obj.agents)) {
+            if (typeof ver === 'string')
+                versions.push({ agent, version: ver });
+        }
+    }
+    if (strategies.length === 0 && versions.length === 0)
+        return null;
+    return { strategies, versions };
+}
 function renderRepoSummary(repo, options) {
     const git = repoGitInfo(repo.root);
     const manifests = REPO_MARKER_FILES.filter(m => fs.existsSync(path.join(repo.root, m)));
-    const counts = {};
+    const manifest = repoManifestSummary(repo.root);
+    const kindData = {};
+    let totalBytes = 0, totalFiles = 0;
     if (!options.brief) {
         for (const kind of DRILLABLE_KINDS) {
             const items = collectRepoKind(repo, kind);
-            counts[kind] = { total: items.length, bySource: { [repo.label]: items.length } };
+            const size = pathSize(path.join(repo.root, kind));
+            kindData[kind] = { items, size };
+            totalBytes += size.bytes;
+            totalFiles += size.files;
         }
     }
     if (options.json) {
@@ -243,32 +345,65 @@ function renderRepoSummary(repo, options) {
             root: repo.root,
             git,
             manifests,
-            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, counts[kind].total])),
+            manifest,
+            size: options.brief ? null : { bytes: totalBytes, files: totalFiles },
+            resources: options.brief ? null : Object.fromEntries(DRILLABLE_KINDS.map(kind => [kind, {
+                    count: kindData[kind].items.length,
+                    bytes: kindData[kind].size.bytes,
+                    files: kindData[kind].size.files,
+                    names: kindData[kind].items.map(i => i.name),
+                }])),
         }, null, 2));
         return;
     }
     console.log('\n' + chalk.bold(repo.label) + '  ' + chalk.gray('[dotagents repo]') + '\n');
-    const rows = [['root', termLink(repo.root, repo.root)]];
+    // Indent for continuation sub-rows: 2 leading + 10 key column + 1 space.
+    const sub = (label, value) => console.log(`  ${''.padEnd(10)} ${chalk.gray(label.padEnd(8))} ${value}`);
+    console.log(`  ${'root'.padEnd(10)} ${termLink(repo.root, repo.root)}`);
     if (git) {
         const dirty = git.dirty > 0 ? ` ${chalk.gray('·')} ${chalk.yellow(`${git.dirty} dirty`)}` : '';
         const url = git.url ? ` ${chalk.gray('·')} ${chalk.gray(git.url)}` : '';
-        rows.push(['git', `${git.branch}${dirty}${url}`]);
+        console.log(`  ${'git'.padEnd(10)} ${git.branch}${dirty}${url}`);
+        if (git.lastCommit) {
+            const rel = git.lastCommit.relative ? `  ${chalk.gray(`(${git.lastCommit.relative})`)}` : '';
+            sub('last', `${chalk.cyan(git.lastCommit.sha)}  ${truncate(git.lastCommit.subject, 60)}${rel}`);
+        }
+        if (git.ahead !== null && git.behind !== null && (git.ahead > 0 || git.behind > 0)) {
+            sub('sync', `ahead ${git.ahead} ${chalk.gray('·')} behind ${git.behind}`);
+        }
+        if (git.dirtyFiles.length > 0) {
+            const shown = git.dirtyFiles.slice(0, 4).join(', ');
+            const extra = git.dirtyFiles.length - Math.min(4, git.dirtyFiles.length);
+            sub('dirty', chalk.yellow(shown + (extra > 0 ? ` …(+${extra})` : '')));
+        }
+    }
+    if (manifests.length > 0) {
+        console.log(`  ${'manifests'.padEnd(10)} ${manifests.join(', ')}`);
+        if (manifest) {
+            if (manifest.versions.length > 0) {
+                sub('versions', manifest.versions.map(v => `${v.agent} ${chalk.cyan(v.version)}`).join(chalk.gray(' · ')));
+            }
+            if (manifest.strategies.length > 0) {
+                sub('run', manifest.strategies.map(s => `${s.agent}:${s.strategy}`).join(chalk.gray(' · ')));
+            }
+        }
     }
-    if (manifests.length > 0)
-        rows.push(['manifests', manifests.join(', ')]);
-    for (const [k, v] of rows)
-        console.log(`  ${k.padEnd(10)} ${v}`);
     if (!options.brief) {
+        console.log(`  ${'size'.padEnd(10)} ${formatBytes(totalBytes)} ${chalk.gray('·')} ${totalFiles} files`);
         console.log('\n' + chalk.bold('Resources'));
         for (const kind of DRILLABLE_KINDS) {
-            console.log(`  ${kind.padEnd(10)} ${String(counts[kind].total).padStart(4)}`);
+            const { items, size } = kindData[kind];
+            const count = String(items.length).padStart(4);
+            const sz = items.length > 0 ? formatBytes(size.bytes).padStart(8) : ''.padEnd(8);
+            const preview = items.length > 0 ? chalk.gray(truncate(previewNames(items, 4), 60)) : '';
+            console.log(`  ${kind.padEnd(10)} ${count}  ${sz}  ${preview}`.trimEnd());
         }
     }
     console.log('');
     console.log(chalk.gray(`Drill in:   agents inspect ${repo.label} --skills <query>`));
     console.log('');
 }
-function repoGitInfo(root) {
+export function repoGitInfo(root) {
     const git = (args) => {
         try {
             return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
@@ -281,9 +416,33 @@ function repoGitInfo(root) {
     const branch = git('rev-parse --abbrev-ref HEAD');
     if (branch === null)
         return null;
-    const status = git('status --porcelain');
-    const dirty = status ? status.split('\n').filter(Boolean).length : 0;
-    return { branch, dirty, url: git('remote get-url origin') };
+    // Read status WITHOUT trimming — git()'s .trim() would strip the leading
+    // space of the first porcelain line (`XY path`), corrupting the path slice.
+    let statusRaw;
+    try {
+        statusRaw = execSync(`git -C ${JSON.stringify(root)} status --porcelain`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    }
+    catch {
+        statusRaw = null;
+    }
+    const dirtyFiles = statusRaw ? statusRaw.split('\n').filter(Boolean).map(l => l.slice(3)) : [];
+    let lastCommit = null;
+    const log = git('log -1 --format=%h%x1f%s%x1f%cr');
+    if (log) {
+        const [sha, subject, relative] = log.split('\x1f');
+        if (sha)
+            lastCommit = { sha, subject: subject ?? '', relative: relative ?? '' };
+    }
+    let ahead = null, behind = null;
+    const counts = git("rev-list --left-right --count '@{upstream}...HEAD'");
+    if (counts) {
+        const [b, a] = counts.split(/\s+/).map(n => parseInt(n, 10));
+        if (Number.isFinite(b) && Number.isFinite(a)) {
+            behind = b;
+            ahead = a;
+        }
+    }
+    return { branch, dirty: dirtyFiles.length, dirtyFiles, url: git('remote get-url origin'), lastCommit, ahead, behind };
 }
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {
@@ -486,14 +645,35 @@ function collectKind(agent, versionHome, kind) {
     }
 }
 function pluginItems() {
-    const plugins = discoverPlugins();
-    return plugins.map(p => ({
-        name: p.name,
-        source: 'user',
-        path: p.root,
-        linkTarget: linkTarget(p.root),
-        description: p.manifest.description ?? '',
-    }));
+    return discoverPlugins().map(p => pluginToItem(p, 'user'));
+}
+/**
+ * Map a discovered plugin to a resource item, surfacing the manifest description
+ * and the bundle's nested resources (skills, commands, hooks, ...) as detail rows.
+ */
+function pluginToItem(plugin, source) {
+    const extra = [];
+    const list = (names) => names.length <= 8 ? names.join(', ') : `${names.slice(0, 8).join(', ')}, +${names.length - 8} more`;
+    if (plugin.skills.length)
+        extra.push(['skills', `${plugin.skills.length}  (${list(plugin.skills)})`]);
+    if (plugin.commands.length)
+        extra.push(['commands', `${plugin.commands.length}  (${list(plugin.commands)})`]);
+    if (plugin.agentDefs.length)
+        extra.push(['subagents', `${plugin.agentDefs.length}  (${list(plugin.agentDefs)})`]);
+    if (plugin.hooks.length)
+        extra.push(['hooks', String(plugin.hooks.length)]);
+    if (plugin.mcpServers.length)
+        extra.push(['mcp', list(plugin.mcpServers)]);
+    if (plugin.manifest.version)
+        extra.push(['version', plugin.manifest.version]);
+    return {
+        name: plugin.name,
+        source,
+        path: plugin.root,
+        linkTarget: linkTarget(plugin.root),
+        description: plugin.manifest.description ?? '',
+        extra,
+    };
 }
 function entriesFromAgentResources(agent, versionHome, kind) {
     const res = getAgentResources(agent, { home: versionHome });
@@ -562,6 +742,10 @@ function buildDetailRows(item, kind) {
                 rows.push(['tools', fm.tools.join(', ')]);
         }
     }
+    // Plugin bundles carry their nested resources as pre-built rows.
+    if (kind === 'plugins' && item.extra) {
+        rows.push(...item.extra);
+    }
     return rows;
 }
 function findMatches(items, query) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.9",
+  "version": "1.20.11",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",