@north-light/crouter 0.3.173 → 0.3.175

package/dist/commands/sys/settings-shell.js

@@ -0,0 +1,400 @@
+// The `crtr sys settings` surface: a grouped left rail over the config panels.
+//
+// This is the persistent settings editor. The first-run installer lives in
+// setup-wizard.ts; both surfaces reuse only the panels they actually share.
+import { matchesKey, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { configPath } from "../../core/config.js";
+import { formatGesture, matchesPiTuiInput, } from "../../core/keybindings/index.js";
+import { reconcileInboxFrontDoor, resolveExaKeyPath, writeExaKey, } from "./setup-core.js";
+import { runSetupSettingsProcess } from "./setup-settings-runner.js";
+import { BrokerLimitsPanel } from "./panels/broker-limits-panel.js";
+import { KeybindingsPanel } from "./panels/keybindings-panel.js";
+import { KeysPanel } from "./panels/keys-panel.js";
+import { ModelsPanel } from "./panels/models-panel.js";
+import { PAGE_CHROME_ROWS, columns, padAnsi, pageFrame, theme, } from "./panels/panel.js";
+import { PrefsPanel } from "./panels/prefs-panel.js";
+import { ProviderPanel } from "./panels/provider-panel.js";
+/** Rail column width, including its badge gutter. */
+const RAIL_WIDTH = 22;
+/** Below this the rail costs more than it explains; the page falls back to a
+ *  one-line position header and gives every column to the panel. */
+const RAIL_MIN_TOTAL_WIDTH = 84;
+export class SettingsShell {
+    tui;
+    bindings;
+    terminalRows;
+    providers;
+    models;
+    keybindings;
+    brokerLimits;
+    keys;
+    destinations;
+    index = 0;
+    /** The rail owns the arrow keys until you step into a panel. */
+    railFocused = true;
+    _focused = false;
+    cachedWidth;
+    cachedHeight;
+    cachedLines;
+    keySaveInFlight = false;
+    onCancel;
+    constructor(tui, agentDir, runtime, registry, bindings, rawKeybindings, terminalRows, rawTmuxPassthrough = undefined) {
+        this.tui = tui;
+        this.bindings = bindings;
+        this.terminalRows = terminalRows;
+        const invalidate = () => this.invalidate();
+        this.providers = new ProviderPanel(tui, agentDir, runtime, registry);
+        this.providers.onChange = invalidate;
+        this.models = new ModelsPanel(tui, runtime, registry, (id, data) => this.matches(id, data), (id) => this.label(id));
+        this.models.onChange = invalidate;
+        this.keybindings = new KeybindingsPanel(bindings, rawKeybindings, rawTmuxPassthrough, terminalRows, invalidate);
+        this.brokerLimits = new BrokerLimitsPanel(invalidate);
+        this.keys = new KeysPanel();
+        this.keys.onSubmit = () => this.saveExaKey();
+        this.keys.onCancel = () => this.enterRail();
+        const prefs = (group, title, subtitle) => new PrefsPanel(group, title, subtitle, invalidate);
+        this.destinations = [
+            {
+                id: "providers",
+                group: "Intelligence",
+                label: "Providers",
+                panel: this.providers,
+            },
+            {
+                id: "models",
+                group: "Intelligence",
+                label: "Models",
+                panel: this.models,
+            },
+            {
+                id: "keybindings",
+                group: "Interface",
+                label: "Keybindings",
+                panel: this.keybindings,
+            },
+            {
+                id: "display",
+                group: "Interface",
+                label: "Display",
+                panel: prefs("display", "Display", "How an attached viewer renders a conversation."),
+            },
+            {
+                id: "panes",
+                group: "Workspace",
+                label: "Panes",
+                panel: prefs("panes", "Panes", "Where tmux places viewers for the nodes you spawn."),
+            },
+            {
+                id: "broker-limits",
+                group: "Workspace",
+                label: "Broker limits",
+                panel: this.brokerLimits,
+            },
+            {
+                id: "updates",
+                group: "Workspace",
+                label: "Updates",
+                panel: prefs("updates", "Updates", "How crouter checks for and applies new releases."),
+            },
+            { id: "keys", group: "Integrations", label: "API keys", panel: this.keys },
+        ];
+    }
+    // --- focus and navigation -------------------------------------------------
+    set focused(value) {
+        this._focused = value;
+        this.syncFocus();
+    }
+    get focused() {
+        return this._focused;
+    }
+    get current() {
+        return this.destinations[this.index];
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedHeight = undefined;
+        this.cachedLines = undefined;
+    }
+    syncFocus() {
+        const live = this._focused && !this.railFocused;
+        this.keys.focused = live && this.current.id === "keys";
+        this.keybindings.focused = live && this.current.id === "keybindings";
+        this.brokerLimits.focused = live && this.current.id === "broker-limits";
+    }
+    enterRail() {
+        this.railFocused = true;
+        this.syncFocus();
+        this.invalidate();
+    }
+    enterPanel() {
+        this.railFocused = false;
+        this.syncFocus();
+        this.invalidate();
+    }
+    go(index) {
+        const next = (index + this.destinations.length) % this.destinations.length;
+        if (next === this.index)
+            return;
+        this.index = next;
+        if (this.current.id === "models")
+            this.models.refresh();
+        this.syncFocus();
+        this.invalidate();
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    label(id) {
+        const gestures = this.bindings.gestures(id);
+        return gestures.length === 0
+            ? "disabled"
+            : formatGesture(gestures[0].split(" > ").pop());
+    }
+    // --- input ----------------------------------------------------------------
+    /** Panels that have taken over the keyboard — a live text field, a modal, an
+     *  open picker — keep every key including Escape until they release it. */
+    panelOwnsKeyboard(data) {
+        if (this.railFocused)
+            return false;
+        switch (this.current.id) {
+            case "providers":
+                return this.providers.isNestedFlowActive();
+            case "models":
+                return this.models.isPickerOpen();
+            case "keybindings":
+                return this.keybindings.takesPriorityInput;
+            case "broker-limits":
+                // Threshold fields take digits; a remapped destination gesture must
+                // never swallow a number the user is typing into a limit.
+                return /^\d+$/.test(data);
+            case "keys":
+                // The key field takes text and cursor movement; step gestures still
+                // reach the shell so the field is never a trap.
+                return ((data.length === 1 && data.charCodeAt(0) >= 32) ||
+                    matchesKey(data, "left") ||
+                    matchesKey(data, "right") ||
+                    matchesKey(data, "up") ||
+                    matchesKey(data, "down"));
+            default:
+                return false;
+        }
+    }
+    /** `crtr.setup.tab-next`/`-previous` still carry the tab strip's horizontal
+     *  arrows. In the rail layout the horizontal arrows mean "into the panel" and
+     *  "back to the rail", so only the Tab gestures cycle destinations. */
+    cyclesDestination(data) {
+        if (this.matches("crtr.setup.tab-next", data) && !matchesKey(data, "right"))
+            return 1;
+        if (this.matches("crtr.setup.tab-previous", data) &&
+            !matchesKey(data, "left"))
+            return -1;
+        return 0;
+    }
+    handleInput(data) {
+        if (this.panelOwnsKeyboard(data)) {
+            this.routeToPanel(data);
+            return;
+        }
+        // Destination cycling works from either focus, so Tab keeps meaning
+        // "somewhere else in settings" exactly as it did with the old tab strip.
+        const cycle = this.cyclesDestination(data);
+        if (cycle !== 0) {
+            this.go(this.index + cycle);
+            return;
+        }
+        if (this.railFocused) {
+            if (this.matches("crtr.setup.list-down", data))
+                this.go(this.index + 1);
+            else if (this.matches("crtr.setup.list-up", data))
+                this.go(this.index - 1);
+            else if (this.matches("crtr.setup.advance", data) ||
+                this.matches("crtr.setup.cell-next", data) ||
+                matchesKey(data, "right"))
+                this.enterPanel();
+            else if (this.matches("crtr.setup.cancel", data))
+                this.close();
+            else
+                this.jumpToInitial(data);
+            return;
+        }
+        // An unsaved keybinding draft turns every exit into a discard prompt, so
+        // leaving the destination can never silently drop edits.
+        if (this.current.id === "keybindings" &&
+            this.keybindings.dirty &&
+            (this.matches("crtr.setup.cancel", data) ||
+                matchesKey(data, "escape") ||
+                matchesKey(data, "left"))) {
+            this.keybindings.requestDiscard();
+            return;
+        }
+        if (matchesKey(data, "escape") || matchesKey(data, "left")) {
+            this.enterRail();
+            return;
+        }
+        if (this.matches("crtr.setup.cancel", data)) {
+            this.close();
+            return;
+        }
+        this.routeToPanel(data);
+    }
+    /** Typing a letter on the rail jumps to the destination it starts. */
+    jumpToInitial(data) {
+        if (data.length !== 1 || data.charCodeAt(0) < 32)
+            return;
+        const needle = data.toLowerCase();
+        const found = this.destinations.findIndex((destination, offset) => offset !== this.index
+            ? destination.label.toLowerCase().startsWith(needle)
+            : false);
+        if (found >= 0)
+            this.go(found);
+    }
+    routeToPanel(data) {
+        const match = (id, input) => this.matches(id, input);
+        if (this.current.panel.handleInput(data, match))
+            this.invalidate();
+    }
+    saveExaKey() {
+        if (this.keySaveInFlight)
+            return;
+        const key = this.keys.value;
+        if (key === "") {
+            this.keys.setNotice("Paste an Exa key before saving.");
+            this.invalidate();
+            return;
+        }
+        this.keySaveInFlight = true;
+        this.keys.setNotice("Saving Exa key…");
+        this.invalidate();
+        void writeExaKey(resolveExaKeyPath(), key).then(() => this.keys.setNotice("Saved Exa key.", true), (error) => this.keys.setNotice(`Could not save Exa key: ${error instanceof Error ? error.message : String(error)}`)).finally(() => {
+            this.keySaveInFlight = false;
+            this.invalidate();
+            this.tui.requestRender();
+        });
+    }
+    close() {
+        this.onCancel?.();
+    }
+    dispose() {
+        this.providers.dispose();
+        this.models.dispose();
+        this.keys.focused = false;
+        this.keybindings.focused = false;
+        this.brokerLimits.focused = false;
+    }
+    // --- rendering ------------------------------------------------------------
+    renderRail(height) {
+        const out = [];
+        let group;
+        for (const [offset, destination] of this.destinations.entries()) {
+            if (destination.group !== group) {
+                if (group !== undefined)
+                    out.push("");
+                group = destination.group;
+                out.push(theme.fg("dim", ` ${group.toUpperCase()}`));
+            }
+            const badge = destination.panel.badge?.() ?? "";
+            const room = RAIL_WIDTH - 2 - visibleWidth(badge) - 1;
+            const label = truncateToWidth(destination.label, Math.max(1, room));
+            const selected = offset === this.index;
+            const body = ` ${padAnsi(label, Math.max(1, room))} ${badge}`;
+            if (selected && this.railFocused)
+                out.push(theme.bg("selectedBg", padAnsi(body, RAIL_WIDTH)));
+            else if (selected)
+                out.push(`${theme.fg("accent", "\u258c")}${padAnsi(theme.fg("accent", body.slice(1)), RAIL_WIDTH - 1)}`);
+            else
+                out.push(padAnsi(` ${padAnsi(label, Math.max(1, room))} ${theme.fg("dim", badge)}`, RAIL_WIDTH));
+        }
+        // Pad rather than trim: the rail column sets the divider's length, and a
+        // divider that stops halfway makes the page look broken.
+        while (out.length < height)
+            out.push("");
+        return out.slice(0, height);
+    }
+    /** Left hint plus the always-there navigation keys, the hint shedding its
+     *  optional half on a narrow terminal rather than pushing "close" off. */
+    footer(width) {
+        const right = `${this.label("crtr.setup.tab-next")}/${this.label("crtr.setup.tab-previous")} destination \u00b7 ${this.label("crtr.setup.cancel")} close`;
+        const move = `${this.label("crtr.setup.list-down")}/${this.label("crtr.setup.list-up")} move \u00b7 ${this.label("crtr.setup.advance")} open`;
+        const candidates = this.railFocused
+            ? [`${move} \u00b7 type a letter to jump`, move]
+            : [`${this.panelHint()} \u00b7 esc rail`, this.panelHint()];
+        for (const left of candidates) {
+            const gap = width - visibleWidth(left) - visibleWidth(right);
+            if (gap >= 2)
+                return `${theme.fg("dim", left)}${" ".repeat(gap)}${theme.fg("dim", right)}`;
+        }
+        return theme.fg("dim", truncateToWidth(candidates.at(-1), width));
+    }
+    panelHint() {
+        const move = `${this.label("crtr.setup.list-down")}/${this.label("crtr.setup.list-up")}`;
+        switch (this.current.id) {
+            case "providers":
+                return this.providers.isNestedFlowActive()
+                    ? "OAuth in progress \u00b7 esc cancel"
+                    : `${move} select \u00b7 a add \u00b7 p prefer \u00b7 r rename \u00b7 l re-login \u00b7 x remove`;
+            case "models":
+                return this.models.isPickerOpen()
+                    ? this.models.footerHint()
+                    : `${move} row \u00b7 ${this.label("crtr.setup.cell-previous")}/${this.label("crtr.setup.cell-next")} column \u00b7 ${this.label("crtr.setup.models.scope-next")} scope \u00b7 ${this.label("crtr.setup.models.open")} edit`;
+            case "keybindings":
+                return this.keybindings.footerHint();
+            case "broker-limits":
+                return `${move} field \u00b7 type a value \u00b7 ${this.label("crtr.setup.advance")} save`;
+            case "keys":
+                return `paste the key \u00b7 ${this.label("crtr.setup.advance")} save`;
+            default:
+                return `${move} row \u00b7 ${this.label("crtr.setup.toggle")} or ${this.label("crtr.setup.cell-previous")}/${this.label("crtr.setup.cell-next")} change value`;
+        }
+    }
+    render(width) {
+        const bypass = (this.current.id === "models" && this.models.isPickerOpen()) ||
+            this.current.id === "providers";
+        const height = this.terminalRows();
+        if (!bypass &&
+            this.cachedLines &&
+            this.cachedWidth === width &&
+            this.cachedHeight === height)
+            return this.cachedLines;
+        const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);
+        const useRail = width >= RAIL_MIN_TOTAL_WIDTH;
+        const panelWidth = useRail ? width - RAIL_WIDTH - 3 : width;
+        let body;
+        if (useRail) {
+            const panel = this.current.panel.render(panelWidth, bodyHeight);
+            body = columns(this.renderRail(bodyHeight), RAIL_WIDTH, panel, panelWidth);
+        }
+        else {
+            body = this.current.panel.render(width, bodyHeight);
+        }
+        const lines = pageFrame({
+            width,
+            height,
+            title: "crouter settings",
+            // Without the rail, the title row carries the position instead of the
+            // config path — the page must always say where in settings you are.
+            meta: useRail
+                ? `user \u00b7 ${configPath("user") ?? ""}`
+                : `${this.index + 1}/${this.destinations.length} ${this.current.label}`,
+            body,
+            footer: this.footer(width),
+        });
+        if (!bypass) {
+            this.cachedWidth = width;
+            this.cachedHeight = height;
+            this.cachedLines = lines;
+        }
+        return lines;
+    }
+}
+export async function runSettings() {
+    await reconcileInboxFrontDoor();
+    if (!process.stdout.isTTY) {
+        process.stdout.write("crtr sys settings needs a TTY. Run it in a terminal, or use `crtr sys config get|set` for scriptable access.\n");
+        return;
+    }
+    await runSetupSettingsProcess(({ tui, terminal, agentDir, runtime, registry, bindings, rawUserConfig }, control) => {
+        const shell = new SettingsShell(tui, agentDir, runtime, registry, bindings, rawUserConfig?.keybindings, () => terminal.rows, rawUserConfig?.tmux_passthrough);
+        shell.onCancel = control.cancel;
+        return shell;
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const sysSettingsLeaf: LeafDef;

package/dist/commands/sys/settings.js

@@ -0,0 +1,31 @@
+// The `crtr sys settings` leaf DEFINITION only. The shell itself lives in
+// settings-shell.ts and is loaded on demand, because it pulls pi's model
+// runtime and TUI components — a ~270ms module graph. Registering the `sys`
+// subtree (every `crtr sys …` invocation, and root `-h`, which builds the full
+// tree) needs the help metadata below and nothing else, so the shell must NOT
+// be reachable by a static import from here.
+import { defineLeaf } from '../../core/command.js';
+import { BROKER_LIMIT_OVERRIDE_PRECEDENCE } from './setup.js';
+export const sysSettingsLeaf = defineLeaf({
+    name: 'settings',
+    description: 'open the settings page — providers, models, keybindings, display, panes, broker limits, updates, API keys',
+    whenToUse: 'a human wants to change crouter configuration interactively. Agents should use sys config get/set, which is scriptable; sys setup installs a fresh machine.',
+    help: {
+        name: 'sys settings',
+        summary: 'open the interactive settings page for an already-installed crouter',
+        inputNote: 'No input parameters.',
+        output: [],
+        outputKind: 'object',
+        effects: [
+            'Opens a pi-tui page whose left rail groups ongoing configuration: Intelligence (providers, models), Interface (keybindings, display), Workspace (panes, broker limits, updates), and Integrations (API keys).',
+            'Preference, model-ladder and keybinding edits save to the user config as you make them; saved keybinding changes also refresh crouter-owned tmux bindings without overwriting occupied user keys.',
+            `Broker warning and automatic-revive hard-cap values save under user config brokerThresholds; crtrd reads them on its next supervision tick. ${BROKER_LIMIT_OVERRIDE_PRECEDENCE}`,
+            'Saving a replacement Exa key writes it directly to ~/.crouter/exa.key. Machine installs and bootstrap remain under sys setup.',
+            'Requires a TTY. Without one it prints a pointer to sys config and exits.',
+        ],
+    },
+    run: async () => {
+        await (await import('./settings-shell.js')).runSettings();
+    },
+    render: () => '',
+});

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

@@ -23,26 +23,11 @@ export interface SetupPackageManifestEntry {
 }
 export interface SetupSystemInstallPlan {
     tool: SetupTool;
-    label: string;
     installed: boolean;
-    checked: boolean;
-    packageManager: PackageManager;
     command: string | null;
     hint: string;
     autoInstall: boolean;
 }
-export interface SetupSystemToolState {
-    tool: SetupTool;
-    installed: boolean;
-    plan: SetupSystemInstallPlan;
-}
-export interface SetupStaticInstructions {
-    headline: string;
-    packageLines: string[];
-    systemLines: string[];
-    exaLine: string;
-    footer: string;
-}
 export interface SetupSubmission {
     packages: SetupPackageManifestEntry[];
     installedPackageIds: Set<SetupPackageId>;
@@ -59,7 +44,7 @@ export interface SetupExecutionSummary {
 export interface SetupInitialState {
     manifest: SetupPackageManifestEntry[];
     installedPackageIds: Set<SetupPackageId>;
-    systemTools: SetupSystemToolState[];
+    systemPlans: SetupSystemInstallPlan[];
     exaKeyPath: string;
 }
 export interface KeybindingEditResult {
@@ -102,8 +87,7 @@ export declare function normalizePackageIdentity(source: string, settingsDir: st
 export declare function detectInstalledSetupPackageIds(settingsJson: unknown, manifest?: SetupPackageManifestEntry[], settingsPath?: string, homeDir?: string): Set<SetupPackageId>;
 export declare function detectCommandOnPath(command: string): boolean;
 export declare function detectPackageManager(platform?: NodeJS.Platform, commandExists?: (command: string) => boolean): PackageManager;
-export declare function buildSystemInstallPlan(tool: SetupTool, packageManager: PackageManager, installed: boolean): SetupSystemInstallPlan;
-export declare function buildSystemToolState(tool: SetupTool, packageManager: PackageManager, commandExists?: (command: string) => boolean): SetupSystemToolState;
+export declare function buildSystemInstallPlan(tool: SetupTool, packageManager: PackageManager, commandExists?: (command: string) => boolean): SetupSystemInstallPlan;
 export declare function resolveSettingsPath(homeDir?: string): string;
 export declare function resolveExaKeyPath(homeDir?: string): string;
 /** Where an already-present API key is resolved from — env var wins over the
@@ -121,23 +105,9 @@ export declare function buildSetupInitialState(opts?: {
     packageManager?: PackageManager;
     commandExists?: (command: string) => boolean;
 }): SetupInitialState;
-export declare function buildSetupStaticInstructions(opts: {
-    manifest: SetupPackageManifestEntry[];
-    installedPackageIds: Set<SetupPackageId>;
-    systemPlans: SetupSystemInstallPlan[];
-    exaKeyPath: string;
-}): SetupStaticInstructions;
-export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemTools' | 'exaKeyPath'>): string;
+export declare function renderSetupStaticInstructions(state: Pick<SetupInitialState, 'manifest' | 'installedPackageIds' | 'systemPlans' | 'exaKeyPath'>): string;
 export declare function writeExaKey(exaKeyPath: string, exaKey: string): Promise<void>;
 /** Refresh crouter-owned tmux bindings. Setup must never fail because tmux is unavailable. */
 export declare function reconcileInboxFrontDoor(): Promise<void>;
-export declare function summarizeSetupExecution(result: {
-    installedPackages: string[];
-    skippedPackages: string[];
-    installedSystemDeps: string[];
-    skippedSystemDeps: string[];
-    exaKeyWritten: boolean;
-    exaKeyPath: string;
-}): SetupExecutionSummary;
 export declare function formatSetupExecutionSummary(summary: SetupExecutionSummary): string;
 export declare function executeSetupSubmission(submission: SetupSubmission): Promise<SetupExecutionSummary>;