dev-cockpit 0.1.0 → 0.2.2

package/package.json

@@ -1,91 +1,94 @@
 {
-  "name": "dev-cockpit",
-  "version": "0.1.0",
-  "description": "A reusable, domain-neutral terminal UI dev cockpit — tabbed pane shell, watcher streaming, optional Docker log tail with highlights, health framework with one-keystroke remediations, transition-only OS notifications, live-markdown Help. Profiles extend it with project-specific commands, repos, and health checks.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/frankfava/package--dev-cockpit.git"
-  },
-  "homepage": "https://github.com/frankfava/package--dev-cockpit#readme",
-  "bugs": {
-    "url": "https://github.com/frankfava/package--dev-cockpit/issues"
-  },
-  "keywords": [
-    "tui",
-    "terminal",
-    "dashboard",
-    "cockpit",
-    "watcher",
-    "docker",
-    "dev",
-    "dx"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=20.12.0"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./ink": {
-      "types": "./dist/ink.d.ts",
-      "import": "./dist/ink.js"
-    },
-    "./react": {
-      "types": "./dist/react.d.ts",
-      "import": "./dist/react.js"
-    }
-  },
-  "bin": {
-    "dev-cockpit": "bin/dev-cockpit.mjs"
-  },
-  "files": [
-    "dist/",
-    "bin/",
-    "docs/",
-    "examples/",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
-    "test": "vitest run"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^8.4.2",
-    "chalk": "^5.3.0",
-    "chokidar": "^5.0.0",
-    "commander": "^12.1.0",
-    "execa": "^9.3.0",
-    "ink": "^7.0.2",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "node-notifier": "^10.0.1",
-    "pino": "^9.3.2",
-    "react": "^19.2.6",
-    "yaml": "^2.5.0",
-    "zod": "^3.23.8",
-    "zustand": "^5.0.13"
-  },
-  "devDependencies": {
-    "@types/node": "^22.5.0",
-    "@types/node-notifier": "^8.0.5",
-    "@types/react": "^19.2.14",
-    "@typescript-eslint/eslint-plugin": "^8.3.0",
-    "@typescript-eslint/parser": "^8.3.0",
-    "eslint": "^9.9.1",
-    "eslint-config-prettier": "^9.1.0",
-    "ink-testing-library": "^4.0.0",
-    "prettier": "^3.3.3",
-    "typescript": "^5.5.4",
-    "vitest": "^2.0.5"
-  }
-}
+	"name": "dev-cockpit",
+	"version": "0.2.2",
+	"description": "A reusable, domain-neutral terminal UI dev cockpit — tabbed pane shell, watcher streaming, optional Docker log tail with highlights, health framework with one-keystroke remediations, transition-only OS notifications, live-markdown Help. Profiles extend it with project-specific commands, repos, and health checks.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/frankfava/package--dev-cockpit.git"
+	},
+	"homepage": "https://github.com/frankfava/package--dev-cockpit#readme",
+	"bugs": {
+		"url": "https://github.com/frankfava/package--dev-cockpit/issues"
+	},
+	"keywords": [
+		"tui",
+		"terminal",
+		"dashboard",
+		"cockpit",
+		"watcher",
+		"docker",
+		"dev",
+		"dx"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=20.12.0"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./ink": {
+			"types": "./dist/ink.d.ts",
+			"import": "./dist/ink.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"import": "./dist/react.js"
+		}
+	},
+	"bin": {
+		"dev-cockpit": "bin/dev-cockpit.mjs"
+	},
+	"files": [
+		"dist/",
+		"bin/",
+		"docs/",
+		"examples/",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "rm -rf dist && node esbuild.config.mjs && tsc -p tsconfig.build.json --emitDeclarationOnly --declaration",
+		"typecheck": "tsc --noEmit",
+		"lint": "eslint 'src/**/*.{ts,tsx}' 'tests/**/*.{ts,tsx}'",
+		"test": "vitest run"
+	},
+	"peerDependencies": {
+		"@inquirer/prompts": "^8.4.2",
+		"node-notifier": "^10.0.1"
+	},
+	"devDependencies": {
+		"@inquirer/prompts": "^8.4.2",
+		"@types/node": "^22.5.0",
+		"@types/node-notifier": "^8.0.5",
+		"@types/react": "^19.2.14",
+		"@typescript-eslint/eslint-plugin": "^8.3.0",
+		"@typescript-eslint/parser": "^8.3.0",
+		"chalk": "^5.3.0",
+		"chokidar": "^5.0.0",
+		"commander": "^12.1.0",
+		"esbuild": "^0.23.1",
+		"eslint": "^9.9.1",
+		"eslint-config-prettier": "^9.1.0",
+		"execa": "^9.3.0",
+		"ink": "^7.0.2",
+		"ink-testing-library": "^4.0.0",
+		"marked": "^15.0.12",
+		"marked-terminal": "^7.3.0",
+		"node-notifier": "^10.0.1",
+		"pino": "^9.3.2",
+		"prettier": "^3.3.3",
+		"react": "^19.2.6",
+		"typescript": "^5.5.4",
+		"vitest": "^2.0.5",
+		"yaml": "^2.5.0",
+		"zod": "^3.23.8",
+		"zustand": "^5.0.13"
+	}
+}

