summer-engine 2.8.2 → 3.1.0

package/dist/installer/version-check.js

@@ -0,0 +1,479 @@
+/**
+ * Version drift detection helpers used by `summer doctor` and the MCP server
+ * boot path.
+ *
+ * Two checks are exposed:
+ *   - cli-version-current: compares installed package.json version against the
+ *     latest published `summer-engine` on the npm registry.
+ *   - skills-version-stale: reads a `.summer-version` marker written into the
+ *     skill install dir (per-agent) and compares against the current CLI.
+ *
+ * Both are designed to be silent on offline / network errors — we never want
+ * to false-alarm a user just because their wifi is flaky.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+import { allAgentSpecs, defaultPathContext, resolveSkillPath } from "./agent-table.js";
+import { join, sep } from "node:path";
+import { PACKAGE_ROOT } from "../core/package-root.js";
+import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, topLevelKey, } from "./agent-config.js";
+const NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org/summer-engine/latest";
+const REGISTRY_FETCH_TIMEOUT_MS = 3000;
+export function parseSemver(version) {
+    if (!version)
+        return null;
+    // Strip any leading "v" and trim build / pre-release tags after the first hyphen.
+    const cleaned = version.trim().replace(/^v/, "").split(/[-+]/)[0];
+    const match = cleaned.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!match)
+        return null;
+    const [, maj, min, pat] = match;
+    return {
+        major: Number(maj),
+        minor: Number(min),
+        patch: Number(pat),
+    };
+}
+export function compareSemver(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+/**
+ * Classify drift between an installed and a target version.
+ *
+ *   ok        installed >= target, OR installed is behind only on patch
+ *             OR installed differs only in pre-release/build metadata.
+ *   warning   one minor version behind on the same major.
+ *   fail      two or more minors behind, or any major-version drift behind.
+ */
+export function classifyDrift(installed, target) {
+    const cmp = compareSemver(installed, target);
+    if (cmp === 0)
+        return { severity: "ok", reason: "current" };
+    if (cmp > 0)
+        return { severity: "ok", reason: "ahead" };
+    // installed < target
+    if (installed.major < target.major) {
+        return { severity: "fail", reason: "major-drift" };
+    }
+    if (installed.minor === target.minor) {
+        // Same major + minor, target patch is higher → patch-only drift.
+        return { severity: "ok", reason: "patch-only" };
+    }
+    const minorDelta = target.minor - installed.minor;
+    if (minorDelta >= 2) {
+        return { severity: "fail", reason: "minor-drift" };
+    }
+    return { severity: "warning", reason: "minor-drift" };
+}
+export async function fetchLatestRegistryVersion(options = {}) {
+    const url = options.url ?? NPM_REGISTRY_LATEST_URL;
+    const timeoutMs = options.timeoutMs ?? REGISTRY_FETCH_TIMEOUT_MS;
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return { ok: false, reason: "registry-unreachable", message: "fetch unavailable" };
+    }
+    try {
+        const response = await fetchImpl(url, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: "application/json" },
+        });
+        if (!response.ok) {
+            return {
+                ok: false,
+                reason: "registry-unreachable",
+                message: `registry responded ${response.status}`,
+            };
+        }
+        const body = (await response.json());
+        if (typeof body.version !== "string") {
+            return {
+                ok: false,
+                reason: "registry-unreachable",
+                message: "registry payload missing version",
+            };
+        }
+        return { ok: true, version: body.version };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "registry-unreachable",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+const RECOMMENDED_REFRESH_COMMAND = "npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force";
+export function buildCliVersionCheck(input) {
+    if (!input.registry.ok) {
+        return {
+            status: "ok",
+            message: "registry unreachable, skipping check",
+            details: {
+                installedVersion: input.installedVersion,
+                reason: input.registry.reason,
+            },
+        };
+    }
+    const installed = parseSemver(input.installedVersion);
+    const latest = parseSemver(input.registry.version);
+    if (!installed || !latest) {
+        // If we can't parse either side, don't false-alarm.
+        return {
+            status: "ok",
+            message: "could not compare versions",
+            details: {
+                installedVersion: input.installedVersion,
+                latestVersion: input.registry.version,
+                reason: "unparseable-version",
+            },
+        };
+    }
+    const drift = classifyDrift(installed, latest);
+    const baseDetails = {
+        installedVersion: input.installedVersion,
+        latestVersion: input.registry.version,
+    };
+    switch (drift.severity) {
+        case "ok":
+            return {
+                status: "ok",
+                message: drift.reason === "patch-only"
+                    ? `v${input.installedVersion} (latest ${input.registry.version}, patch-only)`
+                    : drift.reason === "ahead"
+                        ? `v${input.installedVersion} (ahead of latest ${input.registry.version})`
+                        : `v${input.installedVersion}`,
+                details: { ...baseDetails, reason: drift.reason },
+            };
+        case "warning":
+            return {
+                status: "warning",
+                message: `v${input.installedVersion} → v${input.registry.version} available`,
+                details: {
+                    ...baseDetails,
+                    recommendedAction: RECOMMENDED_REFRESH_COMMAND,
+                },
+            };
+        case "fail":
+            return {
+                status: "fail",
+                message: `v${input.installedVersion} is significantly behind v${input.registry.version}`,
+                details: {
+                    ...baseDetails,
+                    recommendedAction: RECOMMENDED_REFRESH_COMMAND,
+                },
+            };
+    }
+}
+// ---------------------------------------------------------------------------
+// Skill marker (.summer-version) helpers
+// ---------------------------------------------------------------------------
+export const SKILL_VERSION_MARKER_FILENAME = ".summer-version";
+export function readSkillMarker(dir) {
+    const path = join(dir, SKILL_VERSION_MARKER_FILENAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version !== "string" || typeof parsed.installedAt !== "string") {
+            return null;
+        }
+        return { version: parsed.version, installedAt: parsed.installedAt };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSkillMarker(dir, version, now = new Date()) {
+    const path = join(dir, SKILL_VERSION_MARKER_FILENAME);
+    const payload = {
+        version,
+        installedAt: now.toISOString(),
+    };
+    writeFileSync(path, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+    return path;
+}
+export function defaultSkillMarkerCandidates() {
+    const ctx = defaultPathContext();
+    const candidates = [
+        { agent: "summer", dir: join(ctx.home, ".summer", "skills") },
+    ];
+    // Every agent with a user-scope skills home, from the one agent table.
+    // Devin Desktop's single rules file has no dir to mark; skip that kind.
+    for (const spec of allAgentSpecs()) {
+        const home = resolveSkillPath(spec, "user", ctx);
+        if (!home || home.kind === "windsurf-rule-file")
+            continue;
+        candidates.push({ agent: spec.id, dir: home.path });
+    }
+    return candidates;
+}
+/** The npm dist-tag a refresh command should name. A CLI that is AHEAD of
+ *  npm `latest` was installed from `next` (a soaking release); telling that
+ *  user to run `summer-engine@latest` would silently downgrade the MCP server
+ *  while leaving the newer skills in place (release review P1-3). */
+export function refreshChannel(installedVersion, latestVersion) {
+    const installed = parseSemver(installedVersion);
+    const latest = latestVersion ? parseSemver(latestVersion) : null;
+    if (!installed || !latest)
+        return "latest";
+    return classifyDrift(installed, latest).reason === "ahead" ? "next" : "latest";
+}
+/** Default `summer setup` channel when neither --channel nor SUMMER_CHANNEL is
+ *  given: `next` while this CLI is ahead of npm latest, else `latest`. Network
+ *  failure means `latest` (never blocks setup). */
+export async function resolveDefaultChannel(installedVersion) {
+    const registry = await fetchLatestRegistryVersion();
+    if (!registry.ok)
+        return { channel: "latest" };
+    const channel = refreshChannel(installedVersion, registry.version);
+    return channel === "next"
+        ? { channel, note: `This CLI (${installedVersion}) is ahead of npm latest (${registry.version}); the MCP entry is pinned to summer-engine@next so the agent keeps running this release. Pass --channel latest to override.` }
+        : { channel };
+}
+export async function buildSkillsVersionCheck(input) {
+    const cliParsed = parseSemver(input.installedCliVersion);
+    if (!cliParsed) {
+        return {
+            status: "ok",
+            message: "could not parse CLI version",
+            details: { reason: "unparseable-cli-version" },
+        };
+    }
+    const resolutions = [];
+    for (const candidate of input.candidates) {
+        const marker = readSkillMarker(candidate.dir);
+        if (!marker)
+            continue;
+        const markerSemver = parseSemver(marker.version);
+        if (!markerSemver)
+            continue;
+        const drift = classifyDrift(markerSemver, cliParsed);
+        const installedAtMs = Date.parse(marker.installedAt);
+        resolutions.push({
+            agent: candidate.agent,
+            dir: candidate.dir,
+            marker,
+            drift,
+            installedAtMs: Number.isFinite(installedAtMs) ? installedAtMs : 0,
+        });
+    }
+    if (resolutions.length === 0) {
+        return {
+            status: "ok",
+            message: "no skill marker yet (treated as fresh install)",
+            details: { reason: "no-marker" },
+        };
+    }
+    // Pick the worst (most-stale) marker. Severity rank fail > warning > ok;
+    // tiebreak by oldest installedAt.
+    const severityRank = { fail: 2, warning: 1, ok: 0 };
+    const worst = [...resolutions].sort((a, b) => {
+        const sevDiff = severityRank[b.drift.severity] - severityRank[a.drift.severity];
+        if (sevDiff !== 0)
+            return sevDiff;
+        return a.installedAtMs - b.installedAtMs;
+    })[0];
+    const baseDetails = {
+        agent: worst.agent,
+        skillsDir: worst.dir,
+        markerVersion: worst.marker.version,
+        installedAt: worst.marker.installedAt,
+        cliVersion: input.installedCliVersion,
+    };
+    if (worst.drift.severity === "ok") {
+        return {
+            status: "ok",
+            message: `skills v${worst.marker.version} match CLI`,
+            details: baseDetails,
+        };
+    }
+    // Skills that lag the CLI still work — the toolkit is not broken, the
+    // library it installed is older than the one it ships. That is a warning
+    // with a refresh command, never an exit-1 failure; a "fail"-grade drift
+    // (two minors or a major behind) only changes the wording.
+    const install = await resolveRecordedInstall(input.recordedInstall, worst.agent);
+    return {
+        status: "warning",
+        message: worst.drift.severity === "fail"
+            ? `skills v${worst.marker.version} are significantly behind v${input.installedCliVersion}`
+            : `skills v${worst.marker.version} are one minor version behind v${input.installedCliVersion}`,
+        details: {
+            ...baseDetails,
+            drift: worst.drift.reason,
+            ...(install ? { install } : {}),
+            recommendedAction: skillsRefreshCommand(worst.agent, install, refreshChannel(input.installedCliVersion, input.latestRegistryVersion)),
+        },
+    };
+}
+async function resolveRecordedInstall(resolver, agent) {
+    try {
+        return (await (resolver ?? detectRecordedInstall)(agent)) ?? null;
+    }
+    catch {
+        // A detection failure must not break doctor; the npx form is the
+        // conservative default only when nothing says local-dev.
+        return null;
+    }
+}
+/**
+ * The command that refreshes an agent's skills without changing how its MCP
+ * entry was recorded: the local-dev form re-links the same checkout
+ * (`setup --local-dev --force` re-copies the checkout's skills); the npx form
+ * is for installs that already run the published package.
+ */
+export function skillsRefreshCommand(agent, install, channel = "latest") {
+    if (install?.localDev && install.cliPath) {
+        return `node ${install.cliPath} setup ${agent} --local-dev --yes --force`;
+    }
+    const tag = channel === "next" ? "next" : "latest";
+    return `npx clear-npx-cache && npx -y summer-engine@${tag} setup ${agent} --yes --force${channel === "next" ? " --channel next" : ""}`;
+}
+/** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
+ *  (createSummerMcpServerConfig(true)). */
+export function isLocalDevServerConfig(server) {
+    const entry = server.args[0] ?? "";
+    return (server.command === "node" &&
+        /(^|[\\/])bin[\\/]summer\.js$/.test(entry) &&
+        server.args[1] === "mcp");
+}
+/**
+ * Read the Summer MCP entry an agent's config records, shape-tolerantly
+ * (this is the read side of agent-config.ts's per-format writers):
+ *   json           {"mcpServers": {"summer-engine": {command, args}}}     Claude Code, Cursor, …
+ *   json-copilot   {"mcpServers": {"summer-engine": {type, command, args}}}
+ *   json-vscode    {"servers":    {"summer-engine": {type, command, args}}}
+ *   json-opencode  {"mcp":        {"summer-engine": {type, command: [cmd, ...args]}}}
+ *   json-zed       {"context_servers": {"summer-engine": {source, command, args}}}
+ *   yaml-goose     extensions: summer-engine: {cmd, args}
+ *   yaml-hermes    mcp_servers: summer-engine: {command, args}
+ *   toml (codex)   [mcp_servers.summer-engine]\ncommand = "…"\nargs = ["…", …]
+ * Returns null when the file is missing, unparsable, or has no Summer entry.
+ */
+export function readRecordedMcpServer(text, format) {
+    if (!text.trim())
+        return null;
+    if (format === "toml-array") {
+        const block = text.match(new RegExp(`^\\[\\[mcp_servers\\]\\]\\s*$([\\s\\S]*?)(?=^\\[|(?![\\s\\S]))`, "gm"));
+        for (const candidate of block ?? []) {
+            if (!new RegExp(`^name\\s*=\\s*"${SUMMER_MCP_SERVER_NAME}"`, "m").test(candidate))
+                continue;
+            const command = candidate.match(/^command\s*=\s*"((?:[^"\\]|\\.)*)"/m)?.[1];
+            const argsText = candidate.match(/^args\s*=\s*\[([^\]]*)\]/m)?.[1] ?? "";
+            if (!command)
+                return null;
+            const args = [...argsText.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(.)/g, "$1"));
+            return { command: command.replace(/\\(.)/g, "$1"), args };
+        }
+        return null;
+    }
+    if (format === "toml") {
+        const table = text.match(new RegExp(`^\\[mcp_servers\\.${SUMMER_MCP_SERVER_NAME.replace(/[-.]/g, "\\$&")}\\]\\s*$([\\s\\S]*?)(?=^\\[|(?![\\s\\S]))`, "m"));
+        if (!table)
+            return null;
+        const command = table[1].match(/^command\s*=\s*"((?:[^"\\]|\\.)*)"/m)?.[1];
+        const argsText = table[1].match(/^args\s*=\s*\[([^\]]*)\]/m)?.[1] ?? "";
+        if (!command)
+            return null;
+        const args = [...argsText.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => m[1].replace(/\\(.)/g, "$1"));
+        return { command: command.replace(/\\(.)/g, "$1"), args };
+    }
+    let parsed;
+    try {
+        parsed = format === "yaml-goose" || format === "yaml-hermes" ? parseYaml(text) : JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const root = parsed;
+    // The format's own key first, then the other shapes (a user may have moved to a newer file layout).
+    const containers = [topLevelKey(format), "mcpServers", "servers", "mcp", "context_servers", "extensions", "mcp_servers", "amp.mcpServers"];
+    for (const container of [...new Set(containers)]) {
+        const servers = root[container];
+        if (!servers || typeof servers !== "object")
+            continue;
+        const entry = servers[SUMMER_MCP_SERVER_NAME];
+        if (!entry || typeof entry !== "object")
+            continue;
+        const record = entry;
+        if (typeof record.cmd === "string") {
+            // Goose: { cmd, args }
+            const args = Array.isArray(record.args) ? record.args.filter((part) => typeof part === "string") : [];
+            return { command: record.cmd, args };
+        }
+        if (Array.isArray(record.command)) {
+            const [command, ...args] = record.command.filter((part) => typeof part === "string");
+            return command ? { command, args } : null;
+        }
+        if (typeof record.command === "string") {
+            const args = Array.isArray(record.args)
+                ? record.args.filter((part) => typeof part === "string")
+                : [];
+            return { command: record.command, args };
+        }
+    }
+    return null;
+}
+/** Is the CLI running this check a source checkout rather than an installed
+ *  package? npm/npx/global installs all live under a node_modules directory. */
+export function runningCliIsCheckout(packageRoot = PACKAGE_ROOT) {
+    return !packageRoot.split(/[\\/]/).includes("node_modules");
+}
+/**
+ * How `summer setup` recorded the agent's Summer MCP entry. Resolves the
+ * agent's user-scope config path through agent-config's own target
+ * resolution (print mode: no file is written or read there), then reads the
+ * entry. Marker agents without an agent config ("summer") and agents whose
+ * config has no readable Summer entry fall back to the nature of the running
+ * CLI: a checkout recommends re-linking itself, an installed package the npx form.
+ */
+export async function detectRecordedInstall(agent) {
+    const supported = parseAgent(agent);
+    if (supported) {
+        try {
+            const target = await configureAgentMcp({ agent: supported, scope: "user", print: true });
+            if (existsSync(target.path)) {
+                const recorded = readRecordedMcpServer(readFileSync(target.path, "utf-8"), target.format);
+                if (recorded) {
+                    const localDev = isLocalDevServerConfig(recorded);
+                    return { localDev, cliPath: localDev ? recorded.args[0] ?? null : null, source: "agent-config" };
+                }
+            }
+        }
+        catch {
+            // Unreadable config: fall through to the running-CLI answer.
+        }
+    }
+    const checkout = runningCliIsCheckout();
+    return {
+        localDev: checkout,
+        cliPath: checkout ? [PACKAGE_ROOT, "dist", "bin", "summer.js"].join(sep) : null,
+        source: "running-cli",
+    };
+}
+export function buildBootDriftNotice(installedVersion, registry, agent) {
+    if (!registry.ok)
+        return null;
+    const installed = parseSemver(installedVersion);
+    const latest = parseSemver(registry.version);
+    if (!installed || !latest)
+        return null;
+    const drift = classifyDrift(installed, latest);
+    if (drift.severity === "ok")
+        return null;
+    const agentSlug = agent ?? "<agent>";
+    const text = `[summer] CLI ${installedVersion} — latest ${registry.version}; ` +
+        `run \`npx clear-npx-cache && npx -y summer-engine@latest setup ${agentSlug} --yes --force\` to update.`;
+    return {
+        installedVersion,
+        latestVersion: registry.version,
+        agent,
+        text,
+    };
+}

