@matthesketh/fleet 1.0.0 → 1.2.0

package/dist/core/deps/types.d.ts

@@ -0,0 +1,64 @@
+import type { AppEntry } from '../registry.js';
+export type CollectorType = 'npm' | 'composer' | 'pip' | 'docker-image' | 'docker-running' | 'eol' | 'vulnerability' | 'github-pr';
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export type FindingCategory = 'outdated-dep' | 'image-update' | 'eol-warning' | 'vulnerability' | 'pending-pr';
+export interface Finding {
+    appName: string;
+    source: CollectorType;
+    severity: Severity;
+    category: FindingCategory;
+    title: string;
+    detail: string;
+    package?: string;
+    currentVersion?: string;
+    latestVersion?: string;
+    eolDate?: string;
+    cveId?: string;
+    prUrl?: string;
+    fixable: boolean;
+    updatedAt: string;
+}
+export interface ScanError {
+    collector: CollectorType;
+    appName?: string;
+    message: string;
+    timestamp: string;
+}
+export interface IgnoreRule {
+    appName?: string;
+    package?: string;
+    source?: CollectorType;
+    reason: string;
+    until?: string;
+}
+export interface DepsConfig {
+    scanIntervalHours: number;
+    concurrency: number;
+    notifications: {
+        telegram: {
+            enabled: boolean;
+            chatId: string;
+            minSeverity: Severity;
+        };
+    };
+    ignore: IgnoreRule[];
+    severityOverrides: {
+        eolDaysWarning: number;
+        majorVersionBehind: Severity;
+        minorVersionBehind: Severity;
+        patchVersionBehind: Severity;
+    };
+}
+export interface DepsCache {
+    version: 1;
+    lastScan: string;
+    scanDurationMs: number;
+    findings: Finding[];
+    errors: ScanError[];
+    config: DepsConfig;
+}
+export interface Collector {
+    type: CollectorType;
+    detect(appPath: string): boolean;
+    collect(app: AppEntry): Promise<Finding[]>;
+}

package/dist/core/deps/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/deps-tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDepsTools(server: McpServer): void;

package/dist/mcp/deps-tools.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { load, findApp } from '../core/registry.js';
+import { loadConfig, saveConfig } from '../core/deps/config.js';
+import { loadCache, saveCache } from '../core/deps/cache.js';
+import { runScan } from '../core/deps/scanner.js';
+import { createDepsPr } from '../core/deps/actors/pr-creator.js';
+import { AppNotFoundError } from '../core/errors.js';
+function text(msg) {
+    return { content: [{ type: 'text', text: msg }] };
+}
+export function registerDepsTools(server) {
+    server.tool('fleet_deps_status', 'Dependency health summary from cache — outdated packages, CVEs, EOL warnings, Docker image updates', async () => {
+        const cache = loadCache();
+        if (!cache)
+            return text('No scan data. Run fleet deps scan first.');
+        return text(JSON.stringify(cache, null, 2));
+    });
+    server.tool('fleet_deps_scan', 'Run a fresh dependency scan across all registered apps', async () => {
+        const reg = load();
+        const config = loadConfig();
+        const cache = await runScan(reg.apps, config);
+        saveCache(cache);
+        return text(JSON.stringify({
+            findings: cache.findings.length,
+            errors: cache.errors.length,
+            duration: cache.scanDurationMs,
+            apps: reg.apps.length,
+        }, null, 2));
+    });
+    server.tool('fleet_deps_app', 'Dependency findings for a specific app', { app: z.string().describe('App name') }, async ({ app }) => {
+        const cache = loadCache();
+        if (!cache)
+            return text('No scan data. Run fleet deps scan first.');
+        const reg = load();
+        const entry = findApp(reg, app);
+        if (!entry)
+            throw new AppNotFoundError(app);
+        const findings = cache.findings.filter(f => f.appName === entry.name);
+        return text(JSON.stringify(findings, null, 2));
+    });
+    server.tool('fleet_deps_fix', 'Create a PR with dependency updates for an app (dry-run by default)', {
+        app: z.string().describe('App name'),
+        dryRun: z.boolean().default(true).describe('Preview changes without creating PR'),
+    }, async ({ app, dryRun }) => {
+        const reg = load();
+        const entry = findApp(reg, app);
+        if (!entry)
+            throw new AppNotFoundError(app);
+        const cache = loadCache();
+        if (!cache)
+            return text('No scan data. Run fleet deps scan first.');
+        const findings = cache.findings.filter(f => f.appName === entry.name && f.fixable);
+        const result = createDepsPr(entry, findings, dryRun);
+        return text(JSON.stringify(result, null, 2));
+    });
+    server.tool('fleet_deps_ignore', 'Add an ignore rule for a dependency finding', {
+        package: z.string().describe('Package name to ignore'),
+        reason: z.string().describe('Why this is being ignored'),
+        app: z.string().optional().describe('Limit to specific app'),
+        until: z.string().optional().describe('Auto-expire date (YYYY-MM-DD)'),
+    }, async (params) => {
+        const config = loadConfig();
+        config.ignore.push({
+            package: params.package, reason: params.reason,
+            ...(params.app && { appName: params.app }),
+            ...(params.until && { until: params.until }),
+        });
+        saveConfig(config);
+        return text(`Ignoring ${params.package}: ${params.reason}`);
+    });
+    server.tool('fleet_deps_config', 'Get or set dependency monitoring configuration', { key: z.string().optional(), value: z.string().optional() }, async ({ key, value }) => {
+        const config = loadConfig();
+        if (!key)
+            return text(JSON.stringify(config, null, 2));
+        if (!value)
+            return text(JSON.stringify(config[key], null, 2));
+        config[key] = value === 'true' ? true : value === 'false' ? false : isNaN(Number(value)) ? value : Number(value);
+        saveConfig(config);
+        return text(`Set ${key} = ${value}`);
+    });
+}

