pikiloop 0.4.0

package/dist/agent/cli/auth.js

@@ -0,0 +1,325 @@
+/**
+ * CLI auth + install runner.
+ *
+ * Two flows share a single streaming-child-session core:
+ *
+ *   - oauth-web: spawn `loginArgv`, stream stdout/stderr to the UI, poll
+ *     `statusArgv` in the background, and settle when the CLI reports ready.
+ *     Used by CLIs that print a device code / one-time-code non-interactively
+ *     (gh, wrangler, supabase, …). CLIs whose sign-in needs a real TTY use
+ *     `manualLoginCommands` instead and never reach this runner.
+ *   - install: spawn the `npm install -g <pkg>` argv, stream output, re-detect
+ *     once the child exits.
+ *
+ * Token CLIs (aws, mocli) skip this entirely — credentials come in via a plain
+ * POST and are applied synchronously by `applyCliToken`.
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { detectCli, invalidateCliStatus, currentPlatform } from './detector.js';
+import { getRecommendedCli } from './registry.js';
+const SESSIONS = new Map();
+const MAX_SESSION_AGE_MS = 15 * 60 * 1000;
+const POLL_INTERVAL_MS = 2_000;
+const POLL_TIMEOUT_MS = 10 * 60 * 1000;
+const BACKLOG_LINES = 200;
+// ---------------------------------------------------------------------------
+// Session lifecycle
+// ---------------------------------------------------------------------------
+function reapExpiredSessions() {
+    const now = Date.now();
+    for (const [id, s] of SESSIONS) {
+        if (s.done && now - s.startedAt > MAX_SESSION_AGE_MS)
+            SESSIONS.delete(id);
+    }
+}
+export function getAuthSession(sessionId) {
+    reapExpiredSessions();
+    return SESSIONS.get(sessionId);
+}
+export function cancelAuthSession(sessionId) {
+    const s = SESSIONS.get(sessionId);
+    if (!s || s.done)
+        return false;
+    s._child?.kill?.('SIGTERM');
+    return true;
+}
+function startStreamingSession(opts) {
+    const { cli, argv, env, shell, pollUntilReady, computeOk } = opts;
+    const sessionId = randomUUID();
+    const events = new EventEmitter();
+    // Unlimited listeners — SSE clients may resubscribe multiple times.
+    events.setMaxListeners(0);
+    const session = {
+        sessionId,
+        cliId: cli.id,
+        startedAt: Date.now(),
+        events,
+        done: false,
+        ok: false,
+        exitCode: null,
+        backlog: [],
+    };
+    SESSIONS.set(sessionId, session);
+    const [cmd, ...args] = argv;
+    const child = spawn(cmd, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env,
+        shell,
+        windowsHide: true,
+    });
+    session._child = child;
+    const pushOutput = (chunk) => {
+        session.backlog.push(chunk);
+        if (session.backlog.length > BACKLOG_LINES) {
+            session.backlog.splice(0, session.backlog.length - BACKLOG_LINES);
+        }
+        events.emit('event', { type: 'output', chunk });
+    };
+    child.stdout?.on('data', (buf) => pushOutput(buf.toString('utf8')));
+    child.stderr?.on('data', (buf) => pushOutput(buf.toString('utf8')));
+    child.on('error', (err) => {
+        events.emit('event', { type: 'error', message: err.message });
+    });
+    let settled = false;
+    let poller;
+    const settle = async (exitCode) => {
+        if (settled)
+            return;
+        settled = true;
+        if (poller)
+            clearInterval(poller);
+        invalidateCliStatus(cli.id);
+        let finalStatus;
+        try {
+            finalStatus = await detectCli(cli);
+        }
+        catch { /* best-effort */ }
+        if (finalStatus) {
+            events.emit('event', { type: 'status', status: finalStatus });
+        }
+        session.ok = computeOk(exitCode, finalStatus);
+        session.exitCode = exitCode;
+        session.done = true;
+        events.emit('event', { type: 'done', ok: session.ok, exitCode });
+    };
+    if (pollUntilReady) {
+        const pollDeadline = Date.now() + POLL_TIMEOUT_MS;
+        poller = setInterval(async () => {
+            if (settled)
+                return;
+            if (Date.now() > pollDeadline) {
+                child.kill('SIGTERM');
+                void settle(null);
+                return;
+            }
+            try {
+                invalidateCliStatus(cli.id);
+                const status = await detectCli(cli);
+                events.emit('event', { type: 'status', status });
+                if (status.state === 'ready') {
+                    if (!child.killed)
+                        child.kill('SIGTERM');
+                    void settle(child.exitCode);
+                }
+            }
+            catch { /* ignore polling errors */ }
+        }, POLL_INTERVAL_MS);
+    }
+    child.on('close', (code) => { void settle(code); });
+    return { ok: true, sessionId };
+}
+// ---------------------------------------------------------------------------
+// oauth-web login
+// ---------------------------------------------------------------------------
+export async function startCliAuthSession(cliId) {
+    const cli = getRecommendedCli(cliId);
+    if (!cli)
+        return { ok: false, error: `unknown cli: ${cliId}` };
+    if (cli.auth.type !== 'oauth-web' || !cli.auth.loginArgv) {
+        return { ok: false, error: `cli ${cliId} does not support oauth-web sign-in` };
+    }
+    // CLIs configured for manual login should never spawn here — guard so a
+    // misbehaving client can't end-run the documented terminal flow.
+    if (cli.auth.manualLoginCommands && cli.auth.manualLoginCommands.length > 0) {
+        return { ok: false, error: `cli ${cliId} uses manual sign-in (run the commands in your own terminal)` };
+    }
+    return startStreamingSession({
+        cli,
+        argv: cli.auth.loginArgv,
+        env: { ...process.env, NO_COLOR: '1', TERM: 'dumb', CI: '' },
+        pollUntilReady: true,
+        computeOk: (_exit, status) => status?.state === 'ready',
+    });
+}
+const NPM_GLOBAL_INSTALL_RE = /^npm\s+(?:install|i)\s+(?:-g|--global)\s+(\S.*)$/;
+const SHELL_METACHAR_RE = /[|;&`$()<>]/;
+/**
+ * Inspect a CLI's install spec for the current platform and return a single
+ * argv that's safe to spawn without user-side approvals. Returns null when no
+ * such command exists (brew/apt/dnf/winget/scoop/curl-pipe-sh entries are all
+ * rejected on purpose — those require sudo or interactive confirmation).
+ */
+export function resolveAutoInstallSpec(cli, platform) {
+    const commands = cli.install[platform] || [];
+    for (const c of commands) {
+        const cmd = c.cmd.trim();
+        if (SHELL_METACHAR_RE.test(cmd))
+            continue;
+        if (/^sudo\b/i.test(cmd))
+            continue;
+        const m = cmd.match(NPM_GLOBAL_INSTALL_RE);
+        if (!m)
+            continue;
+        const pkgs = m[1].split(/\s+/).filter(Boolean);
+        if (pkgs.length === 0)
+            continue;
+        return { argv: ['npm', 'install', '-g', ...pkgs], label: c.label || 'npm' };
+    }
+    return null;
+}
+export async function startCliInstallSession(cliId) {
+    const cli = getRecommendedCli(cliId);
+    if (!cli)
+        return { ok: false, error: `unknown cli: ${cliId}` };
+    const spec = resolveAutoInstallSpec(cli, currentPlatform());
+    if (!spec)
+        return { ok: false, error: `no auto-install command available for ${cliId}` };
+    return startStreamingSession({
+        cli,
+        argv: spec.argv,
+        env: { ...process.env, NO_COLOR: '1', TERM: 'dumb', CI: '1' },
+        // npm on Windows is npm.cmd — needs shell resolution. spawn() args are
+        // still passed argv-style; we don't concat into a shell string.
+        shell: process.platform === 'win32',
+        pollUntilReady: false,
+        computeOk: (exit, status) => exit === 0 && (status ? status.state !== 'not_installed' : true),
+    });
+}
+// ---------------------------------------------------------------------------
+// Token auth — apply-credentials flow
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+/**
+ * Apply a set of credentials for a `token`-auth CLI and verify. Each CLI gets a
+ * tailored write path because there's no universal convention — we only do this
+ * for CLIs we explicitly support.
+ */
+export async function applyCliToken(cliId, values) {
+    const cli = getRecommendedCli(cliId);
+    if (!cli)
+        return { ok: false, error: `unknown cli: ${cliId}` };
+    if (cli.auth.type !== 'token')
+        return { ok: false, error: `cli ${cliId} does not use token auth` };
+    try {
+        if (cli.id === 'aws') {
+            const id = (values.AWS_ACCESS_KEY_ID || '').trim();
+            const secret = (values.AWS_SECRET_ACCESS_KEY || '').trim();
+            const region = (values.AWS_DEFAULT_REGION || '').trim();
+            if (!id || !secret)
+                return { ok: false, error: 'AWS access key ID and secret are required' };
+            const awsDir = path.join(os.homedir(), '.aws');
+            fs.mkdirSync(awsDir, { recursive: true, mode: 0o700 });
+            const credPath = path.join(awsDir, 'credentials');
+            const credBody = `[default]\naws_access_key_id = ${id}\naws_secret_access_key = ${secret}\n`;
+            mergeIniSection(credPath, 'default', credBody);
+            if (region) {
+                const configPath = path.join(awsDir, 'config');
+                mergeIniSection(configPath, 'default', `[default]\nregion = ${region}\n`);
+            }
+        }
+        else if (cli.id === 'mocli') {
+            // mocli stores its key via `mocli auth init --apik <KEY>` — let the CLI
+            // own its storage path so future schema changes upstream don't break us.
+            const key = (values.MOWEN_API_KEY || '').trim();
+            if (!key)
+                return { ok: false, error: 'Mowen API Key is required' };
+            const applied = await new Promise((resolve) => {
+                const child = spawn('mocli', ['auth', 'init', '--apik', key], {
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+                });
+                let stderr = '';
+                child.stderr?.on('data', b => { stderr += b.toString('utf8'); });
+                child.on('error', err => resolve({ ok: false, stderr: err.message }));
+                child.on('close', code => resolve({ ok: code === 0, stderr }));
+            });
+            if (!applied.ok) {
+                return { ok: false, error: applied.stderr.trim().slice(0, 200) || 'mocli auth init failed' };
+            }
+        }
+        else {
+            return { ok: false, error: `token auth is not implemented for ${cliId}` };
+        }
+        invalidateCliStatus(cliId);
+        const status = await detectCli(cli);
+        return { ok: status.state === 'ready', status, error: status.state === 'ready' ? undefined : status.authDetail };
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || 'failed to apply token' };
+    }
+}
+/**
+ * Merge a `[section]` block into an INI-style file, replacing any existing
+ * block with the same name. Idempotent; preserves other sections and comments.
+ */
+function mergeIniSection(filePath, section, block) {
+    let current = '';
+    try {
+        current = fs.readFileSync(filePath, 'utf-8');
+    }
+    catch { /* new file */ }
+    const header = `[${section}]`;
+    const lines = current.split(/\r?\n/);
+    const out = [];
+    let inTarget = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed === header) {
+            inTarget = true;
+            continue;
+        }
+        if (inTarget) {
+            if (/^\[.+\]$/.test(trimmed)) {
+                inTarget = false;
+                out.push(line);
+            }
+            // else: drop old line
+        }
+        else {
+            out.push(line);
+        }
+    }
+    let body = out.join('\n').replace(/\n+$/, '');
+    if (body)
+        body += '\n\n';
+    body += block.trim() + '\n';
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, body, { mode: 0o600 });
+}
+export async function logoutCli(cliId) {
+    const cli = getRecommendedCli(cliId);
+    if (!cli)
+        return { ok: false, error: `unknown cli: ${cliId}` };
+    if (!cli.auth.logoutArgv || cli.auth.logoutArgv.length === 0) {
+        return { ok: false, error: `cli ${cliId} has no logout command` };
+    }
+    return new Promise((resolve) => {
+        const [cmd, ...args] = cli.auth.logoutArgv;
+        const child = spawn(cmd, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+        });
+        let stderr = '';
+        child.stderr?.on('data', b => { stderr += b.toString('utf8'); });
+        child.on('error', err => resolve({ ok: false, error: err.message }));
+        child.on('close', async () => {
+            invalidateCliStatus(cliId);
+            const status = await detectCli(cli).catch(() => undefined);
+            resolve({ ok: true, status, error: stderr.trim() ? stderr.trim().slice(0, 200) : undefined });
+        });
+    });
+}

package/dist/agent/cli/catalog.js

@@ -0,0 +1,40 @@
+/**
+ * CLI catalog — merges the recommended registry with live detection status.
+ */
+import { getRecommendedClis } from './registry.js';
+import { detectCli, getCachedCliStatus, currentPlatform } from './detector.js';
+import { resolveAutoInstallSpec } from './auth.js';
+export async function getCliCatalog() {
+    const recs = getRecommendedClis();
+    const platform = currentPlatform();
+    const results = await Promise.all(recs.map(async (cli) => {
+        const cached = getCachedCliStatus(cli.id);
+        const status = cached ?? await detectCli(cli);
+        const auto = resolveAutoInstallSpec(cli, platform);
+        return {
+            id: cli.id,
+            binary: cli.binary,
+            name: cli.name,
+            description: cli.description,
+            descriptionZh: cli.descriptionZh,
+            category: cli.category,
+            iconSlug: cli.iconSlug,
+            iconUrl: cli.iconUrl,
+            homepage: cli.homepage,
+            install: cli.install,
+            auth: cli.auth,
+            state: status.state,
+            version: status.version,
+            authDetail: status.authDetail,
+            platform,
+            autoInstall: auto ? { label: auto.label } : undefined,
+        };
+    }));
+    return results;
+}
+export async function refreshCliStatus(id) {
+    const cli = getRecommendedClis().find(c => c.id === id);
+    if (!cli)
+        return undefined;
+    return await detectCli(cli);
+}

package/dist/agent/cli/detector.js

@@ -0,0 +1,136 @@
+/**
+ * CLI detector — checks whether a CLI binary is on PATH, what version it is,
+ * and whether the user is already signed in.
+ *
+ * Results are cached with a short TTL so catalog rendering stays snappy.
+ */
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+const DETECT_TTL_MS = 30_000;
+const cache = new Map();
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function runArgv(argv, timeoutMs) {
+    return new Promise((resolve) => {
+        const [cmd, ...rest] = argv;
+        execFile(cmd, rest, {
+            timeout: timeoutMs,
+            env: { ...process.env, NO_COLOR: '1', CLICOLOR: '0', TERM: 'dumb' },
+            shell: false,
+            windowsHide: true,
+        }, (err, stdout, stderr) => {
+            const code = err?.code;
+            const exitCode = typeof code === 'number' ? code : (err ? 1 : 0);
+            resolve({
+                ok: !err,
+                stdout: stdout?.toString() || '',
+                stderr: stderr?.toString() || '',
+                code: typeof exitCode === 'number' ? exitCode : null,
+            });
+        });
+    });
+}
+function which(binary) {
+    const isWin = process.platform === 'win32';
+    const exts = isWin ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+    const sep = isWin ? ';' : ':';
+    const pathDirs = (process.env.PATH || '').split(sep);
+    for (const dir of pathDirs) {
+        if (!dir)
+            continue;
+        for (const ext of exts) {
+            const candidate = path.join(dir, binary + ext);
+            try {
+                const stat = fs.statSync(candidate);
+                if (stat.isFile())
+                    return candidate;
+            }
+            catch { /* next */ }
+        }
+    }
+    return null;
+}
+function extractVersion(stdout, stderr) {
+    const text = (stdout || stderr).trim();
+    if (!text)
+        return undefined;
+    const firstLine = text.split(/\r?\n/, 1)[0].trim();
+    // Common patterns: "gh version 2.56.0 (...)" / "1.2.3" / "aws-cli/2.x ..."
+    const m = firstLine.match(/\b(\d+\.\d+(?:\.\d+)?(?:[-.+][0-9A-Za-z.]+)?)\b/);
+    return m ? m[1] : firstLine.slice(0, 80);
+}
+function trimDetail(s) {
+    const text = s.trim();
+    if (!text)
+        return undefined;
+    const first = text.split(/\r?\n/, 1)[0].trim();
+    return first.slice(0, 200);
+}
+// ---------------------------------------------------------------------------
+// Public
+// ---------------------------------------------------------------------------
+export function getCachedCliStatus(id) {
+    const cached = cache.get(id);
+    if (!cached)
+        return undefined;
+    if (Date.now() - cached.checkedAt > DETECT_TTL_MS)
+        return undefined;
+    return cached;
+}
+export function invalidateCliStatus(id) {
+    if (id)
+        cache.delete(id);
+    else
+        cache.clear();
+}
+export async function detectCli(cli) {
+    const binaryPath = which(cli.binary);
+    if (!binaryPath) {
+        const status = {
+            id: cli.id, binary: cli.binary, state: 'not_installed', checkedAt: Date.now(),
+        };
+        cache.set(cli.id, status);
+        return status;
+    }
+    // Installed — read version, best-effort.
+    let version;
+    if (cli.versionArgv && cli.versionArgv.length) {
+        const v = await runArgv(cli.versionArgv, 5_000);
+        version = extractVersion(v.stdout, v.stderr);
+    }
+    if (cli.auth.type === 'none' || !cli.auth.statusArgv || cli.auth.statusArgv.length === 0) {
+        const status = {
+            id: cli.id, binary: cli.binary, state: 'ready', version, checkedAt: Date.now(),
+        };
+        cache.set(cli.id, status);
+        return status;
+    }
+    const result = await runArgv(cli.auth.statusArgv, 6_000);
+    // Some CLIs (gcloud) report success via exit 0 but emit empty output when no
+    // account is configured — fall back to a content check when declared.
+    const patternOk = !cli.auth.statusReadyPattern
+        || new RegExp(cli.auth.statusReadyPattern).test(result.stdout);
+    const state = (result.ok && patternOk) ? 'ready' : 'installed_not_auth';
+    const status = {
+        id: cli.id, binary: cli.binary, state, version,
+        authDetail: state === 'ready' ? trimDetail(result.stdout) : trimDetail(result.stderr || result.stdout),
+        checkedAt: Date.now(),
+    };
+    cache.set(cli.id, status);
+    return status;
+}
+/** Best-effort platform key for picking install commands. */
+export function currentPlatform() {
+    if (process.platform === 'darwin')
+        return 'darwin';
+    if (process.platform === 'win32')
+        return 'win';
+    return 'linux';
+}
+/** Where AWS credentials go for the `token` auth flow. */
+export function awsCredentialsPath() {
+    return path.join(os.homedir(), '.aws', 'credentials');
+}

package/dist/agent/cli/index.js

@@ -0,0 +1,7 @@
+/**
+ * Barrel entry for the CLI extension module.
+ */
+export { getRecommendedClis, getRecommendedCli, } from './registry.js';
+export { detectCli, getCachedCliStatus, invalidateCliStatus, currentPlatform, } from './detector.js';
+export { getCliCatalog, refreshCliStatus, } from './catalog.js';
+export { startCliAuthSession, getAuthSession, cancelAuthSession, applyCliToken, logoutCli, startCliInstallSession, resolveAutoInstallSpec, } from './auth.js';

package/dist/agent/cli/registry.js

@@ -0,0 +1,33 @@
+/**
+ * CLI tool registry — curated command-line tools agents commonly need.
+ *
+ * Each entry declares how to install the binary on each OS, how to detect the
+ * install / auth state, and (optionally) how to drive the sign-in flow.
+ *
+ * Two auth types are supported today:
+ *   - oauth-web: the CLI has a first-party `<cli> auth login --web` flavor that
+ *     prints a device code and opens the browser. We spawn it, stream output,
+ *     and poll the status command to know when the user finished in the browser.
+ *   - token: the user pastes an API key; we set it via the CLI's config command
+ *     (or via env var for CLIs that only read from env).
+ *
+ * Keep this list opinionated and small — better to nail the common case than to
+ * ship a wall of half-working entries.
+ */
+// ---------------------------------------------------------------------------
+// Recommended CLI tools — data lives in src/catalog/
+//
+// This module owns the *types* and helper functions. Edit
+// `src/catalog/cli-tools.ts` to add or hide a CLI tool entry.
+// ---------------------------------------------------------------------------
+import { CLI_TOOLS } from '../../catalog/index.js';
+const RECOMMENDED_CLIS = CLI_TOOLS;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export function getRecommendedClis() {
+    return RECOMMENDED_CLIS;
+}
+export function getRecommendedCli(id) {
+    return RECOMMENDED_CLIS.find(c => c.id === id);
+}

package/dist/agent/driver.js

@@ -0,0 +1,39 @@
+/**
+ * agent-driver.ts — Agent driver interface and registry.
+ *
+ * Each CLI agent (claude, codex, gemini, ...) implements AgentDriver.
+ * Register with `registerDriver()`, look up with `getDriver()`.
+ */
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const drivers = new Map();
+export function registerDriver(d) { drivers.set(d.id, d); }
+export function getDriver(id) {
+    const d = drivers.get(id);
+    if (!d)
+        throw new Error(`Unknown agent: ${id}. Available: ${[...drivers.keys()].join(', ')}`);
+    return d;
+}
+export function hasDriver(id) { return drivers.has(id); }
+export function allDrivers() { return [...drivers.values()]; }
+export function allDriverIds() { return [...drivers.keys()]; }
+export function shutdownAllDrivers() {
+    for (const d of drivers.values())
+        d.shutdown();
+}
+const DEFAULT_CAPABILITIES = { fork: false, modelSwitch: true, workflow: false };
+export function getDriverCapabilities(id) {
+    const d = drivers.get(id);
+    if (!d?.capabilities)
+        return DEFAULT_CAPABILITIES;
+    return { ...DEFAULT_CAPABILITIES, ...d.capabilities };
+}
+/**
+ * Provider kinds this driver can route through. Empty array means the driver
+ * declared no compatibility (so no Profiles will be listed for it). Callers
+ * should treat this as the filter for cross-provider model offerings.
+ */
+export function getAcceptedProviderKinds(id) {
+    return drivers.get(id)?.acceptedProviderKinds ?? [];
+}