@pasko70/pibo 1.0.0

package/dist/tools/index.js

@@ -0,0 +1,366 @@
+import { Command } from 'commander';
+import { ErrorCode, formatCliError } from '../cli-errors.js';
+import { acquireBrowserUseLease, listBrowserUseLeases, printBrowserUseAuthTemplateEnv, printBrowserUseAuthTemplatePath, reapStaleBrowserUseLeases, releaseBrowserUseLease, } from './browser-use-leases.js';
+import { formatBrowserUseTargets, listBrowserUseCdpTargets, printAttachChatExports, selectBestChatTarget, } from './browser-use-cdp.js';
+import { ensureBrowserUseWrapper } from './browser-use-wrapper.js';
+import { detectDesktopEnv } from './desktop-env.js';
+import { doctorCliTool, findCliToolEntry, findToolGuide, getCliToolStatus, installCliTool, listCliToolEntries, removeCliTool, } from './registry.js';
+function requireEntry(name) {
+    const entry = findCliToolEntry(name);
+    if (!entry) {
+        throw new Error(formatCliError({
+            code: ErrorCode.CLIENT_ERROR,
+            type: 'CLI_TOOL_NOT_FOUND',
+            message: `Tool "${name}" not found`,
+            details: `Available tools: ${listCliToolEntries().map((item) => item.name).join(', ')}`,
+            suggestion: 'Run pibo tools list to see curated tools.',
+        }));
+    }
+    return entry;
+}
+function printList(installedOnly) {
+    const rows = listCliToolEntries()
+        .map((entry) => getCliToolStatus(entry))
+        .filter((status) => !installedOnly || status.installed)
+        .map((status) => ({
+        name: status.entry.name,
+        status: status.installed ? 'installed' : 'available',
+        executable: status.installed ? status.executablePath : '',
+        description: status.entry.description,
+    }));
+    if (rows.length === 0) {
+        console.log(installedOnly ? 'No cli tools are installed.' : 'No cli tools are currently bundled.');
+        return;
+    }
+    for (const row of rows) {
+        const executable = row.executable ? `\t${row.executable}` : '';
+        console.log(`${row.name}\t${row.status}\t${row.description}${executable}`);
+    }
+}
+function printShow(name) {
+    const entry = requireEntry(name);
+    const status = getCliToolStatus(entry);
+    console.log(`${entry.name}`);
+    console.log(`  ${entry.description}`);
+    console.log(`  package: ${entry.runtime.packageName}`);
+    console.log(`  status: ${status.installed ? 'installed' : 'available'}`);
+    console.log(`  runtime: ${status.rootDir}`);
+    console.log(`  home: ${status.homeDir}`);
+    console.log(`  executable: ${status.executablePath}`);
+    console.log('');
+    console.log('Guides:');
+    for (const guide of entry.guides) {
+        console.log(`  ${guide.name}\t${guide.description}`);
+    }
+    if (entry.notes.length > 0) {
+        console.log('');
+        console.log('Notes:');
+        for (const note of entry.notes)
+            console.log(`  - ${note}`);
+    }
+    console.log('');
+    console.log('Next:');
+    console.log(`  pibo tools env ${entry.name}`);
+    console.log(`  pibo tools guide ${entry.name} ${entry.guides[0]?.name ?? ''}`.trimEnd());
+    if (entry.name === 'browser-use') {
+        console.log('  pibo tools browser-use');
+    }
+}
+function printGuides(name) {
+    const entry = requireEntry(name);
+    for (const guide of entry.guides) {
+        console.log(`${guide.name}\t${guide.description}`);
+    }
+}
+function printGuide(name, guideName) {
+    const entry = requireEntry(name);
+    const selectedGuideName = guideName ?? entry.guides[0]?.name;
+    if (!selectedGuideName) {
+        throw new Error(formatCliError({
+            code: ErrorCode.CLIENT_ERROR,
+            type: 'CLI_TOOL_GUIDE_NOT_FOUND',
+            message: `Tool "${name}" has no guides`,
+        }));
+    }
+    const guide = findToolGuide(entry, selectedGuideName);
+    if (!guide) {
+        throw new Error(formatCliError({
+            code: ErrorCode.CLIENT_ERROR,
+            type: 'CLI_TOOL_GUIDE_NOT_FOUND',
+            message: `Guide "${selectedGuideName}" not found for tool "${name}"`,
+            details: `Available guides: ${entry.guides.map((item) => item.name).join(', ')}`,
+        }));
+    }
+    console.log(guide.content);
+}
+function printPath(name) {
+    const entry = requireEntry(name);
+    console.log(getCliToolStatus(entry).executablePath);
+}
+function printEnv(name) {
+    const entry = requireEntry(name);
+    const status = getCliToolStatus(entry);
+    const desktop = detectDesktopEnv();
+    if (process.platform === 'win32') {
+        console.log(`$env:PATH = "${status.executablePath.replace(/\\[^\\]+$/, '')};$env:PATH"`);
+        if (entry.runtime.homeEnvVar)
+            console.log(`$env:${entry.runtime.homeEnvVar} = "${status.homeDir}"`);
+        return;
+    }
+    const binDir = status.executablePath.replace(/\/[^/]+$/, '');
+    const wrapperPath = ensureBrowserUseWrapper(status);
+    const wrapperBinDir = wrapperPath ? wrapperPath.replace(/\/[^/]+$/, '') : `${status.homeDir}/bin`;
+    console.log(`export PATH="${wrapperBinDir}:${binDir}:$PATH"`);
+    if (entry.runtime.homeEnvVar)
+        console.log(`export ${entry.runtime.homeEnvVar}="${status.homeDir}"`);
+    if (desktop.display)
+        console.log(`export DISPLAY="${desktop.display}"`);
+    if (desktop.waylandDisplay)
+        console.log(`export WAYLAND_DISPLAY="${desktop.waylandDisplay}"`);
+    if (desktop.xauthority)
+        console.log(`export XAUTHORITY="${desktop.xauthority}"`);
+    if (desktop.xdgRuntimeDir)
+        console.log(`export XDG_RUNTIME_DIR="${desktop.xdgRuntimeDir}"`);
+    if (desktop.dbusSessionBusAddress) {
+        console.log(`export DBUS_SESSION_BUS_ADDRESS="${desktop.dbusSessionBusAddress}"`);
+    }
+}
+function parsePositiveInteger(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+        throw new Error(`Expected a positive integer, got "${value}"`);
+    }
+    return parsed;
+}
+function printBrowserUseDiscovery() {
+    console.log(`pibo tools browser-use - browser-use helpers
+
+Start:
+  eval "$(pibo tools env browser-use)"
+
+Commands:
+  targets                    List Chrome CDP targets with Chat auth hints
+  attach-chat                Export the best existing authenticated Chat target
+  auth-template path          Print the default authenticated template profile path
+  auth-template env           Print shell exports for preparing the auth template profile
+  lease acquire               Acquire an isolated authenticated browser slot
+  lease list                  List authenticated browser slots
+  lease release <id>          Release one browser slot
+  lease reap-stale            Release expired or dead browser slots
+
+Next:
+  pibo tools show browser-use
+  pibo tools guide browser-use browser-use
+  pibo tools browser-use targets
+  pibo tools browser-use auth-template env
+  pibo tools browser-use lease acquire`);
+}
+function printToolsDiscovery() {
+    console.log(`pibo tools - curated external CLI tools
+
+Commands:
+  list                      List curated tools
+  installed                 List installed tools
+  show <name>               Show one tool
+  install <name>            Install one tool
+  doctor <name>             Check one tool
+  guides <name>             List tool guides
+  guide <name> [guide]      Print one guide
+  path <name>               Print executable path
+  env <name>                Print shell exports
+  browser-use               Browser-use auth slots and helper commands
+
+Next:
+  pibo tools list`);
+}
+export async function runToolsCli(argv = process.argv) {
+    if (argv[2] === '--help' || argv[2] === '-h') {
+        printToolsDiscovery();
+        return;
+    }
+    const program = new Command();
+    program
+        .name('pibo tools')
+        .description('Install and inspect curated external CLI tools')
+        .helpOption(false)
+        .showHelpAfterError();
+    program
+        .command('list')
+        .description('List curated CLI tools')
+        .action(() => printList(false));
+    program
+        .command('installed')
+        .description('List installed CLI tools')
+        .action(() => printList(true));
+    program
+        .command('show')
+        .argument('<name>')
+        .description('Show one CLI tool preset')
+        .action(printShow);
+    program
+        .command('install')
+        .argument('<name>')
+        .option('--no-setup', 'Only print install target without installing runtime')
+        .description('Install a CLI tool')
+        .action(async (name, options) => {
+        await installCliTool(requireEntry(name), options.setup !== false);
+    });
+    program
+        .command('remove')
+        .argument('<name>')
+        .description('Remove an installed CLI tool runtime')
+        .action(async (name) => {
+        await removeCliTool(requireEntry(name));
+    });
+    program
+        .command('doctor')
+        .argument('<name>')
+        .description('Check tool prerequisites and runtime state')
+        .action(async (name) => {
+        await doctorCliTool(requireEntry(name));
+    });
+    program
+        .command('guides')
+        .argument('<name>')
+        .description('List guides for a CLI tool')
+        .action(printGuides);
+    program
+        .command('guide')
+        .argument('<name>')
+        .argument('[guide]')
+        .description('Print a CLI tool guide')
+        .action(printGuide);
+    program
+        .command('path')
+        .argument('<name>')
+        .description('Print the installed tool executable path')
+        .action(printPath);
+    program
+        .command('env')
+        .argument('<name>')
+        .description('Print shell exports for using the tool directly')
+        .action(printEnv);
+    const browserUse = program
+        .command('browser-use')
+        .description('Browser-use auth slots and helper commands')
+        .action(printBrowserUseDiscovery);
+    browserUse
+        .command('targets')
+        .description('List Chrome CDP targets with Chat auth hints')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL', 'http://127.0.0.1:56663')
+        .option('--no-probe', 'Only read /json/list without page DOM probes')
+        .option('--json', 'Print machine-readable target data')
+        .action(async (options) => {
+        const targets = await listBrowserUseCdpTargets({ cdpUrl: options.cdpUrl, probe: options.probe });
+        if (options.json) {
+            console.log(JSON.stringify({ targets }, null, 2));
+            return;
+        }
+        console.log(formatBrowserUseTargets(targets));
+        if (targets.length === 0) {
+            console.log('');
+            console.log('Next: eval "$(pibo tools env browser-use)"');
+        }
+    });
+    browserUse
+        .command('attach-chat')
+        .description('Export the best existing authenticated Chat target')
+        .option('--cdp-url <url>', 'Chrome DevTools HTTP URL', 'http://127.0.0.1:56663')
+        .option('--json', 'Print machine-readable target data')
+        .action(async (options) => {
+        const targets = await listBrowserUseCdpTargets({ cdpUrl: options.cdpUrl });
+        const target = selectBestChatTarget(targets);
+        if (!target) {
+            throw new Error(formatCliError({
+                code: ErrorCode.CLIENT_ERROR,
+                type: 'BROWSER_USE_CHAT_TARGET_NOT_FOUND',
+                message: 'No authenticated Chat Web target with a composer textarea was found',
+                suggestion: 'Run `pibo tools browser-use targets`, reuse an authenticated tab if present, or acquire a slot with `pibo tools browser-use lease acquire`.',
+            }));
+        }
+        if (options.json) {
+            console.log(JSON.stringify({ target }, null, 2));
+            return;
+        }
+        printAttachChatExports(target, options.cdpUrl);
+    });
+    const authTemplate = browserUse
+        .command('auth-template')
+        .description('Manage the browser-use authenticated template profile')
+        .action(() => {
+        console.log(`pibo tools browser-use auth-template
+
+Commands:
+  path    Print the default authenticated template profile path
+  env     Print shell exports for preparing the auth template profile`);
+    });
+    authTemplate
+        .command('path')
+        .description('Print the default authenticated template profile path')
+        .action(() => {
+        printBrowserUseAuthTemplatePath(getCliToolStatus(requireEntry('browser-use')));
+    });
+    authTemplate
+        .command('env')
+        .description('Print shell exports for preparing the auth template profile')
+        .action(async () => {
+        await printBrowserUseAuthTemplateEnv(getCliToolStatus(requireEntry('browser-use')));
+    });
+    const lease = browserUse
+        .command('lease')
+        .description('Acquire and manage isolated authenticated browser-use slots')
+        .action(() => {
+        console.log(`pibo tools browser-use lease
+
+Commands:
+  acquire       Acquire an isolated authenticated browser slot
+  list          List authenticated browser slots
+  release <id>  Release one browser slot
+  reap-stale    Release expired or dead browser slots`);
+    });
+    lease
+        .command('acquire')
+        .description('Acquire an isolated authenticated browser slot')
+        .option('--app <name>', 'Auth pool app name', 'pibo-chat')
+        .option('--owner <owner>', 'Lease owner label')
+        .option('--ttl-minutes <minutes>', 'Lease time-to-live in minutes', parsePositiveInteger)
+        .option('--max-slots <count>', 'Maximum active slots for the app', parsePositiveInteger)
+        .option('--template-dir <path>', 'Authenticated Chrome user-data-dir template to clone')
+        .option('--profile-name <name>', 'Chrome profile name inside each slot')
+        .option('--json', 'Print machine-readable lease data')
+        .action(async (options) => {
+        await acquireBrowserUseLease({ status: getCliToolStatus(requireEntry('browser-use')) }, options);
+    });
+    lease
+        .command('list')
+        .description('List authenticated browser slots')
+        .option('--json', 'Print machine-readable lease data')
+        .action(async (options) => {
+        await listBrowserUseLeases({ status: getCliToolStatus(requireEntry('browser-use')) }, Boolean(options.json));
+    });
+    lease
+        .command('release')
+        .argument('<id>')
+        .option('--delete-profile', 'Delete the slot Chrome user-data-dir')
+        .description('Release one browser slot')
+        .action(async (id, options) => {
+        await releaseBrowserUseLease({ status: getCliToolStatus(requireEntry('browser-use')) }, id, options);
+    });
+    lease
+        .command('reap-stale')
+        .description('Release expired or dead browser slots')
+        .action(async () => {
+        await reapStaleBrowserUseLeases({ status: getCliToolStatus(requireEntry('browser-use')) });
+    });
+    if (argv.length <= 2) {
+        printList(false);
+        return;
+    }
+    try {
+        await program.parseAsync(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exitCode = ErrorCode.CLIENT_ERROR;
+    }
+}

package/dist/tools/python-runtime.js

@@ -0,0 +1,154 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ErrorCode, formatCliError } from '../cli-errors.js';
+import { getDesktopProcessEnv, printDesktopEnvStatus } from './desktop-env.js';
+function getPiboHome() {
+    return process.env.PIBO_HOME || join(homedir(), '.pibo');
+}
+export function getToolPythonRuntimePaths(name, spec) {
+    const rootDir = join(getPiboHome(), 'tools', name);
+    const homeDir = join(rootDir, 'home');
+    const venvDir = join(rootDir, '.venv');
+    const binDir = join(venvDir, process.platform === 'win32' ? 'Scripts' : 'bin');
+    const executable = process.platform === 'win32'
+        ? `${spec.executableName}.exe`
+        : spec.executableName;
+    return {
+        rootDir,
+        homeDir,
+        venvDir,
+        binDir,
+        pythonPath: join(binDir, process.platform === 'win32' ? 'python.exe' : 'python'),
+        executablePath: join(binDir, executable),
+    };
+}
+export function getToolPythonRuntimeEnv(paths, spec) {
+    const env = { ...process.env, ...getDesktopProcessEnv() };
+    env.PATH = `${paths.binDir}:${join(paths.homeDir, 'bin')}:${env.PATH ?? ''}`;
+    if (spec.homeEnvVar)
+        env[spec.homeEnvVar] = paths.homeDir;
+    return env;
+}
+function runBuffered(command, args, env = process.env) {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+        const chunks = [];
+        child.stdout.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+        child.stderr.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+        child.on('error', (error) => {
+            resolve({ ok: false, output: error.message });
+        });
+        child.on('close', (code) => {
+            resolve({
+                ok: code === 0,
+                output: Buffer.concat(chunks).toString('utf-8').trim(),
+            });
+        });
+    });
+}
+function runInherited(command, args, env = process.env) {
+    return new Promise((resolve, reject) => {
+        console.log(`Running: ${command} ${args.join(' ')}`);
+        const child = spawn(command, args, {
+            stdio: 'inherit',
+            env,
+        });
+        child.on('error', (error) => {
+            reject(new Error(formatCliError({
+                code: ErrorCode.CLIENT_ERROR,
+                type: 'CLI_TOOL_COMMAND_FAILED',
+                message: `Failed to run command: ${command}`,
+                details: error.message,
+                suggestion: 'Install uv first, then rerun the command.',
+            })));
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(formatCliError({
+                code: ErrorCode.CLIENT_ERROR,
+                type: 'CLI_TOOL_COMMAND_FAILED',
+                message: `Command failed with exit code ${code ?? 'unknown'}`,
+                details: `${command} ${args.join(' ')}`,
+                suggestion: 'Fix the setup error above, then rerun the install command.',
+            })));
+        });
+    });
+}
+export async function printToolPythonRuntimeDoctor(name, spec) {
+    const paths = getToolPythonRuntimePaths(name, spec);
+    const uv = await runBuffered('uv', ['--version']);
+    const python = uv.ok
+        ? await runBuffered('uv', ['python', 'find', spec.pythonVersion])
+        : { ok: false, output: 'skipped because uv is missing' };
+    console.log(`${name}`);
+    console.log(`  uv: ${uv.ok ? uv.output || 'ok' : `missing (${uv.output})`}`);
+    console.log(`  python ${spec.pythonVersion}: ${python.ok ? python.output || 'ok' : `missing (${python.output})`}`);
+    console.log(`  runtime: ${paths.rootDir}`);
+    console.log(`  home: ${paths.homeDir}`);
+    console.log(`  venv: ${existsSync(paths.venvDir) ? 'present' : 'missing'}`);
+    console.log(`  executable: ${existsSync(paths.executablePath) ? paths.executablePath : 'missing'}`);
+    printDesktopEnvStatus('  ');
+    if (existsSync(paths.executablePath)) {
+        const doctor = await runBuffered(paths.executablePath, ['doctor'], getToolPythonRuntimeEnv(paths, spec));
+        console.log(`  tool doctor: ${doctor.ok ? 'ok' : 'failed'}`);
+        if (doctor.output) {
+            console.log(doctor.output.split('\n').map((line) => `    ${line}`).join('\n'));
+        }
+    }
+    if (!uv.ok) {
+        console.log('');
+        console.log('Install uv first:');
+        console.log('  macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh');
+        console.log('  Windows PowerShell: irm https://astral.sh/uv/install.ps1 | iex');
+    }
+    if (uv.ok && !python.ok) {
+        console.log('');
+        console.log(`Install Python ${spec.pythonVersion}+ first:`);
+        console.log('  Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-venv');
+        console.log('  macOS: brew install python');
+        console.log('  Windows PowerShell: winget install Python.Python.3.12');
+        console.log('');
+        console.log('Then rerun:');
+        console.log(`  pibo tools doctor ${name}`);
+    }
+}
+export async function installToolPythonRuntime(name, spec) {
+    const uv = await runBuffered('uv', ['--version']);
+    if (!uv.ok) {
+        throw new Error(formatCliError({
+            code: ErrorCode.CLIENT_ERROR,
+            type: 'CLI_TOOL_UV_MISSING',
+            message: 'uv was not found on PATH',
+            details: uv.output,
+            suggestion: 'Install uv first. macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh. Windows PowerShell: irm https://astral.sh/uv/install.ps1 | iex.',
+        }));
+    }
+    const paths = getToolPythonRuntimePaths(name, spec);
+    await mkdir(paths.rootDir, { recursive: true });
+    await mkdir(paths.homeDir, { recursive: true });
+    if (!existsSync(paths.venvDir)) {
+        await runInherited('uv', ['venv', paths.venvDir, '--python', spec.pythonVersion]);
+    }
+    await runInherited('uv', [
+        'pip',
+        'install',
+        '--python',
+        paths.pythonPath,
+        spec.packageName,
+    ]);
+    if (spec.postInstallArgs?.length) {
+        await runInherited(paths.executablePath, spec.postInstallArgs, getToolPythonRuntimeEnv(paths, spec));
+    }
+    return paths;
+}
+export async function removeToolPythonRuntime(name, spec) {
+    const paths = getToolPythonRuntimePaths(name, spec);
+    await rm(paths.rootDir, { recursive: true, force: true });
+    console.log(`Removed runtime: ${paths.rootDir}`);
+}

