@crouton-kit/crouter 0.3.78 → 0.3.79

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

@@ -1,7 +1,164 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { resolveBundledPiCliPath } from '../../../core/runtime/pi-cli.js';
+import { BINDING_CATALOG, resolveKeybindings } from '../../../core/keybindings/index.js';
+import { SetupKeybindingsDraft, buildSetupManifest } from '../setup-core.js';
+import { SetupWizard } from '../setup.js';
+import { applyTheme } from '../../../clients/attach/config-load.js';
+import { stripVTControlCharacters } from 'node:util';
+// The provider panel only touches the TUI on async OAuth transitions (never in
+// these keybindings-tab render/input tests) and reads auth from `agentDir`; a
+// no-op TUI stub and an empty temp agent dir keep the wizard headless.
+const stubTui = { requestRender() { } };
+const agentDir = mkdtempSync(join(tmpdir(), 'setup-wizard-test-'));
+test('setup keybinding draft edits, disables, resets, and discards transactionally', () => {
+    const draft = new SetupKeybindingsDraft({ 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.expression('crtr.attach.graph.toggle'), 'alt+x');
+    assert.equal(draft.dirty, false);
+    assert.equal(draft.edit('crtr.attach.graph.toggle', 'M-Y, ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['alt+shift+y', 'ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.unbind('crtr.attach.graph.toggle').ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], []);
+    draft.resetRow('crtr.attach.graph.toggle');
+    assert.equal(Object.hasOwn(draft.overrides(), 'crtr.attach.graph.toggle'), false);
+    draft.edit('crtr.attach.graph.toggle', 'alt+y');
+    draft.discard();
+    assert.deepEqual(draft.overrides(), { 'crtr.attach.graph.toggle': ['alt+x'] });
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft drops a member when the committed value equals the catalog default (N2 sparseness)', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const definition = BINDING_CATALOG.find((entry) => entry.id === 'crtr.attach.graph.toggle');
+    const defaultExpression = draft.expression(definition.id);
+    // Committing the seeded default verbatim must NOT record an override: the row
+    // stays sparse (no member) and the draft stays clean — no spurious unsaved/dot.
+    const result = draft.edit(definition.id, defaultExpression);
+    assert.equal(result.ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+    // Editing to a real value records the member; re-committing the default drops it.
+    assert.equal(draft.edit(definition.id, 'ctrl+g').ok, true);
+    assert.deepEqual(draft.overrides()[definition.id], ['ctrl+g']);
+    assert.equal(draft.dirty, true);
+    assert.equal(draft.edit(definition.id, defaultExpression).ok, true);
+    assert.equal(Object.hasOwn(draft.overrides(), definition.id), false);
+    assert.equal(draft.dirty, false);
+});
+test('setup keybinding draft keeps the last valid cell value on syntax, collision, and safety errors', () => {
+    const draft = new SetupKeybindingsDraft(undefined);
+    const syntax = draft.edit('crtr.attach.graph.toggle', 'ctrl+not-a-key');
+    assert.equal(syntax.ok, false);
+    assert.deepEqual(draft.overrides(), {});
+    const collision = draft.edit('crtr.attach.graph.toggle', 'alt+m');
+    assert.equal(collision.ok, false);
+    assert.match(collision.diagnostics[0].message, /crtr\.mode\.cycle/);
+    assert.deepEqual(draft.overrides(), {});
+    const unsafe = draft.unbind('crtr.setup.keybindings.save');
+    assert.equal(unsafe.ok, false);
+    assert.match(unsafe.diagnostics[0].message, /save-keybindings/);
+    assert.deepEqual(draft.overrides(), {});
+});
+test('setup reset-all removes invalid and unknown raw members without cataloging pi bindings', () => {
+    const invalidRoot = new SetupKeybindingsDraft('alt+x');
+    assert.equal(invalidRoot.resolution().diagnostics[0]?.code, 'invalid-keybindings');
+    invalidRoot.resetAll();
+    assert.equal(invalidRoot.dirty, true);
+    assert.equal(invalidRoot.resolution().diagnostics.length, 0);
+    const draft = new SetupKeybindingsDraft({
+        'crtr.unknown': ['x'],
+        'crtr.attach.graph.toggle': 'alt+x',
+    });
+    assert.equal(draft.resolution().diagnostics.length, 2);
+    draft.resetAll();
+    assert.deepEqual(draft.overrides(), {});
+    assert.equal(draft.resolution().diagnostics.length, 0);
+    assert.equal(BINDING_CATALOG.some((entry) => entry.id.includes('app.') || entry.id.includes('tui.')), false);
+});
+test('setup keybinding draft refuses edits while the raw root is invalid until reset-all', () => {
+    const draft = new SetupKeybindingsDraft('alt+x');
+    assert.equal(draft.hasInvalidRoot(), true);
+    // An edit against an invalid root must NOT commit (the prior bug: it returned
+    // ok:true against an empty `current` while the row kept showing the default).
+    const rejected = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(rejected.ok, false);
+    assert.equal(rejected.diagnostics[0].code, 'invalid-keybindings');
+    assert.deepEqual(draft.overrides(), {});
+    // reset-all clears the invalid root; edits then succeed and display.
+    draft.resetAll();
+    assert.equal(draft.hasInvalidRoot(), false);
+    const accepted = draft.edit('crtr.attach.graph.toggle', 'ctrl+g');
+    assert.equal(accepted.ok, true);
+    assert.deepEqual(draft.overrides()['crtr.attach.graph.toggle'], ['ctrl+g']);
+});
+test('setup keybindings editor stays visible while paging moves the selection (m3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const openingBindings = resolveKeybindings(undefined);
+    // A short terminal forces a small scroll window so paging past the edit row
+    // is the reproducible m3 scenario (editor was blind-typing off-screen before).
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, openingBindings, undefined, () => 14);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    // Drive to the Keybindings tab (tab-next = Tab), open the editor on row 0 (Enter).
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    assert.match(render(), /Keybindings/);
+    wizard.handleInput('\r');
+    // Type a distinctive marker into the live editor buffer.
+    wizard.handleInput('zzz');
+    assert.match(render(), /zzz/, 'editor should echo typed input before paging');
+    // PageDown twice: selection moves off, but the editor row must remain on screen.
+    wizard.handleInput('\x1b[6~');
+    wizard.handleInput('\x1b[6~');
+    assert.match(render(), /zzz/, 'editor must stay visible (and keep capturing) after paging');
+});
+test('setup keybindings q-cancel with a dirty draft routes through discard-confirm, not a silent exit (N3)', () => {
+    applyTheme({ cwd: process.cwd() });
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    wizard.focused = true;
+    let cancelled = false;
+    wizard.onCancel = () => { cancelled = true; };
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Make the draft dirty: unbind the selected row (delete key) so it has a real
+    // pending override.
+    wizard.handleInput('\x1b[3~');
+    assert.match(render(), /unsaved/, 'draft should be dirty after unbind');
+    // q (crtr.setup.cancel) in list mode must NOT drop the edits: it opens the same
+    // discard-confirm the Escape path uses.
+    wizard.handleInput('q');
+    assert.equal(cancelled, false, 'dirty draft must not silently exit on q');
+    assert.match(render(), /Discard every unsaved keybinding change\?/);
+    // A clean draft still exits on q (cancel elsewhere is unchanged).
+    const clean = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 40);
+    let cleanCancelled = false;
+    clean.onCancel = () => { cleanCancelled = true; };
+    clean.focused = true;
+    for (let i = 0; i < 5; i += 1)
+        clean.handleInput('\t');
+    clean.handleInput('q');
+    assert.equal(cleanCancelled, true, 'clean draft still exits on q');
+});
+test('setup keybindings selection always renders across group boundaries in a short window (m4 residual)', () => {
+    applyTheme({ cwd: process.cwd() });
+    // Small viewport so a window spans several group headings + a diagnostic line —
+    // the fixed-reserve page math used to let the selected row fail to render here.
+    const wizard = new SetupWizard(buildSetupManifest(), new Set(), [], stubTui, agentDir, resolveKeybindings(undefined), undefined, () => 13);
+    wizard.focused = true;
+    const render = () => stripVTControlCharacters(wizard.render(100).join('\n'));
+    for (let i = 0; i < 5; i += 1)
+        wizard.handleInput('\t');
+    // Page/step down through the whole catalog; the selection marker must always render.
+    for (let step = 0; step < BINDING_CATALOG.length + 5; step += 1) {
+        assert.match(render(), /\u25b6/, `selection marker must render at step ${step}`);
+        wizard.handleInput('\x1b[6~'); // PageDown
+        wizard.handleInput('j'); // and a single-row step to hit every boundary alignment
+    }
+});
 test('resolveBundledPiCliPath uses crouter bundled pi instead of a standalone pi on PATH', () => {
     const prevPath = process.env.PATH;
     process.env.PATH = '';

package/dist/commands/sys/doctor.js

@@ -8,6 +8,8 @@ import { lsRemote } from '../../core/git.js';
 import { listNodes } from '../../core/canvas/index.js';
 import { activeFaultForDisplay } from '../../core/canvas/render.js';
 import { readFault } from '../../core/runtime/fault.js';
+import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { SUBTREE_NAMES } from '../../build-root.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -89,6 +91,41 @@ function faultRemediation(fault) {
         logPath: fault.logPath,
     };
 }
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+function runCommandPluginChecks(scopes) {
+    const results = [];
+    const inScope = new Set(scopes);
+    const reserved = new Set(SUBTREE_NAMES);
+    // Validate the whole effective set together so cross-plugin top-level name
+    // collisions surface here — a collided command is NOT mounted, and every
+    // claimant must fail, not pass.
+    for (const v of validateEffectiveCommandPlugins(reserved)) {
+        const plugin = v.plugin;
+        if (!inScope.has(plugin.scope))
+            continue;
+        if (v.issues.length === 0) {
+            const mounts = v.contributions.map((c) => c.node.name).join(', ');
+            results.push(pass(plugin.scope, `plugin:${plugin.name}:commands`, mounts.length > 0 ? `contributes top-level command(s): ${mounts}` : `command manifest valid`));
+            continue;
+        }
+        v.issues.forEach((issue, i) => {
+            const remediation = {
+                kind: 'human_action',
+                description: `${issue.next} If unfixable, disable (pkg plugin disable ${plugin.name}), update (pkg plugin update --name ${plugin.name}), or remove (pkg plugin remove ${plugin.name}) the plugin.`,
+            };
+            const detail = issue.path !== undefined ? ` at ${issue.path}` : '';
+            results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
+        });
+    }
+    return results;
+}
 function runFaultChecks() {
     const results = [];
     for (const node of listNodes()) {
@@ -240,7 +277,7 @@ function runChecksForScope(scope, opts) {
 export const sysDoctorLeaf = defineLeaf({
     name: 'doctor',
     description: 'diagnose installation health',
-    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, or a config entry points at a directory that no longer exists. Reports each problem with a structured remediation, and can apply the repairs for you.',
+    whenToUse: 'something in your crtr install looks off and you want it diagnosed — a plugin or marketplace manifest is missing, a config entry points at a directory that no longer exists, or a command-plugin manifest/executable is malformed. Reports each problem with a structured remediation, and can apply the safe repairs for you.',
     help: {
         name: 'sys doctor',
         summary: 'diagnose missing manifests and broken config entries',
@@ -250,13 +287,13 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. Command-plugin manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed.',
-            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings stay read-only.',
+            'Read-only unless --fix is passed. Command-plugin manifests are validated statically — the plugin executable is never run, at any time.',
+            'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and command-plugin findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with logPath) so callers can apply it directly without --fix.',
         ],
     },
@@ -270,6 +307,7 @@ export const sysDoctorLeaf = defineLeaf({
             const results = runChecksForScope(scope, { fix, remote });
             allResults.push(...results);
         }
+        allResults.push(...runCommandPluginChecks(scopes));
         allResults.push(...runFaultChecks());
         // Sort by scope then name (mirrors old printResults grouping)
         const scopeOrder = { user: 0, project: 1, builtin: 2, canvas: 3 };

package/dist/commands/sys/setup-core.d.ts

@@ -1,3 +1,4 @@
+import { type BindingId, type BindingResolution, type KeybindingDiagnostic, type SparseKeybindingOverrides } from '../../core/keybindings/index.js';
 export type SetupPackageId = 'crtr-extensions' | 'mode-switch' | 'oauth-adapter';
 export type SetupTool = 'tmux' | 'nvim';
 export type SetupPackageSourceKind = 'local-path' | 'npm';
@@ -58,6 +59,33 @@ export interface SetupInitialState {
     exaKeyPath: string;
     composioKeyPath: string;
 }
+export interface KeybindingEditResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly KeybindingDiagnostic[];
+}
+/** Transactional sparse keybinding draft used by the full-screen setup tab. */
+export declare class SetupKeybindingsDraft {
+    private expected;
+    private baseline;
+    private current;
+    private baselineInvalidRoot;
+    private invalidRoot;
+    constructor(rawKeybindings: unknown);
+    get dirty(): boolean;
+    overrides(): Record<string, unknown>;
+    expectedKeybindings(): unknown;
+    resolution(): BindingResolution<BindingId>;
+    /** 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(): boolean;
+    expression(id: BindingId): string;
+    edit(id: BindingId, expression: string): KeybindingEditResult;
+    unbind(id: BindingId): KeybindingEditResult;
+    resetRow(id: BindingId): void;
+    resetAll(): void;
+    discard(): void;
+    markSaved(overrides: SparseKeybindingOverrides<BindingId>): void;
+}
 export declare function buildSetupManifest(resolveBuiltinPackageDir?: (name: string) => string): SetupPackageManifestEntry[];
 export declare function normalizePackageIdentity(source: string, settingsDir: string, homeDir: string): SetupPackageIdentity;
 export declare function detectInstalledSetupPackageIds(settingsJson: unknown, manifest?: SetupPackageManifestEntry[], settingsPath?: string, homeDir?: string): Set<SetupPackageId>;
@@ -68,6 +96,15 @@ export declare function buildSystemToolState(tool: SetupTool, packageManager: Pa
 export declare function resolveSettingsPath(homeDir?: string): string;
 export declare function resolveExaKeyPath(homeDir?: string): string;
 export declare function resolveComposioKeyPath(homeDir?: string): string;
+/** Where an already-present API key is resolved from — env var wins over the
+ *  key file, matching the runtime resolvers (search/exa.ts, connectors). */
+export type ApiKeySource = 'env' | 'file';
+export interface ApiKeyPresence {
+    present: boolean;
+    source?: ApiKeySource;
+}
+export declare function detectExaKey(homeDir?: string): ApiKeyPresence;
+export declare function detectComposioKey(homeDir?: string): ApiKeyPresence;
 export declare function buildSetupInitialState(opts?: {
     manifest?: SetupPackageManifestEntry[];
     settingsPath?: string;

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

@@ -1,10 +1,131 @@
 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, 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';
+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;
+    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() {
+        return resolveKeybindings(this.invalidRoot === undefined ? this.current : this.invalidRoot);
+    }
+    /** 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() === ''
+                ? []
+                : expression.split(',').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;
+        return { ok: true, diagnostics: resolution.diagnostics };
+    }
+    unbind(id) {
+        return this.edit(id, '');
+    }
+    resetRow(id) {
+        delete this.current[id];
+    }
+    resetAll() {
+        this.current = {};
+        this.invalidRoot = undefined;
+    }
+    discard() {
+        this.current = cloneKeybindings(this.baseline);
+        this.invalidRoot = this.baselineInvalidRoot;
+    }
+    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;
+    }
+}
 const PACKAGE_COPY = {
     'crtr-extensions': {
         name: 'pi-crtr-extensions',
@@ -234,6 +355,22 @@ export function resolveExaKeyPath(homeDir = homedir()) {
 export function resolveComposioKeyPath(homeDir = homedir()) {
     return join(homeDir, '.crouter', 'composio.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 detectComposioKey(homeDir = homedir()) {
+    return detectApiKey('COMPOSIO_API_KEY', resolveComposioKeyPath(homeDir));
+}
 export function buildSetupInitialState(opts = {}) {
     const homeDir = opts.homeDir ?? homedir();
     const settingsPath = opts.settingsPath ?? resolveSettingsPath(homeDir);
@@ -275,7 +412,7 @@ export function renderSetupStaticInstructions(state) {
     return [
         instructions.headline,
         '',
-        'Provider login: open the wizard in a TTY and use the Login tab (same flow as /login) to authenticate a model provider.',
+        '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,

package/dist/commands/sys/setup.d.ts

@@ -1,2 +1,90 @@
 import type { LeafDef } from '../../core/command.js';
+import { TUI, type Component, type Focusable } from '@earendil-works/pi-tui';
+import { type BindingId, type BindingResolution } from '../../core/keybindings/index.js';
+import { type SetupPackageId, type SetupPackageManifestEntry, type SetupSubmission, type SetupSystemToolState } from './setup-core.js';
+export declare class SetupWizard implements Component, Focusable {
+    private readonly manifest;
+    private readonly installedPackageIds;
+    private readonly systemTools;
+    private readonly exaInput;
+    private readonly composioInput;
+    private readonly keyInput;
+    private readonly openingBindings;
+    private readonly keyDraft;
+    private readonly terminalRows;
+    private readonly selectedPackageIds;
+    private readonly selectedSystemTools;
+    private readonly providers;
+    private activeTab;
+    private pluginIndex;
+    private systemIndex;
+    private expandedPluginId;
+    private confirming;
+    private keyIndex;
+    private keyScroll;
+    private keyFilter;
+    private filteringKeys;
+    private editingKey;
+    private keyEditError;
+    private keyDiagnostics;
+    private keyConfirm;
+    private keyNotice;
+    private cachedWidth;
+    private cachedLines;
+    private _focused;
+    onSubmit?: (submission: SetupSubmission) => void;
+    onCancel?: () => void;
+    constructor(manifest: SetupPackageManifestEntry[], installedPackageIds: Set<SetupPackageId>, systemTools: SetupSystemToolState[], tui: TUI, agentDir: string, openingBindings: BindingResolution<BindingId>, rawKeybindings: unknown, terminalRows: () => number);
+    set focused(value: boolean);
+    get focused(): boolean;
+    invalidate(): void;
+    private setTab;
+    private moveTab;
+    private cancel;
+    dispose(): void;
+    private matches;
+    /** Human hint label for an action, derived from the opening snapshot so footers
+     *  reflect the effective (possibly remapped) gestures the wizard actually honors. */
+    private label;
+    /** Like `label`, but drops gestures a focused pi text Input consumes as data
+     *  (single printable chars and the arrow keys), so the Exa/Composio footers do
+     *  not claim keys that never reach the wizard while a field owns focus. */
+    private fieldSafeLabel;
+    private handleGlobalTabSwitch;
+    private selectedPackage;
+    private selectedSystem;
+    private movePlugin;
+    private moveSystem;
+    private togglePackage;
+    private toggleSystem;
+    private toggleDetails;
+    private hasPendingInstalls;
+    private buildSubmission;
+    private finalize;
+    private filteredKeybindings;
+    private selectedKeybinding;
+    private moveKey;
+    private keyViewportLines;
+    private keyPageSize;
+    private beginKeyEdit;
+    private commitKeyEdit;
+    private cancelKeyEdit;
+    private saveKeybindings;
+    private refreshTmuxBindingsAfterSave;
+    private confirmKeyAction;
+    private handleKeybindingsInput;
+    handleInput(data: string): void;
+    private renderHeader;
+    private renderFooter;
+    private renderProviders;
+    private renderPlugins;
+    private renderSystems;
+    private renderExa;
+    private renderComposio;
+    private renderConfirm;
+    private keyRowHasMessage;
+    private keyLineCost;
+    private renderKeybindings;
+    render(width: number): string[];
+}
 export declare const sysSetupLeaf: LeafDef;