@whenlabs/when 0.8.1 → 0.9.0

package/README.md

@@ -16,10 +16,9 @@ This is a one-time setup. After install, all six tools are available in every pr
 
 Running `npx @whenlabs/when install` will:
 
-1. Register **two MCP servers** in your Claude Code configuration:
-   - `velocity-mcp` — task timing and estimation tools
-   - `whenlabs` — stale, envalid, berth, aware, and vow tools
+1. Register a **single MCP server** (`whenlabs`) in your Claude Code configuration — all six tools, including velocity, are served from one server
 2. Inject **CLAUDE.md instructions** so Claude knows when to use each tool automatically — and prefers them over shell commands
+3. Clean up any legacy `velocity-mcp` registrations (velocity is now bundled)
 
 Once connected, Claude can call any tool directly without you asking. For example, after a refactor Claude might run `stale_scan` to check for doc drift, or before a release it might run `vow_check` to validate licenses.
 
@@ -46,17 +45,21 @@ These tools are available to Claude in every session after install:
 | `velocity_start_task` | Start timing a coding task |
 | `velocity_end_task` | End timing and record results |
 | `velocity_estimate` | Estimate time for a planned task |
-| `velocity_stats` | Show aggregate performance stats |
+| `velocity_stats` | Show aggregate performance stats with insights |
 | `velocity_history` | Show task history |
 | `stale_scan` | Detect documentation drift |
+| `stale_fix` | Auto-fix documentation drift (wrong paths, dead links, phantom env vars) |
 | `envalid_validate` | Validate .env files against schemas |
 | `envalid_detect` | Find undocumented env vars in codebase |
+| `envalid_generate_schema` | Generate .env.schema from code analysis |
 | `berth_status` | Show active ports and conflicts |
 | `berth_check` | Scan project for port conflicts |
+| `berth_resolve` | Auto-resolve port conflicts (kill or reassign) |
 | `aware_init` | Auto-detect stack, generate AI context files |
 | `aware_doctor` | Diagnose project health and config issues |
 | `vow_scan` | Scan and summarize dependency licenses |
 | `vow_check` | Validate licenses against policy |
+| `vow_hook_install` | Install pre-commit license check hook |
 
 ## Multi-Editor Support
 
@@ -78,12 +81,18 @@ You can also run tools directly from the command line:
 ```bash
 when init            # Onboard a project — detect stack, run all tools
 when stale scan
+when stale fix       # Auto-fix documentation drift
 when envalid validate
+when envalid detect --generate  # Generate schema from code
 when berth status
+when berth resolve   # Auto-resolve port conflicts
 when aware init
 when vow scan
+when vow hook install  # Install pre-commit license hook
 when status          # Show installation status
 when doctor          # Run all tools, show unified health report
+when doctor --watch  # Continuous monitoring dashboard
+when watch           # Background daemon for status line
 when ci              # Run checks for CI (exits 1 on issues)
 ```
 
@@ -93,7 +102,11 @@ One command to onboard any project. Auto-detects your stack, runs all 5 tools in
 
 ### `when doctor`
 
-Runs all 5 CLI tools against the current project and displays a unified health report card. Supports `--json` for machine-readable output.
+Runs all 5 CLI tools against the current project and displays a unified health report card. Supports `--json` for machine-readable output and `--watch` for continuous monitoring with a live dashboard.
+
+### `when watch`
+
+Background daemon that runs all 5 tools on intervals and writes results to `~/.whenlabs/status.json`. Powers the Claude Code status line integration. Use `--once` for a single scan or `--interval <seconds>` to customize the schedule.
 
 ### `when ci`
 
