summer-engine 2.7.0 → 2.8.1

package/dist/lib/api-client.js

@@ -2,7 +2,7 @@ import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
 import { randomUUID } from "node:crypto";
-import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
+import { getApiToken, getApiPort, checkEngineHealth, resolveEngineConnection, } from "./engine.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 function asRecord(value) {
     return value && typeof value === "object" && !Array.isArray(value)
@@ -74,15 +74,25 @@ export class EngineApiClient {
     // preserves the pre-2.6.6 constructor contract for existing callers that only
     // supplied a projectIdHash.
     targetIdentity;
-    constructor(port, token, targetIdentity = {}) {
+    selection;
+    constructor(port, token, targetIdentity = {}, selection = null) {
         this.port = port;
         this.token = token;
         this.targetIdentity =
             typeof targetIdentity === "string"
                 ? { projectIdHash: targetIdentity }
                 : { ...targetIdentity };
-    }
-    static async connect() {
+        this.selection = selection ? { ...selection } : null;
+    }
+    static async connect(selection) {
+        if (selection) {
+            const connection = await resolveEngineConnection(selection);
+            return new EngineApiClient(connection.port, connection.token, {
+                instanceId: connection.health.instanceId,
+                projectId: connection.health.projectId,
+                projectIdHash: connection.health.projectIdHash,
+            }, { ...selection });
+        }
         const port = await getApiPort();
         const token = await getApiToken();
         if (!token) {
@@ -320,14 +330,33 @@ export class EngineApiClient {
         });
         return this.request("GET", `/api/state/read-file?${query.toString()}`);
     }
-    async getSceneState(scenePath) {
-        const query = scenePath
-            ? `?scene=${encodeURIComponent(scenePath)}`
-            : "";
+    async getSceneState(scenePath, options) {
+        // depth/limit only take effect on targeted (scene=) reads: the engine
+        // routes those through the live command queue and forwards every query
+        // param into StateProvider::scene_state (tool_net_thread.cpp
+        // _parse_state_args). An UNtargeted read is answered from a pre-published
+        // snapshot built with the defaults (depth 2, limit 200) and its query
+        // params are ignored — callers who need depth/limit must pass scenePath
+        // (summer_get_scene_tree resolves the current scene path for this).
+        const parts = [];
+        if (scenePath)
+            parts.push(`scene=${encodeURIComponent(scenePath)}`);
+        if (options?.depth !== undefined)
+            parts.push(`depth=${options.depth}`);
+        if (options?.limit !== undefined)
+            parts.push(`limit=${options.limit}`);
+        const query = parts.length ? `?${parts.join("&")}` : "";
         return this.request("GET", `/api/state/scene${query}`);
     }
-    async getProjectState() {
-        return this.request("GET", "/api/state/project");
+    async getProjectState(prefix) {
+        // ?prefix= is sent for forward-compatibility, but current engine builds
+        // IGNORE it: /api/state/project is always served from the snapshot, which
+        // is published with empty args (local_api_server.cpp
+        // _maybe_publish_snapshot), so StateProvider::project_state never sees the
+        // query. Callers that need a prefix subset must also filter client-side
+        // (summer_get_project_context does).
+        const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+        return this.request("GET", `/api/state/project${query}`);
     }
     async getDiagnostics() {
         return this.request("GET", "/api/state/diagnostics");
@@ -465,6 +494,9 @@ export class EngineApiClient {
             sceneHasCamera: boolFrom(payload.scene_has_camera),
             sceneHadLight: boolFrom(payload.scene_had_light),
             usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
+            framing: stringFrom(payload.framing),
+            framedNode: stringFrom(payload.framed_node),
+            renderRetries: numberFrom(payload.render_retries),
             projectMismatch,
             metadata: withoutImageData(payload),
         };
@@ -515,9 +547,14 @@ export class EngineApiClient {
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
      * boot; physics/animations are static). Mirrors the web previewScene op input
      * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
-     * node_path? } — scene_path optional, engine defaults to the open scene. The
-     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
-     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     * node? } — scene_path optional, engine defaults to the open scene. `node` is
+     * the canonical focus-node arg (the engine also accepts the legacy web wire
+     * name `node_path`); an unresolvable node fails with failure_reason
+     * "node_not_found". framing "auto" is an alias of "iso"; the engine also
+     * accepts "top"/"front"/"back"/"left"/"right" and echoes the resolved framing.
+     * The result carries image_base64 + mime (+ width/height) plus the P4.3
+     * confession fields (scene_has_camera / scene_had_light /
+     * used_synthetic_camera) and framing / framed_node / render_retries.
      */
     async scenePreview(input) {
         const opInput = { op: "ScenePreview" };
@@ -529,7 +566,7 @@ export class EngineApiClient {
         if (input?.size)
             opInput.size = input.size;
         if (input?.nodePath)
-            opInput.node_path = input.nodePath;
+            opInput.node = input.nodePath;
         let response;
         try {
             // executeOps stamps the bound identity so a drifted project is rejected
@@ -558,6 +595,20 @@ export class EngineApiClient {
      * will fail and trigger a reconnect+retry if the client really is stale.
      */
     async credentialsChanged() {
+        if (this.selection) {
+            try {
+                const connection = await resolveEngineConnection(this.selection);
+                return (connection.port !== this.port ||
+                    connection.token !== this.token ||
+                    connection.health.instanceId !== this.targetIdentity.instanceId);
+            }
+            catch {
+                // A selected editor disappearing is real drift. Dropping the cached
+                // client makes the next connect report which project/instance is absent
+                // instead of silently following another editor's global pointer.
+                return true;
+            }
+        }
         try {
             const [port, token] = await Promise.all([getApiPort(), getApiToken()]);
             if (!token)

package/dist/lib/auth.d.ts

@@ -1,15 +1,43 @@
-export declare function getSummerDir(): string;
-export declare function getAuthToken(): Promise<string | null>;
-export declare function saveAuthToken(token: string): Promise<void>;
-export declare function getCloudToken(): Promise<string | null>;
-export declare function saveCloudToken(token: string): Promise<void>;
-export declare function getUserInfo(): Promise<{
+export { getSummerDir } from "./store.js";
+export interface SummerUserInfo {
     id: string;
     email: string;
     name?: string;
-} | null>;
-export declare function saveUserInfo(info: {
-    id: string;
-    email: string;
-    name?: string;
-}): Promise<void>;
+}
+export interface CredentialMetadata {
+    audience: string[];
+    scopes: string[];
+    tokenType?: string;
+    issuedAt?: string;
+    expiresAt?: string;
+}
+interface CredentialMetadataDocument {
+    schemaVersion: 1;
+    auth?: CredentialMetadata;
+    cloud?: CredentialMetadata;
+    creator?: CredentialMetadata;
+}
+export interface LoginSession {
+    token: string;
+    cloudToken?: string | null;
+    user?: SummerUserInfo;
+    scopes?: string[];
+    cloudScopes?: string[];
+}
+export declare function getAuthToken(): Promise<string | null>;
+export declare function saveAuthToken(token: string, scopes?: string[]): Promise<void>;
+export declare function getCloudToken(): Promise<string | null>;
+export declare function saveCloudToken(token: string, scopes?: string[]): Promise<void>;
+/**
+ * Summercraft creator tokens are a separate credential audience from the
+ * core-compatible Summer CLI JWT. Never store an sc_ token in auth-token:
+ * the engine reads that file and expects the summer-cli JWT contract.
+ */
+export declare function getCreatorToken(): Promise<string | null>;
+export declare function saveCreatorToken(token: string): Promise<void>;
+export declare function getUserInfo(): Promise<SummerUserInfo | null>;
+export declare function saveUserInfo(info: SummerUserInfo): Promise<void>;
+export declare function saveLoginSession(session: LoginSession): Promise<void>;
+export declare function getCredentialMetadata(): Promise<CredentialMetadataDocument>;
+export declare function clearAuthCredentials(): Promise<number>;
+export declare function assertCredentialScopes(metadata: CredentialMetadata | undefined, requiredScopes: string[]): void;

package/dist/lib/auth.js

@@ -1,52 +1,188 @@
-import { readFile, writeFile, mkdir } from "fs/promises";
-import { existsSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-const SUMMER_DIR = join(homedir(), ".summer");
-export function getSummerDir() {
-    return SUMMER_DIR;
+import { readStoreJson, readStoreText, removeStoreFile, writeStoreJson, writeStoreText, } from "./store.js";
+export { getSummerDir } from "./store.js";
+const AUTH_TOKEN_FILE = "auth-token";
+const CLOUD_TOKEN_FILE = "cloud-token";
+const CREATOR_TOKEN_FILE = "creator-token";
+const USER_FILE = "user.json";
+const METADATA_FILE = "credential-metadata.json";
+function decodeJwtMetadata(token, explicitScopes = []) {
+    const payload = decodeJwtPayload(token);
+    const aud = payload.aud;
+    const audience = typeof aud === "string"
+        ? [aud]
+        : Array.isArray(aud)
+            ? aud.filter((value) => typeof value === "string")
+            : [];
+    const claimScopes = typeof payload.scope === "string"
+        ? payload.scope.split(/\s+/)
+        : Array.isArray(payload.scp)
+            ? payload.scp.filter((value) => typeof value === "string")
+            : [];
+    const scopes = [...new Set([...explicitScopes, ...claimScopes].filter(Boolean))].sort();
+    const issuedAt = typeof payload.iat === "number"
+        ? new Date(payload.iat * 1000).toISOString()
+        : undefined;
+    const expiresAt = typeof payload.exp === "number"
+        ? new Date(payload.exp * 1000).toISOString()
+        : undefined;
+    return {
+        audience,
+        scopes,
+        ...(typeof payload.type === "string" ? { tokenType: payload.type } : {}),
+        ...(issuedAt ? { issuedAt } : {}),
+        ...(expiresAt ? { expiresAt } : {}),
+    };
 }
-async function ensureSummerDir() {
-    if (!existsSync(SUMMER_DIR)) {
-        await mkdir(SUMMER_DIR, { recursive: true, mode: 0o700 });
-    }
-}
-export async function getAuthToken() {
+function decodeJwtPayload(token) {
     try {
-        const token = await readFile(join(SUMMER_DIR, "auth-token"), "utf-8");
-        return token.trim() || null;
+        const encoded = token.split(".")[1];
+        if (encoded) {
+            return JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        }
     }
     catch {
-        return null;
+        // Metadata is advisory only. The gateway verifies the signature.
     }
+    return {};
+}
+async function readMetadata() {
+    return ((await readStoreJson(METADATA_FILE)) ?? {
+        schemaVersion: 1,
+    });
+}
+async function updateMetadata(kind, value) {
+    const current = await readMetadata();
+    const next = {
+        ...current,
+        schemaVersion: 1,
+        [kind]: value,
+    };
+    if (!next.auth)
+        delete next.auth;
+    if (!next.cloud)
+        delete next.cloud;
+    if (!next.creator)
+        delete next.creator;
+    await writeStoreJson(METADATA_FILE, next);
+}
+export async function getAuthToken() {
+    const token = await readStoreText(AUTH_TOKEN_FILE);
+    return token?.trim() || null;
 }
-export async function saveAuthToken(token) {
-    await ensureSummerDir();
-    await writeFile(join(SUMMER_DIR, "auth-token"), token, { encoding: "utf-8", mode: 0o600 });
+export async function saveAuthToken(token, scopes = []) {
+    const clean = token.trim();
+    if (!clean)
+        throw new Error("Cannot save an empty auth token.");
+    await writeStoreText(AUTH_TOKEN_FILE, `${clean}\n`);
+    await updateMetadata("auth", decodeJwtMetadata(clean, scopes));
 }
 export async function getCloudToken() {
-    try {
-        const token = await readFile(join(SUMMER_DIR, "cloud-token"), "utf-8");
-        return token.trim() || null;
-    }
-    catch {
-        return null;
-    }
+    const token = await readStoreText(CLOUD_TOKEN_FILE);
+    return token?.trim() || null;
+}
+export async function saveCloudToken(token, scopes = []) {
+    const clean = token.trim();
+    if (!clean)
+        throw new Error("Cannot save an empty cloud token.");
+    await writeStoreText(CLOUD_TOKEN_FILE, `${clean}\n`);
+    await updateMetadata("cloud", decodeJwtMetadata(clean, scopes));
 }
-export async function saveCloudToken(token) {
-    await ensureSummerDir();
-    await writeFile(join(SUMMER_DIR, "cloud-token"), token, { encoding: "utf-8", mode: 0o600 });
+/**
+ * Summercraft creator tokens are a separate credential audience from the
+ * core-compatible Summer CLI JWT. Never store an sc_ token in auth-token:
+ * the engine reads that file and expects the summer-cli JWT contract.
+ */
+export async function getCreatorToken() {
+    const token = await readStoreText(CREATOR_TOKEN_FILE);
+    return token?.trim() || null;
+}
+export async function saveCreatorToken(token) {
+    const clean = token.trim();
+    if (!/^sc_[A-Za-z0-9_-]{32,}$/.test(clean)) {
+        throw new Error('That is not a Summercraft creator API token. Recovery: open /creator/settings/tokens, mint a token with the "publish" scope, and paste the complete one-time sc_ value.');
+    }
+    await writeStoreText(CREATOR_TOKEN_FILE, `${clean}\n`);
+    await updateMetadata("creator", {
+        audience: ["summercraft-creator"],
+        scopes: ["publish"],
+        tokenType: "api",
+    });
 }
 export async function getUserInfo() {
-    try {
-        const data = await readFile(join(SUMMER_DIR, "user.json"), "utf-8");
-        return JSON.parse(data);
+    return readStoreJson(USER_FILE);
+}
+export async function saveUserInfo(info) {
+    await writeStoreJson(USER_FILE, info);
+}
+export async function saveLoginSession(session) {
+    const payload = decodeJwtPayload(session.token);
+    if (!session.user ||
+        typeof payload.sub !== "string" ||
+        payload.sub !== session.user.id) {
+        throw new Error('The gateway returned an incomplete or mismatched identity. Recovery: run "summer login --force" again; if it repeats, report the CLI login endpoint as unhealthy.');
     }
-    catch {
-        return null;
+    const metadata = decodeJwtMetadata(session.token, session.scopes);
+    if (metadata.tokenType !== "cli" ||
+        !metadata.audience.includes("summer-cli")) {
+        throw new Error('The gateway returned a token that is not valid for the Summer CLI. Recovery: run "summer login --force" again after the gateway is updated.');
     }
+    if (metadata.expiresAt && Date.parse(metadata.expiresAt) <= Date.now()) {
+        throw new Error('The gateway returned an expired CLI token. Recovery: run "summer login --force" again; if it repeats, check the gateway clock and token issuer.');
+    }
+    // Keep auth-token and user.json canonical: the desktop engine already reads
+    // those exact files. credential-metadata.json adds audience/scope information
+    // without changing or duplicating the secret.
+    // Activate the new auth token last. The desktop engine cross-checks token.sub
+    // against user.json, so an interrupted multi-file write fails closed instead
+    // of adopting a mismatched identity.
+    if (session.user)
+        await saveUserInfo(session.user);
+    if (session.cloudToken) {
+        await saveCloudToken(session.cloudToken, session.cloudScopes);
+    }
+    await saveAuthToken(session.token, session.scopes);
 }
-export async function saveUserInfo(info) {
-    await ensureSummerDir();
-    await writeFile(join(SUMMER_DIR, "user.json"), JSON.stringify(info, null, 2), { encoding: "utf-8", mode: 0o600 });
+export async function getCredentialMetadata() {
+    const metadata = await readMetadata();
+    const token = await getAuthToken();
+    const cloudToken = await getCloudToken();
+    const creatorToken = await getCreatorToken();
+    return {
+        schemaVersion: 1,
+        ...(token
+            ? { auth: metadata.auth ?? decodeJwtMetadata(token) }
+            : {}),
+        ...(cloudToken
+            ? { cloud: metadata.cloud ?? decodeJwtMetadata(cloudToken) }
+            : {}),
+        ...(creatorToken
+            ? {
+                creator: metadata.creator ?? {
+                    audience: ["summercraft-creator"],
+                    scopes: [],
+                    tokenType: "api",
+                },
+            }
+            : {}),
+    };
+}
+export async function clearAuthCredentials() {
+    let removed = 0;
+    for (const file of [
+        AUTH_TOKEN_FILE,
+        CLOUD_TOKEN_FILE,
+        CREATOR_TOKEN_FILE,
+        USER_FILE,
+        METADATA_FILE,
+    ]) {
+        if (await removeStoreFile(file))
+            removed += 1;
+    }
+    return removed;
+}
+export function assertCredentialScopes(metadata, requiredScopes) {
+    const missing = requiredScopes.filter((scope) => !metadata?.scopes.includes(scope));
+    if (missing.length === 0)
+        return;
+    throw new Error(`This sign-in does not grant ${missing.join(", ")}. Recovery: run "summer login --force" after the platform enables scoped creator tokens, then retry.`);
 }

package/dist/lib/cloud/engine-bridge.d.ts

@@ -13,9 +13,22 @@ export declare function writeProjectPathMarker(projectRoot: string): Promise<voi
  */
 export declare function saveDirtyScenesIfRunning(projectRoot: string): Promise<boolean>;
 /**
- * After apply (spec 8.7): trigger a filesystem rescan and reload the open
- * scene if the pull replaced it. ScanChanges is the engine-side hook; older
- * engines without it simply reject the op and the editor's own focus scan
- * picks the changes up.
+ * After apply (spec 8.7): tell the open editor that files changed underneath it.
+ *
+ * BOTH HALVES OF THIS ARE CURRENTLY DEAD, and the user-visible symptom is that
+ * after a cloud pull the editor keeps showing the pre-pull bytes:
+ *
+ *  - `ScanChanges` is not an engine op. The dispatch ladder
+ *    (modules/1summer_engine/editor/ops_executor.cpp:1060-1290) has 84 op kinds and
+ *    no ScanChanges branch, so this fails on EVERY build, not just older ones. The
+ *    engine-side capability exists as EditorFileSystem::scan_changes() but is
+ *    exposed neither as an op nor to GDScript, so there is no caller-reachable
+ *    rescan verb at all. O2 owns adding one.
+ *  - The scene reload depends on `session.scene`, which /api/health never returns
+ *    (see the note in lib/engine.ts), so it is always undefined and never fires.
+ *
+ * Until the engine exposes a rescan, say so out loud rather than swallowing it —
+ * a stale editor that looks correct is exactly the failure this codebase is trying
+ * to stop shipping.
  */
 export declare function notifyEngineAfterApply(projectRoot: string, appliedPaths: readonly string[]): Promise<void>;

package/dist/lib/cloud/engine-bridge.js

@@ -81,10 +81,23 @@ export async function saveDirtyScenesIfRunning(projectRoot) {
     }
 }
 /**
- * After apply (spec 8.7): trigger a filesystem rescan and reload the open
- * scene if the pull replaced it. ScanChanges is the engine-side hook; older
- * engines without it simply reject the op and the editor's own focus scan
- * picks the changes up.
+ * After apply (spec 8.7): tell the open editor that files changed underneath it.
+ *
+ * BOTH HALVES OF THIS ARE CURRENTLY DEAD, and the user-visible symptom is that
+ * after a cloud pull the editor keeps showing the pre-pull bytes:
+ *
+ *  - `ScanChanges` is not an engine op. The dispatch ladder
+ *    (modules/1summer_engine/editor/ops_executor.cpp:1060-1290) has 84 op kinds and
+ *    no ScanChanges branch, so this fails on EVERY build, not just older ones. The
+ *    engine-side capability exists as EditorFileSystem::scan_changes() but is
+ *    exposed neither as an op nor to GDScript, so there is no caller-reachable
+ *    rescan verb at all. O2 owns adding one.
+ *  - The scene reload depends on `session.scene`, which /api/health never returns
+ *    (see the note in lib/engine.ts), so it is always undefined and never fires.
+ *
+ * Until the engine exposes a rescan, say so out loud rather than swallowing it —
+ * a stale editor that looks correct is exactly the failure this codebase is trying
+ * to stop shipping.
  */
 export async function notifyEngineAfterApply(projectRoot, appliedPaths) {
     if (!appliedPaths.length)
@@ -92,22 +105,35 @@ export async function notifyEngineAfterApply(projectRoot, appliedPaths) {
     const session = await connectForProject(projectRoot);
     if (!session)
         return;
+    let rescanned = false;
     try {
         await session.client.executeOps([{ op: "ScanChanges" }], { projectIdHash: session.projectIdHash });
+        rescanned = true;
     }
     catch {
-        // Engine build without the ScanChanges op; non-fatal.
+        rescanned = false;
     }
+    let reloaded = false;
     try {
         const scene = session.scene;
         if (scene && scene.startsWith("res://")) {
             const sceneRel = scene.slice("res://".length);
             if (appliedPaths.includes(sceneRel)) {
                 await session.client.executeOps([{ op: "OpenScene", path: scene }], { projectIdHash: session.projectIdHash });
+                reloaded = true;
             }
         }
     }
     catch {
-        // Reload is best-effort; the editor reloads from disk on focus.
+        reloaded = false;
+    }
+    if (!rescanned) {
+        console.warn(`Pulled ${appliedPaths.length} file(s), but could not tell the running editor to rescan ` +
+            "(this engine build exposes no rescan op). The editor may still be showing the old " +
+            "contents — click into its window, or reopen the affected scene, before trusting what you see.");
+    }
+    else if (!reloaded) {
+        console.warn("Pulled files and rescanned, but could not confirm which scene is open, so an open " +
+            "scene replaced by the pull was not reloaded. Reopen it before trusting what you see.");
     }
 }

package/dist/lib/config.d.ts

@@ -0,0 +1,20 @@
+export interface SummerConfig {
+    schemaVersion: 1;
+    gateway?: {
+        url?: string;
+    };
+    creator?: {
+        apiUrl?: string;
+        projectId?: string;
+        channel?: string;
+    };
+}
+export declare const CONFIG_KEYS: readonly ["gateway.url", "creator.apiUrl", "creator.projectId", "creator.channel"];
+export type ConfigKey = (typeof CONFIG_KEYS)[number];
+export declare function readSummerConfig(): Promise<SummerConfig>;
+export declare function getConfigValue(config: SummerConfig, key: ConfigKey): string | undefined;
+export declare function setConfigValue(key: ConfigKey, rawValue: string): Promise<SummerConfig>;
+export declare function unsetConfigValue(key: ConfigKey): Promise<SummerConfig>;
+export declare function isConfigKey(value: string): value is ConfigKey;
+export declare function getGatewayUrl(): Promise<string>;
+export declare function getCreatorApiUrl(): Promise<string>;