package/dist/tools/registry.js

@@ -0,0 +1,107 @@
+import { existsSync } from 'node:fs';
+import { printDesktopEnvStatus } from './desktop-env.js';
+import { BROWSER_USE_GUIDE, REMOTE_BROWSER_GUIDE } from './guides.js';
+import { getToolPythonRuntimePaths, installToolPythonRuntime, printToolPythonRuntimeDoctor, removeToolPythonRuntime, } from './python-runtime.js';
+const MAX_AGENT_CONTEXT_SNIPPET_LENGTH = 480;
+const INSTALLED_TOOLS_CONTEXT_PATH = '.pibo/context/installed-pibo-tools.md';
+const REGISTRY = [
+    {
+        name: 'browser-use',
+        description: 'Browser automation CLI for web interaction, screenshots, and extraction.',
+        runtime: {
+            packageName: 'browser-use[cli]==0.12.6',
+            executableName: 'browser-use',
+            pythonVersion: '3.12',
+            homeEnvVar: 'BROWSER_USE_HOME',
+        },
+        guides: [BROWSER_USE_GUIDE, REMOTE_BROWSER_GUIDE],
+        notes: [
+            'Installed on demand into an isolated Python virtual environment.',
+            'Pinned to browser-use 0.12.6 so the CLI surface matches the bundled guides.',
+            'The tool uses BROWSER_USE_HOME under the pibo tool runtime directory.',
+            'The pibo tool environment wraps browser-use so new browser sessions default to Pibo-managed persistent PIBo Chrome via CDP; pass --fresh-profile for a temporary profile.',
+            'Use pibo tools browser-use lease acquire for isolated authenticated browser slots when multiple agents need Chat Web App access.',
+            'Guides are available through pibo tools guide and are not loaded into pibo profiles automatically.',
+        ],
+        agentContextSnippet: [
+            'Browser automation CLI for frontend development and web testing.',
+            'Start in one persistent shell with `eval "$(npm run --silent dev -- tools env browser-use)"`.',
+            'For authenticated Pibo Chat Web App testing, prefer `eval "$(npm run --silent dev -- tools browser-use lease acquire --app pibo-chat --owner "$USER")"`.',
+            'Discover details with `npm run dev -- tools show browser-use` and `npm run dev -- tools guide browser-use browser-use`.',
+        ].join('\n'),
+    },
+];
+for (const entry of REGISTRY) {
+    const snippet = entry.agentContextSnippet.trim();
+    if (snippet.length === 0) {
+        throw new Error(`CLI tool "${entry.name}" is missing agentContextSnippet`);
+    }
+    if (snippet.length > MAX_AGENT_CONTEXT_SNIPPET_LENGTH) {
+        throw new Error(`CLI tool "${entry.name}" agentContextSnippet exceeds ${MAX_AGENT_CONTEXT_SNIPPET_LENGTH} characters`);
+    }
+}
+export function listCliToolEntries() {
+    return REGISTRY;
+}
+export function findCliToolEntry(name) {
+    return REGISTRY.find((entry) => entry.name === name);
+}
+export function getCliToolStatus(entry) {
+    const paths = getToolPythonRuntimePaths(entry.name, entry.runtime);
+    return {
+        entry,
+        installed: existsSync(paths.executablePath),
+        executablePath: paths.executablePath,
+        rootDir: paths.rootDir,
+        homeDir: paths.homeDir,
+    };
+}
+export function findToolGuide(entry, guideName) {
+    return entry.guides.find((guide) => guide.name === guideName);
+}
+export function listInstalledCliToolAgentContexts() {
+    return REGISTRY
+        .filter((entry) => getCliToolStatus(entry).installed)
+        .map((entry) => ({
+        name: entry.name,
+        description: entry.description,
+        snippet: entry.agentContextSnippet,
+    }));
+}
+export function getInstalledCliToolContextFile() {
+    const installedEntries = listInstalledCliToolAgentContexts();
+    if (installedEntries.length === 0)
+        return undefined;
+    const sections = installedEntries.flatMap((entry) => [
+        `## ${entry.name}`,
+        entry.snippet,
+        '',
+    ]);
+    return {
+        path: INSTALLED_TOOLS_CONTEXT_PATH,
+        content: [
+            '# Installed Pibo Tools',
+            '',
+            'These curated CLI tools are installed in this environment. The CLI remains the source of truth; use the referenced commands to discover each workflow step by step.',
+            '',
+            ...sections,
+        ].join('\n').trimEnd(),
+    };
+}
+export async function installCliTool(entry, runSetup) {
+    if (runSetup) {
+        await installToolPythonRuntime(entry.name, entry.runtime);
+    }
+    const status = getCliToolStatus(entry);
+    console.log(`${runSetup ? 'Installed' : 'Install target'} ${entry.name}`);
+    console.log(`  executable: ${status.executablePath}`);
+    console.log(`  home: ${status.homeDir}`);
+    printDesktopEnvStatus('  ');
+    console.log(`  env: pibo tools env ${entry.name}`);
+}
+export async function removeCliTool(entry) {
+    await removeToolPythonRuntime(entry.name, entry.runtime);
+}
+export async function doctorCliTool(entry) {
+    await printToolPythonRuntimeDoctor(entry.name, entry.runtime);
+}