@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/commands/repo.js

@@ -0,0 +1,570 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import simpleGit from 'simple-git';
+import { confirm, input } from '@inquirer/prompts';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+const HOME = os.homedir();
+/**
+ * Resolve a target argument to an absolute path.
+ * - No arg: ~/.agents/
+ * - Looks like a path (starts with /, ~, .): resolve as path
+ * - Otherwise: ~/.agents-{name}/
+ */
+function resolveRepoPath(target) {
+    if (!target)
+        return path.join(HOME, '.agents');
+    const trimmed = target.trim();
+    if (trimmed.startsWith('/') || trimmed.startsWith('~') || trimmed.startsWith('.')) {
+        return path.resolve(trimmed.replace(/^~/, HOME));
+    }
+    return path.join(HOME, `.agents-${trimmed}`);
+}
+import { ensureAgentsDir, getExtraRepoDir, getSystemAgentsDir, getUserAgentsDir, readMeta, resolveExtraRepoDir, updateMeta, } from '../lib/state.js';
+import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin } from '../lib/git.js';
+import { DEFAULT_SYSTEM_REPO } from '../lib/types.js';
+const ALIAS_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+/** Derive a default alias from a source URL (e.g. gh:foo/.agents-work -> agents-work). */
+function deriveAlias(source) {
+    const parsed = parseSource(source);
+    let base;
+    if (parsed.type === 'local') {
+        base = path.basename(parsed.url);
+    }
+    else {
+        const match = parsed.url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+        base = match ? match[2] : parsed.url;
+    }
+    // Strip leading dots and any "agents-" prefix so the alias is short and
+    // becomes ~/.agents-<alias>/ on disk (e.g. ".agents-work" -> "work").
+    return base.replace(/^\.+/, '').replace(/^agents-/, '') || 'repo';
+}
+/** Get the last commit short hash for a repo, or null if unavailable. */
+async function getShortCommit(repoDir) {
+    try {
+        const git = simpleGit(repoDir);
+        const log = await git.log({ maxCount: 1 });
+        return log.latest?.hash.slice(0, 8) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Register the `agents repo` command tree. */
+export function registerRepoCommands(program) {
+    const repoCmd = program
+        .command('repo')
+        .description('Manage extra DotAgent repos alongside ~/.agents/ (for private or team skills)')
+        .addHelpText('after', `
+Managed extras live at ~/.agents-<alias>/ as peer dirs to ~/.agents/. User-owned
+repos can also live anywhere and be registered by path. Their skills, commands,
+and hooks merge into agent version homes after the user repo's — so ~/.agents/
+wins on name collisions.
+
+Examples:
+  # Scaffold your own editable repo (default: ~/.agents/)
+  agents repo init
+
+  # Scaffold a named repo (creates ~/.agents-work/)
+  agents repo init work
+
+  # Scaffold at a custom path
+  agents repo init ~/my-agents
+
+  # Add a private repo for work-only skills
+  agents repo add gh:yourname/.agents-work
+
+  # Add with a custom alias
+  agents repo add git@github.com:acme/team-skills.git --as acme
+
+  # Show all registered repos
+  agents repo list
+
+  # Temporarily disable without deleting
+  agents repo disable acme
+
+  # Unregister it
+  agents repo remove acme
+`);
+    repoCmd
+        .command('init [target]')
+        .description('Create a user-owned repo from a template and register it as an extra')
+        .option('--from <source>', 'Template repo to clone from', DEFAULT_SYSTEM_REPO)
+        .option('--as <alias>', 'Alias to register under (defaults to the directory name)')
+        .action(async (target, options) => {
+        let targetDir = resolveRepoPath(target);
+        if (!target && fs.existsSync(targetDir)) {
+            if (!isInteractiveTerminal()) {
+                console.log(chalk.red(`Path already exists: ${targetDir}`));
+                console.log(chalk.gray('Pass a name (e.g. `agents repo init work` -> ~/.agents-work) or a path.'));
+                process.exitCode = 1;
+                return;
+            }
+            try {
+                const name = await input({
+                    message: 'Name for your repo:',
+                    default: 'work',
+                    validate: (raw) => {
+                        const v = raw.trim();
+                        if (!v)
+                            return 'Required';
+                        if (!ALIAS_PATTERN.test(v))
+                            return 'Letters, digits, "_" or "-"; must start with letter/digit';
+                        const candidate = path.join(HOME, `.agents-${v}`);
+                        if (fs.existsSync(candidate))
+                            return `~/.agents-${v} already exists`;
+                        return true;
+                    },
+                    theme: { prefix: chalk.gray('Will be created at $HOME/.agents-<name>/') },
+                });
+                targetDir = path.join(HOME, `.agents-${name.trim()}`);
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    process.exit(130);
+                }
+                throw err;
+            }
+        }
+        const alias = options.as ? options.as.trim() : (path.basename(targetDir).replace(/^\.+/, '') || 'repo');
+        if (!ALIAS_PATTERN.test(alias)) {
+            console.log(chalk.red(`Invalid alias "${alias}".`));
+            process.exitCode = 1;
+            return;
+        }
+        const meta = readMeta();
+        const extras = { ...(meta.extraRepos || {}) };
+        if (extras[alias]) {
+            console.log(chalk.red(`Alias "${alias}" is already registered.`));
+            process.exitCode = 1;
+            return;
+        }
+        if (fs.existsSync(targetDir)) {
+            console.log(chalk.red(`Path already exists: ${targetDir}`));
+            process.exitCode = 1;
+            return;
+        }
+        const parsed = parseSource(options.from);
+        const spinner = ora(`Cloning ${options.from} into ${targetDir}...`).start();
+        try {
+            fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+            await simpleGit().clone(parsed.url, targetDir);
+            await simpleGit(targetDir).removeRemote('origin');
+            const log = await simpleGit(targetDir).log({ maxCount: 1 });
+            const commit = log.latest?.hash.slice(0, 8) || 'unknown';
+            extras[alias] = { url: targetDir, path: targetDir, enabled: true };
+            updateMeta({ extraRepos: extras });
+            spinner.succeed(`Created ${targetDir} (${commit})`);
+            console.log(chalk.gray(`\nRegistered as "${alias}". Edit files there, then add your own git remote when ready.`));
+        }
+        catch (err) {
+            spinner.fail(`Init failed: ${err.message}`);
+            try {
+                fs.rmSync(targetDir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            process.exitCode = 1;
+        }
+    });
+    repoCmd
+        .command('add <source>')
+        .description('Register an existing local repo or clone a remote repo into ~/.agents-<alias>/')
+        .option('--as <alias>', 'Override the auto-derived alias (letters, digits, _ or -)')
+        .action(async (source, options) => {
+        const meta = readMeta();
+        const extras = { ...(meta.extraRepos || {}) };
+        const alias = options.as ? options.as.trim() : deriveAlias(source);
+        if (!ALIAS_PATTERN.test(alias)) {
+            console.log(chalk.red(`Invalid alias "${alias}".`));
+            console.log(chalk.gray('Alias must start with a letter/digit and contain only letters, digits, "_" or "-".'));
+            process.exitCode = 1;
+            return;
+        }
+        if (extras[alias]) {
+            console.log(chalk.red(`Alias "${alias}" is already registered.`));
+            console.log(chalk.gray(`Existing: ${extras[alias].url}`));
+            console.log(chalk.gray(`Use --as <other-alias>, or: agents repo remove ${alias}`));
+            process.exitCode = 1;
+            return;
+        }
+        let parsed;
+        try {
+            parsed = parseSource(source);
+        }
+        catch (err) {
+            console.log(chalk.red(err.message));
+            process.exitCode = 1;
+            return;
+        }
+        if (parsed.type === 'local') {
+            extras[alias] = { url: parsed.url, path: parsed.url, enabled: true };
+            updateMeta({ extraRepos: extras });
+            console.log(chalk.green(`Registered local repo "${alias}" -> ${parsed.url}`));
+            return;
+        }
+        ensureAgentsDir();
+        const targetDir = getExtraRepoDir(alias);
+        if (fs.existsSync(targetDir)) {
+            console.log(chalk.red(`Directory already exists: ${targetDir}`));
+            console.log(chalk.gray('Remove it manually or pick a different alias with --as.'));
+            process.exitCode = 1;
+            return;
+        }
+        const spinner = ora(`Cloning ${source}...`).start();
+        try {
+            fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+            await simpleGit().clone(parsed.url, targetDir);
+            if (parsed.ref) {
+                await simpleGit(targetDir).checkout(parsed.ref);
+            }
+            const log = await simpleGit(targetDir).log({ maxCount: 1 });
+            const commit = log.latest?.hash.slice(0, 8) || 'unknown';
+            spinner.succeed(`Cloned ${source} -> ${targetDir} (${commit})`);
+        }
+        catch (err) {
+            spinner.fail(`Clone failed: ${err.message}`);
+            try {
+                fs.rmSync(targetDir, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+            process.exitCode = 1;
+            return;
+        }
+        extras[alias] = { url: parsed.url, path: targetDir, enabled: true };
+        updateMeta({ extraRepos: extras });
+        console.log(chalk.gray(`\nRegistered as "${alias}". Skills and commands from this repo will be`));
+        console.log(chalk.gray(`picked up automatically the next time you launch any agent.`));
+    });
+    repoCmd
+        .command('list')
+        .alias('ls')
+        .description('Show all repos: system, user, and any registered extras')
+        .action(async () => {
+        const meta = readMeta();
+        console.log('');
+        // System repo
+        const systemUrl = meta.source || DEFAULT_SYSTEM_REPO;
+        const systemDir = getSystemAgentsDir();
+        const systemOnDisk = fs.existsSync(systemDir);
+        const systemIsGit = systemOnDisk && isGitRepo(systemDir);
+        const systemCommit = systemIsGit ? await getShortCommit(systemDir) : null;
+        const systemStatus = !systemOnDisk
+            ? chalk.red('missing')
+            : !systemIsGit
+                ? chalk.yellow('not a git repo — run: agents init')
+                : chalk.green('cloned');
+        const systemCommitLabel = systemCommit ? chalk.gray(`(${systemCommit})`) : '';
+        console.log(chalk.bold('System  (~/.agents-system/)'));
+        console.log(`  ${chalk.cyan('system'.padEnd(12))}  ${systemUrl}  ${systemStatus}  ${systemCommitLabel}`);
+        // User repo
+        const userDir = getUserAgentsDir();
+        const userOnDisk = fs.existsSync(userDir);
+        const userIsGit = userOnDisk && isGitRepo(userDir);
+        const userCommit = userIsGit ? await getShortCommit(userDir) : null;
+        let userRemoteUrl = '';
+        if (userIsGit) {
+            try {
+                const git = simpleGit(userDir);
+                const remotes = await git.getRemotes(true);
+                const origin = remotes.find(r => r.name === 'origin');
+                userRemoteUrl = origin?.refs?.fetch || '';
+            }
+            catch { /* no remote */ }
+        }
+        const userStatus = !userOnDisk
+            ? chalk.gray('not created')
+            : !userIsGit
+                ? chalk.gray('local (no remote)')
+                : chalk.green('cloned');
+        const userCommitLabel = userCommit ? chalk.gray(`(${userCommit})`) : '';
+        console.log(chalk.bold('\nUser  (~/.agents/)'));
+        console.log(`  ${chalk.cyan('user'.padEnd(12))}  ${userRemoteUrl || '~/.agents/'}  ${userStatus}  ${userCommitLabel}`);
+        if (!userIsGit) {
+            console.log(chalk.gray(`  ${''.padEnd(12)}  scaffold one with: agents repo init`));
+        }
+        // Extra repos
+        const extras = meta.extraRepos || {};
+        const aliases = Object.keys(extras);
+        console.log(chalk.bold('\nExtras:'));
+        if (aliases.length === 0) {
+            console.log(chalk.gray('  (none — add one with `agents repo add <source>`)\n'));
+            return;
+        }
+        for (const alias of aliases) {
+            const config = extras[alias];
+            const dir = resolveExtraRepoDir(alias, config);
+            const onDisk = fs.existsSync(dir);
+            const commit = onDisk ? await getShortCommit(dir) : null;
+            const status = !config.enabled
+                ? chalk.yellow('disabled')
+                : !onDisk
+                    ? chalk.red('missing')
+                    : chalk.green('enabled');
+            const commitLabel = commit ? chalk.gray(`(${commit})`) : '';
+            console.log(`  ${chalk.cyan(alias.padEnd(12))}  ${config.url}  ${status}  ${commitLabel}`);
+        }
+        console.log('');
+    });
+    repoCmd
+        .command('remove <alias>')
+        .alias('rm')
+        .description('Unregister an extra repo. Managed clones are deleted; external paths are kept.')
+        .action(async (alias) => {
+        const meta = readMeta();
+        const extras = { ...(meta.extraRepos || {}) };
+        if (!extras[alias]) {
+            console.log(chalk.red(`No extra repo registered as "${alias}".`));
+            process.exitCode = 1;
+            return;
+        }
+        const dir = resolveExtraRepoDir(alias, extras[alias]);
+        // Managed clones live at the default ~/.agents-<alias>/ — those we own
+        // and should delete on remove. Anything else is user-owned, leave alone.
+        const isManagedClone = path.resolve(dir) === path.resolve(getExtraRepoDir(alias));
+        try {
+            if (isManagedClone && fs.existsSync(dir)) {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+        }
+        catch (err) {
+            console.log(chalk.yellow(`Warning: could not delete ${dir}: ${err.message}`));
+        }
+        delete extras[alias];
+        updateMeta({ extraRepos: extras });
+        console.log(chalk.green(`Removed "${alias}"`));
+    });
+    repoCmd
+        .command('enable <alias>')
+        .description('Re-enable a previously disabled extra repo')
+        .action(async (alias) => {
+        await toggle(alias, true);
+    });
+    repoCmd
+        .command('disable <alias>')
+        .description('Stop merging this repo during sync without deleting the clone')
+        .action(async (alias) => {
+        await toggle(alias, false);
+    });
+    repoCmd
+        .command('pull [alias]')
+        .description('Pull updates. Aliases: "system" (~/.agents-system/), "user" (~/.agents/), or any registered extra. No arg pulls all.')
+        .action(async (alias) => {
+        const targets = collectRepoTargets(alias);
+        if (!targets) {
+            process.exitCode = 1;
+            return;
+        }
+        if (targets.length === 0) {
+            console.log(chalk.gray('No repos to pull.'));
+            return;
+        }
+        for (const t of targets) {
+            if (!fs.existsSync(t.dir) || !isGitRepo(t.dir)) {
+                console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
+                continue;
+            }
+            if (t.alias === 'system') {
+                // Skip system repo unless explicitly requested
+                if (alias !== 'system')
+                    continue;
+                // User explicitly asked for system repo — show status and offer to pull
+                try {
+                    const git = simpleGit(t.dir);
+                    await git.fetch();
+                    const status = await git.status();
+                    const behind = status.behind ?? 0;
+                    if (behind === 0) {
+                        console.log(chalk.green('Up to date'));
+                    }
+                    else {
+                        // Count changed resources by type
+                        const diff = await git.diff(['--name-only', 'HEAD..@{upstream}']);
+                        const files = diff.split('\n').filter(Boolean);
+                        const counts = {};
+                        for (const f of files) {
+                            if (f.startsWith('skills/'))
+                                counts['skills'] = (counts['skills'] || 0) + 1;
+                            else if (f.startsWith('commands/'))
+                                counts['commands'] = (counts['commands'] || 0) + 1;
+                            else if (f.startsWith('hooks/'))
+                                counts['hooks'] = (counts['hooks'] || 0) + 1;
+                            else if (f.startsWith('rules/'))
+                                counts['rules'] = (counts['rules'] || 0) + 1;
+                            else
+                                counts['other'] = (counts['other'] || 0) + 1;
+                        }
+                        const parts = [];
+                        if (counts['skills'])
+                            parts.push(`${counts['skills']} skill${counts['skills'] > 1 ? 's' : ''}`);
+                        if (counts['commands'])
+                            parts.push(`${counts['commands']} command${counts['commands'] > 1 ? 's' : ''}`);
+                        if (counts['hooks'])
+                            parts.push(`${counts['hooks']} hook${counts['hooks'] > 1 ? 's' : ''}`);
+                        if (counts['rules'])
+                            parts.push(`${counts['rules']} rule${counts['rules'] > 1 ? 's' : ''}`);
+                        if (counts['other'])
+                            parts.push(`${counts['other']} other`);
+                        const summary = parts.length > 0 ? parts.join(', ') : `${behind} update${behind > 1 ? 's' : ''}`;
+                        console.log(chalk.yellow(`${summary} available`));
+                        if (isInteractiveTerminal()) {
+                            const doPull = await confirm({ message: 'Pull now?', default: true });
+                            if (doPull) {
+                                const result = await pullRepo(t.dir);
+                                if (result.success) {
+                                    console.log(chalk.green('Updated'));
+                                }
+                                else {
+                                    console.log(chalk.red(result.error || 'Pull failed'));
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (err) {
+                    console.log(chalk.red(err.message));
+                }
+                continue;
+            }
+            const spinner = ora(`Pulling ${t.alias}...`).start();
+            const result = await pullRepo(t.dir);
+            if (result.success) {
+                spinner.succeed(`${t.alias} -> ${result.commit}`);
+            }
+            else {
+                spinner.fail(`${t.alias}: ${result.error}`);
+            }
+        }
+    });
+    repoCmd
+        .command('push [alias]')
+        .description('Commit and push the user repo or a user-owned extra. Refuses to push the system repo.')
+        .option('-m, --message <msg>', 'Commit message', 'Update via agents repo push')
+        .action(async (alias, options) => {
+        const targets = collectRepoTargets(alias);
+        if (!targets) {
+            process.exitCode = 1;
+            return;
+        }
+        // Drop system-repo targets — read-only by design.
+        const pushable = [];
+        for (const t of targets) {
+            if (t.alias === 'system') {
+                console.log(chalk.yellow('Skipping system repo (read-only — managed via the agents-cli upstream).'));
+                continue;
+            }
+            if (!fs.existsSync(t.dir) || !isGitRepo(t.dir)) {
+                console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
+                continue;
+            }
+            // Defense in depth: refuse if origin happens to be the system upstream.
+            if (await isSystemRepoOrigin(t.dir)) {
+                console.log(chalk.red(`  ${t.alias}: origin tracks the system repo — refusing to push.`));
+                continue;
+            }
+            pushable.push(t);
+        }
+        if (pushable.length === 0) {
+            console.log(chalk.gray('No pushable repos.'));
+            return;
+        }
+        for (const t of pushable) {
+            const spinner = ora(`Pushing ${t.alias}...`).start();
+            const result = await commitAndPush(t.dir, options.message);
+            if (result.success) {
+                spinner.succeed(`${t.alias} pushed`);
+            }
+            else {
+                spinner.fail(`${t.alias}: ${result.error}`);
+            }
+        }
+    });
+    repoCmd
+        .command('status [alias]')
+        .description('Per-repo summary: branch, ahead/behind upstream, working-tree state')
+        .action(async (alias) => {
+        const targets = collectRepoTargets(alias) || [];
+        if (targets.length === 0) {
+            console.log(chalk.gray('No git repos found.'));
+            return;
+        }
+        console.log('');
+        console.log(`  ${chalk.gray('REPO'.padEnd(12))} ${chalk.gray('BRANCH'.padEnd(28))}  ${chalk.gray('REMOTE'.padEnd(12))}  ${chalk.gray('LOCAL')}`);
+        for (const t of targets) {
+            if (!fs.existsSync(t.dir)) {
+                console.log(`  ${chalk.cyan(t.alias.padEnd(12))} ${chalk.red('missing')} ${chalk.gray(t.dir)}`);
+                continue;
+            }
+            if (!isGitRepo(t.dir)) {
+                console.log(`  ${chalk.cyan(t.alias.padEnd(12))} ${chalk.gray('not a git repo')} ${chalk.gray(t.dir)}`);
+                continue;
+            }
+            try {
+                const git = simpleGit(t.dir);
+                const status = await git.status();
+                const branch = status.tracking || status.current || '(detached)';
+                const remoteRaw = (status.ahead ?? 0) === 0 && (status.behind ?? 0) === 0
+                    ? 'in sync'
+                    : `+${status.ahead ?? 0} -${status.behind ?? 0}`;
+                const remoteColored = (status.ahead ?? 0) === 0 && (status.behind ?? 0) === 0
+                    ? chalk.green(remoteRaw)
+                    : chalk.yellow(remoteRaw);
+                const tree = status.isClean()
+                    ? chalk.green('clean')
+                    : chalk.yellow(`${status.files.length} uncommitted`);
+                const remotePad = ' '.repeat(Math.max(0, 12 - remoteRaw.length));
+                console.log(`  ${chalk.cyan(t.alias.padEnd(12))} ${branch.padEnd(28)}  ${remoteColored}${remotePad}  ${tree}`);
+            }
+            catch (err) {
+                console.log(`  ${chalk.cyan(t.alias.padEnd(12))} ${chalk.red('error')} ${err.message}`);
+            }
+        }
+        console.log('');
+    });
+}
+/**
+ * Resolve an alias (or undefined for "all") to a list of repo targets.
+ * Returns null when a named alias isn't found (callers should set exit code).
+ */
+function collectRepoTargets(alias) {
+    const meta = readMeta();
+    const extras = meta.extraRepos || {};
+    const all = [
+        { alias: 'system', dir: getSystemAgentsDir() },
+        { alias: 'user', dir: getUserAgentsDir() },
+        ...Object.keys(extras)
+            .filter((a) => extras[a].enabled)
+            .map((a) => ({ alias: a, dir: resolveExtraRepoDir(a, extras[a]) })),
+    ];
+    if (!alias)
+        return all;
+    const found = all.find((t) => t.alias === alias) || (extras[alias]
+        ? { alias, dir: resolveExtraRepoDir(alias, extras[alias]) }
+        : null);
+    if (!found) {
+        console.log(chalk.red(`Unknown repo "${alias}". Use "system", "user", or a registered extra alias.`));
+        return null;
+    }
+    return [found];
+}
+async function toggle(alias, enabled) {
+    const meta = readMeta();
+    const extras = { ...(meta.extraRepos || {}) };
+    if (!extras[alias]) {
+        console.log(chalk.red(`No extra repo registered as "${alias}".`));
+        process.exitCode = 1;
+        return;
+    }
+    if (extras[alias].enabled === enabled) {
+        console.log(chalk.gray(`"${alias}" is already ${enabled ? 'enabled' : 'disabled'}.`));
+        return;
+    }
+    extras[alias] = { ...extras[alias], enabled };
+    updateMeta({ extraRepos: extras });
+    console.log(chalk.green(`${enabled ? 'Enabled' : 'Disabled'} "${alias}"`));
+}

package/dist/commands/resource-view.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Shared resource list and detail view.
+ *
+ * Provides a reusable picker (TTY) / table (piped) presentation layer
+ * for resource-type commands (plugins, subagents, skills, etc.). Each
+ * resource supplies rows with sync targets; this module handles layout,
+ * filtering, and paging.
+ */
 import type { AgentId } from '../lib/types.js';
 export type SyncStatus = 'synced' | 'stale' | 'missing';
 export interface SyncTarget {
@@ -24,8 +32,7 @@ export interface ResourceViewOptions {
     filterAgent?: AgentId;
     filterVersion?: string;
 }
-/** Entry point: picker in TTY, table otherwise. */
+/** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export declare function showResourceList(opts: ResourceViewOptions): Promise<void>;
-/** Build the detail pane text shown when a row is focused. */
+/** Build the sync targets section showing version pills grouped by agent. */
 export declare function buildTargetsSection(targets: SyncTarget[]): string;
-//# sourceMappingURL=resource-view.d.ts.map

package/dist/commands/resource-view.js

@@ -1,8 +1,16 @@
+/**
+ * Shared resource list and detail view.
+ *
+ * Provides a reusable picker (TTY) / table (piped) presentation layer
+ * for resource-type commands (plugins, subagents, skills, etc.). Each
+ * resource supplies rows with sync targets; this module handles layout,
+ * filtering, and paging.
+ */
 import chalk from 'chalk';
 import { agentLabel } from '../lib/agents.js';
 import { itemPicker } from '../lib/picker.js';
 import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './utils.js';
-/** Entry point: picker in TTY, table otherwise. */
+/** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export async function showResourceList(opts) {
     if (opts.rows.length === 0) {
         console.log(chalk.gray(opts.emptyMessage));
@@ -37,6 +45,7 @@ export async function showResourceList(opts) {
     const lines = detail.split('\n');
     printWithPager(detail, lines.length);
 }
+/** Build the prompt message shown above the picker, including any scope label. */
 function buildPickerMessage(opts) {
     const scope = opts.filterVersion
         ? ` (${opts.filterAgent}@${opts.filterVersion})`
@@ -45,6 +54,7 @@ function buildPickerMessage(opts) {
             : '';
     return `Search ${opts.resourcePlural}${scope}:`;
 }
+/** Filter rows by a case-insensitive substring match on name or description. */
 function filterRows(rows, query) {
     const q = query.trim().toLowerCase();
     if (!q)
@@ -63,7 +73,7 @@ function formatPickerRow(row, opts) {
     const sync = formatSyncSummary(row.targets, opts);
     return `${name} ${extra}${desc} ${sync}`;
 }
-/** Table mode (piped output). */
+/** Render resources as a plain-text table (used when output is piped). */
 function printResourceTable(opts) {
     const header = buildTableHeader(opts);
     console.log(header);
@@ -87,6 +97,7 @@ function printResourceTable(opts) {
     }
     console.log(chalk.gray(summary.join(' · ')));
 }
+/** Build the column header line for the plain-text table. */
 function buildTableHeader(opts) {
     const name = chalk.bold(padRight('Name', 22));
     const extra = opts.extraLabel
@@ -96,7 +107,7 @@ function buildTableHeader(opts) {
     const sync = chalk.bold('Synced');
     return `${name} ${extra}${desc} ${sync}`;
 }
-/** Human-readable sync status: "everywhere", "14 of 16 installs", "not installed". */
+/** Compact sync summary: "everywhere", "14 of 16 installs", or "not installed". */
 function formatSyncSummary(targets, opts) {
     if (targets.length === 0) {
         return chalk.gray('no installed versions');
@@ -137,7 +148,7 @@ function formatSyncSummary(targets, opts) {
     }
     return parts.join(chalk.gray(' · '));
 }
-/** Build the detail pane text shown when a row is focused. */
+/** Build the sync targets section showing version pills grouped by agent. */
 export function buildTargetsSection(targets) {
     if (targets.length === 0)
         return chalk.gray('  No capable agent versions installed.');
@@ -156,6 +167,7 @@ export function buildTargetsSection(targets) {
     }
     return lines.join('\n');
 }
+/** Render a single version as a colored pill (green/yellow/strikethrough). */
 function formatVersionPill(t) {
     const star = t.isDefault ? chalk.yellow('★ ') : '';
     const vtxt = `v${t.version}`;
@@ -168,6 +180,7 @@ function formatVersionPill(t) {
             return star + chalk.gray.strikethrough(vtxt);
     }
 }
+/** Pad a string to a fixed width, accounting for ANSI escape codes in length calculation. */
 function padRight(s, width) {
     // Strip ANSI for length calc
     const raw = s.replace(/\x1b\[[0-9;]*m/g, '');
@@ -175,9 +188,9 @@ function padRight(s, width) {
         return s;
     return s + ' '.repeat(width - raw.length);
 }
+/** Truncate a string to a maximum length, appending an ellipsis if needed. */
 function truncate(s, max) {
     if (s.length <= max)
         return s;
     return s.slice(0, max - 1) + '…';
 }
-//# sourceMappingURL=resource-view.js.map