package/dist/mcp/server.js

@@ -16,6 +16,7 @@ import { unsealAll, getStatus as getSecretsStatus } from '../core/secrets-ops.js
 import { validateApp, validateAll } from '../core/secrets-validate.js';
 import { registerGitTools } from './git-tools.js';
 import { registerSecretsTools } from './secrets-tools.js';
+import { registerDepsTools } from './deps-tools.js';
 function requireApp(name) {
     const reg = load();
     const app = findApp(reg, name);
@@ -174,6 +175,7 @@ export async function startMcpServer() {
     });
     registerGitTools(server);
     registerSecretsTools(server);
+    registerDepsTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/templates/motd.d.ts

@@ -0,0 +1 @@
+export declare function generateMotdScript(): string;

package/dist/templates/motd.js

@@ -0,0 +1,7 @@
+export function generateMotdScript() {
+    return `#!/bin/bash
+# Fleet service health check — installed by "fleet motd install"
+# Shows service status on SSH login
+/usr/bin/node /home/matt/fleet/dist/index.js watchdog --motd 2>/dev/null || echo "  Fleet: health check failed to run"
+`;
+}

package/dist/tui/components/AppList.js

@@ -25,7 +25,7 @@ export function AppList({ items, onSelect, renderItem }) {
     return (_jsx(Box, { flexDirection: "column", children: items.map((item, i) => {
             const selected = i === selectedIndex;
             if (renderItem) {
-                return (_jsxs(Box, { children: [_jsx(Text, { color: colors.primary, children: selected ? '> ' : '  ' }), renderItem(item, selected)] }, item.name));
+                return (_jsxs(Box, { children: [_jsx(Text, { bold: true, color: selected ? colors.primary : colors.muted, children: selected ? '> ' : '  ' }), renderItem(item, selected)] }, item.name));
             }
             return (_jsxs(Text, { bold: selected, color: selected ? colors.primary : colors.text, children: [selected ? '> ' : '  ', item.label ?? item.name] }, item.name));
         }) }));

package/dist/tui/components/Confirm.js

@@ -1,10 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Text } from 'ink';
+import { Text, Box } from 'ink';
+import { Modal } from '@matthesketh/ink-modal';
 import { useAppState } from '../state.js';
 import { colors } from '../theme.js';
 export function Confirm() {
     const { confirmAction } = useAppState();
-    if (!confirmAction)
-        return null;
-    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: colors.warning, paddingX: 2, paddingY: 1, marginY: 1, children: [_jsx(Text, { bold: true, color: colors.warning, children: confirmAction.label }), _jsx(Text, { color: colors.muted, children: confirmAction.description }), _jsxs(Box, { marginTop: 1, gap: 2, children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: colors.success, children: "y" }), " confirm"] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, color: colors.error, children: "n" }), " cancel"] })] })] }));
+    return (_jsx(Modal, { visible: confirmAction !== null, title: confirmAction?.label, borderColor: colors.warning, width: 50, footer: _jsxs(Box, { gap: 2, children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, color: colors.success, children: "y" }), " confirm"] }), _jsxs(Text, { children: [_jsx(Text, { bold: true, color: colors.error, children: "n" }), " cancel"] })] }), children: _jsx(Text, { color: colors.muted, children: confirmAction?.description ?? '' }) }));
 }

