@north-light/api 0.3.580 → 0.3.587

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

@@ -0,0 +1,890 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { homedir, tmpdir } from 'node:os';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { piAgentDir } from '../../core/runtime/package-health.js';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { BINDING_CATALOG, normalizeGesture, splitGestureExpression, inboxShortcut, resolveKeybindings, } from '../../core/keybindings/index.js';
+import { runtimeManifest } from './shared.js';
+import { atomicWriteJson, readJsonIfExists, readJsonOrNull } from '../../core/fs-utils.js';
+import { resolveBundledPiCliPath } from '../../core/runtime/pi-cli.js';
+import { crtrVersion } from '../../shared/crtr-version.js';
+import { installTmuxBindings } from '../../core/runtime/tmux-chrome.js';
+import { normalizeTmuxPassthrough } from '../../core/config.js';
+import { detectNerdFont, nerdFontInstallCommand, createCurlPercentReader, NERD_FONT_MANUAL_LINUX_COMMAND, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
+import { startProgressBar } from '../../core/runtime/progress-bar.js';
+import { ensureRenderer, isRendererReady } from '../../core/termrender/termrender.js';
+import { installFromMarketplace, isMarketplaceRelativeSource } from '../pkg/plugin-manage.js';
+import { requiredPluginEnv } from '../../core/plugin-env.js';
+import { readPluginManifest } from '../../core/manifest.js';
+import { addMarketplace } from '../pkg/market-manage.js';
+import { clone } from '../../core/git.js';
+import { readMarketplaceManifest } from '../../core/manifest.js';
+import { findPluginByName, findMarketplaceByName } from '../../core/resolver.js';
+import { expandTilde } from '../../core/fs-utils.js';
+import { applyTerminalEdit } from './terminal-option.js';
+export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
+export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
+export const OFFICIAL_MARKETPLACE_REF = 'main';
+/** Read declarations without installing or registering a marketplace until confirmation. */
+export function setupPluginEnvFields(packages) {
+    const fields = [];
+    const seen = new Set();
+    const temporary = new Map();
+    try {
+        for (const entry of packages) {
+            if (entry.sourceKind !== 'marketplace-plugin')
+                continue;
+            const [marketplaceName, pluginName] = entry.installSource.split('/');
+            if (!marketplaceName || !pluginName)
+                continue;
+            const installed = findPluginByName(pluginName, 'user')?.manifest;
+            const registered = findMarketplaceByName(marketplaceName, 'user');
+            let marketplace = registered;
+            if (!marketplace && !installed && marketplaceName === OFFICIAL_MARKETPLACE_NAME) {
+                try {
+                    let root = temporary.get(marketplaceName);
+                    if (!root) {
+                        root = mkdtempSync(join(tmpdir(), 'crtr-setup-market-'));
+                        temporary.set(marketplaceName, root);
+                        clone(OFFICIAL_MARKETPLACE_URL, join(root, 'checkout'), { ref: OFFICIAL_MARKETPLACE_REF, depth: 1 });
+                    }
+                    const checkout = join(root, 'checkout');
+                    const manifest = readMarketplaceManifest(checkout);
+                    if (manifest)
+                        marketplace = { root: checkout, manifest };
+                }
+                catch { /* An unavailable optional marketplace is reported at installation. */ }
+            }
+            const source = marketplace?.manifest.plugins.find((plugin) => plugin.name === pluginName)?.source;
+            const manifest = source && isMarketplaceRelativeSource(source)
+                ? readPluginManifest(join(marketplace.root, source)) ?? installed
+                : installed;
+            if (!manifest)
+                continue;
+            for (const name of requiredPluginEnv(manifest.env)) {
+                if (seen.has(name))
+                    continue;
+                seen.add(name);
+                fields.push({ name, plugin: pluginName, declaration: manifest.env[name] });
+            }
+        }
+    }
+    finally {
+        for (const root of temporary.values())
+            rmSync(root, { recursive: true, force: true });
+    }
+    return fields;
+}
+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;
+    expectedPassthrough;
+    baselinePassthrough;
+    currentPassthrough;
+    constructor(rawKeybindings, rawTmuxPassthrough = undefined) {
+        this.expected = rawKeybindings;
+        this.baseline = cloneKeybindings(rawKeybindings);
+        this.current = cloneKeybindings(rawKeybindings);
+        this.baselineInvalidRoot = rawKeybindings !== undefined && !isKeybindingsObject(rawKeybindings) ? rawKeybindings : undefined;
+        this.invalidRoot = this.baselineInvalidRoot;
+        this.expectedPassthrough = rawTmuxPassthrough;
+        this.baselinePassthrough = normalizeTmuxPassthrough(rawTmuxPassthrough);
+        this.currentPassthrough = [...this.baselinePassthrough];
+    }
+    get dirty() {
+        return !isDeepStrictEqual(this.current, this.baseline)
+            || !isDeepStrictEqual(this.invalidRoot, this.baselineInvalidRoot)
+            || !isDeepStrictEqual(this.currentPassthrough, this.baselinePassthrough);
+    }
+    overrides() {
+        return cloneKeybindings(this.current);
+    }
+    expectedKeybindings() {
+        return this.expected;
+    }
+    tmuxPassthrough() {
+        return [...this.currentPassthrough];
+    }
+    expectedTmuxPassthrough() {
+        return this.expectedPassthrough;
+    }
+    usesTmuxPassthrough(id) {
+        return this.currentPassthrough.includes(id);
+    }
+    toggleTmuxPassthrough(id) {
+        this.currentPassthrough = this.currentPassthrough.includes(id)
+            ? this.currentPassthrough.filter((candidate) => candidate !== id)
+            : [...this.currentPassthrough, id];
+    }
+    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.currentPassthrough = [];
+        this.invalidRoot = undefined;
+        this.resolutionCache = undefined;
+    }
+    discard() {
+        this.current = cloneKeybindings(this.baseline);
+        this.currentPassthrough = [...this.baselinePassthrough];
+        this.invalidRoot = this.baselineInvalidRoot;
+        this.resolutionCache = undefined;
+    }
+    markSaved(overrides, tmuxPassthrough = []) {
+        this.expected = Object.keys(overrides).length === 0 ? undefined : cloneKeybindings(overrides);
+        this.baseline = cloneKeybindings(overrides);
+        this.current = cloneKeybindings(overrides);
+        this.expectedPassthrough = tmuxPassthrough.length === 0 ? undefined : [...tmuxPassthrough];
+        this.baselinePassthrough = [...tmuxPassthrough];
+        this.currentPassthrough = [...tmuxPassthrough];
+        this.baselineInvalidRoot = undefined;
+        this.invalidRoot = undefined;
+        this.resolutionCache = undefined;
+    }
+}
+const PACKAGE_COPY = {
+    'official-marketplace': {
+        name: OFFICIAL_MARKETPLACE_NAME,
+        shortDescription: 'the official crtr plugin catalog — registered as a source so its plugins are installable by ref.',
+        longDescription: 'Shallow-clones github.com/crouton-labs/crouter-official-marketplace into the user scope and registers it, which is what makes `crtr pkg plugin install crouter-official-marketplace/<name>` resolve and what fills `crtr pkg market browse`. Registering the source installs no plugin by itself. Uncheck it on a machine that should reach no external catalog — a plugin selected below still registers the marketplace it comes from, because its ref cannot resolve otherwise.',
+    },
+    'crtr-extensions': {
+        name: 'pi-crtr-extensions',
+        shortDescription: 'crtr companion extensions — command palette, help gating, 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, 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.',
+    },
+    '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.2.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.',
+    },
+    'exa-search-plugin': {
+        name: 'exa-search',
+        shortDescription: 'crtr plugin mounting `crtr exa-search` — public-web discovery, grounded answers, and content extraction.',
+        longDescription: 'Installs the `exa-search` plugin from the official crtr marketplace. It mounts `crtr exa-search` and calls Exa directly with EXA_API_KEY, collected during install or set through `crtr sys env set --name EXA_API_KEY` in the app env store. Uncheck it on a machine whose agents get web search from somewhere else, such as a Northlight home where the platform serves `crtr search` from its own plugin.',
+    },
+    'dev-plugin': {
+        name: 'dev',
+        shortDescription: 'crtr plugin mounting the development workflow — repository setup, worktrees, pull requests, and a dev track in the tutorial.',
+        longDescription: 'Installs the dev plugin from the official crtr marketplace. It adds the /dev: workflow commands (init, spec, design, plan, pr-loop), mounts crtr dev for a repository\'s own lifecycle commands and Grove instances, and contributes the crtr sys tutorial dev track. Uncheck it on a machine whose agents do not work in source repositories.',
+    },
+};
+const PACKAGE_SOURCES = {
+    'official-marketplace': { kind: 'marketplace-source', source: OFFICIAL_MARKETPLACE_URL },
+    'crtr-extensions': { kind: 'local-path', source: selectedPiPackageDir('pi-crtr-extensions') },
+    'oauth-adapter': { kind: 'npm', source: 'npm:pi-claude-oauth-adapter@0.2.2' },
+    'capture-plugin': { kind: 'marketplace-plugin', source: 'crouter-official-marketplace/capture' },
+    'exa-search-plugin': { kind: 'marketplace-plugin', source: 'crouter-official-marketplace/exa-search' },
+    'dev-plugin': { kind: 'marketplace-plugin', source: 'crouter-official-marketplace/dev' },
+};
+const CRTR_EXTENSION_GLOBS = ['extensions/*.ts', 'extensions/*/index.ts', '!extensions/**/*.d.ts'];
+const LOCAL_PACKAGE_NAME_ALIASES = {
+    'official-marketplace': [],
+    'crtr-extensions': ['pi-crtr-extensions'],
+    'oauth-adapter': [],
+    'capture-plugin': [],
+    'exa-search-plugin': [],
+    'dev-plugin': [],
+};
+function selectedPiPackageDir(name) {
+    return join(runtimeManifest.runtimeHome(), 'selected', 'dist', 'builtin-pi-packages', name);
+}
+export function buildSetupManifest(resolveBuiltinPackageDir = selectedPiPackageDir) {
+    // Order matters at execution: the marketplace source registers before the
+    // plugin whose ref needs it.
+    return [
+        'official-marketplace',
+        'crtr-extensions',
+        'oauth-adapter',
+        'capture-plugin',
+        'exa-search-plugin',
+        'dev-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,
+        };
+    });
+}
+/** One-line description of what installing an entry will actually run — the
+ *  wizard's confirm step and the non-TTY dump both show it. */
+export function packagePlanAction(entry) {
+    switch (entry.sourceKind) {
+        case 'marketplace-source':
+            return `clone + register ${entry.installSource}`;
+        case 'marketplace-plugin':
+            return `crtr pkg plugin install ${entry.installSource}`;
+        default:
+            return `pi install ${entry.installSource}`;
+    }
+}
+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(piAgentDir(), '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 === 'crtr-extensions') {
+                const selected = manifest.find((entry) => entry.id === id);
+                if (normalizePackageIdentity(source, settingsDir, homeDir) !== normalizePackageIdentity(selected.installSource, settingsDir, homeDir)
+                    || !raw || typeof raw !== 'object' || !isDeepStrictEqual(raw.extensions, CRTR_EXTENSION_GLOBS))
+                    continue;
+            }
+            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, commandExists = detectCommandOnPath) {
+    const installed = tool === 'nerd-font' ? detectNerdFont().installed : commandExists(tool);
+    if (installed) {
+        return {
+            tool,
+            installed: true,
+            command: null,
+            hint: 'already installed',
+            autoInstall: false,
+        };
+    }
+    if (tool === 'nerd-font') {
+        const plan = nerdFontInstallCommand(packageManager);
+        return {
+            tool,
+            installed: false,
+            command: plan.command,
+            hint: `${plan.hint} — ${NERD_FONT_SELECT_HINT}`,
+            autoInstall: plan.autoInstall,
+        };
+    }
+    const packageName = tool === 'nvim' ? 'neovim' : 'tmux';
+    switch (packageManager) {
+        case 'brew':
+            return {
+                tool,
+                installed: false,
+                command: `brew install ${packageName}`,
+                hint: 'Homebrew install',
+                autoInstall: true,
+            };
+        case 'apt-get':
+            return {
+                tool,
+                installed: false,
+                command: `sudo apt-get update && sudo apt-get install -y ${packageName}`,
+                hint: 'apt-get install',
+                autoInstall: true,
+            };
+        case 'dnf':
+            return {
+                tool,
+                installed: false,
+                command: `sudo dnf install -y ${packageName}`,
+                hint: 'dnf install',
+                autoInstall: true,
+            };
+        case 'pacman':
+            return {
+                tool,
+                installed: false,
+                command: `sudo pacman -S --noconfirm ${packageName}`,
+                hint: 'pacman install',
+                autoInstall: true,
+            };
+        default:
+            return {
+                tool,
+                installed: false,
+                command: null,
+                hint: `manual install required for ${tool}`,
+                autoInstall: false,
+            };
+    }
+}
+export function resolveSettingsPath(homeDir = homedir()) {
+    return join(homeDir === homedir() ? piAgentDir() : join(homeDir, '.pi', 'agent'), 'settings.json');
+}
+export function buildSetupInitialState(opts = {}) {
+    const homeDir = opts.homeDir ?? homedir();
+    const settingsPath = opts.settingsPath ?? resolveSettingsPath(homeDir);
+    const manifest = opts.manifest ?? buildSetupManifest();
+    const settingsJson = readJsonIfExists(settingsPath);
+    const installedPackageIds = detectInstalledSetupPackageIds(settingsJson, manifest, settingsPath, homeDir);
+    for (const id of detectInstalledMarketplaceEntries(manifest))
+        installedPackageIds.add(id);
+    const commandExists = opts.commandExists ?? detectCommandOnPath;
+    const packageManager = opts.packageManager ?? detectPackageManager(process.platform, commandExists);
+    const systemPlans = ['tmux', 'nvim', 'nerd-font'].map((tool) => buildSystemInstallPlan(tool, packageManager, commandExists));
+    return { manifest, installedPackageIds, systemPlans };
+}
+export function renderSetupStaticInstructions(state) {
+    const packageLines = state.manifest.map((entry) => {
+        const installed = state.installedPackageIds.has(entry.id) ? 'installed' : 'not installed';
+        return `- ${entry.name} — ${entry.shortDescription} (${installed})`;
+    });
+    const systemLines = state.systemPlans.map((plan) => {
+        if (plan.installed)
+            return `- ${plan.tool}: ✓ installed`;
+        if (plan.command)
+            return `- ${plan.tool}: ${plan.command}`;
+        return `- ${plan.tool}: ${plan.hint}`;
+    });
+    return [
+        'crtr sys setup (non-interactive)',
+        '',
+        'Provider login: open the wizard in a TTY and use the Providers tab (same flow as /login) to authenticate a model provider.',
+        '',
+        'Packages:',
+        ...packageLines,
+        '',
+        'System deps:',
+        ...systemLines,
+        '',
+        `Inbox: the inbox-toggle key (${inboxShortcut() ?? 'disabled'}) is a crouter keybinding — view or rebind it in \`crtr sys settings\`; it is installed on the same tmux server as every other crouter binding.`,
+        'Run `crtr sys setup` in a TTY to open the wizard.',
+    ].join('\n') + '\n';
+}
+class SetupCommandError extends Error {
+    output;
+    constructor(message, output) {
+        super(message);
+        this.output = output;
+    }
+}
+function commandOutput(result) {
+    return `${result.stdout?.toString() ?? ''}${result.stderr?.toString() ?? ''}`;
+}
+/** Output is captured and shown only when the step fails, and stderr is
+ *  streamed to `onStderr` so a step with a real progress count (curl's meter)
+ *  can drive its bar. Asynchronous so a bar on this terminal keeps animating
+ *  while the command runs. */
+function runCapturedCommand(command, args, onStderr, env = process.env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+        let output = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { output += chunk; });
+        child.stderr.on('data', (chunk) => {
+            output += chunk;
+            onStderr?.(chunk);
+        });
+        child.on('error', (error) => reject(new SetupCommandError(`${command} failed: ${error.message}`, output)));
+        child.on('close', (status) => {
+            if (status === 0)
+                resolve();
+            else
+                reject(new SetupCommandError(`${command} failed with status ${status ?? 'unknown'}`, output));
+        });
+    });
+}
+function runShellCommand(command, onStderr) {
+    return runCapturedCommand('sh', ['-lc', command], onStderr);
+}
+function installPiPackage(source, piCliPath = resolveBundledPiCliPath()) {
+    return runCapturedCommand(process.execPath, [piCliPath, 'install', source], undefined, { ...process.env, PI_CODING_AGENT_DIR: piAgentDir() });
+}
+async function installCaptureCliIfMissing() {
+    if (!detectCommandOnPath('capture'))
+        await runShellCommand('npm install -g @crouton-kit/capture');
+}
+function capturedFailureOutput(error) {
+    return error instanceof SetupCommandError ? error.output : undefined;
+}
+function firstFailureLine(error) {
+    const output = capturedFailureOutput(error);
+    const line = output?.split(/\r?\n/).find((candidate) => candidate.trim() !== '');
+    if (line !== undefined)
+        return line.trim();
+    return error instanceof Error ? error.message : String(error);
+}
+function printCapturedFailure(error) {
+    const output = capturedFailureOutput(error);
+    if (output === undefined || output.length === 0)
+        return;
+    process.stderr.write(output.endsWith('\n') ? output : `${output}\n`);
+}
+/** One line per install item: an animated bar while the item runs, replaced by
+ *  `✓ name` or `✗ name — <first error line>` when it finishes. Draws nothing
+ *  off a terminal, which is what the non-TTY `crtr sys setup --settings` path
+ *  gets; that path still prints captured output on failure. */
+class SetupProgress {
+    interactive;
+    bar = null;
+    constructor(interactive = Boolean(process.stdout.isTTY)) {
+        this.interactive = interactive;
+    }
+    start(name) {
+        if (!this.interactive)
+            return null;
+        this.bar = startProgressBar(`Installing ${name}…`);
+        return this.bar;
+    }
+    async clear() {
+        await this.bar?.stop();
+        this.bar = null;
+    }
+    async succeed(name) {
+        await this.clear();
+        if (this.interactive)
+            process.stdout.write(`\r\x1b[2K✓ ${name}\n`);
+    }
+    async fail(name, error) {
+        await this.clear();
+        if (this.interactive)
+            process.stdout.write(`\r\x1b[2K✗ ${name} — ${firstFailureLine(error)}\n`);
+        printCapturedFailure(error);
+    }
+    async run(name, operation) {
+        const bar = this.start(name);
+        try {
+            const result = await operation(bar);
+            await this.succeed(name);
+            return result;
+        }
+        catch (error) {
+            await this.fail(name, error);
+            throw error;
+        }
+    }
+}
+/** Provision the pinned termrender venv — crouter's one remaining out-of-tree
+ * dependency. Best-effort: a renderer that will not provision (no `uv`, no
+ * network) reports as skipped and never fails setup. */
+function ensureManagedRenderer(onProvision, onDiagnostic) {
+    if (isRendererReady())
+        return 'current';
+    onProvision?.();
+    ensureRenderer(onDiagnostic);
+    return isRendererReady() ? 'provisioned' : 'unavailable';
+}
+/** Refresh crouter-owned tmux bindings. Setup must never fail because tmux is unavailable. */
+export async function reconcileInboxFrontDoor() {
+    try {
+        installTmuxBindings();
+    }
+    catch { /* best-effort: no tmux server */ }
+}
+/** One item per line: a wrapped comma-joined list of a dozen entries, several
+ *  carrying their own parenthesised reason, is unreadable in a terminal. */
+function summarySection(label, items) {
+    if (items.length === 0)
+        return [`${label}: none`];
+    return [`${label}:`, ...items.map((item) => `  - ${item}`)];
+}
+export function formatSetupExecutionSummary(summary) {
+    return [
+        'crtr sys setup complete',
+        ...summarySection('installed', summary.installed),
+        ...summarySection('skipped', summary.skipped),
+        'New to crouter? Ask for the tutorial in your first conversation, or run /tutorial any time.',
+    ].join('\n') + '\n';
+}
+/** Marketplace manifest entries already present in any scope — the marketplace
+ *  and plugin registries are their install record, not pi's settings.json. */
+function detectInstalledMarketplaceEntries(manifest, scope) {
+    const installed = [];
+    for (const entry of manifest) {
+        try {
+            if (entry.sourceKind === 'marketplace-source') {
+                if (findMarketplaceByName(entry.name, scope) !== null)
+                    installed.push(entry.id);
+            }
+            else if (entry.sourceKind === 'marketplace-plugin') {
+                if (findPluginByName(entry.name, scope) !== null)
+                    installed.push(entry.id);
+            }
+        }
+        catch { /* unreadable scope config — treat as not installed */ }
+    }
+    return installed;
+}
+/** A `<marketplace>/<plugin>` ref only resolves once its marketplace is
+ *  registered, so selecting a plugin selects its source. Returns the
+ *  marketplace name when this call registered it. */
+async function ensureMarketplaceRegistered(name, scope = 'user') {
+    if (findMarketplaceByName(name, scope) !== null)
+        return null;
+    if (name !== OFFICIAL_MARKETPLACE_NAME) {
+        throw new Error(`marketplace not registered: ${name}`);
+    }
+    await addMarketplace({ url: OFFICIAL_MARKETPLACE_URL, ref: OFFICIAL_MARKETPLACE_REF, scope });
+    return name;
+}
+function configureCrtrExtensions(source) {
+    const settingsPath = resolveSettingsPath();
+    const settings = readJsonOrNull(settingsPath);
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+        throw new Error(`invalid pi settings: ${settingsPath}`);
+    const packages = settings.packages;
+    if (!Array.isArray(packages))
+        throw new Error(`invalid pi packages: ${settingsPath}`);
+    const isCrtrExtensions = (entry) => {
+        const path = typeof entry === 'string' ? entry : entry && typeof entry === 'object' ? entry.source : undefined;
+        return typeof path === 'string' && localPackageNameIdentities(path).includes(packageNameIdentity('pi-crtr-extensions'));
+    };
+    const first = packages.findIndex(isCrtrExtensions);
+    const remaining = packages.filter((entry) => !isCrtrExtensions(entry));
+    remaining.splice(first < 0 ? remaining.length : first, 0, {
+        source: relative(dirname(settingsPath), source),
+        extensions: CRTR_EXTENSION_GLOBS,
+    });
+    atomicWriteJson(settingsPath, { ...settings, packages: remaining });
+}
+/** Every marketplace source is a git clone, so with no `git` each marketplace
+ *  entry would fail on its own with the same clone error. */
+const GIT_MISSING_MESSAGE = 'git is not installed — install it (Debian/Ubuntu: apt-get install git), then run `crtr sys setup`';
+function isMarketplaceEntry(entry) {
+    return entry.sourceKind === 'marketplace-source' || entry.sourceKind === 'marketplace-plugin';
+}
+async function installSetupPackage(entry) {
+    if (entry.sourceKind === 'marketplace-source') {
+        await addMarketplace({ url: entry.installSource, ref: OFFICIAL_MARKETPLACE_REF, scope: 'user' });
+        return [entry.name];
+    }
+    if (entry.sourceKind === 'marketplace-plugin') {
+        const [marketplace, plugin] = entry.installSource.split('/');
+        const registered = await ensureMarketplaceRegistered(marketplace);
+        await installFromMarketplace({ marketplace: marketplace, plugin: plugin }, 'user');
+        if (entry.id === 'capture-plugin')
+            await installCaptureCliIfMissing();
+        return registered === null ? [entry.name] : [registered, entry.name];
+    }
+    await installPiPackage(entry.installSource);
+    if (entry.id === 'crtr-extensions')
+        configureCrtrExtensions(entry.installSource);
+    return [entry.name];
+}
+/** The non-interactive first command reconciles only crouter-owned packages.
+ * Individual failures are reported by the CLI but never prevent later work or
+ * writing the once-per-machine marker. */
+export async function reconcileFirstRun(onFailure, commandExists = detectCommandOnPath) {
+    const manifest = buildSetupManifest();
+    const installedPackageIds = detectInstalledSetupPackageIds(readJsonOrNull(resolveSettingsPath()), manifest);
+    for (const id of detectInstalledMarketplaceEntries(manifest, 'user'))
+        installedPackageIds.add(id);
+    const byId = new Map(manifest.map((entry) => [entry.id, entry]));
+    const packageIds = process.stdin.isTTY && process.stdout.isTTY
+        ? ['crtr-extensions', 'official-marketplace', 'oauth-adapter', 'capture-plugin', 'exa-search-plugin']
+        : ['crtr-extensions', 'official-marketplace', 'capture-plugin', 'exa-search-plugin'];
+    let gitMissing;
+    let gitReported = false;
+    for (const id of packageIds) {
+        const entry = byId.get(id);
+        if (installedPackageIds.has(id))
+            continue;
+        if (isMarketplaceEntry(entry)) {
+            gitMissing ??= !commandExists('git');
+            if (gitMissing) {
+                if (!gitReported)
+                    onFailure('marketplace packages', new Error(GIT_MISSING_MESSAGE));
+                gitReported = true;
+                continue;
+            }
+        }
+        try {
+            await installSetupPackage(entry);
+        }
+        catch (error) {
+            onFailure(entry.name, error);
+        }
+    }
+    try {
+        if (ensureManagedRenderer(undefined, () => { }) === 'unavailable')
+            onFailure('termrender renderer', new Error('unavailable — install uv'));
+    }
+    catch (error) {
+        onFailure('termrender renderer', error);
+    }
+    return crtrVersion();
+}
+export async function executeSetupSubmission(submission, commandExists = detectCommandOnPath) {
+    const installedPackages = [];
+    const skippedPackages = [];
+    const installedSystemDeps = [];
+    const skippedSystemDeps = [];
+    const progress = new SetupProgress();
+    let gitMissing;
+    let gitReported = false;
+    for (const entry of submission.packages) {
+        if (submission.installedPackageIds.has(entry.id)) {
+            skippedPackages.push(`${entry.name} (already installed)`);
+            if (entry.id === 'capture-plugin' && !detectCommandOnPath('capture')) {
+                try {
+                    await progress.run('Capture CLI', () => installCaptureCliIfMissing());
+                    installedPackages.push('Capture CLI');
+                }
+                catch (error) {
+                    skippedPackages.push(`Capture CLI (${error instanceof Error ? error.message : String(error)})`);
+                }
+            }
+            continue;
+        }
+        if (isMarketplaceEntry(entry)) {
+            gitMissing ??= !commandExists('git');
+            if (gitMissing) {
+                if (!gitReported)
+                    skippedPackages.push(`marketplace packages (${GIT_MISSING_MESSAGE})`);
+                gitReported = true;
+                continue;
+            }
+        }
+        try {
+            installedPackages.push(...await progress.run(entry.name, () => installSetupPackage(entry)));
+        }
+        catch (error) {
+            // The explicit wizard may stop on a local pi package failure, but an
+            // unavailable marketplace remains a skipped optional package.
+            if (entry.sourceKind !== 'marketplace-source' && entry.sourceKind !== 'marketplace-plugin')
+                throw error;
+            skippedPackages.push(`${entry.name} (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    for (const plan of submission.systemDeps) {
+        if (plan.installed) {
+            skippedSystemDeps.push(`${plan.tool} (already installed)`);
+            continue;
+        }
+        if (!plan.autoInstall || !plan.command) {
+            skippedSystemDeps.push(`${plan.tool} (${plan.hint})`);
+            continue;
+        }
+        // Only the command crouter writes itself runs curl with its progress
+        // meter on, so only that one can fill its bar from a real count; a
+        // package manager's own output is left to the indeterminate bar.
+        const command = plan.command;
+        const tracksCurl = command === NERD_FONT_MANUAL_LINUX_COMMAND;
+        await progress.run(plan.tool, (bar) => {
+            if (!tracksCurl || bar === null)
+                return runShellCommand(command);
+            const readPercent = createCurlPercentReader();
+            return runShellCommand(command, (chunk) => {
+                const percent = readPercent(chunk);
+                if (percent !== null)
+                    bar.setFraction(percent / 100);
+            });
+        });
+        installedSystemDeps.push(plan.tool);
+    }
+    const rendererDiagnostics = [];
+    let rendererProvisioning = false;
+    let rendererOutcome;
+    try {
+        rendererOutcome = ensureManagedRenderer(() => {
+            rendererProvisioning = true;
+            progress.start('termrender renderer');
+        }, (message) => rendererDiagnostics.push(message));
+    }
+    catch (error) {
+        if (rendererProvisioning)
+            await progress.fail('termrender renderer', error);
+        throw error;
+    }
+    switch (rendererOutcome) {
+        case 'provisioned':
+            if (rendererProvisioning)
+                await progress.succeed('termrender renderer');
+            installedPackages.push('termrender renderer');
+            break;
+        case 'current':
+            skippedPackages.push('termrender renderer (current)');
+            break;
+        case 'unavailable': {
+            const error = new SetupCommandError('unavailable — install uv', rendererDiagnostics.join(''));
+            if (rendererProvisioning)
+                await progress.fail('termrender renderer', error);
+            skippedPackages.push('termrender renderer (unavailable — install uv)');
+            break;
+        }
+    }
+    if (submission.terminalEdit !== undefined) {
+        const label = `Option as Alt (${submission.terminalEdit.path})`;
+        const result = applyTerminalEdit(submission.terminalEdit);
+        if (result.ok) {
+            installedPackages.push(`${label} — ${submission.terminalEdit.reload}`);
+        }
+        else {
+            skippedPackages.push(`${label} (${result.message})`);
+        }
+    }
+    // A fresh-machine run can install tmux after preflight reconciliation, so
+    // refresh the front-door bindings once the setup transaction has completed.
+    await reconcileInboxFrontDoor();
+    return {
+        installed: [...installedPackages, ...installedSystemDeps],
+        skipped: [...skippedPackages, ...skippedSystemDeps],
+    };
+}