summer-engine 1.2.0 → 1.3.0

package/dist/commands/skills.js

@@ -1,25 +1,29 @@
 import { Command } from "commander";
-import { existsSync, mkdirSync, readdirSync, readFileSync, cpSync, } from "fs";
+import { existsSync, mkdirSync, readFileSync, cpSync, writeFileSync, } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { homedir } from "os";
+import { AGENT_CLIENTS, SKILL_REGISTRY, } from "../lib/skills-registry.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Resolve skills dir: from dist/commands/skills.js -> ../../skills
 const skillsDir = join(__dirname, "..", "..", "skills");
+const SKILL_SCOPES = ["user", "project"];
 function getBuiltinSkills() {
-    if (!existsSync(skillsDir))
-        return [];
-    const entries = readdirSync(skillsDir, { withFileTypes: true });
     const skills = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory())
+    for (const entry of SKILL_REGISTRY) {
+        if (!entry.public)
             continue;
-        const skillPath = join(skillsDir, entry.name, "SKILL.md");
+        const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
         if (!existsSync(skillPath))
             continue;
-        const meta = parseSkillFrontmatter(skillPath);
-        if (meta)
-            skills.push(meta);
+        const frontmatter = parseSkillFrontmatter(skillPath);
+        if (!frontmatter)
+            continue;
+        skills.push({
+            ...entry,
+            name: entry.name,
+            description: frontmatter.description,
+        });
     }
     return skills;
 }
@@ -40,12 +44,215 @@ function parseSkillFrontmatter(skillPath) {
         return null;
     }
 }
+function getSkillMeta(name) {
+    return getBuiltinSkills().find((skill) => skill.name === name) ?? null;
+}
 function getSkillPath(name) {
-    const path = join(skillsDir, name);
+    const entry = SKILL_REGISTRY.find((s) => s.name === name);
+    if (!entry)
+        return null;
+    const path = join(skillsDir, entry.category, entry.name);
     if (!existsSync(path) || !existsSync(join(path, "SKILL.md")))
         return null;
     return path;
 }
