@north-light/crouter 0.3.154

package/dist/commands/sys/setup-core.js

@@ -0,0 +1,582 @@
+import { spawnSync } from 'node:child_process';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { BINDING_CATALOG, normalizeGesture, splitGestureExpression, inboxShortcut, resolveKeybindings, } from '../../core/keybindings/index.js';
+import { builtinPiPackageDir } from '../../core/scope.js';
+import { readJsonIfExists } from '../../core/fs-utils.js';
+import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
+import { installTmuxBindings } from '../../core/runtime/tmux-chrome.js';
+import { globalHumanloopHealth, globalHumanloopInstallCommand } from '../../core/runtime/package-health.js';
+import { registerCrouterRoot } from '../human/shared.js';
+import { installFromMarketplace } from '../pkg/plugin-manage.js';
+import { findPluginByName } from '../../core/resolver.js';
+function isKeybindingsObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function cloneKeybindings(value) {
+    if (!isKeybindingsObject(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([id, gestures]) => [
+        id,
+        Array.isArray(gestures) ? [...gestures] : gestures,
+    ]));
+}
+/** Transactional sparse keybinding draft used by the full-screen setup tab. */
+export class SetupKeybindingsDraft {
+    expected;
+    baseline;
+    current;
+    baselineInvalidRoot;
+    invalidRoot;
+    resolutionCache;
+    constructor(rawKeybindings) {
+        this.expected = rawKeybindings;
+        this.baseline = cloneKeybindings(rawKeybindings);
+        this.current = cloneKeybindings(rawKeybindings);
+        this.baselineInvalidRoot = rawKeybindings !== undefined && !isKeybindingsObject(rawKeybindings) ? rawKeybindings : undefined;
+        this.invalidRoot = this.baselineInvalidRoot;
+    }
+    get dirty() {
+        return !isDeepStrictEqual(this.current, this.baseline)
+            || !isDeepStrictEqual(this.invalidRoot, this.baselineInvalidRoot);
+    }
+    overrides() {
+        return cloneKeybindings(this.current);
+    }
+    expectedKeybindings() {
+        return this.expected;
+    }
+    resolution() {
+        if (this.resolutionCache === undefined) {
+            this.resolutionCache = resolveKeybindings(this.invalidRoot === undefined ? this.current : this.invalidRoot);
+        }
+        return this.resolutionCache;
+    }
+    /** True while the persisted `keybindings` root is a non-object (e.g. a string):
+     *  edits cannot be layered onto an invalid root, so the tab must reset-all first. */
+    hasInvalidRoot() {
+        return this.invalidRoot !== undefined;
+    }
+    expression(id) {
+        return this.resolution().gestures(id).join(', ');
+    }
+    edit(id, expression) {
+        if (this.invalidRoot !== undefined) {
+            return {
+                ok: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'invalid-keybindings',
+                        offendingValue: this.invalidRoot,
+                        message: 'Reset all before editing: the saved keybindings root is invalid.',
+                    }],
+            };
+        }
+        const definition = BINDING_CATALOG.find((candidate) => candidate.id === id);
+        let gestures;
+        try {
+            gestures = expression.trim() === ''
+                ? []
+                : splitGestureExpression(expression).map((gesture) => normalizeGesture(gesture.trim(), definition));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                diagnostics: [{
+                        severity: 'error',
+                        code: 'invalid-override',
+                        bindingId: id,
+                        offendingValue: expression,
+                        message: error instanceof Error ? error.message : String(error),
+                    }],
+            };
+        }
+        const deduped = [...new Set(gestures)];
+        // Sparse invariant: a member is stored only when it changes the effective
+        // resolution. If the committed gestures equal the catalog default for this
+        // id, drop the member instead of recording a redundant override — otherwise
+        // committing an unchanged default flips the row to a spurious user/unsaved
+        // state that persistence would then strip anyway.
+        const withoutId = { ...this.current };
+        delete withoutId[id];
+        const defaultGestures = [...resolveKeybindings(withoutId).gestures(id)];
+        const prospective = isDeepStrictEqual(deduped, defaultGestures)
+            ? withoutId
+            : { ...this.current, [id]: deduped };
+        const resolution = resolveKeybindings(prospective);
+        const relevant = resolution.diagnostics.filter((diagnostic) => diagnostic.bindingId === id || diagnostic.relatedBindingIds?.includes(id));
+        if (relevant.length > 0)
+            return { ok: false, diagnostics: relevant };
+        this.current = prospective;
+        this.resolutionCache = undefined;
+        return { ok: true, diagnostics: resolution.diagnostics };
+    }
+    unbind(id) {
+        return this.edit(id, '');
+    }
+    resetRow(id) {
+        delete this.current[id];
+        this.resolutionCache = undefined;
+    }
+    resetAll() {
+        this.current = {};
+        this.invalidRoot = undefined;
+        this.resolutionCache = undefined;
+    }
+    discard() {
+        this.current = cloneKeybindings(this.baseline);
+        this.invalidRoot = this.baselineInvalidRoot;
+        this.resolutionCache = undefined;
+    }
+    markSaved(overrides) {
+        this.expected = Object.keys(overrides).length === 0 ? undefined : cloneKeybindings(overrides);
+        this.baseline = cloneKeybindings(overrides);
+        this.current = cloneKeybindings(overrides);
+        this.baselineInvalidRoot = undefined;
+        this.invalidRoot = undefined;
+        this.resolutionCache = undefined;
+    }
+}
+const PACKAGE_COPY = {
+    'crtr-extensions': {
+        name: 'pi-crtr-extensions',
+        shortDescription: 'crtr companion extensions — command palette, help gating, statusline, subscription/OAuth rotation, nested context.',
+        longDescription: 'Bundles the extensions built for crtr: a crtr slash-command palette, crtr/crouter help gating, surfacing of Claude Code marketplace plugin commands, nested AGENTS.md/CLAUDE.md loading, a model/subscription/token statusline badge, OAuth login + rotation across multiple Claude subscriptions (provider-rotation), and system-prompt trimming. The OAuth/rotation piece is what lets crtr authenticate your Claude account.',
+    },
+    'mode-switch': {
+        name: 'pi-mode-switch',
+        shortDescription: 'Alt+Shift+P cycles spec / plan / normal modes; injects mode-specific guidance on change.',
+        longDescription: 'Press Alt+Shift+P to rotate between three operating modes — spec (requirements gathering), plan (design before code), and normal (execution). Each switch appends mode-tailored guidance to keep the agent in the right gear.',
+    },
+    'oauth-adapter': {
+        name: 'pi-claude-oauth-adapter',
+        shortDescription: 'Anthropic OAuth / Claude Code credential compatibility for pi.',
+        longDescription: 'Third-party adapter (minzique/dotfiles-agents) letting pi authenticate with Claude using Claude Code OAuth credentials. Installed from npm, pinned to 0.1.2.',
+    },
+    'capture-plugin': {
+        name: 'capture',
+        shortDescription: 'crtr plugin mounting `crtr capture` — browser automation and UI measurement over CDP.',
+        longDescription: 'Installs the `capture` plugin from the official crtr marketplace. It mounts `crtr capture` as a transparent passthrough to the external Capture CLI (`npm install -g @crouton-kit/capture`) for CDP screenshots, rendered-geometry measurement, HAR, accessibility trees, and JS execution against a live page. Uncheck it on a machine where agents never drive a browser — the command then costs nothing in their root prompt.',
+    },
+};
+const PACKAGE_SOURCES = {
+    'crtr-extensions': { kind: 'local-path', source: builtinPiPackageDir('pi-crtr-extensions') },
+    'mode-switch': { kind: 'local-path', source: builtinPiPackageDir('pi-mode-switch') },
+    'oauth-adapter': { kind: 'npm', source: 'npm:pi-claude-oauth-adapter@0.1.2' },
+    'capture-plugin': { kind: 'marketplace-plugin', source: 'crouter-official-marketplace/capture' },
+};
+const LOCAL_PACKAGE_NAME_ALIASES = {
+    'crtr-extensions': ['pi-crtr-extensions'],
+    'mode-switch': ['pi-mode-switch'],
+    'oauth-adapter': [],
+    'capture-plugin': [],
+};
+export function buildSetupManifest(resolveBuiltinPackageDir = builtinPiPackageDir) {
+    return [
+        'crtr-extensions',
+        'mode-switch',
+        'oauth-adapter',
+        'capture-plugin',
+    ].map((id) => {
+        const copy = PACKAGE_COPY[id];
+        const source = PACKAGE_SOURCES[id].kind === 'local-path'
+            ? resolveBuiltinPackageDir(copy.name)
+            : PACKAGE_SOURCES[id].source;
+        return {
+            id,
+            name: copy.name,
+            sourceKind: PACKAGE_SOURCES[id].kind,
+            installSource: source,
+            shortDescription: copy.shortDescription,
+            longDescription: copy.longDescription,
+        };
+    });
+}
+function expandTilde(pathValue, homeDir) {
+    if (pathValue === '~')
+        return homeDir;
+    if (pathValue.startsWith('~/'))
+        return join(homeDir, pathValue.slice(2));
+    return pathValue;
+}
+function npmPackageName(source) {
+    if (!source.startsWith('npm:'))
+        return null;
+    const spec = source.slice(4);
+    const versionIndex = spec.startsWith('@') ? spec.indexOf('@', 1) : spec.lastIndexOf('@');
+    return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+}
+export function normalizePackageIdentity(source, settingsDir, homeDir) {
+    const npmName = npmPackageName(source);
+    if (npmName !== null)
+        return `npm:${npmName}`;
+    const expanded = expandTilde(source, homeDir);
+    return resolve(settingsDir, expanded);
+}
+function packageNameIdentity(name) {
+    return `package:${name}`;
+}
+function localPackageNameIdentities(source) {
+    if (source.startsWith('npm:'))
+        return [];
+    return [packageNameIdentity(basename(source))];
+}
+function manifestIdentities(entry, settingsDir, homeDir) {
+    const identities = [normalizePackageIdentity(entry.installSource, settingsDir, homeDir)];
+    if (entry.sourceKind === 'local-path') {
+        identities.push(packageNameIdentity(entry.name));
+        for (const alias of LOCAL_PACKAGE_NAME_ALIASES[entry.id])
+            identities.push(packageNameIdentity(alias));
+    }
+    return identities;
+}
+export function detectInstalledSetupPackageIds(settingsJson, manifest = buildSetupManifest(), settingsPath = join(homedir(), '.pi', 'agent', 'settings.json'), homeDir = homedir()) {
+    const settingsDir = dirname(settingsPath);
+    const installed = new Set();
+    const manifestByIdentity = new Map();
+    for (const entry of manifest) {
+        for (const identity of manifestIdentities(entry, settingsDir, homeDir)) {
+            manifestByIdentity.set(identity, entry.id);
+        }
+    }
+    const rawPackages = settingsJson && typeof settingsJson === 'object'
+        ? settingsJson.packages
+        : undefined;
+    if (!Array.isArray(rawPackages))
+        return installed;
+    for (const raw of rawPackages) {
+        const source = typeof raw === 'string'
+            ? raw
+            : raw && typeof raw === 'object' && typeof raw.source === 'string'
+                ? raw.source
+                : null;
+        if (source === null)
+            continue;
+        const identities = [
+            normalizePackageIdentity(source, settingsDir, homeDir),
+            ...localPackageNameIdentities(source),
+        ];
+        for (const identity of identities) {
+            const id = manifestByIdentity.get(identity);
+            if (id !== undefined)
+                installed.add(id);
+        }
+    }
+    return installed;
+}
+export function detectCommandOnPath(command) {
+    const res = spawnSync('sh', ['-lc', `command -v ${command} >/dev/null 2>&1`], { stdio: 'ignore' });
+    return res.status === 0;
+}
+export function detectPackageManager(platform = process.platform, commandExists = detectCommandOnPath) {
+    switch (platform) {
+        case 'darwin':
+            return commandExists('brew') ? 'brew' : 'manual';
+        case 'linux':
+            if (commandExists('apt-get'))
+                return 'apt-get';
+            if (commandExists('dnf'))
+                return 'dnf';
+            if (commandExists('pacman'))
+                return 'pacman';
+            return 'manual';
+        default:
+            return 'manual';
+    }
+}
+export function buildSystemInstallPlan(tool, packageManager, installed) {
+    const label = `Install ${tool}`;
+    if (installed) {
+        return {
+            tool,
+            label,
+            installed: true,
+            checked: false,
+            packageManager,
+            command: null,
+            hint: 'already installed',
+            autoInstall: false,
+        };
+    }
+    const packageName = tool === 'nvim' ? 'neovim' : 'tmux';
+    switch (packageManager) {
+        case 'brew':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `brew install ${packageName}`,
+                hint: 'Homebrew install',
+                autoInstall: true,
+            };
+        case 'apt-get':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo apt-get update && sudo apt-get install -y ${packageName}`,
+                hint: 'apt-get install',
+                autoInstall: true,
+            };
+        case 'dnf':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo dnf install -y ${packageName}`,
+                hint: 'dnf install',
+                autoInstall: true,
+            };
+        case 'pacman':
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: true,
+                packageManager,
+                command: `sudo pacman -S --noconfirm ${packageName}`,
+                hint: 'pacman install',
+                autoInstall: true,
+            };
+        default:
+            return {
+                tool,
+                label,
+                installed: false,
+                checked: false,
+                packageManager: 'manual',
+                command: null,
+                hint: `manual install required for ${tool}`,
+                autoInstall: false,
+            };
+    }
+}
+export function buildSystemToolState(tool, packageManager, commandExists = detectCommandOnPath) {
+    const installed = commandExists(tool);
+    return {
+        tool,
+        installed,
+        plan: buildSystemInstallPlan(tool, packageManager, installed),
+    };
+}
+export function resolveSettingsPath(homeDir = homedir()) {
+    return join(homeDir, '.pi', 'agent', 'settings.json');
+}
+export function resolveExaKeyPath(homeDir = homedir()) {
+    return join(homeDir, '.crouter', 'exa.key');
+}
+function detectApiKey(envVar, keyPath) {
+    if ((process.env[envVar] ?? '').trim() !== '')
+        return { present: true, source: 'env' };
+    try {
+        if (readFileSync(keyPath, 'utf8').trim() !== '')
+            return { present: true, source: 'file' };
+    }
+    catch { /* absent/unreadable → not present */ }
+    return { present: false };
+}
+export function detectExaKey(homeDir = homedir()) {
+    return detectApiKey('EXA_API_KEY', resolveExaKeyPath(homeDir));
+}
+export function buildSetupInitialState(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const settingsPath = opts.settingsPath ?? resolveSettingsPath(homeDir);
+    const manifest = opts.manifest ?? buildSetupManifest(builtinPiPackageDir);
+    const settingsJson = readJsonIfExists(settingsPath);
+    const installedPackageIds = detectInstalledSetupPackageIds(settingsJson, manifest, settingsPath, homeDir);
+    for (const id of detectInstalledMarketplacePlugins(manifest))
+        installedPackageIds.add(id);
+    const commandExists = opts.commandExists ?? detectCommandOnPath;
+    const packageManager = opts.packageManager ?? detectPackageManager(process.platform, commandExists);
+    const systemTools = ['tmux', 'nvim'].map((tool) => buildSystemToolState(tool, packageManager, commandExists));
+    return { manifest, installedPackageIds, systemTools, exaKeyPath: resolveExaKeyPath(homeDir) };
+}
+export function buildSetupStaticInstructions(opts) {
+    return {
+        headline: 'crtr sys setup (non-interactive)',
+        packageLines: opts.manifest.map((entry) => {
+            const installed = opts.installedPackageIds.has(entry.id) ? 'installed' : 'not installed';
+            return `- ${entry.name} — ${entry.shortDescription} (${installed})`;
+        }),
+        systemLines: opts.systemPlans.map((plan) => {
+            if (plan.installed)
+                return `- ${plan.tool}: ✓ installed`;
+            if (plan.command)
+                return `- ${plan.tool}: ${plan.command}`;
+            return `- ${plan.tool}: ${plan.hint}`;
+        }),
+        exaLine: `- Exa key: write to ${opts.exaKeyPath} or set EXA_API_KEY`,
+        footer: 'Run `crtr sys setup` in a TTY to open the wizard.',
+    };
+}
+export function renderSetupStaticInstructions(state) {
+    const instructions = buildSetupStaticInstructions({
+        manifest: state.manifest,
+        installedPackageIds: state.installedPackageIds,
+        systemPlans: state.systemTools.map((tool) => tool.plan),
+        exaKeyPath: state.exaKeyPath,
+    });
+    return [
+        instructions.headline,
+        '',
+        'Provider login: open the wizard in a TTY and use the Providers tab (same flow as /login) to authenticate a model provider.',
+        '',
+        'Packages:',
+        ...instructions.packageLines,
+        '',
+        'System deps:',
+        ...instructions.systemLines,
+        '',
+        instructions.exaLine,
+        '',
+        `Inbox popup: the inbox-toggle key (${inboxShortcut() ?? 'disabled'}) is a crouter keybinding — view or rebind it in the \`crtr sys setup\` keybindings tab; it is installed on the same tmux server as every other crouter binding. \`crtr sys setup\` also registers known nodes' interaction roots (best-effort).`,
+        instructions.footer,
+    ].join('\n') + '\n';
+}
+function runShellCommand(command) {
+    const result = spawnSync('sh', ['-lc', command], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        throw new Error(`command failed: ${command}`);
+    }
+}
+function installPiPackage(source, piCliPath = resolveBundledPiCliPath()) {
+    const result = spawnSync(process.execPath, [piCliPath, 'install', source], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        throw new Error(`pi install failed: ${source}`);
+    }
+}
+/** Keep the PATH-global executable used by the tmux inbox binding at least as
+ * new as crouter's bundled humanloop library. This is deliberately separate
+ * from pi's companion package install: `hl` is a global npm binary, not a pi
+ * package entry in settings.json. */
+function ensureGlobalHumanloop() {
+    if (globalHumanloopHealth().current)
+        return false;
+    const command = globalHumanloopInstallCommand();
+    process.stdout.write(`Updating global hl CLI: ${command}\n`);
+    runShellCommand(command);
+    return true;
+}
+export async function writeExaKey(exaKeyPath, exaKey) {
+    await mkdir(dirname(exaKeyPath), { recursive: true });
+    await writeFile(exaKeyPath, `${exaKey}\n`, 'utf8');
+    await chmod(exaKeyPath, 0o600).catch(() => undefined);
+}
+/** Refresh crouter-owned tmux bindings and register the one canvas node root
+ * with humanloop so every bridge ticket can call back into `human _deliver`.
+ * Both are best-effort: setup must never fail because tmux or humanloop is unavailable. */
+export async function reconcileInboxFrontDoor() {
+    try {
+        installTmuxBindings();
+    }
+    catch { /* best-effort: no tmux server */ }
+    try {
+        registerCrouterRoot();
+        return { interactionRootsRegistered: 1 };
+    }
+    catch {
+        return { interactionRootsRegistered: 0 };
+    }
+}
+export function summarizeSetupExecution(result) {
+    return {
+        installed: [...result.installedPackages, ...result.installedSystemDeps],
+        skipped: [...result.skippedPackages, ...result.skippedSystemDeps],
+        exaKeyWritten: result.exaKeyWritten,
+        exaKeyPath: result.exaKeyPath,
+        interactionRootsRegistered: result.interactionRootsRegistered,
+    };
+}
+export function formatSetupExecutionSummary(summary) {
+    return [
+        'crtr sys setup complete',
+        summary.installed.length > 0 ? `installed: ${summary.installed.join(', ')}` : 'installed: none',
+        summary.skipped.length > 0 ? `skipped: ${summary.skipped.join(', ')}` : 'skipped: none',
+        summary.exaKeyWritten ? `exa key written: ${summary.exaKeyPath}` : 'exa key written: no',
+        `interaction roots registered: ${summary.interactionRootsRegistered}`,
+    ].join('\n') + '\n';
+}
+/** Marketplace-plugin manifest entries already installed in any scope — the
+ *  plugin registry is their install record, not pi's settings.json. */
+function detectInstalledMarketplacePlugins(manifest) {
+    const installed = [];
+    for (const entry of manifest) {
+        if (entry.sourceKind !== 'marketplace-plugin')
+            continue;
+        try {
+            if (findPluginByName(entry.name) !== null)
+                installed.push(entry.id);
+        }
+        catch { /* unreadable scope config — treat as not installed */ }
+    }
+    return installed;
+}
+export async function executeSetupSubmission(submission) {
+    const installedPackages = [];
+    const skippedPackages = [];
+    const installedSystemDeps = [];
+    const skippedSystemDeps = [];
+    for (const entry of submission.packages) {
+        if (submission.installedPackageIds.has(entry.id)) {
+            skippedPackages.push(`${entry.name} (already installed)`);
+            continue;
+        }
+        if (entry.sourceKind === 'marketplace-plugin') {
+            const [marketplace, plugin] = entry.installSource.split('/');
+            try {
+                installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
+                installedPackages.push(entry.name);
+            }
+            catch (e) {
+                // A marketplace that will not refresh (offline, diverged cache) must not
+                // abort the rest of setup.
+                skippedPackages.push(`${entry.name} (${e instanceof Error ? e.message : String(e)})`);
+            }
+            continue;
+        }
+        installPiPackage(entry.installSource);
+        installedPackages.push(entry.name);
+    }
+    for (const plan of submission.systemDeps) {
+        if (!plan.checked || plan.installed) {
+            skippedSystemDeps.push(`${plan.tool} (already installed)`);
+            continue;
+        }
+        if (!plan.autoInstall || !plan.command) {
+            skippedSystemDeps.push(`${plan.tool} (${plan.hint})`);
+            continue;
+        }
+        runShellCommand(plan.command);
+        installedSystemDeps.push(plan.tool);
+    }
+    if (ensureGlobalHumanloop())
+        installedPackages.push('global hl CLI');
+    else
+        skippedPackages.push('global hl CLI (current)');
+    const exaKeyWritten = submission.exaKey.trim() !== '';
+    if (exaKeyWritten) {
+        await writeExaKey(submission.exaKeyPath, submission.exaKey);
+    }
+    // Front-door reconciliation: refresh the crouter-owned tmux bindings and
+    // register known nodes' interaction roots for `human _deliver`. Both are
+    // best-effort.
+    const { interactionRootsRegistered } = await reconcileInboxFrontDoor();
+    return summarizeSetupExecution({
+        installedPackages,
+        skippedPackages,
+        installedSystemDeps,
+        skippedSystemDeps,
+        exaKeyWritten,
+        exaKeyPath: submission.exaKeyPath,
+        interactionRootsRegistered,
+    });
+}