summer-engine 2.8.2 → 3.1.0

package/dist/installer/setup.d.ts

@@ -0,0 +1,76 @@
+import { SupportedAgent } from "./agent-config.js";
+export interface SkillSetupResult {
+    status: "installed" | "planned" | "skipped" | "failed";
+    message: string;
+    command?: string[];
+    stdout?: string;
+    stderr?: string;
+    /** Number of skills selected for install (all, or the recommended subset). */
+    count?: number;
+    /** Preview skills installed alongside the stable ones (the default). */
+    previewIncluded?: number;
+    /** Preview skills left out because --stable-only was given. */
+    previewSkipped?: number;
+    /** Where the skills land, e.g. "~/.claude/skills/<skill>/SKILL.md". */
+    destination?: string;
+    /** Post-install tallies parsed from `skills install` output. */
+    installed?: {
+        total: number;
+        added: number;
+        updated: number;
+    };
+}
+export interface SkillInstallInvocation {
+    command: string;
+    args: string[];
+    display: string[];
+}
+export interface SkillSetupOptions {
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+    /** Skills scope; defaults to the MCP scope so both land in the same place. */
+    scope?: "user" | "project";
+    /** Install only `recommended: true` skills instead of the whole library. */
+    recommended?: boolean;
+    /** Skip `status: preview` skills. By default they install like any other
+     *  skill — preview is a label carried in the skill's guidance, not a gate. */
+    stableOnly?: boolean;
+}
+/**
+ * The preview clause of the setup summary — one wording for the result message
+ * and the CLI line, e.g. "10 preview — labelled in each skill's guidance; use
+ * --stable-only to skip". Empty when there is nothing to say.
+ */
+export declare function previewNote(result: {
+    previewIncluded?: number;
+    previewSkipped?: number;
+}): string;
+/**
+ * Install the Summer skill library for an agent as part of `summer setup`.
+ *
+ * Installs EVERY library skill by default: skills are progressive-disclosure
+ * (name + description in context, body on activation), and the session entry
+ * skill `using-summer` is not in the recommended subset, so a
+ * recommended-only default left the documented starting point uninstalled.
+ * `--recommended` keeps the smaller subset as an opt-in; `--stable-only` drops
+ * the preview skills (installed by default, labelled in their guidance).
+ */
+export declare function setupSkills(agent: SupportedAgent, options: SkillSetupOptions): SkillSetupResult;
+/** @deprecated use setupSkills; kept for older callers. */
+export declare const setupRecommendedSkills: (agent: SupportedAgent, options: {
+    dryRun: boolean;
+    yes: boolean;
+    force: boolean;
+}) => SkillSetupResult;
+/**
+ * Count `skills install` result lines. Directory installs print
+ * "Installed <skill> -> <path>" for new copies and "Updated <skill> -> <path>"
+ * for re-installs; rule-file agents (Cursor, Cline, ...) always print
+ * "Generated <skill> -> <path>" and are counted as updated-or-new (added).
+ */
+export declare function tallyInstallOutput(stdout: string): {
+    total: number;
+    added: number;
+    updated: number;
+};

package/dist/installer/setup.js

