summer-engine 2.8.2 → 3.1.0

package/dist/installer/agent-config.js

@@ -0,0 +1,540 @@
+import { existsSync, readFileSync } from "fs";
+import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { isMap, parseDocument } from "yaml";
+import { PACKAGE_ROOT } from "../core/package-root.js";
+import { agentAliasMap, agentSpec, defaultPathContext, resolveMcpPath, supportedAgents, } from "./agent-table.js";
+export { supportedAgents } from "./agent-table.js";
+export const SUMMER_MCP_SERVER_NAME = "summer-engine";
+const agentAliases = agentAliasMap();
+export function parseAgent(value) {
+    if (!value)
+        return null;
+    return agentAliases[value.trim().toLowerCase()] ?? null;
+}
+export function parseScope(value) {
+    if (!value)
+        return "user";
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "user" || normalized === "project")
+        return normalized;
+    return null;
+}
+/** `summer setup [agent] --agent <agent>`: positional and option must agree;
+ *  throws with a user-facing message when neither names a supported agent. */
+export function resolveAgentSelection(agentArg, agentOpt) {
+    if (agentArg && agentOpt && parseAgent(agentArg) !== parseAgent(agentOpt)) {
+        throw new Error("Specify the agent either positionally or with --agent, not both.");
+    }
+    const parsed = parseAgent(agentOpt ?? agentArg);
+    if (!parsed) {
+        throw new Error(`Specify an agent: ${supportedAgents.join(", ")}`);
+    }
+    return parsed;
+}
+/** `--scope` with a user-facing error; absent means "user". */
+export function resolveConfigScope(scopeOpt) {
+    const parsed = parseScope(scopeOpt);
+    if (!parsed) {
+        throw new Error("Invalid --scope. Use user or project.");
+    }
+    return parsed;
+}
+export async function configureAgentMcp(options) {
+    const env = options.env ?? process.env;
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const channel = normalizeChannel(options.channel);
+    const server = createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel);
+    const spec = agentSpec(options.agent);
+    const target = resolveConfigTarget(spec, options.scope, cwd, env);
+    const snippet = renderConfigSnippet(options.agent, server);
+    const dryRun = Boolean(options.dryRun);
+    const print = Boolean(options.print);
+    const shouldWrite = !dryRun && !print;
+    const update = print
+        ? { changed: true }
+        : await upsertConfig(spec.format, target.path, server, shouldWrite);
+    return {
+        agent: options.agent,
+        scope: options.scope,
+        path: target.path,
+        serverName: SUMMER_MCP_SERVER_NAME,
+        server,
+        format: spec.format,
+        snippet,
+        changed: update.changed,
+        wrote: shouldWrite && update.changed,
+        dryRun,
+        print,
+        localDev: Boolean(options.localDev),
+        channel,
+        warnings: target.warnings,
+        nextSteps: [`Updated ${target.path}.`, spec.restart],
+    };
+}
+async function upsertConfig(format, path, server, write) {
+    switch (format) {
+        case "toml":
+            return upsertCodexConfig(path, server, write);
+        case "toml-array":
+            return upsertTomlArrayConfig(path, server, write);
+        case "json-gemini":
+            return upsertGeminiExtension(path, server, write);
+        case "yaml-goose":
+        case "yaml-hermes":
+            return upsertYamlConfig(path, [topLevelKey(format), SUMMER_MCP_SERVER_NAME], mcpEntry(format, server), write);
+        default:
+            return upsertJsonEntry(path, format, server, write);
+    }
+}
+export const DEFAULT_CHANNEL = "latest";
+/** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
+ *  anything that could be read as a version or a path is refused (a bare
+ *  version belongs in a version bump, not a channel). */
+export function normalizeChannel(channel) {
+    const value = (channel ?? "").trim();
+    if (value === "")
+        return DEFAULT_CHANNEL;
+    if (!/^[a-z][a-z0-9-]*$/.test(value) || /^v?\d/.test(value)) {
+        throw new Error(`Invalid channel "${channel}": use an npm dist-tag such as latest or next (lowercase letters, digits, hyphens).`);
+    }
+    return value;
+}
+export function createSummerMcpServerConfig(localDev, platform = process.platform, channel = DEFAULT_CHANNEL) {
+    const spec = `summer-engine@${normalizeChannel(channel)}`;
+    if (localDev) {
+        // node is a real executable on every platform; spawn("node") resolves fine.
+        return {
+            command: "node",
+            args: [resolveLocalCliPath(), "mcp"],
+        };
+    }
+    // On Windows, npx is a .cmd/.ps1 shim, and Node's spawn() does not do PATHEXT
+    // resolution — hosts that spawn("npx") directly (Claude Code, Kimi Code,
+    // Cursor, ...) fail with ENOENT even though npx works in a terminal. Route
+    // through cmd.exe so the shim resolves. (User-reported: Imitater967, 2026-09-01.)
+    if (platform === "win32") {
+        return {
+            command: "cmd.exe",
+            args: ["/c", "npx", "-y", spec, "mcp"],
+        };
+    }
+    return {
+        command: "npx",
+        args: ["-y", spec, "mcp"],
+    };
+}
+export function renderConfigSnippet(agent, server) {
+    const format = agentSpec(agent).format;
+    if (format === "toml")
+        return renderCodexServerTable(server);
+    if (format === "toml-array")
+        return renderTomlArrayEntry(server);
+    if (format === "json-gemini") {
+        return renderJsonFile(geminiExtensionManifest(server, readBundledGeminiManifestSync()));
+    }
+    if (format === "yaml-goose" || format === "yaml-hermes") {
+        const doc = parseDocument("{}");
+        doc.setIn([topLevelKey(format), SUMMER_MCP_SERVER_NAME], doc.createNode(mcpEntry(format, server)));
+        return doc.toString();
+    }
+    const file = {};
+    if (format === "json-opencode" && agent === "opencode")
+        file.$schema = OPENCODE_SCHEMA;
+    file[topLevelKey(format)] = { [SUMMER_MCP_SERVER_NAME]: mcpEntry(format, server) };
+    return renderJsonFile(file);
+}
+const OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+/** The key under which the file lists MCP servers (see McpFormat in agent-table.ts). */
+export function topLevelKey(format) {
+    switch (format) {
+        case "json-vscode":
+        case "json-servers":
+            return "servers";
+        case "json-opencode":
+        case "json-crush":
+            return "mcp";
+        case "json-zed":
+            return "context_servers";
+        case "json-amp":
+            return "amp.mcpServers";
+        case "yaml-goose":
+            return "extensions";
+        case "yaml-hermes":
+        case "toml":
+        case "toml-array":
+            return "mcp_servers";
+        default:
+            return "mcpServers";
+    }
+}
+/** One server entry in the shape the agent's file expects. */
+export function mcpEntry(format, server) {
+    const env = server.env && Object.keys(server.env).length > 0 ? { ...server.env } : undefined;
+    switch (format) {
+        case "json-opencode":
+            return {
+                type: "local",
+                command: [server.command, ...server.args],
+                enabled: true,
+                ...(env ? { environment: env } : {}),
+            };
+        case "json-copilot":
+            return { type: "local", command: server.command, args: server.args, tools: ["*"], ...(env ? { env } : {}) };
+        case "json-vscode":
+        case "json-stdio":
+        case "json-crush":
+            return { type: "stdio", command: server.command, args: server.args, ...(env ? { env } : {}) };
+        case "json-zed":
+            return { command: server.command, args: server.args, env: env ?? {} };
+        case "json-transport":
+            return { command: server.command, args: server.args, transport: "stdio", ...(env ? { env } : {}) };
+        case "toml-array":
+            return { name: SUMMER_MCP_SERVER_NAME, transport: "stdio", command: server.command, args: server.args, ...(env ? { env } : {}) };
+        case "yaml-goose":
+            return {
+                type: "stdio",
+                name: SUMMER_MCP_SERVER_NAME,
+                description: "Summer Engine: scenes, scripts, play mode and diagnostics over MCP",
+                cmd: server.command,
+                args: server.args,
+                enabled: true,
+                timeout: 300,
+                env_keys: [],
+                envs: env ?? {},
+            };
+        default:
+            return { command: server.command, args: server.args, ...(env ? { env } : {}) };
+    }
+}
+function resolveLocalCliPath() {
+    const thisFile = fileURLToPath(import.meta.url);
+    return resolve(dirname(thisFile), "..", "bin", "summer.js");
+}
+/** Installed package root (dist/ and src/ alike). */
+export function resolvePackageRoot() {
+    return PACKAGE_ROOT;
+}
+/** Directory name Gemini expects the extension under; the manifest `name` must match it. */
+export const GEMINI_EXTENSION_DIR_NAME = "summer-engine";
+/** Files copied next to the extension manifest so `contextFileName` (GEMINI.md, which imports AGENTS.md) resolves. */
+const GEMINI_CONTEXT_FILES = ["GEMINI.md", "AGENTS.md"];
+function resolveConfigTarget(spec, scope, cwd, env) {
+    const resolved = resolveMcpPath(spec, scope, defaultPathContext(env, cwd));
+    const override = env[spec.envOverride];
+    return { path: override ? resolve(override) : resolved.path, warnings: resolved.warnings };
+}
+/** Merge one server entry into a JSON config file under the format's top-level key. */
+async function upsertJsonEntry(path, format, server, write) {
+    const current = await readJsonConfig(path);
+    const next = copyJsonObject(current);
+    const key = topLevelKey(format);
+    // OpenCode's file carries its schema; Kilo shares the shape but has its own.
+    if (format === "json-opencode" && typeof next.$schema !== "string" && /opencode\.json$/.test(path)) {
+        next.$schema = OPENCODE_SCHEMA;
+    }
+    next[key] = mergeNamedObject(next[key], SUMMER_MCP_SERVER_NAME, mcpEntry(format, server), key);
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+/**
+ * Merge one server entry into a YAML config (Goose, Hermes). Uses the yaml
+ * Document API so the user's comments and ordering survive; only the
+ * summer-engine node is replaced.
+ */
+async function upsertYamlConfig(path, keyPath, entry, write) {
+    const current = await readTextFileIfExists(path);
+    const doc = parseDocument(current.trim() === "" ? "{}" : current);
+    if (doc.errors.length > 0) {
+        throw new Error(`Could not parse YAML in ${path}: ${doc.errors[0].message}`);
+    }
+    if (!isMap(doc.contents)) {
+        throw new Error(`Expected ${path} to contain a YAML mapping.`);
+    }
+    const parent = doc.getIn(keyPath.slice(0, -1));
+    if (parent !== undefined && parent !== null && !isMap(parent)) {
+        throw new Error(`Existing ${keyPath[0]} value in ${path} must be a mapping.`);
+    }
+    doc.setIn(keyPath, doc.createNode(entry));
+    const next = doc.toString();
+    const changed = current !== next;
+    if (write && changed) {
+        await writeTextFile(path, next);
+    }
+    return { changed };
+}
+async function readJsonConfig(path) {
+    if (!existsSync(path))
+        return {};
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+    }
+    if (content.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Could not parse JSON in ${path}: ${formatError(error)}`);
+    }
+    if (!isJsonObject(parsed)) {
+        throw new Error(`Expected ${path} to contain a JSON object.`);
+    }
+    return parsed;
+}
+async function upsertCodexConfig(path, server, write) {
+    const current = await readTextFileIfExists(path);
+    const next = upsertTomlTable(current, renderCodexServerTable(server));
+    const changed = current !== next;
+    if (write && changed) {
+        await writeTextFile(path, next);
+    }
+    return { changed };
+}
+/**
+ * Mistral Vibe lists servers as a TOML array of tables:
+ *   [[mcp_servers]]
+ *   name = "summer-engine"
+ *   ...
+ * Replace the block whose name is ours, else append one.
+ */
+async function upsertTomlArrayConfig(path, server, write) {
+    const current = await readTextFileIfExists(path);
+    const next = upsertTomlArrayBlock(current, renderTomlArrayEntry(server));
+    const changed = current !== next;
+    if (write && changed) {
+        await writeTextFile(path, next);
+    }
+    return { changed };
+}
+export function upsertTomlArrayBlock(content, block) {
+    const lines = content.split(/\r?\n/);
+    const header = /^\s*\[\[mcp_servers\]\]\s*(?:#.*)?$/;
+    const nameLine = new RegExp(`^\\s*name\\s*=\\s*"${SUMMER_MCP_SERVER_NAME}"\\s*(?:#.*)?$`);
+    let start = -1;
+    let end = lines.length;
+    for (let index = 0; index < lines.length; index += 1) {
+        if (!header.test(lines[index]))
+            continue;
+        let blockEnd = lines.length;
+        for (let inner = index + 1; inner < lines.length; inner += 1) {
+            if (/^\s*\[/.test(lines[inner])) {
+                blockEnd = inner;
+                break;
+            }
+        }
+        if (lines.slice(index + 1, blockEnd).some((line) => nameLine.test(line))) {
+            start = index;
+            end = blockEnd;
+            break;
+        }
+    }
+    if (start === -1) {
+        const trimmed = content.endsWith("\n") || content === "" ? content : `${content}\n`;
+        return `${trimmed}${trimmed === "" ? "" : "\n"}${block}`;
+    }
+    const replacement = block.trimEnd().split("\n");
+    if (lines[end] && lines[end].trim() !== "")
+        replacement.push("");
+    return ensureTrailingNewline([...lines.slice(0, start), ...replacement, ...lines.slice(end)].join("\n"));
+}
+function renderTomlArrayEntry(server) {
+    const lines = [
+        "[[mcp_servers]]",
+        `name = ${tomlString(SUMMER_MCP_SERVER_NAME)}`,
+        `transport = "stdio"`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+    ];
+    if (server.env && Object.keys(server.env).length > 0) {
+        lines.push(`env = { ${Object.entries(server.env)
+            .map(([key, value]) => `${key} = ${tomlString(value)}`)
+            .join(", ")} }`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function upsertGeminiExtension(path, server, write) {
+    const current = await readJsonConfig(path);
+    const bundled = await readBundledGeminiManifest();
+    const next = geminiExtensionManifest(server, bundled, current);
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    let changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    // GEMINI.md (the declared contextFileName) and AGENTS.md (which it imports)
+    // must sit next to the manifest or Gemini has no context file to load.
+    const extensionDir = dirname(path);
+    const packageRoot = resolvePackageRoot();
+    for (const name of GEMINI_CONTEXT_FILES) {
+        const src = join(packageRoot, name);
+        if (!existsSync(src))
+            continue;
+        const dest = join(extensionDir, name);
+        const srcText = await readFile(src, "utf-8");
+        const destText = existsSync(dest) ? await readFile(dest, "utf-8") : null;
+        if (destText === srcText)
+            continue;
+        changed = true;
+        if (write) {
+            await mkdir(extensionDir, { recursive: true, mode: 0o700 });
+            await copyFile(src, dest);
+        }
+    }
+    return { changed };
+}
+/**
+ * The GENERATED gemini-extension.json shipped at the package root
+ * (registry/generated/gemini-extension.json -> gemini-extension.json). Absent
+ * only in broken installs; the installer then falls back to a minimal manifest.
+ */
+async function readBundledGeminiManifest() {
+    const path = join(resolvePackageRoot(), "gemini-extension.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        return await readJsonConfig(path);
+    }
+    catch {
+        return {};
+    }
+}
+function readBundledGeminiManifestSync() {
+    const path = join(resolvePackageRoot(), "gemini-extension.json");
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        return isJsonObject(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Manifest written to ~/.gemini/extensions/summer-engine/gemini-extension.json.
+ *
+ * Starts from the generated package manifest (version, description, settings,
+ * contextFileName, ...) so the installed copy never drifts from the registry,
+ * then overrides what only makes sense at install time:
+ *  - `name` = the extension directory name (Gemini requires them to match;
+ *    geminicli.com/docs/extensions/reference), which is "summer-engine".
+ *  - `mcpServers` = the same launcher every other host gets (npx -y ...@latest,
+ *    cmd.exe-wrapped on Windows). The bundled entry runs from `${extensionPath}`
+ *    where no package is installed, and that only works inside the npm layout.
+ *  - `skills` is dropped: Gemini has no such manifest field; it discovers
+ *    <extension>/skills/<name>/SKILL.md, which `summer skills install --agent
+ *    gemini` writes.
+ *  - the `_generated` banner is dropped: this file is written by the installer.
+ * Unknown keys already present in the user's file (`base`) are preserved.
+ */
+function geminiExtensionManifest(server, bundled, base = {}) {
+    const { _generated: _banner, skills: _skills, ...fromPackage } = bundled;
+    const manifest = { ...base, ...fromPackage };
+    manifest.name = GEMINI_EXTENSION_DIR_NAME;
+    if (typeof manifest.description !== "string") {
+        manifest.description =
+            "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills.";
+    }
+    manifest.contextFileName = "GEMINI.md";
+    manifest.mcpServers = {
+        [SUMMER_MCP_SERVER_NAME]: {
+            command: server.command,
+            args: server.args,
+            ...(server.env && Object.keys(server.env).length > 0 ? { env: { ...server.env } } : {}),
+        },
+    };
+    return manifest;
+}
+async function readTextFileIfExists(path) {
+    if (!existsSync(path))
+        return "";
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+    }
+}
+function upsertTomlTable(content, table) {
+    const lines = content.split(/\r?\n/);
+    const serverHeader = /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)(?:\.|\])/;
+    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)\]\s*(?:#.*)?$/.test(line));
+    if (start === -1) {
+        const trimmed = content.endsWith("\n") || content === "" ? content : `${content}\n`;
+        return `${trimmed}${trimmed === "" ? "" : "\n"}${table}`;
+    }
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (/^\s*\[/.test(lines[index]) && !serverHeader.test(lines[index])) {
+            end = index;
+            break;
+        }
+    }
+    const replacement = table.trimEnd().split("\n");
+    if (lines[end] && lines[end].trim() !== "") {
+        replacement.push("");
+    }
+    const nextLines = [
+        ...lines.slice(0, start),
+        ...replacement,
+        ...lines.slice(end),
+    ];
+    return ensureTrailingNewline(nextLines.join("\n"));
+}
+function renderCodexServerTable(server) {
+    const lines = [
+        `[mcp_servers.${SUMMER_MCP_SERVER_NAME}]`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+    ];
+    if (server.env && Object.keys(server.env).length > 0) {
+        lines.push(`env = { ${Object.entries(server.env)
+            .map(([key, value]) => `${key} = ${tomlString(value)}`)
+            .join(", ")} }`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function renderJsonFile(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function copyJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function mergeNamedObject(value, key, entry, label) {
+    if (value !== undefined && !isJsonObject(value)) {
+        throw new Error(`Existing ${label} value must be a JSON object.`);
+    }
+    return {
+        ...(isJsonObject(value) ? value : {}),
+        [key]: entry,
+    };
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function writeTextFile(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, content, { encoding: "utf-8", mode: 0o600 });
+}
+function ensureTrailingNewline(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/installer/agent-table.d.ts

@@ -0,0 +1,103 @@
+/** Ids `summer setup <agent>` accepts. Legacy ids stay so old commands and
+ *  configs keep resolving, but they are hidden from help and warn on use. */
+export declare const AGENT_IDS: readonly ["claude-code", "claude-desktop", "codex", "cursor", "windsurf", "antigravity", "gemini", "cline", "cline-cli", "roo-code", "kilo-code", "github-copilot", "vscode-copilot", "visual-studio", "copilot-jetbrains", "opencode", "zed", "kiro", "goose", "hermes", "trae", "qwen-code", "kimi-code", "crush", "amp", "factory", "junie", "warp", "rovo-dev", "qoder", "grok-build", "mistral-vibe", "lm-studio"];
+export type SupportedAgent = (typeof AGENT_IDS)[number];
+export type ConfigScope = "user" | "project";
+/**
+ * File shapes the installer can write. One writer per shape in agent-config.ts.
+ *  json          { mcpServers: { <name>: { command, args, env? } } }
+ *  json-stdio    { mcpServers: { <name>: { type: "stdio", command, args, env? } } }
+ *  json-vscode   { servers:    { <name>: { type: "stdio", command, args, env? } } }
+ *  json-copilot  { mcpServers: { <name>: { type: "local", command, args, tools: ["*"], env? } } }
+ *  json-opencode { mcp:        { <name>: { type: "local", command: [..], enabled: true, environment? } } }
+ *  json-servers  { servers:    { <name>: { command, args, env? } } }               (Copilot in JetBrains)
+ *  json-zed      { context_servers: { <name>: { command, args, env } } }
+ *  json-amp      { "amp.mcpServers": { <name>: { command, args, env? } } }
+ *  json-crush    { mcp:        { <name>: { type: "stdio", command, args, env? } } }
+ *  json-transport{ mcpServers: { <name>: { command, args, transport: "stdio", env? } } } (Rovo Dev)
+ *  toml          [mcp_servers.<name>] command/args/env                              (Codex, Grok Build)
+ *  toml-array    [[mcp_servers]] name/transport/command/args                         (Mistral Vibe)
+ *  yaml-goose    extensions: <name>: { type: stdio, name, cmd, args, enabled, timeout, envs }
+ *  yaml-hermes   mcp_servers: <name>: { command, args, env? }
+ *  json-gemini   the Gemini extension manifest (legacy)
+ */
+export type McpFormat = "json" | "json-stdio" | "json-vscode" | "json-copilot" | "json-opencode" | "json-servers" | "json-zed" | "json-amp" | "json-crush" | "json-transport" | "toml" | "toml-array" | "yaml-goose" | "yaml-hermes" | "json-gemini";
+export type SkillLocationKind = "skill-dir" | "cursor-rule-dir" | "windsurf-rule-file" | "cline-rule-dir" | "opencode-skill-dir";
+export interface PathContext {
+    home: string;
+    os: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+}
+export interface SkillHome {
+    kind: SkillLocationKind;
+    user: (ctx: PathContext) => string;
+    /** null: the agent reads skills from one user-level place only. */
+    project: ((ctx: PathContext) => string) | null;
+    /** `summer skills install --agent <id>` without --scope uses this (default "user"). */
+    defaultScope?: ConfigScope;
+    /** Printed after a skills install when the agent needs a nudge to reload. */
+    reloadHint?: string;
+    /**
+     * Where Summer versions before 3.1 wrote this agent's skills as generated
+     * rule files. `skills install --force` deletes the `summer-<skill>` files it
+     * finds there so the agent does not load a rule and a skill for the same slug.
+     */
+    legacyRules?: {
+        user: (ctx: PathContext) => string;
+        project: ((ctx: PathContext) => string) | null;
+        suffix: string;
+    };
+}
+export interface AgentSpec {
+    id: SupportedAgent;
+    label: string;
+    /** Extra spellings `summer setup` accepts (the id itself always resolves). */
+    aliases: readonly string[];
+    /** legacy: product retired or renamed; still writes, but warns and is hidden from help. */
+    status: "active" | "legacy";
+    legacyNote?: string;
+    /** Env var that overrides the MCP config path (tests, unusual installs). */
+    envOverride: string;
+    format: McpFormat;
+    mcp: {
+        /** null: user-level servers are managed in the app's UI; a user request writes the project file with a warning. */
+        user: ((ctx: PathContext) => string) | null;
+        /** null: user-only config; a project request falls back to user with a warning. */
+        project: ((ctx: PathContext) => string) | null;
+        /** Extra warning printed when project scope is requested (also when it is honoured). */
+        projectNote?: string;
+    };
+    /** What to do after the config is written. */
+    restart: string;
+    /** null: no skills/rules mechanism — MCP only. */
+    skills: SkillHome | null;
+    noSkillsNote?: string;
+}
+export declare function agentSpec(id: SupportedAgent): AgentSpec;
+export declare function allAgentSpecs(): readonly AgentSpec[];
+/** Ids shown in help and error messages (legacy ids still parse). */
+export declare const supportedAgents: readonly SupportedAgent[];
+/** Ids with a skills/rules home; `AGENT_CLIENTS` in core mirrors this plus "summer". */
+export declare const skillCapableAgents: readonly SupportedAgent[];
+/** Every spelling → canonical id. Aliases must be unique across the table. */
+export declare function agentAliasMap(): Record<string, SupportedAgent>;
+export declare function agentLabel(id: SupportedAgent): string;
+export declare function defaultPathContext(env?: NodeJS.ProcessEnv, cwd?: string): PathContext;
+export interface ResolvedMcpPath {
+    path: string;
+    /** The scope actually written (project requests fall back to user when the agent has no project config). */
+    scope: ConfigScope;
+    warnings: string[];
+}
+/** Where the MCP config goes for an agent and requested scope, with the warnings to show. */
+export declare function resolveMcpPath(spec: AgentSpec, scope: ConfigScope, ctx: PathContext): ResolvedMcpPath;
+/** Rule files a pre-3.1 Summer wrote for this agent at this scope; `null` when the agent never had any. */
+export declare function legacyRuleFiles(spec: AgentSpec, scope: ConfigScope, ctx: PathContext, skillNames: Iterable<string>): string[] | null;
+export interface ResolvedSkillPath {
+    kind: SkillLocationKind;
+    path: string;
+    scope: ConfigScope;
+}
+/** Where skills go for an agent with a skills home. */
+export declare function resolveSkillPath(spec: AgentSpec, scope: ConfigScope, ctx: PathContext): ResolvedSkillPath | null;