package/dist/{lib/mcp-boot-notice.d.ts → mcp/boot-notice.d.ts}

@@ -1,3 +1,3 @@
-import type { BootDriftNotice } from "./version-check.js";
+import type { BootDriftNotice } from "../installer/version-check.js";
 export declare function getCachedBootDriftNotice(): BootDriftNotice | null;
 export declare function setCachedBootDriftNotice(notice: BootDriftNotice | null): void;

package/dist/{commands/mcp.js → mcp/command.js}

@@ -1,6 +1,6 @@
-import { Command } from "commander";
-import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
-import { startMcpServer } from "../mcp/server.js";
+import { Command, Option } from "commander";
+import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../installer/agent-config.js";
+import { startMcpServer } from "./server.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
     .option("--project <path>", "Bind local engine tools to the editor running this project")
@@ -11,13 +11,22 @@ export const mcpCommand = new Command("mcp")
         instanceId: opts.instance,
     });
 });
+// Deprecated alias. `summer setup <agent>` (src/cli/commands/setup.ts) is the
+// one setup path: the same configureAgentMcp() write plus skills + doctor.
+// This stays for one release so existing docs/scripts keep working; it cannot
+// delegate to the cli layer (contract §2: mcp never imports cli), so it calls
+// the shared installer directly and says where to go.
 mcpCommand
     .command("setup <agent>")
