@massu/core 1.3.0 → 1.4.0

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,98 @@
+// 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;
+  allow_setuid?: boolean;
+  max_rss_mb?: number;
+}): 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,
+    // F-014 / F-015 (closed 2026-05-06): pass through the security knobs
+    // from config so the spawn surface enforces them.
+    allowSetuid: server.allow_setuid ?? false,
+    maxRssMb: server.max_rss_mb ?? undefined,
+  };
+}