package/dist/tui/components/Header.js

@@ -1,16 +1,45 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
+import { Tabs } from '@matthesketh/ink-tabs';
+import { Breadcrumb } from '@matthesketh/ink-breadcrumb';
 import { useAppState } from '../state.js';
 import { colors } from '../theme.js';
-const TABS = [
-    { view: 'dashboard', label: 'Dashboard' },
-    { view: 'health', label: 'Health' },
-    { view: 'secrets', label: 'Secrets' },
+const TAB_ITEMS = [
+    { id: 'dashboard', label: 'Dashboard' },
+    { id: 'health', label: 'Health' },
+    { id: 'secrets', label: 'Secrets' },
 ];
-function VaultIndicator({ sealed }) {
-    return (_jsx(Text, { color: sealed ? colors.warning : colors.success, children: sealed ? '[SEALED]' : '[UNSEALED]' }));
+const TOP_VIEWS = new Set(['dashboard', 'health', 'secrets']);
+function resolveActiveTab(view, previousView) {
+    if (TOP_VIEWS.has(view))
+        return view;
+    if (view === 'app-detail' || view === 'logs')
+        return 'dashboard';
+    if (view === 'secret-edit')
+        return 'secrets';
+    return previousView ?? 'dashboard';
+}
+function buildBreadcrumb(view, selectedApp) {
+    switch (view) {
+        case 'dashboard':
+            return ['Dashboard'];
+        case 'health':
+            return ['Health'];
+        case 'secrets':
+            return ['Secrets'];
+        case 'app-detail':
+            return ['Dashboard', selectedApp ?? '...'];
+        case 'logs':
+            return ['Dashboard', selectedApp ?? '...', 'Logs'];
+        case 'secret-edit':
+            return ['Secrets', selectedApp ?? '...', 'Edit'];
+        default:
+            return ['Dashboard'];
+    }
 }
 export function Header({ vaultSealed }) {
-    const { currentView, redacted } = useAppState();
-    return (_jsxs(Box, { borderStyle: "single", borderBottom: true, paddingX: 1, justifyContent: "space-between", children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { bold: true, color: colors.primary, children: "Fleet" }), _jsx(Text, { color: colors.muted, children: "|" }), TABS.map(tab => (_jsx(Text, { bold: currentView === tab.view || currentView === 'app-detail' && tab.view === 'dashboard' || currentView === 'secret-edit' && tab.view === 'secrets' || currentView === 'logs' && tab.view === 'dashboard', color: currentView === tab.view ? colors.primary : colors.muted, children: tab.label }, tab.view)))] }), _jsxs(Box, { gap: 1, children: [redacted && _jsx(Text, { color: "magenta", bold: true, children: "[REDACTED]" }), _jsx(VaultIndicator, { sealed: vaultSealed })] })] }));
+    const { currentView, previousView, selectedApp, redacted } = useAppState();
+    const activeTab = resolveActiveTab(currentView, previousView);
+    const breadcrumb = buildBreadcrumb(currentView, selectedApp);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { borderStyle: "single", borderBottom: true, paddingX: 1, justifyContent: "space-between", children: [_jsxs(Box, { gap: 1, alignItems: "center", children: [_jsx(Text, { bold: true, color: colors.primary, children: "Fleet" }), _jsx(Tabs, { tabs: TAB_ITEMS, activeId: activeTab, accentColor: colors.primary })] }), _jsxs(Box, { gap: 1, children: [redacted && _jsx(Text, { color: "magenta", bold: true, children: "[REDACTED]" }), _jsx(Text, { color: vaultSealed ? colors.warning : colors.success, children: vaultSealed ? '[SEALED]' : '[UNSEALED]' })] })] }), breadcrumb.length > 1 && (_jsx(Box, { paddingX: 1, children: _jsx(Breadcrumb, { path: breadcrumb, activeColor: colors.primary }) }))] }));
 }

package/dist/tui/components/KeyHint.js

