summer-engine 2.7.0 → 2.8.0

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>;

package/dist/lib/config.js

@@ -0,0 +1,142 @@
+import { readStoreJson, writeStoreJson } from "./store.js";
+const CONFIG_FILE = "config.json";
+const DEFAULT_GATEWAY_URL = "https://www.summerengine.com";
+const DEFAULT_CREATOR_API_URL = "https://summercraft.ai";
+export const CONFIG_KEYS = [
+    "gateway.url",
+    "creator.apiUrl",
+    "creator.projectId",
+    "creator.channel",
+];
+function emptyConfig() {
+    return { schemaVersion: 1 };
+}
+export async function readSummerConfig() {
+    const value = await readStoreJson(CONFIG_FILE);
+    if (!value)
+        return emptyConfig();
+    if (value.schemaVersion !== 1) {
+        throw new Error(`Unsupported ~/.summer/config.json schema ${String(value.schemaVersion)}. Recovery: upgrade the Summer CLI, or move config.json aside and configure it again.`);
+    }
+    return value;
+}
+function validateGatewayUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`gateway.url must be a complete URL. Recovery: use "summer config set gateway.url https://www.summerengine.com".`);
+    }
+    const local = parsed.hostname === "localhost" ||
+        parsed.hostname === "127.0.0.1" ||
+        parsed.hostname === "::1";
+    if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
+        throw new Error("gateway.url must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+        throw new Error("gateway.url cannot contain credentials, query parameters, or fragments. Recovery: set only the origin URL and retry.");
+    }
+    return parsed.toString().replace(/\/+$/, "");
+}
+function validateCreatorApiUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error('creator.apiUrl must be a complete URL. Recovery: use "summer config set creator.apiUrl https://summercraft.ai".');
+    }
+    const local = parsed.hostname === "localhost" ||
+        parsed.hostname === "127.0.0.1" ||
+        parsed.hostname === "::1";
+    if (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:")) {
+        throw new Error("creator.apiUrl must use HTTPS (HTTP is allowed only for localhost). Recovery: set an HTTPS URL and retry.");
+    }
+    if (parsed.username ||
+        parsed.password ||
+        parsed.pathname !== "/" ||
+        parsed.search ||
+        parsed.hash) {
+        throw new Error("creator.apiUrl must be an origin without credentials, a path, query parameters, or fragments.");
+    }
+    return parsed.origin;
+}
+function validateValue(key, value) {
+    const clean = value.trim();
+    if (!clean) {
+        throw new Error(`Cannot set ${key} to an empty value. Recovery: provide a value, or run "summer config unset ${key}".`);
+    }
+    if (key === "gateway.url")
+        return validateGatewayUrl(clean);
+    if (key === "creator.apiUrl")
+        return validateCreatorApiUrl(clean);
+    if (key === "creator.channel" && !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(clean)) {
+        throw new Error("creator.channel may contain letters, numbers, dots, underscores, and hyphens. Recovery: choose a channel such as production or preview.");
+    }
+    if (key === "creator.projectId" && clean.length > 128) {
+        throw new Error("creator.projectId is too long. Recovery: copy the project ID from the Summer creator dashboard and retry.");
+    }
+    return clean;
+}
+export function getConfigValue(config, key) {
+    if (key === "gateway.url")
+        return config.gateway?.url;
+    if (key === "creator.apiUrl")
+        return config.creator?.apiUrl;
+    if (key === "creator.projectId")
+        return config.creator?.projectId;
+    return config.creator?.channel;
+}
+export async function setConfigValue(key, rawValue) {
+    const config = await readSummerConfig();
+    const value = validateValue(key, rawValue);
+    if (key === "gateway.url") {
+        config.gateway = { ...config.gateway, url: value };
+    }
+    else if (key === "creator.apiUrl") {
+        config.creator = { ...config.creator, apiUrl: value };
+    }
+    else if (key === "creator.projectId") {
+        config.creator = { ...config.creator, projectId: value };
+    }
+    else {
+        config.creator = { ...config.creator, channel: value };
+    }
+    await writeStoreJson(CONFIG_FILE, config);
+    return config;
+}
+export async function unsetConfigValue(key) {
+    const config = await readSummerConfig();
+    if (key === "gateway.url" && config.gateway)
+        delete config.gateway.url;
+    if (key === "creator.apiUrl" && config.creator)
+        delete config.creator.apiUrl;
+    if (key === "creator.projectId" && config.creator) {
+        delete config.creator.projectId;
+    }
+    if (key === "creator.channel" && config.creator)
+        delete config.creator.channel;
+    if (config.gateway && Object.keys(config.gateway).length === 0) {
+        delete config.gateway;
+    }
+    if (config.creator && Object.keys(config.creator).length === 0) {
+        delete config.creator;
+    }
+    await writeStoreJson(CONFIG_FILE, config);
+    return config;
+}
+export function isConfigKey(value) {
+    return CONFIG_KEYS.includes(value);
+}
+export async function getGatewayUrl() {
+    const environment = process.env.SUMMER_GATEWAY_URL?.trim();
+    if (environment)
+        return validateGatewayUrl(environment);
+    const config = await readSummerConfig();
+    return config.gateway?.url ?? DEFAULT_GATEWAY_URL;
+}
+export async function getCreatorApiUrl() {
+    const config = await readSummerConfig();
+    return config.creator?.apiUrl ?? DEFAULT_CREATOR_API_URL;
+}

