dev-cockpit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `dev-cockpit` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-10
+
+First pre-1.0 release. The public surface (`Profile` interface with `boot` lifecycle hook, `buildCli`, the four core commands `dev / doctor / init-config / mount`, the `cockpit.yaml` schema with `version: 1`) is stable enough for first consumers to depend on. Expect minor churn until the post-1.0 roadmap items land.
+
+### Added
+
+- **Interactive `init-config` wizard** (`-i` / `--interactive`). Seven-step onboarding with project sniffing — auto-detects compose files + services, `package.json` scripts as watcher candidates, npm/yarn/pnpm workspaces as repo entries, and surfaces sensible defaults so most prompts just need an enter. Closes by offering to run `doctor` immediately.
+- **`profile.boot` lifecycle hook**. Profiles return `{cockpitHandlers, subscribeFsEvents, cleanup}` from a single async function called after config load + workspace resolution and before the cockpit renders. Replaces the older "profile registers its own dev command" override pattern.
+- **`profile.reposProvider(ctx)` receives the wizard context** so profiles can drive the Repos pane from their validated `profile.<appName>` namespace.
+- **`killAllSpawned()` global subprocess registry** — every `spawnStream` auto-registers + auto-deregisters; `killAllSpawned()` SIGTERMs stragglers, awaits reap, falls back to SIGKILL after 1.5s. Eliminates the "second Ctrl-C needed to quit" class of bugs.
+- **Periodic poll for `docker`-trigger health checks** (default 5s, configurable via `SchedulerDeps.dockerPollIntervalMs`, set 0 to disable). `docker compose down` mid-session now flips `container-running` / `port-open` checks red within the poll interval.
+- **Synthetic test fixtures** under `tests/fixtures/`: `plain-node` (no docker block; tsc watcher; http-ok + file-exists checks) and `dockerized` (alpine heartbeat + redis; container-running + port-open checks). Smoke tests via `ink-testing-library`.
+- **Generic CLI commands** — `dev / doctor / init-config / mount` — with `buildCli({ profile? })` factory. Profile-first registration: `setupCli(program)` runs before core, claimed names skip their core counterpart (one mechanism, no array mutation).
+- **Health framework** with five built-in check types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`), `useHealth` hook orchestrating the scheduler + transition diffing + remediation dispatch, per-item `notify` overrides.
+- **Watcher subsystem** (chokidar lazy-spawn, reactive lint, transition-only build notifications).
+- **Docker subsystem** (log tailer with live-check, highlight engine, stack-trace extractor, restart helper).
+- **Cockpit shell** — four-pane TUI (Repos / Output / Health / Help), tab nav, modals (filter / search), live-markdown Help loader.
+- **Core modules** — config loader (zod + `version: 1` schema), state paths (`xdg_state_home/<appName>/<hash>/`), pino logger, execa subprocess wrapper, OS notifier (detached `osascript` / `notify-send` so the helper doesn't keep the parent loop alive).
+
+### Changed
+
+- **OS notifier no longer uses `node-notifier`.** Direct `child_process.spawn` with `detached: true` + `stdio: 'ignore'` + `unref()` so notification helpers run independently of the cockpit's lifetime.
+- **`DockerLogTailer.stop()` and `WatcherManager.stop()` await child SIGTERM reap** before resolving (previously sent the signal and returned immediately, leaving handles in the event loop).
+- **Bin shim filters Node 22's `ExperimentalWarning: Importing JSON modules`** (cli-boxes uses `with {type: 'json'}`). Filtered at the bin level via dynamic-import-after-emitWarning-hook.
+
+### Fixed
+
+- Per-phase exit cleanup so the shell prompt returns immediately on `q` — no more "second Ctrl-C needed to quit".
+
+## [0.0.0] — early lifts
+
+Initial scaffold + the phase 2-6 lifts of the cockpit shell + watcher / docker / health subsystems into a generic, domain-neutral library. Captured here for completeness; commit history in git is the authoritative record.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Fava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# dev-cockpit
+
+A reusable, domain-neutral terminal UI dev cockpit. One window for the long-running processes you babysit during development: code, logs, health, and the keystrokes to fix things when they break.
+
+```
+┌── Repos ── Output ── Health ── Help ────────────────── [↔ / tab] cycle ──┐
+│ Repos                                                                     │
+│   web      docker     idle                                               │
+│   db       docker     idle                                               │
+│   cache    docker     idle                                               │
+│                                                                           │
+│ Recent errors:                                                            │
+│   web │ Stack trace at /srv/app/handler.ts:42                            │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+## What's in the box
+
+- **Four-pane TUI** — Repos / Output / Health / Help, tab-cycle nav, filter + search modals.
+- **Watchers** — long-running processes spawned once on boot; their stdout streams into Output, tagged by id.
+- **Docker log tailing** — stream `docker compose logs -f <services>` into the same Output pane with regex-driven highlights for errors / stack traces.
+- **Health framework** — five built-in check types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`) plus profile-contributed ones; each gets a row on the Health pane and a single-keystroke remediation.
+- **Profile interface** — drop-in adapter so a domain-specific tool can wire its own discoverer / repos / health / commands / cockpit handlers without forking the shell.
+- **Live markdown Help** — pages render inside the cockpit; profiles can layer their own docs over the generic ones.
+- **Native OS notifications** — fire on state transitions only (no spam). Detached helper, never blocks process exit.
+
+## Install
+
+```sh
+npm install -g dev-cockpit
+```
+
+Or `npm link` from a checkout for development.
+
+## Quick start
+
+```sh
+cd your-project
+dev-cockpit init-config -i    # interactive wizard, 7 steps with auto-detection
+dev-cockpit doctor             # validate + print initial health
+dev-cockpit dev                # boot the cockpit
+```
+
+The wizard sniffs your project: if there's a `compose.yaml` it suggests services to tail, if `package.json` has a `dev` script it offers it as a watcher, if there are workspaces it surfaces them as repo entries. Most prompts just need an enter.
+
+## Configuration
+
+Single file, `cockpit.yaml` at your project root. Schema enforced by zod (`version: 1`). Full reference: [`docs/config-reference.md`](./docs/config-reference.md). Minimal example:
+
+```yaml
+version: 1
+appName: my-app
+
+watchers:
+  - id: vite
+    command: npm run dev
+
+docker:
+  composeFile: compose.yaml
+  services:
+    - { name: db }
+    - { name: cache }
+
+health:
+  - id: app-up
+    label: app responsive
+    type: http-ok
+    url: http://localhost:3000/health
+    severity: error
+    remediation:
+      key: R
+      label: restart app
+      command: docker compose restart app
+
+notifications:
+  enabled: true
+```
+
+## Profiles
+
+A profile is a domain-specific bundle that plugs into dev-cockpit's lifecycle. It contributes any combination of:
+
+- `discoverer`        — workspace root resolution
+- `reposProvider`     — Repos-pane entries
+- `healthChecks`      — pre-built `HealthCheck[]` (programmatic, beyond the five built-ins)
+- `setupCli`          — extra CLI commands (the profile's own `select`, `release`, etc.)
+- `helpSources`       — markdown docs that layer over the generic Help
+- `configSchemaExt`   — zod schema validating the profile's `profile.<appName>` namespace
+- `mountCandidatesProvider` — auto-detected bind-mount candidates
+- `boot`              — async lifecycle hook returning Cockpit pane handlers + `subscribeFsEvents` + `cleanup`
+
+A profile is its own npm package — its bin entry composes `buildCli({ profile })` and that's it. The skeleton:
+
+```ts
+import type { Profile } from 'dev-cockpit';
+
+export const myProfile: Profile = {
+  appName: 'my-app',
+  healthChecks: [...],
+  boot: ({ config, workspaceRoot }) => ({
+    cockpitHandlers: { runRepoAction, onWatchToggle, onLint, onOpenError },
+    subscribeFsEvents: (listener) => watcherManager.subscribeFsEvents(listener),
+    cleanup: () => watcherManager.stop(),
+  }),
+};
+
+// Bin entry — that's it.
+import { buildCli } from 'dev-cockpit';
+buildCli({ profile: myProfile }).parse(process.argv);
+```
+
+## Documentation
+
+| Topic | Link |
+|---|---|
+| Getting started | [`docs/getting-started.md`](./docs/getting-started.md) |
+| Commands | [`docs/commands.md`](./docs/commands.md) |
+| `init-config` wizard | [`docs/init-config.md`](./docs/init-config.md) |
+| Panes | [`docs/panes.md`](./docs/panes.md) |
+| Watchers | [`docs/watchers.md`](./docs/watchers.md) |
+| Health | [`docs/health.md`](./docs/health.md) |
+| Mounts | [`docs/mount.md`](./docs/mount.md) |
+| Notifications | [`docs/notifications.md`](./docs/notifications.md) |
+| Config reference | [`docs/config-reference.md`](./docs/config-reference.md) |
+| ADRs | [`adr/`](./adr/) |
+| Changelog | [`CHANGELOG.md`](./CHANGELOG.md) |
+| License | MIT |
+
+## Status
+
+Pre-1.0. The public surface (`Profile` interface, `buildCli`, the four core commands, `cockpit.yaml` schema with `version: 1`) is stable enough for first consumers to depend on; expect minor churn until the post-1.0 roadmap items land. See `CHANGELOG.md` for what's shipped.

package/bin/dev-cockpit.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Filter Node 22's ExperimentalWarning about JSON modules. The warning fires
+// from a transitive dep (cli-boxes uses `import boxes from './boxes.json' with
+// {type: 'json'}`) the moment the cockpit shell's import graph resolves. It's
+// benign — Node will stabilise JSON modules — but loud on every CLI invocation.
+// Installing the filter here, before any dynamic import, ensures it's in place
+// before cli-boxes loads.
+const orig = process.emitWarning.bind(process);
+process.emitWarning = (w, ...rest) => {
+  // The JSON-modules warning fires as a plain string with the type passed
+  // separately (`process.emitWarning(text, 'ExperimentalWarning')`), so we
+  // match on the message text directly. The `.name` check from earlier
+  // only worked when the caller handed us an Error object.
+  const msg = typeof w === 'string' ? w : (w?.message ?? '');
+  if (/JSON modules/i.test(msg)) return;
+  return orig(w, ...rest);
+};
+
+const { buildCli } = await import('../dist/index.js');
+buildCli().parse();

