summer-engine 4.5.0 → 4.8.0

package/dist/installer/agent-detect.js

@@ -0,0 +1,166 @@
+/**
+ * `summer setup --detect`: which agents from agent-table.ts are on this
+ * computer, where each one's MCP config file is, and whether it already lists
+ * summer-engine. Reads only; never writes.
+ *
+ * How an agent counts as installed (any one hit; `detectedBy` names each):
+ *  - bin: one of its commands is a file on PATH, or in a usual install folder
+ *    (~/.local/bin, /opt/homebrew/bin, %APPDATA%\npm, ...). A desktop app's
+ *    installer runs with a short PATH that leaves those out, so they are
+ *    checked by name. On Windows each name is tried with every PATHEXT ending.
+ *  - app: a macOS app bundle in /Applications or ~/Applications, or a Windows
+ *    executable under %LOCALAPPDATA%, %ProgramFiles% or %ProgramFiles(x86)%.
+ *  - folder: a config, data or install folder the agent makes on first run.
+ *  - extension: a VS Code extension folder in ~/.vscode/extensions.
+ * The per-agent names live in agent-table.ts (`detect`).
+ */
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { allAgentSpecs, defaultPathContext, resolveMcpPath, } from "./agent-table.js";
+import { listsSummerEngine, readRecordedMcpServer } from "./version-check.js";
+import { toStepError } from "./setup-error.js";
+export function detectAgents(options = {}) {
+    const ctx = options.ctx ?? defaultPathContext();
+    const binDirs = searchedBinDirs(ctx, options.systemBinDirs);
+    const macAppDirs = options.macAppDirs ?? ["/Applications", join(ctx.home, "Applications")];
+    return allAgentSpecs().map((spec) => detectAgent(spec, ctx, binDirs, macAppDirs));
+}
+function detectAgent(spec, ctx, binDirs, macAppDirs) {
+    const detectedBy = [
+        ...(spec.detect.bins ?? []).flatMap((name) => findBin(name, binDirs, ctx)).map((path) => ({ kind: "bin", path })),
+        ...findApps(spec, ctx, macAppDirs).map((path) => ({ kind: "app", path })),
+        ...(spec.detect.dirs?.(ctx) ?? []).filter((path) => existsSync(path)).map((path) => ({ kind: "folder", path })),
+        ...findVsCodeExtensions(spec.detect.vscodeExtensions ?? [], ctx).map((path) => ({ kind: "extension", path })),
+    ];
+    const unique = detectedBy.filter((hit, index) => detectedBy.findIndex((other) => other.path === hit.path) === index);
+    const resolved = resolveMcpPath(spec, "user", ctx);
+    const override = ctx.env[spec.envOverride];
+    const configPath = override || resolved.path;
+    const configExists = existsSync(configPath);
+    let mcpEntry = false;
+    let mcpServer = null;
+    let configError;
+    if (configExists) {
+        try {
+            const text = readFileSync(configPath, "utf-8");
+            mcpEntry = listsSummerEngine(text, spec.format);
+            mcpServer = readRecordedMcpServer(text, spec.format);
+        }
+        catch (error) {
+            configError = toStepError(error, "config_unreadable");
+        }
+    }
+    return {
+        id: spec.id,
+        label: spec.label,
+        status: spec.status,
+        installed: unique.length > 0,
+        programFound: unique.some((hit) => hit.kind !== "folder"),
+        detectedBy: unique,
+        configPath,
+        configScope: resolved.scope,
+        configFormat: spec.format,
+        configExists,
+        mcpEntry,
+        mcpServer,
+        summerGames: Boolean(spec.remoteMcp),
+        skills: spec.skills !== null,
+        ...(configError ? { configError } : {}),
+    };
+}
+/** PATH first, then the install folders a GUI-launched process's PATH leaves out. */
+export function searchedBinDirs(ctx, systemBinDirs = ["/opt/homebrew/bin", "/usr/local/bin"]) {
+    const path = ctx.env.PATH ?? ctx.env.Path ?? "";
+    const sep = ctx.os === "win32" ? ";" : ":";
+    const fromPath = path.split(sep).filter(Boolean);
+    const home = ctx.home;
+    const usual = ctx.os === "win32"
+        ? [
+            join(home, ".local", "bin"),
+            join(ctx.env.APPDATA ?? join(home, "AppData", "Roaming"), "npm"),
+            join(localAppData(ctx), "Microsoft", "WinGet", "Links"),
+            join(localAppData(ctx), "pnpm"),
+            join(home, ".bun", "bin"),
+            join(home, ".volta", "bin"),
+            join(home, ".lmstudio", "bin"),
+        ]
+        : [
+            join(home, ".local", "bin"),
+            join(home, "bin"),
+            ...systemBinDirs,
+            join(home, ".npm-global", "bin"),
+            join(home, ".bun", "bin"),
+            join(home, ".volta", "bin"),
+            join(home, "Library", "pnpm"),
+            join(home, ".local", "share", "pnpm"),
+            join(home, ".claude", "local"),
+            join(home, ".opencode", "bin"),
+            join(home, ".lmstudio", "bin"),
+            ...nvmBinDirs(home),
+        ];
+    return [...new Set([...fromPath, ...usual])];
+}
+/** ~/.nvm/versions/node/<version>/bin for each installed Node (npm -g installs land there). */
+function nvmBinDirs(home) {
+    const root = join(home, ".nvm", "versions", "node");
+    try {
+        return readdirSync(root).map((version) => join(root, version, "bin"));
+    }
+    catch {
+        return [];
+    }
+}
+function localAppData(ctx) {
+    return ctx.env.LOCALAPPDATA ?? join(ctx.home, "AppData", "Local");
+}
+function findBin(name, dirs, ctx) {
+    const names = ctx.os === "win32"
+        ? [name, ...(ctx.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => `${name}${ext.toLowerCase()}`)]
+        : [name];
+    const hits = [];
+    for (const dir of dirs) {
+        for (const candidate of names) {
+            const path = join(dir, candidate);
+            if (isRunnable(path, ctx)) {
+                hits.push(path);
+                break;
+            }
+        }
+    }
+    return hits;
+}
+function isRunnable(path, ctx) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        if (ctx.os !== "win32")
+            accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function findApps(spec, ctx, macAppDirs) {
+    if (ctx.os === "darwin") {
+        return (spec.detect.macApps ?? []).flatMap((app) => macAppDirs.map((dir) => join(dir, app))).filter((path) => existsSync(path));
+    }
+    if (ctx.os === "win32") {
+        const roots = [localAppData(ctx), ctx.env.ProgramFiles, ctx.env["ProgramFiles(x86)"]].filter((root) => Boolean(root));
+        return (spec.detect.winApps ?? []).flatMap((exe) => roots.map((root) => join(root, exe))).filter((path) => existsSync(path));
+    }
+    return [];
+}
+function findVsCodeExtensions(prefixes, ctx) {
+    if (prefixes.length === 0)
+        return [];
+    const dir = join(ctx.home, ".vscode", "extensions");
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => prefixes.some((prefix) => entry.toLowerCase().startsWith(prefix))).map((entry) => join(dir, entry));
+}

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