@@ -118,7 +131,7 @@ when ci --json       # Machine-readable JSON output
 npx @whenlabs/when uninstall
 ```
 
-Removes both MCP servers and cleans up CLAUDE.md instructions.
+Removes the MCP server and cleans up CLAUDE.md instructions.
 
 ## License
 

package/dist/chunk-4ZVSCJCJ.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// src/utils/status-provider.ts
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync, statSync } from "fs";
+var STATUS_PATH = join(homedir(), ".whenlabs", "status.json");
+function getStatusPath() {
+  return STATUS_PATH;
+}
+function readStatus() {
+  if (!existsSync(STATUS_PATH)) return null;
+  try {
+    const raw = readFileSync(STATUS_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function formatStatusLine() {
+  const data = readStatus();
+  if (!data) return null;
+  const tools = data.tools;
+  const parts = [];
+  for (const [key, info] of Object.entries(tools)) {
+    const label = key === "envalid" ? "env" : key === "vow" ? "lic" : key;
+    if (info.status === "ok") {
+      parts.push(`\u2713${label}`);
+    } else if (info.status === "issues") {
+      parts.push(`\u2717${label}:${info.count}`);
+    } else {
+      parts.push(`!${label}`);
+    }
+  }
+  return parts.join(" ");
+}
+function isStale(maxAgeMs = 120 * 60 * 1e3) {
+  if (!existsSync(STATUS_PATH)) return true;
+  try {
+    const stat = statSync(STATUS_PATH);
+    return Date.now() - stat.mtimeMs > maxAgeMs;
+  } catch {
+    return true;
+  }
+}
+
+export {
+  getStatusPath,
+  readStatus,
+  formatStatusLine,
+  isStale
+};

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import {
+  getStatusPath
+} from "./chunk-4ZVSCJCJ.js";
 
 // src/index.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/commands/delegate.ts
 import { Command } from "commander";
@@ -47,25 +50,15 @@ function createDelegateCommand(name, description, binName) {
 
 // src/commands/doctor.ts
 import { Command as Command2 } from "commander";
+
+// src/utils/tool-runner.ts
 import { spawn as spawn2 } from "child_process";
 import { resolve as resolve2, dirname as dirname2 } from "path";
 import { existsSync as existsSync2 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-var c = {
-  reset: "\x1B[0m",
-  bold: "\x1B[1m",
-  green: "\x1B[32m",
-  yellow: "\x1B[33m",
-  red: "\x1B[31m",
-  cyan: "\x1B[36m",
-  dim: "\x1B[2m"
-};
-function colorize(text, ...codes) {
-  return codes.join("") + text + c.reset;
-}
 function findBin2(name) {
-  const pkgRoot = resolve2(__dirname2, "..");
+  const pkgRoot = resolve2(__dirname2, "..", "..");
   const localBin = resolve2(pkgRoot, "node_modules", ".bin", name);
   if (existsSync2(localBin)) return localBin;
   return name;
@@ -215,6 +208,29 @@ async function checkAware() {
     exitCode
   };
 }
+async function runAllChecks(cwd) {
+  return Promise.all([
+    checkStale(cwd),
+    checkEnvalid(cwd),
+    checkBerth(cwd),
+    checkVow(cwd),
+    checkAware()
+  ]);
+}
+
+// src/commands/doctor.ts
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m"
+};
+function colorize(text, ...codes) {
+  return codes.join("") + text + c.reset;
+}
 function statusIcon(result) {
   switch (result.status) {
     case "ok":
@@ -257,13 +273,7 @@ function createDoctorCommand() {
     if (!options.json) {
       process.stdout.write(colorize("  Running health checks\u2026", c.dim) + "\n");
     }
-    const results = await Promise.all([
-      checkStale(cwd),
-      checkEnvalid(cwd),
-      checkBerth(cwd),
-      checkVow(cwd),
-      checkAware()
-    ]);
+    const results = await runAllChecks(cwd);
     const hasIssues = results.some((r) => r.status === "issues" || r.status === "error");
     if (options.json) {
       const output = {
@@ -491,8 +501,99 @@ function createInitCommand() {
   return cmd;
 }
 
+// src/commands/watch.ts
+import { Command as Command4 } from "commander";
+import { join } from "path";
+import { homedir } from "os";
+import { mkdirSync, writeFileSync } from "fs";
+var STATUS_DIR = join(homedir(), ".whenlabs");
+function toolResultToStatus(r) {
+  const count = r.issues + r.warnings;
+  if (r.status === "error") {
+    return { status: "error", count, detail: r.detail };
+  }
+  if (r.status === "issues") {
+    return { status: "issues", count, detail: r.detail };
+  }
+  return { status: "ok", count: 0, detail: r.detail };
+}
+function buildSummary(results) {
+  const map = {};
+  for (const r of results) map[r.name] = r;
+  const stalePart = `stale:${map["stale"]?.issues ?? 0}`;
+  const envPart = `env:${(map["envalid"]?.issues ?? 0) + (map["envalid"]?.warnings ?? 0)}`;
+  const portsPart = `ports:${map["berth"]?.issues ?? 0}`;
+  const licPart = `lic:${(map["vow"]?.issues ?? 0) + (map["vow"]?.warnings ?? 0)}`;
+  const awarePart = `aware:${map["aware"]?.status === "ok" || map["aware"]?.status === "skipped" ? "ok" : "stale"}`;
+  return `${stalePart} ${envPart} ${portsPart} ${licPart} ${awarePart}`;
+}
+function writeStatus(results) {
+  mkdirSync(STATUS_DIR, { recursive: true });
+  const toolsMap = {};
+  for (const r of results) toolsMap[r.name] = r;
+  const status = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    tools: {
+      stale: toolResultToStatus(toolsMap["stale"]),
+      envalid: toolResultToStatus(toolsMap["envalid"]),
+      berth: toolResultToStatus(toolsMap["berth"]),
+      vow: toolResultToStatus(toolsMap["vow"]),
+      aware: toolResultToStatus(toolsMap["aware"])
+    },
+    summary: buildSummary(results)
+  };
+  writeFileSync(getStatusPath(), JSON.stringify(status, null, 2) + "\n");
+}
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+function createWatchCommand() {
+  const cmd = new Command4("watch");
+  cmd.description("Run all 5 WhenLabs tools on a schedule and write results to ~/.whenlabs/status.json");
+  cmd.option("--once", "Run a single scan and exit");
+  cmd.option("--interval <seconds>", "Override the default scan interval (seconds)", "60");
+  cmd.action(async (options) => {
+    const cwd = process.cwd();
+    const intervalSec = Math.max(10, parseInt(options.interval ?? "60", 10));
+    let stopped = false;
+    const shutdown = () => {
+      stopped = true;
+      process.stderr.write("\nwatch: shutting down gracefully\n");
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    const runScan = async () => {
+      const start = Date.now();
+      process.stderr.write(`watch: scanning... `);
+      const results = await runAllChecks(cwd);
+      writeStatus(results);
+      const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+      const summary = buildSummary(results);
+      process.stderr.write(`done in ${elapsed}s  [${summary}]
+`);
+      const hasIssues = results.some((r) => r.status === "issues" || r.status === "error");
+      return hasIssues;
+    };
+    if (options.once) {
+      const hasIssues = await runScan();
+      process.exit(hasIssues ? 1 : 0);
+      return;
+    }
+    process.stderr.write(`watch: started (interval=${intervalSec}s, status=${getStatusPath()})
+`);
+    while (!stopped) {
+      await runScan();
+      for (let i = 0; i < intervalSec && !stopped; i++) {
+        await sleep(1e3);
+      }
+    }
+  });
+  return cmd;
+}
+
 // src/index.ts
-var program = new Command4();
+var program = new Command5();
 program.name("when").version("0.1.0").description("The WhenLabs developer toolkit \u2014 6 tools, one install");
 program.command("install").description("Install all WhenLabs tools globally (MCP server + CLAUDE.md instructions)").option("--cursor", "Install MCP servers into Cursor (~/.cursor/mcp.json)").option("--vscode", "Install MCP servers into VS Code (settings.json)").option("--windsurf", "Install MCP servers into Windsurf (~/.codeium/windsurf/mcp_config.json)").option("--all", "Install MCP servers into all supported editors").action(async (options) => {
   const { install } = await import("./install-HPF26YW2.js");
@@ -503,7 +604,7 @@ program.command("uninstall").description("Remove all WhenLabs tools").option("--
   await uninstall(options);
 });
 program.command("status").description("Show installation status and velocity stats").action(async () => {
-  const { status } = await import("./status-LOZGVOA3.js");
+  const { status } = await import("./status-QWAHXHNA.js");
   await status();
 });
 program.command("ci").description("Run stale, envalid, and vow checks \u2014 exits 1 if any tool finds issues").option("--ci", "Output GitHub Actions annotations (::error file=X::message)").option("--json", "Machine-readable JSON output").action(async (options) => {
@@ -512,6 +613,7 @@ program.command("ci").description("Run stale, envalid, and vow checks \u2014 exi
 });
 program.addCommand(createInitCommand());
 program.addCommand(createDoctorCommand());
+program.addCommand(createWatchCommand());
 program.addCommand(createDelegateCommand("stale", "Detect documentation drift in your codebase"));
 program.addCommand(createDelegateCommand("envalid", "Validate .env files against a type-safe schema"));
 program.addCommand(createDelegateCommand("berth", "Detect and resolve port conflicts"));

package/dist/mcp.js

@@ -100,7 +100,7 @@ Note: Conflicts found in project "${projectName}".`);
 }
 var server = new McpServer({
   name: "whenlabs",
-  version: "0.2.0"
+  version: "0.3.0"
 });
 var velocityDb = initDb();
 var velocityQueries = new TaskQueries(velocityDb);
