summer-engine 3.2.0 → 3.3.0

package/dist/core/capabilities/runtime-control.d.ts

@@ -97,14 +97,14 @@ export declare const runtimeSetArgsSchema: z.ZodObject<{
     field: z.ZodOptional<z.ZodString>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     value: string | number | boolean;
+    path: string;
     property: string;
     instance?: string | undefined;
     field?: string | undefined;
 }, {
-    path: string;
     value: string | number | boolean;
+    path: string;
     property: string;
     instance?: string | undefined;
     field?: string | undefined;
@@ -117,13 +117,13 @@ export declare const runtimeCallArgsSchema: z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    path: string;
     method: string;
+    path: string;
     args?: unknown[] | undefined;
     instance?: string | undefined;
 }, {
-    path: string;
     method: string;
+    path: string;
     args?: unknown[] | undefined;
     instance?: string | undefined;
 }>;
@@ -183,13 +183,13 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     path: string;
     target: "tree" | "player" | "bones";
+    state?: string | undefined;
+    value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    value?: string | number | boolean | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
-    state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;
@@ -202,13 +202,13 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, {
     path: string;
     target: "tree" | "player" | "bones";
+    state?: string | undefined;
+    value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    value?: string | number | boolean | undefined;
-    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
     blend?: number | undefined;
-    state?: string | undefined;
     position?: number | undefined;
     speed?: number | undefined;
     bones?: string[] | undefined;

package/dist/core/capabilities/summer-bundle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The summer.games export (summer-platform ADR 0033): one .zip with
+ * summer-bundle.json, client.pck, and for a game with a host server.pck plus
+ * config/. This reads what the build upload declares; the Platform verifies
+ * the uploaded bytes again. Same rules as Studio's browser check
+ * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ */
+export declare const BUNDLE_SCHEMA = "summer.bundle.v1";
+export declare const BUNDLE_MANIFEST = "summer-bundle.json";
+/** A failure with a stable code, a plain message and the next step. */
+export declare class BuildToolError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly status?: number | undefined;
+    readonly detail?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, recovery: string, status?: number | undefined, detail?: Record<string, unknown> | undefined);
+}
+export interface BundleFile {
+    path: string;
+    sha256: string;
+    size: number;
+}
+export interface SummerBundle {
+    schema: typeof BUNDLE_SCHEMA;
+    summerVersion: string | null;
+    engineSha: string | null;
+    /** res:// scene the client pack opens. */
+    mainScene: string;
+    /** Client platforms the export was made for (ios, macos, windows, ...). */
+    targetPlatforms: string[];
+    /** True when the game has a host (server.pck + config/summer.build.json). */
+    hosted: boolean;
+    compositionPath: string | null;
+    /** client.pck as summer-bundle.json lists it ("sha256:<hex>"). */
+    clientPack: {
+        sha256: string;
+        size: number;
+    };
+    /** Hosted only: config/summer.build.json, sent as the Build declaration. */
+    hostedBuild?: Record<string, unknown>;
+    files: BundleFile[];
+}
+/** Read and check summer-bundle.json in an exported .zip. */
+export declare function readSummerBundle(path: string): Promise<SummerBundle>;
+/** "sha256:<hex>" and size of a whole file, streamed. */
+export declare function hashFile(path: string): Promise<{
+    sha256: string;
+    sizeBytes: number;
+}>;

package/dist/core/capabilities/summer-bundle.js