@@ -101,6 +101,25 @@ export interface AgentSpec {
     /** null: no skills/rules mechanism — MCP only. */
     skills: SkillHome | null;
     noSkillsNote?: string;
+    /** How `summer setup --detect` tells the agent is on this computer (agent-detect.ts). */
+    detect: AgentDetect;
+}
+/**
+ * Where an agent shows up once it is installed, on macOS and Windows (Linux
+ * uses the bins and folders). Any one hit counts as installed; `--detect`
+ * names each hit, so a caller can tell a live binary from a leftover folder.
+ */
+export interface AgentDetect {
+    /** Commands: looked up on PATH and in the usual install folders a GUI app's short PATH misses (agent-detect.ts). */
+    bins?: readonly string[];
+    /** macOS app bundles, looked up in /Applications and ~/Applications. */
+    macApps?: readonly string[];
+    /** Windows executables, relative to %LOCALAPPDATA%, %ProgramFiles% and %ProgramFiles(x86)%. */
+    winApps?: readonly string[];
+    /** Folders the agent creates on install or first run (config, data or install folder). */
+    dirs?: (ctx: PathContext) => string[];
+    /** VS Code extension id prefixes, looked up in ~/.vscode/extensions (folders named <id>-<version>). */
+    vscodeExtensions?: readonly string[];
 }
 /** True when this location is the shared agentskills.io folder. */
 export declare function isSharedSkillsPath(path: string): boolean;

package/dist/installer/agent-table.js

@@ -114,6 +114,11 @@ const SPECS = [
             signIn: (name) => `In Claude Code, run /mcp, choose ${name} and sign in.`,
         },
         mcp: { user: home(".claude.json"), project: project(".mcp.json") },
+        detect: {
+            // The native installer puts claude in ~/.local/bin (macOS and Windows); older npm installs in ~/.claude/local.
+            bins: ["claude"],
+            dirs: (ctx) => [join(ctx.home, ".claude"), join(ctx.home, ".claude.json")],
+        },
         restart: "Restart Claude Code or run /mcp in a new session.",
         skills: skillDirs(home(".claude", "skills"), project(".claude", "skills")),
     },
