@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/commands/inspect.js

@@ -0,0 +1,590 @@
+/**
+ * `agents inspect <agent>[@version]` — single-agent, single-version detail view.
+ *
+ * Summary mode shows the per-version header (paths, shim, capabilities, resource
+ * counts, sessions). Drill-down flags (`--skills`, `--hooks`, `--mcp`, ...) list
+ * one resource kind; passing a positional query to the same flag fuzzy-searches
+ * for a single resource and prints its detail. Resource names render as OSC-8
+ * hyperlinks to the marker file (SKILL.md / WORKFLOW.md / AGENT.md / the file
+ * itself) so users can click straight to the source.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import chalk from 'chalk';
+import * as yaml from 'yaml';
+import { AGENTS, getCliState } from '../lib/agents.js';
+import { supports } from '../lib/capabilities.js';
+import { readMeta } from '../lib/state.js';
+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 { countSessionsInScope } from '../lib/session/discover.js';
+import { damerauLevenshtein } from '../lib/fuzzy.js';
+/** Resource kinds the inspect command can drill into. */
+const DRILLABLE_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'mcp',
+    'rules',
+    'plugins',
+    'workflows',
+    'subagents',
+];
+const CAPABILITY_NAMES = [
+    'hooks', 'mcp', 'skills', 'commands', 'subagents', 'plugins', 'workflows', 'rules', 'allowlist',
+];
+// ─── Command registration ────────────────────────────────────────────────────
+export function registerInspectCommand(program) {
+    const cmd = program
+        .command('inspect <agent>')
+        .description('Inspect one installed agent at one version — paths, capabilities, resources, drill into any kind.')
+        .option('--brief', 'header + capabilities only; skip resources/sessions')
+        .option('--json', 'machine-readable JSON output');
+    for (const kind of DRILLABLE_KINDS) {
+        cmd.option(`--${kind} [query]`, `list ${kind}; pass a name (fuzzy) to show detail`);
+    }
+    cmd.action(async (target, options) => {
+        await inspectAction(target, options);
+    });
+}
+// ─── Main dispatcher ─────────────────────────────────────────────────────────
+export async function inspectAction(target, options) {
+    const { agent, version } = parseTarget(target);
+    const versionHome = getVersionHomePath(agent, version);
+    if (!fs.existsSync(versionHome)) {
+        console.error(chalk.red(`${agent}@${version} is not installed.`));
+        console.error(chalk.gray(`Run 'agents add ${agent}@${version}' first.`));
+        process.exitCode = 1;
+        return;
+    }
+    const drill = pickDrillKind(options);
+    if (drill) {
+        const { kind, query } = drill;
+        if (query === true || query === undefined) {
+            await renderList(agent, version, versionHome, kind, options);
+        }
+        else {
+            await renderDetail(agent, version, versionHome, kind, String(query), options);
+        }
+        return;
+    }
+    await renderSummary(agent, version, versionHome, options);
+}
+function parseTarget(target) {
+    const [rawAgent, rawVersion] = target.split('@');
+    const agentKey = (rawAgent || '').toLowerCase();
+    if (!(agentKey in AGENTS)) {
+        console.error(chalk.red(`Unknown agent: ${rawAgent}`));
+        console.error(chalk.gray(`Known agents: ${Object.keys(AGENTS).join(', ')}`));
+        process.exit(1);
+    }
+    const agent = agentKey;
+    let version = rawVersion;
+    if (!version || version === 'default') {
+        const meta = readMeta();
+        const def = meta.agents?.[agent];
+        if (!def) {
+            console.error(chalk.red(`No default version set for ${agent}.`));
+            console.error(chalk.gray(`Pass a version: agents inspect ${agent}@<version>`));
+            process.exit(1);
+        }
+        version = def;
+    }
+    return { agent, version };
+}
+function pickDrillKind(options) {
+    const active = [];
+    for (const kind of DRILLABLE_KINDS) {
+        const value = options[kind];
+        if (value !== undefined)
+            active.push({ kind, query: value });
+    }
+    if (active.length === 0)
+        return null;
+    if (active.length > 1) {
+        console.error(chalk.red(`Pick at most one drill-down flag. Got: ${active.map(a => '--' + a.kind).join(', ')}`));
+        process.exit(1);
+    }
+    return active[0];
+}
+// ─── Summary mode ────────────────────────────────────────────────────────────
+async function renderSummary(agent, version, versionHome, options) {
+    const meta = readMeta();
+    const isDefault = meta.agents?.[agent] === version;
+    const strategy = meta.run?.[agent]?.strategy ?? 'pinned';
+    const cliState = await getCliState(agent).catch(() => null);
+    const configSymlink = path.join(os.homedir(), `.${agent}`);
+    const configTarget = readSymlinkSafe(configSymlink);
+    const shimPath = path.join(getShimsDir(), AGENTS[agent].cliCommand);
+    const aliasPath = getVersionedAliasPath(agent, version);
+    const capabilities = collectCapabilities(agent, version);
+    const counts = options.brief ? null : collectCounts(agent, versionHome);
+    const sessions = options.brief ? null : {
+        total: safeCountSessions(agent),
+    };
+    if (options.json) {
+        const json = {
+            agent,
+            version,
+            default: isDefault,
+            home: versionHome,
+            configSymlink: configTarget ? { from: configSymlink, to: configTarget } : null,
+            shim: shimPath,
+            alias: aliasPath,
+            strategy,
+            installedShim: cliState?.installed === true ? cliState.path : null,
+            capabilities,
+            resources: counts,
+            sessions,
+        };
+        console.log(JSON.stringify(json, null, 2));
+        return;
+    }
+    // Plain text
+    const head = `${chalk.bold(agent)} ${chalk.gray('@')} ${chalk.cyan(version)}${isDefault ? '  ' + chalk.green('[default]') : ''}`;
+    console.log('\n' + head + '\n');
+    const rows = [
+        ['install', versionHome],
+        ['config', configTarget ? `${configSymlink}  ${chalk.gray('→')}  ${configTarget}` : chalk.gray('(no symlink)')],
+        ['shim', shimPath],
+        ['alias', aliasPath],
+        ['strategy', strategy],
+    ];
+    for (const [k, v] of rows)
+        console.log(`  ${k.padEnd(10)} ${v}`);
+    console.log('\n' + chalk.bold('Capabilities'));
+    for (const cap of CAPABILITY_NAMES) {
+        const res = capabilities[cap];
+        const mark = res.ok ? chalk.green('✓') : chalk.red('✗');
+        const reason = res.ok ? '' : chalk.gray(`(${res.reason}${res.need ? ' ' + res.need : ''})`);
+        console.log(`  ${cap.padEnd(10)} ${mark} ${reason}`);
+    }
+    if (counts) {
+        console.log('\n' + chalk.bold('Resources'));
+        for (const kind of DRILLABLE_KINDS) {
+            const c = counts[kind];
+            if (!c)
+                continue;
+            const breakdown = formatScopeBreakdown(c.bySource);
+            console.log(`  ${kind.padEnd(10)} ${String(c.total).padStart(4)}   ${chalk.gray(breakdown)}`);
+        }
+    }
+    if (sessions) {
+        console.log('\n' + chalk.bold('Sessions'));
+        console.log(`  ${'total'.padEnd(10)} ${sessions.total}   ${chalk.gray('(across all versions)')}`);
+    }
+    console.log('');
+    console.log(chalk.gray(`Drill in:   agents inspect ${agent}@${version} --skills <query>`));
+    console.log(chalk.gray(`Diagnose:   agents doctor ${agent}@${version}`));
+    console.log('');
+}
+// ─── List mode ───────────────────────────────────────────────────────────────
+async function renderList(agent, version, versionHome, kind, options) {
+    const items = collectKind(agent, versionHome, kind);
+    if (options.json) {
+        console.log(JSON.stringify({
+            agent,
+            version,
+            kind,
+            count: items.length,
+            items: items.map(i => ({ name: i.name, source: i.source, path: i.path, description: i.description })),
+        }, null, 2));
+        return;
+    }
+    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} (${items.length})`) + '\n');
+    if (items.length === 0) {
+        console.log(chalk.gray(`  (none installed)`));
+        console.log('');
+        return;
+    }
+    for (const item of items) {
+        const tag = chalk.gray(`[${item.source}]`.padEnd(10));
+        console.log(`  ${tag} ${termLink(chalk.cyan(item.name), item.linkTarget)}`);
+        if (item.description) {
+            console.log(`             ${chalk.gray(truncate(item.description, 90))}`);
+        }
+    }
+    console.log('');
+}
+// ─── Detail mode (fuzzy) ─────────────────────────────────────────────────────
+async function renderDetail(agent, version, versionHome, kind, query, options) {
+    const items = collectKind(agent, versionHome, kind);
+    const matches = findMatches(items, query);
+    if (matches.length === 0) {
+        const suggestions = suggestClosest(items, query, 3);
+        if (options.json) {
+            console.log(JSON.stringify({ agent, version, kind, query, match: null, suggestions: suggestions.map(s => s.name) }, null, 2));
+        }
+        else {
+            console.error(chalk.red(`No ${kind} matching '${query}'.`));
+            if (suggestions.length > 0) {
+                console.error(chalk.gray(`Closest: ${suggestions.map(s => s.name).join(', ')}`));
+            }
+        }
+        process.exit(1);
+    }
+    const best = matches[0];
+    const others = matches.slice(1, 4);
+    if (options.json) {
+        const detail = buildDetail(best.item, kind);
+        console.log(JSON.stringify({
+            agent,
+            version,
+            kind,
+            query,
+            match: { ...detail, matchKind: best.matchKind },
+            others: others.map(o => ({ name: o.item.name, source: o.item.source, path: o.item.path, matchKind: o.matchKind })),
+        }, null, 2));
+        return;
+    }
+    console.log('\n' + chalk.bold(`${agent}@${version}`) + '  ' + chalk.gray(`${kind} matching "${query}"`) + '\n');
+    const matchTag = best.matchKind === 'exact' ? 'exact' : best.matchKind === 'substring' ? 'substring' : `~${best.distance}`;
+    console.log(`  ${chalk.green('✓')}  ${termLink(chalk.bold.cyan(best.item.name), best.item.linkTarget)}  ${chalk.gray(`[${matchTag}, ${best.item.source}]`)}`);
+    if (best.item.description) {
+        console.log(`     ${chalk.gray(truncate(best.item.description, 100))}`);
+    }
+    for (const [k, v] of buildDetailRows(best.item, kind)) {
+        console.log(`     ${chalk.gray(k.padEnd(10))} ${v}`);
+    }
+    if (others.length > 0) {
+        console.log('\n' + chalk.gray('Other matches:'));
+        for (const m of others) {
+            const tag = m.matchKind === 'substring' ? 'substring' : `~${m.distance}`;
+            console.log(`  ${termLink(chalk.cyan(m.item.name), m.item.linkTarget)}  ${chalk.gray(`(${tag}) [${m.item.source}]`)}`);
+        }
+    }
+    console.log('');
+}
+// ─── Data collection ─────────────────────────────────────────────────────────
+function collectCapabilities(agent, version) {
+    const out = {};
+    for (const cap of CAPABILITY_NAMES) {
+        const res = supports(agent, cap, version);
+        if (res.ok) {
+            out[cap] = { ok: true };
+        }
+        else {
+            out[cap] = { ok: false, reason: res.reason, need: res.need };
+        }
+    }
+    return out;
+}
+function collectCounts(agent, versionHome) {
+    const out = {};
+    for (const kind of DRILLABLE_KINDS) {
+        const items = collectKind(agent, versionHome, kind);
+        const bySource = {};
+        for (const item of items)
+            bySource[item.source] = (bySource[item.source] || 0) + 1;
+        out[kind] = { total: items.length, bySource };
+    }
+    return out;
+}
+function collectKind(agent, versionHome, kind) {
+    switch (kind) {
+        case 'commands':
+        case 'hooks':
+        case 'workflows':
+            return entriesFromAgentResources(agent, versionHome, kind);
+        case 'skills':
+            return skillsFromAgentResources(agent, versionHome);
+        case 'mcp':
+            return mcpItems(agent, versionHome);
+        case 'rules':
+        case 'subagents':
+            return listResources(kind).map(r => ({
+                name: r.name,
+                source: r.source,
+                path: r.path,
+                linkTarget: linkTarget(r.path),
+                description: readDescription(r.path),
+            }));
+        case 'plugins':
+            return pluginItems();
+    }
+}
+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 ?? '',
+    }));
+}
+function entriesFromAgentResources(agent, versionHome, kind) {
+    const res = getAgentResources(agent, { home: versionHome });
+    const list = res[kind];
+    return list.map(e => ({
+        name: e.name,
+        source: e.scope,
+        path: e.path,
+        linkTarget: linkTarget(e.path),
+        description: readDescription(e.path),
+    }));
+}
+function skillsFromAgentResources(agent, versionHome) {
+    const res = getAgentResources(agent, { home: versionHome });
+    return res.skills.map(s => ({
+        name: s.name,
+        source: s.scope,
+        path: s.path,
+        linkTarget: linkTarget(s.path),
+        description: readDescription(s.path),
+    }));
+}
+function mcpItems(agent, versionHome) {
+    const res = getAgentResources(agent, { home: versionHome });
+    return res.mcp.map(m => ({
+        name: m.name,
+        source: m.scope,
+        path: '',
+        linkTarget: '',
+        description: m.version ? `version ${m.version}` : '',
+    }));
+}
+// ─── Detail field builders ───────────────────────────────────────────────────
+function buildDetail(item, kind) {
+    const rows = buildDetailRows(item, kind);
+    const out = {
+        name: item.name,
+        source: item.source,
+        path: item.path,
+        description: item.description,
+    };
+    for (const [k, v] of rows)
+        out[k] = v;
+    return out;
+}
+function buildDetailRows(item, kind) {
+    const rows = [];
+    if (item.path && kind !== 'mcp') {
+        const stat = safeStat(item.path);
+        if (stat)
+            rows.push(['size', stat.isDirectory() ? '(bundle)' : `${stat.size} bytes`]);
+    }
+    // Kind-specific fields
+    if (kind === 'skills' || kind === 'commands' || kind === 'subagents') {
+        const fm = readFrontmatter(item.path);
+        if (fm) {
+            // description was already printed by caller; skip if redundant
+            if (typeof fm.description === 'string' && fm.description.trim() !== item.description.trim()) {
+                rows.push(['description', truncate(fm.description, 120)]);
+            }
+            if (Array.isArray(fm.triggers))
+                rows.push(['triggers', fm.triggers.join(', ')]);
+            if (typeof fm.model === 'string')
+                rows.push(['model', fm.model]);
+            if (Array.isArray(fm.tools))
+                rows.push(['tools', fm.tools.join(', ')]);
+        }
+    }
+    return rows;
+}
+function findMatches(items, query) {
+    const q = query.toLowerCase();
+    const out = [];
+    for (const item of items) {
+        const name = item.name.toLowerCase();
+        if (name === q) {
+            out.push({ item, matchKind: 'exact', distance: 0 });
+        }
+        else if (name.includes(q)) {
+            out.push({ item, matchKind: 'substring', distance: name.length - q.length });
+        }
+    }
+    if (out.length > 0) {
+        out.sort((a, b) => rankMatch(a) - rankMatch(b));
+        return out;
+    }
+    // No substring hits — fall back to edit distance.
+    const threshold = Math.max(2, Math.floor(q.length * 0.3));
+    for (const item of items) {
+        const d = damerauLevenshtein(q, item.name.toLowerCase());
+        if (d <= threshold)
+            out.push({ item, matchKind: 'fuzzy', distance: d });
+    }
+    out.sort((a, b) => a.distance - b.distance);
+    return out;
+}
+function rankMatch(m) {
+    if (m.matchKind === 'exact')
+        return 0;
+    if (m.matchKind === 'substring')
+        return 100 + m.distance;
+    return 1000 + m.distance;
+}
+function suggestClosest(items, query, n) {
+    const q = query.toLowerCase();
+    const scored = items.map(item => ({ item, d: damerauLevenshtein(q, item.name.toLowerCase()) }));
+    scored.sort((a, b) => a.d - b.d);
+    return scored.slice(0, n).map(s => s.item);
+}
+// ─── Frontmatter + description helpers ───────────────────────────────────────
+function readDescription(p) {
+    if (!p)
+        return '';
+    let filePath = p;
+    try {
+        if (fs.statSync(p).isDirectory()) {
+            for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md', 'README.md']) {
+                const c = path.join(p, marker);
+                if (fs.existsSync(c)) {
+                    filePath = c;
+                    break;
+                }
+            }
+        }
+    }
+    catch {
+        return '';
+    }
+    const fm = readFrontmatter(filePath);
+    if (fm && typeof fm.description === 'string' && fm.description.trim().length > 0) {
+        return fm.description.trim();
+    }
+    return readFirstProseLine(filePath);
+}
+function readFrontmatter(p) {
+    if (!p)
+        return null;
+    let filePath = p;
+    try {
+        if (fs.statSync(p).isDirectory()) {
+            for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md']) {
+                const c = path.join(p, marker);
+                if (fs.existsSync(c)) {
+                    filePath = c;
+                    break;
+                }
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    if (!filePath.endsWith('.md'))
+        return null;
+    let head = '';
+    try {
+        const fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(4096);
+        const n = fs.readSync(fd, buf, 0, 4096, 0);
+        fs.closeSync(fd);
+        head = buf.subarray(0, n).toString('utf-8');
+    }
+    catch {
+        return null;
+    }
+    if (!head.startsWith('---'))
+        return null;
+    const end = head.indexOf('\n---', 3);
+    if (end === -1)
+        return null;
+    const body = head.slice(3, end).trim();
+    try {
+        const parsed = yaml.parse(body);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readFirstProseLine(p) {
+    try {
+        const stat = fs.statSync(p);
+        if (stat.isDirectory())
+            return '';
+        if (stat.size > 64 * 1024)
+            return '';
+        const text = fs.readFileSync(p, 'utf-8');
+        // Skip frontmatter
+        let body = text;
+        if (body.startsWith('---')) {
+            const end = body.indexOf('\n---', 3);
+            if (end !== -1)
+                body = body.slice(end + 4);
+        }
+        for (const raw of body.split('\n')) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            if (line.startsWith('#'))
+                return line.replace(/^#+\s*/, '');
+            return line;
+        }
+    }
+    catch { /* ignore */ }
+    return '';
+}
+// ─── OSC-8 + path helpers ────────────────────────────────────────────────────
+function termLink(text, filePath) {
+    if (!filePath)
+        return text;
+    const url = `file://${filePath}`;
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
+function linkTarget(p) {
+    if (!p)
+        return '';
+    try {
+        if (!fs.statSync(p).isDirectory())
+            return p;
+    }
+    catch {
+        return p;
+    }
+    for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md']) {
+        const c = path.join(p, marker);
+        if (fs.existsSync(c))
+            return c;
+    }
+    return p;
+}
+function readSymlinkSafe(p) {
+    try {
+        const stat = fs.lstatSync(p);
+        if (!stat.isSymbolicLink())
+            return null;
+        return fs.readlinkSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+function safeStat(p) {
+    try {
+        return fs.statSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+const SESSION_AGENTS = new Set([
+    'claude', 'codex', 'gemini', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi',
+]);
+function safeCountSessions(agent) {
+    if (!SESSION_AGENTS.has(agent))
+        return 0;
+    try {
+        return countSessionsInScope({ agent: agent });
+    }
+    catch {
+        return 0;
+    }
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n - 1) + '…';
+}
+function formatScopeBreakdown(bySource) {
+    const entries = Object.entries(bySource);
+    if (entries.length === 0)
+        return '';
+    return '[' + entries.map(([k, v]) => `${k}:${v}`).join(' ') + ']';
+}