@massu/core 1.2.1 → 1.4.0-soak.0

package/src/hooks/session-start.ts

@@ -16,6 +16,7 @@ import { parse as parseYaml } from 'yaml';
 import type Database from 'better-sqlite3';
 import { runDetection } from '../detect/index.ts';
 import { computeFingerprint } from '../detect/drift.ts';
+import { isPidAlive } from '../lib/pidLiveness.ts';
 
 interface HookInput {
   session_id: string;
@@ -68,9 +69,14 @@ async function main(): Promise<void> {
       }
 
       // P5-001: drift banner (runs after memory context, independent of it).
+      // Plan 3a Phase 6: when a live watcher daemon exists, the drift banner
+      // is suppressed in favor of a compact watcher banner.
       const driftBanner = await buildDriftBanner();
       if (driftBanner) {
         process.stdout.write(driftBanner);
+      } else {
+        const watcherBanner = buildWatcherBanner();
+        if (watcherBanner) process.stdout.write(watcherBanner);
       }
     } finally {
       db.close();
@@ -261,6 +267,15 @@ function readStdin(): Promise<string> {
  */
 async function buildDriftBanner(): Promise<string> {
   try {
+    // Plan #2 P4-004: explicit opt-out for users in deliberate mid-migration windows.
+    // Stays at the top so MASSU_DRIFT_QUIET=1 remains the strongest signal
+    // (iter-1 G8: env-var override beats watcher-state suppression).
+    if (process.env.MASSU_DRIFT_QUIET === '1') return '';
+
+    // Plan 3a Phase 6: if a live watcher daemon refreshed within the last 24h,
+    // suppress this banner — the watcher already keeps the config current.
+    if (watcherIsLiveAndFresh()) return '';
+
     const configPath = resolve(process.cwd(), 'massu.config.yaml');
     if (!existsSync(configPath)) return '';
     const content = readFileSync(configPath, 'utf-8');
@@ -269,7 +284,10 @@ async function buildDriftBanner(): Promise<string> {
     const det = parsed.detection as Record<string, unknown> | undefined;
     const storedFp = typeof det?.fingerprint === 'string' ? (det.fingerprint as string) : null;
     if (!storedFp) return '';
-    const detection = await runDetection(process.cwd());
+    // Plan #2 P4-006: skip the codebase introspector pass — the drift banner
+    // only needs the fingerprint, not the introspected detail. Saves up to 2s
+    // wall-clock from the hook's 5-second budget.
+    const detection = await runDetection(process.cwd(), undefined, { skipIntrospect: true });
     const currentFp = computeFingerprint(detection);
     if (currentFp === storedFp) return '';
     return (
@@ -277,6 +295,9 @@ async function buildDriftBanner(): Promise<string> {
       'Detected stack has changed since last config refresh.\n' +
       `Fingerprint:  ${storedFp.slice(0, 16)}  ->  ${currentFp.slice(0, 16)}\n` +
       'Run: npx massu config refresh\n' +
+      '(this will update massu.config.yaml AND any commands that need\n' +
+      ' re-templating for your new stack)\n' +
+      'Tip: set MASSU_DRIFT_QUIET=1 to suppress this banner during mid-migration.\n' +
       '=== END ===\n'
     );
   } catch (_e) {
@@ -306,8 +327,11 @@ function loadCorrectionsPreventionRules(): string[] {
     const cwd = process.cwd();
     const config = getConfig();
     const claudeDirName = config.conventions?.claudeDirName ?? '.claude';
-    // Convert cwd to Claude's directory format: /Users/x/project -> -Users-x-project
-    const projectDirName = cwd.replace(/\//g, '-').replace(/^-/, '');
+    // Convert cwd to Claude's directory format: /Users/x/project -> -Users-x-project.
+    // Match both forward slashes (POSIX) and backslashes (Windows) so the lookup
+    // works cross-platform — without this, Windows users silently miss prevention
+    // rules because their projectDirName never resolves.
+    const projectDirName = cwd.replace(/[/\\]/g, '-').replace(/^-/, '');
     const correctionsPath = join(homeDir, claudeDirName, 'projects', projectDirName, 'memory', 'corrections.md');
 
     if (!existsSync(correctionsPath)) return [];
@@ -341,4 +365,71 @@ function loadCorrectionsPreventionRules(): string[] {
   }
 }
 
+// ============================================================
+// Plan 3a Phase 6: watcher-aware banner support
+// ============================================================
+
+interface WatchStateShape {
+  schema_version?: number;
+  daemonPid?: number | null;
+  lastRefreshAt?: string | null;
+  startedAt?: string | null;
+}
+
+function readWatchStateRaw(cwd: string): WatchStateShape | null {
+  try {
+    const path = resolve(cwd, '.massu', 'watch-state.json');
+    if (!existsSync(path)) return null;
+    const obj = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!obj || typeof obj !== 'object') return null;
+    return obj as WatchStateShape;
+  } catch {
+    return null;
+  }
+}
+
+function watcherIsLiveAndFresh(): boolean {
+  // MASSU_DRIFT_QUIET takes precedence (caller already short-circuited).
+  // Fresh = last refresh within 24h AND daemonPid is alive.
+  const state = readWatchStateRaw(process.cwd());
+  if (!state) return false;
+  if (typeof state.daemonPid !== 'number' || state.daemonPid <= 0) return false;
+  if (!isPidAlive(state.daemonPid)) return false;
+  if (typeof state.lastRefreshAt !== 'string') return false;
+  const last = Date.parse(state.lastRefreshAt);
+  if (!Number.isFinite(last)) return false;
+  const ageMs = Date.now() - last;
+  return ageMs >= 0 && ageMs < 24 * 60 * 60 * 1000;
+}
+
+function buildWatcherBanner(): string {
+  // P4-004 ordering: MASSU_DRIFT_QUIET wins everywhere.
+  if (process.env.MASSU_DRIFT_QUIET === '1') return '';
+  const state = readWatchStateRaw(process.cwd());
+  if (!state) return '';
+  if (typeof state.daemonPid !== 'number' || state.daemonPid <= 0) return '';
+  if (!isPidAlive(state.daemonPid)) return '';
+  if (typeof state.lastRefreshAt !== 'string') return '';
+  const last = Date.parse(state.lastRefreshAt);
+  if (!Number.isFinite(last)) return '';
+  const ageMs = Date.now() - last;
+  if (ageMs < 0 || ageMs >= 24 * 60 * 60 * 1000) return '';
+
+  const ageStr = formatAge(ageMs);
+  return (
+    '=== Massu Watcher ===\n' +
+    `[massu] watcher running, last refresh: ${ageStr} ago (pid ${state.daemonPid})\n` +
+    '=== END ===\n'
+  );
+}
+
+function formatAge(ms: number): string {
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.round(min / 60);
+  return `${hr}h`;
+}
+
 main();

package/src/lib/gitToplevel.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Resolve the git repository root for a given working directory, falling
+ * back to the cwd itself when not inside a git repo.
+ *
+ * Used by `massu watch` and `massu refresh-log` so the watcher root and the
+ * refresh-log path always anchor on the same toplevel rather than wherever
+ * the user happened to invoke the CLI from.
+ */
+
+import { spawnSync } from 'child_process';
+
+export function gitToplevel(cwd: string): string {
+  const res = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd,
+    encoding: 'utf-8',
+  });
+  if (res.status === 0 && res.stdout) return res.stdout.trim();
+  return cwd;
+}

package/src/lib/installLock.ts

@@ -0,0 +1,179 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Synchronous file lock around installAll() for cross-process safety.
+ *
+ * Plan 3a Phase 6: installAll() may now be invoked from BOTH the manual
+ * `runConfigRefresh` path AND the watcher auto-trigger. Without
+ * serialization, two concurrent callers can race on `.claude/commands/`
+ * file writes. proper-lockfile gives us atomic mkdir-based locks that
+ * work cross-platform; we wrap it to:
+ *
+ *   1. mkdirSync the lock dir (fresh repos may not have `.massu/`)
+ *   2. surface ELOCKED (POSIX) and EBUSY (Windows) as the same error
+ *   3. keep installAll() synchronous (lockSync, not lock)
+ *
+ * Plan §190 retry behavior: "second caller blocks up to 30s, then bails".
+ * proper-lockfile's `lockSync` REJECTS `retries>0` (see node_modules/
+ * proper-lockfile/lib/adapter.js: `Cannot use retries with the sync api`).
+ * We implement the retry-block manually via a `lockfile.checkSync` /
+ * `lockSync` loop with a busy-wait sleep.
+ *
+ * iter-3 (third pass, G3-iter3-1+2): align error message with plan §243
+ * format `"installAll already running (PID=X) — try again in <N>s"` AND
+ * add the manual retry-block loop.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import * as lockfile from 'proper-lockfile';
+
+export interface InstallLockOpts {
+  /** Default 30s — proper-lockfile considers a lock stale after this elapses. */
+  staleMs?: number;
+  /**
+   * How long the manual retry loop should block waiting for the holder to
+   * release before bailing with `InstallLockBusyError`. Default 30s per
+   * plan §190 ("second caller blocks up to 30s, then bails").
+   * Pass `0` to bail immediately (used in tests).
+   */
+  blockMs?: number;
+  /** Sleep granularity inside the retry loop. Default 100ms. */
+  pollIntervalMs?: number;
+  /**
+   * Backwards-compat: legacy callers pass `retries: 0` to mean "do not
+   * block". When set to a positive integer, used by tests that want to
+   * exercise a specific retry count instead of the default time-based loop.
+   */
+  retries?: number;
+  /** Override clock (test seam). */
+  now?: () => number;
+  /** Override sleep (test seam). Defaults to a busy-wait spinloop. */
+  sleep?: (ms: number) => void;
+}
+
+export class InstallLockBusyError extends Error {
+  constructor(
+    public lockPath: string,
+    public holderPid: number | null,
+    public retryAfterSeconds: number,
+    public causeCode?: string,
+  ) {
+    const pidPart = holderPid != null ? `(PID=${holderPid})` : '(PID=unknown)';
+    super(`installAll already running ${pidPart} — try again in ${retryAfterSeconds}s`);
+    this.name = 'InstallLockBusyError';
+  }
+}
+
+/**
+ * Best-effort: read the PID of the current lock holder. proper-lockfile
+ * stores the lock as a directory at `<lockPath>` containing nothing PID-
+ * identifying, so we look at our own sidecar `<lockPath>.pid` file (written
+ * by the lock acquirer below). On any read error we return null so the
+ * error message degrades gracefully to `(PID=unknown)`.
+ */
+function readHolderPid(lockPath: string): number | null {
+  try {
+    const raw = readFileSync(`${lockPath}.pid`, 'utf-8').trim();
+    const pid = Number.parseInt(raw, 10);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+function busyWaitSync(ms: number): void {
+  const end = Date.now() + ms;
+  // Atomics.wait against a SharedArrayBuffer is the cleanest portable sync
+  // sleep; fall back to a tight loop if SharedArrayBuffer is unavailable
+  // (older runtimes / sandboxed envs).
+  if (typeof SharedArrayBuffer !== 'undefined' && typeof Atomics !== 'undefined') {
+    const sab = new SharedArrayBuffer(4);
+    const view = new Int32Array(sab);
+    Atomics.wait(view, 0, 0, ms);
+    return;
+  }
+  while (Date.now() < end) {
+    // Spin — this should never run on modern Node, kept as belt-and-suspenders.
+  }
+}
+
+/**
+ * Acquire the lock, run `fn`, release on every exit path.
+ * Synchronous all the way through so installAll() keeps its sync signature.
+ */
+export function withInstallLock<T>(projectRoot: string, fn: () => T, opts: InstallLockOpts = {}): T {
+  const lockPath = resolve(projectRoot, '.massu', 'installAll.lock');
+  // iter-3 G3-A11: ensure parent dir exists (fresh repo case).
+  mkdirSync(dirname(lockPath), { recursive: true });
+
+  const staleMs = opts.staleMs ?? 30_000;
+  // `retries: 0` legacy path = bail immediately, no wait.
+  // Otherwise default to plan §190's 30s block.
+  const blockMs = opts.retries === 0
+    ? 0
+    : (opts.blockMs ?? 30_000);
+  const pollIntervalMs = opts.pollIntervalMs ?? 100;
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? busyWaitSync;
+
+  let release: (() => void) | null = null;
+  const deadline = now() + blockMs;
+  let lastErr: NodeJS.ErrnoException | null = null;
+
+  // Manual retry loop. proper-lockfile.lockSync forbids retries>0, so we
+  // wrap it ourselves: try → on ELOCKED/EBUSY, sleep → try again until
+  // deadline. This satisfies plan §190 "second caller blocks up to 30s".
+  for (;;) {
+    try {
+      release = lockfile.lockSync(lockPath, {
+        stale: staleMs,
+        retries: 0,
+        realpath: false,
+      });
+      // Persist our PID alongside the lock so the next contender can include
+      // it in the user-friendly error per plan §243 format.
+      try {
+        writeFileSync(`${lockPath}.pid`, String(process.pid), 'utf-8');
+      } catch {
+        // best-effort
+      }
+      break;
+    } catch (err) {
+      lastErr = err as NodeJS.ErrnoException;
+      const code = lastErr.code;
+      if (code !== 'ELOCKED' && code !== 'EBUSY') {
+        throw err;
+      }
+      if (now() >= deadline) {
+        const holderPid = readHolderPid(lockPath);
+        const remainingMs = Math.max(0, deadline - now());
+        // Surface a hint about how long the *next* poll cycle should wait.
+        // When `blockMs=0` the user got bail-immediately semantics; report
+        // the staleness window so they know the lock auto-releases in N s.
+        const retryAfterSeconds = blockMs === 0
+          ? Math.round(staleMs / 1000)
+          : Math.round(remainingMs / 1000);
+        throw new InstallLockBusyError(lockPath, holderPid, retryAfterSeconds, code);
+      }
+      sleep(pollIntervalMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      if (release) release();
+    } catch {
+      // best-effort
+    }
+    try {
+      rmSync(`${lockPath}.pid`, { force: true });
+    } catch {
+      // best-effort
+    }
+  }
+}

package/src/lib/pidLiveness.ts

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Cross-platform PID liveness probe.
+ *
+ * POSIX (macOS / Linux):
+ *   process.kill(pid, 0) → no-throw == alive; ESRCH → dead; EPERM → alive
+ *   (the process exists but we lack permission to signal it).
+ *
+ * Windows:
+ *   `tasklist /FI "PID eq <pid>" /NH` and grep for the PID. Best-effort.
+ *
+ * Returns boolean; never throws. Used by hooks/session-start.ts
+ * (banner suppression) and watch/daemon.ts (registry sweep).
+ */
+
+import { spawnSync } from 'child_process';
+
+interface ProbeOpts {
+  /** When set, override `process.platform` (test seam). */
+  platformOverride?: NodeJS.Platform;
+  /** When set, override `process.kill` (test seam). */
+  killOverride?: (pid: number, signal: number) => boolean;
+}
+
+export function isPidAlive(pid: number, opts: ProbeOpts = {}): boolean {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+
+  const platform = opts.platformOverride ?? process.platform;
+
+  if (platform === 'win32') {
+    return checkWindows(pid);
+  }
+  return checkPosix(pid, opts.killOverride);
+}
+
+function checkPosix(pid: number, killOverride?: (pid: number, signal: number) => boolean): boolean {
+  try {
+    if (killOverride) {
+      killOverride(pid, 0);
+    } else {
+      process.kill(pid, 0);
+    }
+    return true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'EPERM') return true;
+    // ESRCH or anything else → treat as dead.
+    return false;
+  }
+}
+
+function checkWindows(pid: number): boolean {
+  try {
+    const res = spawnSync('tasklist', ['/FI', `PID eq ${pid}`, '/NH'], {
+      encoding: 'utf-8',
+      windowsHide: true,
+    });
+    if (res.error || res.status !== 0) return false;
+    const stdout = res.stdout || '';
+    // Each match is a line that starts with the image name and includes the PID.
+    return new RegExp(`\\b${pid}\\b`).test(stdout);
+  } catch {
+    return false;
+  }
+}

package/src/lsp/auto-detect.ts

@@ -0,0 +1,89 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 4: LSP server discovery.
+ *
+ * Per audit-iter-1 fix G4: this module's discovery is **explicit-only by
+ * default**. The optional `lsof` port-scan path is GATED behind
+ * `lsp.autoDetect.viaPortScan: true` and defaults to `false` (port-scanning
+ * local processes is a security-sensitive default — opt-in only at v1).
+ *
+ * Empty-servers edge case (audit-iter-3 fix Z): when `lsp.enabled: true` AND
+ * `lsp.servers` is empty AND `viaPortScan: false`, we log ONE informational
+ * stderr line and return an empty list — the caller (`enrich.ts`) then
+ * proceeds AST-only without throwing.
+ *
+ * VR-LSP-AUTODETECT-OFF-BY-DEFAULT: `viaPortScan` MUST be checked BEFORE any
+ * `lsof` invocation. The grep `grep -nE 'viaPortScan' auto-detect.ts` MUST
+ * show that boolean check ahead of any `lsof` call.
+ */
+
+import type { LSPConfig } from '../config.ts';
+import type { LSPServerSpec } from './client.ts';
+
+/**
+ * Find LSP servers to launch / connect to. Pure config-driven by default.
+ *
+ * @param config - The `lsp` block from `massu.config.yaml`. May be undefined
+ *   when LSP is not configured at all (returns empty list silently).
+ * @returns A list of `LSPServerSpec` ready to feed `LSPClient.fromCommand()`.
+ *   Empty list is a valid, non-error outcome — callers MUST proceed AST-only.
+ */
+export async function findRunningLSPs(
+  config: LSPConfig | undefined
+): Promise<LSPServerSpec[]> {
+  // Disabled or absent: silently no-op (no log).
+  if (!config || !config.enabled) {
+    return [];
+  }
+
+  const explicit = (config.servers ?? []).map((s) => splitCommand(s));
+
+  // VR-LSP-AUTODETECT-OFF-BY-DEFAULT: this boolean check happens BEFORE any
+  // `lsof`/port-scan invocation. Default is false — explicit-only path.
+  const viaPortScan = config.autoDetect?.viaPortScan === true;
+
+  if (explicit.length === 0 && !viaPortScan) {
+    // Empty-servers edge case: enabled but nothing configured AND auto-detect
+    // is off. Log once, proceed AST-only.
+    process.stderr.write(
+      '[massu/lsp] INFO: LSP enabled but no servers configured and auto-detect off — skipping LSP enrichment.\n'
+    );
+    return [];
+  }
+
+  // Port-scan path is opt-in via `viaPortScan: true`. Implementation
+  // intentionally minimal at v1 — emits an INFO stderr line and returns
+  // explicit servers only. Plan 3d will flesh out actual `lsof` discovery
+  // once the threat model is reviewed.
+  if (viaPortScan) {
+    process.stderr.write(
+      '[massu/lsp] INFO: lsp.autoDetect.viaPortScan is enabled but port-scan auto-detect is reserved for Plan 3d — using explicit servers only.\n'
+    );
+    // (No `lsof` invocation yet. The viaPortScan gate exists so future
+    // implementations slot in here without changing the default surface.)
+  }
+
+  return explicit;
+}
+
+/**
+ * Parse a config-string `command` into an `LSPServerSpec`. Splits on
+ * whitespace (no shell evaluation, no globbing). Strict path validation
+ * happens later in `LSPClient.fromCommand()` — this just parses the shape.
+ *
+ * Note: callers passing untrusted commands MUST review the result before
+ * passing it to `LSPClient.fromCommand`. The factory rejects relative paths
+ * and `..`-containing argv elements.
+ */
+function splitCommand(server: { language: string; command: string }): LSPServerSpec {
+  const cmd = (server.command ?? '').trim();
+  // Whitespace split — not a full shell parser. Quoted args with spaces are
+  // not supported at v1; users with such commands should run a wrapper script.
+  const argv = cmd.length === 0 ? [] : cmd.split(/\s+/);
+  return {
+    language: server.language,
+    argv,
+  };
+}