@@ -129,6 +134,12 @@ const SPECS = [
             user: (ctx) => join(appConfigRoot(ctx), "Claude", "claude_desktop_config.json"),
             project: null,
         },
+        detect: {
+            macApps: ["Claude.app"],
+            // Squirrel install: %LOCALAPPDATA%/AnthropicClaude/claude.exe.
+            winApps: [join("AnthropicClaude", "claude.exe")],
+            dirs: (ctx) => [join(appConfigRoot(ctx), "Claude")],
+        },
         restart: "Quit and reopen Claude Desktop; the summer-engine tools appear under the tools menu in a new chat.",
         skills: null,
         noSkillsNote: "Claude Desktop has no skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.",
@@ -150,6 +161,12 @@ const SPECS = [
             project: project(".codex", "config.toml"),
             projectNote: "Codex only loads project .codex/config.toml from trusted projects.",
         },
+        detect: {
+            // The codex CLI (npm or Homebrew) and the Codex desktop app share $CODEX_HOME (default ~/.codex).
+            bins: ["codex"],
+            macApps: ["Codex.app"],
+            dirs: (ctx) => [ctx.env.CODEX_HOME || join(ctx.home, ".codex")],
+        },
         restart: "Restart Codex or run /mcp in a new session.",
         skills: sharedSkills(),
     },
@@ -165,6 +182,12 @@ const SPECS = [
             signIn: (name) => `In Cursor Settings, open MCP and click Connect (or Authenticate) next to ${name}.`,
         },
         mcp: { user: home(".cursor", "mcp.json"), project: project(".cursor", "mcp.json") },
+        detect: {
+            bins: ["cursor", "cursor-agent"],
+            macApps: ["Cursor.app"],
+            winApps: [join("Programs", "cursor", "Cursor.exe")],
+            dirs: (ctx) => [join(ctx.home, ".cursor")],
+        },
         restart: "Restart Cursor and enable the summer-engine MCP server if prompted.",
         skills: sharedSkills({
             reloadHint: "Cursor loads skills in the next chat. Summer 3.0 wrote rule files to .cursor/rules and 3.1.0 wrote .cursor/skills; `--force` removes both.",
@@ -189,6 +212,12 @@ const SPECS = [
             project: null,
             movedFrom: home(".codeium", "windsurf", "mcp_config.json"),
         },
+        detect: {
+            bins: ["windsurf", "devin"],
+            macApps: ["Windsurf.app", "Devin.app"],
+            winApps: [join("Programs", "Windsurf", "Windsurf.exe"), join("Programs", "Devin", "Devin.exe")],
+            dirs: (ctx) => [join(xdgOrAppData(ctx), "devin"), join(ctx.home, ".codeium", "windsurf")],
+        },
         restart: "Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings. Devin's docs say mcp_config.json configures the Cascade agent; for the Devin agent add the server in the app's MCP settings with the same command.",
         skills: sharedSkills({ legacyDirs: { user: home(".codeium", "windsurf", "skills"), project: project(".windsurf", "skills") } }),
     },
@@ -207,6 +236,12 @@ const SPECS = [
             user: home(".gemini", "config", "mcp_config.json"),
             project: project(".agents", "mcp_config.json"),
         },
+        detect: {
+            bins: ["antigravity", "agy"],
+            macApps: ["Antigravity.app"],
+            winApps: [join("Programs", "Antigravity", "Antigravity.exe")],
+            dirs: (ctx) => [join(ctx.home, ".gemini", "antigravity"), join(ctx.home, ".gemini", "config")],
+        },
         restart: "In Antigravity open the agent panel's MCP servers view and refresh; summer-engine appears in the list (IDE and CLI share this file).",
         skills: skillDirs(home(".gemini", "config", "skills"), project(".agents", "skills")),
     },
@@ -223,6 +258,7 @@ const SPECS = [
             user: home(".gemini", "extensions", "summer-engine", "gemini-extension.json"),
             project: null,
         },
+        detect: { bins: ["gemini"], dirs: (ctx) => [join(ctx.home, ".gemini", "extensions")] },
         restart: "Run `summer skills install --all --agent gemini` if skills were not installed, then restart Gemini CLI (or `gemini extensions enable summer-engine` if it is disabled).",
         skills: skillDirs(home(".gemini", "extensions", "summer-engine", "skills"), null),
     },