@@ -1,12 +1,12 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Text } from 'ink';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StatusBar } from '@matthesketh/ink-status-bar';
 import { useAppState } from '../state.js';
-import { colors } from '../theme.js';
 const viewHints = {
     dashboard: [
         { key: 'j/k', label: 'navigate' },
         { key: 'Enter', label: 'select' },
         { key: 'Tab', label: 'switch view' },
+        { key: '?', label: 'help' },
         { key: 'x', label: 'redact' },
         { key: 'q', label: 'quit' },
     ],
@@ -31,7 +31,6 @@ const viewHints = {
         { key: 'a', label: 'add' },
         { key: 'd', label: 'delete' },
         { key: 'r', label: 'reveal' },
-        { key: 'x', label: 'redact' },
         { key: 'Esc', label: 'back' },
         { key: 'q', label: 'quit' },
     ],
@@ -51,5 +50,5 @@ export function KeyHint() {
     const hints = confirmAction
         ? [{ key: 'y', label: 'confirm' }, { key: 'n', label: 'cancel' }]
         : viewHints[currentView] ?? [];
-    return (_jsx(Box, { borderStyle: "single", borderTop: true, paddingX: 1, gap: 2, children: hints.map(hint => (_jsxs(Box, { gap: 0, children: [_jsx(Text, { bold: true, color: colors.primary, children: hint.key }), _jsxs(Text, { color: colors.muted, children: [" ", hint.label] })] }, hint.key))) }));
+    return _jsx(StatusBar, { items: hints });
 }

package/dist/tui/hooks/use-terminal-size.d.ts

@@ -0,0 +1 @@
+export { useTerminalSize, useAvailableHeight } from '@matthesketh/ink-viewport';

package/dist/tui/hooks/use-terminal-size.js

@@ -0,0 +1 @@
+export { useTerminalSize, useAvailableHeight } from '@matthesketh/ink-viewport';

package/dist/tui/router.js

@@ -1,8 +1,12 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import React, { useReducer, useState, useEffect } from 'react';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useReducer, useState, useEffect, useCallback } from 'react';
 import { Box, Text } from 'ink';
-import { reducer, initialState, AppStateContext, AppDispatchContext } from './state.js';
-import { useKeyboard } from './hooks/use-keyboard.js';
+import { InputDispatcher } from '@matthesketh/ink-input-dispatcher';
+import { Viewport } from '@matthesketh/ink-viewport';
+import { ToastProvider } from '@matthesketh/ink-toast';
+import { ToastContainer } from '@matthesketh/ink-toast';
+import { KeyBindingHelp } from '@matthesketh/ink-keybinding-help';
+import { reducer, initialState, AppStateContext, AppDispatchContext, nextTopView } from './state.js';
 import { Header } from './components/Header.js';
 import { KeyHint } from './components/KeyHint.js';
 import { Confirm } from './components/Confirm.js';
@@ -13,6 +17,35 @@ import { SecretEdit } from './views/SecretEdit.js';
 import { HealthView } from './views/HealthView.js';
 import { LogsView } from './views/LogsView.js';
 import { isSealed, isInitialized } from '../core/secrets.js';
