summer-engine 2.8.2 → 3.0.0

package/dist/core/capabilities/navigation/open.js

@@ -0,0 +1,567 @@
+/**
+ * `summer open` / `summer_open` — one behavior, two faces (CONTRACT §3).
+ *
+ * Resolve a target (id, intent phrase, res:// path or summerengine.com path)
+ * against the product map (./targets.ts), then either open it — the browser
+ * for web targets (through /login?returnUrl= when login is required and the
+ * CLI is not logged in), the running Summer Engine via the local API for
+ * editor targets — or, with `open: false`, return what would open without
+ * opening.
+ *
+ * Editor targets are FORWARDED, not implemented here: when the engine
+ * advertises `capabilities.navigation` the tool sends the one-table op
+ * `Navigate { target, ...args }`; on an engine that predates it the few ids the
+ * original ops can serve (scene, node, script, file, the three docks) use those
+ * ops and everything else answers `engine_lacks_op`. See NAVIGATION-PLAN.md.
+ *
+ * Both faces call runOpen(); the CLI (tool-dispatch + `summer open`) and the
+ * MCP tool (src/mcp/tools/navigation-tools.ts) only differ in how the engine
+ * client and the browser launcher are supplied.
+ */
+import { z } from "zod";
+import { extractOpError } from "../engine-receipt.js";
+import { NAV_TARGETS, WEB_CATALOG, getNavTarget, } from "./targets.js";
+/** The ONE argument shape both faces validate with (mirrors
+ *  library/tools/open/resource.yaml input_schema; parity-tested). */
+export const openArgsShape = {
+    target: z
+        .string()
+        .optional()
+        .describe('Where to go: a target id (billing, my-games, mcp-guide, scene, node, inspector, …), an intent phrase ("change my plan"), a res:// path, or a summerengine.com path ("/pricing"). Omit to list every target.'),
+    params: z
+        .record(z.string())
+        .optional()
+        .describe("Slot values for the target: gameId, section, username, version, guide (agent name or guide slug), path (res://…), node, scene, line, col, tab."),
+    surface: z
+        .enum(["auto", "web", "editor"])
+        .optional()
+        .describe('Restrict matching to the website or the editor. "auto" (default) considers both.'),
+    open: z
+        .boolean()
+        .optional()
+        .describe("Default true: open it. false = resolve only — return the URL or engine op and open nothing (works without the engine and without a browser). The CLI's --print."),
+};
+export const openArgsSchema = z.object(openArgsShape).strict();
+// ---------------------------------------------------------------------------
+// Safety rails
+// ---------------------------------------------------------------------------
+/** The only origins this tool ever opens a browser on: summerengine.com and its
+ *  subdomains, plus loopback for local web development. A configured gateway
+ *  (SUMMER_GATEWAY_URL / gateway.url) that points anywhere else is refused —
+ *  the API calls may go there, a browser launch never does. */
+export function isAllowedNavigationOrigin(origin) {
+    let host;
+    try {
+        host = new URL(origin).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return (host === "summerengine.com" ||
+        host.endsWith(".summerengine.com") ||
+        host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "[::1]" ||
+        host === "::1");
+}
+/** A project resource path the engine may be asked to open: `res://` plus a
+ *  plain relative path — no parent segments, no backslashes, no percent
+ *  escapes, nothing that could name a file outside the project. Returns the
+ *  problem, or null when the path is acceptable. */
+export function resPathProblem(value) {
+    if (!value.startsWith("res://"))
+        return `must start with res:// (got "${value}")`;
+    const rest = value.slice("res://".length);
+    if (rest.length === 0)
+        return "must name a file or folder under res://";
+    if (rest.includes("\\"))
+        return "must use forward slashes";
+    if (rest.includes("%"))
+        return "must not contain percent escapes";
+    if (rest.startsWith("/"))
+        return "must be relative to res:// (no leading slash)";
+    if (rest.split("/").some((segment) => segment === ".." || segment === "."))
+        return "must not contain . or .. segments";
+    if (/[\u0000-\u001f]/.test(rest))
+        return "must not contain control characters";
+    return null;
+}
+/** Launch the browser; a failed launch is a result, not a crash. */
+async function launch(deps, url) {
+    try {
+        await deps.openUrl(url);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+function openFailed(url, error, extra = {}) {
+    return {
+        ok: false,
+        action: "open_failed",
+        url,
+        ...extra,
+        hint: `Could not launch a browser on this machine (${error}). Nothing opened — hand the user the url instead.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+const STOPWORDS = new Set([
+    "the", "a", "an", "my", "me", "i", "to", "of", "in", "on", "for", "please", "open", "show",
+    "go", "page", "want", "up", "take", "it", "is", "do", "how", "can", "you", "where", "with",
+    "and", "that", "this", "at", "into", "see", "let", "get", "bring", "our", "your", "im", "am",
+]);
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[’']/g, "")
+        .split(/[^a-z0-9]+/)
+        .filter((tok) => tok.length > 0 && !STOPWORDS.has(tok))
+        .map((tok) => (tok.length > 3 && tok.endsWith("s") ? tok.slice(0, -1) : tok));
+}
+function phraseScore(queryTokens, phrase) {
+    const phraseTokens = tokenize(phrase);
+    if (queryTokens.length === 0 || phraseTokens.length === 0)
+        return 0;
+    if (queryTokens.join(" ") === phraseTokens.join(" "))
+        return 1;
+    const phraseSet = new Set(phraseTokens);
+    const overlap = queryTokens.filter((tok) => phraseSet.has(tok)).length;
+    if (overlap === 0)
+        return 0;
+    const coverage = overlap / queryTokens.length;
+    const precision = overlap / phraseTokens.length;
+    return coverage * (0.7 + 0.3 * precision);
+}
+function scoreTarget(queryTokens, target) {
+    let best = 0;
+    for (const phrase of [target.id.replace(/-/g, " "), target.title, ...target.intents, ...(target.aliases ?? [])]) {
+        best = Math.max(best, phraseScore(queryTokens, phrase));
+        if (best === 1)
+            break;
+    }
+    return best;
+}
+const MIN_SCORE = 0.5;
+/** Rank every target for a free-text query. Exported for tests. */
+export function rankTargets(query, surface = "auto") {
+    const queryTokens = tokenize(query);
+    const candidates = NAV_TARGETS.filter((target) => surface === "auto" || target.surface === surface);
+    return candidates
+        .map((target) => ({
+        id: target.id,
+        surface: target.surface,
+        title: target.title,
+        score: round(scoreTarget(queryTokens, target)),
+    }))
+        .filter((match) => match.score >= MIN_SCORE)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+function round(value) {
+    return Math.round(value * 1000) / 1000;
+}
+function resolveResourcePath(path, params) {
+    const problem = resPathProblem(path);
+    if (problem) {
+        return { kind: "not_found", matches: [], hint: `Refused resource path: ${problem}.` };
+    }
+    const lower = path.toLowerCase();
+    const id = lower.endsWith(".tscn") || lower.endsWith(".scn") ? "scene" : lower.endsWith(".gd") || lower.endsWith(".cs") ? "script" : "file";
+    return { kind: "target", target: getNavTarget(id), params: { ...params, path } };
+}
+/** Redirect-style query params on an unmapped path must be relative same-origin
+ *  paths; a full URL there would turn the login page into an open redirect. */
+const REDIRECT_PARAMS = new Set(["returnurl", "redirect", "next", "callbackurl", "redirect_uri", "return_to"]);
+export function unsafeRedirectParam(pathWithQuery) {
+    const q = pathWithQuery.indexOf("?");
+    if (q === -1)
+        return null;
+    for (const [key, value] of new URLSearchParams(pathWithQuery.slice(q + 1))) {
+        if (!REDIRECT_PARAMS.has(key.toLowerCase()))
+            continue;
+        if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\"))
+            return key;
+    }
+    return null;
+}
+function resolveWebPath(path, params) {
+    const badParam = unsafeRedirectParam(path);
+    if (badParam) {
+        return { kind: "not_found", matches: [], hint: `Refused: query parameter "${badParam}" must be a relative summerengine.com path (it is used as a redirect target).` };
+    }
+    const wanted = path.replace(/\/+$/, "") || "/";
+    for (const target of NAV_TARGETS) {
+        if (!target.web || target.web.origin !== "gateway")
+            continue;
+        const literal = target.web.path.replace(/\[\/\{[a-zA-Z]+\}\]/g, "");
+        if (literal.includes("{"))
+            continue;
+        if (literal.replace(/\/+$/, "") === wanted || literal === wanted) {
+            return { kind: "target", target, params };
+        }
+    }
+    return { kind: "url", url: path };
+}
+export function resolveTarget(rawTarget, params, surface) {
+    const raw = rawTarget.trim();
+    if (raw.startsWith("res://"))
+        return resolveResourcePath(raw, params);
+    if (raw.startsWith("/") && !raw.startsWith("//"))
+        return resolveWebPath(raw, params);
+    const direct = getNavTarget(raw.toLowerCase().replace(/\s+/g, "-"));
+    if (direct && (surface === "auto" || direct.surface === surface)) {
+        return { kind: "target", target: direct, params };
+    }
+    const matches = rankTargets(raw, surface);
+    if (matches.length === 0) {
+        return {
+            kind: "not_found",
+            matches,
+            hint: `No destination matches "${raw.length > 80 ? raw.slice(0, 77) + "..." : raw}". Run 'summer open --list' (or call summer_open with no target) to see every target, or pass a res:// path or a summerengine.com path.`,
+        };
+    }
+    const [top, second] = matches;
+    const clear = top.score >= 0.999
+        ? !second || second.score < 0.999
+        : top.score >= 0.6 && (!second || top.score - second.score >= 0.25);
+    if (clear)
+        return { kind: "target", target: getNavTarget(top.id), params };
+    return { kind: "ambiguous", matches: matches.slice(0, 5) };
+}
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+function summarize(target, availability) {
+    return {
+        id: target.id,
+        surface: target.surface,
+        title: target.title,
+        description: target.description,
+        requires: target.requires,
+        ...(target.params ? { params: target.params } : {}),
+        ...(availability ? { availability } : {}),
+    };
+}
+class ParamError extends Error {
+}
+function normalizeParam(param, value) {
+    const clean = value.trim();
+    if (!param.values)
+        return clean;
+    const lower = clean.toLowerCase();
+    if (param.values.includes(lower))
+        return lower;
+    const alias = param.valueAliases?.[lower];
+    if (alias)
+        return alias;
+    throw new ParamError(`${param.name} must be one of: ${param.values.join(", ")}` +
+        (param.valueAliases ? ` (or an alias: ${Object.keys(param.valueAliases).join(", ")})` : ""));
+}
+/** Fill a web path template. `{slot}` required, `[/{slot}]` optional. */
+export function renderWebPath(template, params, declared = []) {
+    const byName = new Map(declared.map((param) => [param.name, param]));
+    const lookup = (name) => {
+        const value = params[name];
+        if (value === undefined || value === "")
+            return undefined;
+        const param = byName.get(name);
+        return param ? normalizeParam(param, value) : value.trim();
+    };
+    let out = template.replace(/\[\/\{([a-zA-Z]+)\}\]/g, (_m, name) => {
+        const value = lookup(name);
+        return value === undefined ? "" : `/${encodeURIComponent(value)}`;
+    });
+    out = out.replace(/\{([a-zA-Z]+)\}/g, (_m, name) => {
+        const value = lookup(name);
+        if (value === undefined)
+            throw new ParamError(`Missing required param: ${name}`);
+        return encodeURIComponent(value);
+    });
+    return out;
+}
+function requireParams(meta, params) {
+    for (const param of meta.params ?? []) {
+        const value = params[param.name];
+        if (param.required && (value === undefined || value === "")) {
+            throw new ParamError(`Missing required param: ${param.name}`);
+        }
+        // Resource paths are forwarded to the engine as-is; refuse anything that
+        // does not name a file under the project.
+        if ((param.name === "path" || param.name === "scene") && meta.id !== "assistant" && value !== undefined && value !== "") {
+            const problem = resPathProblem(value);
+            if (problem)
+                throw new ParamError(`${param.name} ${problem}`);
+        }
+    }
+}
+/** Numeric args (line, col) travel as numbers; everything else as trimmed strings. */
+function argValue(name, value) {
+    const trimmed = value.trim();
+    return (name === "line" || name === "col") && /^\d+$/.test(trimmed) ? Number.parseInt(trimmed, 10) : trimmed;
+}
+/** The one-table op: Navigate { target, ...args }. */
+export function buildNavigateOp(meta, params) {
+    const op = { op: "Navigate", target: meta.navigate.target, ...(meta.navigate.fixed ?? {}) };
+    for (const [paramName, argName] of Object.entries(meta.navigate.map ?? {})) {
+        const value = params[paramName];
+        if (value !== undefined && value !== "")
+            op[argName] = argValue(argName, value);
+    }
+    return op;
+}
+/** The pre-Navigate op for engines that predate the table (only some rows have one). */
+export function buildLegacyOp(meta, params) {
+    if (!meta.legacy)
+        return null;
+    const op = { op: meta.legacy.op, ...(meta.legacy.fixed ?? {}) };
+    for (const [paramName, field] of Object.entries(meta.legacy.map ?? {})) {
+        const value = params[paramName];
+        if (value !== undefined && value !== "")
+            op[field] = value.trim();
+    }
+    return op;
+}
+function mainSceneFrom(projectState) {
+    const root = (projectState ?? {});
+    const data = (root.data ?? root);
+    const entries = data.entries;
+    if (Array.isArray(entries)) {
+        for (const entry of entries) {
+            const item = (entry ?? {});
+            if (item.key === "application/run/main_scene" || item.key === "run/main_scene") {
+                return typeof item.value === "string" && item.value.length > 0 ? item.value : null;
+            }
+        }
+    }
+    for (const key of ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) {
+        const value = data[key] ?? root[key];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+/** Which ids the connected engine can open. undefined = engine predates the advert. */
+export function advertisedNavigation(client) {
+    const targets = client.getEngineCapabilities?.()?.navigation?.targets;
+    return targets ? new Set(targets.map((t) => t.id)) : undefined;
+}
+export function editorAvailability(meta, advertised) {
+    if (advertised)
+        return advertised.has(meta.navigate.target) ? "available" : "unavailable";
+    return meta.legacy ? "legacy" : "unavailable";
+}
+export function listTargets(surface = "auto", advertised) {
+    return NAV_TARGETS.filter((target) => surface === "auto" || target.surface === surface).map((target) => target.editor
+        ? summarize(target, advertised === "unknown" ? "unknown" : editorAvailability(target.editor, advertised))
+        : summarize(target));
+}
+// ---------------------------------------------------------------------------
+// The behavior
+// ---------------------------------------------------------------------------
+export async function runOpen(args, deps) {
+    const surface = args.surface ?? "auto";
+    const params = args.params ?? {};
+    const print = args.open === false;
+    const docsOrigin = deps.docsOrigin ?? WEB_CATALOG.docsBase;
+    if (!args.target || args.target.trim() === "") {
+        let advertised = "unknown";
+        if (surface !== "web") {
+            try {
+                advertised = advertisedNavigation(await deps.engine());
+            }
+            catch {
+                advertised = "unknown";
+            }
+        }
+        return {
+            ok: true,
+            action: "listed",
+            targets: listTargets(surface, advertised),
+            hint: "Pass a target id, an intent phrase, a res:// path, or a summerengine.com path. Editor availability comes from the connected engine: available = Navigate op; legacy = served by an older op; unavailable = update Summer Engine; unknown = engine not running.",
+        };
+    }
+    const gateway = (await deps.gatewayUrl()).replace(/\/+$/, "");
+    if (!isAllowedNavigationOrigin(gateway) || !isAllowedNavigationOrigin(docsOrigin)) {
+        return {
+            ok: false,
+            action: "blocked_origin",
+            hint: `Refusing to open a browser on ${isAllowedNavigationOrigin(gateway) ? docsOrigin : gateway}: summer_open only opens summerengine.com, its subdomains, and loopback. Check gateway.url / SUMMER_GATEWAY_URL.`,
+        };
+    }
+    // A full URL is accepted only on the two origins this tool ever opens; the
+    // path is then resolved like a summerengine.com path.
+    let rawTarget = args.target.trim();
+    if (/^https?:\/\//i.test(rawTarget)) {
+        let parsed;
+        try {
+            parsed = new URL(rawTarget);
+        }
+        catch {
+            return { ok: false, action: "not_found", hint: `"${rawTarget}" is not a valid URL.` };
+        }
+        const sameGateway = parsed.origin === gateway || parsed.origin.replace("://www.", "://") === gateway.replace("://www.", "://");
+        if (parsed.origin === docsOrigin) {
+            const url = `${docsOrigin}${parsed.pathname}${parsed.search}`;
+            if (print)
+                return { ok: true, action: "printed", url, unmapped: true };
+            const failure = await launch(deps, url);
+            if (failure)
+                return openFailed(url, failure, { unmapped: true });
+            return { ok: true, action: "opened", url, opened_url: url, unmapped: true };
+        }
+        if (!sameGateway) {
+            return {
+                ok: false,
+                action: "not_found",
+                hint: `summer_open only opens ${gateway} and ${docsOrigin}; "${parsed.origin}" is not a Summer destination.`,
+            };
+        }
+        rawTarget = `${parsed.pathname}${parsed.search}`;
+    }
+    const resolution = resolveTarget(rawTarget, params, surface);
+    if (resolution.kind === "not_found") {
+        return { ok: false, action: "not_found", matches: resolution.matches, hint: resolution.hint };
+    }
+    if (resolution.kind === "ambiguous") {
+        return {
+            ok: false,
+            action: "ambiguous",
+            matches: resolution.matches,
+            hint: `"${args.target.length > 80 ? args.target.slice(0, 77) + "..." : args.target}" matches several destinations. Call again with one of the ids listed in matches.`,
+        };
+    }
+    if (resolution.kind === "url") {
+        const url = `${gateway}${resolution.url}`;
+        const base = {
+            ok: true,
+            action: print ? "printed" : "opened",
+            url,
+            unmapped: true,
+            hint: "This path is not in the product map; it was opened on the Summer gateway origin as given.",
+        };
+        if (print)
+            return base;
+        const failure = await launch(deps, url);
+        if (failure)
+            return openFailed(url, failure, { unmapped: true });
+        return { ...base, opened_url: url };
+    }
+    const { target } = resolution;
+    // ---- web -----------------------------------------------------------------
+    if (target.web) {
+        const summary = summarize(target);
+        let path;
+        try {
+            path = renderWebPath(target.web.path, resolution.params, target.params);
+        }
+        catch (error) {
+            if (error instanceof ParamError)
+                return { ok: false, action: "invalid_params", target: summary, hint: error.message };
+            throw error;
+        }
+        const origin = target.web.origin === "docs" ? docsOrigin : gateway;
+        const url = `${origin}${path}`;
+        const needsLogin = target.requires.login === true && target.web.origin === "gateway";
+        const loggedIn = needsLogin ? await deps.isLoggedIn() : undefined;
+        const loginUrl = needsLogin
+            ? `${gateway}${WEB_CATALOG.login.path}?${WEB_CATALOG.login.returnParam}=${encodeURIComponent(path)}`
+            : undefined;
+        const result = {
+            ok: true,
+            action: print ? "printed" : "opened",
+            target: summary,
+            url,
+            ...(loginUrl ? { login_url: loginUrl } : {}),
+            ...(loggedIn !== undefined ? { logged_in: loggedIn } : {}),
+        };
+        if (print)
+            return result;
+        const toOpen = needsLogin && loggedIn === false ? loginUrl : url;
+        const failure = await launch(deps, toOpen);
+        if (failure)
+            return openFailed(toOpen, failure, { target: summary, ...(loginUrl ? { login_url: loginUrl } : {}), ...(loggedIn !== undefined ? { logged_in: loggedIn } : {}) });
+        return {
+            ...result,
+            opened_url: toOpen,
+            ...(needsLogin && loggedIn === false
+                ? { hint: "Not logged in on this machine, so the login page was opened with returnUrl set; the destination loads after sign-in." }
+                : {}),
+        };
+    }
+    // ---- editor: forward to the engine's table -------------------------------
+    const meta = target.editor;
+    try {
+        requireParams(meta, resolution.params);
+    }
+    catch (error) {
+        if (error instanceof ParamError)
+            return { ok: false, action: "invalid_params", target: summarize(target), hint: error.message };
+        throw error;
+    }
+    let client;
+    try {
+        client = await deps.engine();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const navigateOp = buildNavigateOp(meta, resolution.params);
+        if (meta.mainSceneDefault && navigateOp.path === undefined)
+            navigateOp.path = "<application/run/main_scene>";
+        const summary = summarize(target, meta.legacy ? "legacy" : "unknown");
+        if (print) {
+            return { ok: true, action: "printed", target: summary, op: navigateOp, engine: { running: false, error: message } };
+        }
+        return {
+            ok: false,
+            action: "engine_not_running",
+            target: summary,
+            op: navigateOp,
+            engine: { running: false, error: message },
+            hint: `Summer Engine is not running (or no project is open), so nothing was opened. Start it with 'summer run <project>' or open the project in the Summer desktop app, then retry. What would open: ${target.title} — ${target.description}`,
+        };
+    }
+    const version = client.getEngineVersion?.();
+    const advertised = advertisedNavigation(client);
+    const availability = editorAvailability(meta, advertised);
+    const summary = summarize(target, availability);
+    const engine = { running: true, version, navigation: advertised !== undefined };
+    if (availability === "unavailable") {
+        const navigateOp = buildNavigateOp(meta, resolution.params);
+        return {
+            ok: false,
+            action: "unsupported",
+            target: summary,
+            op: navigateOp,
+            engine,
+            failure_reason: "engine_lacks_op",
+            hint: advertised
+                ? `This Summer Engine build (${version ?? "unknown version"}) has the Navigate op but does not advertise the "${meta.navigate.target}" destination. Update Summer Engine; until then tell the user what to open by hand: ${target.title}.`
+                : `This Summer Engine build (${version ?? "unknown version"}) predates the Navigate op, and "${target.id}" has no legacy equivalent. Update Summer Engine (restart it after updating); until then tell the user what to open by hand: ${target.title}.`,
+        };
+    }
+    const op = availability === "legacy" ? buildLegacyOp(meta, resolution.params) : buildNavigateOp(meta, resolution.params);
+    if (meta.mainSceneDefault && op.path === undefined) {
+        const mainScene = mainSceneFrom(await client.getProjectState("application/"));
+        if (!mainScene) {
+            return {
+                ok: false,
+                action: "engine_error",
+                target: summary,
+                op,
+                engine,
+                hint: "The project has no application/run/main_scene configured. Pass params.path with an explicit res://…tscn.",
+            };
+        }
+        op.path = mainScene;
+    }
+    if (print)
+        return { ok: true, action: "printed", target: summary, op, engine };
+    const receipt = await client.executeOps([op]);
+    const failure = extractOpError(receipt);
+    if (failure) {
+        return { ok: false, action: "engine_error", target: summary, op, engine, receipt, hint: failure };
+    }
+    return { ok: true, action: "opened", target: summary, op, engine, receipt };
+}

package/dist/core/capabilities/navigation/render-product-map.d.ts

@@ -0,0 +1 @@
+export declare function renderProductMap(): string;

package/dist/core/capabilities/navigation/render-product-map.js

@@ -0,0 +1,84 @@
+/**
+ * Renders library/references/product-map/product-map.md from the same data
+ * `summer_open` uses (targets.ts): the web rows from the vendored
+ * /agent-routes.json snapshot, the editor rows from the engine-id metadata.
+ * `node scripts/navigation/render-product-map.ts` writes it; navigation.test.ts
+ * fails when the committed file differs from this render.
+ */
+import { EDITOR_TARGETS, WEB_CATALOG } from "./targets.js";
+function esc(text) {
+    return text.replace(/\|/g, "\\|");
+}
+function intents(list) {
+    return esc(list.slice(0, 4).map((i) => `"${i}"`).join(", "));
+}
+function params(list) {
+    if (!list || list.length === 0)
+        return "—";
+    return list.map((p) => `\`${p.name}\`${p.required ? " (required)" : ""}`).join(", ");
+}
+function idCell(id, aliases) {
+    return `\`${id}\`${aliases && aliases.length ? ` (${aliases.map((a) => `\`${a}\``).join(", ")})` : ""}`;
+}
+function webRow(route) {
+    // The apex host is what the capability lint allows; the tool itself uses the
+    // configured gateway (www. in production).
+    const origin = route.origin === "docs" ? WEB_CATALOG.docsBase : "https://summerengine.com";
+    return `| ${idCell(route.id, route.aliases)} | web | ${intents(route.intents)} | \`${esc(origin + route.path)}\` | ${params(route.params)} | ${route.auth === "signed-in" ? "login" : "—"} | ${esc(route.description)} |`;
+}
+function editorRow(meta) {
+    const nav = meta.navigate;
+    const navArgs = [
+        ...Object.entries(nav.fixed ?? {}).map(([k, v]) => `${k}=${v}`),
+        ...Object.entries(nav.map ?? {}).map(([p, a]) => `${a}=<${p}>`),
+    ];
+    const where = `Navigate target=${nav.target}${navArgs.length ? " " + navArgs.join(" ") : ""}${meta.mainSceneDefault ? " (path defaults to the main scene)" : ""}`;
+    const legacy = meta.legacy
+        ? `\`${meta.legacy.op}\`${meta.legacy.fixed ? " " + JSON.stringify(meta.legacy.fixed) : ""}`
+        : "— (needs an engine with the Navigate op)";
+    return `| ${idCell(meta.id, meta.aliases)} | editor | ${intents(meta.intents)} | \`${esc(where)}\` | ${params(meta.params)} | ${legacy} | ${esc(meta.description)} |`;
+}
+export function renderProductMap() {
+    const lines = [];
+    lines.push("# Summer product map");
+    lines.push("");
+    lines.push("> Every place an agent can send the user: pages on summerengine.com and docs.summerengine.com, and surfaces inside the Summer Engine editor. One table, two surfaces. Open any row with `summer_open` (MCP) or `summer open <id>` (CLI); the `navigate-summer` skill says when to open a surface for the user and when to act through the API instead.");
+    lines.push("");
+    lines.push("**Generated file.** Rendered from the tool's own data by `node scripts/navigation/render-product-map.ts`; a test fails when this file and the data disagree. Do not edit by hand.");
+    lines.push("");
+    lines.push("## Who owns what");
+    lines.push("");
+    lines.push("- **Web rows** come from summerengine.com's own route catalog (`/agent-routes.json`, published from the web repo's `src/lib/navigation/routes.ts`). The toolkit vendors a snapshot (`assets/navigation/web-routes.json`, refreshed with `npm run sync:web-routes`); it does not invent pages.");
+    lines.push("- **Editor rows** are ids of Summer Engine's one navigation table (`navigate_ops.cpp`, op `Navigate`). The running engine advertises which ids it can open in `/api/health` `capabilities.navigation`; `summer open --list` shows availability from the connected engine. Engines that predate the `Navigate` op can still serve the rows with a legacy op (last-but-one column); every other row answers `engine_lacks_op` with an update hint.");
+    lines.push("");
+    lines.push("## How to read a row");
+    lines.push("");
+    lines.push("- **id** — what you pass as `target`. Aliases in parentheses also resolve. Intent phrases in the third column resolve too (`summer open \"change my plan\"`).");
+    lines.push(`- **where** — the URL (web) or the engine op (editor). \`{slot}\` is a required param; \`[/{slot}]\` is optional. Web URLs are shown on the apex host; the tool uses the configured gateway (\`gateway.url\` / \`SUMMER_GATEWAY_URL\`), so a staging gateway opens staging.`);
+    lines.push("- **params** — slot values passed as `params: { … }`. `guide` accepts an agent name (`cursor`, `claude-code`, `codex`, `gemini`, …) or a guide slug; `section` is one of the game's Studio sections; `line`/`col` are for `script`.");
+    lines.push(`- **login** — the page needs a Summer account; when this machine has no CLI login token the tool opens \`${WEB_CATALOG.login.path}?${WEB_CATALOG.login.returnParam}=<path>\` and the destination loads after sign-in. Editor rows need Summer Engine running with the project open; otherwise the tool reports \`engine_not_running\` and nothing opens.`);
+    lines.push("");
+    lines.push("Things that do not exist and are therefore not in the map (verified against the web app, 2026-09-03): a public play URL for a published game (`/games` is a curated gallery; distribution runs through a game's Builds / Releases / Store page in Studio, so \"my published games\" is `my-games`), and an API-token or MCP-credential page (CLI login is a device-code flow started by `summer login`).");
+    lines.push("");
+    lines.push("## Web");
+    lines.push("");
+    lines.push("| id | surface | intents (excerpt) | where | params | login | what the user sees |");
+    lines.push("|---|---|---|---|---|---|---|");
+    for (const route of WEB_CATALOG.routes)
+        lines.push(webRow(route));
+    lines.push("");
+    lines.push("## Editor");
+    lines.push("");
+    lines.push("| id | surface | intents (excerpt) | where (Navigate op) | params | legacy op (pre-Navigate engines) | what the user sees |");
+    lines.push("|---|---|---|---|---|---|---|");
+    for (const meta of EDITOR_TARGETS)
+        lines.push(editorRow(meta));
+    lines.push("");
+    lines.push("## Shorthands the tool also accepts");
+    lines.push("");
+    lines.push("- A `res://` path: `.tscn`/`.scn` → `scene`, `.gd`/`.cs` → `script`, anything else → `file`.");
+    lines.push("- A summerengine.com path: `/pricing` resolves to the matching row; an unknown path on the gateway origin opens as given and is reported `unmapped: true`.");
+    lines.push("- Anything that is not on summerengine.com or docs.summerengine.com is refused.");
+    lines.push("");
+    return lines.join("\n");
+}