@@ -241,6 +277,11 @@ const SPECS = [
             user: (ctx) => vsCodeGlobalStorage(ctx, "saoudrizwan.claude-dev", "cline_mcp_settings.json"),
             project: null,
         },
+        detect: {
+            // A VS Code extension: its install folder, or the storage it makes on first run.
+            vscodeExtensions: ["saoudrizwan.claude-dev-"],
+            dirs: (ctx) => [join(vsCodeUserDir(ctx), "globalStorage", "saoudrizwan.claude-dev")],
+        },
         restart: "Restart VS Code so Cline reloads its MCP config.",
         skills: skillDirs(home(".cline", "skills"), project(".cline", "skills")),
     },
@@ -256,6 +297,7 @@ const SPECS = [
             signIn: (name) => `Run \`cline mcp\`, pick ${name} and choose Authorize OAuth.`,
         },
         mcp: { user: home(".cline", "data", "settings", "cline_mcp_settings.json"), project: null },
+        detect: { bins: ["cline"], dirs: (ctx) => [join(ctx.home, ".cline", "data")] },
         restart: "Restart the Cline CLI so it reloads its MCP settings.",
         skills: skillDirs(home(".cline", "skills"), project(".cline", "skills")),
     },
@@ -272,6 +314,10 @@ const SPECS = [
             user: (ctx) => vsCodeGlobalStorage(ctx, "rooveterinaryinc.roo-cline", "cline_mcp_settings.json"),
             project: null,
         },
+        detect: {
+            vscodeExtensions: ["rooveterinaryinc.roo-cline-"],
+            dirs: (ctx) => [join(vsCodeUserDir(ctx), "globalStorage", "rooveterinaryinc.roo-cline")],
+        },
         restart: "Restart VS Code so Roo Code reloads its MCP config.",
         skills: {
             kind: "cline-rule-dir",
@@ -295,6 +341,12 @@ const SPECS = [
             user: (ctx) => join(xdgOrAppData(ctx), "kilo", "kilo.json"),
             project: project("kilo.json"),
         },
+        detect: {
+            // The kilo CLI, or the VS Code extension.
+            bins: ["kilo", "kilocode"],
+            vscodeExtensions: ["kilocode.kilo-code-"],
+            dirs: (ctx) => [join(xdgOrAppData(ctx), "kilo"), join(ctx.home, ".kilo")],
+        },
         restart: "Restart Kilo (CLI or the VS Code extension) so it reloads kilo.json.",
         skills: skillDirs(home(".kilo", "skills"), project(".kilo", "skills")),
     },
@@ -310,6 +362,7 @@ const SPECS = [
             signIn: (name) => `Copilot CLI opens summer.games to sign in when ${name} first connects; /mcp signs in again.`,
         },
         mcp: { user: home(".copilot", "mcp-config.json"), project: project(".mcp.json") },
+        detect: { bins: ["copilot"], dirs: (ctx) => [join(ctx.home, ".copilot")] },
         restart: "Restart Copilot CLI, or run /mcp reload and /skills reload in the active session.",
         skills: skillDirs(home(".copilot", "skills"), project(".github", "skills")),
     },
@@ -327,6 +380,13 @@ const SPECS = [
             signIn: (name) => `In VS Code, click Allow when ${name} asks to authenticate, then sign in on summer.games.`,
         },
         mcp: { user: (ctx) => join(vsCodeUserDir(ctx), "mcp.json"), project: project(".vscode", "mcp.json") },
+        detect: {
+            // Copilot Chat ships with VS Code, so VS Code itself is the signal.
+            bins: ["code"],
+            macApps: ["Visual Studio Code.app"],
+            winApps: [join("Programs", "Microsoft VS Code", "Code.exe"), join("Microsoft VS Code", "Code.exe")],
+            dirs: (ctx) => [vsCodeUserDir(ctx)],
+        },
         restart: "Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode.",
         skills: sharedSkills({ legacyDirs: { user: home(".copilot", "skills"), project: project(".github", "skills") } }),
     },