+const HELP_GROUPS = [
+    {
+        title: 'Navigation',
+        bindings: [
+            { key: 'j/k', description: 'move up/down' },
+            { key: 'Enter', description: 'select / confirm' },
+            { key: 'Tab', description: 'switch view' },
+            { key: 'Esc', description: 'go back' },
+        ],
+    },
+    {
+        title: 'Actions',
+        bindings: [
+            { key: 'x', description: 'toggle redaction' },
+            { key: 'f', description: 'follow logs' },
+            { key: 'q', description: 'quit' },
+        ],
+    },
+    {
+        title: 'Secrets',
+        bindings: [
+            { key: 'u', description: 'unseal vault' },
+            { key: 'l', description: 'seal vault' },
+            { key: 'a', description: 'add secret' },
+            { key: 'd', description: 'delete secret' },
+            { key: 'r', description: 'reveal / hide' },
+        ],
+    },
+];
 function ViewRouter() {
     const state = React.useContext(AppStateContext);
     switch (state.currentView) {
@@ -32,13 +65,11 @@ function ViewRouter() {
             return _jsx(Dashboard, {});
     }
 }
-function KeyboardHandler() {
-    useKeyboard();
-    return null;
-}
+const CHROME_ROWS = 6;
 export function App() {
     const [state, dispatch] = useReducer(reducer, initialState);
     const [vaultSealed, setVaultSealed] = useState(true);
+    const [showHelp, setShowHelp] = useState(false);
     useEffect(() => {
         try {
             if (isInitialized()) {
@@ -61,5 +92,46 @@ export function App() {
         }, 5000);
         return () => clearInterval(interval);
     }, []);
-    return (_jsx(AppStateContext.Provider, { value: state, children: _jsxs(AppDispatchContext.Provider, { value: dispatch, children: [_jsx(KeyboardHandler, {}), _jsxs(Box, { flexDirection: "column", height: process.stdout.rows || 24, children: [_jsx(Header, { vaultSealed: vaultSealed }), _jsxs(Box, { flexGrow: 1, flexDirection: "column", children: [_jsx(ViewRouter, {}), _jsx(Confirm, {}), state.error && (_jsx(Box, { paddingX: 1, children: _jsx(Box, { borderStyle: "round", borderColor: "red", paddingX: 1, children: _jsx(Text, { color: "red", children: state.error }) }) }))] }), _jsx(KeyHint, {})] })] }) }));
+    const globalHandler = useCallback((input, key) => {
+        if (showHelp) {
+            setShowHelp(false);
+            return true;
+        }
+        if (state.confirmAction) {
+            if (input === 'y' || input === 'Y') {
+                state.confirmAction.onConfirm();
+                dispatch({ type: 'CANCEL_CONFIRM' });
+            }
+            else if (input === 'n' || input === 'N' || key.escape) {
+                dispatch({ type: 'CANCEL_CONFIRM' });
+            }
+            return true;
+        }
+        if (input === '?' && state.currentView !== 'secret-edit') {
+            setShowHelp(true);
+            return true;
+        }
+        if (input === 'q' && state.currentView !== 'secret-edit') {
+            process.exit(0);
+            return true;
+        }
+        if (input === 'x' && state.currentView !== 'secret-edit') {
+            dispatch({ type: 'TOGGLE_REDACT' });
+            return true;
+        }
+        if (key.tab) {
+            const topViews = ['dashboard', 'health', 'secrets'];
+            const base = topViews.includes(state.currentView)
+                ? state.currentView
+                : state.previousView ?? 'dashboard';
+            dispatch({ type: 'NAVIGATE', view: nextTopView(base) });
+            return true;
+        }
+        if (key.escape && state.previousView) {
+            dispatch({ type: 'GO_BACK' });
+            return true;
+        }
+        return false;
+    }, [state.confirmAction, state.currentView, state.previousView, showHelp]);
+    return (_jsx(AppStateContext.Provider, { value: state, children: _jsx(AppDispatchContext.Provider, { value: dispatch, children: _jsx(ToastProvider, { children: _jsx(InputDispatcher, { globalHandler: globalHandler, children: _jsxs(Viewport, { chrome: CHROME_ROWS, children: [_jsx(Header, { vaultSealed: vaultSealed }), _jsx(Box, { flexGrow: 1, flexDirection: "column", children: showHelp ? (_jsx(KeyBindingHelp, { groups: HELP_GROUPS, title: "Fleet TUI \u2014 Keyboard Shortcuts" })) : (_jsxs(_Fragment, { children: [_jsx(ViewRouter, {}), _jsx(Confirm, {}), state.error && (_jsx(Box, { paddingX: 1, children: _jsx(Box, { borderStyle: "round", borderColor: "red", paddingX: 1, children: _jsx(Text, { color: "red", children: state.error }) }) }))] })) }), _jsx(ToastContainer, {}), _jsx(KeyHint, {})] }) }) }) }) }));
 }

package/dist/tui/state.js

@@ -9,6 +9,11 @@ export const initialState = {
     loading: false,
     error: null,
     confirmAction: null,
+    dashboardIndex: 0,
+    healthIndex: 0,
+    secretsIndex: 0,
+    secretsSubView: 'app-list',
+    appDetailIndex: 0,
 };
 export function reducer(state, action) {
     switch (action.type) {
@@ -26,6 +31,7 @@ export function reducer(state, action) {
                 currentView: state.previousView ?? 'dashboard',
                 previousView: null,
                 selectedSecret: null,
+                secretsSubView: 'app-list',
                 error: null,
                 confirmAction: null,
             };
@@ -43,6 +49,15 @@ export function reducer(state, action) {
             return { ...state, confirmAction: action.action };
         case 'CANCEL_CONFIRM':
             return { ...state, confirmAction: null };
+        case 'SET_INDEX': {
+            const key = `${action.view}Index`;
+            if (key in state) {
+                return { ...state, [key]: action.index };
+            }
+            return state;
+        }
+        case 'SET_SECRETS_SUBVIEW':
+            return { ...state, secretsSubView: action.subView, secretsIndex: 0 };
         default:
             return state;
     }

package/dist/tui/tests/flicker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tui/tests/flicker.test.js

@@ -0,0 +1,105 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { render } from 'ink-testing-library';
+import { describe, it, expect } from 'vitest';
+import { TestApp } from './test-app.js';
+const delay = (ms) => new Promise((r) => setTimeout(r, ms));
+const apps = ['app-alpha', 'app-bravo', 'app-charlie'];
+describe('no-flicker guarantees', () => {
+    it('tab switch produces no intermediate frames', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        const beforeCount = frames.length;
+        stdin.write('\t');
+        await delay(50);
+        // grab only the frames produced by this action
+        const newFrames = frames.slice(beforeCount);
+        // every new frame must show the destination view, never a blank or half-state
+        for (const frame of newFrames) {
+            expect(frame).toContain('view:');
+            // should not show a frame with view:dashboard after we switched to health
+            expect(frame).toContain('view:health');
+        }
+    });
+    it('enter on dashboard does not flash dashboard before showing detail', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        stdin.write('j');
+        await delay(50);
+        const beforeCount = frames.length;
+        stdin.write('\r');
+        await delay(50);
+        const newFrames = frames.slice(beforeCount);
+        // should have at least one frame with the detail view
+        const detailFrames = newFrames.filter(f => f.includes('view:app-detail'));
+        expect(detailFrames.length).toBeGreaterThan(0);
+        // no frame should show view:dashboard after the enter press
+        // (which would indicate SELECT_APP rendered before NAVIGATE)
+        for (const frame of newFrames) {
+            if (frame.includes('view:')) {
+                expect(frame).toContain('view:app-detail');
+            }
+        }
+    });
+    it('arrow key navigation produces exactly one visual change', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        const beforeCount = frames.length;
+        stdin.write('\x1B[B'); // down arrow
+        await delay(50);
+        const newFrames = frames.slice(beforeCount);
+        // all new frames should show the cursor on app-bravo
+        for (const frame of newFrames) {
+            expect(frame).toContain('> app-bravo');
+        }
+    });
+    it('escape from sub-view does not flash intermediate state', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        // go to detail
+        stdin.write('\r');
+        await delay(50);
+        expect(frames[frames.length - 1]).toContain('view:app-detail');
+        const beforeCount = frames.length;
+        stdin.write('\x1B');
+        await delay(50);
+        const newFrames = frames.slice(beforeCount);
+        for (const frame of newFrames) {
+            expect(frame).toContain('view:dashboard');
+        }
+    });
+    it('rapid key presses do not produce garbled frames', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        // rapid j-j-j
+        stdin.write('j');
+        stdin.write('j');
+        stdin.write('j');
+        await delay(100);
+        const lastFrame = frames[frames.length - 1];
+        // should be clamped at the last item
+        expect(lastFrame).toContain('> app-charlie');
+        // should still show the view label
+        expect(lastFrame).toContain('view:dashboard');
+    });
+    it('help overlay toggle produces no blank frames', async () => {
+        const { stdin, frames } = render(_jsx(TestApp, { items: apps }));
+        await delay(100);
+        const beforeCount = frames.length;
+        stdin.write('?');
+        await delay(50);
+        const helpFrames = frames.slice(beforeCount);
+        for (const frame of helpFrames) {
+            expect(frame).toContain('view:dashboard');
+            expect(frame).toContain('help-overlay');
+        }
+        const beforeDismiss = frames.length;
+        stdin.write('x');
+        await delay(50);
+        const dismissFrames = frames.slice(beforeDismiss);
+        for (const frame of dismissFrames) {
+            expect(frame).toContain('view:dashboard');
+            // help should be gone
+            expect(frame).not.toContain('help-overlay');
+        }
+    });
+});

package/dist/tui/tests/keyboard-integration.test.d.ts

@@ -0,0 +1 @@
+export {};