@@ -0,0 +1,156 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readZipEntries, readZipEntry, ZipReadError } from "../util/zip.js";
+/**
+ * The summer.games export (summer-platform ADR 0033): one .zip with
+ * summer-bundle.json, client.pck, and for a game with a host server.pck plus
+ * config/. This reads what the build upload declares; the Platform verifies
+ * the uploaded bytes again. Same rules as Studio's browser check
+ * (publicsummerengine src/lib/creator-store/pck-check.ts, checkBundle).
+ */
+export const BUNDLE_SCHEMA = "summer.bundle.v1";
+export const BUNDLE_MANIFEST = "summer-bundle.json";
+const BUNDLE_CLIENT = "client.pck";
+const BUNDLE_SERVER = "server.pck";
+const BUNDLE_BUILD = "config/summer.build.json";
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const AS_EXPORTED = "Recovery: export the game again with the summer.games preset and use the .zip exactly as Summer Engine wrote it.";
+/** A failure with a stable code, a plain message and the next step. */
+export class BuildToolError extends Error {
+    code;
+    recovery;
+    status;
+    detail;
+    constructor(code, message, recovery, status, detail) {
+        super(`${message} ${recovery}`);
+        this.code = code;
+        this.recovery = recovery;
+        this.status = status;
+        this.detail = detail;
+        this.name = "BuildToolError";
+    }
+}
+function bundleError(message) {
+    return new BuildToolError("bundle_invalid", message, AS_EXPORTED);
+}
+/** Read and check summer-bundle.json in an exported .zip. */
+export async function readSummerBundle(path) {
+    let entries;
+    try {
+        entries = await readZipEntries(path);
+    }
+    catch (error) {
+        throw bundleError(`${path} is not a readable summer.games export (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    const byName = new Map(entries.map((entry) => [entry.name, entry]));
+    const manifestEntry = byName.get(BUNDLE_MANIFEST);
+    const clientEntry = byName.get(BUNDLE_CLIENT);
+    if (!manifestEntry || !clientEntry) {
+        throw bundleError(`${path} is not a summer.games export: it has no ${BUNDLE_MANIFEST} and ${BUNDLE_CLIENT}.`);
+    }
+    if (byName.size !== entries.length ||
+        entries.some((entry) => entry.encrypted ||
+            entry.name.endsWith("/") ||
+            entry.name.split("/").some((part) => !part || part === "." || part === "..") ||
+            /[\\\0\r\n]/.test(entry.name))) {
+        throw bundleError("The export contains a repeated or unsafe file path.");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse((await readZipEntry(path, manifestEntry)).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof ZipReadError)
+            throw bundleError(`${BUNDLE_MANIFEST} could not be read: ${error.message}`);
+        throw bundleError(`${BUNDLE_MANIFEST} is not valid JSON.`);
+    }
+    const client = manifest?.client;
+    const mainScene = typeof client?.mainScene === "string" ? client.mainScene : null;
+    if (manifest?.schema !== BUNDLE_SCHEMA ||
+        client?.path !== BUNDLE_CLIENT ||
+        !mainScene?.startsWith("res://") ||
+        !Array.isArray(client?.targetPlatforms) ||
+        !client.targetPlatforms.every((value) => typeof value === "string") ||
+        !Array.isArray(manifest.files)) {
+        throw new BuildToolError("bundle_invalid", `${BUNDLE_MANIFEST} is not a ${BUNDLE_SCHEMA} manifest.`, "Recovery: update Summer Engine and export again.");
+    }
+    const hosted = Boolean(manifest.server);
+    const compositionPath = typeof manifest.compositionPath === "string" ? manifest.compositionPath : null;
+    if ((!hosted && manifest.compositionPath != null) ||
+        hosted !== byName.has(BUNDLE_SERVER) ||
+        (hosted &&
+            (manifest.server?.path !== BUNDLE_SERVER ||
+                typeof manifest.server.mainScene !== "string" ||
+                !/^res:\/\/.+\.tscn$/.test(manifest.server.mainScene) ||
+                !compositionPath ||
+                !/^res:\/\/.+\.tres$/.test(compositionPath)))) {
+        throw bundleError("The export must name its server pack, main scene and network composition together.");
+    }
+    const allowed = (name) => name === BUNDLE_MANIFEST ||
+        name === BUNDLE_CLIENT ||
+        name === BUNDLE_BUILD ||
+        (hosted && (name === BUNDLE_SERVER || name.startsWith("config/")));
+    const extra = entries.find((entry) => !allowed(entry.name));
+    if (extra)
+        throw bundleError(`The export contains ${extra.name}, which a summer.games export never has.`);
+    const files = [];
+    for (const item of manifest.files) {
+        const entry = typeof item?.path === "string" ? byName.get(item.path) : undefined;
+        if (!entry ||
+            item.path === BUNDLE_MANIFEST ||
+            typeof item.sha256 !== "string" ||
+            !SHA256.test(item.sha256) ||
+            item.size !== entry.uncompressedSize) {
+            throw bundleError(`The files do not match ${BUNDLE_MANIFEST}.`);
+        }
+        files.push({ path: entry.name, sha256: item.sha256, size: entry.uncompressedSize });
+    }
+    if (new Set(files.map((file) => file.path)).size !== files.length || files.length !== entries.length - 1) {
+        throw bundleError(`The files do not match ${BUNDLE_MANIFEST}.`);
+    }
+    const listedClient = files.find((file) => file.path === BUNDLE_CLIENT);
+    if (clientEntry.method !== 0) {
+        throw bundleError(`${BUNDLE_CLIENT} is compressed in this zip; Summer reads it in place, so it must be stored.`);
+    }
+    let hostedBuild;
+    if (hosted) {
+        const config = byName.get(BUNDLE_BUILD);
+        let build;
+        try {
+            build = config ? JSON.parse((await readZipEntry(path, config, 64 * 1024)).toString("utf8")) : undefined;
+        }
+        catch {
+            build = undefined;
+        }
+        if (!build || typeof build !== "object" || Array.isArray(build) || build.executionMode !== "hosted") {
+            throw bundleError(`${BUNDLE_BUILD} is missing or does not declare a hosted game.`);
+        }
+        hostedBuild = build;
+    }
+    const targetPlatforms = client.targetPlatforms;
+    if (new Set(targetPlatforms).size !== targetPlatforms.length || targetPlatforms.length === 0) {
+        throw bundleError("The export must name at least one platform, each once.");
+    }
+    return {
+        schema: BUNDLE_SCHEMA,
+        summerVersion: typeof manifest.export?.summerVersion === "string" ? manifest.export.summerVersion : null,
+        engineSha: typeof manifest.export?.engineSha === "string" ? manifest.export.engineSha : null,
+        mainScene: mainScene,
+        targetPlatforms,
+        hosted,
+        compositionPath,
+        clientPack: { sha256: listedClient.sha256, size: listedClient.size },
+        ...(hostedBuild ? { hostedBuild } : {}),
+        files,
+    };
+}
+/** "sha256:<hex>" and size of a whole file, streamed. */
+export async function hashFile(path) {
+    const hash = createHash("sha256");
+    let sizeBytes = 0;
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+        sizeBytes += chunk.length;
+    }
+    return { sha256: `sha256:${hash.digest("hex")}`, sizeBytes };
+}

package/dist/core/capabilities/tool-dispatch.js

@@ -47,6 +47,9 @@ import open from "open";
 import { openArgsSchema, runOpen } from "./navigation/open.js";
 import { shapeEngineLogResponse } from "../log-filters.js";
 import { listCreatorReleases, publishCreator, } from "./creator.js";
+import { exportGame } from "./export-game.js";
+import { exportTemplates } from "./export-templates.js";
+import { publishBuild } from "./publish-build.js";
 import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, resolveGatewayUrl, setConfigValue, unsetConfigValue, } from "../config.js";
 import { createDebugReportArtifact } from "./debug-report.js";
 import { buildGameTaskPlan, gameTaskPlanInputSchema } from "./game-task-plan.js";
@@ -608,7 +611,36 @@ export const TOOL_DISPATCH = [
             throw err;
         }
     }),
-    entry("summer_creator_publish", "Publish an exported .pck through the creator API (confirm-gated)", false, (args) => publishCreator({
+    entry("summer_export_game", "Export the game as a summer.games .zip with the installed engine (headless)", false, (args) => exportGame({
+        project: optStr(args, "project"),
+        out: optStr(args, "out"),
+        targets: Array.isArray(args.targets) ? args.targets.map(String) : undefined,
+        format: optStr(args, "format"),
+        debug: args.debug === true,
+        ...(typeof args.timeoutSeconds === "number" ? { timeoutMs: args.timeoutSeconds * 1000 } : {}),
+    })),
+    entry("summer_export_templates", "List or install Summer export templates from the CDN (web, macos, windows)", false, (args) => {
+        const action = optStr(args, "action");
+        if (action !== "list" && action !== "install")
+            throw new ToolDispatchError('action must be "list" or "install".');
+        return exportTemplates({
+            action,
+            platforms: Array.isArray(args.platforms) ? args.platforms.map(String) : undefined,
+            includeDebug: args.includeDebug === true,
+            summerVersion: optStr(args, "summerVersion"),
+        });
+    }),
+    entry("summer_publish_build", "Upload a summer.games export to your store game (confirm-gated)", false, (args) => publishBuild({
+        gameId: optStr(args, "gameId"),
+        file: optStr(args, "file"),
+        clientVersion: optStr(args, "clientVersion"),
+        publish: args.publish === true,
+        platform: optStr(args, "platform"),
+        confirm: args.confirm === true,
+        ...(typeof args.waitSeconds === "number" ? { waitSeconds: args.waitSeconds } : {}),
+        face: "cli",
+    })),
+    entry("summer_creator_publish", "Deprecated: publish a .pck to the legacy creator API; use publish-build", false, (args) => publishCreator({
         project: optStr(args, "project"),
         artifact: optStr(args, "artifact"),
         version: optStr(args, "version"),

package/dist/core/capabilities/ui-control.d.ts

@@ -88,17 +88,17 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     button: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    value?: string | number | undefined;
     action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;
 }, {
+    value?: string | number | undefined;
     title?: string | undefined;
     path?: string | undefined;
-    value?: string | number | undefined;
     action?: "focus" | "press" | "toggle" | "select_tab" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;

package/dist/core/library-read.d.ts

@@ -19,10 +19,10 @@ export declare const readLibraryInputSchema: z.ZodObject<{
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    part?: "all" | "resource" | "skill" | undefined;
+    part?: "resource" | "all" | "skill" | undefined;
 }, {
     id: string;
-    part?: "all" | "resource" | "skill" | undefined;
+    part?: "resource" | "all" | "skill" | undefined;
 }>;
 export type ReadLibraryArgs = z.infer<typeof readLibraryInputSchema>;
 export interface LibraryReadDeps extends LibrarySearchDeps {

package/dist/core/oauth.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The Summer store sign-in for local tools (summer_publish_build): OAuth 2.1
+ * authorization code + PKCE against the same Supabase authorization server
+ * and resource the hosted MCP uses (mcp.summerengine.com/mcp), with a
+ * loopback redirect (RFC 8252). The access token's audience is the MCP
+ * resource, the one token the creator store accepts for agents (creator
+ * publishing spec, part C.3).
+ *
+ * The Summer CLI is one public client (no secret; PKCE proves each login).
+ * The authorization server matches redirect URIs exactly, so the CLI listens
+ * on one of a few fixed loopback ports and registers its client once per
+ * machine with exactly those redirect URIs. Later logins and refreshes reuse
+ * that client id (~/.summer/oauth-client); only --force registers anew.
+ *
+ * The token is stored in ~/.summer/oauth-token (0600) with its refresh token,
+ * separate from the CLI JWT in auth-token: the engine reads that file and
+ * expects the summer-cli contract.
+ */
+export declare const OAUTH_TOKEN_FILE = "oauth-token";
+export declare const OAUTH_CLIENT_FILE = "oauth-client";
+/** Loopback ports the Summer CLI client is registered for, tried in order. */
+export declare const STORE_LOGIN_PORTS: readonly [47615, 47616, 47617];
+export declare const DEFAULT_MCP_RESOURCE_URL = "https://mcp.summerengine.com/mcp";
+export declare const MCP_RESOURCE_ENV = "SUMMER_MCP_RESOURCE_URL";
+export declare class OAuthError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    constructor(code: string, message: string, recovery: string);
+}
+export interface StoredOAuthToken {
+    schemaVersion: 1;
+    resource: string;
+    issuer: string;
+    tokenEndpoint: string;
+    clientId: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: string;
+    scope?: string;
+}
+/** The machine's registered Summer CLI client for one authorization server. */
+export interface StoredOAuthClient {
+    schemaVersion: 1;
+    issuer: string;
+    clientId: string;
+    redirectUris: string[];
+}
+interface AuthorizationServer {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint: string;
+}
+export interface OAuthDependencies {
+    fetch: typeof fetch;
+    now: () => number;
+}
+export declare function resolveMcpResourceUrl(env?: NodeJS.ProcessEnv): string;
+/** RFC 9728 resource metadata, then RFC 8414 server metadata (path-aware first). */
+export declare function discoverAuthorizationServer(resource: string, deps?: OAuthDependencies): Promise<AuthorizationServer>;
+export interface StoreLoginDependencies extends OAuthDependencies {
+    openUrl: (url: string) => Promise<unknown>;
+    log: (message: string) => void;
+    timeoutMs?: number;
+    /** Register a new client instead of reusing this machine's ("summer login --store --force"). */
+    newClient?: boolean;
+    /** Tests only: other loopback ports. */
+    ports?: readonly number[];
+}
+/** Browser sign-in (authorization code + PKCE) that stores ~/.summer/oauth-token. */
+export declare function runStoreLogin(deps: StoreLoginDependencies): Promise<StoredOAuthToken>;
+export declare function readStoredOAuthToken(): Promise<StoredOAuthToken | null>;
+/**
+ * A current store access token: the stored one, refreshed when it expires
+ * within a minute.
+ */
+export declare function getStoreAccessToken(deps?: OAuthDependencies): Promise<string>;
+export {};