package/dist/buildCli.js

@@ -1,107 +0,0 @@
-/**
- * `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.js

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

package/dist/cockpit/Cockpit.js

@@ -1,73 +0,0 @@
-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.js

@@ -1,33 +0,0 @@
-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.js

@@ -1,12 +0,0 @@
-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.js

@@ -1,22 +0,0 @@
-/**
- * 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'),
-};

package/dist/cockpit/help/loader.js

@@ -1,118 +0,0 @@
-/**
- * Help-tab content loader.
- *
- * Resolves a docs/ folder by walking up from a given module URL, looking for
- * a directory containing both `package.json` and `docs/index.md`. This works
- * across three contexts:
- *   - tsx-from-source     → src/cockpit/help/loader.ts → ../../../docs
- *   - dist/-from-build    → dist/cockpit/help/loader.js → ../../../docs
- *   - npm i installed     → node_modules/<pkg>/dist/.../loader.js → <pkg>/docs
- *
- * The loader supports merging multiple sources: core docs first, then any
- * profile-supplied sources (paths or inline pages). Sources later in the list
- * override earlier ones by slug. A source with `omit: true` removes that slug.
- *
- * `docs/index.md` defines the ordered page list for that source. Each entry
- * is a markdown bullet of the form:
- *   - [Title](./slug.md) — optional summary
- *
- * The index page is itself returned as the first HelpPage (slug = 'index').
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-/** Walk up from `startUrl` (or this module by default) for package.json + docs/index.md. */
-export function resolveDocsRoot(startUrl = import.meta.url) {
-    let dir = path.dirname(fileURLToPath(startUrl));
-    while (dir !== path.dirname(dir)) {
-        const pkgJson = path.join(dir, 'package.json');
-        const docsIndex = path.join(dir, 'docs', 'index.md');
-        if (fs.existsSync(pkgJson) && fs.existsSync(docsIndex)) {
-            return path.join(dir, 'docs');
-        }
-        dir = path.dirname(dir);
-    }
-    return null;
-}
-/** Parse the markdown index into an ordered list of page slugs. */
-export function parseIndex(indexBody) {
-    const out = [];
-    const linkRe = /^\s*[-*]\s+\[([^\]]+)\]\((?:\.\/)?([^)]+?)\.md\)/;
-    for (const line of indexBody.split(/\r?\n/)) {
-        const match = linkRe.exec(line);
-        if (match && match[1] && match[2]) {
-            out.push({ title: match[1], slug: match[2] });
-        }
-    }
-    return out;
-}
-/** Load all pages (in index order) from a single docs/ directory. */
-export function loadPagesFromDir(docsRoot) {
-    const indexPath = path.join(docsRoot, 'index.md');
-    let indexBody;
-    try {
-        indexBody = fs.readFileSync(indexPath, 'utf8');
-    }
-    catch {
-        return [];
-    }
-    const pages = [{ slug: 'index', title: 'Index', path: indexPath, body: indexBody }];
-    for (const entry of parseIndex(indexBody)) {
-        const pagePath = path.join(docsRoot, `${entry.slug}.md`);
-        try {
-            const body = fs.readFileSync(pagePath, 'utf8');
-            pages.push({ slug: entry.slug, title: entry.title, path: pagePath, body });
-        }
-        catch {
-            // Missing page file — skip silently.
-        }
-    }
-    return pages;
-}
-/**
- * Load and merge help pages from core + any contributed sources.
- *
- * Returns `null` only if the core docs root cannot be found AND no sources
- * provide pages. Otherwise returns a non-empty merged list with `defaultIndex`
- * pointing at `defaultPage` (or 0 when `defaultPage` is absent / unknown).
- */
-export function loadHelpPages(opts = {}) {
-    const coreUrl = opts.coreUrl ?? import.meta.url;
-    const corePages = [];
-    const coreRoot = resolveDocsRoot(coreUrl);
-    if (coreRoot) {
-        corePages.push(...loadPagesFromDir(coreRoot));
-    }
-    // Merge sources in order. Map keyed by slug preserves first-write insertion
-    // order; later sources REPLACE by re-assigning the same key.
-    const merged = new Map();
-    for (const page of corePages) {
-        merged.set(page.slug, page);
-    }
-    for (const src of opts.sources ?? []) {
-        if (src.omit && src.id) {
-            merged.delete(src.id);
-            continue;
-        }
-        if (src.page) {
-            merged.set(src.page.slug, src.page);
-            continue;
-        }
-        if (src.path) {
-            const pages = loadPagesFromDir(src.path);
-            for (const p of pages) {
-                merged.set(p.slug, p);
-            }
-        }
-    }
-    const pages = Array.from(merged.values());
-    if (pages.length === 0)
-        return null;
-    let defaultIndex = 0;
-    if (opts.defaultPage) {
-        const idx = pages.findIndex((p) => p.slug === opts.defaultPage);
-        if (idx >= 0)
-            defaultIndex = idx;
-    }
-    return { pages, defaultIndex };
-}

