scenescout 1.0.0 → 1.2.0

package/dist/clients.js

@@ -0,0 +1,213 @@
+/**
+ * Registering the MCP server with clients other than Claude Code.
+ *
+ * Each client keeps its server list somewhere different. Where a client has a
+ * command for adding a server, that command is used: it knows its own config
+ * format and location. Where it has none, the JSON file it reads is edited in
+ * place, keeping every other entry.
+ *
+ * Nothing here launches a process or touches the home directory on its own:
+ * the runner, the home directory and the platform are passed in, so every rule
+ * can be table-tested.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { MCP_NAME } from "./installer.js";
+export const OTHER_CLIENTS = ["cursor", "vscode", "codex", "gemini", "copilot", "windsurf"];
+export const CLIENTS = ["claude-code", ...OTHER_CLIENTS];
+export const CLIENT_LABELS = {
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    vscode: "VS Code (GitHub Copilot agent mode)",
+    codex: "Codex CLI",
+    gemini: "Gemini CLI",
+    copilot: "GitHub Copilot CLI",
+    windsurf: "Windsurf",
+};
+/** Read the value of `--client`. Absent means Claude Code, which is what install has always set up. */
+export function parseClients(value) {
+    if (value === undefined)
+        return { clients: ["claude-code"] };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    const choices = CLIENTS.join(", ");
+    if (names.length === 0)
+        return { error: `--client needs a value. Choose from: ${choices}.` };
+    const picked = new Set();
+    for (const name of names) {
+        if (!CLIENTS.includes(name))
+            return { error: `"${name}" is not a client install knows how to set up. Choose from: ${choices}.` };
+        picked.add(name);
+    }
+    return { clients: CLIENTS.filter((c) => picked.has(c)) };
+}
+const STRATEGIES = {
+    cursor: { kind: "file", file: (home) => path.join(home, ".cursor", "mcp.json"), key: "mcpServers" },
+    windsurf: { kind: "file", file: (home) => path.join(home, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers" },
+    // `add` replaces an entry of the same name.
+    codex: { kind: "command", binary: "codex", add: (launch) => ["mcp", "add", MCP_NAME, "--", ...launch] },
+    // `add` updates an entry of the same name. The default scope is the project; a tool like this belongs to the user.
+    gemini: { kind: "command", binary: "gemini", add: (launch) => ["mcp", "add", "--scope", "user", MCP_NAME, ...launch] },
+    // `add` refuses a name that already exists, so the old entry is removed first.
+    copilot: { kind: "command", binary: "copilot", add: (launch) => ["mcp", "add", MCP_NAME, "--", ...launch], removeFirst: ["mcp", "remove", MCP_NAME] },
+};
+const quote = (s) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`);
+/** The entry every `mcpServers`-style file takes. */
+export function serverEntry(launch) {
+    return { command: launch[0], args: launch.slice(1) };
+}
+/**
+ * Put the server into a client's JSON server list, keeping everything else in
+ * the file. A file that is not valid JSON is left exactly as it is: rewriting
+ * it would discard whatever the person had in it.
+ */
+export function registerInFile(file, key, launch) {
+    const entry = serverEntry(launch);
+    const manual = `add this under "${key}" in ${file}:\n  ${JSON.stringify({ [MCP_NAME]: entry })}`;
+    let config = {};
+    // A config kept in a dotfiles repository is a link. Renaming over the link
+    // would replace it with a plain file and leave the real one unchanged, so
+    // the write goes to whatever the link points at.
+    let target = file;
+    let mode = 0o600;
+    try {
+        if (fs.existsSync(file)) {
+            target = fs.realpathSync(file);
+            mode = fs.statSync(target).mode & 0o777;
+            // Some editors save with a byte-order mark, which JSON.parse rejects.
+            const raw = fs.readFileSync(target, "utf8").replace(/^\uFEFF/, "");
+            if (raw.trim().length > 0) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch (err) {
+                    return {
+                        status: "failed",
+                        detail: `${file} is not valid JSON (${err instanceof Error ? err.message : String(err)}), so it was left untouched`,
+                        manual,
+                    };
+                }
+                if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    return { status: "failed", detail: `${file} does not hold a JSON object, so it was left untouched`, manual };
+                }
+                config = parsed;
+            }
+        }
+    }
+    catch (err) {
+        return { status: "failed", detail: `${file} could not be read (${err instanceof Error ? err.message : String(err)})`, manual };
+    }
+    const existing = config[key];
+    if (existing !== undefined && (existing === null || typeof existing !== "object" || Array.isArray(existing))) {
+        return { status: "failed", detail: `"${key}" in ${file} is not an object, so the file was left untouched`, manual };
+    }
+    const servers = (existing ?? {});
+    const before = servers[MCP_NAME];
+    const notes = [];
+    if (before !== undefined && JSON.stringify(before) !== JSON.stringify(entry)) {
+        notes.push(`the previous "${MCP_NAME}" entry was replaced; it ran: ${JSON.stringify(before)}`);
+    }
+    config[key] = { ...servers, [MCP_NAME]: entry };
+    // Written beside the target and renamed over it, so a crash cannot leave half a file.
+    const tmp = `${target}.scenescout-${process.pid}.tmp`;
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode });
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        // The temporary file is a full copy of the config, which can hold secrets in `env`; it must not stay behind.
+        fs.rmSync(tmp, { force: true });
+        return { status: "failed", detail: `${file} could not be written (${err instanceof Error ? err.message : String(err)}), so it was left untouched`, manual };
+    }
+    return { status: "registered", where: file, replaced: before !== undefined, notes };
+}
+function registerWithCommand(client, launch, run) {
+    const manual = [client.binary, ...client.add(launch)].map(quote).join(" ");
+    let removed = false;
+    if (client.removeFirst) {
+        const removal = run(client.binary, client.removeFirst);
+        if (removal.missing)
+            return { status: "client-missing", manual };
+        // A non-zero exit here only means there was nothing of that name to remove.
+        removed = removal.status === 0;
+    }
+    const added = run(client.binary, client.add(launch));
+    if (added.missing)
+        return { status: "client-missing", manual };
+    if (added.status !== 0) {
+        const reason = (added.stdout + added.stderr).trim().split("\n")[0] || `exit code ${added.status}`;
+        // Having removed the old entry to make room, say so: the person now has no registration at all.
+        const lost = removed ? ` The previous "${MCP_NAME}" entry had already been removed to make room, so ${client.binary} now has none.` : "";
+        return { status: "failed", detail: reason + lost, manual };
+    }
+    return { status: "registered", where: `${client.binary} mcp`, replaced: removed, notes: [] };
+}
+/**
+ * The VS Code command line, or null when only a fork is installed. Cursor and
+ * Windsurf both install a `code` command of their own, and running that one
+ * registers the server in the wrong editor: it reports success and VS Code
+ * never sees the entry. A `code` that resolves into another editor's files is
+ * therefore not VS Code.
+ *
+ * The real path is only inspected. What gets run is the command as found on
+ * PATH: some installs (snap) link `code` to a launcher that decides what to
+ * start from the name it was called by, and running the link's target directly
+ * starts the wrong thing.
+ */
+export function vscodeBinary(opts) {
+    if (opts.platform === "darwin") {
+        for (const root of ["/Applications", path.posix.join(opts.home, "Applications")]) {
+            const bundled = path.posix.join(root, "Visual Studio Code.app", "Contents", "Resources", "app", "bin", "code");
+            if (opts.exists(bundled))
+                return bundled;
+        }
+    }
+    if (!opts.codeOnPath)
+        return null;
+    // Looked for below the home directory's own name, so an account called "cursor" does not disqualify every install under it.
+    const real = opts.codeOnPath.realPath;
+    const belowHome = real.toLowerCase().startsWith(opts.home.toLowerCase()) ? real.slice(opts.home.length) : real;
+    return /cursor|windsurf|codeium|vscodium/i.test(belowHome) ? null : opts.codeOnPath.command;
+}
+/** What `code --add-mcp` takes: the entry plus its name. */
+export function vscodeAddArgs(launch) {
+    return ["--add-mcp", JSON.stringify({ name: MCP_NAME, ...serverEntry(launch) })];
+}
+export function registerWithClient(client, opts) {
+    if (client === "vscode") {
+        const manual = `in VS Code run "MCP: Add Server…" and choose a command (stdio) server, or run:\n  code ${vscodeAddArgs(opts.launch).map(quote).join(" ")}`;
+        if (!opts.vscode)
+            return { status: "client-missing", manual };
+        const added = opts.run(opts.vscode, vscodeAddArgs(opts.launch));
+        if (added.missing)
+            return { status: "client-missing", manual };
+        const output = (added.stdout + added.stderr).trim();
+        if (added.status !== 0)
+            return { status: "failed", detail: output.split("\n")[0] || `exit code ${added.status}`, manual };
+        // This command replaces an entry of the same name and does not say whether there was one.
+        return { status: "registered", where: "VS Code's user profile", replaced: false, notes: [] };
+    }
+    const strategy = STRATEGIES[client];
+    return strategy.kind === "file" ? registerInFile(strategy.file(opts.home), strategy.key, opts.launch) : registerWithCommand(strategy, opts.launch, opts.run);
+}
+/** How to register with a client by hand, without running anything. */
+export function manualFor(client, launch, home) {
+    if (client === "vscode")
+        return `code ${vscodeAddArgs(launch).map(quote).join(" ")}`;
+    const strategy = STRATEGIES[client];
+    if (strategy.kind === "command")
+        return [strategy.binary, ...strategy.add(launch)].map(quote).join(" ");
+    return `add under "${strategy.key}" in ${strategy.file(home)}:  ${JSON.stringify({ [MCP_NAME]: serverEntry(launch) })}`;
+}
+/** What to tell the person once their clients are set up: how the method reaches an agent that has no skill. */
+export function firstMessageHint(clients) {
+    const names = clients.map((c) => CLIENT_LABELS[c]);
+    const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}` : names[0];
+    return (`Restart ${list} (or reload the MCP servers there), then ask the agent:\n` +
+        `  Use SceneScout to test http://localhost:3000\n` +
+        `The server hands the agent the testing method through its scout_playbook tool.`);
+}

package/dist/code-routes.js

@@ -0,0 +1,462 @@
+/**
+ * Route discovery for frameworks that define routes in CODE rather than in the
+ * filesystem: React Router, Vue Router and Angular.
+ *
+ * Without this, those projects fell back to link discovery, so a page nothing
+ * linked to was outside the completion contract. The three routers share two
+ * shapes — route records written as object literals (`{ path, children }`) and,
+ * for React, `<Route path>` elements — so one reader covers them.
+ *
+ * It is a static READER, not an evaluator, and it prefers missing a route to
+ * inventing one: an invented route becomes a page the contract demands and the
+ * app does not have. So it only reads files that are recognisably router
+ * configuration, only accepts object literals that look like route records,
+ * and skips anything it cannot resolve (identifiers, spreads, computed paths).
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Keys that make an object literal with a `path` a route record rather than, say, a build config. */
+/** `name` and `meta` are deliberately absent: a sidebar or breadcrumb entry is `{ path, name }` too. */
+const ROUTE_RECORD_KEYS = [
+    "element",
+    "Component",
+    "component",
+    "components",
+    "children",
+    "loadComponent",
+    "loadChildren",
+    "lazy",
+    "loader",
+    "redirect",
+    "redirectTo",
+    "index",
+];
+/** Read a JS string literal starting at `i` (which points at the quote). Returns the value and the index after it, or null for a template literal with interpolation. */
+function readString(src, i) {
+    const quote = src[i];
+    // A ' or " string cannot span lines. When there is no closing quote before
+    // the newline this is not a string at all — an apostrophe in JSX text
+    // ("couldn't"), a quote inside a regex (/['"]/) — and treating it as one
+    // swallowed the rest of the file, routes included.
+    if (quote !== "`") {
+        let k = i + 1;
+        while (k < src.length && src[k] !== quote && src[k] !== "\n")
+            k += src[k] === "\\" ? 2 : 1;
+        if (src[k] !== quote)
+            return { value: null, end: i + 1 };
+    }
+    let j = i + 1;
+    let value = "";
+    let interpolated = false;
+    while (j < src.length && src[j] !== quote) {
+        if (src[j] === "\\") {
+            value += src[j + 1] ?? "";
+            j += 2;
+            continue;
+        }
+        if (quote === "`" && src[j] === "$" && src[j + 1] === "{")
+            interpolated = true;
+        value += src[j];
+        j += 1;
+    }
+    return { value: interpolated ? null : value, end: j + 1 };
+}
+/** Route records written as object literals, in source order, with their nesting. */
+export function readRouteObjects(src) {
+    const frames = [];
+    const stack = [];
+    let lastSignificant = "";
+    let i = 0;
+    const nearestObj = () => {
+        for (let k = stack.length - 1; k >= 0; k--)
+            if (frames[stack[k]].kind === "obj")
+                return stack[k];
+        return -1;
+    };
+    while (i < src.length) {
+        const c = src[i];
+        if (c === "/" && src[i + 1] === "/") {
+            while (i < src.length && src[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "*") {
+            const end = src.indexOf("*/", i + 2);
+            i = end === -1 ? src.length : end + 2;
+            continue;
+        }
+        if (c === '"' || c === "'" || c === "`") {
+            const { value, end } = readString(src, i);
+            const owner = nearestObj();
+            const top = stack[stack.length - 1];
+            if (owner !== -1 && value !== null) {
+                const f = frames[owner];
+                // A quoted KEY: `'path': '/x'`.
+                let k = end;
+                while (k < src.length && /\s/.test(src[k]))
+                    k += 1;
+                if (top === owner && (lastSignificant === "{" || lastSignificant === ",") && src[k] === ":") {
+                    f.currentKey = value;
+                    f.keys.add(value);
+                }
+                else if (top === owner && f.currentKey === "path" && lastSignificant === ":") {
+                    f.path = value;
+                }
+                else if (f.currentKey === "loadChildren" && /import\s*\(\s*$/.test(src.slice(Math.max(0, i - 12), i))) {
+                    f.lazyImport = value;
+                }
+            }
+            lastSignificant = "s";
+            i = end;
+            continue;
+        }
+        if (c === "{" || c === "[" || c === "(") {
+            // `{` opens an object literal when it follows something a value can follow.
+            const isObject = c === "{" && /[[(,:=?]|^$|r/.test(lastSignificant === "return" ? "r" : lastSignificant);
+            const enclosing = nearestObj();
+            frames.push({ kind: isObject ? "obj" : "other", parent: enclosing, keys: new Set(), via: enclosing === -1 ? undefined : frames[enclosing].currentKey });
+            stack.push(frames.length - 1);
+            lastSignificant = c;
+            i += 1;
+            continue;
+        }
+        if (c === "}" || c === "]" || c === ")") {
+            const idx = stack.pop();
+            void idx;
+            lastSignificant = c;
+            i += 1;
+            continue;
+        }
+        if (/[A-Za-z_$]/.test(c)) {
+            let j = i;
+            while (j < src.length && /[\w$]/.test(src[j]))
+                j += 1;
+            const word = src.slice(i, j);
+            const owner = nearestObj();
+            const top = stack[stack.length - 1];
+            let k = j;
+            while (k < src.length && /\s/.test(src[k]))
+                k += 1;
+            if (owner !== -1 && top === owner && (lastSignificant === "{" || lastSignificant === ",")) {
+                if (src[k] === ":") {
+                    frames[owner].currentKey = word;
+                    frames[owner].keys.add(word);
+                }
+                else if (src[k] === "," || src[k] === "}") {
+                    frames[owner].keys.add(word); // shorthand property, e.g. `{ path, component }` — no literal to read
+                    frames[owner].currentKey = undefined;
+                }
+            }
+            lastSignificant = word === "return" ? "return" : "w";
+            i = j;
+            continue;
+        }
+        if (!/\s/.test(c))
+            lastSignificant = c;
+        i += 1;
+    }
+    // Keep the frames that are route records, in source order, and re-link parents among them.
+    const isRecord = (f) => f.path !== undefined && ROUTE_RECORD_KEYS.some((k) => f.keys.has(k));
+    // A record belongs to the route tree only when every object between it and
+    // the top was entered through `children` (or `routes`, the router's own
+    // option). `{ path, component }` under `meta.breadcrumbs` or `props.link` is
+    // data carried BY a route, not a route.
+    const inRouteTree = (f) => {
+        for (let cur = f; cur && cur.parent !== -1; cur = frames[cur.parent]) {
+            if (cur.via !== "children" && cur.via !== "routes")
+                return false;
+        }
+        return true;
+    };
+    const recordFrames = frames.map((f, index) => ({ f, index })).filter(({ f }) => f.kind === "obj" && isRecord(f) && inRouteTree(f));
+    const position = new Map(recordFrames.map(({ index }, pos) => [index, pos]));
+    return recordFrames.map(({ f }) => {
+        let p = f.parent;
+        while (p !== -1 && !position.has(p))
+            p = frames[p].parent;
+        const redirectOnly = (f.keys.has("redirect") || f.keys.has("redirectTo")) &&
+            !["element", "Component", "component", "components", "loadComponent", "lazy"].some((k) => f.keys.has(k));
+        return { path: f.path, parent: p === -1 ? -1 : position.get(p), redirectOnly, lazyImport: f.lazyImport };
+    });
+}
+/**
+ * The source with comments blanked out, offsets preserved. `<Route>` tags are
+ * found by pattern, so a commented-out route would otherwise be read as live.
+ */
+export function maskComments(src) {
+    const out = src.split("");
+    let i = 0;
+    const blank = (from, to) => {
+        for (let k = from; k < to && k < out.length; k++)
+            if (out[k] !== "\n")
+                out[k] = " ";
+    };
+    while (i < src.length) {
+        const c = src[i];
+        if (c === '"' || c === "'" || c === "`") {
+            i = readString(src, i).end;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "/" && src[i - 1] !== ":") {
+            let j = i;
+            while (j < src.length && src[j] !== "\n")
+                j += 1;
+            blank(i, j);
+            i = j;
+            continue;
+        }
+        if (c === "/" && src[i + 1] === "*") {
+            const end = src.indexOf("*/", i + 2);
+            const j = end === -1 ? src.length : end + 2;
+            blank(i, j);
+            i = j;
+            continue;
+        }
+        i += 1;
+    }
+    return out.join("");
+}
+/** `<Route path="…">` elements (React Router), with their nesting. */
+export function readRouteElements(source) {
+    const src = maskComments(source);
+    const out = [];
+    const open = [];
+    const tagRe = /<\/?Route\b/g;
+    let m;
+    while ((m = tagRe.exec(src))) {
+        if (m[0].startsWith("</")) {
+            open.pop();
+            continue;
+        }
+        // Scan to the end of the opening tag, stepping over `{…}` expressions and
+        // strings: `element={<Orders />}` contains a `>` that is not the tag's own.
+        let i = m.index + m[0].length;
+        let depth = 0;
+        let attrs = "";
+        while (i < src.length) {
+            const c = src[i];
+            if (c === '"' || c === "'" || c === "`") {
+                const { end } = readString(src, i);
+                attrs += src.slice(i, end);
+                i = end;
+                continue;
+            }
+            if (c === "{")
+                depth += 1;
+            else if (c === "}")
+                depth -= 1;
+            else if (c === ">" && depth === 0)
+                break;
+            attrs += c;
+            i += 1;
+        }
+        const selfClosing = attrs.trimEnd().endsWith("/");
+        const pathAttr = /(?:^|\s)path\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*"([^"]*)"\s*\}|\{\s*'([^']*)'\s*\})/.exec(attrs);
+        const isIndex = /(?:^|\s)index(?=[\s/>=]|$)/.test(attrs);
+        const parent = open.length > 0 ? open[open.length - 1] : -1;
+        let self = -1;
+        if (pathAttr || isIndex) {
+            out.push({ path: pathAttr ? (pathAttr[1] ?? pathAttr[2] ?? pathAttr[3] ?? pathAttr[4] ?? "") : "", parent, redirectOnly: false });
+            self = out.length - 1;
+        }
+        // A pathless layout route still nests its children under ITS parent.
+        if (!selfClosing)
+            open.push(self === -1 ? parent : self);
+        tagRe.lastIndex = i + 1;
+    }
+    return out;
+}
+const tidy = (p) => `/${p}`.replace(/\/+/g, "/").replace(/(.)\/$/, "$1");
+/** The absolute path of one record, or null when it (or an ancestor) is a wildcard. */
+export function recordPath(records, idx, prefix = "", absoluteTopOnly = false) {
+    const r = records[idx];
+    if (/[*]/.test(r.path))
+        return null;
+    // An absolute child path is absolute (React Router and Vue Router both allow it).
+    if (r.path.startsWith("/"))
+        return tidy(r.path);
+    // A relative path at the top of a file that is not provably the router's
+    // root has an unknown parent; joining it onto "/" would invent a page.
+    if (r.parent === -1 && absoluteTopOnly)
+        return null;
+    const base = r.parent === -1 ? prefix : recordPath(records, r.parent, prefix, absoluteTopOnly);
+    return base === null ? null : tidy(`${base}/${r.path}`);
+}
+/** Join nested route records into absolute paths. Wildcards, redirect-only records and lazily loaded parents are not pages themselves. */
+export function resolveRoutes(records, prefix = "", absoluteTopOnly = false) {
+    const out = new Set();
+    records.forEach((r, idx) => {
+        if (r.redirectOnly || r.lazyImport)
+            return;
+        const p = recordPath(records, idx, prefix, absoluteTopOnly);
+        if (p !== null)
+            out.add(p);
+    });
+    return [...out];
+}
+/**
+ * Text that marks a file as the ENTRY of a router: the place where the router
+ * is created or mounted at the app's root. A relative top-level path there
+ * means "relative to /".
+ */
+const ENTRY_MARKERS = /createBrowserRouter\s*\(|createHashRouter\s*\(|createMemoryRouter\s*\(|<RouterProvider\b|<BrowserRouter\b|<HashRouter\b|<MemoryRouter\b|createRouter\s*\(|new\s+VueRouter\s*\(|RouterModule\s*\.\s*forRoot\s*\(|provideRouter\s*\(/;
+/**
+ * `<Routes>` and `useRoutes()` mount routes wherever they are rendered — at
+ * the root, or inside a component reached through a splat route
+ * (`<Route path="admin/*">`). In the second case their paths are relative to
+ * that parent, which this reader cannot see, so a file with only these markers
+ * is trusted for relative paths only when it is the single such file in the
+ * project.
+ */
+const MOUNT_MARKERS = /<Routes\b|useRoutes\s*\(/;
+/** Angular's conventional root files: relative top-level paths there are relative to "/". */
+const ANGULAR_ROOT_FILENAMES = /(^|[\\/])(app\.routes|app-routing\.module)\.(ts|js|mjs)$/;
+/** Conventional names for router files in general. Read, but only their ABSOLUTE top-level paths are trusted. */
+const ROUTER_FILENAMES = /(^|[\\/])(routes|router|router[\\/]index)\.(ts|tsx|js|jsx|mjs)$/;
+const ROUTER_MENTION = /react-router|vue-router|@angular\/router|<Route\b|createBrowserRouter|RouterModule|provideRouter/;
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+/** Matched against the path RELATIVE to the scanned root: a checkout that happens to live under a directory called `build` or `tests` must still be read. */
+const SKIP = /(^|[\\/])(node_modules|dist|build|coverage|\.next|\.nuxt|\.svelte-kit|__tests__|e2e|tests?)([\\/]|$)|\.(spec|test|stories|d)\.[a-z]+$/;
+/** Files read for routes. Candidates are listed first, so the budget is spent on likely router files. */
+const MAX_FILES = 600;
+/** Paths listed before giving up on a very large tree. */
+const MAX_LISTED = 20_000;
+const MAX_DEPTH = 14;
+const MAX_BYTES = 400_000;
+const LIKELY_ROUTER_FILE = /(^|[\\/])(app\.routes|app-routing\.module|routes|router|index|main|App|app)\.(ts|tsx|js|jsx|mjs)$|rout/i;
+function sourceFiles(root) {
+    const listed = [];
+    let truncated = false;
+    const walk = (dir, depth) => {
+        if (depth > MAX_DEPTH || listed.length >= MAX_LISTED) {
+            truncated = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable directory: nothing to read routes from
+        }
+        for (const e of entries) {
+            const p = path.join(dir, e.name);
+            if (e.name.startsWith(".") || SKIP.test(path.relative(root, p)))
+                continue;
+            if (e.isDirectory())
+                walk(p, depth + 1);
+            else if (SOURCE_EXT.test(e.name))
+                listed.push(p);
+        }
+    };
+    walk(root, 0);
+    // Likely router files first; within each group, shallower paths first.
+    const depthOf = (f) => f.split(path.sep).length;
+    listed.sort((a, b) => Number(LIKELY_ROUTER_FILE.test(b)) - Number(LIKELY_ROUTER_FILE.test(a)) || depthOf(a) - depthOf(b) || a.localeCompare(b));
+    if (listed.length > MAX_FILES)
+        truncated = true;
+    return { files: listed.slice(0, MAX_FILES), truncated };
+}
+/** Resolve a relative import to a file INSIDE `root`. Bare and aliased specifiers, and anything outside the project, are not followed. */
+function resolveImport(root, fromFile, spec) {
+    if (!spec.startsWith("."))
+        return null;
+    const base = path.resolve(path.dirname(fromFile), spec);
+    for (const candidate of [base, ...[".ts", ".tsx", ".js", ".jsx", ".mjs"].map((x) => base + x), ...["index.ts", "index.js"].map((x) => path.join(base, x))]) {
+        const rel = path.relative(root, candidate);
+        if (rel.startsWith("..") || path.isAbsolute(rel))
+            continue;
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+            return candidate;
+    }
+    return null;
+}
+function readSource(file) {
+    try {
+        if (fs.statSync(file).size > MAX_BYTES)
+            return null;
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The file that holds a lazily loaded branch's routes. Angular's classic shape
+ * points `loadChildren` at an NgModule (`admin.module`) whose routes live in
+ * its sibling `admin-routing.module`; the standalone shape points straight at
+ * the routes file.
+ */
+function lazyRouteFile(root, fromFile, spec) {
+    const direct = resolveImport(root, fromFile, spec);
+    if (direct) {
+        const src = readSource(direct);
+        if (src !== null && readRouteObjects(src).length > 0)
+            return direct;
+    }
+    const sibling = /\.module$/.test(spec) ? resolveImport(root, fromFile, spec.replace(/\.module$/, "-routing.module")) : null;
+    return sibling ?? null;
+}
+/** Routes of one file, following Angular `loadChildren` imports: each child file's routes are prefixed with the path of the record that loads it. */
+function routesOfFile(ctx, file, prefix, absoluteTopOnly) {
+    // A child loaded under two parents keeps the first prefix only: a miss, never an invention.
+    if (ctx.seen.has(file))
+        return [];
+    ctx.seen.add(file);
+    const src = readSource(file);
+    if (src === null)
+        return [];
+    const records = readRouteObjects(src);
+    const out = [...resolveRoutes(records, prefix, absoluteTopOnly), ...resolveRoutes(readRouteElements(src), prefix, absoluteTopOnly)];
+    records.forEach((r, idx) => {
+        if (!r.lazyImport)
+            return;
+        const lazyPrefix = recordPath(records, idx, prefix, absoluteTopOnly);
+        if (lazyPrefix === null)
+            return;
+        // The record's own path is a page whichever way the branch resolves: it is
+        // where the lazily loaded module mounts.
+        out.push(lazyPrefix);
+        const child = lazyRouteFile(ctx.root, file, r.lazyImport);
+        if (child)
+            out.push(...routesOfFile(ctx, child, lazyPrefix === "/" ? "" : lazyPrefix, absoluteTopOnly));
+        else
+            ctx.unresolved.push(r.lazyImport);
+    });
+    return out;
+}
+/** Read routes from router configuration under `frontendDir`. Empty when none is recognisable. */
+export function codeRoutes(frontendDir) {
+    const srcDir = fs.existsSync(path.join(frontendDir, "src")) ? path.join(frontendDir, "src") : frontendDir;
+    const { files: candidates, truncated } = sourceFiles(srcDir);
+    const mentions = [];
+    for (const file of candidates) {
+        const src = readSource(file);
+        if (src !== null && ROUTER_MENTION.test(src))
+            mentions.push({ file, src: maskComments(src) });
+    }
+    const mountFiles = mentions.filter(({ src }) => MOUNT_MARKERS.test(src));
+    const roots = [];
+    for (const { file, src } of mentions) {
+        const entry = ENTRY_MARKERS.test(src) || ANGULAR_ROOT_FILENAMES.test(file);
+        // The only file that mounts routes must be the root, wherever the router itself is created.
+        const soleMount = MOUNT_MARKERS.test(src) && mountFiles.length === 1;
+        if (entry || soleMount)
+            roots.push({ file, trusted: true });
+        else if (MOUNT_MARKERS.test(src) || ROUTER_FILENAMES.test(file))
+            roots.push({ file, trusted: false });
+    }
+    // Trusted roots first, so a child file they load lazily is claimed with its prefix before it can be read bare.
+    roots.sort((a, b) => Number(b.trusted) - Number(a.trusted));
+    const ctx = { root: frontendDir, seen: new Set(), unresolved: [] };
+    const routes = new Set();
+    const files = [];
+    for (const { file, trusted } of roots) {
+        const found = routesOfFile(ctx, file, "", !trusted);
+        if (found.length > 0)
+            files.push(path.relative(frontendDir, file));
+        for (const r of found)
+            routes.add(r);
+    }
+    return { routes: [...routes].sort(), files, unresolved: [...new Set(ctx.unresolved)], truncated };
+}