@lightpath-dev/daemon 0.0.1 → 0.1.0

package/dist/actions.d.ts

@@ -0,0 +1,19 @@
+import type { ActionRequest, ActionResult, ActionRunner, Trace, TraceId } from '@lightpath-dev/protocol';
+import type { Store } from './store.js';
+/** Longest wait after `traceEnd` for the backend lines of the requests an action sent (D-114). */
+export declare const BACKEND_WAIT_MS = 1500;
+type Tagged = {
+    method: string;
+    path: string;
+};
+/** The tagged requests that have no backend delta in the trace yet, matched by method and path. */
+export declare function missingBackend(trace: Trace | undefined, tagged: readonly Tagged[]): Tagged[];
+/**
+ * One wait for all of an action's requests: ends as soon as each tagged request has its backend
+ * delta in the stored trace, or after `waitMs`. Returns the requests still missing.
+ */
+export declare function waitForBackend(store: Store, traceId: TraceId, tagged: readonly Tagged[], waitMs?: number): Promise<Tagged[]>;
+/** Runs one `/v1/action` request: the runner's action, then the backend wait (section 4.3). */
+export declare function runAction(runner: ActionRunner | undefined, store: Store, request: ActionRequest, waitMs?: number): Promise<ActionResult>;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -0,0 +1,84 @@
+/** Longest wait after `traceEnd` for the backend lines of the requests an action sent (D-114). */
+export const BACKEND_WAIT_MS = 1500;
+const withoutQuery = (path) => path.split('?')[0] ?? path;
+const key = (r) => `${r.method.toUpperCase()} ${withoutQuery(r.path)}`;
+/** The tagged requests that have no backend delta in the trace yet, matched by method and path. */
+export function missingBackend(trace, tagged) {
+    const have = new Map();
+    for (const r of trace?.requests ?? []) {
+        if (r.collector === 'browser')
+            continue;
+        have.set(key(r), (have.get(key(r)) ?? 0) + 1);
+    }
+    const missing = [];
+    for (const r of tagged) {
+        const n = have.get(key(r)) ?? 0;
+        if (n > 0)
+            have.set(key(r), n - 1);
+        else
+            missing.push(r);
+    }
+    return missing;
+}
+/**
+ * One wait for all of an action's requests: ends as soon as each tagged request has its backend
+ * delta in the stored trace, or after `waitMs`. Returns the requests still missing.
+ */
+export function waitForBackend(store, traceId, tagged, waitMs = BACKEND_WAIT_MS) {
+    const initial = missingBackend(store.get(traceId), tagged);
+    if (initial.length === 0)
+        return Promise.resolve([]);
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(missingBackend(store.get(traceId), tagged));
+        };
+        const timer = setTimeout(finish, waitMs);
+        const unsubscribe = store.subscribe((trace) => {
+            if (trace.id === traceId && missingBackend(trace, tagged).length === 0)
+                finish();
+        });
+    });
+}
+/** Runs one `/v1/action` request: the runner's action, then the backend wait (section 4.3). */
+export async function runAction(runner, store, request, waitMs = BACKEND_WAIT_MS) {
+    if (!runner) {
+        return {
+            ok: false,
+            error: {
+                code: 'no_browser',
+                message: 'Lightpath has no browser open to act in. Start it with a browser (lightpath dev -- <your dev command>, ' +
+                    'without --no-browser) and wait until it prints "watching".',
+            },
+        };
+    }
+    const outcome = await runner(request);
+    if (!outcome.ok)
+        return outcome;
+    const missing = await waitForBackend(store, outcome.traceId, outcome.tagged, waitMs);
+    const trace = store.get(outcome.traceId);
+    if (!trace) {
+        return {
+            ok: false,
+            error: { code: 'no_trace', message: `Trace ${outcome.traceId} was evicted before it could be read.` },
+        };
+    }
+    const warnings = [...outcome.warnings];
+    if (missing.length > 0) {
+        warnings.push({
+            code: 'backend_partial',
+            message: `No backend lines arrived within ${waitMs} ms for ${missing.map(key).join(', ')}: a remote API, or a server not started by lightpath dev.`,
+        });
+    }
+    return {
+        ok: true,
+        trace,
+        boundary: outcome.boundary,
+        settled: outcome.settled,
+        backend: missing.length > 0 ? 'partial' : 'complete',
+        pageUrl: outcome.pageUrl,
+        warnings,
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/correlator.d.ts

@@ -1,5 +1,5 @@
 import { type ResolveContext } from '@lightpath-dev/core';
-import type { IngestMessage } from '@lightpath-dev/protocol';
+import { type IngestMessage } from '@lightpath-dev/protocol';
 import type { Store } from './store.js';
 /**
  * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).

package/dist/correlator.js

@@ -1,4 +1,5 @@
-import { decodeDataUrlSourceMap, mapScript, mergeLineCounts, newTraceId, PeriodicFunctions, resolveFile, } from '@lightpath-dev/core';
+import { decodeDataUrlSourceMap, mapFunctions, mapScript, mergeLineCounts, newTraceId, originalLocation, PeriodicFunctions, resolveFile, } from '@lightpath-dev/core';
+import { MAX_TRACE_PROBLEMS, } from '@lightpath-dev/protocol';
 /**
  * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).
  * Pure in-memory logic with no I/O, so it's tested without sockets.
@@ -68,7 +69,62 @@ export class Correlator {
             case 'lines':
                 this.#onLines(agentId, message);
                 return;
+            case 'problem':
+                this.#onProblem(agentId, message);
+                return;
+        }
+    }
+    /** Attaches an error or failed request to its trace (D-121). Without an open trace, dropped. */
+    #onProblem(agentId, msg) {
+        if (!msg.traceId)
+            return;
+        const agent = this.#agent(agentId);
+        // A backend crash during run_request comes before any delta for its trace: it opens one.
+        const pending = this.#pending.get(msg.traceId) ??
+            this.#fromStore(msg.traceId) ??
+            (agent.kind === 'browser' ? undefined : this.#pendingFor(msg.traceId, 'uncaught error', msg.at));
+        if (!pending)
+            return;
+        pending.trace.problems ??= [];
+        const problems = pending.trace.problems;
+        if (problems.length >= MAX_TRACE_PROBLEMS) {
+            pending.trace.problemsDropped = (pending.trace.problemsDropped ?? 0) + 1;
+            this.#publish(pending);
+            return;
+        }
+        const where = msg.location ? this.#locate(agent, msg.location) : undefined;
+        problems.push({
+            collector: agent.kind,
+            kind: msg.kind,
+            message: msg.message,
+            at: msg.at,
+            ...(where ? { path: where.path, line: where.line } : {}),
+            ...(msg.request ? { request: msg.request } : {}),
+        });
+        this.#publish(pending);
+    }
+    /** A problem's generated location as a workspace path and original line, if it maps there. */
+    #locate(agent, loc) {
+        if (loc.line < 1)
+            return undefined;
+        const info = [...agent.scripts.values()].reverse().find((s) => s.url === loc.url);
+        let source = loc.url;
+        let line = loc.line;
+        if (info?.sourceMapURL) {
+            try {
+                const map = decodeDataUrlSourceMap(info.sourceMapURL);
+                const orig = map ? originalLocation(map, info.url, loc.line, loc.column) : undefined;
+                if (!orig)
+                    return undefined;
+                source = orig.source;
+                line = orig.line;
+            }
+            catch {
+                return undefined;
+            }
         }
+        const r = resolveFile(source, this.#ctx);
+        return r.kind === 'workspace' ? { path: r.path, line } : undefined;
     }
     #onDelta(agentId, delta) {
         const agent = this.#agent(agentId);
@@ -78,6 +134,20 @@ export class Correlator {
             return;
         }
         const pending = this.#pendingFor(delta.traceId, delta.request ? `${delta.request.method} ${delta.request.path}` : 'action', delta.startedAt);
+        // Which phase this delta's functions belong to (D-116). A backend phase is made below, once
+        // the request has its index.
+        let phase;
+        if (delta.beforeRequest) {
+            phase = { kind: 'before-request', at: delta.endedAt, leaving: delta.beforeRequest };
+            pending.phases.push(phase);
+        }
+        else if (!delta.request) {
+            phase = this.#closingPhase(pending, delta.endedAt);
+        }
+        else {
+            phase = { kind: 'backend', at: delta.startedAt, request: pending.trace.requests.length };
+            pending.phases.push(phase);
+        }
         for (const coverage of delta.coverage) {
             const info = agent.scripts.get(coverage.scriptId);
             const source = info ? this.#sources.get(info.hash) : undefined;
@@ -108,6 +178,9 @@ export class Correlator {
                 const foreground = fgLines !== undefined && [...fgLines.values()].some((c) => c > 0);
                 this.#addFile(pending, path, agent.kind, lines, delta.startedAt, foreground);
             }
+            const fns = mapFunctions({ coverage, source, ...(sourceMap ? { sourceMap } : {}) }, result.files, this.#ctx);
+            for (const fn of fns)
+                this.#addFunction(pending, phase, agent.kind, fn);
         }
         if (delta.request) {
             pending.trace.requests.push({
@@ -126,10 +199,56 @@ export class Correlator {
             pending.trace.endedAt = Math.max(pending.trace.endedAt ?? 0, delta.endedAt);
         this.#publish(pending);
     }
+    /** Adds one function to its phase, summing calls and keeping lines not run in every delta. */
+    #addFunction(p, phase, collector, fn) {
+        const key = `${p.phases.indexOf(phase)}|${phase.kind}|${fn.path}|${fn.name}|${fn.startLine}`;
+        const prev = p.functions.get(key);
+        if (!prev) {
+            p.functions.set(key, {
+                phase,
+                hit: {
+                    path: fn.path,
+                    collector,
+                    name: fn.name,
+                    startLine: fn.startLine,
+                    endLine: fn.endLine,
+                    count: fn.count,
+                    ...(fn.notRun.length ? { notRun: fn.notRun } : {}),
+                    ...(fn.notRunSpans.length ? { notRunSpans: fn.notRunSpans } : {}),
+                },
+            });
+            return;
+        }
+        const hit = prev.hit;
+        hit.count += fn.count;
+        hit.endLine = Math.max(hit.endLine, fn.endLine);
+        const notRun = (hit.notRun ?? []).filter((l) => fn.notRun.includes(l));
+        const spans = (hit.notRunSpans ?? []).filter((s) => fn.notRunSpans.some((t) => t.line === s.line && t.startColumn === s.startColumn));
+        if (notRun.length)
+            hit.notRun = notRun;
+        else
+            delete hit.notRun;
+        if (spans.length)
+            hit.notRunSpans = spans;
+        else
+            delete hit.notRunSpans;
+    }
+    /** The one browser phase for reads not taken before a request (D-116), made on first use. */
+    #closingPhase(p, at) {
+        if (!p.closing) {
+            p.closing = { kind: 'browser', at };
+            p.phases.push(p.closing);
+        }
+        p.closing.at = Math.max(p.closing.at, at);
+        return p.closing;
+    }
     #onLines(agentId, msg) {
         const agent = this.#agent(agentId);
         const label = msg.request ? `${msg.request.method} ${msg.request.path}` : 'action';
         const pending = this.#pendingFor(msg.traceId, label, msg.startedAt);
+        // Python files have no function list; the summary lists them by line range in this phase.
+        if (msg.request)
+            pending.phases.push({ kind: 'backend', at: msg.startedAt, request: pending.trace.requests.length });
         for (const file of msg.files) {
             const r = resolveFile(file.path, this.#ctx);
             if (r.kind === 'dropped') {
@@ -182,7 +301,37 @@ export class Correlator {
         const trace = this.#store.get(traceId);
         if (!trace)
             return undefined;
-        const p = { trace: structuredClone(trace), files: new Map(), dropped: new Map() };
+        const p = {
+            trace: structuredClone(trace),
+            files: new Map(),
+            dropped: new Map(),
+            phases: [],
+            functions: new Map(),
+        };
+        // Phases keep their published order: their old sort keys are their positions, which sort
+        // before any new read's time. The closing browser phase stays last.
+        for (const [i, ph] of (trace.phases ?? []).entries()) {
+            const open = {
+                kind: ph.kind,
+                at: i,
+                ...(ph.request !== undefined ? { request: ph.request } : {}),
+            };
+            if (ph.kind === 'before-request' && ph.request !== undefined) {
+                const r = trace.requests[ph.request];
+                if (r)
+                    open.leaving = { method: r.method, path: r.path };
+            }
+            if (ph.kind === 'browser' || ph.kind === 'after-response')
+                p.closing = open;
+            p.phases.push(open);
+        }
+        for (const f of trace.functions ?? []) {
+            const phase = p.phases[f.phase];
+            if (!phase)
+                continue;
+            const { phase: _, ...hit } = f;
+            p.functions.set(`${f.phase}|${phase.kind}|${f.path}|${f.name}|${f.startLine}`, { phase, hit });
+        }
         for (const f of trace.files) {
             p.files.set(f.path, {
                 collector: f.collector,
@@ -201,8 +350,48 @@ export class Correlator {
             trace: { id, label, origin, startedAt: at, files: [], requests: [], dropped: [] },
             files: new Map(),
             dropped: new Map(),
+            phases: [],
+            functions: new Map(),
         };
     }
+    /**
+     * Orders the phases and numbers them (design section 5.3): reads and requests in time order, the
+     * closing browser phase last. It is `after-response` when any request left the page before it,
+     * else `browser`. Each before-request phase is tied to the first unmatched backend request with
+     * the same method and path.
+     */
+    #phasesOf(p, published) {
+        if (p.phases.length === 0)
+            return undefined;
+        const ordered = p.phases.filter((ph) => ph !== p.closing).sort((a, b) => a.at - b.at);
+        if (p.closing)
+            ordered.push(p.closing);
+        const hasBefore = ordered.some((ph) => ph.kind === 'before-request');
+        const matched = new Set();
+        const phases = ordered.map((ph) => {
+            if (ph === p.closing)
+                return { kind: hasBefore ? 'after-response' : 'browser' };
+            if (ph.kind === 'backend')
+                return { kind: 'backend', ...(ph.request !== undefined ? { request: ph.request } : {}) };
+            if (ph.kind === 'before-request' && ph.leaving) {
+                const { method, path } = ph.leaving;
+                const i = p.trace.requests.findIndex((r, j) => !matched.has(j) && r.collector !== 'browser' && r.method === method && r.path === path);
+                if (i >= 0) {
+                    matched.add(i);
+                    return { kind: 'before-request', request: i };
+                }
+            }
+            return { kind: ph.kind };
+        });
+        const functions = [];
+        for (const { phase, hit } of p.functions.values()) {
+            if (!published.has(hit.path))
+                continue; // its file has no lit line, so it isn't in the trace
+            functions.push({ ...hit, phase: ordered.indexOf(phase) });
+        }
+        functions.sort((a, b) => a.phase - b.phase || a.path.localeCompare(b.path) || a.startLine - b.startLine);
+        return { phases, functions };
+    }
     #addFile(p, path, collector, lines, at, foreground) {
         const existing = p.files.get(path);
         if (existing) {
@@ -235,6 +424,11 @@ export class Correlator {
         files.sort((a, b) => a.firstSeenAt - b.firstSeenAt || a.path.localeCompare(b.path));
         p.trace.files = files;
         p.trace.dropped = [...p.dropped].map(([reason, count]) => ({ reason, count }));
+        const shaped = this.#phasesOf(p, new Set(files.map((f) => f.path)));
+        if (shaped) {
+            p.trace.phases = shaped.phases;
+            p.trace.functions = shaped.functions;
+        }
         this.#store.put(structuredClone(p.trace));
         // Keep at most 50 traces open for late backend deltas; older ones are re-read from the store.
         if (this.#pending.size > 50) {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { BACKEND_WAIT_MS, missingBackend, runAction, waitForBackend } from './actions.js';
 export { authorize, newToken, tokensEqual } from './auth.js';
 export { Correlator } from './correlator.js';
 export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { BACKEND_WAIT_MS, missingBackend, runAction, waitForBackend } from './actions.js';
 export { authorize, newToken, tokensEqual } from './auth.js';
 export { Correlator } from './correlator.js';
 export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import type { ResolveContext } from '@lightpath-dev/core';
+import { type ActionRunner } from '@lightpath-dev/protocol';
 import { Correlator } from './correlator.js';
 import { type Store } from './store.js';
 export interface DaemonOptions {
@@ -13,6 +14,8 @@ export interface DaemonOptions {
     store?: Store;
     writeDiscoveryFile?: boolean;
     log?: (msg: string) => void;
+    /** Longest wait after an action's `traceEnd` for its backend lines (default 1,500 ms). */
+    backendWaitMs?: number;
 }
 export interface RunningDaemon {
     port: number;
@@ -21,6 +24,11 @@ export interface RunningDaemon {
     startedAt: number;
     store: Store;
     correlator: Correlator;
+    /**
+     * Registers what runs `POST /v1/action` (the browser collector, once its page is open), or
+     * removes it. Without one, every action answers `no_browser` (D-115).
+     */
+    setActionRunner(runner: ActionRunner | undefined): void;
     close(): Promise<void>;
 }
 /** Starts the daemon on 127.0.0.1 (docs/ARCHITECTURE.md section 7). */

package/dist/server.js

@@ -1,6 +1,7 @@
 import http, {} from 'node:http';
-import { ClientMessage, CloseCode, IngestBatch, MAX_MESSAGE_BYTES, PROTOCOL_VERSION, } from '@lightpath-dev/protocol';
+import { ActionRequest, ClientMessage, CloseCode, IngestBatch, MAX_ACTION_BYTES, MAX_MESSAGE_BYTES, PROTOCOL_VERSION, } from '@lightpath-dev/protocol';
 import { WebSocketServer } from 'ws';
+import { BACKEND_WAIT_MS, runAction } from './actions.js';
 import { authorize, newToken } from './auth.js';
 import { Correlator } from './correlator.js';
 import { removeDiscovery, writeDiscovery } from './discovery.js';
@@ -11,6 +12,8 @@ export async function startDaemon(options) {
     const store = options.store ?? new MemoryStore();
     const log = options.log ?? (() => { });
     const startedAt = Date.now();
+    const backendWaitMs = options.backendWaitMs ?? BACKEND_WAIT_MS;
+    let actionRunner;
     const correlator = new Correlator(store, {
         workspaceRoots: options.workspaceRoots,
         ...(options.devServers ? { devServers: options.devServers } : {}),
@@ -52,6 +55,32 @@ export async function startDaemon(options) {
             res.writeHead(204, { 'x-lightpath-started-at': String(startedAt) }).end();
             return;
         }
+        if (req.method === 'POST' && path === '/v1/action') {
+            // Same rules as /v1/ingest (D-115). The body holds `fill` values, which are secrets: it is
+            // never logged, and a schema error reply names fields, never values.
+            const auth = authorize(req, token);
+            if (auth !== 'ok')
+                return json(res, auth === 'forbidden' ? 403 : 401, { error: auth });
+            // Drain an oversized body instead of dropping the connection, so the caller sees the 413.
+            const body = await readBody(req, MAX_ACTION_BYTES, true);
+            if (body === undefined)
+                return json(res, 413, { error: 'body too large' });
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return json(res, 400, { error: 'invalid JSON' });
+            }
+            const request = ActionRequest.safeParse(parsed);
+            if (!request.success) {
+                const issues = request.error.issues.slice(0, 5).map((i) => ({ path: i.path, message: i.message }));
+                return json(res, 400, { error: issues });
+            }
+            if (request.data.protocolVersion !== PROTOCOL_VERSION)
+                return json(res, 426, { error: 'protocol version mismatch' });
+            return json(res, 200, await runAction(actionRunner, store, request.data, backendWaitMs));
+        }
         json(res, 404, { error: 'not found' });
     }
     // ── Client feed ───────────────────────────────────────────────────────────
@@ -119,6 +148,9 @@ export async function startDaemon(options) {
         startedAt,
         store,
         correlator,
+        setActionRunner(runner) {
+            actionRunner = runner;
+        },
         async close() {
             for (const client of wss.clients)
                 client.close();
@@ -132,21 +164,27 @@ export async function startDaemon(options) {
 function json(res, status, body) {
     res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
 }
-/** Reads a request body as UTF-8, or returns undefined if it exceeds `limit` bytes. */
-function readBody(req, limit) {
+/**
+ * Reads a request body as UTF-8, or returns undefined if it exceeds `limit` bytes. Past the limit
+ * it drops the connection, or with `drain` reads the rest without keeping it.
+ */
+function readBody(req, limit, drain = false) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
         req.on('data', (chunk) => {
             size += chunk.length;
             if (size > limit) {
+                chunks.length = 0;
+                if (drain)
+                    return;
                 resolve(undefined);
                 req.destroy();
                 return;
             }
             chunks.push(chunk);
         });
-        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('end', () => resolve(size > limit ? undefined : Buffer.concat(chunks).toString('utf8')));
         req.on('error', reject);
     });
 }

package/dist/store.js

@@ -28,7 +28,14 @@ export class MemoryStore {
         for (const t of [...this.#traces.values()].reverse()) {
             if (needle && !t.label.toLowerCase().includes(needle))
                 continue;
-            out.push({ id: t.id, label: t.label, startedAt: t.startedAt, fileCount: t.files.length });
+            const problems = (t.problems?.length ?? 0) + (t.problemsDropped ?? 0);
+            out.push({
+                id: t.id,
+                label: t.label,
+                startedAt: t.startedAt,
+                fileCount: t.files.length,
+                ...(problems > 0 ? { problemCount: problems } : {}),
+            });
             if (query.limit && out.length >= query.limit)
                 break;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightpath-dev/daemon",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Local Lightpath daemon: receives coverage from agents, maps it to source lines, and serves traces",
   "keywords": [
     "coverage",
@@ -35,8 +35,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@lightpath-dev/core": "0.0.1",
-    "@lightpath-dev/protocol": "0.0.1",
+    "@lightpath-dev/core": "0.1.0",
+    "@lightpath-dev/protocol": "0.1.0",
     "ws": "8.22.0"
   },
   "devDependencies": {