package/dist/cockpit/help/renderer.js

@@ -1,35 +0,0 @@
-/**
- * Markdown → terminal ANSI renderer.
- *
- * marked + marked-terminal — the latter emits an ANSI string handed to Ink's
- * <Text>. Ink passes ANSI through to stdout. Tradeoff accepted: long lines
- * wrap at the terminal column boundary, which is fine for prose docs.
- *
- * Renderer is configured once at module load (marked-terminal mutates the
- * shared marked instance).
- */
-import { marked } from 'marked';
-import { markedTerminal } from 'marked-terminal';
-let configured = false;
-function ensureConfigured() {
-    if (configured)
-        return;
-    marked.use(markedTerminal());
-    configured = true;
-}
-/**
- * Render a markdown string to ANSI-colored terminal output.
- * Always returns a string; never throws on well-formed markdown.
- */
-export function renderMarkdown(markdown) {
-    ensureConfigured();
-    if (!markdown)
-        return '';
-    try {
-        const out = marked.parse(markdown);
-        return typeof out === 'string' ? out : markdown;
-    }
-    catch {
-        return markdown;
-    }
-}

package/dist/cockpit/help/types.js

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

package/dist/cockpit/hooks/useCockpitStore.js

@@ -1,5 +0,0 @@
-import { useSyncExternalStore } from 'react';
-import { cockpitStore } from '../state/store.js';
-export function useCockpitStore(selector) {
-    return useSyncExternalStore(cockpitStore.subscribe, () => selector(cockpitStore.getState()));
-}