codegraph-java 0.1.0

package/dist/ui-server/index.js

@@ -0,0 +1,399 @@
+"use strict";
+/**
+ * The `cg ui` server.
+ *
+ * A loopback-only `node:http` server that hands the browser the built viewer
+ * (`dist/viewer/`) and, through the JSON API mounted on the `api` seam below
+ * (`./api`), a view of one indexed project. No framework, no new dependency: it
+ * answers GET, serves files, and refuses everything else.
+ *
+ * It is a reader with one exception, added deliberately and scoped as narrowly
+ * as it could be: `POST`/`DELETE /api/trails` saves and removes the reader's own
+ * named trails, as JSON files under `.codegraph/ui/trails/`. Nothing else it
+ * serves has a side effect, no other path accepts a write, and `--read-only`
+ * turns even that one off. See `security.ts` for what a write has to carry.
+ *
+ * The interesting part is not the routing, it is the boundary in `security.ts`.
+ * Read that first.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = exports.GraphSession = exports.createGraphApi = exports.cacheControlFor = exports.contentTypeFor = exports.openBrowser = exports.browserOpenCommand = exports.resolveStaticAsset = exports.resolveProjectFile = exports.isWriteRequest = exports.isWriteMethod = exports.isSafeRequestPath = exports.isAllowedOrigin = exports.isAllowedHost = exports.PathRefusalError = exports.WRITE_METHODS = exports.WRITE_HEADER = exports.READ_METHODS = exports.ALLOWED_METHODS = exports.VIEWER_PATH_ENV = exports.LOOPBACK_ADDRESS = exports.DEFAULT_UI_PORT = exports.DEFAULT_PORT_ATTEMPTS = exports.BROWSER_ENV = exports.ViewerMissingError = void 0;
+exports.startUiServer = startUiServer;
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const path = __importStar(require("path"));
+const assets_1 = require("./assets");
+const security_1 = require("./security");
+const static_1 = require("./static");
+const constants_1 = require("./constants");
+var assets_2 = require("./assets");
+Object.defineProperty(exports, "ViewerMissingError", { enumerable: true, get: function () { return assets_2.ViewerMissingError; } });
+var constants_2 = require("./constants");
+Object.defineProperty(exports, "BROWSER_ENV", { enumerable: true, get: function () { return constants_2.BROWSER_ENV; } });
+Object.defineProperty(exports, "DEFAULT_PORT_ATTEMPTS", { enumerable: true, get: function () { return constants_2.DEFAULT_PORT_ATTEMPTS; } });
+Object.defineProperty(exports, "DEFAULT_UI_PORT", { enumerable: true, get: function () { return constants_2.DEFAULT_UI_PORT; } });
+Object.defineProperty(exports, "LOOPBACK_ADDRESS", { enumerable: true, get: function () { return constants_2.LOOPBACK_ADDRESS; } });
+Object.defineProperty(exports, "VIEWER_PATH_ENV", { enumerable: true, get: function () { return constants_2.VIEWER_PATH_ENV; } });
+var security_2 = require("./security");
+Object.defineProperty(exports, "ALLOWED_METHODS", { enumerable: true, get: function () { return security_2.ALLOWED_METHODS; } });
+Object.defineProperty(exports, "READ_METHODS", { enumerable: true, get: function () { return security_2.READ_METHODS; } });
+Object.defineProperty(exports, "WRITE_HEADER", { enumerable: true, get: function () { return security_2.WRITE_HEADER; } });
+Object.defineProperty(exports, "WRITE_METHODS", { enumerable: true, get: function () { return security_2.WRITE_METHODS; } });
+Object.defineProperty(exports, "PathRefusalError", { enumerable: true, get: function () { return security_2.PathRefusalError; } });
+Object.defineProperty(exports, "isAllowedHost", { enumerable: true, get: function () { return security_2.isAllowedHost; } });
+Object.defineProperty(exports, "isAllowedOrigin", { enumerable: true, get: function () { return security_2.isAllowedOrigin; } });
+Object.defineProperty(exports, "isSafeRequestPath", { enumerable: true, get: function () { return security_2.isSafeRequestPath; } });
+Object.defineProperty(exports, "isWriteMethod", { enumerable: true, get: function () { return security_2.isWriteMethod; } });
+Object.defineProperty(exports, "isWriteRequest", { enumerable: true, get: function () { return security_2.isWriteRequest; } });
+Object.defineProperty(exports, "resolveProjectFile", { enumerable: true, get: function () { return security_2.resolveProjectFile; } });
+Object.defineProperty(exports, "resolveStaticAsset", { enumerable: true, get: function () { return security_2.resolveStaticAsset; } });
+var open_browser_1 = require("./open-browser");
+Object.defineProperty(exports, "browserOpenCommand", { enumerable: true, get: function () { return open_browser_1.browserOpenCommand; } });
+Object.defineProperty(exports, "openBrowser", { enumerable: true, get: function () { return open_browser_1.openBrowser; } });
+var static_2 = require("./static");
+Object.defineProperty(exports, "contentTypeFor", { enumerable: true, get: function () { return static_2.contentTypeFor; } });
+Object.defineProperty(exports, "cacheControlFor", { enumerable: true, get: function () { return static_2.cacheControlFor; } });
+var api_1 = require("./api");
+Object.defineProperty(exports, "createGraphApi", { enumerable: true, get: function () { return api_1.createGraphApi; } });
+Object.defineProperty(exports, "GraphSession", { enumerable: true, get: function () { return api_1.GraphSession; } });
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_1.ApiError; } });
+/**
+ * Response headers sent on EVERY response.
+ *
+ * `frame-ancestors`/`X-Frame-Options` stop another page from framing the viewer
+ * and reading it by overlay; `nosniff` stops an asset with a surprising
+ * extension from being executed as script; the CSP pins every resource to this
+ * origin, so a future viewer change cannot start phoning out with what it read.
+ * `style-src` keeps `'unsafe-inline'` because the syntax highlighter emits
+ * inline `style=` attributes on code spans.
+ *
+ * Note what is NOT here: any `Access-Control-*` header. Their absence is what
+ * makes a cross-origin read of a response body impossible even if a request
+ * somehow gets past the `Host` check.
+ */
+const SECURITY_HEADERS = {
+    'X-Content-Type-Options': 'nosniff',
+    'X-Frame-Options': 'DENY',
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': [
+        "default-src 'none'",
+        "script-src 'self'",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data:",
+        "font-src 'self'",
+        "connect-src 'self'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join('; '),
+};
+/**
+ * Start the viewer server.
+ *
+ * Resolves once the socket is bound, so the caller can print a URL that is
+ * already answering.
+ */
+async function startUiServer(options) {
+    // realpath, not just resolve: `resolveStaticAsset` hands back realpaths (the
+    // symlink check in `validatePathWithinRoot` resolves them), so a viewerDir
+    // that still holds a symlink — every macOS `/var/folders` temp dir, plenty of
+    // package managers — would make `path.relative` between the two nonsense, and
+    // the cache policy that keys off it silently wrong.
+    const viewerDir = options.viewerDir ? realpath(options.viewerDir) : (0, assets_1.resolveViewerDir)();
+    const projectRoot = path.resolve(options.projectRoot);
+    const indexHtml = path.join(viewerDir, 'index.html');
+    // The bound port is needed by the Host check, but is only known after listen.
+    // Captured by reference so the handler always sees the real value.
+    let boundPort = 0;
+    const server = http.createServer((req, res) => {
+        handleRequest(req, res, {
+            viewerDir,
+            indexHtml,
+            projectRoot,
+            api: options.api,
+            port: () => boundPort,
+        }).catch(() => {
+            // handleRequest already answers every error it can; reaching here means
+            // the socket itself is gone. Never let it become an unhandled rejection,
+            // which the CLI's fatal handlers would turn into a process exit.
+            if (!res.writableEnded)
+                res.destroy();
+        });
+    });
+    // A browser holds keep-alive sockets open; without this, `close()` would wait
+    // for them and Ctrl-C would appear to hang.
+    server.keepAliveTimeout = 5_000;
+    boundPort = await listenWithFallback(server, {
+        port: options.port ?? constants_1.DEFAULT_UI_PORT,
+        fallback: options.portFallback ?? true,
+        attempts: options.maxPortAttempts ?? constants_1.DEFAULT_PORT_ATTEMPTS,
+    });
+    let closed = false;
+    return {
+        port: boundPort,
+        url: `http://${constants_1.LOOPBACK_ADDRESS}:${boundPort}`,
+        viewerDir,
+        server,
+        close() {
+            if (closed)
+                return Promise.resolve();
+            closed = true;
+            return new Promise((resolve) => {
+                server.closeAllConnections();
+                server.close(() => resolve());
+            });
+        },
+    };
+}
+/**
+ * One request, start to finish. Order matters: the cheap refusals (method,
+ * `Host`, `Origin`) run before anything touches the filesystem.
+ */
+async function handleRequest(req, res, deps) {
+    const method = req.method ?? 'GET';
+    for (const [name, value] of Object.entries(SECURITY_HEADERS)) {
+        res.setHeader(name, value);
+    }
+    if (!security_1.ALLOWED_METHODS.includes(method)) {
+        res.setHeader('Allow', security_1.ALLOWED_METHODS.join(', '));
+        (0, static_1.sendText)(res, 405, `cg ui does not answer ${method}.`, method);
+        return;
+    }
+    const port = deps.port();
+    if (!(0, security_1.isAllowedHost)(req.headers.host, port)) {
+        // The DNS-rebinding refusal. Say why, since a human hitting this through a
+        // proxy or a container hostname needs to know what to change.
+        (0, static_1.sendText)(res, 403, 'Refused: cg ui only answers requests addressed to this machine ' +
+            `(localhost, 127.0.0.1 or [::1] on port ${port}).\n` +
+            `This request said Host: ${forEcho(req.headers.host)}`, method);
+        return;
+    }
+    if (!(0, security_1.isAllowedOrigin)(readHeader(req, 'origin'), port)) {
+        (0, static_1.sendText)(res, 403, 'Refused: cross-origin requests are not served.', method);
+        return;
+    }
+    // Checked on the RAW url, before WHATWG parsing folds `..` segments away.
+    const rawPath = (req.url ?? '/').split(/[?#]/)[0] ?? '/';
+    // The `/api/` namespace answers JSON for EVERY outcome, refusals included:
+    // the viewer parses these responses, and a text/plain body here would surface
+    // as a parse error instead of the refusal it actually is.
+    const jsonNamespace = rawPath === '/api' || rawPath.startsWith('/api/');
+    // The one place this server stops being a pure reader. A write has to be
+    // under /api/ and carry the marker header — see `isWriteRequest` for what
+    // that closes that Host and Origin do not.
+    if ((0, security_1.isWriteMethod)(method)) {
+        const verdict = (0, security_1.isWriteRequest)(rawPath, {
+            marker: readHeader(req, security_1.WRITE_HEADER),
+            contentType: readHeader(req, 'content-type'),
+        });
+        if (!verdict.ok) {
+            if (!jsonNamespace)
+                res.setHeader('Allow', security_1.READ_METHODS.join(', '));
+            const body = `Refused: ${verdict.reason}`;
+            if (jsonNamespace)
+                (0, static_1.sendJson)(res, 403, { error: body, code: 'refused' }, method);
+            else
+                (0, static_1.sendText)(res, 405, body, method);
+            return;
+        }
+    }
+    if (!(0, security_1.isSafeRequestPath)(rawPath)) {
+        if (jsonNamespace) {
+            (0, static_1.sendJson)(res, 404, { error: 'Not found', code: 'not-found' }, method);
+        }
+        else {
+            (0, static_1.sendText)(res, 404, 'Not found', method);
+        }
+        return;
+    }
+    let url;
+    try {
+        url = new URL(req.url ?? '/', `http://${constants_1.LOOPBACK_ADDRESS}:${port}`);
+    }
+    catch {
+        (0, static_1.sendText)(res, 400, 'Bad request URL.', method);
+        return;
+    }
+    // `/api/` is reserved — it must 404 as JSON rather than fall through to the
+    // SPA, or a typo'd endpoint returns 200 + HTML and the viewer parses the app
+    // shell as a payload.
+    if (url.pathname === '/api' || url.pathname.startsWith('/api/')) {
+        const ctx = {
+            pathname: safeDecode(url.pathname),
+            query: url.searchParams,
+            projectRoot: deps.projectRoot,
+            method,
+        };
+        if (deps.api) {
+            try {
+                if (await deps.api(req, res, ctx))
+                    return;
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    (0, static_1.sendJson)(res, 500, { error: err instanceof Error ? err.message : String(err) }, method);
+                }
+                else {
+                    res.destroy();
+                }
+                return;
+            }
+        }
+        if (!res.headersSent)
+            (0, static_1.sendJson)(res, 404, { error: `No such endpoint: ${url.pathname}` }, method);
+        return;
+    }
+    const requested = url.pathname === '/' ? '/index.html' : url.pathname;
+    const file = (0, security_1.resolveStaticAsset)(deps.viewerDir, requested);
+    if (file) {
+        (0, static_1.sendFile)(res, file, { rootDir: deps.viewerDir, method });
+        return;
+    }
+    if ((0, static_1.shouldFallBackToIndex)(url.pathname)) {
+        (0, static_1.sendFile)(res, deps.indexHtml, { rootDir: deps.viewerDir, method });
+        return;
+    }
+    (0, static_1.sendText)(res, 404, 'Not found', method);
+}
+/** `path.resolve` + symlink resolution, falling back when the path is missing. */
+function realpath(dir) {
+    const resolved = path.resolve(dir);
+    try {
+        return fs.realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Bound and de-fang an attacker-supplied header before echoing it back.
+ *
+ * The refused `Host` is worth showing — a human hitting this through a proxy or
+ * a container hostname needs to know what was actually sent. But it is
+ * attacker-chosen text, so it goes out truncated and stripped of control bytes.
+ * (The response is `text/plain` + `nosniff`, so there is nothing to inject
+ * into; this is belt and braces.)
+ */
+function forEcho(value) {
+    if (!value)
+        return '(none)';
+    // eslint-disable-next-line no-control-regex -- stripping raw control bytes IS the point
+    const clean = value.replace(/[\x00-\x1f\x7f]/g, '?');
+    return clean.length > 100 ? `${clean.slice(0, 100)}…` : clean;
+}
+/** Read a header as a single string (node gives arrays for some headers). */
+function readHeader(req, name) {
+    const value = req.headers[name];
+    if (value === undefined)
+        return undefined;
+    return Array.isArray(value) ? value[0] : value;
+}
+/** Percent-decode for display; the raw value is used for anything security-relevant. */
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Bind the first free port at or after `port`, on loopback only.
+ *
+ * Only `EADDRINUSE` advances to the next port — a permission failure or a bad
+ * address will not get better one port over, and retrying twenty times would
+ * only bury the real error.
+ */
+async function listenWithFallback(server, opts) {
+    // Port 0 means "any free port", so there is nothing to fall back from.
+    const attempts = opts.port === 0 || !opts.fallback ? 1 : Math.max(1, opts.attempts);
+    for (let i = 0; i < attempts; i++) {
+        const candidate = opts.port === 0 ? 0 : opts.port + i;
+        try {
+            await listenOnce(server, candidate);
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                throw new Error('The UI server bound to an unexpected address.');
+            }
+            return address.port;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EADDRINUSE' || i === attempts - 1) {
+                throw describeBindFailure(err, candidate, opts);
+            }
+        }
+    }
+    /* istanbul ignore next — the loop either returns or throws */
+    throw new Error('The UI server could not bind a port.');
+}
+/**
+ * One `listen()` attempt, with both outcomes as a promise.
+ *
+ * The same `http.Server` is reused across attempts: a `listen()` that failed
+ * with EADDRINUSE never took a handle, so it can be listened on again directly
+ * (verified on Node 20 and 22 — `server.listening` is still `false` afterwards,
+ * and `close()` on a never-listening server would itself throw).
+ */
+function listenOnce(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.removeListener('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, constants_1.LOOPBACK_ADDRESS);
+    });
+}
+/** Turn a bind failure into something a user can act on. */
+function describeBindFailure(err, port, opts) {
+    const code = err.code;
+    if (code === 'EADDRINUSE') {
+        return opts.fallback
+            ? new Error(`Ports ${opts.port}–${port} are all in use. Free one, or pick another with --port.`)
+            : new Error(`Port ${port} is already in use. Pick another with --port, or omit --port to let CodeGraph find a free one.`);
+    }
+    if (code === 'EACCES') {
+        return new Error(`Not allowed to listen on port ${port}. Ports below 1024 usually need elevated privileges — pick a higher one with --port.`);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+//# sourceMappingURL=index.js.map

package/dist/ui-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui-server/index.ts"],"names":[],"mappings":"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"}

package/dist/ui-server/open-browser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Opening the user's browser at the viewer URL.
+ *
+ * No dependency: the three platform openers are one-liners, and pulling in a
+ * package to shell out to `open` would be the only runtime dependency the
+ * viewer adds to a CLI that currently has ten.
+ */
+import { BROWSER_ENV } from './constants';
+export { BROWSER_ENV };
+export interface OpenCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * The command that would open `url`, or `null` when opening is suppressed.
+ *
+ * Split out from {@link openBrowser} so the platform mapping is testable
+ * without launching anything.
+ */
+export declare function browserOpenCommand(url: string, platform: NodeJS.Platform, override?: string): OpenCommand | null;
+/**
+ * Open `url` in the user's default browser, best effort.
+ *
+ * Never throws and never keeps the CLI alive: the child is detached and
+ * unref'd, and a missing opener (a headless Linux box with no `xdg-open`) is
+ * swallowed — the URL is already printed, which is the part that matters.
+ *
+ * @returns `true` if a launch was attempted.
+ */
+export declare function openBrowser(url: string, platform?: NodeJS.Platform): boolean;
+//# sourceMappingURL=open-browser.d.ts.map

package/dist/ui-server/open-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.d.ts","sourceRoot":"","sources":["../../src/ui-server/open-browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,CAAC;AAIvB,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,IAAI,CAsBpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,OAAO,CAkB9F"}

package/dist/ui-server/open-browser.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Opening the user's browser at the viewer URL.
+ *
+ * No dependency: the three platform openers are one-liners, and pulling in a
+ * package to shell out to `open` would be the only runtime dependency the
+ * viewer adds to a CLI that currently has ten.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_ENV = void 0;
+exports.browserOpenCommand = browserOpenCommand;
+exports.openBrowser = openBrowser;
+const child_process_1 = require("child_process");
+const constants_1 = require("./constants");
+Object.defineProperty(exports, "BROWSER_ENV", { enumerable: true, get: function () { return constants_1.BROWSER_ENV; } });
+const SUPPRESS_VALUES = new Set(['', 'none', '0', 'false', 'off']);
+/**
+ * The command that would open `url`, or `null` when opening is suppressed.
+ *
+ * Split out from {@link openBrowser} so the platform mapping is testable
+ * without launching anything.
+ */
+function browserOpenCommand(url, platform, override) {
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (SUPPRESS_VALUES.has(trimmed.toLowerCase()))
+            return null;
+        // Windows: go through `cmd /c` rather than spawning the override directly.
+        // `spawn` there is CreateProcess, which only ever launches a real .exe — a
+        // `.cmd`/`.bat` browser shim (how most Windows wrappers are written) fails
+        // outright, and an extension-less name only resolves because CreateProcess
+        // appends `.exe`. Routing through cmd makes .exe, .cmd and .bat all work,
+        // and node quotes each argument, so a path with spaces survives. Caught on
+        // the Windows VM, where the direct spawn silently launched nothing.
+        if (platform === 'win32')
+            return { command: 'cmd', args: ['/c', trimmed, url] };
+        return { command: trimmed, args: [url] };
+    }
+    if (platform === 'darwin')
+        return { command: 'open', args: [url] };
+    if (platform === 'win32') {
+        // `start` is a cmd builtin, not an executable. The empty string is the
+        // window title — without it `start` treats a quoted URL as the title and
+        // opens a blank console instead.
+        return { command: 'cmd', args: ['/c', 'start', '', url] };
+    }
+    return { command: 'xdg-open', args: [url] };
+}
+/**
+ * Open `url` in the user's default browser, best effort.
+ *
+ * Never throws and never keeps the CLI alive: the child is detached and
+ * unref'd, and a missing opener (a headless Linux box with no `xdg-open`) is
+ * swallowed — the URL is already printed, which is the part that matters.
+ *
+ * @returns `true` if a launch was attempted.
+ */
+function openBrowser(url, platform = process.platform) {
+    const open = browserOpenCommand(url, platform, process.env[constants_1.BROWSER_ENV]);
+    if (!open)
+        return false;
+    try {
+        const child = (0, child_process_1.spawn)(open.command, open.args, {
+            detached: true,
+            stdio: 'ignore',
+            // `start` is a shell builtin reached through `cmd /c`, so no shell here.
+            shell: false,
+        });
+        child.on('error', () => {
+            /* no opener installed — the printed URL is the fallback */
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=open-browser.js.map

package/dist/ui-server/open-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.js","sourceRoot":"","sources":["../../src/ui-server/open-browser.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAoBH,gDA0BC;AAWD,kCAkBC;AAzED,iDAAsC;AACtC,2CAA0C;AAEjC,4FAFA,uBAAW,OAEA;AAEpB,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AAOxF;;;;;GAKG;AACH,SAAgB,kBAAkB,CAChC,GAAW,EACX,QAAyB,EACzB,QAAiB;IAEjB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5D,2EAA2E;QAC3E,2EAA2E;QAC3E,2EAA2E;QAC3E,2EAA2E;QAC3E,0EAA0E;QAC1E,2EAA2E;QAC3E,oEAAoE;QACpE,IAAI,QAAQ,KAAK,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;QAChF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3C,CAAC;IACD,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACnE,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,uEAAuE;QACvE,yEAAyE;QACzE,iCAAiC;QACjC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,WAAW,CAAC,GAAW,EAAE,WAA4B,OAAO,CAAC,QAAQ;IACnF,MAAM,IAAI,GAAG,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAW,CAAC,CAAC,CAAC;IACzE,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAA,qBAAK,EAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE;YAC3C,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;YACf,yEAAyE;YACzE,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,2DAA2D;QAC7D,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/ui-server/security.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The `cg ui` server's security boundary.
+ *
+ * Threat model, stated plainly: this process serves a browser-readable view of
+ * the user's SOURCE CODE from a port on their machine. It binds loopback, so
+ * nothing on the network can reach it. That leaves one realistic attack —
+ * **DNS rebinding**: any page the user visits can point `evil.example` at
+ * `127.0.0.1` and then have the browser issue same-origin requests to us. The
+ * browser will happily connect; the only thing that distinguishes the attacker's
+ * request from the viewer's own is the `Host` header, which the browser fills in
+ * from the URL and script cannot forge.
+ *
+ * So the rules are:
+ *
+ * - **`Host` must be a loopback name** (`localhost`, `127.0.0.1`, `[::1]`) and,
+ *   if it carries a port, that port must be ours. Anything else is 403.
+ * - **`Origin`, when present, must be loopback too.** Belt and braces: absent on
+ *   the viewer's own same-origin GETs, and present-and-foreign only on a
+ *   cross-site request we want nothing to do with.
+ * - **No CORS headers, ever.** Not adding `Access-Control-Allow-Origin` is what
+ *   keeps a cross-origin reader from seeing a response body even if it does
+ *   reach us. There is deliberately no way to turn this on.
+ * - **GET/HEAD everywhere; POST/DELETE only under `/api/`, and only for a
+ *   request that could not have been forged by a form.** See
+ *   {@link isWriteRequest} below — the viewer went from a pure reader to one
+ *   that saves trails into `.codegraph/ui/`, and that is the entire change to
+ *   this boundary.
+ * - **Every path resolves through {@link validatePathWithinRoot}** — the same
+ *   chokepoint the MCP read sinks use, which catches `../` traversal AND
+ *   in-tree symlinks pointing out of the root (#527).
+ */
+import { PathRefusalError } from '../errors';
+export { PathRefusalError };
+/** Methods that answer anywhere: the viewer's assets and every read endpoint. */
+export declare const READ_METHODS: readonly string[];
+/**
+ * Methods that answer under `/api/` only, and only for a request carrying
+ * {@link WRITE_HEADER}. The viewer's one write is a saved trail.
+ */
+export declare const WRITE_METHODS: readonly string[];
+/** HTTP methods the viewer server answers at all. Everything else is 405. */
+export declare const ALLOWED_METHODS: readonly string[];
+/**
+ * The header a write has to carry.
+ *
+ * Belt and braces behind the `Host` and `Origin` checks, and worth the two
+ * lines because it fails *differently*: a custom request header cannot be sent
+ * cross-origin without a CORS preflight, and this server answers no preflight
+ * and sends no `Access-Control-*` header, so the browser never issues the real
+ * request. That closes the one shape those checks lean on a header for — a
+ * `<form method="post">` submitted from another page, which sends no `Origin`
+ * in some older browsers and cannot set a custom header in any of them.
+ */
+export declare const WRITE_HEADER = "x-codegraph-ui";
+export declare function isWriteMethod(method: string): boolean;
+/**
+ * Whether a mutating request is one the viewer could have made.
+ *
+ * @param method     the request method, already known to be a write method
+ * @param pathname   the raw request path
+ * @param headers    `x-codegraph-ui` and, for a body-carrying method, `content-type`
+ */
+export declare function isWriteRequest(pathname: string, headers: {
+    marker: string | undefined;
+    contentType: string | undefined;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether a request's `Host` header names this loopback server.
+ *
+ * A missing `Host` is rejected: HTTP/1.1 requires it, and the one client that
+ * may legally omit it (HTTP/1.0) is not a browser we need to serve.
+ */
+export declare function isAllowedHost(host: string | undefined, port: number): boolean;
+/**
+ * Whether a request's `Origin` header is acceptable.
+ *
+ * An ABSENT `Origin` is allowed — browsers omit it on same-origin GETs, which
+ * is every request the viewer makes. A present one must be loopback-on-our-port;
+ * the literal `null` origin (sandboxed iframe, `file://` page) is refused.
+ */
+export declare function isAllowedOrigin(origin: string | undefined, port: number): boolean;
+/**
+ * Whether a raw request path is worth resolving at all.
+ *
+ * Rejects any `..` segment outright rather than letting containment sort it
+ * out later. Containment WOULD catch it — but the SPA fallback sits behind
+ * containment, so `GET /../../etc/passwd` would otherwise be answered with the
+ * app shell (a 200) instead of the 404 a traversal attempt deserves. Nothing
+ * outside the root leaks either way; this just stops the server from
+ * pretending a hostile path was an ordinary route.
+ *
+ * Takes the RAW path from `req.url`, before WHATWG URL parsing folds `..`
+ * segments away — that folding is what would hide the attempt.
+ */
+export declare function isSafeRequestPath(rawPath: string): boolean;
+/**
+ * Resolve a request path to a file inside the static asset root.
+ *
+ * Returns the absolute path, or `null` for anything that is not a readable file
+ * inside `rootDir` — a traversal attempt, a symlink escape, a directory, a
+ * missing file. Callers turn `null` into a 404 (never a 403): telling a prober
+ * which of those it hit is free information.
+ *
+ * Percent-decoding happens HERE, before containment is checked, so an encoded
+ * `..%2f` is caught by the same guard as a literal `../`.
+ */
+export declare function resolveStaticAsset(rootDir: string, urlPath: string): string | null;
+/**
+ * Resolve a project-relative source path to an absolute path that is safe to
+ * read and hand to the browser.
+ *
+ * This is the single read chokepoint for anything served OUT OF THE USER'S
+ * REPOSITORY (as opposed to the viewer's own bundled assets). The JSON API
+ * built on top of this server must route every file read through it — that is
+ * what keeps `/api/source?path=../../.ssh/id_rsa` from being a credential leak
+ * over a port the user opened to read their own code.
+ *
+ * @throws {PathRefusalError} when the root is a sensitive system directory, or
+ *   the path escapes the root by traversal or symlink.
+ */
+export declare function resolveProjectFile(projectRoot: string, relativePath: string): string;
+//# sourceMappingURL=security.d.ts.map