summer-engine 2.6.6 → 2.8.0

package/dist/lib/mcp-log.js

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getSummerDir } from "./auth.js";
+const MAX_LOG_BYTES = 512 * 1024;
+const RETAIN_LOG_BYTES = 256 * 1024;
+export function getMcpLogPath() {
+    return join(getSummerDir(), "mcp.log");
+}
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map((item) => redact(item));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, nested] of Object.entries(value)) {
+        if (/token|secret|password|authorization|cookie|api[-_]?key/i.test(key)) {
+            out[key] = "[REDACTED]";
+        }
+        else {
+            out[key] = redact(nested);
+        }
+    }
+    return out;
+}
+function rotateIfNeeded(path) {
+    try {
+        if (statSync(path).size < MAX_LOG_BYTES)
+            return;
+        const text = readFileSync(path, "utf-8");
+        const retained = text.slice(-RETAIN_LOG_BYTES);
+        writeFileSync(path, `{"event":"mcp:log_rotated"}\n${retained}`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // No existing log, or not readable. The next append will recreate it.
+    }
+}
+export function appendMcpLogEvent(event, details = {}) {
+    try {
+        const dir = getSummerDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = getMcpLogPath();
+        rotateIfNeeded(path);
+        const safeDetails = redact(details);
+        const payload = {
+            ts: new Date().toISOString(),
+            event,
+            ...safeDetails,
+        };
+        appendFileSync(path, `${JSON.stringify(payload)}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Logging must never affect MCP behavior.
+    }
+}
+export async function readRecentMcpLogLines(maxLines = 120) {
+    try {
+        const text = await readFile(getMcpLogPath(), "utf-8");
+        if (!text.trim())
+            return [];
+        return text.trimEnd().split(/\r?\n/).slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/public-surface-paths.d.ts

@@ -0,0 +1,13 @@
+export interface PathFlavor {
+    isAbsolute(path: string): boolean;
+    relative(from: string, to: string): string;
+    resolve(...paths: string[]): string;
+    sep: string;
+}
+export interface PublicSurfaceRoots {
+    packageRoot: string;
+    engineRoot: string;
+}
+export declare function snapshotPublicPath(pathFlavor: PathFlavor, roots: PublicSurfaceRoots, file: string): string;
+export declare function compareByCodePoint(left: string, right: string): number;
+export declare function stablePublicPathInventory(pathFlavor: PathFlavor, roots: PublicSurfaceRoots, files: readonly string[]): string;

package/dist/lib/public-surface-paths.js

@@ -0,0 +1,42 @@
+function relativeWithin(pathFlavor, root, file) {
+    const resolvedRoot = pathFlavor.resolve(root);
+    const resolvedFile = pathFlavor.resolve(file);
+    const candidate = pathFlavor.relative(resolvedRoot, resolvedFile);
+    if (pathFlavor.isAbsolute(candidate) ||
+        candidate === ".." ||
+        candidate.startsWith(`..${pathFlavor.sep}`)) {
+        return null;
+    }
+    return candidate;
+}
+function toPosix(pathFlavor, path) {
+    return path.split(pathFlavor.sep).join("/");
+}
+export function snapshotPublicPath(pathFlavor, roots, file) {
+    const packageRelative = relativeWithin(pathFlavor, roots.packageRoot, file);
+    if (packageRelative !== null) {
+        return `cli/${toPosix(pathFlavor, packageRelative)}`;
+    }
+    const engineRelative = relativeWithin(pathFlavor, roots.engineRoot, file);
+    if (engineRelative !== null) {
+        return `engine/${toPosix(pathFlavor, engineRelative)}`;
+    }
+    throw new Error(`Public surface escapes both inventory roots: ${file}`);
+}
+export function compareByCodePoint(left, right) {
+    const leftPoints = [...left].map((character) => character.codePointAt(0));
+    const rightPoints = [...right].map((character) => character.codePointAt(0));
+    const sharedLength = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        if (leftPoints[index] !== rightPoints[index]) {
+            return leftPoints[index] - rightPoints[index];
+        }
+    }
+    return leftPoints.length - rightPoints.length;
+}
+export function stablePublicPathInventory(pathFlavor, roots, files) {
+    return files
+        .map((file) => snapshotPublicPath(pathFlavor, roots, file))
+        .sort(compareByCodePoint)
+        .join("\n");
+}

package/dist/lib/skills-registry.d.ts

@@ -23,7 +23,7 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly public: true;
     readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
     readonly recommended: true;
-    readonly requiresMcpTools: readonly ["summer_get_console", "summer_get_debugger_errors", "summer_get_script_errors", "summer_get_diagnostics", "summer_clear_console", "summer_play", "summer_stop", "summer_inspect_node"];
+    readonly requiresMcpTools: readonly ["summer_create_debug_report", "summer_get_console", "summer_get_debugger_errors", "summer_get_script_errors", "summer_get_diagnostics", "summer_clear_console", "summer_play", "summer_stop", "summer_inspect_node"];
     readonly testScenario: "Triage a runtime crash end-to-end: read errors, locate code, propose fix, apply on approval, verify.";
 }, {
     readonly name: "play";
@@ -49,6 +49,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_create_scene", "summer_open_scene", "summer_get_scene_tree", "summer_add_node", "summer_instantiate_scene", "summer_save_scene"];
     readonly testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.";
+}, {
+    readonly name: "summer-cloud";
+    readonly category: "scene-and-project";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_cloud_init", "summer_cloud_status", "summer_cloud_push", "summer_cloud_pull", "summer_cloud_restore", "summer_cloud_checkpoints", "summer_cloud_conflicts"];
+    readonly testScenario: "Enable Cloud for a project, push it, then pull it onto a second machine, taking the bootstrap choice and surfacing the delete count before any guarded deletion.";
 }, {
     readonly name: "fps-controller";
     readonly category: "character-controllers";
@@ -201,6 +209,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_get_scene_tree", "summer_inspect_node", "summer_project_setting", "summer_get_console", "summer_get_diagnostics"];
     readonly testScenario: "Run the Steam pre-flight checklist (Windows + Mac + Linux), validate icons/banners/screenshots/build config, and produce a release build only when green.";
+}, {
+    readonly name: "remote-deploy";
+    readonly category: "deployment";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_project_setting", "summer_get_diagnostics", "summer_get_console", "summer_get_script_errors"];
+    readonly testScenario: "User says \"deploy the game to my Android phone\" — skill walks the prerequisites (runnable export preset, installed export templates, USB-debugging device), checks diagnostics are clean, and points them at the topnav Remote Deploy button to deploy a debug build with on-device remote debugging.";
 }, {
     readonly name: "concept-art";
     readonly category: "2d-assets";
@@ -249,6 +265,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: false;
     readonly requiresMcpTools: readonly ["summer_generate_image", "summer_import_from_url", "summer_set_resource_property", "summer_add_node", "summer_set_prop"];
     readonly testScenario: "User requests a '4-frame walk cycle for the goblin' — skill generates per-frame at locked anchor, builds SpriteFrames resource, wires AnimatedSprite2D.";
+}, {
+    readonly name: "create-asset-sheet";
+    readonly category: "2d-assets";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: false;
+    readonly requiresMcpTools: readonly ["summer_get_studio_workflow", "summer_generate_image", "summer_slice_asset_sheet", "summer_import_asset_by_id"];
+    readonly testScenario: "User requests a Japanese village asset pack — skill loads the Guided asset-pack recipe, generates one coherent sheet, slices it through the shared cloud pipeline, and imports selected results.";
 }, {
     readonly name: "skybox-panorama";
     readonly category: "2d-assets";
@@ -521,6 +545,14 @@ export declare const SKILL_REGISTRY: readonly [{
     readonly recommended: true;
     readonly requiresMcpTools: readonly ["summer_play", "summer_stop", "summer_get_console", "summer_get_debugger_errors", "summer_get_diagnostics"];
     readonly testScenario: "Just finished a gameplay feature — skill drives a golden-path + edge-case playthrough with diagnostics capture before the feature can be marked done.";
+}, {
+    readonly name: "headless-scripting";
+    readonly category: "workflow";
+    readonly public: true;
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_get_project_context", "summer_write_file"];
+    readonly testScenario: "User needs a navmesh baked, collision generated, an Animation authored, or raw assets re-imported — skill runs a GDScript file against the real engine binary instead of reporting the capability as missing, and blocks the 'run it headless and screenshot it' plan that silently returns null.";
 }, {
     readonly name: "debugging-game-feel";
     readonly category: "workflow";

package/dist/lib/skills-registry.js

@@ -53,6 +53,7 @@ export const SKILL_REGISTRY = [
         clients: ALL_CLIENTS,
         recommended: true,
         requiresMcpTools: [
+            "summer_create_debug_report",
             "summer_get_console",
             "summer_get_debugger_errors",
             "summer_get_script_errors",
@@ -108,6 +109,23 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.",
     },
+    {
+        name: "summer-cloud",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_cloud_init",
+            "summer_cloud_status",
+            "summer_cloud_push",
+            "summer_cloud_pull",
+            "summer_cloud_restore",
+            "summer_cloud_checkpoints",
+            "summer_cloud_conflicts",
+        ],
+        testScenario: "Enable Cloud for a project, push it, then pull it onto a second machine, taking the bootstrap choice and surfacing the delete count before any guarded deletion.",
+    },
     {
         name: "fps-controller",
         category: "character-controllers",
@@ -413,6 +431,20 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Run the Steam pre-flight checklist (Windows + Mac + Linux), validate icons/banners/screenshots/build config, and produce a release build only when green.",
     },
+    {
+        name: "remote-deploy",
+        category: "deployment",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_project_setting",
+            "summer_get_diagnostics",
+            "summer_get_console",
+            "summer_get_script_errors",
+        ],
+        testScenario: "User says \"deploy the game to my Android phone\" — skill walks the prerequisites (runnable export preset, installed export templates, USB-debugging device), checks diagnostics are clean, and points them at the topnav Remote Deploy button to deploy a debug build with on-device remote debugging.",
+    },
     {
         name: "concept-art",
         category: "2d-assets",
@@ -494,6 +526,20 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "User requests a '4-frame walk cycle for the goblin' — skill generates per-frame at locked anchor, builds SpriteFrames resource, wires AnimatedSprite2D.",
     },
+    {
+        name: "create-asset-sheet",
+        category: "2d-assets",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: false,
+        requiresMcpTools: [
+            "summer_get_studio_workflow",
+            "summer_generate_image",
+            "summer_slice_asset_sheet",
+            "summer_import_asset_by_id",
+        ],
+        testScenario: "User requests a Japanese village asset pack — skill loads the Guided asset-pack recipe, generates one coherent sheet, slices it through the shared cloud pipeline, and imports selected results.",
+    },
     {
         name: "skybox-panorama",
         category: "2d-assets",
@@ -977,6 +1023,15 @@ export const SKILL_REGISTRY = [
         ],
         testScenario: "Just finished a gameplay feature — skill drives a golden-path + edge-case playthrough with diagnostics capture before the feature can be marked done.",
     },
+    {
+        name: "headless-scripting",
+        category: "workflow",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: ["summer_get_project_context", "summer_write_file"],
+        testScenario: "User needs a navmesh baked, collision generated, an Animation authored, or raw assets re-imported — skill runs a GDScript file against the real engine binary instead of reporting the capability as missing, and blocks the 'run it headless and screenshot it' plan that silently returns null.",
+    },
     {
         name: "debugging-game-feel",
         category: "workflow",

package/dist/lib/store.d.ts

@@ -0,0 +1,14 @@
+export declare class SummerStoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function getSummerDir(): string;
+/** Test-only seam. Passing null restores the real ~/.summer path. */
+export declare function setSummerDirForTests(path: string | null): void;
+export declare function ensureSummerStore(): Promise<string>;
+export declare function readStoreText(name: string): Promise<string | null>;
+export declare function readStoreJson<T>(name: string): Promise<T | null>;
+export declare function writeStoreText(name: string, value: string): Promise<void>;
+export declare function writeStoreJson(name: string, value: unknown): Promise<void>;
+export declare function appendStoreJsonLine(name: string, value: unknown): Promise<void>;
+export declare function removeStoreFile(name: string): Promise<boolean>;

package/dist/lib/store.js

@@ -0,0 +1,145 @@
+import { appendFile, chmod, lstat, mkdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+let summerDirOverride = null;
+export class SummerStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SummerStoreError";
+    }
+}
+export function getSummerDir() {
+    return summerDirOverride ?? join(homedir(), ".summer");
+}
+/** Test-only seam. Passing null restores the real ~/.summer path. */
+export function setSummerDirForTests(path) {
+    summerDirOverride = path;
+}
+function storePath(name) {
+    if (!name || basename(name) !== name || name === "." || name === "..") {
+        throw new SummerStoreError("invalid_store_path", `Invalid Summer store filename "${name}". Recovery: use a single filename inside ~/.summer/.`);
+    }
+    return join(getSummerDir(), name);
+}
+async function hardenMode(path, mode) {
+    try {
+        await chmod(path, mode);
+    }
+    catch (error) {
+        const code = error.code;
+        // Windows does not implement POSIX permission bits consistently.
+        if (process.platform !== "win32" && code !== "EPERM")
+            throw error;
+    }
+}
+export async function ensureSummerStore() {
+    const dir = getSummerDir();
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const info = await lstat(dir);
+        if (info.isSymbolicLink() || !info.isDirectory()) {
+            throw new SummerStoreError("unsafe_store_directory", `${dir} must be a real directory, not a file or symlink. Recovery: move it aside, create a directory at ${dir}, and run the command again.`);
+        }
+        await hardenMode(dir, 0o700);
+        return dir;
+    }
+    catch (error) {
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_unavailable", `Cannot secure ${dir}. Recovery: make sure the directory is owned and writable by your user, then run the command again.`);
+    }
+}
+async function assertSafeExistingFile(path) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink() || !info.isFile()) {
+            throw new SummerStoreError("unsafe_store_file", `${path} must be a regular file, not a directory or symlink. Recovery: move it aside and run the command again.`);
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function readStoreText(name) {
+    const path = storePath(name);
+    if (!(await assertSafeExistingFile(path)))
+        return null;
+    try {
+        await hardenMode(path, 0o600);
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_read_failed", `Cannot read ${path}. Recovery: make sure the file is owned and readable by your user, then run the command again.`);
+    }
+}
+export async function readStoreJson(name) {
+    const raw = await readStoreText(name);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new SummerStoreError("invalid_store_json", `${storePath(name)} is not valid JSON. Recovery: move that file aside and run the command again.`);
+    }
+}
+export async function writeStoreText(name, value) {
+    const dir = await ensureSummerStore();
+    const destination = storePath(name);
+    await assertSafeExistingFile(destination);
+    const temporary = join(dir, `.${name}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, value, {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await hardenMode(temporary, 0o600);
+        await rename(temporary, destination);
+        await hardenMode(destination, 0o600);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (error instanceof SummerStoreError)
+            throw error;
+        throw new SummerStoreError("store_write_failed", `Cannot write ${destination}. Recovery: make sure ${dir} is owned and writable by your user, then run the command again.`);
+    }
+}
+export async function writeStoreJson(name, value) {
+    await writeStoreText(name, `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function appendStoreJsonLine(name, value) {
+    await ensureSummerStore();
+    const path = storePath(name);
+    await assertSafeExistingFile(path);
+    try {
+        await appendFile(path, `${JSON.stringify(value)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await hardenMode(path, 0o600);
+    }
+    catch {
+        throw new SummerStoreError("store_append_failed", `Cannot append to ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    }
+}
+export async function removeStoreFile(name) {
+    const path = storePath(name);
+    if (!(await assertSafeExistingFile(path)))
+        return false;
+    try {
+        await rm(path);
+        return true;
+    }
+    catch {
+        throw new SummerStoreError("store_remove_failed", `Cannot remove ${path}. Recovery: make sure the file is owned and writable by your user, then run the command again.`);
+    }
+}

package/dist/lib/summer-compatibility.d.ts

@@ -0,0 +1,6 @@
+export declare const SUMMER_ENGINE_COMPATIBILITY: Readonly<{
+    currentTechnicalBaseVersion: "4.6.1";
+    projectFeatureTag: string;
+    plannedNextTechnicalBaseVersion: "4.7.1";
+    upstreamPolicy: "continuous-upstream";
+}>;

package/dist/lib/summer-compatibility.js

@@ -0,0 +1,22 @@
+/**
+ * Summer CLI compatibility values.
+ *
+ * Keep the current technical base in one place. The project feature tag is
+ * derived from it so `summer create` cannot drift to a different line. This
+ * source is cross-checked against the repository compatibility contract by
+ * `summer-compatibility.test.ts`.
+ */
+const CURRENT_TECHNICAL_BASE_VERSION = "4.6.1";
+function featureTagFor(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+    if (!match) {
+        throw new Error(`Invalid Summer Engine technical base version: ${version}`);
+    }
+    return `${match[1]}.${match[2]}`;
+}
+export const SUMMER_ENGINE_COMPATIBILITY = Object.freeze({
+    currentTechnicalBaseVersion: CURRENT_TECHNICAL_BASE_VERSION,
+    projectFeatureTag: featureTagFor(CURRENT_TECHNICAL_BASE_VERSION),
+    plannedNextTechnicalBaseVersion: "4.7.1",
+    upstreamPolicy: "continuous-upstream",
+});

package/dist/mcp/server.d.ts

@@ -1,6 +1,13 @@
 import { EngineApiClient } from "../lib/api-client.js";
-import { type BootDriftNotice } from "../lib/version-check.js";
-export declare function getCachedBootDriftNotice(): BootDriftNotice | null;
+import type { EngineSelection } from "../lib/engine.js";
+import { getCachedBootDriftNotice as getCachedNotice } from "../lib/mcp-boot-notice.js";
+export declare const getCachedBootDriftNotice: typeof getCachedNotice;
+export declare function configureMcpEngineSelection(selection?: EngineSelection): void;
 export declare function getClient(): Promise<EngineApiClient>;
 export declare function resetClient(): void;
-export declare function startMcpServer(): Promise<void>;
+export interface StartMcpServerOptions {
+    projectPath?: string;
+    instanceId?: string;
+    cwd?: string;
+}
+export declare function startMcpServer(options?: StartMcpServerOptions): Promise<void>;