@@ -339,6 +399,10 @@ const SPECS = [
         format: "json-vscode",
         // No Summer Games entry: Visual Studio's OAuth redirect for MCP is not documented; not checked against api.summer.games.
         mcp: { user: home(".mcp.json"), project: project(".mcp.json") },
+        detect: {
+            // Windows only (Visual Studio for Mac is retired): the install root under Program Files.
+            winApps: [join("Microsoft Visual Studio", "Installer", "vswhere.exe")],
+        },
         restart: "Restart Visual Studio, open Copilot Chat in Agent mode, and enable summer-engine in the tools picker.",
         skills: null,
         noSkillsNote: "Visual Studio's Copilot has no skills folder yet; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
@@ -358,6 +422,10 @@ const SPECS = [
             user: (ctx) => join(xdgOrAppData(ctx), "github-copilot", "intellij", "mcp.json"),
             project: null,
         },
+        detect: {
+            // The Copilot plugin writes its settings here on first run; the IDE itself can be any JetBrains product.
+            dirs: (ctx) => [join(xdgOrAppData(ctx), "github-copilot", "intellij")],
+        },
         restart: "Restart the JetBrains IDE and open Copilot Chat in Agent mode; summer-engine shows in the tools list.",
         skills: null,
         noSkillsNote: "Copilot in JetBrains documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
@@ -377,6 +445,12 @@ const SPECS = [
             user: (ctx) => join(xdgOrAppData(ctx), "opencode", "opencode.json"),
             project: project("opencode.json"),
         },
+        detect: {
+            // The install script puts opencode in ~/.opencode/bin.
+            bins: ["opencode"],
+            macApps: ["OpenCode.app"],
+            dirs: (ctx) => [join(xdgOrAppData(ctx), "opencode"), join(ctx.home, ".opencode")],
+        },
         restart: "Restart OpenCode so it reloads opencode.json.",
         skills: sharedSkills({
             reloadHint: "OpenCode loads skills from this folder on the next session. Summer 3.0 wrote markdown under agents/summer and 3.1.0 wrote opencode/skills; `--force` removes both.",
@@ -399,6 +473,12 @@ const SPECS = [
             user: (ctx) => join(xdgOrAppData(ctx), "zed", "settings.json"),
             project: null,
         },
+        detect: {
+            bins: ["zed"],
+            macApps: ["Zed.app", "Zed Preview.app"],
+            winApps: [join("Programs", "Zed", "Zed.exe")],
+            dirs: (ctx) => [join(xdgOrAppData(ctx), "zed")],
+        },
         restart: "Zed reloads settings.json live; open the Agent panel and check summer-engine under MCP servers.",
         skills: sharedSkills(),
     },
@@ -414,6 +494,12 @@ const SPECS = [
             signIn: (name) => `Kiro opens summer.games to sign in when ${name} connects (Kiro CLI: /mcp auth).`,
         },
         mcp: { user: home(".kiro", "settings", "mcp.json"), project: project(".kiro", "settings", "mcp.json") },
+        detect: {
+            bins: ["kiro", "kiro-cli"],
+            macApps: ["Kiro.app"],
+            winApps: [join("Programs", "Kiro", "Kiro.exe")],
+            dirs: (ctx) => [join(ctx.home, ".kiro")],
+        },
         restart: "Kiro reloads MCP config on save; open the MCP Servers view to confirm summer-engine is connected.",
         skills: skillDirs(home(".kiro", "skills"), project(".kiro", "skills")),
     },
@@ -443,6 +529,12 @@ const SPECS = [
                 : join(xdgConfig(ctx), "goose", "config.yaml"),
             project: null,
         },
+        detect: {
+            bins: ["goose"],
+            macApps: ["Goose.app"],
+            winApps: [join("Programs", "Goose", "Goose.exe")],
+            dirs: (ctx) => [ctx.os === "win32" ? join(appData(ctx), "Block", "goose") : join(xdgConfig(ctx), "goose")],
+        },
         restart: "Restart Goose (CLI or Desktop); summer-engine is listed under Extensions.",
         skills: skillDirs((ctx) => join(xdgConfig(ctx), "agents", "skills"), project(".agents", "skills")),
     },
@@ -458,6 +550,7 @@ const SPECS = [
             signIn: (name) => `Run \`hermes mcp login ${name}\`, or sign in on summer.games when Hermes first connects.`,
         },
         mcp: { user: home(".hermes", "config.yaml"), project: null },