-    .description("Configure an AI agent to use the Summer Engine MCP server")
+    .description("Deprecated alias of `summer setup <agent>`: write only the MCP config for an agent")
     .option("--scope <scope>", "Configuration scope: user or project", "user")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--dry-run", "Show planned changes without writing files")
-    .option("--local-dev", "Use the local built CLI instead of npx summer-engine")
+    .addOption(
+// Contributor-only: point the config at this checkout's built CLI instead
+// of npx summer-engine. Hidden from the public surface; also honoured
+// when SUMMER_DEV=1 is set.
+new Option("--local-dev", "Use the local built CLI instead of npx summer-engine").hideHelp())
     .option("--json", "Print the setup result as JSON")
     .action(async (agentValue, opts) => {
     const agent = parseAgent(agentValue);
@@ -33,12 +42,15 @@ mcpCommand
         scope,
         print: opts.print,
         dryRun: opts.dryRun,
-        localDev: opts.localDev,
+        localDev: opts.localDev || process.env.SUMMER_DEV === "1",
     });
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
+    if (!opts.print) {
+        console.warn(`Note: 'summer mcp setup' is deprecated; use 'summer setup ${agent}' (same MCP config, plus skills and doctor).`);
+    }
     if (result.print) {
         console.log(result.snippet.trimEnd());
     }