+function getSkillBody(name) {
+    const entry = SKILL_REGISTRY.find((s) => s.name === name);
+    if (!entry)
+        throw new Error(`Unknown skill: ${name}`);
+    const skillPath = join(skillsDir, entry.category, entry.name, "SKILL.md");
+    const content = readFileSync(skillPath, "utf-8");
+    return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "").trim();
+}
+function die(message) {
+    console.error(message);
+    process.exit(1);
+}
+function isAgentClient(value) {
+    return AGENT_CLIENTS.includes(value);
+}
+function isSkillScope(value) {
+    return SKILL_SCOPES.includes(value);
+}
+function parseAgent(value) {
+    if (isAgentClient(value))
+        return value;
+    die(`Unknown agent: ${value}. Use one of: ${AGENT_CLIENTS.join(", ")}.`);
+}
+function parseScope(value) {
+    if (isSkillScope(value))
+        return value;
+    die(`Unknown scope: ${value}. Use user or project.`);
+}
+function resolveAgent(opts) {
+    if (opts.asClaudeSkill && opts.asCursorSkill) {
+        die("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) {
+        die(`Conflicting agent options: --agent ${opts.agent} with legacy alias for ${legacyAgent}.`);
+    }
+    return parseAgent(opts.agent ?? legacyAgent ?? "summer");
+}
+function resolveScope(agent, opts) {
+    if (opts.scope)
+        return parseScope(opts.scope);
+    if (agent === "cursor" || agent === "windsurf")
+        return "project";
+    return "user";
+}
+function agentLabel(agent) {
+    switch (agent) {
+        case "claude-code":
+            return "Claude Code";
+        case "codex":
+            return "Codex";
+        case "cursor":
+            return "Cursor";
+        case "windsurf":
+            return "Windsurf";
+        case "summer":
+            return "Summer";
+    }
+}
+function resolveInstallLocation(agent, scope) {
+    const overrideDir = process.env.SUMMER_SKILLS_DIR;
+    if (overrideDir) {
+        if (agent === "cursor")
+            return { kind: "cursor-rule-dir", path: overrideDir };
+        if (agent === "windsurf") {
+            return { kind: "windsurf-rule-file", path: join(overrideDir, ".windsurfrules") };
+        }
+        return { kind: "skill-dir", path: overrideDir };
+    }
+    const root = scope === "user" ? homedir() : process.cwd();
+    switch (agent) {
+        case "codex":
+            return { kind: "skill-dir", path: join(root, ".agents", "skills") };
+        case "claude-code":
+            return { kind: "skill-dir", path: join(root, ".claude", "skills") };
+        case "cursor":
+            return { kind: "cursor-rule-dir", path: join(root, ".cursor", "rules") };
+        case "windsurf":
+            return { kind: "windsurf-rule-file", path: join(root, ".windsurfrules") };
+        case "summer":
+            return { kind: "skill-dir", path: join(root, ".summer", "skills") };
+    }
+}
+function selectSkills(name, opts) {
+    if (opts.all && opts.recommended) {
+        die("Use only one bulk option: --all or --recommended.");
+    }
+    if (name && (opts.all || opts.recommended)) {
+        die("Specify either a skill name or a bulk option, not both.");
+    }
+    const skills = getBuiltinSkills();
+    if (opts.all)
+        return skills;
+    if (opts.recommended)
+        return skills.filter((skill) => skill.recommended);
+    if (!name) {
+        console.error("Specify a skill name, --recommended, or --all.");
+        printAvailableSkillNames();
+        process.exit(1);
+    }
+    const skill = skills.find((candidate) => candidate.name === name);
+    if (!skill) {
+        console.error(`Unknown skill: ${name}`);
+        printAvailableSkillNames();
+        process.exit(1);
+    }
+    return [skill];
+}
+function printAvailableSkillNames() {
+    const skills = getBuiltinSkills();
+    if (skills.length === 0)
+        return;
+    console.log("\nAvailable skills:");
+    for (const skill of skills) {
+        console.log(`  ${skill.name}`);
+    }
+}
+function installSkill(skill, agent, location) {
+    if (!skill.clients.includes(agent)) {
+        die(`${skill.name} does not support ${agentLabel(agent)}.`);
+    }
+    switch (location.kind) {
+        case "skill-dir":
+            return copySkillDirectory(skill, location.path);
+        case "cursor-rule-dir":
+            return writeCursorRule(skill, location.path);
+        case "windsurf-rule-file":
+            return upsertWindsurfRule(skill, location.path);
+    }
+}
+function copySkillDirectory(skill, targetDir) {
+    const src = getSkillPath(skill.name);
+    if (!src)
+        die(`Skill files missing: ${skill.name}`);
+    mkdirSync(targetDir, { recursive: true });
+    const dest = join(targetDir, skill.name);
+    cpSync(src, dest, { recursive: true });
+    return { action: "Installed", path: dest };
+}
+function writeCursorRule(skill, rulesDir) {
+    mkdirSync(rulesDir, { recursive: true });
+    const rulePath = join(rulesDir, `summer-${skill.name}.mdc`);
+    writeFileSync(rulePath, renderCursorRule(skill), "utf-8");
+    return { action: "Generated", path: rulePath };
+}
+function upsertWindsurfRule(skill, rulePath) {
+    mkdirSync(dirname(rulePath), { recursive: true });
+    const start = `<!-- summer-skill:start:${skill.name} -->`;
+    const end = `<!-- summer-skill:end:${skill.name} -->`;
+    const block = `${start}\n${renderWindsurfRule(skill)}\n${end}`;
+    const existing = existsSync(rulePath) ? readFileSync(rulePath, "utf-8") : "";
+    const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
+    const next = pattern.test(existing)
+        ? existing.replace(pattern, block)
+        : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}\n`;
+    writeFileSync(rulePath, next, "utf-8");
+    return { action: "Generated", path: rulePath };
+}
+function renderCursorRule(skill) {
+    const description = `Summer skill ${skill.name}: ${skill.description}`;
+    return `---\ndescription: ${JSON.stringify(description)}\nglobs: []\nalwaysApply: false\n---\n\n${renderRuleBody(skill)}\n`;
+}
+function renderWindsurfRule(skill) {
+    return renderRuleBody(skill);
+}
+function renderRuleBody(skill) {
+    return `# Summer skill: ${skill.name}
+
+${skill.description}
+
+Use Summer MCP tools for scene, editor, asset, play, and diagnostics operations. Use the host agent's normal file editing tools for scripts and other text files.
+
+## Skill
+
+${getSkillBody(skill.name)}
+`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function printInstallSummary(count, agent, scope, location) {
+    const label = agentLabel(agent);
+    console.log(`\n${count} skill${count === 1 ? "" : "s"} ready for ${label} (${scope} scope).`);
+    if (location.kind === "skill-dir") {
+        console.log(`${label} can read skills from ${location.path}/<skill>/SKILL.md`);
+    }
+    else if (location.kind === "cursor-rule-dir") {
+        console.log(`Cursor rules are in ${location.path}/summer-<skill>.mdc`);
+    }
+    else {
+        console.log(`Windsurf rules are in ${location.path}`);
+    }
+}
 export const skillsCommand = new Command("skills")
     .description("Install and manage best-practice guides for AI agents building games")
     .action(() => {
@@ -60,124 +267,62 @@ skillsCommand
         console.log("No skills found.");
         return;
     }
-    console.log("Available skills:\n");
+    console.log("Available public skills:\n");
     for (const s of skills) {
-        console.log(`  ${s.name.padEnd(20)} ${s.description}`);
+        const badge = s.recommended ? "recommended" : "optional";
+        console.log(`  ${s.name.padEnd(20)} ${s.category.padEnd(10)} ${badge.padEnd(11)} ${s.description}`);
     }
-    console.log("\nInstall: summer skills install <name>");
+    console.log("\nInstall recommended: summer skills install --recommended");
+    console.log("Install one:         summer skills install <name>");
+    console.log(`Agents:              ${AGENT_CLIENTS.join(", ")}`);
 });
-function resolveInstallDir(target) {
-    if (process.env.SUMMER_SKILLS_DIR) {
-        return process.env.SUMMER_SKILLS_DIR;
-    }
-    if (target === "claude") {
-        return join(homedir(), ".claude", "skills");
-    }
-    if (target === "cursor") {
-        return join(homedir(), ".cursor", "skills");
-    }
-    return join(homedir(), ".summer", "skills");
-}
-function getTargetFromOpts(opts) {
-    if (opts.asClaudeSkill)
-        return "claude";
-    if (opts.asCursorSkill)
-        return "cursor";
-    return "summer";
-}
 skillsCommand
     .command("install [name]")
-    .description("Install a skill to ~/.summer/skills/ (or use --as-claude-skill / --as-cursor-skill)")
+    .description("Install Summer skills for a target agent")
     .option("--all", "Install all available skills")
-    .option("--as-claude-skill", "Install to ~/.claude/skills/ for Claude Code auto-discovery")
-    .option("--as-cursor-skill", "Install to ~/.cursor/skills/ for Cursor auto-discovery")
+    .option("--recommended", "Install recommended public skills (excludes make-game)")
+    .option("--agent <agent>", `Target agent: ${AGENT_CLIENTS.join("|")}`)
+    .option("--scope <scope>", "Install scope: user or project")
+    .option("--as-claude-skill", "Legacy alias for --agent claude-code")
+    .option("--as-cursor-skill", "Legacy alias for --agent cursor")
     .action((name, opts) => {
-    const { all } = opts;
-    const target = getTargetFromOpts(opts);
-    const targetDir = resolveInstallDir(target);
-    if (all) {
-        const skills = getBuiltinSkills();
-        if (skills.length === 0) {
-            console.log("No skills found.");
-            return;
-        }
-        if (!existsSync(targetDir)) {
-            mkdirSync(targetDir, { recursive: true });
-        }
-        for (const s of skills) {
-            const src = getSkillPath(s.name);
-            if (src) {
-                const dest = join(targetDir, s.name);
-                cpSync(src, dest, { recursive: true });
-                console.log(`  Installed ${s.name}`);
-            }
-        }
-        console.log(`\nInstalled ${skills.length} skills to ${targetDir}`);
-        if (target === "claude") {
-            console.log("Claude Code will auto-discover these skills.");
-        }
-        else if (target === "cursor") {
-            console.log("Cursor will auto-discover these skills.");
-        }
-        else {
-            console.log("AI agents can read: <dir>/<name>/SKILL.md");
-        }
+    const agent = resolveAgent(opts);
+    const scope = resolveScope(agent, opts);
+    const location = resolveInstallLocation(agent, scope);
+    const skills = selectSkills(name, opts);
+    if (skills.length === 0) {
+        console.log("No skills found.");
         return;
     }
-    if (!name) {
-        console.error("Specify a skill name or use --all to install all skills.");
-        console.log("\nAvailable skills:");
-        for (const s of getBuiltinSkills()) {
-            console.log(`  ${s.name}`);
-        }
-        process.exit(1);
-    }
-    const src = getSkillPath(name);
-    if (!src) {
-        console.error(`Unknown skill: ${name}`);
-        const skills = getBuiltinSkills();
-        if (skills.length > 0) {
-            console.log("\nAvailable skills:");
-            for (const s of skills) {
-                console.log(`  ${s.name}`);
-            }
-        }
-        process.exit(1);
-    }
-    if (!existsSync(targetDir)) {
-        mkdirSync(targetDir, { recursive: true });
-    }
-    const dest = join(targetDir, name);
-    cpSync(src, dest, { recursive: true });
-    console.log(`Installed ${name} to ${dest}`);
-    if (target === "claude") {
-        console.log("Claude Code will auto-discover this skill.");
-    }
-    else if (target === "cursor") {
-        console.log("Cursor will auto-discover this skill.");
-    }
-    else {
-        console.log(`\nAI agents can read: ${dest}/SKILL.md`);
+    for (const skill of skills) {
+        const result = installSkill(skill, agent, location);
+        console.log(`  ${result.action} ${skill.name} -> ${result.path}`);
     }
+    printInstallSummary(skills.length, agent, scope, location);
 });
 skillsCommand
     .command("info <name>")
     .description("Show skill description and preview")
     .action((name) => {
-    const src = getSkillPath(name);
-    if (!src) {
+    const meta = getSkillMeta(name);
+    if (!meta) {
         console.error(`Unknown skill: ${name}`);
         process.exit(1);
     }
+    const src = getSkillPath(name);
+    if (!src)
+        die(`Skill files missing: ${name}`);
     const skillPath = join(src, "SKILL.md");
     const content = readFileSync(skillPath, "utf-8");
-    const meta = parseSkillFrontmatter(skillPath);
-    if (meta) {
-        console.log(`\n${meta.name}`);
-        console.log("─".repeat(40));
-        console.log(meta.description);
-        console.log("\n" + "─".repeat(40));
-    }
+    console.log(`\n${meta.name}`);
+    console.log("-".repeat(40));
+    console.log(meta.description);
+    console.log(`Category: ${meta.category}`);
+    console.log(`Recommended: ${meta.recommended ? "yes" : "no"}`);
+    console.log(`Agents: ${meta.clients.join(", ")}`);
+    console.log(`MCP tools: ${meta.requiresMcpTools.length > 0 ? meta.requiresMcpTools.join(", ") : "none"}`);
+    console.log(`Test scenario: ${meta.testScenario}`);
+    console.log("\n" + "-".repeat(40));
     const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n/, "");
     const preview = body.split("\n").slice(0, 30).join("\n");
     console.log(preview);

package/dist/lib/agent-config.d.ts

@@ -0,0 +1,39 @@
+export declare const SUMMER_MCP_SERVER_NAME = "summer-engine";
+export declare const supportedAgents: readonly ["codex", "claude-code", "cursor", "windsurf"];
+export type SupportedAgent = (typeof supportedAgents)[number];
+export type ConfigScope = "user" | "project";
+export interface StdioMcpServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface AgentConfigOptions {
+    agent: SupportedAgent;
+    scope: ConfigScope;
+    dryRun?: boolean;
+    print?: boolean;
+    localDev?: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface AgentConfigResult {
+    agent: SupportedAgent;
+    scope: ConfigScope;
+    path: string;
+    serverName: string;
+    server: StdioMcpServerConfig;
+    format: "json" | "toml";
+    snippet: string;
+    changed: boolean;
+    wrote: boolean;
+    dryRun: boolean;
+    print: boolean;
+    localDev: boolean;
+    warnings: string[];
+    nextSteps: string[];
+}
+export declare function parseAgent(value: string | undefined): SupportedAgent | null;
+export declare function parseScope(value: string | undefined): ConfigScope | null;
+export declare function configureAgentMcp(options: AgentConfigOptions): Promise<AgentConfigResult>;
+export declare function createSummerMcpServerConfig(localDev: boolean): StdioMcpServerConfig;
+export declare function renderConfigSnippet(agent: SupportedAgent, server: StdioMcpServerConfig): string;