+        detect: { bins: ["hermes"], dirs: (ctx) => [join(ctx.home, ".hermes")] },
         restart: "Run /reload-mcp in Hermes Agent (or restart it).",
         skills: skillDirs(home(".hermes", "skills"), SHARED_SKILLS_PROJECT, {
             reloadHint: "Project skills need `hermes skills trust` before Hermes loads them.",
@@ -480,6 +573,12 @@ const SPECS = [
             project: project(".trae", "mcp.json"),
             projectNote: "Trae manages user-level MCP servers in its UI; writing the project file .trae/mcp.json instead.",
         },
+        detect: {
+            bins: ["trae"],
+            macApps: ["Trae.app"],
+            winApps: [join("Programs", "Trae", "Trae.exe")],
+            dirs: (ctx) => [join(appConfigRoot(ctx), "Trae"), join(ctx.home, ".trae")],
+        },
         restart: "Restart Trae and open the MCP settings; summer-engine should show as connected.",
         skills: null,
         noSkillsNote: "Trae documents no skills folder; the MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
@@ -496,6 +595,7 @@ const SPECS = [
             signIn: (name) => `In Qwen Code, run /mcp auth ${name} and sign in.`,
         },
         mcp: { user: home(".qwen", "settings.json"), project: project(".qwen", "settings.json") },
+        detect: { bins: ["qwen"], dirs: (ctx) => [join(ctx.home, ".qwen")] },
         restart: "Restart Qwen Code or run /mcp in a new session.",
         skills: skillDirs(home(".qwen", "skills"), project(".qwen", "skills")),
     },
@@ -511,6 +611,7 @@ const SPECS = [
             signIn: (name) => `Run \`kimi mcp auth ${name}\`; it opens summer.games to sign in.`,
         },
         mcp: { user: home(".kimi-code", "mcp.json"), project: project(".kimi-code", "mcp.json") },
+        detect: { bins: ["kimi"], dirs: (ctx) => [join(ctx.home, ".kimi-code"), join(ctx.home, ".kimi")] },
         restart: "Restart Kimi Code CLI so it reconnects its MCP servers.",
         skills: sharedSkills({ legacyDirs: { user: home(".kimi-code", "skills"), project: project(".kimi-code", "skills") } }),
     },
@@ -529,6 +630,7 @@ const SPECS = [
             user: home(".config", "crush", "crushrc"),
             project: project(".crushrc"),
         },
+        detect: { bins: ["crush"], dirs: (ctx) => [join(ctx.home, ".config", "crush"), join(ctx.home, ".local", "share", "crush")] },
         restart: "Restart Crush so it reloads crushrc.",
         skills: sharedSkills({ legacyDirs: { user: home(".config", "crush", "skills"), project: project(".crush", "skills") } }),
     },
@@ -544,6 +646,7 @@ const SPECS = [
             signIn: (name) => `Amp opens summer.games to sign in for ${name} when it starts.`,
         },
         mcp: { user: (ctx) => join(xdgOrAppData(ctx), "amp", "settings.json"), project: null },
+        detect: { bins: ["amp"], dirs: (ctx) => [join(xdgOrAppData(ctx), "amp")] },
         restart: "Restart Amp so it reloads settings.json.",
         skills: sharedSkills({ legacyDirs: { user: (ctx) => join(xdgOrAppData(ctx), "amp", "skills"), project: null } }),
     },
@@ -559,6 +662,7 @@ const SPECS = [
             signIn: (name) => `In Droid, run /mcp, choose ${name} and Authenticate.`,
         },
         mcp: { user: home(".factory", "mcp.json"), project: project(".factory", "mcp.json") },
+        detect: { bins: ["droid"], dirs: (ctx) => [join(ctx.home, ".factory")] },
         restart: "Restart droid or run /mcp in the active session.",
         skills: sharedSkills({ legacyDirs: { user: home(".factory", "skills"), project: project(".factory", "skills") } }),
     },
@@ -574,6 +678,7 @@ const SPECS = [
             signIn: (name) => `In Junie, run /mcp, open ${name} and choose Authorize.`,
         },
         mcp: { user: home(".junie", "mcp", "mcp.json"), project: project(".junie", "mcp", "mcp.json") },
+        detect: { bins: ["junie"], dirs: (ctx) => [join(ctx.home, ".junie")] },
         restart: "Restart the JetBrains IDE so Junie reloads its MCP config.",
         skills: null,
         noSkillsNote: "Junie has no skills folder; put project guidance in .junie/guidelines.md. The MCP server ships summer_docs_search and summer_docs_read for in-chat guidance.",
@@ -590,6 +695,11 @@ const SPECS = [
             signIn: (name) => `Warp opens summer.games to sign in when ${name} starts.`,
         },
         mcp: { user: home(".warp", ".mcp.json"), project: project(".warp", ".mcp.json") },
+        detect: {
+            macApps: ["Warp.app"],
+            winApps: [join("Programs", "Warp", "warp.exe")],
+            dirs: (ctx) => [join(ctx.home, ".warp")],
+        },
         restart: "Warp detects the file and spawns the server; check Settings > AI > MCP servers.",
         skills: sharedSkills({ legacyDirs: { user: home(".warp", "skills"), project: project(".warp", "skills") } }),
     },
