@lightpath-dev/cli 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @lightpath-dev/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@lightpath-dev/cli?label=npm&color=cb3837)](https://www.npmjs.com/package/@lightpath-dev/cli)
+[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/lightpath-dev.lightpath-vscode?label=VS%20Code&color=007acc)](https://marketplace.visualstudio.com/items?itemName=lightpath-dev.lightpath-vscode)
+[![CI](https://github.com/Unknown-333/Lightpath/actions/workflows/ci.yml/badge.svg)](https://github.com/Unknown-333/Lightpath/actions/workflows/ci.yml)
+
+**Click anything in your running app and see the exact code it ran, frontend and backend, line by line.**
+
+No code changes, no test suite, no tracing setup.
+
+![Clicking Add to cart and Checkout in the example shop lights up Cart.tsx and the order route in VS Code](https://raw.githubusercontent.com/Unknown-333/Lightpath/main/docs/media/demo.gif)
+
+## Quick start
+
+Requires Node.js 22.12+ and Chrome or Edge.
+
+```sh
+npx @lightpath-dev/cli dev -- npm run dev
+```
+
+Lightpath starts your dev command, finds your app's URL, and opens the app in a browser. Click something, and the code path prints in your terminal:
+
+```
+◆ button: Checkout 335 ms
+  → POST /api/orders 201
+  ├─ src/api.ts :25-32, 35-36
+  ├─ src/App.tsx :6-8, 10, 12, 24-41, 43 ×6
+  ├─ src/Cart.tsx :11-14, 16-19, 21-28, 30-33, 35-44, 46-48, 50 ×4
+  ├─ src/money.ts :3-5 ×9
+  ├─ server/db.ts :26-28, 30-38 ×3
+  ├─ server/routes/orders.ts :11-14, 19-21, 25, 29, 31-33, 38-40
+  ├─ server/services/payment.ts :6-7, 10-12
+  └─ server/services/pricing.ts :12-19, 21-22, 26-33
+```
+
+To see the lines light up in your editor, add the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=lightpath-dev.lightpath-vscode):
+
+```sh
+code --install-extension lightpath-dev.lightpath-vscode
+```
+
+To let your coding agent ask "which code handles Checkout?", add the MCP server. For Claude Code:
+
+```sh
+claude mcp add lightpath -- npx -y @lightpath-dev/cli mcp
+```
+
+Setup for Cursor, VS Code and Kiro is in [the main README](https://github.com/Unknown-333/Lightpath#ask-your-coding-agent).
+
+## Commands
+
+| Command            | What it does                                             |
+| ------------------ | -------------------------------------------------------- |
+| `lightpath dev`    | Runs your dev command with Lightpath and opens your app  |
+| `lightpath mcp`    | MCP server over stdio, so coding agents can ask what ran |
+| `lightpath doctor` | Checks Node, the browser, the agent and your config file |
+
+Everything stays on your machine: the daemon listens on `127.0.0.1` only and needs a token.
+
+## More
+
+- [Config file](https://github.com/Unknown-333/Lightpath#config-file): save your flags and hide generated code.
+- [How it works](https://github.com/Unknown-333/Lightpath#how-it-works) and [performance](https://github.com/Unknown-333/Lightpath#performance).
+- [Known limits](https://github.com/Unknown-333/Lightpath#known-limits) and [real apps it was tested on](https://github.com/Unknown-333/Lightpath#tested-on-real-apps).
+- [Issues](https://github.com/Unknown-333/Lightpath/issues) and the [changelog](https://github.com/Unknown-333/Lightpath/blob/main/CHANGELOG.md).
+
+MIT licensed.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from './main.js';
+main(process.argv).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`lightpath: ${err.stack ?? err}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const CONFIG_FILE = "lightpath.config.json";
+/**
+ * `lightpath.config.json` (docs/ARCHITECTURE.md section 9.2). Every key is optional and a flag on
+ * the command line wins over it. Unknown keys are errors, so a typo doesn't pass silently.
+ */
+export declare const LightpathConfig: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    command: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    url: z.ZodOptional<z.ZodString>;
+    webRoot: z.ZodOptional<z.ZodString>;
+    backend: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    roots: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    settleMs: z.ZodOptional<z.ZodNumber>;
+    maxSettleMs: z.ZodOptional<z.ZodNumber>;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type LightpathConfig = z.infer<typeof LightpathConfig>;
+export interface LoadedConfig {
+    path: string;
+    config: LightpathConfig;
+}
+export declare class ConfigError extends Error {
+}
+/**
+ * Reads `lightpath.config.json` from `dir` (or `file` when given). Returns undefined when there is
+ * none; throws ConfigError with every problem when it doesn't parse or validate. Relative paths in
+ * `webRoot` and `roots` become absolute against the file's folder.
+ */
+export declare function loadConfig(dir: string, file?: string): Promise<LoadedConfig | undefined>;
+/** JSON Schema for editors, from the same definition. A test keeps lightpath.config.schema.json equal to it. */
+export declare function configJsonSchema(): unknown;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,86 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+export const CONFIG_FILE = 'lightpath.config.json';
+const origin = z.string().refine((s) => {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'http:' || u.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}, { message: 'must be an http(s) origin, like http://localhost:3001' });
+/**
+ * `lightpath.config.json` (docs/ARCHITECTURE.md section 9.2). Every key is optional and a flag on
+ * the command line wins over it. Unknown keys are errors, so a typo doesn't pass silently.
+ */
+export const LightpathConfig = z.strictObject({
+    $schema: z.string().optional(),
+    command: z
+        .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+        .optional()
+        .describe('Dev command to run when none is given after --. A string runs in a shell.'),
+    url: origin.optional().describe('App URL; detected from the command output when omitted'),
+    webRoot: z.string().min(1).optional().describe('Folder the dev server serves from, relative to this file'),
+    backend: z.array(origin).optional().describe('Remote backend origins to tag with the trace header'),
+    roots: z.array(z.string().min(1)).min(1).optional().describe('Workspace roots, relative to this file'),
+    ignore: z
+        .array(z.string())
+        .optional()
+        .describe('Globs for workspace files to leave out of traces, like "src/generated/**"'),
+    settleMs: z.number().int().min(50).max(10_000).optional().describe('Quiet time that ends a click (ms)'),
+    maxSettleMs: z.number().int().min(500).max(60_000).optional().describe('Longest a click can last (ms)'),
+    browser: z.boolean().optional().describe('false: trace backend requests only'),
+    headless: z.boolean().optional().describe('Run the browser without a window'),
+});
+export class ConfigError extends Error {
+}
+/**
+ * Reads `lightpath.config.json` from `dir` (or `file` when given). Returns undefined when there is
+ * none; throws ConfigError with every problem when it doesn't parse or validate. Relative paths in
+ * `webRoot` and `roots` become absolute against the file's folder.
+ */
+export async function loadConfig(dir, file) {
+    const path = resolve(dir, file ?? CONFIG_FILE);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT' && file === undefined)
+            return undefined;
+        throw new ConfigError(`can't read ${path}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw.replace(/^\uFEFF/, ''));
+    }
+    catch (err) {
+        throw new ConfigError(`${path} isn't valid JSON: ${err.message}`);
+    }
+    const parsed = LightpathConfig.safeParse(json);
+    if (!parsed.success) {
+        const problems = parsed.error.issues.map((i) => {
+            const where = i.path.length ? i.path.join('.') : '(top level)';
+            return `  ${where}: ${i.message}`;
+        });
+        throw new ConfigError(`${path} has problems:\n${problems.join('\n')}`);
+    }
+    const base = dirname(path);
+    const config = { ...parsed.data };
+    if (config.webRoot)
+        config.webRoot = resolve(base, config.webRoot);
+    if (config.roots)
+        config.roots = config.roots.map((r) => resolve(base, r));
+    if (config.backend)
+        config.backend = config.backend.map((b) => new URL(b).origin);
+    if (config.url)
+        config.url = new URL(config.url).href;
+    return { path, config };
+}
+/** JSON Schema for editors, from the same definition. A test keeps lightpath.config.schema.json equal to it. */
+export function configJsonSchema() {
+    return z.toJSONSchema(LightpathConfig, { target: 'draft-7' });
+}
+//# sourceMappingURL=config.js.map

package/dist/detect.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds the first local dev-server URL in a chunk of output, e.g. Vite's
+ * `➜  Local:   http://localhost:5173/`. Returns it without a trailing slash.
+ */
+export declare function findLocalUrl(output: string): string | undefined;
+/** Line-buffers a stream of chunks and reports the first local URL seen. */
+export declare class UrlWatcher {
+    #private;
+    get found(): string | undefined;
+    push(chunk: string): string | undefined;
+}
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.js

@@ -0,0 +1,38 @@
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape sequences is the point.
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+const LOCAL_URL = /\bhttps?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d{2,5}(?:\/[^\s'")\]]*)?/;
+/**
+ * Finds the first local dev-server URL in a chunk of output, e.g. Vite's
+ * `➜  Local:   http://localhost:5173/`. Returns it without a trailing slash.
+ */
+export function findLocalUrl(output) {
+    const match = LOCAL_URL.exec(output.replace(ANSI, ''));
+    return match?.[0].replace(/\/$/, '');
+}
+/** Line-buffers a stream of chunks and reports the first local URL seen. */
+export class UrlWatcher {
+    #buffer = '';
+    #found;
+    get found() {
+        return this.#found;
+    }
+    push(chunk) {
+        if (this.#found)
+            return undefined;
+        this.#buffer += chunk;
+        const lines = this.#buffer.split(/\r?\n/);
+        this.#buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            const url = findLocalUrl(line);
+            if (url) {
+                this.#found = url;
+                return url;
+            }
+        }
+        // Keep memory bounded if the child prints a huge line without a newline.
+        if (this.#buffer.length > 10_000)
+            this.#buffer = this.#buffer.slice(-1000);
+        return undefined;
+    }
+}
+//# sourceMappingURL=detect.js.map

package/dist/dev.d.ts

@@ -0,0 +1,25 @@
+export interface DevOptions {
+    /**
+     * The user's dev command and its arguments, e.g. ['npm', 'run', 'dev'], or one string that runs in
+     * a shell (the `command` key in lightpath.config.json).
+     */
+    command: string[] | string;
+    /** App URL; detected from the command's output when omitted. */
+    url?: string | undefined;
+    /** Directory Vite (or another dev server) serves from. Defaults to cwd. */
+    webRoot?: string | undefined;
+    /** Extra origins to tag with the trace header, besides the app's own. */
+    backend?: string[] | undefined;
+    roots?: string[] | undefined;
+    /** Globs for workspace files to leave out of traces. */
+    ignore?: string[] | undefined;
+    settleMs?: number | undefined;
+    maxSettleMs?: number | undefined;
+    browser?: boolean | undefined;
+    headless?: boolean | undefined;
+    debug?: boolean | undefined;
+    cwd?: string | undefined;
+}
+/** `lightpath dev -- <command>` (docs/ARCHITECTURE.md section 9.2). */
+export declare function dev(options: DevOptions): Promise<number>;
+//# sourceMappingURL=dev.d.ts.map

package/dist/dev.js

@@ -0,0 +1,115 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { BrowserCollector } from '@lightpath-dev/browser';
+import { startDaemon } from '@lightpath-dev/daemon';
+import { registerUrl } from '@lightpath-dev/node-agent';
+import pc from 'picocolors';
+import { UrlWatcher } from './detect.js';
+import { agentEnv, nodeVersionProblem, toShellCommand } from './env.js';
+import { formatTrace } from './format.js';
+const say = (msg) => process.stderr.write(`${pc.magenta('lightpath')} ${msg}\n`);
+/** `lightpath dev -- <command>` (docs/ARCHITECTURE.md section 9.2). */
+export async function dev(options) {
+    const problem = nodeVersionProblem(process.version);
+    if (problem) {
+        say(pc.red(problem));
+        return 1;
+    }
+    const shellLine = typeof options.command === 'string' ? options.command.trim() : undefined;
+    const [cmd, ...args] = typeof options.command === 'string' ? [] : options.command;
+    if (!cmd && !shellLine) {
+        say(pc.red('missing command. Usage: lightpath dev -- npm run dev (or set "command" in lightpath.config.json)'));
+        return 1;
+    }
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const roots = (options.roots?.length ? options.roots : [cwd]).map((r) => resolve(cwd, r));
+    const daemon = await startDaemon({
+        workspaceRoots: roots,
+        ...(options.ignore?.length ? { ignore: options.ignore } : {}),
+        ...(options.debug ? { log: say } : {}),
+    });
+    say(`daemon on ${pc.dim(daemon.url)}`);
+    const unsubscribe = daemon.store.subscribe((trace) => {
+        if (trace.endedAt !== undefined)
+            process.stdout.write(`\n${formatTrace(trace)}\n`);
+    });
+    const env = agentEnv(process.env, {
+        daemonUrl: daemon.url,
+        token: daemon.token,
+        roots,
+        registerUrl,
+        debug: options.debug,
+    });
+    const spawnOptions = { cwd, env, stdio: ['inherit', 'pipe', 'pipe'] };
+    // Windows needs a shell so `npm`, `pnpm`, and other `.cmd` shims resolve.
+    const child = shellLine
+        ? spawn(shellLine, { ...spawnOptions, shell: true })
+        : process.platform === 'win32'
+            ? spawn(toShellCommand([cmd, ...args]), { ...spawnOptions, shell: true })
+            : spawn(cmd, args, spawnOptions);
+    let collector;
+    const openBrowser = async (url) => {
+        if (options.browser === false || collector)
+            return;
+        const origin = new URL(url).origin;
+        daemon.correlator.addDevServer(origin, resolve(cwd, options.webRoot ?? '.'));
+        collector = new BrowserCollector({
+            url,
+            backendOrigins: [origin, ...(options.backend ?? [])],
+            ...(options.settleMs !== undefined ? { settleMs: options.settleMs } : {}),
+            ...(options.maxSettleMs !== undefined ? { maxSettleMs: options.maxSettleMs } : {}),
+            ...(options.headless !== undefined ? { headless: options.headless } : {}),
+            send: (m) => ingestLocal(daemon, m),
+            notice: (m) => say(pc.yellow(m)),
+            ...(options.debug ? { log: say } : {}),
+        });
+        try {
+            await collector.start();
+            say(`watching ${pc.cyan(url)}. Click anything in the browser window.`);
+        }
+        catch (err) {
+            say(pc.red(err.message));
+        }
+    };
+    const watcher = new UrlWatcher();
+    const pipe = (stream, out) => {
+        stream?.on('data', (chunk) => {
+            out.write(chunk);
+            const url = options.url ? undefined : watcher.push(chunk.toString());
+            if (url)
+                void openBrowser(url);
+        });
+    };
+    pipe(child.stdout, process.stdout);
+    pipe(child.stderr, process.stderr);
+    if (options.url)
+        void openBrowser(options.url);
+    const code = await waitForExit(child);
+    unsubscribe();
+    await collector?.stop();
+    await daemon.close();
+    return code;
+}
+/** The collector runs in this process, so its messages skip HTTP and go straight to the correlator. */
+function ingestLocal(daemon, message) {
+    daemon.correlator.ingest('browser', message);
+}
+function waitForExit(child) {
+    return new Promise((resolveExit) => {
+        const forward = (signal) => () => child.kill(signal);
+        const onInt = forward('SIGINT');
+        const onTerm = forward('SIGTERM');
+        process.on('SIGINT', onInt);
+        process.on('SIGTERM', onTerm);
+        child.on('exit', (code, signal) => {
+            process.off('SIGINT', onInt);
+            process.off('SIGTERM', onTerm);
+            resolveExit(code ?? (signal ? 130 : 0));
+        });
+        child.on('error', (err) => {
+            say(pc.red(`could not start command: ${err.message}`));
+            resolveExit(127);
+        });
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/doctor.d.ts

@@ -0,0 +1,3 @@
+/** `lightpath doctor`: checks the environment and explains what to fix. */
+export declare function doctor(cwd: string, configFile?: string): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { launchBrowser } from '@lightpath-dev/browser';
+import { findDiscovery } from '@lightpath-dev/daemon';
+import { registerUrl } from '@lightpath-dev/node-agent';
+import { DISCOVERY_FILE } from '@lightpath-dev/protocol';
+import pc from 'picocolors';
+import { CONFIG_FILE, ConfigError, loadConfig } from './config.js';
+import { nodeVersionProblem } from './env.js';
+/** `lightpath doctor`: checks the environment and explains what to fix. */
+export async function doctor(cwd, configFile) {
+    const checks = [
+        {
+            name: 'Node.js version',
+            run: async () => {
+                const problem = nodeVersionProblem(process.version);
+                return { ok: !problem, detail: problem ?? process.version };
+            },
+        },
+        {
+            name: 'Chromium-based browser',
+            run: async () => {
+                try {
+                    const browser = await launchBrowser({ headless: true });
+                    const version = browser.version();
+                    await browser.close();
+                    return { ok: true, detail: version };
+                }
+                catch (err) {
+                    return { ok: false, detail: err.message };
+                }
+            },
+        },
+        {
+            name: 'Node agent',
+            run: async () => {
+                const path = fileURLToPath(registerUrl);
+                return existsSync(path)
+                    ? { ok: true, detail: path }
+                    : { ok: false, detail: `missing ${path}; reinstall @lightpath-dev/cli` };
+            },
+        },
+        {
+            name: 'Config file',
+            run: async () => {
+                try {
+                    const loaded = await loadConfig(cwd, configFile);
+                    if (!loaded)
+                        return { ok: true, detail: `none (optional; see ${CONFIG_FILE} in the README)` };
+                    const keys = Object.keys(loaded.config).filter((k) => k !== '$schema');
+                    return { ok: true, detail: `${loaded.path} (${keys.join(', ') || 'empty'})` };
+                }
+                catch (err) {
+                    if (err instanceof ConfigError)
+                        return { ok: false, detail: err.message };
+                    throw err;
+                }
+            },
+        },
+        {
+            name: 'Daemon for this workspace',
+            run: async () => {
+                // Look where `lightpath mcp` looks: here, then each parent (D-102).
+                const found = await findDiscovery(cwd);
+                if (!found)
+                    return { ok: true, detail: 'not running (start it with lightpath dev)' };
+                const { root, info } = found;
+                const where = root === resolve(cwd) ? '' : ` (started in ${root})`;
+                try {
+                    const res = await fetch(`http://127.0.0.1:${info.port}/v1/health`);
+                    return { ok: res.ok, detail: `running on port ${info.port}, pid ${info.pid}${where}` };
+                }
+                catch {
+                    return {
+                        ok: false,
+                        detail: `stale ${join(root, DISCOVERY_FILE)} (port ${info.port} not answering); delete it`,
+                    };
+                }
+            },
+        },
+    ];
+    let failed = 0;
+    for (const check of checks) {
+        const { ok, detail } = await check.run();
+        if (!ok)
+            failed++;
+        process.stdout.write(`${ok ? pc.green('✓') : pc.red('✗')} ${check.name}: ${detail}\n`);
+    }
+    return failed === 0 ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Adds `--require="<path>"` to NODE_OPTIONS without dropping the user's own options (ARCHITECTURE 10).
+ *
+ * `--require`, not `--import` (D-085): any `--import` makes Node run the main file through its ES
+ * module loader, which skips `require` hooks, so `ts-node` (and other tools that call
+ * `Module.runMain`) failed to start. Node 22.12+ can `--require` the agent's ES module file.
+ * NODE_OPTIONS eats backslashes inside quotes on Windows (measured), so the path uses forward
+ * slashes; quoting handles spaces.
+ */
+export declare function withRequire(existing: string | undefined, registerUrl: string): string;
+export interface AgentEnvInput {
+    daemonUrl: string;
+    token: string;
+    roots: string[];
+    registerUrl: string;
+    skip?: string | undefined;
+    debug?: boolean | undefined;
+}
+/** Environment for the user's dev command, so every Node process it starts loads the agent. */
+export declare function agentEnv(base: NodeJS.ProcessEnv, input: AgentEnvInput): NodeJS.ProcessEnv;
+/** Node versions the agent supports: 22.12+ (ADR 0002). */
+export declare function nodeVersionProblem(version: string): string | undefined;
+/**
+ * Joins the user's command for `spawn(line, { shell: true })` on Windows, where `npm` and other
+ * `.cmd` shims need a shell. Node 24 deprecates passing an argument array with `shell: true`
+ * (DEP0190), so arguments are quoted here. The input is the user's own command line.
+ */
+export declare function toShellCommand(argv: readonly string[]): string;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -0,0 +1,47 @@
+import { fileURLToPath } from 'node:url';
+import { AgentEnv } from '@lightpath-dev/protocol';
+/**
+ * Adds `--require="<path>"` to NODE_OPTIONS without dropping the user's own options (ARCHITECTURE 10).
+ *
+ * `--require`, not `--import` (D-085): any `--import` makes Node run the main file through its ES
+ * module loader, which skips `require` hooks, so `ts-node` (and other tools that call
+ * `Module.runMain`) failed to start. Node 22.12+ can `--require` the agent's ES module file.
+ * NODE_OPTIONS eats backslashes inside quotes on Windows (measured), so the path uses forward
+ * slashes; quoting handles spaces.
+ */
+export function withRequire(existing, registerUrl) {
+    const path = fileURLToPath(registerUrl).replace(/\\/g, '/');
+    const flag = `--require="${path}"`;
+    const current = existing?.trim() ?? '';
+    if (current.includes(path))
+        return current;
+    return current ? `${current} ${flag}` : flag;
+}
+/** Environment for the user's dev command, so every Node process it starts loads the agent. */
+export function agentEnv(base, input) {
+    return {
+        ...base,
+        NODE_OPTIONS: withRequire(base.NODE_OPTIONS, input.registerUrl),
+        [AgentEnv.url]: input.daemonUrl,
+        [AgentEnv.token]: input.token,
+        [AgentEnv.roots]: input.roots.join(','),
+        ...(input.skip ? { [AgentEnv.skip]: input.skip } : {}),
+        ...(input.debug ? { [AgentEnv.debug]: '1' } : {}),
+    };
+}
+/** Node versions the agent supports: 22.12+ (ADR 0002). */
+export function nodeVersionProblem(version) {
+    const [major = 0, minor = 0] = version.replace(/^v/, '').split('.').map(Number);
+    if (major > 22 || (major === 22 && minor >= 12))
+        return undefined;
+    return `Lightpath needs Node.js 22.12 or newer; this is ${version}.`;
+}
+/**
+ * Joins the user's command for `spawn(line, { shell: true })` on Windows, where `npm` and other
+ * `.cmd` shims need a shell. Node 24 deprecates passing an argument array with `shell: true`
+ * (DEP0190), so arguments are quoted here. The input is the user's own command line.
+ */
+export function toShellCommand(argv) {
+    return argv.map((a) => (/^[\w./:=@+-]+$/.test(a) ? a : `"${a.replace(/"/g, '""')}"`)).join(' ');
+}
+//# sourceMappingURL=env.js.map

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+import type { Trace } from '@lightpath-dev/protocol';
+/** Prints one trace as a tree of files and line ranges, for `lightpath dev` (ARCHITECTURE 9.2). */
+export declare function formatTrace(trace: Trace, color?: boolean): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,30 @@
+import { lineRanges } from '@lightpath-dev/mcp';
+import pc from 'picocolors';
+const COLLECTOR_COLOR = { browser: pc.cyan, node: pc.green, python: pc.yellow };
+/** Prints one trace as a tree of files and line ranges, for `lightpath dev` (ARCHITECTURE 9.2). */
+export function formatTrace(trace, color = true) {
+    const c = color ? pc : pc.createColors(false);
+    const duration = trace.endedAt ? ` ${c.dim(`${Math.max(0, trace.endedAt - trace.startedAt)} ms`)}` : '';
+    const lines = [`${c.bold('◆')} ${c.bold(trace.label)}${duration} ${c.dim(trace.id)}`];
+    for (const r of trace.requests) {
+        const status = r.status === undefined ? '' : r.status >= 400 ? c.red(` ${r.status}`) : c.dim(` ${r.status}`);
+        lines.push(`  ${c.dim('→')} ${r.method} ${r.path}${status}${r.overlapped ? c.yellow(' (overlapped)') : ''}`);
+    }
+    // Files where only periodic code ran (timers, polling) go last and dimmed; they're rarely the answer.
+    const files = [...trace.files.filter((f) => !f.background), ...trace.files.filter((f) => f.background)];
+    files.forEach((f, i) => {
+        const branch = i === files.length - 1 ? '└─' : '├─';
+        const paint = f.background ? c.dim : color ? COLLECTOR_COLOR[f.collector] : (s) => s;
+        const hottest = Math.max(...f.lines.map((l) => l.count));
+        const hot = hottest > 1 ? c.dim(` ×${hottest}`) : '';
+        const note = f.background ? c.dim(' (background)') : '';
+        lines.push(`  ${c.dim(branch)} ${paint(f.path)} ${c.dim(`:${lineRanges(f.lines)}`)}${hot}${note}`);
+    });
+    if (trace.files.length === 0)
+        lines.push(`  ${c.dim('no workspace code ran')}`);
+    const hidden = trace.dropped.reduce((n, d) => n + d.count, 0);
+    if (hidden > 0)
+        lines.push(`  ${c.dim(`${hidden} scripts hidden (${trace.dropped.map((d) => d.reason).join(', ')})`)}`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { CONFIG_FILE, ConfigError, configJsonSchema, LightpathConfig, type LoadedConfig, loadConfig, } from './config.js';
+export { findLocalUrl, UrlWatcher } from './detect.js';
+export { type DevOptions, dev } from './dev.js';
+export { doctor } from './doctor.js';
+export { agentEnv, nodeVersionProblem, withRequire } from './env.js';
+export { formatTrace } from './format.js';
+export { main, VERSION } from './main.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,8 @@
+export { CONFIG_FILE, ConfigError, configJsonSchema, LightpathConfig, loadConfig, } from './config.js';
+export { findLocalUrl, UrlWatcher } from './detect.js';
+export { dev } from './dev.js';
+export { doctor } from './doctor.js';
+export { agentEnv, nodeVersionProblem, withRequire } from './env.js';
+export { formatTrace } from './format.js';
+export { main, VERSION } from './main.js';
+//# sourceMappingURL=index.js.map

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+/** This package's version, read from package.json (one folder up from both src/ and dist/). */
+export declare const VERSION: string;
+/** Builds the CLI. Returns the process exit code. */
+export declare function main(argv: string[]): Promise<number>;
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,88 @@
+import { readFileSync } from 'node:fs';
+import { runMcpServer } from '@lightpath-dev/mcp';
+import { cac } from 'cac';
+import { CONFIG_FILE, ConfigError, loadConfig } from './config.js';
+import { dev } from './dev.js';
+import { doctor } from './doctor.js';
+/** This package's version, read from package.json (one folder up from both src/ and dist/). */
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const list = (v) => v === undefined
+    ? undefined
+    : (Array.isArray(v) ? v : [v]).flatMap((s) => String(s).split(',')).filter(Boolean);
+/** Builds the CLI. Returns the process exit code. */
+export async function main(argv) {
+    const cli = cac('lightpath');
+    let result = Promise.resolve(0);
+    cli
+        .command('dev', 'Run your dev command with Lightpath, open your app, and print the code each click ran')
+        .usage('dev [options] -- <command...>')
+        .option('--url <url>', 'App URL (default: detected from the command output)')
+        .option('--web-root <dir>', 'Directory the dev server serves from (default: current directory)')
+        .option('--backend <origin>', 'Extra backend origin to tag with the trace header (repeatable)')
+        .option('--root <dir>', 'Workspace root to show files from (repeatable; default: current directory)')
+        .option('--ignore <glob>', 'Leave matching workspace files out of traces (repeatable)')
+        .option('--config <file>', `Config file (default: ${CONFIG_FILE} in the current directory, if any)`)
+        .option('--no-browser', "Don't open a browser; trace backend requests only")
+        .option('--headless', 'Run the browser without a window')
+        .option('--debug', 'Print Lightpath internals')
+        .example('lightpath dev -- npm run dev')
+        .example('lightpath dev --url http://localhost:5173 -- pnpm dev')
+        .example(`lightpath dev   (runs "command" from ${CONFIG_FILE})`)
+        .action((options) => {
+        result = (async () => {
+            let loaded;
+            try {
+                loaded = await loadConfig(process.cwd(), options.config);
+            }
+            catch (err) {
+                if (!(err instanceof ConfigError))
+                    throw err;
+                process.stderr.write(`lightpath: ${err.message}\n`);
+                return 1;
+            }
+            const config = loaded?.config ?? {};
+            const flagCommand = options['--'] ?? [];
+            // cac fills in browser: true for --no-browser's default, so read the flag from argv.
+            const end = argv.indexOf('--');
+            const noBrowser = (end < 0 ? argv : argv.slice(0, end)).includes('--no-browser');
+            return dev({
+                command: flagCommand.length > 0 ? flagCommand : (config.command ?? []),
+                url: options.url ?? config.url,
+                webRoot: options.webRoot ?? config.webRoot,
+                backend: list(options.backend) ?? config.backend,
+                roots: list(options.root) ?? config.roots,
+                ignore: [
+                    ...(config.ignore ?? []),
+                    ...(list(options.ignore) ?? []),
+                ],
+                settleMs: config.settleMs,
+                maxSettleMs: config.maxSettleMs,
+                browser: noBrowser ? false : config.browser,
+                headless: options.headless === true ? true : config.headless,
+                debug: options.debug,
+            });
+        })();
+    });
+    cli
+        .command('mcp', 'Run the MCP server over stdio for coding agents (reads .lightpath/daemon.json)')
+        .option('--root <dir>', 'Where to look for .lightpath/daemon.json, then in each parent (default: current directory)')
+        .action((options) => {
+        result = runMcpServer({ workspaceRoot: options.root ?? process.cwd() }).then(() => new Promise(() => { }));
+    });
+    cli
+        .command('doctor', 'Check that Lightpath can run here')
+        .option('--config <file>', `Config file to check (default: ${CONFIG_FILE})`)
+        .action((options) => {
+        result = doctor(process.cwd(), options.config);
+    });
+    cli.help();
+    cli.version(VERSION);
+    cli.parse(argv, { run: false });
+    if (!cli.matchedCommand && !cli.options.help && !cli.options.version) {
+        cli.outputHelp();
+        return cli.args.length > 0 ? 1 : 0;
+    }
+    await cli.runMatchedCommand();
+    return result;
+}
+//# sourceMappingURL=main.js.map

package/lightpath.config.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "command": {
+      "description": "Dev command to run when none is given after --. A string runs in a shell.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      ]
+    },
+    "url": {
+      "description": "App URL; detected from the command output when omitted",
+      "type": "string"
+    },
+    "webRoot": {
+      "description": "Folder the dev server serves from, relative to this file",
+      "type": "string",
+      "minLength": 1
+    },
+    "backend": {
+      "description": "Remote backend origins to tag with the trace header",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "roots": {
+      "description": "Workspace roots, relative to this file",
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "ignore": {
+      "description": "Globs for workspace files to leave out of traces, like \"src/generated/**\"",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "settleMs": {
+      "description": "Quiet time that ends a click (ms)",
+      "type": "integer",
+      "minimum": 50,
+      "maximum": 10000
+    },
+    "maxSettleMs": {
+      "description": "Longest a click can last (ms)",
+      "type": "integer",
+      "minimum": 500,
+      "maximum": 60000
+    },
+    "browser": {
+      "description": "false: trace backend requests only",
+      "type": "boolean"
+    },
+    "headless": {
+      "description": "Run the browser without a window",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@lightpath-dev/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Click anything in your running app and see which frontend and backend lines ran",
+  "keywords": [
+    "coverage",
+    "runtime",
+    "trace",
+    "debug",
+    "click",
+    "devtools",
+    "mcp"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Unknown-333/Lightpath#readme",
+  "bugs": "https://github.com/Unknown-333/Lightpath/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unknown-333/Lightpath.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "lightpath": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "lightpath.config.schema.json",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lightpath-dev/browser": "0.0.2",
+    "@lightpath-dev/daemon": "0.0.1",
+    "@lightpath-dev/mcp": "0.0.1",
+    "@lightpath-dev/node-agent": "0.0.1",
+    "@lightpath-dev/protocol": "0.0.1",
+    "cac": "7.1.0",
+    "picocolors": "1.1.1",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p test"
+  }
 }