package/dist/buildCli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `buildCli({ profile? })` — assemble the dev-cockpit commander program.
+ *
+ * Registration order: **profile first, core last.** The profile's
+ * `setupCli(program)` runs before any core command is registered. When core
+ * goes to register a command (`dev`, `doctor`, `init-config`, `mount`),
+ * it skips any name the profile already claimed. Profiles override by
+ * registering first, not by mutating commander's internal arrays — one
+ * mechanism, no escape hatch.
+ */
+import { Command } from 'commander';
+import type { Profile } from './core/types.js';
+export interface BuildCliOptions {
+    profile?: Profile;
+}
+export declare function buildCli(opts?: BuildCliOptions): Command;
+//# sourceMappingURL=buildCli.d.ts.map

package/dist/buildCli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildCli.d.ts","sourceRoot":"","sources":["../src/buildCli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAU/C,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAkBD,wBAAgB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAwF5D"}

package/dist/buildCli.js

@@ -0,0 +1,107 @@
+/**
+ * `buildCli({ profile? })` — assemble the dev-cockpit commander program.
+ *
+ * Registration order: **profile first, core last.** The profile's
+ * `setupCli(program)` runs before any core command is registered. When core
+ * goes to register a command (`dev`, `doctor`, `init-config`, `mount`),
+ * it skips any name the profile already claimed. Profiles override by
+ * registering first, not by mutating commander's internal arrays — one
+ * mechanism, no escape hatch.
+ */
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { devCommand } from './commands/dev.js';
+import { doctorCommand } from './commands/doctor.js';
+import { initConfigCommand } from './commands/init-config.js';
+import { mountCommand, mountStatusCommand, mountClearCommand, } from './commands/mount.js';
+function readPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf-8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function hasCommand(program, name) {
+    return program.commands.some((c) => c.name() === name);
+}
+export function buildCli(opts = {}) {
+    const program = new Command();
+    const profile = opts.profile;
+    const appName = profile?.appName ?? 'dev-cockpit';
+    program
+        .name(appName)
+        .description(profile
+        ? `${appName} — built on dev-cockpit`
+        : 'Generic terminal UI dev cockpit')
+        .version(readPackageVersion(), '-V, --version', 'Output the version number');
+    // Profile registers first; its commands win by precedence.
+    if (profile?.setupCli) {
+        profile.setupCli(program);
+    }
+    // Core commands fill in any names the profile didn't claim.
+    if (!hasCommand(program, 'dev')) {
+        program
+            .command('dev')
+            .description('Boot the three-pane TUI (Repos / Output / Health / Help)')
+            .option('-c, --config <path>', 'Path to cockpit.yaml', 'cockpit.yaml')
+            .action(async (cmdOpts) => {
+            await devCommand({ config: cmdOpts.config, profile });
+        });
+    }
+    if (!hasCommand(program, 'doctor')) {
+        program
+            .command('doctor')
+            .description('Run all health checks once and print a status table')
+            .option('-c, --config <path>', 'Path to cockpit.yaml', 'cockpit.yaml')
+            .action(async (cmdOpts) => {
+            await doctorCommand({ config: cmdOpts.config, profile });
+        });
+    }
+    if (!hasCommand(program, 'init-config')) {
+        program
+            .command('init-config')
+            .description('Write a starter cockpit.yaml in the current directory')
+            .option('-f, --force', 'Overwrite an existing cockpit.yaml without prompting', false)
+            .option('--with-docker', 'Include an uncommented docker block (static template only)', false)
+            .option('-i, --interactive', 'Walk through prompts to populate the file (skips static template)', false)
+            .action(async (cmdOpts) => {
+            await initConfigCommand({
+                force: cmdOpts.force ?? false,
+                withDocker: cmdOpts.withDocker ?? false,
+                interactive: cmdOpts.interactive ?? false,
+                appName,
+                profile,
+            });
+        });
+    }
+    if (!hasCommand(program, 'mount')) {
+        const mountCmd = program
+            .command('mount')
+            .description('Generate a Docker compose overlay for bind-mount candidates')
+            .option('-c, --config <path>', 'Path to cockpit.yaml', 'cockpit.yaml')
+            .option('-s, --service <name>', 'Target compose service (default: first in docker.services)')
+            .action(async (cmdOpts) => {
+            await mountCommand({ config: cmdOpts.config, service: cmdOpts.service, profile });
+        });
+        mountCmd
+            .command('status')
+            .description('Show the active overlay manifest')
+            .option('-c, --config <path>', 'Path to cockpit.yaml', 'cockpit.yaml')
+            .action(async (cmdOpts) => {
+            await mountStatusCommand({ config: cmdOpts.config, profile });
+        });
+        mountCmd
+            .command('clear')
+            .description('Remove the overlay file and manifest')
+            .option('-c, --config <path>', 'Path to cockpit.yaml', 'cockpit.yaml')
+            .action(async (cmdOpts) => {
+            await mountClearCommand({ config: cmdOpts.config, profile });
+        });
+    }
+    return program;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,2 @@
+import { buildCli } from './index.js';
+buildCli().parse();

package/dist/cockpit/Cockpit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Top-level Ink component for the cockpit TUI.
+ *
+ * Layout:
+ *   ┌──────────────────────────────────────────────┐
+ *   │  TabBar (tabs + global key legend)           │
+ *   ├──────────────────────────────────────────────┤
+ *   │  Active pane OR active modal (full area)     │
+ *   ├──────────────────────────────────────────────┤
+ *   │  Footer (per-tab contextual hints)           │
+ *   └──────────────────────────────────────────────┘
+ *
+ * Modals render IN PLACE of the active pane (opaque, fills available height).
+ *
+ * Domain handlers (repo action, lint, open-error) flow in via props and are
+ * routed through useGlobalKeys. Health remediation is owned by the `health`
+ * option — useHealth produces the runRemediation dispatcher (one mechanism).
+ */
+import React from 'react';
+import { type FooterLegends } from './Footer.js';
+import { type UseGlobalKeysOptions } from './hooks/useGlobalKeys.js';
+import { type UseHealthOptions } from '../health/useHealth.js';
+export type CockpitProps = Omit<UseGlobalKeysOptions, 'onQuit' | 'runRemediation'> & {
+    /** Per-tab footer legend overrides. */
+    footerLegends?: FooterLegends;
+    /**
+     * Enables the integrated health framework. When provided, useHealth manages
+     * the scheduler, transitions, notifications, and remediation dispatch.
+     */
+    health?: UseHealthOptions;
+};
+export declare function Cockpit(props: CockpitProps): React.ReactElement;
+//# sourceMappingURL=Cockpit.d.ts.map

package/dist/cockpit/Cockpit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cockpit.d.ts","sourceRoot":"","sources":["../../src/cockpit/Cockpit.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAA8B,MAAM,OAAO,CAAC;AAOnD,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEpF,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,gBAAgB,CAAC,GAAG;IACnF,uCAAuC;IACvC,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CAkD/D"}

package/dist/cockpit/Cockpit.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Top-level Ink component for the cockpit TUI.
+ *
+ * Layout:
+ *   ┌──────────────────────────────────────────────┐
+ *   │  TabBar (tabs + global key legend)           │
+ *   ├──────────────────────────────────────────────┤
+ *   │  Active pane OR active modal (full area)     │
+ *   ├──────────────────────────────────────────────┤
+ *   │  Footer (per-tab contextual hints)           │
+ *   └──────────────────────────────────────────────┘
+ *
+ * Modals render IN PLACE of the active pane (opaque, fills available height).
+ *
+ * Domain handlers (repo action, lint, open-error) flow in via props and are
+ * routed through useGlobalKeys. Health remediation is owned by the `health`
+ * option — useHealth produces the runRemediation dispatcher (one mechanism).
+ */
+import { useEffect, useState } from 'react';
+import { Box, useApp, useStdout } from 'ink';
+import { Repos } from './panes/Repos.js';
+import { Output } from './panes/Output.js';
+import { Health } from './panes/Health.js';
+import { Help } from './panes/Help.js';
+import { TabBar } from './TabBar.js';
+import { Footer } from './Footer.js';
+import { FilterModal } from './panes/FilterModal.js';
+import { SearchModal } from './panes/SearchModal.js';
+import { useGlobalKeys } from './hooks/useGlobalKeys.js';
+import { useCockpitStore } from './hooks/useCockpitStore.js';
+import { useHealth } from '../health/useHealth.js';
+export function Cockpit(props) {
+    const { health, footerLegends, ...rest } = props;
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const focus = useCockpitStore((s) => s.focus);
+    const activeModal = useCockpitStore((s) => s.activeModal);
+    const [rows, setRows] = useState(stdout.rows ?? 24);
+    useEffect(() => {
+        const onResize = () => setRows(stdout.rows ?? 24);
+        stdout.on('resize', onResize);
+        return () => {
+            stdout.off('resize', onResize);
+        };
+    }, [stdout]);
+    const healthHandle = useHealth(health);
+    useGlobalKeys({
+        onQuit: exit,
+        ...rest,
+        runRemediation: healthHandle?.runRemediation,
+    });
+    let mainContent;
+    if (activeModal === 'filter') {
+        mainContent = _jsx(FilterModal, {});
+    }
+    else if (activeModal === 'search') {
+        mainContent = _jsx(SearchModal, {});
+    }
+    else if (focus === 'repos') {
+        mainContent = _jsx(Repos, {});
+    }
+    else if (focus === 'output') {
+        mainContent = _jsx(Output, {});
+    }
+    else if (focus === 'health') {
+        mainContent = _jsx(Health, {});
+    }
+    else {
+        mainContent = _jsx(Help, {});
+    }
+    return (_jsxs(Box, { flexDirection: "column", height: rows, children: [_jsx(TabBar, {}), _jsx(Box, { flexDirection: "column", flexGrow: 1, children: mainContent }), _jsx(Footer, { legends: footerLegends })] }));
+}

package/dist/cockpit/Footer.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Footer — per-tab contextual hotkey hints.
+ *
+ * TabBar owns the global navigation legend (tab cycle); the Footer only
+ * shows what the user can do INSIDE the currently active tab.
+ *
+ * Legends are pluggable via props so profiles can override the default
+ * verbiage. Defaults are the generic shapes that apply to every consumer.
+ */
+import React from 'react';
+export interface FooterLegends {
+    reposRepo?: string;
+    reposDocker?: string;
+    output?: string;
+    health?: string;
+    help?: string;
+}
+export interface FooterProps {
+    legends?: FooterLegends;
+}
+export declare function Footer({ legends }?: FooterProps): React.ReactElement;
+//# sourceMappingURL=Footer.d.ts.map

package/dist/cockpit/Footer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Footer.d.ts","sourceRoot":"","sources":["../../src/cockpit/Footer.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAW1B,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,wBAAgB,MAAM,CAAC,EAAE,OAAO,EAAE,GAAE,WAAgB,GAAG,KAAK,CAAC,YAAY,CA2BxE"}

package/dist/cockpit/Footer.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useCockpitStore } from './hooks/useCockpitStore.js';
+const DEFAULT_REPOS_LEGEND_REPO = '[↑↓] select  [r] action  [w] watch  [l] lint';
+const DEFAULT_REPOS_LEGEND_DOCKER = '[↑↓] select  [r] restart';
+const DEFAULT_OUTPUT_LEGEND = '[c] clear  [/] search  [f] filter';
+const DEFAULT_HEALTH_LEGEND = '[↑↓] select  [enter] details  [letter] fix';
+const DEFAULT_HELP_LEGEND = 'read-only — see TabBar for navigation';
+export function Footer({ legends } = {}) {
+    const focus = useCockpitStore((s) => s.focus);
+    const reposLegend = useCockpitStore((s) => {
+        const key = s.repoOrder[s.selectedRepoIndex];
+        const entry = key ? s.repos[key] : undefined;
+        if (entry?.kind === 'docker') {
+            return legends?.reposDocker ?? DEFAULT_REPOS_LEGEND_DOCKER;
+        }
+        return legends?.reposRepo ?? DEFAULT_REPOS_LEGEND_REPO;
+    });
+    let legend;
+    if (focus === 'repos') {
+        legend = reposLegend;
+    }
+    else if (focus === 'output') {
+        legend = legends?.output ?? DEFAULT_OUTPUT_LEGEND;
+    }
+    else if (focus === 'health') {
+        legend = legends?.health ?? DEFAULT_HEALTH_LEGEND;
+    }
+    else {
+        legend = legends?.help ?? DEFAULT_HELP_LEGEND;
+    }
+    return (_jsx(Box, { borderStyle: "single", paddingX: 1, children: _jsx(Text, { dimColor: true, children: legend }) }));
+}