@@ -602,6 +712,11 @@ const SPECS = [
         format: "json-transport",
         // No Summer Games entry: Rovo Dev CLI has no OAuth sign-in for remote MCP servers (headers only).
         mcp: { user: home(".rovodev", "mcp.json"), project: null },
+        detect: {
+            // Rovo Dev runs as `acli rovodev`; acli alone is the Atlassian CLI, so the ~/.rovodev folder is the firmer signal.
+            bins: ["acli"],
+            dirs: (ctx) => [join(ctx.home, ".rovodev")],
+        },
         restart: "Restart Rovo Dev CLI so it reconnects its MCP servers.",
         skills: sharedSkills({ legacyDirs: { user: home(".rovodev", "skills"), project: project(".rovodev", "skills") } }),
     },
@@ -614,6 +729,12 @@ const SPECS = [
         format: "json",
         // No Summer Games entry: Qoder's remote-server fields in settings.json are not documented.
         mcp: { user: home(".qoder", "settings.json"), project: project(".mcp.json") },
+        detect: {
+            bins: ["qodercli"],
+            macApps: ["Qoder.app"],
+            winApps: [join("Programs", "Qoder", "Qoder.exe")],
+            dirs: (ctx) => [join(ctx.home, ".qoder")],
+        },
         restart: "Restart Qoder CLI so it reloads its MCP settings (the Qoder IDE manages servers in its UI).",
         skills: skillDirs(home(".qoder", "skills"), project(".qoder", "skills")),
     },
@@ -629,6 +750,7 @@ const SPECS = [
             signIn: (name) => `In Grok Build, run /mcps, select ${name} and press i to sign in.`,
         },
         mcp: { user: home(".grok", "config.toml"), project: project(".grok", "config.toml") },
+        detect: { bins: ["grok"], dirs: (ctx) => [join(ctx.home, ".grok")] },
         restart: "Restart Grok Build so it reloads config.toml (it also reads ~/.claude.json and .cursor/mcp.json).",
         skills: sharedSkills({ legacyDirs: { user: home(".grok", "skills"), project: project(".grok", "skills") } }),
     },
@@ -644,6 +766,7 @@ const SPECS = [
             signIn: (name) => `In Vibe, run /mcp login ${name}.`,
         },
         mcp: { user: home(".vibe", "config.toml"), project: project(".vibe", "config.toml") },
+        detect: { bins: ["vibe"], dirs: (ctx) => [join(ctx.home, ".vibe")] },
         restart: "Restart Vibe so it reloads config.toml.",
         skills: skillDirs(home(".vibe", "skills"), SHARED_SKILLS_PROJECT, { legacyDirs: { user: home(".vibe", "skills"), project: project(".vibe", "skills") } }),
     },
@@ -656,6 +779,13 @@ const SPECS = [
         format: "json",
         // No Summer Games entry: LM Studio's MCP client registration is closed and unverified.
         mcp: { user: home(".lmstudio", "mcp.json"), project: null },
+        detect: {
+            // The app installs the lms command into ~/.lmstudio/bin.
+            bins: ["lms"],
+            macApps: ["LM Studio.app"],
+            winApps: [join("Programs", "LM Studio", "LM Studio.exe"), join("Programs", "lm-studio", "LM Studio.exe")],
+            dirs: (ctx) => [join(ctx.home, ".lmstudio")],
+        },
         restart: "Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher.",
         skills: null,
         noSkillsNote: "LM Studio has no rules or skills folder. The MCP server ships summer_docs_search and summer_docs_read, so the model can pull Summer guidance in-chat.",

package/dist/installer/setup-error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * An error `summer setup` reports with a stable code, so a caller reading
+ * `--json` (the Summer desktop installer) can branch on the code instead of
+ * the message. The message stays the human sentence it always was.
+ */
+export declare class SetupError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * The code for any error a setup step throws: a SetupError's own code, a
+ * file-system failure by kind, else `fallback` (the step's generic code).
+ */
+export declare function setupErrorCode(error: unknown, fallback: string): string;
+export interface SetupStepError {
+    code: string;
+    message: string;
+}
+export declare function toStepError(error: unknown, fallback: string): SetupStepError;

package/dist/installer/setup-error.js

@@ -0,0 +1,34 @@
+/**
+ * An error `summer setup` reports with a stable code, so a caller reading
+ * `--json` (the Summer desktop installer) can branch on the code instead of
+ * the message. The message stays the human sentence it always was.
+ */
+export class SetupError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SetupError";
+    }
+}
+/** File-system errno codes that mean "this file cannot be written here". */
+const NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS", "EISDIR", "ENOTDIR"]);
+/**
+ * The code for any error a setup step throws: a SetupError's own code, a
+ * file-system failure by kind, else `fallback` (the step's generic code).
+ */
+export function setupErrorCode(error, fallback) {
+    if (error instanceof SetupError)
+        return error.code;
+    const errno = error?.code;
+    if (typeof errno === "string") {
+        if (NOT_WRITABLE.has(errno))
+            return "config_not_writable";
+        if (errno === "ENOSPC")
+            return "disk_full";
+    }
+    return fallback;
+}
+export function toStepError(error, fallback) {
+    return { code: setupErrorCode(error, fallback), message: error instanceof Error ? error.message : String(error) };
+}

