sickbay 1.3.0 → 1.3.1

package/README.md

@@ -0,0 +1,244 @@
+# @nebulord/sickbay
+
+The terminal interface for Sickbay. Built with [Ink](https://github.com/vadimdemedes/ink) (React for terminals) and [Commander](https://github.com/tj/commander.js).
+
+## Quickstart
+
+```bash
+# Terminal
+npx sickbay
+
+# Web
+npx sickbay --web
+
+# TUI
+npx sickbay --tui
+```
+
+## Usage
+
+```bash
+sickbay [options]
+```
+
+### Commands
+
+| Command            | Description                                                        |
+| ------------------ | ------------------------------------------------------------------ |
+| `init [options]`   | Scaffold `.sickbay/`, run baseline scan, seed history              |
+| `fix [options]`    | Interactively fix issues found by sickbay scan                     |
+| `trend [options]`  | Show score history and trends over time                            |
+| `stats [options]`  | Show a quick codebase overview and project summary                 |
+| `doctor [options]` | Diagnose project setup and configuration issues                    |
+| `tui [options]`    | Persistent live dashboard with file watching and activity tracking |
+
+### Flags
+
+| Flag                   | Default         | Description                       |
+| ---------------------- | --------------- | --------------------------------- |
+| `-p, --path <path>`    | `process.cwd()` | Path to the project to analyze    |
+| `-c, --checks <names>` | all             | Comma-separated check IDs to run  |
+| `--json`               | false           | Output raw JSON to stdout (no UI) |
+| `--web`                | false           | Open web dashboard after scan     |
+| `--verbose`            | false           | Show tool output during checks    |
+| `-V, --version`        |                 | Print version                     |
+| `-h, --help`           |                 | Show help                         |
+
+### Examples
+
+```bash
+# Analyze current directory
+sickbay
+
+# Analyze another project
+sickbay -p ~/projects/my-app
+
+# Run specific checks only
+sickbay --checks knip,npm-audit,depcheck
+
+# JSON output for CI
+sickbay --json | jq '.overallScore'
+
+# Get just the summary
+sickbay --json | jq '.summary'
+
+# List all check names and their scores
+sickbay --json | jq '.checks[] | {name, score}'
+
+# Get only failing checks
+sickbay --json | jq '.checks[] | select(.status == "fail")'
+
+# Open web dashboard
+sickbay --web
+
+# Initialize .sickbay/ folder with baseline scan
+sickbay init
+
+# Initialize for a specific project
+sickbay init --path ~/projects/my-app
+
+# Interactively fix issues
+sickbay fix
+
+# View score history and trends
+sickbay trend
+
+# Get quick project stats
+sickbay stats
+
+# Diagnose project setup
+sickbay doctor
+
+# Launch tui dashboard (current directory, file watching enabled)
+sickbay tui
+
+# TUI for a specific project, disable file watching
+sickbay tui --path ~/projects/my-app --no-watch
+
+# TUI with faster auto-refresh (60 seconds) and specific checks only
+sickbay tui --path ~/projects/my-app --refresh 60 --checks knip,npm-audit,eslint
+```
+
+## `sickbay init` vs `sickbay`
+
+**Run `sickbay init` once when setting up a project for the first time.**
+
+It scaffolds the `.sickbay/` data folder, saves a `baseline.json` snapshot of the project's current health, and wires up `.gitignore` entries so `history.json` doesn't pollute your repo. Think of it as "onboarding" Sickbay to a project.
+
+**Run `sickbay` for every subsequent scan.**
+
+Each scan automatically appends an entry to `.sickbay/history.json`, so your score trend builds up over time without any extra steps. The History tab in the web dashboard (`sickbay --web`) reads from this file.
+
+|                           | First time     | Ongoing        |
+| ------------------------- | -------------- | -------------- |
+| Command                   | `sickbay init` | `sickbay`      |
+| Creates `.sickbay/`       | ✓              | ✓ (if missing) |
+| Saves `baseline.json`     | ✓              | ✗              |
+| Updates root `.gitignore` | ✓              | ✗              |
+| Appends to `history.json` | ✓              | ✓              |
+
+> If you skip `sickbay init` and go straight to `sickbay`, history will still accumulate — you just won't have a baseline snapshot or gitignore entries for `.sickbay/`. But you can always ignore it manually.
+
+## TUI Dashboard
+
+`sickbay tui` opens a persistent split-pane TUI that continuously monitors your project. Unlike a one-shot scan, it stays running, watches for file changes, and lets you interact with results in real time.
+
+### TUI Flags
+
+| Flag                    | Default         | Description                           |
+| ----------------------- | --------------- | ------------------------------------- |
+| `-p, --path <path>`     | `process.cwd()` | Project path to monitor               |
+| `--no-watch`            | watch enabled   | Disable file-watching auto-refresh    |
+| `--refresh <seconds>`   | `300`           | Auto-refresh interval in seconds      |
+| `-c, --checks <checks>` | all             | Comma-separated list of checks to run |
+
+### Panels
+
+The tui displays six panels arranged in a responsive grid:
+
+| Panel          | Key | Content                                                                    |
+| -------------- | --- | -------------------------------------------------------------------------- |
+| **Health**     | `h` | All check results with status icons, names, and score bars                 |
+| **Score**      | —   | Overall score (0–100), color-coded status, issue counts, score delta       |
+| **Trend**      | `t` | Sparkline charts for overall score and each category (last 10 scans)       |
+| **Git**        | `g` | Branch, commits ahead/behind, modified/staged/untracked files, last commit |
+| **Quick Wins** | `q` | Top 5 actionable fixes prioritized by severity                             |
+| **Activity**   | `a` | Time-stamped event log (scans, file changes, regressions, git changes)     |
+
+### Keyboard Controls
+
+| Key      | Action                                     |
+| -------- | ------------------------------------------ |
+| `r`      | Manually trigger a rescan                  |
+| `w`      | Launch web dashboard (without AI)          |
+| `W`      | Launch web dashboard with AI analysis      |
+| `f`      | Expand focused panel to fullscreen         |
+| `Escape` | Unfocus current panel                      |
+| `↑ / ↓`  | Scroll Health Panel results (when focused) |
+| `h`      | Focus Health panel                         |
+| `g`      | Focus Git panel                            |
+| `t`      | Focus Trend panel                          |
+| `q`      | Focus Quick Wins panel                     |
+| `a`      | Focus Activity panel                       |
+
+### Automatic Triggers
+
+- **Startup** — Initial scan runs immediately
+- **File watch** — Rescans when TypeScript, JavaScript, or JSON files change (debounced 2s)
+- **Auto-refresh** — Periodic rescan at the configured interval (default 5 minutes)
+- **Regression detection** — Activity panel flags category score decreases automatically
+
+## Architecture
+
+```
+src/
+├── index.ts              # Commander entry — parses flags, renders Ink <App>
+├── commands/
+│   └── web.ts            # HTTP server (Node built-in) for the dashboard
+└── components/
+    ├── App.tsx            # Root Ink component — manages phases & state
+    ├── Header.tsx         # ASCII art banner + project name
+    ├── ProgressList.tsx   # Animated check progress (pending → running → done)
+    ├── CheckResult.tsx    # Single check: name, status, score bar, issues
+    ├── ScoreBar.tsx       # Colored horizontal bar (green/yellow/red)
+    ├── Summary.tsx        # Overall score + issue counts
+    ├── QuickWins.tsx      # Top actionable fix suggestions
+    └── tui/
+        ├── TUIApp.tsx         # TUI root — layout, keyboard input, state
+        ├── HealthPanel.tsx        # Check results with status icons and score bars
+        ├── ScorePanel.tsx         # Overall score, issue counts, delta from last scan
+        ├── TrendPanel.tsx         # Sparkline charts for score history (last 10 scans)
+        ├── GitPanel.tsx           # Branch, ahead/behind, staged/modified file counts
+        ├── QuickWinsPanel.tsx     # Top 5 actionable fixes by severity
+        ├── ActivityPanel.tsx      # Timestamped event log
+        ├── HotkeyBar.tsx          # Fixed footer with keyboard shortcut reference
+        ├── PanelBorder.tsx        # Focused/unfocused border styling
+        └── hooks/
+            ├── useSickbayRunner.ts  # Manages check execution and scan state
+            ├── useFileWatcher.ts   # chokidar file watcher with debounce
+            ├── useGitStatus.ts     # Polls git status every 10 seconds
+            └── useTerminalSize.ts  # Tracks terminal dimensions for responsive layout
+```
+
+### UI Phases
+
+The `<App>` component cycles through phases:
+
+1. **`loading`** — Shows progress list with animated spinners while checks run
+2. **`results`** — Displays all check results + summary + quick wins
+3. **`opening-web`** — Starts HTTP server, opens browser, stays alive until Ctrl+C
+4. **`error`** — Shows error message and exits
+
+### `--web` flag flow
+
+When `--web` is passed:
+
+1. Scan completes normally
+2. `serveWeb(report)` starts an HTTP server on port 3030 (or next free port)
+3. Server serves `packages/web/dist/` as static files
+4. Server responds to `GET /sickbay-report.json` with the in-memory report
+5. `open` package opens the browser
+6. Process stays alive until Ctrl+C
+
+### `--json` flag flow
+
+Skips the Ink UI entirely, writes `JSON.stringify(report, null, 2)` to stdout, then exits.
+
+## Local Development
+
+```bash
+# Watch mode — rebuilds on file changes
+pnpm dev
+
+# Test against a project
+node dist/index.js --path ~/Desktop/sickbay-test-app
+node dist/index.js --path ~/Desktop/sickbay-test-app --web
+node dist/index.js --path ~/Desktop/sickbay-test-app --json
+```
+
+## Build
+
+```bash
+pnpm build   # tsup → dist/index.js + dist/web-*.js (code-split)
+pnpm clean   # rm -rf dist/
+```

package/dist/DiffApp-E2AQ3IOB.js

@@ -0,0 +1,172 @@
+import {
+  Header
+} from "./chunk-WS67R6X3.js";
+
+// src/components/DiffApp.tsx
+import React, { useState, useEffect } from "react";
+import { Box, Text, useApp } from "ink";
+import Spinner from "ink-spinner";
+
+// src/commands/diff.ts
+import { execFileSync } from "child_process";
+function loadBaseReport(projectPath, branch) {
+  try {
+    const output = execFileSync("git", ["show", `${branch}:.sickbay/last-report.json`], {
+      cwd: projectPath,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return JSON.parse(output);
+  } catch {
+    return null;
+  }
+}
+var STATUS_ORDER = {
+  regressed: 0,
+  improved: 1,
+  new: 2,
+  removed: 3,
+  unchanged: 4
+};
+function compareReports(current, base, branch) {
+  const baseMap = new Map(base.checks.map((c) => [c.id, c]));
+  const currentMap = new Map(current.checks.map((c) => [c.id, c]));
+  const checks = [];
+  for (const check of current.checks) {
+    const baseCheck = baseMap.get(check.id);
+    if (!baseCheck) {
+      checks.push({
+        id: check.id,
+        name: check.name,
+        category: check.category,
+        currentScore: check.score,
+        baseScore: 0,
+        delta: check.score,
+        status: "new"
+      });
+    } else {
+      const delta = check.score - baseCheck.score;
+      checks.push({
+        id: check.id,
+        name: check.name,
+        category: check.category,
+        currentScore: check.score,
+        baseScore: baseCheck.score,
+        delta,
+        status: delta > 0 ? "improved" : delta < 0 ? "regressed" : "unchanged"
+      });
+    }
+  }
+  for (const check of base.checks) {
+    if (!currentMap.has(check.id)) {
+      checks.push({
+        id: check.id,
+        name: check.name,
+        category: check.category,
+        currentScore: 0,
+        baseScore: check.score,
+        delta: -check.score,
+        status: "removed"
+      });
+    }
+  }
+  checks.sort((a, b) => STATUS_ORDER[a.status] - STATUS_ORDER[b.status]);
+  const summary = {
+    improved: checks.filter((c) => c.status === "improved").length,
+    regressed: checks.filter((c) => c.status === "regressed").length,
+    unchanged: checks.filter((c) => c.status === "unchanged").length,
+    newChecks: checks.filter((c) => c.status === "new").length,
+    removedChecks: checks.filter((c) => c.status === "removed").length
+  };
+  return {
+    branch,
+    currentScore: current.overallScore,
+    baseScore: base.overallScore,
+    scoreDelta: current.overallScore - base.overallScore,
+    checks,
+    summary
+  };
+}
+
+// src/components/DiffApp.tsx
+var STATUS_ICONS = {
+  improved: "\u2191",
+  regressed: "\u2193",
+  unchanged: "=",
+  new: "+",
+  removed: "\u2212"
+};
+var STATUS_COLORS = {
+  improved: "green",
+  regressed: "red",
+  unchanged: "gray",
+  new: "cyan",
+  removed: "yellow"
+};
+function formatDelta(delta) {
+  if (delta > 0) return `+${delta}`;
+  if (delta < 0) return `${delta}`;
+  return "0";
+}
+function DiffTable({ diff }) {
+  return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column" }, /* @__PURE__ */ React.createElement(Box, { marginTop: 1 }, /* @__PURE__ */ React.createElement(Text, { bold: true }, "Overall: "), /* @__PURE__ */ React.createElement(Text, { bold: true }, diff.baseScore), /* @__PURE__ */ React.createElement(Text, { dimColor: true }, " \u2192 "), /* @__PURE__ */ React.createElement(Text, { bold: true }, diff.currentScore), /* @__PURE__ */ React.createElement(Text, null, " "), /* @__PURE__ */ React.createElement(Text, { color: diff.scoreDelta > 0 ? "green" : diff.scoreDelta < 0 ? "red" : "gray", bold: true }, "(", formatDelta(diff.scoreDelta), ")")), /* @__PURE__ */ React.createElement(Box, { flexDirection: "column", marginTop: 1, marginLeft: 2 }, /* @__PURE__ */ React.createElement(Box, null, /* @__PURE__ */ React.createElement(Text, { bold: true }, "  Check".padEnd(30)), /* @__PURE__ */ React.createElement(Text, { bold: true }, "Current".padEnd(10)), /* @__PURE__ */ React.createElement(Text, { bold: true }, "Base".padEnd(10)), /* @__PURE__ */ React.createElement(Text, { bold: true }, "Delta")), /* @__PURE__ */ React.createElement(Text, { dimColor: true }, "\u2501".repeat(56)), diff.checks.map((check) => /* @__PURE__ */ React.createElement(Box, { key: check.id }, /* @__PURE__ */ React.createElement(Text, { color: STATUS_COLORS[check.status] }, STATUS_ICONS[check.status], " "), /* @__PURE__ */ React.createElement(Text, null, check.name.padEnd(28)), /* @__PURE__ */ React.createElement(Text, null, String(check.currentScore || "\u2014").padEnd(10)), /* @__PURE__ */ React.createElement(Text, null, String(check.baseScore || "\u2014").padEnd(10)), /* @__PURE__ */ React.createElement(Text, { color: STATUS_COLORS[check.status], bold: true }, check.status === "new" ? "new" : check.status === "removed" ? "removed" : formatDelta(check.delta))))), /* @__PURE__ */ React.createElement(Box, { marginTop: 1, marginLeft: 2 }, /* @__PURE__ */ React.createElement(Text, { dimColor: true }, diff.summary.improved > 0 && /* @__PURE__ */ React.createElement(Text, { color: "green" }, diff.summary.improved, " improved"), diff.summary.improved > 0 && diff.summary.regressed > 0 && /* @__PURE__ */ React.createElement(Text, null, ", "), diff.summary.regressed > 0 && /* @__PURE__ */ React.createElement(Text, { color: "red" }, diff.summary.regressed, " regressed"), (diff.summary.improved > 0 || diff.summary.regressed > 0) && diff.summary.unchanged > 0 && /* @__PURE__ */ React.createElement(Text, null, ", "), diff.summary.unchanged > 0 && /* @__PURE__ */ React.createElement(Text, null, diff.summary.unchanged, " unchanged"), diff.summary.newChecks > 0 && /* @__PURE__ */ React.createElement(Text, { color: "cyan" }, ", ", diff.summary.newChecks, " new"), diff.summary.removedChecks > 0 && /* @__PURE__ */ React.createElement(Text, { color: "yellow" }, ", ", diff.summary.removedChecks, " removed"))));
+}
+function DiffApp({ projectPath, branch, jsonOutput, checks, verbose }) {
+  const { exit } = useApp();
+  const [phase, setPhase] = useState("scanning");
+  const [diff, setDiff] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    (async () => {
+      try {
+        const { runSickbay } = await import("./dist-YIK3YE5B.js");
+        const currentReport = await runSickbay({
+          projectPath,
+          checks,
+          verbose
+        });
+        try {
+          const { saveEntry, saveLastReport } = await import("./history-XLNVZEDI.js");
+          saveEntry(currentReport);
+          saveLastReport(currentReport);
+        } catch {
+        }
+        setPhase("loading-base");
+        const baseReport = loadBaseReport(projectPath, branch);
+        if (!baseReport) {
+          setError(
+            `No saved report found on "${branch}". Run \`sickbay\` on that branch and commit .sickbay/last-report.json so it can be read via git.`
+          );
+          setPhase("error");
+          setTimeout(() => exit(), 100);
+          return;
+        }
+        const result = compareReports(currentReport, baseReport, branch);
+        setDiff(result);
+        setPhase("results");
+        if (jsonOutput) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        }
+        setTimeout(() => exit(), 100);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err));
+        setPhase("error");
+        setTimeout(() => exit(), 100);
+      }
+    })();
+  }, []);
+  if (phase === "scanning") {
+    return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column", padding: 1 }, /* @__PURE__ */ React.createElement(Header, null), /* @__PURE__ */ React.createElement(Text, null, /* @__PURE__ */ React.createElement(Text, { color: "green" }, /* @__PURE__ */ React.createElement(Spinner, { type: "dots" })), " ", "Scanning current branch..."));
+  }
+  if (phase === "loading-base") {
+    return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column", padding: 1 }, /* @__PURE__ */ React.createElement(Header, null), /* @__PURE__ */ React.createElement(Text, null, /* @__PURE__ */ React.createElement(Text, { color: "green" }, /* @__PURE__ */ React.createElement(Spinner, { type: "dots" })), " ", "Loading ", branch, " baseline..."));
+  }
+  if (phase === "error") {
+    return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column", padding: 1 }, /* @__PURE__ */ React.createElement(Header, null), /* @__PURE__ */ React.createElement(Text, { color: "red" }, "\u2717 ", error));
+  }
+  if (jsonOutput || !diff) return null;
+  return /* @__PURE__ */ React.createElement(Box, { flexDirection: "column", padding: 1 }, /* @__PURE__ */ React.createElement(Header, null), /* @__PURE__ */ React.createElement(Text, { bold: true }, "Branch Diff: current vs ", branch), /* @__PURE__ */ React.createElement(DiffTable, { diff }));
+}
+export {
+  DiffApp
+};