package/dist/lib/creator.d.ts

@@ -0,0 +1,93 @@
+export type CreatorOperation = "publish" | "releases" | "logs";
+export type CreatorFace = "cli" | "mcp";
+export declare const CREATOR_API_CONTRACT: "summer.creator.v1";
+export declare const CREATOR_API_AUDIT: {
+    readonly auditedAt: "2026-07-30";
+    readonly repository: "SummerEngine/summercraft";
+    readonly contract: "summer.creator.v1";
+    readonly credentialAudience: "summercraft-creator";
+    readonly requiredServerScope: "publish";
+    readonly operations: {
+        readonly publish: {
+            readonly supported: true;
+            readonly route: "/api/creator/v1/publish";
+        };
+        readonly releases: {
+            readonly supported: true;
+            readonly route: "/api/creator/v1/releases";
+        };
+        readonly logs: {
+            readonly supported: false;
+            readonly route: null;
+        };
+    };
+};
+export declare class CreatorOperationError extends Error {
+    readonly code: string;
+    readonly operation: CreatorOperation;
+    readonly recovery: string;
+    readonly status?: number | undefined;
+    constructor(code: string, operation: CreatorOperation, message: string, recovery: string, status?: number | undefined);
+}
+export interface CreatorClientDependencies {
+    fetch: typeof fetch;
+    now: () => Date;
+}
+export interface PublishCreatorInput {
+    project?: string;
+    artifact?: string;
+    manifest?: string;
+    version?: string;
+    projectId?: string;
+    channel?: string;
+    notes?: string;
+    confirm?: boolean;
+    face: CreatorFace;
+}
+export interface CreatorPublishResult {
+    ok: true;
+    contract: typeof CREATOR_API_CONTRACT;
+    operation: "publish";
+    projectId: string;
+    releaseId: string;
+    version: string;
+    sha256: string;
+    sizeBytes: number;
+    status: string;
+    detail: string | null;
+}
+export declare function publishCreator(input: PublishCreatorInput, overrides?: Partial<CreatorClientDependencies>): Promise<CreatorPublishResult>;
+export interface ListCreatorReleasesInput {
+    projectId?: string;
+    limit?: number;
+    cursor?: string;
+    face: CreatorFace;
+}
+export interface CreatorRelease {
+    releaseId: string;
+    gameId: string;
+    version: string;
+    state: "published" | "pending_review" | "retired";
+    gameStatus: string;
+    sha256: string | null;
+    sizeBytes: number | null;
+    changelog: string | null;
+    submittedAt: string;
+    artifactPlane: "r2" | "legacy";
+}
+export interface CreatorReleasesResult {
+    ok: true;
+    contract: typeof CREATOR_API_CONTRACT;
+    operation: "releases";
+    projectId: string;
+    releases: CreatorRelease[];
+    nextCursor: string | null;
+}
+export declare function listCreatorReleases(input: ListCreatorReleasesInput, overrides?: Partial<CreatorClientDependencies>): Promise<CreatorReleasesResult>;
+export interface ReadCreatorLogsInput {
+    projectId?: string;
+    releaseId?: string;
+    limit?: number;
+    face: CreatorFace;
+}
+export declare function readCreatorLogs(input: ReadCreatorLogsInput): Promise<never>;