@whenlabs/when 0.9.1 → 0.9.3

package/README.md

@@ -4,6 +4,8 @@
 
 A single installable toolkit that brings six WhenLabs developer tools into your Claude Code / AI coding agent workflow. Once installed, all tools are available as MCP tools in every session — Claude uses them automatically when relevant.
 
+Five tools (stale, envalid, berth, aware, vow) have CLI scan modes and run on a schedule. Velocity is the sixth tool — it is always-on and embedded (SQLite-backed), so it does not have a CLI scan mode and does not appear in `doctor`/`watch`/`init`/`ci` output.
+
 ## Install
 
 ```bash
@@ -61,6 +63,8 @@ These tools are available to Claude in every session after install:
 | `vow_check` | Validate licenses against policy |
 | `vow_hook_install` | Install pre-commit license check hook |
 
+> This table shows a highlights subset. Run `when <tool> --help` for all available commands per tool.
+
 ## Multi-Editor Support
 
 Install MCP servers into other editors alongside Claude Code:
@@ -98,7 +102,7 @@ when ci              # Run checks for CI (exits 1 on issues)
 
 ### `when init`
 
-One command to onboard any project. Auto-detects your stack, runs all 5 tools in parallel, generates AI context files if missing, and shows a summary with next steps.
+One command to onboard any project. Auto-detects your stack, runs all 5 CLI tools in parallel, generates AI context files if missing, and shows a summary with next steps.
 
 ### `when doctor`
 
@@ -106,7 +110,7 @@ Runs all 5 CLI tools against the current project and displays a unified health r
 
 ### `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.