package/dist/cockpit/TabBar.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+export declare function TabBar(): React.ReactElement;
+//# sourceMappingURL=TabBar.d.ts.map

package/dist/cockpit/TabBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TabBar.d.ts","sourceRoot":"","sources":["../../src/cockpit/TabBar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,wBAAgB,MAAM,IAAI,KAAK,CAAC,YAAY,CAwB3C"}

package/dist/cockpit/TabBar.js

@@ -0,0 +1,12 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from 'ink';
+import { useCockpitStore } from './hooks/useCockpitStore.js';
+import { TAB_ORDER, TAB_LABELS } from './tab-state.js';
+export function TabBar() {
+    const focus = useCockpitStore((s) => s.focus);
+    return (_jsxs(Box, { borderStyle: "single", paddingX: 1, flexDirection: "row", children: [_jsx(Box, { flexDirection: "row", children: TAB_ORDER.map((tab) => {
+                    const isActive = focus === tab;
+                    const label = TAB_LABELS[tab];
+                    return (_jsx(Box, { marginRight: 2, children: _jsxs(Text, { inverse: isActive, bold: isActive, color: isActive ? 'cyan' : undefined, children: [' ', label, ' '] }) }, tab));
+                }) }), _jsx(Box, { flexGrow: 1, justifyContent: "flex-end", children: _jsx(Text, { dimColor: true, children: "[\u2190\u2192 / tab] cycle tabs" }) })] }));
+}