@@ -0,0 +1,148 @@
+import { spawnSync } from "child_process";
+import { AGENT_CLIENTS, getSkillRegistry, selectSkillsForBulkInstall, } from "../core/skills-registry.js";
+import { describeInstallLocation, resolveInstallLocation } from "./skill-locations.js";
+import { agentSpec } from "./agent-table.js";
+/**
+ * The preview clause of the setup summary — one wording for the result message
+ * and the CLI line, e.g. "10 preview — labelled in each skill's guidance; use
+ * --stable-only to skip". Empty when there is nothing to say.
+ */
+export function previewNote(result) {
+    if (result.previewIncluded) {
+        return `${result.previewIncluded} preview — labelled in each skill's guidance; use --stable-only to skip`;
+    }
+    if (result.previewSkipped) {
+        return `${result.previewSkipped} preview skipped by --stable-only`;
+    }
+    return "";
+}
+/**
+ * Install the Summer skill library for an agent as part of `summer setup`.
+ *
+ * Installs EVERY library skill by default: skills are progressive-disclosure
+ * (name + description in context, body on activation), and the session entry
+ * skill `using-summer` is not in the recommended subset, so a
+ * recommended-only default left the documented starting point uninstalled.
+ * `--recommended` keeps the smaller subset as an opt-in; `--stable-only` drops
+ * the preview skills (installed by default, labelled in their guidance).
+ */
+export function setupSkills(agent, options) {
+    const spec = agentSpec(agent);
+    if (!spec.skills) {
+        return {
+            status: "skipped",
+            message: spec.noSkillsNote ?? `${spec.label} has no skills folder; the MCP server alone is configured.`,
+        };
+    }
+    const scope = options.scope ?? "user";
+    const recommended = Boolean(options.recommended);
+    const stableOnly = Boolean(options.stableOnly);
+    const invocation = skillInstallInvocation(agent, {
+        force: options.force,
+        scope,
+        recommended,
+        stableOnly,
+    });
+    if (!invocation) {
+        return {
+            status: "skipped",
+            message: "No automatic skill installer is available for this agent yet. Run `summer skills install --all` and point the agent at the installed SKILL.md files.",
+        };
+    }
+    const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(getSkillRegistry(), { recommended, stableOnly });
+    const count = selected.length;
+    const note = previewNote({ previewIncluded, previewSkipped });
+    const destination = isAgentClient(agent)
+        ? describeInstallLocation(resolveInstallLocation(agent, scope))
+        : undefined;
+    const subset = recommended ? "recommended " : "";
+    if (options.dryRun || !options.yes) {
+        return {
+            status: "planned",
+            command: invocation.display,
+            count,
+            previewIncluded,
+            previewSkipped,
+            destination,
+            message: `Would install ${count} ${subset}skills${note ? ` (${note})` : ""} to ${destination ?? "the agent's skills directory"} with: ${invocation.display.join(" ")}`,
+        };
+    }
+    const result = spawnSync(invocation.command, invocation.args, {
+        env: process.env,
+        encoding: "utf-8",
+    });
+    if (result.status === 0) {
+        const installed = tallyInstallOutput(result.stdout);
+        return {
+            status: "installed",
+            command: invocation.display,
+            count,
+            previewIncluded,
+            previewSkipped,
+            destination,
+            installed,
+            message: `Installed ${installed.total} ${subset}skills (${installed.added} new, ${installed.updated} updated${note ? `; ${note}` : ""}).`,
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        };
+    }
+    return {
+        status: "failed",
+        command: invocation.display,
+        count,
+        destination,
+        message: `Skill install failed with exit code ${result.status ?? "unknown"}.`,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+/** @deprecated use setupSkills; kept for older callers. */
+export const setupRecommendedSkills = (agent, options) => setupSkills(agent, { ...options, recommended: true });
+function isAgentClient(agent) {
+    return AGENT_CLIENTS.includes(agent);
+}
+/**
+ * Count `skills install` result lines. Directory installs print
+ * "Installed <skill> -> <path>" for new copies and "Updated <skill> -> <path>"
+ * for re-installs; rule-file agents (Cursor, Cline, ...) always print
+ * "Generated <skill> -> <path>" and are counted as updated-or-new (added).
+ */
+export function tallyInstallOutput(stdout) {
+    let added = 0;
+    let updated = 0;
+    for (const line of stdout.split("\n")) {
+        const m = line.match(/^\s*(Installed|Updated|Generated)\s+([a-z0-9-]+)\s+->/i);
+        if (!m)
+            continue;
+        if (m[1].toLowerCase() === "updated")
+            updated += 1;
+        else
+            added += 1;
+    }
+    return { total: added + updated, added, updated };
+}
+function skillInstallInvocation(agent, opts) {
+    const cliPath = process.argv[1];
+    if (!cliPath)
+        return null;
+    const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
+    const prefix = cliPath.endsWith(".js") ? [cliPath] : [];
+    const baseArgs = [
+        "skills",
+        "install",
+        opts.recommended ? "--recommended" : "--all",
+        "--agent",
+        agent,
+        "--scope",
+        opts.scope,
+    ];
+    if (opts.force)
+        baseArgs.push("--force");
+    if (opts.stableOnly)
+        baseArgs.push("--stable-only");
+    return {
+        command,
+        args: [...prefix, ...baseArgs],
+        display: [cliPath, ...baseArgs],
+    };
+}

package/dist/installer/skill-locations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Where `summer skills install` puts skills for each agent client.
+ *
+ * Lives in the installer layer (not cli/) so `summer setup` can report the
+ * destination and count without importing the CLI (import-direction contract
+ * §2: shared layers never import cli or mcp). The per-agent paths come from
+ * the one agent table (agent-table.ts); only the `summer` pseudo-client is
+ * resolved here.
+ */
+import { type AgentClient } from "../core/skills-registry.js";
+import { type SkillLocationKind } from "./agent-table.js";
+export declare const SKILL_SCOPES: readonly ["user", "project"];
+export type SkillScope = (typeof SKILL_SCOPES)[number];
+/** The agent/scope flags `summer skills install` accepts (legacy aliases included). */
+export interface SkillInstallSelection {
+    agent?: string;
+    scope?: string;
+    asClaudeSkill?: boolean;
+    asCursorSkill?: boolean;
+}
+/** Throws with a user-facing message on an unknown agent. */
+export declare function parseSkillAgent(value: string): AgentClient;
+/** Throws with a user-facing message on an unknown scope. */
+export declare function parseSkillScope(value: string): SkillScope;
+/** Pick the agent from --agent / legacy --as-claude-skill / --as-cursor-skill
+ *  (default "summer"); throws on conflicting flags. */
+export declare function resolveSkillAgent(opts: SkillInstallSelection): AgentClient;
+/** Explicit --scope wins; otherwise the agent's default (rule-file agents default to "project"). */
+export declare function resolveSkillScope(agent: AgentClient, opts: SkillInstallSelection): SkillScope;
+export interface InstallLocation {
+    kind: SkillLocationKind;
+    path: string;
+}
+export declare function resolveInstallLocation(agent: AgentClient, scope: SkillScope): InstallLocation;
+/** One-line, human path pattern for where an install location puts skills. */
+export declare function describeInstallLocation(location: InstallLocation): string;

package/dist/installer/skill-locations.js

@@ -0,0 +1,91 @@
+/**
+ * Where `summer skills install` puts skills for each agent client.
+ *
+ * Lives in the installer layer (not cli/) so `summer setup` can report the
+ * destination and count without importing the CLI (import-direction contract
+ * §2: shared layers never import cli or mcp). The per-agent paths come from
+ * the one agent table (agent-table.ts); only the `summer` pseudo-client is
+ * resolved here.
+ */
+import { join } from "path";
+import { homedir } from "os";
+import { AGENT_CLIENTS } from "../core/skills-registry.js";
+import { tildeify } from "../core/format.js";
+import { agentSpec, defaultPathContext, resolveSkillPath, } from "./agent-table.js";
+export const SKILL_SCOPES = ["user", "project"];
+function isAgentClient(value) {
+    return AGENT_CLIENTS.includes(value);
+}
+function isSkillScope(value) {
+    return SKILL_SCOPES.includes(value);
+}
+/** Throws with a user-facing message on an unknown agent. */
+export function parseSkillAgent(value) {
+    if (isAgentClient(value))
+        return value;
+    throw new Error(`Unknown agent: ${value}. Use one of: ${AGENT_CLIENTS.join(", ")}.`);
+}
+/** Throws with a user-facing message on an unknown scope. */
+export function parseSkillScope(value) {
+    if (isSkillScope(value))
+        return value;
+    throw new Error(`Unknown scope: ${value}. Use user or project.`);
+}
+/** Pick the agent from --agent / legacy --as-claude-skill / --as-cursor-skill
+ *  (default "summer"); throws on conflicting flags. */
+export function resolveSkillAgent(opts) {
+    if (opts.asClaudeSkill && opts.asCursorSkill) {
+        throw new Error("Use only one legacy alias: --as-claude-skill or --as-cursor-skill.");
+    }
+    const legacyAgent = opts.asClaudeSkill
+        ? "claude-code"
+        : opts.asCursorSkill
+            ? "cursor"
+            : undefined;
+    if (opts.agent && legacyAgent && opts.agent !== legacyAgent) {
+        throw new Error(`Conflicting agent options: --agent ${opts.agent} with legacy alias for ${legacyAgent}.`);
+    }
+    return parseSkillAgent(opts.agent ?? legacyAgent ?? "summer");
+}
+/** Explicit --scope wins; otherwise the agent's default (rule-file agents default to "project"). */
+export function resolveSkillScope(agent, opts) {
+    if (opts.scope)
+        return parseSkillScope(opts.scope);
+    if (agent === "summer")
+        return "user";
+    return agentSpec(agent).skills?.defaultScope ?? "user";
+}
+export function resolveInstallLocation(agent, scope) {
+    const overrideDir = process.env.SUMMER_SKILLS_DIR;
+    if (agent === "summer") {
+        const root = scope === "user" ? homedir() : process.cwd();
+        return { kind: "skill-dir", path: overrideDir ?? join(root, ".summer", "skills") };
+    }
+    const spec = agentSpec(agent);
+    const resolved = resolveSkillPath(spec, scope, defaultPathContext());
+    if (!resolved) {
+        throw new Error(`${spec.label} has no skills folder. ${spec.noSkillsNote ?? ""}`.trim());
+    }
+    if (overrideDir) {
+        return {
+            kind: resolved.kind,
+            path: resolved.kind === "windsurf-rule-file" ? join(overrideDir, ".windsurfrules") : overrideDir,
+        };
+    }
+    return { kind: resolved.kind, path: resolved.path };
+}
+/** One-line, human path pattern for where an install location puts skills. */
+export function describeInstallLocation(location) {
+    const p = tildeify(location.path);
+    switch (location.kind) {
+        case "skill-dir":
+            return `${p}/<skill>/SKILL.md`;
+        case "cursor-rule-dir":
+            return `${p}/summer-<skill>.mdc`;
+        case "cline-rule-dir":
+        case "opencode-skill-dir":
+            return `${p}/summer-<skill>.md`;
+        case "windsurf-rule-file":
+            return p;
+    }
+}

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

@@ -0,0 +1,178 @@
+/**
+ * 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 { type McpFormat } from "./agent-table.js";
+import { type StdioMcpServerConfig } from "./agent-config.js";
+export interface SemverParts {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export type DriftSeverity = "ok" | "warning" | "fail";
+export interface DriftClassification {
+    severity: DriftSeverity;
+    reason: "current" | "ahead" | "patch-only" | "minor-drift" | "major-drift" | "behind";
+}
+export declare function parseSemver(version: string): SemverParts | null;
+export declare function compareSemver(a: SemverParts, b: SemverParts): number;
+/**
+ * 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 declare function classifyDrift(installed: SemverParts, target: SemverParts): DriftClassification;
+export interface RegistryFetchOptions {
+    /** Override the default fetch (used in tests). Must implement the global fetch shape. */
+    fetchImpl?: typeof fetch;
+    /** Override the timeout. */
+    timeoutMs?: number;
+    /** Override the URL (used in tests). */
+    url?: string;
+}
+export interface RegistryFetchResult {
+    ok: true;
+    version: string;
+}
+export interface RegistryFetchFailure {
+    ok: false;
+    reason: "registry-unreachable";
+    message?: string;
+}
+export declare function fetchLatestRegistryVersion(options?: RegistryFetchOptions): Promise<RegistryFetchResult | RegistryFetchFailure>;
+/**
+ * Build the `cli-version-current` doctor check. Pure helper so tests can drive
+ * registry responses through `fetchImpl` rather than touching the network.
+ */
+export interface CliVersionCheckInput {
+    installedVersion: string;
+    registry: RegistryFetchResult | RegistryFetchFailure;
+}
+export interface CliVersionCheckOutput {
+    status: DriftSeverity;
+    message: string;
+    details: Record<string, unknown>;
+}
+export declare function buildCliVersionCheck(input: CliVersionCheckInput): CliVersionCheckOutput;
+export declare const SKILL_VERSION_MARKER_FILENAME = ".summer-version";
+export interface SkillVersionMarker {
+    version: string;
+    installedAt: string;
+}
+export declare function readSkillMarker(dir: string): SkillVersionMarker | null;
+export declare function writeSkillMarker(dir: string, version: string, now?: Date): string;
+/**
+ * Candidate locations for skill-version markers. Listed roughly in order of
+ * how likely a Summer user is to have them populated. We probe every candidate,
+ * not just the first one — if multiple agents have markers, the most-stale one
+ * wins so we surface the worst case to the user.
+ */
+export interface SkillMarkerCandidate {
+    agent: string;
+    dir: string;
+}
+export declare function defaultSkillMarkerCandidates(): SkillMarkerCandidate[];
+/**
+ * How the agent's Summer MCP entry was recorded by `summer setup`
+ * (agent-config.ts createSummerMcpServerConfig): a `--local-dev` link runs
+ * `node <checkout>/dist/bin/summer.js mcp`; a normal install runs
+ * `npx -y summer-engine@latest mcp`. The refresh command doctor recommends
+ * must keep that shape — the npx form on a local-dev machine would replace
+ * the checkout link with the published package (E2E 2026-09-03 F-09).
+ */
+export interface RecordedInstall {
+    localDev: boolean;
+    /** The CLI entry point the agent runs, when local-dev. */
+    cliPath: string | null;
+    /** Where the answer came from: the agent's config file, or — when it has
+     *  no readable Summer entry — the nature of the CLI running this check. */
+    source: "agent-config" | "running-cli";
+}
+export type RefreshChannel = "latest" | "next";
+/** 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 declare function refreshChannel(installedVersion: string, latestVersion: string | undefined): RefreshChannel;
+/** 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 declare function resolveDefaultChannel(installedVersion: string): Promise<{
+    channel: RefreshChannel;
+    note?: string;
+}>;
+export interface SkillsVersionCheckInput {
+    installedCliVersion: string;
+    candidates: SkillMarkerCandidate[];
+    /** npm latest, when known, so the refresh command names the right dist-tag. */
+    latestRegistryVersion?: string;
+    /** Resolves how the stale agent's MCP entry was recorded; defaults to
+     *  detectRecordedInstall. Seam for tests. */
+    recordedInstall?: (agent: string) => Promise<RecordedInstall | null> | RecordedInstall | null;
+}
+export interface SkillsVersionCheckOutput {
+    /** "ok" or "warning" — stale skills never fail doctor (TESTING.md §d). */
+    status: DriftSeverity;
+    message: string;
+    details: Record<string, unknown>;
+}
+export declare function buildSkillsVersionCheck(input: SkillsVersionCheckInput): Promise<SkillsVersionCheckOutput>;
+/**
+ * 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 declare function skillsRefreshCommand(agent: string, install: RecordedInstall | null, channel?: RefreshChannel): string;
+/** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
+ *  (createSummerMcpServerConfig(true)). */
+export declare function isLocalDevServerConfig(server: StdioMcpServerConfig): boolean;
+/**
+ * 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 declare function readRecordedMcpServer(text: string, format: McpFormat): StdioMcpServerConfig | 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 declare function runningCliIsCheckout(packageRoot?: string): boolean;
+/**
+ * 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 declare function detectRecordedInstall(agent: string): Promise<RecordedInstall | null>;
+/**
+ * Helper used by the MCP server boot path to render a one-line drift notice.
+ * Returns null when no notice is needed (fresh, ahead, patch-only, offline).
+ */
+export interface BootDriftNotice {
+    installedVersion: string;
+    latestVersion: string;
+    agent?: string;
+    text: string;
+}
+export declare function buildBootDriftNotice(installedVersion: string, registry: RegistryFetchResult | RegistryFetchFailure, agent?: string): BootDriftNotice | null;