@lightpath-dev/mcp 0.0.1 → 0.1.0

package/dist/slices.js

@@ -0,0 +1,216 @@
+import { fitText, MAX_CHARS } from './budget.js';
+import { functionName, numberRanges, phaseTitle } from './summary.js';
+const MAX_LINE = 200;
+/** Room kept for the page line at the end of each page. */
+const PAGE_LINE_ROOM = 300;
+const fnKey = (f) => `${f.path}|${f.name}|${f.startLine}`;
+/**
+ * `get_trace` with `file` or `function` (design section 6.3, D-117): the executed lines of each
+ * outermost function that ran, with numbers, merged over every phase. A run of not-run lines folds
+ * into one marker, an untaken block inside a line that ran is named after the line, lines with no
+ * coverage (blank, comments, types) are left out. Paged under 16,000 characters.
+ */
+export async function sliceTrace(trace, query, read) {
+    const fns = trace.functions ?? [];
+    let path;
+    if (query.file !== undefined) {
+        const found = pick(trace.files.map((f) => f.path), query.file);
+        if (typeof found !== 'string')
+            return listMessage(trace, 'file', query.file, found);
+        path = found;
+    }
+    let units;
+    let label;
+    if (query.function !== undefined) {
+        const name = query.function;
+        const pool = fns.filter((f) => (path ? f.path === path : true));
+        let named = pool.filter((f) => functionName(f) === name);
+        if (named.length === 0)
+            named = pool.filter((f) => functionName(f).toLowerCase() === name.toLowerCase());
+        const groups = new Map();
+        for (const f of named)
+            groups.set(fnKey(f), [...(groups.get(fnKey(f)) ?? []), f]);
+        if (groups.size !== 1) {
+            const all = [...new Set(pool.map((f) => `${functionName(f)} (${f.path}:${f.startLine})`))];
+            const near = all.filter((s) => s.toLowerCase().includes(name.toLowerCase()));
+            return listMessage(trace, 'function', name, groups.size === 0
+                ? near.length
+                    ? near
+                    : all
+                : [...groups.values()].map((g) => `${functionName(g[0])} (${g[0]?.path}:${g[0]?.startLine})`), groups.size > 1);
+        }
+        const group = [...groups.values()][0];
+        const first = group[0];
+        path = first.path;
+        const endLine = Math.max(...group.map((f) => f.endLine));
+        units = [
+            {
+                path,
+                startLine: first.startLine,
+                endLine,
+                fns: fns.filter((f) => f.path === path && f.startLine >= first.startLine && f.endLine <= endLine),
+            },
+        ];
+        label = `function "${name}"`;
+    }
+    else if (path) {
+        units = outermost(path, fns, trace);
+        label = `file "${path}"`;
+    }
+    else {
+        return 'Pass a file or a function to see its executed lines.';
+    }
+    const file = trace.files.find((f) => f.path === path);
+    const lit = new Set((file?.lines ?? []).map((l) => l.line));
+    const source = await read(path);
+    if (!source) {
+        return fitText(`${path}: can't read this file from the workspace, so only line numbers are shown.\nlines that ran: ${numberRanges([...lit])}`);
+    }
+    const src = source.text.split(/\r?\n/);
+    const phaseNames = [
+        ...new Set(fns
+            .filter((f) => f.path === path)
+            .map((f) => trace.phases?.[f.phase])
+            .filter((p) => p !== undefined)
+            .map((p) => phaseTitle(trace, p).replace(/ \[.*\]$/, ''))),
+    ];
+    const head = [];
+    if (source.mtimeMs > trace.startedAt) {
+        head.push(`warning: ${path} changed after this trace; line numbers may not match. Rerun the action for a fresh trace.`);
+    }
+    head.push(`${path} (trace ${trace.id}${phaseNames.length ? `, phase ${phaseNames.join(', ')}` : ''})`);
+    // Each unit as its own block of lines.
+    const blocks = units.map((u) => unitLines(u, src, lit));
+    const pages = paginate(blocks, MAX_CHARS - PAGE_LINE_ROOM - head.join('\n').length - 1);
+    const n = pages.length;
+    const page = Math.min(Math.max(1, query.page ?? 1), Math.max(1, n));
+    if ((query.page ?? 1) > n && n > 0)
+        return `${path} has ${n} page${n === 1 ? '' : 's'}; there is no page ${query.page}.`;
+    const body = pages[page - 1] ?? [];
+    const out = [...head, ...body];
+    if (n > 1) {
+        out.push(page < n
+            ? `page ${page} of ${n}. Call get_trace with traceId "${trace.id}", ${label}, page ${page + 1} for the next.`
+            : `page ${page} of ${n}.`);
+    }
+    return fitText(out.join('\n'), MAX_CHARS, trace.id);
+}
+/** A path from `paths` that `query` names: exactly, or as the only path containing it. */
+function pick(paths, query) {
+    if (paths.includes(query))
+        return query;
+    const q = query.replace(/\\/g, '/').toLowerCase();
+    const hits = paths.filter((p) => p.toLowerCase().includes(q));
+    return hits.length === 1 ? hits[0] : hits;
+}
+function listMessage(trace, what, query, options, ambiguous = options.length > 1) {
+    const shown = options.slice(0, 30);
+    const more = options.length > shown.length ? `\n  +${options.length - shown.length} more` : '';
+    const head = ambiguous
+        ? `"${query}" matches ${options.length} ${what}s in trace ${trace.id}. Call get_trace again with one of them:`
+        : `No ${what} "${query}" in trace ${trace.id}. Its ${what}s:`;
+    return fitText(`${head}\n${shown.map((o) => `  ${o}`).join('\n')}${more}`);
+}
+/** The outermost functions of one file, merged over phases, or one unit for a file without any. */
+function outermost(path, fns, trace) {
+    const mine = fns.filter((f) => f.path === path);
+    if (mine.length === 0) {
+        const lines = trace.files.find((f) => f.path === path)?.lines.map((l) => l.line) ?? [];
+        return lines.length
+            ? [{ path, startLine: Math.min(...lines), endLine: Math.max(...lines), fns: [] }]
+            : [];
+    }
+    const spans = [...new Map(mine.map((f) => [`${f.startLine}-${f.endLine}`, f])).values()].sort((a, b) => a.startLine - b.startLine || b.endLine - a.endLine);
+    const units = [];
+    for (const f of spans) {
+        const last = units.at(-1);
+        if (last && f.startLine >= last.startLine && f.endLine <= last.endLine)
+            continue; // nested
+        if (last && f.startLine <= last.endLine)
+            last.endLine = Math.max(last.endLine, f.endLine);
+        else
+            units.push({ path, startLine: f.startLine, endLine: f.endLine, fns: [] });
+    }
+    for (const u of units)
+        u.fns = mine.filter((f) => f.startLine >= u.startLine && f.endLine <= u.endLine);
+    return units;
+}
+/** The printed lines of one unit. */
+function unitLines(u, src, lit) {
+    const notRun = new Set(u.fns.flatMap((f) => f.notRun ?? []));
+    // A block is untaken only if every phase that ran its function left it untaken.
+    const spansByFn = new Map();
+    for (const f of u.fns) {
+        const list = spansByFn.get(fnKey(f)) ?? [];
+        list.push(new Map((f.notRunSpans ?? []).map((s) => [`${s.line}:${s.startColumn}`, s])));
+        spansByFn.set(fnKey(f), list);
+    }
+    const spans = new Map();
+    for (const list of spansByFn.values()) {
+        const [firstSet, ...others] = list;
+        for (const [key, s] of firstSet ?? []) {
+            if (!others.every((m) => m.has(key)))
+                continue;
+            const line = src[s.line - 1] ?? '';
+            const tail = /^[\w$'"`.\])]+/.exec(line.slice(s.endColumn - 1))?.[0].length ?? 1;
+            const text = line
+                .slice(s.startColumn, s.endColumn - 1 + tail)
+                .trim()
+                .slice(0, 40) || s.text;
+            if (text)
+                spans.set(s.line, [...(spans.get(s.line) ?? []), text]);
+        }
+    }
+    const out = [];
+    let gap = [];
+    const flush = () => {
+        if (gap.length) {
+            out.push(`      // not run: ${gap.length === 1 ? `line ${gap[0]}` : `lines ${gap[0]}-${gap.at(-1)}`}`);
+        }
+        gap = [];
+    };
+    for (let l = u.startLine; l <= u.endLine; l++) {
+        if (lit.has(l)) {
+            flush();
+            let text = src[l - 1] ?? '';
+            if (text.length > MAX_LINE)
+                text = `${text.slice(0, MAX_LINE - 1)}…`;
+            const marks = spans.get(l);
+            out.push(`${String(l).padStart(4)}  ${text}${marks?.length ? `  // not run: ${[...new Set(marks)].join(', ')}` : ''}`);
+        }
+        else if (notRun.has(l))
+            gap.push(l);
+    }
+    flush();
+    return out;
+}
+/** Pages under `room` characters: break between units, and inside a unit only when it alone is too long. */
+function paginate(blocks, room) {
+    const pages = [];
+    let page = [];
+    let used = 0;
+    const push = (line) => {
+        if (used + line.length + 1 > room && page.length) {
+            pages.push(page);
+            page = [];
+            used = 0;
+        }
+        page.push(line);
+        used += line.length + 1;
+    };
+    for (const [i, block] of blocks.entries()) {
+        const lines = i > 0 ? ['  ...', ...block] : block;
+        const blockSize = lines.reduce((n, l) => n + l.length + 1, 0);
+        if (page.length && used + blockSize > room && blockSize <= room) {
+            pages.push(page);
+            page = [];
+            used = 0;
+        }
+        for (const l of lines)
+            push(l);
+    }
+    if (page.length)
+        pages.push(page);
+    return pages;
+}
+//# sourceMappingURL=slices.js.map

package/dist/summary.d.ts

@@ -0,0 +1,30 @@
+import type { FunctionHit, Trace, TracePhase, TraceProblem, TraceRequest } from '@lightpath-dev/protocol';
+/** Sorted line numbers as ranges: [1,2,3,7] → "1-3, 7". */
+export declare function numberRanges(lines: readonly number[]): string;
+export declare const requestLine: (r: TraceRequest) => string;
+/** The title of one phase: `before POST /api/orders [browser]`, `POST /api/orders [node, 3 ms]`. */
+export declare function phaseTitle(trace: Trace, phase: TracePhase): string;
+export declare const functionName: (f: Pick<FunctionHit, 'name'>) => string;
+/** A problem message as one line of at most `max` characters, with where it happened. */
+export declare function problemText(p: TraceProblem, max?: number): string;
+/** Errors (thrown, console.error, uncaught) in the order they happened, dropped ones counted. */
+export declare function errorsOf(trace: Trace): {
+    list: TraceProblem[];
+    total: number;
+};
+/**
+ * Failed requests (D-121): status 400 and up from the browser or the backend, and network
+ * errors, once each by method, path and status (or failure).
+ */
+export declare function failedRequestsOf(trace: Trace): string[];
+/** The summary's problem lines (design section 8): counts and the first message, when any. */
+export declare function problemLines(trace: Trace): string[];
+/** `checkout 21-33 ×1 not run: 29`. */
+export declare function functionLine(f: FunctionHit): string;
+/**
+ * The default trace text (design section 6.1, D-116): header lines, then one block per phase with
+ * its files and their functions in line order, cut to 16,000 characters by `fit()`.
+ * `extraHeader` goes after the first line (run_action's action, page and warning lines).
+ */
+export declare function summarizeTrace(trace: Trace, extraHeader?: readonly string[]): string;
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.js

@@ -0,0 +1,185 @@
+import { fit } from './budget.js';
+const MAX_REQUEST_LINES = 20;
+/** Sorted line numbers as ranges: [1,2,3,7] → "1-3, 7". */
+export function numberRanges(lines) {
+    const sorted = [...new Set(lines)].sort((a, b) => a - b);
+    const parts = [];
+    let start;
+    let prev;
+    for (const l of sorted) {
+        if (start === undefined)
+            start = l;
+        else if (prev !== undefined && l !== prev + 1) {
+            parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+            start = l;
+        }
+        prev = l;
+    }
+    if (start !== undefined && prev !== undefined)
+        parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+    return parts.join(', ');
+}
+export const requestLine = (r) => `${r.method} ${r.path}${r.status ? ` → ${r.status}` : ''} (${r.collector}, ${Math.round(r.durationMs)} ms${r.overlapped ? ', overlapped with another request' : ''})`;
+/** The title of one phase: `before POST /api/orders [browser]`, `POST /api/orders [node, 3 ms]`. */
+export function phaseTitle(trace, phase) {
+    const r = phase.request !== undefined ? trace.requests[phase.request] : undefined;
+    switch (phase.kind) {
+        case 'before-request':
+            return r ? `before ${r.method} ${r.path} [browser]` : 'before a request [browser]';
+        case 'backend':
+            return r
+                ? `${r.method} ${r.path}${r.status ? ` → ${r.status}` : ''} [${r.collector}, ${Math.round(r.durationMs)} ms]`
+                : 'a request [backend]';
+        case 'after-response':
+            return 'after the response [browser]';
+        case 'browser':
+            return 'in the browser [browser]';
+    }
+}
+export const functionName = (f) => f.name || '(anonymous)';
+const ERROR_KINDS = new Set(['exception', 'console-error', 'uncaught']);
+/** A problem message as one line of at most `max` characters, with where it happened. */
+export function problemText(p, max = 200) {
+    const first = p.message.split('\n')[0]?.trim() ?? '';
+    const where = p.path ? ` at ${p.path}${p.line ? `:${p.line}` : ''}` : '';
+    const text = `${first}${where}`;
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+/** Errors (thrown, console.error, uncaught) in the order they happened, dropped ones counted. */
+export function errorsOf(trace) {
+    const list = (trace.problems ?? []).filter((p) => ERROR_KINDS.has(p.kind)).sort((a, b) => a.at - b.at);
+    return { list, total: list.length + (trace.problemsDropped ?? 0) };
+}
+/**
+ * Failed requests (D-121): status 400 and up from the browser or the backend, and network
+ * errors, once each by method, path and status (or failure).
+ */
+export function failedRequestsOf(trace) {
+    const seen = new Map();
+    for (const p of [...(trace.problems ?? [])].sort((a, b) => a.at - b.at)) {
+        if (p.kind !== 'request-failed' || !p.request)
+            continue;
+        const r = p.request;
+        const key = `${r.method} ${r.path} ${r.status ?? r.failure ?? ''}`;
+        if (!seen.has(key))
+            seen.set(key, r.status ? `${r.method} ${r.path} → ${r.status}` : `${r.method} ${r.path} (${r.failure ?? 'failed'})`);
+    }
+    for (const r of trace.requests) {
+        if (r.status === undefined || r.status < 400)
+            continue;
+        const key = `${r.method} ${r.path} ${r.status}`;
+        if (!seen.has(key))
+            seen.set(key, `${r.method} ${r.path} → ${r.status}`);
+    }
+    return [...seen.values()];
+}
+/** The summary's problem lines (design section 8): counts and the first message, when any. */
+export function problemLines(trace) {
+    const out = [];
+    const errors = errorsOf(trace);
+    const first = errors.list[0];
+    if (errors.total > 0)
+        out.push(`errors: ${errors.total}${first ? ` (first: ${problemText(first)})` : ''}`);
+    const failed = failedRequestsOf(trace);
+    if (failed.length > 0)
+        out.push(`failed requests: ${failed.length} (first: ${failed[0]})`);
+    return out;
+}
+/** `checkout 21-33 ×1 not run: 29`. */
+export function functionLine(f) {
+    const range = f.startLine === f.endLine ? `${f.startLine}` : `${f.startLine}-${f.endLine}`;
+    const calls = f.count > 0 ? `×${f.count}` : 'resumed';
+    const notRun = f.notRun?.length ? ` not run: ${numberRanges(f.notRun)}` : '';
+    return `${functionName(f)} ${range} ${calls}${notRun}`;
+}
+const litRanges = (f) => numberRanges(f.lines.map((l) => l.line));
+/**
+ * The default trace text (design section 6.1, D-116): header lines, then one block per phase with
+ * its files and their functions in line order, cut to 16,000 characters by `fit()`.
+ * `extraHeader` goes after the first line (run_action's action, page and warning lines).
+ */
+export function summarizeTrace(trace, extraHeader = []) {
+    const header = [`Trace ${trace.id}: ${trace.label}`, ...extraHeader];
+    for (const r of trace.requests.slice(0, MAX_REQUEST_LINES))
+        header.push(`request: ${requestLine(r)}`);
+    if (trace.requests.length > MAX_REQUEST_LINES)
+        header.push(`+${trace.requests.length - MAX_REQUEST_LINES} more requests`);
+    header.push(...problemLines(trace));
+    if (trace.files.length === 0)
+        header.push('no workspace code ran');
+    header.push('');
+    const fileOf = new Map(trace.files.map((f) => [f.path, f]));
+    const phases = trace.phases ?? [];
+    const sections = phases.map((p) => ({ title: phaseTitle(trace, p), files: [] }));
+    const byPhase = new Map();
+    for (const fn of trace.functions ?? []) {
+        let files = byPhase.get(fn.phase);
+        if (!files) {
+            files = new Map();
+            byPhase.set(fn.phase, files);
+        }
+        files.set(fn.path, [...(files.get(fn.path) ?? []), fn]);
+    }
+    const placed = new Set();
+    const order = (paths) => [...paths].sort((a, b) => {
+        const fa = fileOf.get(a);
+        const fb = fileOf.get(b);
+        const bg = Number(Boolean(fa?.background)) - Number(Boolean(fb?.background));
+        return bg || (fa?.firstSeenAt ?? 0) - (fb?.firstSeenAt ?? 0) || a.localeCompare(b);
+    });
+    for (const [i, files] of byPhase) {
+        const section = sections[i];
+        if (!section)
+            continue;
+        for (const path of order(files.keys())) {
+            const fns = (files.get(path) ?? []).sort((a, b) => a.startLine - b.startLine || b.endLine - a.endLine);
+            const bg = fileOf.get(path)?.background ? ' (background)' : '';
+            section.files.push({
+                path,
+                lines: [`  ${path}${bg}`, ...fns.map((f) => `    ${functionLine(f)}`)],
+                functions: fns.length,
+            });
+            placed.add(path);
+        }
+    }
+    // Files with no function list (Python lines, or code outside any function): by line range, in
+    // the phase their collector belongs to, else in a last section.
+    const rest = order(trace.files.filter((f) => !placed.has(f.path)).map((f) => f.path));
+    let other;
+    for (const path of rest) {
+        const f = fileOf.get(path);
+        const i = phases.findIndex((p) => f.collector === 'browser'
+            ? p.kind === 'browser' || p.kind === 'after-response'
+            : p.kind === 'backend' &&
+                p.request !== undefined &&
+                trace.requests[p.request]?.collector === f.collector);
+        const block = {
+            path,
+            lines: [`  ${path} [${f.collector}] lines ${litRanges(f)}${f.background ? ' (background)' : ''}`],
+            functions: 0,
+        };
+        const section = i >= 0 ? sections[i] : undefined;
+        if (section)
+            section.files.push(block);
+        else {
+            if (!other) {
+                other = { title: phases.length ? 'other files' : 'files', files: [] };
+                sections.push(other);
+            }
+            other.files.push(block);
+        }
+    }
+    const hidden = trace.dropped.filter((d) => d.count > 0);
+    const footer = hidden.length ? [`hidden: ${hidden.map((d) => `${d.count} ${d.reason}`).join(', ')}`] : [];
+    return fit({
+        traceId: trace.id,
+        header,
+        sections,
+        footer,
+        rank: (path) => {
+            const f = fileOf.get(path);
+            return { background: Boolean(f?.background), hits: f ? f.lines.reduce((n, l) => n + l.count, 0) : 0 };
+        },
+    });
+}
+//# sourceMappingURL=summary.js.map

package/dist/texts.d.ts

@@ -0,0 +1,10 @@
+/** The server's `instructions`: what Lightpath records, when to call it, the fix loop, the cap. */
+export declare const INSTRUCTIONS = "Lightpath records which source lines actually ran, in the browser and on the Node server, for each action in the user's running app. It uses real runtime coverage, not static analysis. Use it first when the user reports a bug they see in the app: reproduce it with run_action before searching files, one step per call (the page, sign-in and data stay between calls). Also use it when asked which code handles a button, page or request, or whether a fix changed what runs. run_action clicks or presses a key in the app and returns that action's trace in one call; run_request does the same for one HTTP request, with no browser; find_code_for_action returns the latest trace for a label without acting. Every result is capped at about 4,000 tokens: follow its 'not shown' line to drill down with get_trace. To check a fix, call run_action before and after it, then diff_traces with both trace ids.";
+export declare const DESCRIPTIONS: {
+    readonly find_code_for_action: 'Find the files, functions and lines that ran, frontend and backend, the last time an action was done in the app. Use it before searching files when asked which code handles a button or feature.';
+    readonly get_trace: "Show the executed code of one recorded action, one file or function at a time, with lines that did not run marked, paged. Use it after a 'not shown' line, or to read which branches ran.";
+    readonly list_traces: 'List recent recorded actions, newest first, with trace ids and file counts. Use it to find ids for get_trace or diff_traces.';
+    readonly diff_traces: 'Compare two traces of the same action, before and after a code change, at function level: functions and branches that ran in only one, and changed call counts. Use it to verify a fix.';
+    readonly run_request: "Send one HTTP request to the user's running app on localhost and return the backend files, functions and lines it ran, with its status. No browser needed: use it for APIs and backend-only apps, or to rerun a request after a fix.";
+};
+//# sourceMappingURL=texts.d.ts.map

package/dist/texts.js

@@ -0,0 +1,13 @@
+// The texts of docs/design/agent-loop.md section 3 (D-119), with build 5's run_request clause and
+// shorter descriptions so six tools fit in tools/list (D-129). Tests check the limits:
+// instructions under 1,000 characters, each description under 300, tools/list at most 4,000.
+/** The server's `instructions`: what Lightpath records, when to call it, the fix loop, the cap. */
+export const INSTRUCTIONS = "Lightpath records which source lines actually ran, in the browser and on the Node server, for each action in the user's running app. It uses real runtime coverage, not static analysis. Use it first when the user reports a bug they see in the app: reproduce it with run_action before searching files, one step per call (the page, sign-in and data stay between calls). Also use it when asked which code handles a button, page or request, or whether a fix changed what runs. run_action clicks or presses a key in the app and returns that action's trace in one call; run_request does the same for one HTTP request, with no browser; find_code_for_action returns the latest trace for a label without acting. Every result is capped at about 4,000 tokens: follow its 'not shown' line to drill down with get_trace. To check a fix, call run_action before and after it, then diff_traces with both trace ids.";
+export const DESCRIPTIONS = {
+    find_code_for_action: 'Find the files, functions and lines that ran, frontend and backend, the last time an action was done in the app. Use it before searching files when asked which code handles a button or feature.',
+    get_trace: "Show the executed code of one recorded action, one file or function at a time, with lines that did not run marked, paged. Use it after a 'not shown' line, or to read which branches ran.",
+    list_traces: 'List recent recorded actions, newest first, with trace ids and file counts. Use it to find ids for get_trace or diff_traces.',
+    diff_traces: 'Compare two traces of the same action, before and after a code change, at function level: functions and branches that ran in only one, and changed call counts. Use it to verify a fix.',
+    run_request: "Send one HTTP request to the user's running app on localhost and return the backend files, functions and lines it ran, with its status. No browser needed: use it for APIs and backend-only apps, or to rerun a request after a fix.",
+};
+//# sourceMappingURL=texts.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightpath-dev/mcp",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "MCP server that lets coding agents ask which code ran for an action in your app",
   "keywords": [
     "mcp",
@@ -36,10 +36,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@lightpath-dev/protocol": "0.0.1",
+    "@lightpath-dev/protocol": "0.1.0",
     "@modelcontextprotocol/sdk": "1.32.2",
     "zod": "4.6.7"
   },
+  "devDependencies": {
+    "@lightpath-dev/daemon": "0.1.0"
+  },
   "scripts": {
     "test": "vitest run",
     "typecheck": "tsc -p test"