package/dist/mcp/server.d.ts

@@ -1,10 +1,30 @@
-import { EngineApiClient } from "../lib/api-client.js";
-import type { EngineSelection } from "../lib/engine.js";
-import { getCachedBootDriftNotice as getCachedNotice } from "../lib/mcp-boot-notice.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { EngineApiClient } from "../core/api-client.js";
+import type { EngineSelection } from "../core/engine.js";
+import { getCachedBootDriftNotice as getCachedNotice } from "./boot-notice.js";
 export declare const getCachedBootDriftNotice: typeof getCachedNotice;
+/**
+ * Server `instructions` in the MCP initialize response (SDK ServerOptions,
+ * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
+ * session, before any tool call — the place for the five habits the E2E run
+ * (docs/design/archive/E2E-2026-09-03.md, F-17) showed an agent needs on the first
+ * turn and would otherwise learn the hard way. Kept under 600 characters so
+ * it costs a few hundred tokens once; the full operating guide stays in the
+ * summer_agent_playbook prompt / summer_get_agent_playbook tool.
+ */
+export declare const SUMMER_MCP_INSTRUCTIONS: string;
 export declare function configureMcpEngineSelection(selection?: EngineSelection): void;
 export declare function getClient(): Promise<EngineApiClient>;
 export declare function resetClient(): void;
+/**
+ * Build the MCP server with every Summer tool registered, without connecting
+ * a transport. startMcpServer() uses this; tests use it to count the live
+ * tool surface against registry/generated/counts.json.
+ */
+export declare function createMcpServer(): {
+    server: McpServer;
+    getRegisteredToolCount: () => number;
+};
 export interface StartMcpServerOptions {
     projectPath?: string;
     instanceId?: string;