package/dist/installer/version-check.d.ts

@@ -121,6 +121,8 @@ export interface RecordedInstall {
      *  --cli`, or skills installed alone) and `setup --cli` can set the agent
      *  up: the refresh keeps it without an MCP server. */
     cliOnly?: boolean;
+    /** The bundled node executable the entry runs (`setup --runtime <node> --package-dir <dir>`); cliPath is then that package's dist/bin/summer.js. */
+    runtime?: string;
 }
 /** An npm dist-tag (`latest`, `next`) or an exact version (`3.9.1`). */
 export type RefreshChannel = string;
@@ -170,6 +172,9 @@ export declare function buildSkillsVersionCheck(input: SkillsVersionCheckInput):
  * summer-engine entry refreshes with `--cli`, so the refresh adds no MCP server.
  */
 export declare function skillsRefreshCommand(agent: string, install: RecordedInstall | null, channel?: RefreshChannel): string;
+/** The shape `summer setup --runtime <node> --package-dir <dir>` writes:
+ *  `<absolute path to node> <dir>/dist/bin/summer.js mcp` (bundledRuntimeServerConfig). */
+export declare function isBundledRuntimeServerConfig(server: StdioMcpServerConfig): boolean;
 /** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
  *  (createSummerMcpServerConfig(true)). */
 export declare function isLocalDevServerConfig(server: StdioMcpServerConfig): boolean;

package/dist/installer/version-check.js

@@ -405,11 +405,29 @@ export function skillsRefreshCommand(agent, install, channel = "latest") {
             ? `node ${install.cliPath} setup ${agent} --cli --yes --force`
             : `npx clear-npx-cache && npx -y summer-engine@${channel} setup ${agent} --cli --yes --force`;
     }
+    if (install?.runtime && install.cliPath) {
+        // Keep the bundled runtime: the npx form needs a Node.js the person may not have.
+        const packageDir = install.cliPath.replace(/[\\/]dist[\\/]bin[\\/]summer\.js$/, "");
+        const runtime = shellArg(install.runtime);
+        return `${runtime} ${shellArg(install.cliPath)} setup ${agent} --runtime ${runtime} --package-dir ${shellArg(packageDir)} --yes --force`;
+    }
     if (install?.localDev && install.cliPath) {
         return `node ${install.cliPath} setup ${agent} --local-dev --yes --force`;
     }
     return `npx clear-npx-cache && npx -y summer-engine@${channel} setup ${agent} --yes --force${channel === "latest" ? "" : ` --channel ${channel}`}`;
 }
+/** A path in a printed command: quoted when it has a space (~/Library/Application Support, C:\\Program Files). */
+function shellArg(value) {
+    return /[\s"'$`]/.test(value) ? JSON.stringify(value) : value;
+}
+/** The shape `summer setup --runtime <node> --package-dir <dir>` writes:
+ *  `<absolute path to node> <dir>/dist/bin/summer.js mcp` (bundledRuntimeServerConfig). */
+export function isBundledRuntimeServerConfig(server) {
+    return (/^([a-z]:)?[\\/]/i.test(server.command) &&
+        /(^|[\\/])node(\.exe)?$/i.test(server.command) &&
+        /[\\/]dist[\\/]bin[\\/]summer\.js$/.test(server.args[0] ?? "") &&
+        server.args[1] === "mcp");
+}
 /** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
  *  (createSummerMcpServerConfig(true)). */
 export function isLocalDevServerConfig(server) {
@@ -550,6 +568,9 @@ export async function detectRecordedInstall(agent) {
             const text = existsSync(target.path) ? readFileSync(target.path, "utf-8") : "";
             const recorded = readRecordedMcpServer(text, target.format);
             if (recorded) {
+                if (isBundledRuntimeServerConfig(recorded)) {
+                    return { localDev: false, cliPath: recorded.args[0], runtime: recorded.command, source: "agent-config" };
+                }
                 const localDev = isLocalDevServerConfig(recorded);
                 return { localDev, cliPath: localDev ? recorded.args[0] ?? null : null, source: "agent-config" };
             }