moflo 4.10.6 → 4.10.8

package/dist/src/cli/services/claudemd-injection.js

@@ -0,0 +1,173 @@
+/**
+ * CLAUDE.md injection drift detection + replacement (#1142).
+ *
+ * Detects when a consumer's `<root>/CLAUDE.md` carries a MoFlo-injected block
+ * whose content has drifted from what the current generator produces. Catches
+ * the case where a consumer upgrades moflo (so guidance files refresh) but the
+ * CLAUDE.md injection — only rewritten by explicit `flo init` / `flo-setup` —
+ * stays frozen at the prior version's content, sometimes pointing at paths
+ * that no longer exist (e.g. `.claude/guidance/shipped/...` before the
+ * flat-layout cleanup).
+ *
+ * IMPORTANT: This module must remain self-contained with ZERO imports from
+ * other moflo modules (mirrors the constraint on `services/hook-block-hash.ts`
+ * and `services/hook-wiring.ts`). It is dynamically imported at runtime by
+ * `bin/session-start-launcher.mjs` in consumer projects, where transitive
+ * dependencies may not resolve.
+ *
+ * The MoFlo block markers are duplicated from `init/claudemd-generator.ts` on
+ * purpose — the launcher cannot pull in TS dist of init/types.js at runtime,
+ * and a unit test asserts the two stay in sync.
+ */
+// ────────────────────────────────────────────────────────────────────────────
+// Marker constants — kept in sync with init/claudemd-generator.ts
+// ────────────────────────────────────────────────────────────────────────────
+export const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
+export const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
+// Legacy markers from earlier moflo versions — detected on drift checks so we
+// can offer to replace the legacy block with the current marker pair.
+export const LEGACY_MARKER_STARTS = [
+    '<!-- MOFLO:START -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:START -->',
+];
+export const LEGACY_MARKER_ENDS = [
+    '<!-- MOFLO:END -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:END -->',
+];
+// ────────────────────────────────────────────────────────────────────────────
+// Block extraction
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Locate the MoFlo-injected block in `claudeMdContents`, normalising line
+ * endings so a CRLF file matches an LF canonical block (Windows consumers
+ * regularly hit this — git autocrlf can flip the source bytes on checkout).
+ *
+ * Returns null when `contents` is null/undefined/empty, or when no marker
+ * pair is found. Includes the marker strings themselves in the extracted
+ * block, matching `MARKER_START…MARKER_END` exactly so a byte-for-byte
+ * compare against the canonical block works.
+ */
+export function extractInjectedBlock(claudeMdContents) {
+    if (!claudeMdContents)
+        return null;
+    const normalised = claudeMdContents.replace(/\r\n/g, '\n');
+    // Try the current marker pair first, then each legacy pair. markerIndex:
+    //   0  → current MARKER_START/MARKER_END
+    //   1+ → LEGACY_MARKER_STARTS[markerIndex - 1] / LEGACY_MARKER_ENDS[markerIndex - 1]
+    const starts = [MARKER_START, ...LEGACY_MARKER_STARTS];
+    const ends = [MARKER_END, ...LEGACY_MARKER_ENDS];
+    for (let i = 0; i < starts.length; i++) {
+        const startIdx = normalised.indexOf(starts[i]);
+        if (startIdx < 0)
+            continue;
+        const endIdx = normalised.indexOf(ends[i], startIdx + starts[i].length);
+        if (endIdx <= startIdx)
+            continue;
+        const endInclusive = endIdx + ends[i].length;
+        return {
+            block: normalised.substring(startIdx, endInclusive),
+            start: startIdx,
+            end: endInclusive,
+            markerIndex: i,
+        };
+    }
+    return null;
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Drift detection
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Trim `canonical` to the bytes between (and including) the current MoFlo
+ * markers. `generateClaudeMd()` appends a trailing newline that callers
+ * commonly include in the result; the in-file block does not carry that
+ * newline, so we strip trailing whitespace before comparing.
+ */
+function canonicalBlock(canonical) {
+    return canonical.replace(/\r\n/g, '\n').trimEnd();
+}
+/**
+ * Classify a consumer's CLAUDE.md against the canonical injected block.
+ *
+ * `claudeMdContents` should be the result of `readFileSync(<root>/CLAUDE.md)`
+ * or null/undefined when the file is absent. `canonical` is the output of
+ * `generateClaudeMd({})` from `init/claudemd-generator.ts`.
+ */
+export function computeInjectionDrift(claudeMdContents, canonical) {
+    if (claudeMdContents === null || claudeMdContents === undefined) {
+        return { state: 'no-file' };
+    }
+    const extracted = extractInjectedBlock(claudeMdContents);
+    if (!extracted) {
+        return { state: 'no-marker' };
+    }
+    if (extracted.markerIndex > 0) {
+        return { state: 'legacy-marker', legacyMarkerIndex: extracted.markerIndex - 1 };
+    }
+    const currentBlock = extracted.block;
+    const wantBlock = canonicalBlock(canonical);
+    if (currentBlock === wantBlock) {
+        return { state: 'in-sync' };
+    }
+    return { state: 'drifted' };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Replacement
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Apply the canonical block to `claudeMdContents`, returning the new
+ * contents and a `changed` flag indicating whether any bytes differ. The
+ * caller writes the file (or persists in-memory state) — this function does
+ * no I/O so it's safe to call from any execution context.
+ *
+ * Behavior by input state:
+ *  - `no-file` → returns `{ contents: canonical, changed: true }` so the
+ *    caller can write a fresh CLAUDE.md (e.g. `flo init` first-run).
+ *  - `no-marker` → APPENDS the canonical block to the end of the existing
+ *    contents (matches `bin/setup-project.mjs:updateClaudeMd` append path).
+ *  - `legacy-marker` → REPLACES the legacy block in-place with the canonical block.
+ *  - `in-sync` → no change.
+ *  - `drifted` → REPLACES the existing block in-place with the canonical block.
+ */
+export function applyInjectionReplacement(claudeMdContents, canonical) {
+    const want = canonicalBlock(canonical);
+    if (claudeMdContents === null || claudeMdContents === undefined) {
+        return { contents: `# Project Configuration\n\n${want}\n`, changed: true, state: 'in-sync' };
+    }
+    const extracted = extractInjectedBlock(claudeMdContents);
+    if (!extracted) {
+        // No marker — append the canonical block to the end (idempotent for
+        // future runs because the appended block will then be located on
+        // subsequent extractions).
+        const sep = claudeMdContents.endsWith('\n') ? '\n' : '\n\n';
+        const next = claudeMdContents + sep + want + '\n';
+        return { contents: next, changed: true, state: 'in-sync' };
+    }
+    // We located a marker pair (current or legacy). If content already matches
+    // the canonical block, nothing to do.
+    if (extracted.markerIndex === 0 && extracted.block === want) {
+        return { contents: claudeMdContents, changed: false, state: 'in-sync' };
+    }
+    // Operate on the line-ending-normalised view so the byte offsets we record
+    // line up with the actual replacement window. The output keeps LF endings
+    // — the launcher and setup-project both write LF.
+    const normalised = claudeMdContents.replace(/\r\n/g, '\n');
+    const next = normalised.substring(0, extracted.start) + want + normalised.substring(extracted.end);
+    return { contents: next, changed: true, state: 'in-sync' };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Human-readable status for healer + launcher output
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Short one-line summary describing a drift state. Used by `flo doctor` and
+ * the session-start launcher when reporting status to the user.
+ */
+export function formatInjectionDriftStatus(report) {
+    switch (report.state) {
+        case 'no-file': return 'CLAUDE.md not found';
+        case 'no-marker': return 'CLAUDE.md has no moflo injection block';
+        case 'legacy-marker': return 'CLAUDE.md uses a legacy moflo marker pair';
+        case 'in-sync': return 'CLAUDE.md injection block matches reference';
+        case 'drifted': return 'CLAUDE.md injection block has drifted from reference';
+    }
+}
+//# sourceMappingURL=claudemd-injection.js.map

package/dist/src/cli/services/daemon-dashboard.js

@@ -16,7 +16,18 @@ import { createServer } from 'node:http';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { handleMemoryStore, handleMemoryDelete, handleMemoryBatch, handleMemoryGet, handleMemorySearch, handleMemoryList, matchMemoryRpcRoute, } from './daemon-memory-rpc.js';
 import { aggregateClaudeStats, emptyClaudeStatsShape } from './claude-stats.js';
-export const DEFAULT_DASHBOARD_PORT = 3117;
+import { serverPortCandidates, LEGACY_DEFAULT_PORT } from './daemon-port.js';
+import { writeLockPort } from './daemon-lock.js';
+import { findProjectRoot } from './project-root.js';
+import { readOwnMofloVersion } from './daemon-lock.js';
+/**
+ * Legacy default port retained as a re-export of {@link LEGACY_DEFAULT_PORT}
+ * for backward compat with existing importers (`commands/daemon.ts`,
+ * `__tests__/daemon-dashboard.test.ts`). The actual port a daemon binds is
+ * now resolved deterministically per project via `serverPortCandidates()` —
+ * see `daemon-port.ts` and `docs/internal/1145-daemon-port-collision-analysis.md`.
+ */
+export const DEFAULT_DASHBOARD_PORT = LEGACY_DEFAULT_PORT;
 /**
  * Process-wide promise for the shared MemoryAccessor. Memoized as a *promise*
  * (not the resolved value) so concurrent first-callers share a single init
@@ -129,6 +140,27 @@ function tryParseSafe(s) {
         return s;
     }
 }
+/**
+ * Build the `/api/health` response (#1145).
+ *
+ * Identity payload — clients compare `projectRoot` against their own
+ * `findProjectRoot()` and refuse to route to this daemon on mismatch.
+ * Also surfaces `pid`, `version`, and `uptimeMs` for healer-class
+ * diagnostics and orphan-daemon detection.
+ *
+ * Read-only, no-auth, localhost-only (the dashboard binds 127.0.0.1).
+ */
+function handleHealth(daemon, opts) {
+    const status = daemon.getStatus();
+    const startedAt = status.startedAt instanceof Date ? status.startedAt : null;
+    return {
+        status: 'ok',
+        projectRoot: opts.projectRoot ?? findProjectRoot(),
+        pid: status.pid ?? process.pid,
+        version: readOwnMofloVersion() ?? null,
+        uptimeMs: startedAt ? Date.now() - startedAt.getTime() : 0,
+    };
+}
 function handleStatus(daemon) {
     const status = daemon.getStatus();
     // Index config rows by worker type so the row renderer can show a
@@ -244,15 +276,18 @@ function tryParse(s) {
     }
 }
 async function handleMemoryStats() {
-    // Single GROUP BY query — no hardcoded namespace list, no row fetching
-    try {
-        const { getNamespaceCounts } = await import('../memory/memory-initializer.js');
-        const { namespaces, total } = await getNamespaceCounts();
-        return { namespaces, totalEntries: total, available: total > 0 || Object.keys(namespaces).length > 0 };
-    }
-    catch {
-        return { namespaces: {}, totalEntries: 0, available: false };
-    }
+    // Single GROUP BY query — no hardcoded namespace list, no row fetching.
+    // Errors propagate to the request handler's outer try/catch → 500, so
+    // MCP clients see a real failure instead of a silent `totalEntries: 0`.
+    const { getNamespaceCounts } = await import('../memory/memory-initializer.js');
+    const { namespaces, total, withEmbeddings } = await getNamespaceCounts();
+    return {
+        ok: true,
+        namespaces,
+        totalEntries: total,
+        withEmbeddings,
+        available: total > 0 || Object.keys(namespaces).length > 0,
+    };
 }
 /**
  * Build the `/api/claude-stats` response (#1044).
@@ -433,6 +468,11 @@ async function handleRequest(req, res, daemon, opts) {
         if (url === '/') {
             sendHtml(res, DASHBOARD_HTML);
         }
+        else if (url === '/api/health') {
+            // #1145 — identity probe. Clients use this to confirm they're talking
+            // to the daemon for their OWN project before routing memory ops here.
+            sendJson(res, 200, handleHealth(daemon, opts));
+        }
         else if (url === '/api/status') {
             sendJson(res, 200, handleStatus(daemon));
         }
@@ -588,33 +628,62 @@ const MAX_PORT_ATTEMPTS = 10;
 /**
  * Start the dashboard HTTP server.
  *
- * Tries the requested port first, then falls back to port+1, port+2, ...
- * up to MAX_PORT_ATTEMPTS to avoid crashing the daemon when another
- * project's daemon already holds the default port.
+ * Port selection (#1145):
+ *   1. `opts.port`, if explicitly set (CLI `--dashboard-port` flag).
+ *   2. Otherwise `serverPortCandidates(projectRoot)` — deterministic per-
+ *      project port + collision-fallback range.
+ * Both honor `MOFLO_DAEMON_PORT` (collapses the candidate list to one).
+ *
+ * On successful bind the bound port is stamped into `.moflo/daemon.lock`
+ * via `writeLockPort()` so clients can discover it without guessing.
  *
- * @param daemon - WorkerDaemon instance for status data
- * @param opts - Dashboard configuration
- * @returns A handle to stop the server (port reflects the actual bound port)
+ * On bind exhaustion (every candidate in use) the server throws — the
+ * caller is expected to surface the failure rather than stay half-alive
+ * (the silent-trap pattern that produced #1145).
+ *
+ * @returns handle whose `.port` field reflects the actually bound port
  */
 export async function startDashboard(daemon, opts) {
-    const basePort = opts.port;
-    for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
-        const port = basePort + attempt;
+    const projectRoot = opts.projectRoot ?? findProjectRoot();
+    const candidates = buildBindCandidates(opts.port, projectRoot, MAX_PORT_ATTEMPTS);
+    let lastErr = null;
+    for (let i = 0; i < candidates.length; i++) {
+        const port = candidates[i];
         try {
-            const handle = await tryListenOnPort(daemon, opts, port);
+            const handle = await tryListenOnPort(daemon, { ...opts, projectRoot }, port);
+            // Stamp the bound port into the lock so clients discover us reliably.
+            // Best-effort: a missing/locked-by-another-pid lock means stamping
+            // is a no-op — the deterministic fallback still works.
+            try {
+                writeLockPort(projectRoot, handle.port);
+            }
+            catch { /* ignore */ }
             return handle;
         }
         catch (err) {
+            lastErr = err;
             const code = err && typeof err === 'object' && 'code' in err ? err.code : '';
-            if (code === 'EADDRINUSE' && attempt < MAX_PORT_ATTEMPTS - 1) {
-                // Port taken — try the next one
+            if (code === 'EADDRINUSE' && i < candidates.length - 1)
                 continue;
-            }
             throw err;
         }
     }
-    // Should be unreachable, but satisfies the type checker
-    throw new Error(`All dashboard ports ${basePort}–${basePort + MAX_PORT_ATTEMPTS - 1} are in use`);
+    // Bind exhaustion — surface so the daemon can hard-fail (#1145 §9.4).
+    throw lastErr ?? new Error(`All dashboard ports (${candidates[0]}…${candidates[candidates.length - 1]}) are in use`);
+}
+/**
+ * Build the ordered list of ports to try.
+ *
+ * When the caller pinned a port (CLI flag), respect it without any
+ * fallback — the consumer pinned it on purpose. When they didn't, use
+ * the deterministic per-project candidates so two projects never collide
+ * silently on a fixed default.
+ */
+function buildBindCandidates(explicitPort, projectRoot, maxAttempts) {
+    if (typeof explicitPort === 'number' && explicitPort > 0 && explicitPort < 65536) {
+        return [explicitPort];
+    }
+    return serverPortCandidates(projectRoot, maxAttempts);
 }
 /**
  * Attempt to bind the dashboard server to a specific port.