@whenlabs/when 0.9.2 → 0.10.0

package/dist/install-33GE3HKA.js

@@ -0,0 +1,190 @@
+#!/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
+- \`berth_auto_resolve\` \u2014 Check for conflicts and auto-resolve them in one step
+- \`stale_scan\` \u2014 Detect documentation drift in the codebase
+- \`stale_auto_fix\` \u2014 Scan for drift and auto-fix high-confidence issues in one step
+- \`envalid_validate\` \u2014 Validate .env files against their schema
+- \`envalid_detect\` \u2014 Find undocumented env vars in codebase
+- \`envalid_auto_fix\` \u2014 Detect undocumented env vars and auto-generate schema entries
+- \`aware_init\` \u2014 Auto-detect stack and generate AI context files
+- \`aware_doctor\` \u2014 Diagnose project health and config issues
+- \`aware_auto_sync\` \u2014 Diagnose and auto-sync stale AI context files in one step
+- \`vow_scan\` \u2014 Scan and summarize all dependency licenses
+- \`vow_check\` \u2014 Validate licenses against a policy file
+
+### Cross-tool Intelligence
+Tools provide follow-up suggestions when they detect issues relevant to other tools. When you see a "Tip:" in tool output, act on the suggestion \u2014 it means another tool can help.
+
+### 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
+};