lensmcp 1.0.0

package/index.d.ts

@@ -0,0 +1,2 @@
+export { runCli, type CliResult } from './lib/cli.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC"}

package/index.js

@@ -0,0 +1 @@
+export { runCli } from './lib/cli.js';

package/lib/cli.d.ts

@@ -0,0 +1,17 @@
+export interface CliResult {
+    exitCode: number;
+    message?: string;
+}
+interface CliContext {
+    cwd: string;
+    /** Process argv after the binary name, e.g. `["mcp"]` for `lensmcp mcp`. */
+    argv: string[];
+    /** Override env for child processes (test hooks). */
+    env?: NodeJS.ProcessEnv;
+    /** Output channel — defaults to console.log / console.error. */
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+}
+export declare function runCli(ctx: CliContext): Promise<CliResult>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAmCD,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgChE"}

package/lib/cli.js

@@ -0,0 +1,488 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const HELP = `lensmcp — CLI for LensMCP (FrontMCP-based observability for coding agents)
+
+Usage:
+  lensmcp <command> [options]
+
+Commands:
+  mcp [--cwd <dir>] [--transport stdio|http] [--port <n>]
+                       Launch the LensMCP MCP server. Default transport is
+                       stdio (set LENSMCP_TRANSPORT=http or pass --transport
+                       for HTTP on --port, default 3000).
+  dashboard [--cwd <dir>] [--port <n>]
+                       Serve a live web view of the lens (flows, signals,
+                       stories, status) on --port (default 4321). Reads the
+                       same .lensmcp/events.jsonl your agent-dev producers write.
+  install [--cwd <dir>] [--skip-format] [--register-host-config <mode>]
+                       Install LensMCP into the host Nx workspace at --cwd
+                       (current directory by default). Delegates to
+                       \`nx g @lensmcp/nx-plugin:init\`. Idempotent.
+  doctor [--cwd <dir>] [--json]
+                       Diagnose the install: Node, workspace + plugin,
+                       .mcp.json server entry, MCP bundle, per-project
+                       vite/nest wiring, agent-dev targets, and Chrome for
+                       browser capture. \`--json\` emits a machine-readable
+                       report (for the agent). Exits non-zero on errors.
+  rollout <config.json> <op> [args]
+                       Edit the gateway rollout config — add-cohort, set-weight,
+                       promote, abort, add-rule, remove-rule, status. Validated +
+                       atomic write; the prod gateway picks it up live. Run
+                       \`lensmcp rollout\` (no args) for the op list.
+  --version            Print the lensmcp version.
+  --help               Show this help.
+`;
+export async function runCli(ctx) {
+    const out = ctx.out ?? ((l) => console.log(l));
+    const err = ctx.err ?? ((l) => console.error(l));
+    const [command, ...rest] = ctx.argv;
+    if (!command || command === '--help' || command === '-h') {
+        out(HELP);
+        return { exitCode: 0 };
+    }
+    if (command === '--version' || command === '-V') {
+        out(readCliVersion());
+        return { exitCode: 0 };
+    }
+    switch (command) {
+        case 'mcp':
+            return runMcp(ctx, rest, out, err);
+        case 'dashboard':
+            return runDashboard(ctx, rest, out, err);
+        case 'install':
+            return runInstall(ctx, rest, out, err);
+        case 'doctor':
+            return runDoctor(ctx, rest, out);
+        case 'rollout':
+            return runRollout(ctx, rest, err);
+        default:
+            err(`Unknown command: ${command}`);
+            err(HELP);
+            return { exitCode: 2, message: `Unknown command: ${command}` };
+    }
+}
+// ---------- commands ----------
+function runMcp(ctx, args, _out, err) {
+    const opts = parseFlags(args, {
+        string: ['--cwd', '--transport', '--port'],
+    });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const transport = stringFlag(opts.flags['--transport']) ?? ctx.env?.['LENSMCP_TRANSPORT'] ?? 'stdio';
+    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_PORT'] ?? '3000';
+    const binPath = findMcpBinary(cwd);
+    if (!binPath) {
+        err('Could not locate the lensmcp-mcp server bundle.\n' +
+            'Looked in (in order):\n' +
+            '  • <cli-package>/bundled/main.js          (published bin)\n' +
+            '  • <workspace>/apps/lensmcp-mcp/dist/main.js  (dev build)\n' +
+            'For dev: `yarn nx build @lensmcp/lensmcp-mcp`.');
+        return { exitCode: 1 };
+    }
+    ensureLensmcpDir(cwd);
+    // Default the cross-process event file to `<cwd>/.lensmcp/events.jsonl`
+    // so the server's ingest and the host's `agent-dev` producers (which
+    // write to the same default) rendezvous with zero extra config.
+    const eventFile = ctx.env?.['LENSMCP_EVENT_FILE'] ??
+        process.env['LENSMCP_EVENT_FILE'] ??
+        join(cwd, '.lensmcp', 'events.jsonl');
+    const childEnv = {
+        ...process.env,
+        ...(ctx.env ?? {}),
+        LENSMCP_TRANSPORT: transport,
+        LENSMCP_PORT: port,
+        LENSMCP_EVENT_FILE: eventFile,
+    };
+    const result = spawnSync(process.execPath, [binPath], {
+        cwd,
+        stdio: 'inherit',
+        env: childEnv,
+    });
+    return { exitCode: result.status ?? 1 };
+}
+function runDashboard(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd', '--port'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_DASHBOARD_PORT'] ?? '4321';
+    const binPath = findServerBundle(cwd, 'dashboard.js');
+    if (!binPath) {
+        err('Could not locate the lensmcp dashboard bundle.\n' +
+            'Looked in (in order):\n' +
+            '  • <cli-package>/bundled/dashboard.js               (published bin)\n' +
+            '  • <workspace>/servers/lensmcp-mcp/dist/dashboard.js (dev build)\n' +
+            'For dev: `yarn nx build @lensmcp/lensmcp-mcp`.');
+        return { exitCode: 1 };
+    }
+    ensureLensmcpDir(cwd);
+    // Tail the same event file the host's agent-dev producers write to, so the
+    // dashboard materialises the same live resources the MCP server does.
+    const eventFile = ctx.env?.['LENSMCP_EVENT_FILE'] ??
+        process.env['LENSMCP_EVENT_FILE'] ??
+        join(cwd, '.lensmcp', 'events.jsonl');
+    out(`lensmcp dashboard → http://localhost:${port}  (reading ${eventFile})`);
+    const result = spawnSync(process.execPath, [binPath], {
+        cwd,
+        stdio: 'inherit',
+        env: {
+            ...process.env,
+            ...(ctx.env ?? {}),
+            LENSMCP_DASHBOARD_PORT: port,
+            LENSMCP_EVENT_FILE: eventFile,
+        },
+    });
+    return { exitCode: result.status ?? 1 };
+}
+function runInstall(ctx, args, out, err) {
+    const opts = parseFlags(args, {
+        string: ['--cwd', '--register-host-config'],
+        boolean: ['--skip-format', '--yes'],
+    });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    if (!existsSync(join(cwd, 'nx.json'))) {
+        err(`No nx.json found at ${cwd}.`);
+        err('Run `lensmcp install` from inside a Nx workspace.');
+        return { exitCode: 1 };
+    }
+    const nxBin = findNxBinary(cwd);
+    if (!nxBin) {
+        err('Could not find the `nx` binary in the host workspace. Install Nx first: `yarn add -D nx`.');
+        return { exitCode: 1 };
+    }
+    const nxArgs = ['g', '@lensmcp/nx-plugin:init', '--no-interactive'];
+    if (opts.flags['--skip-format'] === true)
+        nxArgs.push('--skipFormat');
+    if (opts.flags['--register-host-config']) {
+        nxArgs.push(`--registerHostConfig=${String(opts.flags['--register-host-config'])}`);
+    }
+    out(`> ${nxBin} ${nxArgs.join(' ')}`);
+    const result = spawnSync(nxBin, nxArgs, {
+        cwd,
+        stdio: 'inherit',
+        env: { ...process.env, ...(ctx.env ?? {}) },
+    });
+    return { exitCode: result.status ?? 1 };
+}
+function runDoctor(ctx, args, out) {
+    const opts = parseFlags(args, { string: ['--cwd'], boolean: ['--json'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const asJson = opts.flags['--json'] === true;
+    const checks = [];
+    checkNode(checks);
+    checkWorkspace(cwd, checks);
+    checkMcpConfig(cwd, checks);
+    checkServerBundle(cwd, checks);
+    checkRuntimeDir(cwd, checks);
+    checkProjectWiring(cwd, checks);
+    checkChrome(checks);
+    const failed = checks.some((c) => c.status === 'fail');
+    const warned = checks.some((c) => c.status === 'warn');
+    if (asJson) {
+        out(JSON.stringify({
+            ok: !failed,
+            summary: { total: checks.length, failed: checks.filter((c) => c.status === 'fail').length, warnings: checks.filter((c) => c.status === 'warn').length },
+            checks,
+        }, null, 2));
+        return { exitCode: failed ? 1 : 0 };
+    }
+    for (const c of checks) {
+        const icon = c.status === 'pass' ? '✓' : c.status === 'warn' ? '!' : '✗';
+        out(`${icon}  ${c.label}${c.detail ? ` — ${c.detail}` : ''}`);
+        if (c.status !== 'pass' && c.hint)
+            out(`     ↳ ${c.hint}`);
+    }
+    out('');
+    out(failed
+        ? 'doctor: issues found (see ✗ above).'
+        : warned
+            ? 'doctor: ok, with warnings (!).'
+            : 'doctor: all checks passed.');
+    return { exitCode: failed ? 1 : 0 };
+}
+// ---------- doctor checks ----------
+function add(checks, status, label, detail, hint) {
+    checks.push({ status, label, detail, hint });
+}
+function checkNode(checks) {
+    const major = Number(process.versions.node.split('.')[0]);
+    if (major >= 20)
+        add(checks, 'pass', `Node ${process.versions.node}`);
+    else if (major >= 18)
+        add(checks, 'warn', `Node ${process.versions.node}`, 'older than recommended', 'upgrade to Node 20+ for best results');
+    else
+        add(checks, 'fail', `Node ${process.versions.node}`, 'too old', 'LensMCP needs Node 18+ (20+ recommended)');
+}
+function checkWorkspace(cwd, checks) {
+    const nxJsonPath = join(cwd, 'nx.json');
+    if (!existsSync(nxJsonPath)) {
+        add(checks, 'fail', 'nx.json at workspace root', 'missing', 'run `lensmcp` from inside a Nx workspace');
+        return;
+    }
+    let nx;
+    try {
+        nx = JSON.parse(readFileSync(nxJsonPath, 'utf8'));
+    }
+    catch (e) {
+        add(checks, 'fail', 'nx.json parses', e.message, 'fix the JSON syntax in nx.json');
+        return;
+    }
+    const registered = (nx.plugins ?? []).some((p) => typeof p === 'string'
+        ? p === '@lensmcp/nx-plugin'
+        : !!p && typeof p === 'object' && p.plugin === '@lensmcp/nx-plugin');
+    add(checks, registered ? 'pass' : 'fail', '@lensmcp/nx-plugin registered in nx.json#plugins', registered ? undefined : 'not registered', registered ? undefined : 'run `lensmcp install`');
+    add(checks, nx.lensmcp?.schemaVersion === 1 ? 'pass' : 'warn', 'lensmcp config block in nx.json', nx.lensmcp?.schemaVersion === 1 ? undefined : 'missing', nx.lensmcp?.schemaVersion === 1 ? undefined : 'run `lensmcp install` to write the config defaults');
+}
+function checkMcpConfig(cwd, checks) {
+    const mcpPath = join(cwd, '.mcp.json');
+    if (!existsSync(mcpPath)) {
+        add(checks, 'warn', '.mcp.json with a lensmcp server', 'missing', 'run `lensmcp install` so agents auto-discover the MCP server');
+        return;
+    }
+    try {
+        const cfg = JSON.parse(readFileSync(mcpPath, 'utf8'));
+        const has = !!cfg.mcpServers && !!cfg.mcpServers['lensmcp'];
+        add(checks, has ? 'pass' : 'warn', '.mcp.json registers the lensmcp MCP server', has ? undefined : 'no lensmcp entry', has ? undefined : 'run `lensmcp install`');
+    }
+    catch (e) {
+        add(checks, 'warn', '.mcp.json parses', e.message, 'fix the JSON syntax in .mcp.json');
+    }
+}
+function checkServerBundle(cwd, checks) {
+    const bin = findMcpBinary(cwd);
+    add(checks, bin ? 'pass' : 'fail', 'lensmcp-mcp server bundle reachable', bin ?? 'missing', bin ? undefined : 'dev: `yarn nx build @lensmcp/lensmcp-mcp`');
+}
+function checkRuntimeDir(cwd, checks) {
+    const lensmcpDir = join(cwd, '.lensmcp');
+    add(checks, existsSync(lensmcpDir) ? 'pass' : 'warn', '.lensmcp/ runtime directory', existsSync(lensmcpDir) ? undefined : 'not created yet', existsSync(lensmcpDir) ? undefined : 'created automatically on first `lensmcp mcp` run');
+    // .gitignore should exclude the per-session runtime artifacts.
+    const giPath = join(cwd, '.gitignore');
+    const gi = existsSync(giPath) ? safeRead(giPath) : '';
+    const ignored = gi.split('\n').some((l) => l.trim() === '.lensmcp/' || l.trim() === '.lensmcp');
+    add(checks, ignored ? 'pass' : 'warn', '.gitignore excludes .lensmcp/', ignored ? undefined : 'not ignored', ignored ? undefined : 'add `.lensmcp/` to .gitignore (lensmcp install does this)');
+}
+function checkProjectWiring(cwd, checks) {
+    // Frontend: vite.config.* referencing the LensMCP plugin.
+    const viteConfigs = walkProjectFiles(cwd, (n) => /^vite\.config\.[cm]?[jt]s$/.test(n));
+    const viteWired = viteConfigs.filter((f) => /lensmcpVitePlugin|@lensmcp\/vite-plugin/.test(safeRead(f)));
+    if (viteConfigs.length > 0) {
+        const all = viteWired.length === viteConfigs.length;
+        add(checks, all ? 'pass' : 'warn', `Vite wiring: ${viteWired.length}/${viteConfigs.length} config(s) use the LensMCP plugin`, undefined, all ? undefined : 'wire each: `nx g @lensmcp/nx-plugin:setup-vite <project>`');
+    }
+    // Backend: main.ts bootstraps using createLensmcpNestApp vs raw NestFactory.
+    const mains = walkProjectFiles(cwd, (n) => n === 'main.ts');
+    const nestMains = mains.filter((f) => /NestFactory\.create|createLensmcpNestApp/.test(safeRead(f)));
+    const nestWired = nestMains.filter((f) => /createLensmcpNestApp/.test(safeRead(f)));
+    if (nestMains.length > 0) {
+        const all = nestWired.length === nestMains.length;
+        add(checks, all ? 'pass' : 'warn', `Nest wiring: ${nestWired.length}/${nestMains.length} bootstrap(s) use createLensmcpNestApp`, undefined, all ? undefined : 'wire each: `nx g @lensmcp/nx-plugin:setup-nest <project>`');
+    }
+    // agent-dev targets — the marker that setup-vite/setup-nest ran.
+    const configFiles = walkProjectFiles(cwd, (n) => n === 'project.json' || n === 'package.json');
+    const agentDev = configFiles.filter((f) => /"agent-dev"/.test(safeRead(f)));
+    add(checks, agentDev.length > 0 ? 'pass' : 'warn', `agent-dev targets: ${agentDev.length} project(s)`, undefined, agentDev.length > 0 ? undefined : 'no project wired — run setup-vite / setup-nest');
+}
+function checkChrome(checks) {
+    const envPath = process.env['CHROME_PATH'];
+    const candidates = process.platform === 'darwin'
+        ? [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        ]
+        : process.platform === 'win32'
+            ? [
+                'C:/Program Files/Google/Chrome/Application/chrome.exe',
+                'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
+            ]
+            : ['/usr/bin/google-chrome', '/usr/bin/chromium-browser', '/usr/bin/chromium', '/usr/bin/google-chrome-stable'];
+    const found = (envPath && existsSync(envPath) ? envPath : undefined) ?? candidates.find((p) => existsSync(p));
+    add(checks, found ? 'pass' : 'warn', 'Chrome for browser:// capture', found ? basename(found) : 'not found', found ? undefined : 'install Chrome or set CHROME_PATH (only needed for browser capture)');
+}
+/** Read a file, returning '' on any error. */
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Bounded recursive walk collecting files whose basename matches `match`.
+ * Skips node_modules / build / VCS dirs and caps scanned entries so doctor
+ * stays fast on large workspaces.
+ */
+function walkProjectFiles(root, match, maxDepth = 6, cap = 6000) {
+    const SKIP = new Set([
+        'node_modules',
+        'dist',
+        'build',
+        '.git',
+        '.nx',
+        '.lensmcp',
+        'coverage',
+        'tmp',
+        '.cache',
+        '.yarn',
+    ]);
+    const found = [];
+    const stack = [{ dir: root, depth: 0 }];
+    let scanned = 0;
+    while (stack.length > 0) {
+        const { dir, depth } = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (scanned++ > cap)
+                return found;
+            if (e.isDirectory()) {
+                if (SKIP.has(e.name) || e.name.startsWith('.'))
+                    continue;
+                if (depth < maxDepth)
+                    stack.push({ dir: join(dir, e.name), depth: depth + 1 });
+            }
+            else if (e.isFile() && match(e.name)) {
+                found.push(join(dir, e.name));
+            }
+        }
+    }
+    return found;
+}
+// ---------- helpers ----------
+function readCliVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** `lensmcp rollout` — delegate to the @lensmcp/cluster rollout helper (file IO +
+ *  atomic write), resolved at runtime from node_modules / workspace dist. */
+function runRollout(ctx, args, err) {
+    const cwd = resolve(ctx.cwd);
+    const bundle = findRolloutBundle(cwd);
+    if (!bundle) {
+        err('Could not locate the lensmcp rollout helper (@lensmcp/cluster).\n' +
+            'Looked for main.rollout.js (walking up from cwd):\n' +
+            '  • <dir>/node_modules/@lensmcp/cluster/executors/gateway/main.rollout.js\n' +
+            '  • <dir>/dist/libs/cluster/executors/gateway/main.rollout.js\n' +
+            'Install @lensmcp/cluster, or `yarn nx build @lensmcp/cluster` in the workspace.');
+        return { exitCode: 1 };
+    }
+    const res = spawnSync(process.execPath, [bundle, ...args], { stdio: 'inherit', cwd, env: { ...process.env, ...ctx.env } });
+    return { exitCode: res.status ?? 1 };
+}
+function findRolloutBundle(cwd) {
+    let dir = cwd;
+    for (let i = 0; i < 6; i++) {
+        for (const c of [
+            join(dir, 'node_modules', '@lensmcp', 'cluster', 'executors', 'gateway', 'main.rollout.js'),
+            join(dir, 'dist', 'libs', 'cluster', 'executors', 'gateway', 'main.rollout.js'),
+        ])
+            if (existsSync(c))
+                return c;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+function findMcpBinary(cwd) {
+    return findServerBundle(cwd, 'main.js');
+}
+/** Resolve a built server bundle (`main.js` | `dashboard.js`): the published
+ *  `bundled/<file>` first, then the workspace dev build (walking up from cwd). */
+function findServerBundle(cwd, file) {
+    // 1. Bundled inside the published lensmcp (ship step).
+    const here = dirname(fileURLToPath(import.meta.url));
+    const bundled = resolve(here, '..', '..', 'bundled', file);
+    if (existsSync(bundled))
+        return bundled;
+    // 2. Dev build in the workspace (four-bucket layout: servers/).
+    const devBuild = join(cwd, 'servers', 'lensmcp-mcp', 'dist', file);
+    if (existsSync(devBuild))
+        return devBuild;
+    // 3. Common monorepo locations relative to cwd (walk up).
+    let dir = cwd;
+    for (let i = 0; i < 5; i++) {
+        const candidate = join(dir, 'servers', 'lensmcp-mcp', 'dist', file);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+function findNxBinary(cwd) {
+    let dir = cwd;
+    for (let i = 0; i < 5; i++) {
+        const candidate = join(dir, 'node_modules', '.bin', 'nx');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+function ensureLensmcpDir(cwd) {
+    const dir = join(cwd, '.lensmcp');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+/** Narrow a flag value to string-or-undefined, treating booleans as absent. */
+function stringFlag(v) {
+    if (v === undefined)
+        return undefined;
+    return typeof v === 'string' ? v : undefined;
+}
+function parseFlags(argv, spec = {}) {
+    const strings = new Set(spec.string ?? []);
+    const booleans = new Set(spec.boolean ?? []);
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok.startsWith('--')) {
+            const eq = tok.indexOf('=');
+            const key = eq === -1 ? tok : tok.slice(0, eq);
+            if (booleans.has(key)) {
+                flags[key] = true;
+            }
+            else if (strings.has(key)) {
+                if (eq !== -1) {
+                    flags[key] = tok.slice(eq + 1);
+                }
+                else {
+                    const next = argv[i + 1];
+                    if (next === undefined || next.startsWith('--')) {
+                        flags[key] = '';
+                    }
+                    else {
+                        flags[key] = next;
+                        i++;
+                    }
+                }
+            }
+            else {
+                // unknown flag — record raw
+                flags[key] = eq === -1 ? true : tok.slice(eq + 1);
+            }
+        }
+        else {
+            positional.push(tok);
+        }
+    }
+    return { flags, positional };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "lensmcp",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "lensmcp": "bin.js"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "dependencies": {
+    "@frontmcp/sdk": "^1.4.1",
+    "reflect-metadata": "^0.2.2",
+    "tslib": "^2.3.0",
+    "vectoriadb": "^2.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.27.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/kiwiapps-ltd/lensmcp#readme",
+  "bugs": {
+    "url": "https://github.com/kiwiapps-ltd/lensmcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "LensMCP CLI — install and run the MCP observability server coding agents use to see running apps.",
+  "keywords": [
+    "lensmcp",
+    "mcp",
+    "observability",
+    "ai-agents",
+    "claude",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiwiapps-ltd/lensmcp.git",
+    "directory": "libs/cli"
+  }
+}