summer-engine 3.0.0 → 3.1.0

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;