package/dist/cockpit/help/content.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compiled-in fallback for the Help tab.
+ *
+ * Source of truth is `docs/` (loaded at runtime by `loader.ts`). This
+ * fallback only renders when the loader can't locate any docs/ — typically
+ * a published tarball that forgot to whitelist the folder, or a dev build
+ * run from an unusual working directory.
+ */
+import type { HelpPage } from './types.js';
+/** A pre-rendered fallback page. The pane shows this when no docs/ can be located. */
+export declare const FALLBACK_PAGE: HelpPage;
+//# sourceMappingURL=content.d.ts.map

package/dist/cockpit/help/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/cockpit/help/content.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,sFAAsF;AACtF,eAAO,MAAM,aAAa,EAAE,QAY3B,CAAC"}

package/dist/cockpit/help/content.js

@@ -0,0 +1,22 @@
+/**
+ * Compiled-in fallback for the Help tab.
+ *
+ * Source of truth is `docs/` (loaded at runtime by `loader.ts`). This
+ * fallback only renders when the loader can't locate any docs/ — typically
+ * a published tarball that forgot to whitelist the folder, or a dev build
+ * run from an unusual working directory.
+ */
+/** A pre-rendered fallback page. The pane shows this when no docs/ can be located. */
+export const FALLBACK_PAGE = {
+    slug: 'fallback',
+    title: 'Help (fallback)',
+    path: '',
+    body: [
+        '# Help is unavailable',
+        '',
+        'The Help tab usually loads markdown from the `docs/` folder bundled with the package.',
+        'You are seeing this fallback because the loader could not find `docs/index.md`.',
+        'Check that `docs/` ships alongside `dist/` in the install, or that the consumer profile',
+        'configured `helpSources` correctly.',
+    ].join('\n'),
+};