@@ -137,6 +137,25 @@ server.tool(
     return { content: [{ type: "text", text: output + extras.join("") }] };
   }
 );
+server.tool(
+  "stale_fix",
+  "Auto-fix documentation drift \u2014 generate fixes for wrong file paths, dead links, phantom env vars, outdated scripts",
+  {
+    path: z.string().optional().describe("Project directory to scan (defaults to cwd)"),
+    format: z.enum(["terminal", "diff"]).optional().describe("Output format (default: terminal)"),
+    apply: z.coerce.boolean().optional().describe("Apply high-confidence fixes directly"),
+    dryRun: z.coerce.boolean().optional().describe("Show what --apply would do without writing")
+  },
+  async ({ path, format, apply, dryRun }) => {
+    const args = ["fix"];
+    if (format) args.push("--format", format);
+    if (apply) args.push("--apply");
+    if (dryRun) args.push("--dry-run");
+    const result = await runCli("stale", args, path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "stale_init",
   "Generate a .stale.yml config file for customizing documentation drift detection",
@@ -263,6 +282,21 @@ server.tool(
     return { content: [{ type: "text", text: output }] };
   }
 );
+server.tool(
+  "envalid_generate_schema",
+  "Generate .env.schema from code analysis \u2014 infer types, required-ness, and sensitivity from usage patterns",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    output: z.string().optional().describe("Output file path (default: .env.schema)")
+  },
+  async ({ path, output }) => {
+    const args = ["detect", "--generate"];
+    if (output) args.push("-o", output);
+    const result = await runCli("envalid", args, path);
+    const outputText = formatOutput(result);
+    return { content: [{ type: "text", text: outputText }] };
+  }
+);
 server.tool(
   "envalid_hook_status",
   "Check if the envalid pre-commit git hook is installed",
@@ -379,6 +413,25 @@ server.tool(
     return { content: [{ type: "text", text: output }] };
   }
 );
+server.tool(
+  "berth_resolve",
+  "Auto-resolve port conflicts \u2014 detect conflicts and fix via kill or reassign strategy",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    strategy: z.enum(["kill", "reassign", "auto"]).optional().describe("Resolution strategy (default: auto)"),
+    kill: z.coerce.boolean().optional().describe("Allow killing processes (required for kill/auto strategies)"),
+    dryRun: z.coerce.boolean().optional().describe("Show what would be done without making changes")
+  },
+  async ({ path, strategy, kill, dryRun }) => {
+    const args = ["resolve"];
+    if (strategy) args.push("--strategy", strategy);
+    if (kill) args.push("--kill");
+    if (dryRun) args.push("--dry-run");
+    const result = await runCli("berth", args, path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "berth_predict",
   "Predict port conflicts from project config files before starting \u2014 dry-run conflict check",
@@ -427,9 +480,14 @@ server.tool(
 server.tool(
   "aware_diff",
   "Show project changes since last sync \u2014 see what drifted in your codebase",
-  { path: z.string().optional().describe("Project directory (defaults to cwd)") },
-  async ({ path }) => {
-    const result = await runCli("aware", ["diff"], path);
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    exitCode: z.coerce.boolean().optional().describe("Return exit code 1 if changes detected (useful for CI)")
+  },
+  async ({ path, exitCode }) => {
+    const args = ["diff"];
+    if (exitCode) args.push("--exit-code");
+    const result = await runCli("aware", args, path);
     const output = formatOutput(result);
     return { content: [{ type: "text", text: output }] };
   }
@@ -579,6 +637,42 @@ server.tool(
     return { content: [{ type: "text", text: outputText }] };
   }
 );
+server.tool(
+  "vow_hook_install",
+  "Install a pre-commit git hook that checks dependency licenses before each commit",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "install"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+server.tool(
+  "vow_hook_uninstall",
+  "Remove the vow pre-commit license check hook",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "uninstall"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+server.tool(
+  "vow_hook_status",
+  "Check if the vow pre-commit license check hook is installed",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "status"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "vow_attribution",
   "Generate THIRD_PARTY_LICENSES.md \u2014 list all dependencies with their licenses for compliance",

package/dist/{status-LOZGVOA3.js → status-QWAHXHNA.js}

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import {
+  formatStatusLine,
+  isStale,
+  readStatus
+} from "./chunk-4ZVSCJCJ.js";
 import {
   hasBlock
 } from "./chunk-NYUYV3UL.js";
@@ -36,6 +41,16 @@ async function status() {
     `  CLAUDE.md instructions:    ${claudeMdInstalled ? "\u2713 installed" : "\u2717 not installed"}`
   );
   console.log(`  CLAUDE.md path:            ${CLAUDE_MD_PATH}`);
+  const watchData = readStatus();
+  if (watchData) {
+    const line = formatStatusLine();
+    const stale = isStale();
+    const age = stale ? " (stale)" : "";
+    console.log(`
+  Watch results${age}:        ${line}`);
+    console.log(`  Last scan:               ${watchData.timestamp}`);
+    console.log(`  Summary:                 ${watchData.summary}`);
+  }
   const allGood = mcpRegistered && claudeMdInstalled;
   if (allGood) {
     console.log("\n  Everything is set up. Run `when --help` to see available tools.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whenlabs/when",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "The WhenLabs developer toolkit — 6 tools, one install",
   "type": "module",
   "main": "dist/index.js",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@whenlabs/aware": "^0.1.2",
-    "@whenlabs/berth": "^0.1.0",
-    "@whenlabs/envalid": "^0.1.2",
-    "@whenlabs/stale": "^0.1.0",
-    "@whenlabs/velocity-mcp": "^0.1.2",
-    "@whenlabs/vow": "^0.1.3",
+    "@whenlabs/aware": "^0.1.3",
+    "@whenlabs/berth": "^0.1.3",
+    "@whenlabs/envalid": "^0.1.3",
+    "@whenlabs/stale": "^0.1.3",
+    "@whenlabs/velocity-mcp": "^0.1.3",
+    "@whenlabs/vow": "^0.1.4",
     "commander": "^12.0.0",
     "zod": "^4.3.6"
   },