+Background daemon that runs all 5 CLI 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`
 

package/dist/chunk-2A2EZZF4.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+// src/utils/find-bin.ts
+import { resolve, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function findBin(name) {
+  const pkgRoot = resolve(__dirname, "../..");
+  const localBin = resolve(pkgRoot, "node_modules", ".bin", name);
+  if (existsSync(localBin)) return localBin;
+  const directCli = resolve(pkgRoot, "node_modules", "@whenlabs", name, "dist", "cli.js");
+  if (existsSync(directCli)) return directCli;
+  return name;
+}
+
+export {
+  findBin
+};

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  findBin
+} from "./chunk-2A2EZZF4.js";
 import {
   getStatusPath
 } from "./chunk-4ZVSCJCJ.js";
@@ -9,16 +12,6 @@ import { Command as Command5 } from "commander";
 // src/commands/delegate.ts
 import { Command } from "commander";
 import { spawn } from "child_process";
-import { resolve, dirname } from "path";
-import { existsSync } from "fs";
-import { fileURLToPath } from "url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-function findBin(name) {
-  const pkgRoot = resolve(__dirname, "..");
-  const localBin = resolve(pkgRoot, "node_modules", ".bin", name);
-  if (existsSync(localBin)) return localBin;
-  return name;
-}
 function createDelegateCommand(name, description, binName) {
   const cmd = new Command(name);
   cmd.description(description);
@@ -53,14 +46,14 @@ 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));
+import { resolve, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
 function findBin2(name) {
-  const pkgRoot = resolve2(__dirname2, "..", "..");
-  const localBin = resolve2(pkgRoot, "node_modules", ".bin", name);
-  if (existsSync2(localBin)) return localBin;
+  const pkgRoot = resolve(__dirname, "..", "..");
+  const localBin = resolve(pkgRoot, "node_modules", ".bin", name);
+  if (existsSync(localBin)) return localBin;
   return name;
 }
 function runTool(bin, args) {
@@ -303,10 +296,10 @@ function createDoctorCommand() {
 // src/commands/init.ts
 import { Command as Command3 } from "commander";
 import { spawn as spawn3 } from "child_process";
-import { resolve as resolve3, dirname as dirname3, basename } from "path";
-import { existsSync as existsSync3, readFileSync } from "fs";
-import { fileURLToPath as fileURLToPath3 } from "url";
-var __dirname3 = dirname3(fileURLToPath3(import.meta.url));
+import { resolve as resolve2, dirname as dirname2, basename } from "path";
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 var c2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -320,15 +313,15 @@ function colorize2(text, ...codes) {
   return codes.join("") + text + c2.reset;
 }
 function findBin3(name) {
-  const pkgRoot = resolve3(__dirname3, "..");
-  const localBin = resolve3(pkgRoot, "node_modules", ".bin", name);
-  if (existsSync3(localBin)) return localBin;
+  const pkgRoot = resolve2(__dirname2, "..");
+  const localBin = resolve2(pkgRoot, "node_modules", ".bin", name);
+  if (existsSync2(localBin)) return localBin;
   return name;
 }
 function detectProject(cwd) {
   let name = basename(cwd);
-  const pkgPath = resolve3(cwd, "package.json");
-  if (existsSync3(pkgPath)) {
+  const pkgPath = resolve2(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
     try {
       const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
       if (pkg.name) name = pkg.name;
@@ -349,7 +342,7 @@ function detectProject(cwd) {
   ];
   const stacks = [];
   for (const [file, stack] of stackFiles) {
-    if (existsSync3(resolve3(cwd, file)) && !stacks.includes(stack)) {
+    if (existsSync2(resolve2(cwd, file)) && !stacks.includes(stack)) {
       stacks.push(stack);
     }
   }
@@ -423,7 +416,7 @@ async function scanVow(cwd) {
   }
 }
 async function scanAware(cwd) {
-  const hasConfig = existsSync3(resolve3(cwd, ".aware.json"));
+  const hasConfig = existsSync2(resolve2(cwd, ".aware.json"));
   if (!hasConfig) {
     const { exitCode: exitCode2 } = await runTool2(findBin3("aware"), ["init"]);
     if (exitCode2 === 0) return { label: "AI context (aware)", status: "ok", detail: "Generated .aware.json and context files" };
@@ -488,7 +481,7 @@ function createInitCommand() {
     }
     console.log("");
     console.log(colorize2("  Next steps:", c2.bold));
-    const mcpInstalled = existsSync3(resolve3(process.env.HOME ?? "~", ".claude", "settings.json"));
+    const mcpInstalled = existsSync2(resolve2(process.env.HOME ?? "~", ".claude", "settings.json"));
     if (!mcpInstalled) {
       console.log(`    ${colorize2("\u2022", c2.cyan)} Run ${colorize2("when install", c2.bold)} to connect MCP tools to Claude Code`);
     }
@@ -549,7 +542,7 @@ function sleep(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.description("Run all 5 CLI tools on a schedule and write results to ~/.whenlabs/status.json (velocity is embedded and always-on \u2014 it does not participate in scheduled scans)");
   cmd.option("--once", "Run a single scan and exit");
   cmd.option("--interval <seconds>", "Override the default scan interval (seconds)", "60");
   cmd.action(async (options) => {
@@ -593,10 +586,15 @@ function createWatchCommand() {
 }
 
 // src/index.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve3, dirname as dirname3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+var __dirname3 = dirname3(fileURLToPath3(import.meta.url));
+var { version } = JSON.parse(readFileSync2(resolve3(__dirname3, "..", "package.json"), "utf8"));
 var program = new Command5();
-program.name("when").version("0.1.0").description("The WhenLabs developer toolkit \u2014 6 tools, one install");
+program.name("when").version(version).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-TFEGFWJ5.js");
+  const { install } = await import("./install-V24JHOA2.js");
   await install(options);
 });
 program.command("uninstall").description("Remove all WhenLabs tools").option("--cursor", "Remove MCP servers from Cursor").option("--vscode", "Remove MCP servers from VS Code").option("--windsurf", "Remove MCP servers from Windsurf").option("--all", "Remove MCP servers from all supported editors").action(async (options) => {

package/dist/install-V24JHOA2.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import {
+  ALL_EDITORS,
+  installForEditor,
+  registerMcpServer
+} from "./chunk-3PDLNC63.js";
+import {
+  injectBlock
+} from "./chunk-NYUYV3UL.js";
+
+// src/commands/install.ts
+import { join, resolve, dirname } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+
+// src/templates/claude-md-content.ts
+var CLAUDE_MD_CONTENT = `# WhenLabs Toolkit
+
+## Task Timing (velocity-mcp)
+
+Velocity tools are part of the unified \`whenlabs\` MCP server. Follow these rules for EVERY session:
+
+1. **Before starting any discrete coding task**, call \`velocity_start_task\` with:
+   - Appropriate \`category\` (scaffold, implement, refactor, debug, test, config, docs, deploy)
+   - Relevant \`tags\` (e.g. typescript, react, sqlite, api)
+   - Clear \`description\` of what you're about to do
+   - \`estimated_files\` if you know how many files you'll touch
+   - \`project\` set to the current project name (auto-detected from git remote or directory name)
+
+2. **After completing each task**, call \`velocity_end_task\` with:
+   - The \`task_id\` from the start call
+   - \`status\`: completed, failed, or abandoned
+   - \`actual_files\`: how many files were actually modified
+   - \`notes\`: any useful context about what happened
+
+3. **When creating a multi-step plan**, call \`velocity_estimate\` to provide the user with a time estimate before starting work.
+
+4. **If the user asks about speed or performance**, call \`velocity_stats\` to show aggregate data.
+
+### Guidelines
+- Every discrete unit of work should be tracked \u2014 don't batch multiple unrelated changes into one task
+- If a task is abandoned or fails, still call \`velocity_end_task\` with the appropriate status
+- Use consistent tags across sessions so the similarity matching can find comparable historical tasks
+- Keep descriptions concise but specific enough to be useful for future matching
+
+## WhenLabs MCP Tools (ALWAYS prefer these over shell commands)
+
+All six tools (including velocity) are available through the unified \`whenlabs\` MCP server. **ALWAYS use these MCP tools instead of running shell commands like lsof, grep, or manual checks.** These tools are purpose-built and give better results:
+
+| When to use | Call this tool | NOT this |
+|-------------|---------------|----------|
+| Check ports or port conflicts | \`berth_status\` or \`berth_check\` | \`lsof\`, \`netstat\`, \`ss\` |
+| Scan dependency licenses | \`vow_scan\` or \`vow_check\` | manual \`npm ls\`, \`license-checker\` |
+| Check if docs are stale | \`stale_scan\` | manual file comparison |
+| Validate .env files | \`envalid_validate\` or \`envalid_detect\` | manual .env inspection |
+| Generate AI context files | \`aware_init\` or \`aware_doctor\` | manual CLAUDE.md creation |
+
+### Tool Reference
+- \`berth_status\` \u2014 Show all active ports, Docker ports, and configured ports
+- \`berth_check\` \u2014 Scan a project directory for port conflicts
+- \`stale_scan\` \u2014 Detect documentation drift in the codebase
+- \`envalid_validate\` \u2014 Validate .env files against their schema
+- \`envalid_detect\` \u2014 Find undocumented env vars in codebase
+- \`aware_init\` \u2014 Auto-detect stack and generate AI context files
+- \`aware_doctor\` \u2014 Diagnose project health and config issues
+- \`vow_scan\` \u2014 Scan and summarize all dependency licenses
+- \`vow_check\` \u2014 Validate licenses against a policy file
+
+### Proactive Background Scans
+WhenLabs tools run automatically in the background on a schedule. The status line shows findings:
+- \`stale:N\` \u2014 N docs have drifted from code. Run \`stale_scan\` and fix the drift.
+- \`env:N\` \u2014 N .env issues found. Run \`envalid_validate\` and help the user fix them.
+- \`ports:N\` \u2014 N port conflicts. Run \`berth_status\` and suggest resolution.
+- \`lic:N?\` \u2014 N packages with unknown licenses. Run \`vow_scan\` for details.
+- \`aware:stale\` \u2014 AI context files are outdated. Run \`aware_init\` to regenerate.
+
+**When you see any of these in the status line, proactively tell the user and offer to fix the issue.** Do not wait for the user to ask.`;
+
+// src/commands/install.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname(__filename);
+var CLAUDE_MD_PATH = join(homedir(), ".claude", "CLAUDE.md");
+var SCRIPTS_DIR = join(homedir(), ".claude", "scripts");
+var STATUSLINE_PATH = join(SCRIPTS_DIR, "statusline.py");
+var SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+var OLD_START_MARKER = "<!-- velocity-mcp:start -->";
+var OLD_END_MARKER = "<!-- velocity-mcp:end -->";
+var STATUSLINE_SCRIPT = readFileSync(
+  resolve(__dirname, "..", "templates", "statusline.py"),
+  "utf-8"
+);
+function installStatusLine() {
+  try {
+    mkdirSync(SCRIPTS_DIR, { recursive: true });
+    writeFileSync(STATUSLINE_PATH, STATUSLINE_SCRIPT, "utf-8");
+    chmodSync(STATUSLINE_PATH, 493);
+    let settings = {};
+    if (existsSync(SETTINGS_PATH)) {
+      try {
+        settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+      } catch {
+        settings = {};
+      }
+    }
+    const statuslineCmd = `python3 ${STATUSLINE_PATH}`;
+    const currentCmd = settings.statusLine?.command;
+    if (currentCmd !== statuslineCmd) {
+      settings.statusLine = { type: "command", command: statuslineCmd };
+      writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    }
+    return { installed: true, message: "Status line installed (proactive background scans)" };
+  } catch (err) {
+    return { installed: false, message: `Status line install failed: ${err.message}` };
+  }
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasOldBlock(filePath) {
+  if (!existsSync(filePath)) return false;
+  const content = readFileSync(filePath, "utf-8");
+  return content.includes(OLD_START_MARKER) && content.includes(OLD_END_MARKER);
+}
+function removeOldBlock(filePath) {
+  if (!existsSync(filePath)) return;
+  let content = readFileSync(filePath, "utf-8");
+  const pattern = new RegExp(
+    `\\n?${escapeRegex(OLD_START_MARKER)}[\\s\\S]*?${escapeRegex(OLD_END_MARKER)}\\n?`,
+    "g"
+  );
+  content = content.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  writeFileSync(filePath, content, "utf-8");
+}
+async function install(options = {}) {
+  console.log("\n\u{1F527} WhenLabs toolkit installer\n");
+  const editorFlags = options.all ? ALL_EDITORS : [
+    options.cursor && "cursor",
+    options.vscode && "vscode",
+    options.windsurf && "windsurf"
+  ].filter(Boolean);
+  const claudeOnly = editorFlags.length === 0;
+  if (claudeOnly) {
+    const mcpResult = registerMcpServer();
+    console.log(mcpResult.success ? `  \u2713 ${mcpResult.message}` : `  \u2717 ${mcpResult.message}`);
+    injectBlock(CLAUDE_MD_PATH, CLAUDE_MD_CONTENT);
+    console.log(`  \u2713 CLAUDE.md instructions written to ${CLAUDE_MD_PATH}`);
+    const slResult = installStatusLine();
+    console.log(slResult.installed ? `  \u2713 ${slResult.message}` : `  \u2717 ${slResult.message}`);
+    try {
+      const cwd = process.cwd();
+      execFileSync("npx", ["--yes", "@whenlabs/aware", "init", "--force"], {
+        cwd,
+        stdio: "pipe",
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+        timeout: 3e4
+      });
+      execFileSync("npx", ["--yes", "@whenlabs/aware", "sync"], {
+        cwd,
+        stdio: "pipe",
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+        timeout: 3e4
+      });
+      console.log("  \u2713 AI context files generated and synced (aware init + sync)");
+    } catch {
+      console.log("  - Skipped aware init (run `when aware init` in a project directory)");
+    }
+    if (hasOldBlock(CLAUDE_MD_PATH)) {
+      removeOldBlock(CLAUDE_MD_PATH);
+      console.log("  \u2713 Removed legacy velocity-mcp markers (migrated to whenlabs block)");
+    }
+  } else {
+    for (const editor of editorFlags) {
+      const result = installForEditor(editor);
+      console.log(result.success ? `  \u2713 ${result.message}` : `  \u2717 ${result.message}`);
+    }
+  }
+  console.log("\nInstallation complete. Run `when status` to verify.\n");
+}
+export {
+  install
+};