summer-engine 3.2.1 → 3.4.0

package/dist/core/capabilities/export-presets.js

@@ -0,0 +1,177 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { BuildToolError } from "./summer-bundle.js";
+/**
+ * Store targets for summer_export_game, and the export presets that make them.
+ *
+ * The Summer Games store has two intakes (summer-platform):
+ * - build-publications takes ONE summer.bundle.v1 .zip per Build. Summer runs
+ *   its client.pck on its own client templates (the Summer Games iOS and
+ *   Android apps, the Summer desktop app on macOS and Windows), so the creator
+ *   needs no export template and signs nothing. A target only picks the
+ *   platforms the bundle declares and the texture formats the pack carries
+ *   (the summer.games preset option platforms/<id>).
+ * - store versions take a web build (a static HTML5 .zip played in an iframe)
+ *   and native desktop downloads (macos-universal, windows-x64). These are
+ *   ordinary exports and need the matching export template.
+ *
+ * Presets are kept in export_presets.cfg under fixed names, so the creator
+ * sees them in the Export dialog: "summer.games ios", "summer.games
+ * ios+android", "Summer download Web", ... Only the options listed here are
+ * ever rewritten; every other preset and setting stays byte-for-byte. The
+ * engine adds its default "summer.games" preset only while the file has no
+ * summer.games preset, so the default is written alongside the first named
+ * one.
+ */
+export const STORE_TARGETS = ["macos", "windows", "ios", "android", "web"];
+/** Targets a summer.games bundle can declare (the engine's CLIENT_PLATFORMS). */
+export const BUNDLE_TARGETS = ["macos", "windows", "ios", "android"];
+/** Targets the store takes as a download or web build (store versions). */
+export const DOWNLOAD_TARGETS = ["macos", "windows", "web"];
+/** Engine summer.games platform and default preset name (summer_games_export_platform.h PLATFORM_NAME). */
+export const SUMMER_GAMES_PLATFORM = "summer.games";
+export const SUMMER_GAMES_PRESET = "summer.games";
+/** summer_games_export_platform.h CLIENT_FEATURE; create_preset sets it, the file must keep it. */
+const SUMMER_CLIENT_FEATURE = "summer_client";
+const PRESETS_FILE = "export_presets.cfg";
+/** Canonical order, without repeats. */
+export function normalizeTargets(targets) {
+    const unknown = targets.filter((target) => !STORE_TARGETS.includes(target));
+    if (unknown.length) {
+        throw new BuildToolError("target_unknown", `Unknown export target ${unknown.join(", ")}.`, `Recovery: use targets from ${STORE_TARGETS.join(", ")}.`);
+    }
+    const chosen = STORE_TARGETS.filter((target) => targets.includes(target));
+    if (!chosen.length) {
+        throw new BuildToolError("target_unknown", "No export target was given.", `Recovery: pass targets from ${STORE_TARGETS.join(", ")}.`);
+    }
+    return chosen;
+}
+/** Variant text for a String option. */
+export function variantString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+export function bundlePresetSpec(targets) {
+    return {
+        name: `${SUMMER_GAMES_PRESET} ${targets.join("+")}`,
+        platform: SUMMER_GAMES_PLATFORM,
+        customFeatures: SUMMER_CLIENT_FEATURE,
+        // Every engine platform is written, so a platform added by a newer engine
+        // never turns on by default in a preset made for other targets.
+        options: Object.fromEntries(STORE_TARGETS.map((target) => [`platforms/${target}`, String(targets.includes(target))])),
+    };
+}
+function parseSections(text) {
+    const preamble = [];
+    const sections = [];
+    for (const line of text.split(/\r?\n/)) {
+        const header = /^\[([^\]]+)\]\s*$/.exec(line);
+        if (header)
+            sections.push({ header: header[1], lines: [] });
+        else if (sections.length)
+            sections[sections.length - 1].lines.push(line);
+        else
+            preamble.push(line);
+    }
+    return { preamble, sections };
+}
+function stringValue(section, key) {
+    const prefix = `${key}=`;
+    for (const line of section.lines) {
+        if (!line.startsWith(prefix))
+            continue;
+        const match = /^"((?:[^"\\]|\\.)*)"\s*$/.exec(line.slice(prefix.length));
+        if (match)
+            return match[1].replace(/\\(["\\])/g, "$1");
+    }
+    return null;
+}
+function presetLines(spec) {
+    return [
+        "",
+        `name=${variantString(spec.name)}`,
+        `platform=${variantString(spec.platform)}`,
+        "runnable=false",
+        "dedicated_server=false",
+        ...(spec.customFeatures !== undefined ? [`custom_features=${variantString(spec.customFeatures)}`] : []),
+        'export_filter="all_resources"',
+        'include_filter=""',
+        'exclude_filter=""',
+        'export_path=""',
+        "",
+    ];
+}
+function optionLines(options) {
+    return ["", ...Object.entries(options).map(([key, value]) => `${key}=${value}`), ""];
+}
+/** Make sure export_presets.cfg has this preset with these option values. */
+export async function ensurePreset(project, spec) {
+    const file = join(project, PRESETS_FILE);
+    const text = existsSync(file) ? await readFile(file, "utf8") : "";
+    const { preamble, sections } = parseSections(text);
+    const presets = sections
+        .map((section) => ({ section, index: /^preset\.(\d+)$/.exec(section.header)?.[1] }))
+        .filter((item) => item.index !== undefined);
+    const ours = presets.find(({ section }) => stringValue(section, "name") === spec.name);
+    if (ours) {
+        if (stringValue(ours.section, "platform") !== spec.platform) {
+            throw new BuildToolError("export_preset_conflict", `export_presets.cfg already has a preset named "${spec.name}" for another platform.`, "Recovery: rename or delete that preset in Project > Export, then export again.");
+        }
+        const optionsHeader = `preset.${ours.index}.options`;
+        let options = sections.find((section) => section.header === optionsHeader);
+        const wanted = new Map(Object.entries(spec.options));
+        let changed = false;
+        if (!options) {
+            options = { header: optionsHeader, lines: optionLines(spec.options) };
+            sections.splice(sections.indexOf(ours.section) + 1, 0, options);
+            changed = true;
+        }
+        else {
+            const seen = new Set();
+            options.lines = options.lines.map((line) => {
+                const at = line.indexOf("=");
+                const key = at > 0 ? line.slice(0, at) : "";
+                if (!wanted.has(key))
+                    return line;
+                seen.add(key);
+                if (line.slice(at + 1).trim() === wanted.get(key))
+                    return line;
+                changed = true;
+                return `${key}=${wanted.get(key)}`;
+            });
+            const missing = [...wanted].filter(([key]) => !seen.has(key)).map(([key, value]) => `${key}=${value}`);
+            if (missing.length) {
+                const end = options.lines.length && options.lines[options.lines.length - 1] === "" ? options.lines.length - 1 : options.lines.length;
+                options.lines.splice(end, 0, ...missing);
+                changed = true;
+            }
+        }
+        if (!changed)
+            return { name: spec.name, change: "unchanged" };
+        await writeFile(file, render(preamble, sections));
+        return { name: spec.name, change: "updated" };
+    }
+    let next = presets.reduce((max, { index }) => Math.max(max, Number(index) + 1), 0);
+    const added = [];
+    const hasSummerGames = presets.some(({ section }) => stringValue(section, "platform") === SUMMER_GAMES_PLATFORM);
+    if (spec.platform === SUMMER_GAMES_PLATFORM && !hasSummerGames) {
+        // Keep the engine's default "summer.games" preset: it leaves the editor
+        // once the file holds any summer.games preset. No options section, so the
+        // engine fills in its own defaults.
+        added.push({
+            header: `preset.${next}`,
+            lines: presetLines({ name: SUMMER_GAMES_PRESET, platform: SUMMER_GAMES_PLATFORM, customFeatures: SUMMER_CLIENT_FEATURE, options: {} }),
+        });
+        next += 1;
+    }
+    added.push({ header: `preset.${next}`, lines: presetLines(spec) });
+    added.push({ header: `preset.${next}.options`, lines: optionLines(spec.options) });
+    await writeFile(file, render(preamble, [...sections, ...added]));
+    return { name: spec.name, change: "created" };
+}
+function render(preamble, sections) {
+    const body = sections.map((section) => [`[${section.header}]`, ...section.lines].join("\n")).join("\n");
+    const head = preamble.join("\n");
+    const joined = head.trim() ? `${head.replace(/\n*$/, "\n")}\n${body}` : body;
+    return joined.endsWith("\n") ? joined : `${joined}\n`;
+}

package/dist/core/capabilities/export-templates.d.ts

@@ -0,0 +1,118 @@
+import { type EngineRun } from "./engine-run.js";
+/**
+ * summer_export_templates: list, download and install Summer Engine export
+ * templates from Summer's CDN.
+ *
+ * The Summer Games store's own builds (summer.games bundles for iOS, Android,
+ * macOS and Windows) need no template. Templates are for the store's web
+ * build (the Summer WebGPU/JSPI Forward+ template, web_summer_jspi_*.zip) and
+ * for native downloads (macos.zip, windows_*_x86_64.exe). The Mac app bundles
+ * only macos.zip, the Windows app only the Windows exes, both bundle the web
+ * pair when packaged with it, and Linux editors bundle nothing; the editor's
+ * own downloader reads the stock Godot mirrors, which never carry Summer's
+ * binaries. So this tool fetches them from
+ *
+ *   <base>/<summerVersion>/manifest.json   (schema summer.export-templates.v1)
+ *
+ * verifies each file's sha256 and installs it where the engine looks:
+ * <user data>/export_templates/<FULL_CONFIG>/ (Godot's folder; Summer has not
+ * renamed it), FULL_CONFIG being the Godot version the engine prints with
+ * --version (4.7.2.stable, plus .mono for the .NET editor).
+ */
+export declare const TEMPLATES_URL_ENV = "SUMMER_TEMPLATES_URL";
+export declare const DEFAULT_TEMPLATES_URL = "https://downloads.summer.games/engine-templates";
+export declare const TEMPLATES_MANIFEST_SCHEMA = "summer.export-templates.v1";
+export declare const TEMPLATE_PLATFORMS: readonly ["web", "macos", "windows", "linux", "ios", "android"];
+export type TemplatePlatform = (typeof TEMPLATE_PLATFORMS)[number];
+export interface TemplateEntry {
+    platform: TemplatePlatform;
+    /** File name the engine looks for (macos.zip, web_summer_jspi_release.zip, ...). */
+    file: string;
+    /** Path of the file relative to the manifest. */
+    path: string;
+    sha256: string;
+    size: number;
+    debug: boolean;
+    /** true: only the .mono folder; false: only the standard folder; null: both. */
+    mono: boolean | null;
+}
+export interface TemplatesManifest {
+    schema: typeof TEMPLATES_MANIFEST_SCHEMA;
+    summerVersion: string;
+    /** Godot FULL_CONFIG without .mono, e.g. 4.7.2.stable: the template folder name. */
+    godotVersion: string;
+    templates: TemplateEntry[];
+}
+export interface EngineTemplateInfo {
+    engine: string;
+    /** Template folder name: Godot FULL_CONFIG, e.g. 4.7.2.stable.mono. */
+    folder: string;
+    mono: boolean;
+    summerVersion: string | null;
+    /** Folders the engine reads, first match wins: inside the app, then the user folder. */
+    searchDirs: string[];
+    /** Where downloads go. */
+    userDir: string;
+}
+export interface TemplatesDependencies {
+    findBinary: () => string | null;
+    run: (binary: string, args: string[], timeoutMs: number) => Promise<EngineRun>;
+    fetch: typeof globalThis.fetch;
+    os: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    home: string;
+}
+/** Godot's user data folder + export_templates (editor_paths.cpp; get_godot_dir_name is "Godot", "godot" on Linux). */
+export declare function userTemplatesRoot(os: NodeJS.Platform, env: NodeJS.ProcessEnv, home: string): string;
+/** Templates inside the installed app (editor_export_platform.cpp find_export_template). */
+export declare function bundledTemplatesRoot(os: NodeJS.Platform, engine: string): string | null;
+/** FULL_CONFIG from `--version` output ("4.7.2.stable.mono.custom_build.abc" -> "4.7.2.stable.mono"). */
+export declare function parseTemplateFolder(output: string): string | null;
+export declare function engineTemplateInfo(overrides?: Partial<TemplatesDependencies>, summerVersion?: string): Promise<EngineTemplateInfo>;
+/** Where the engine would find this template file, or null. */
+export declare function findInstalledTemplate(info: EngineTemplateInfo, file: string): string | null;
+/** Template file the engine needs for a download export (export plugins' template names). */
+export declare function templateFileFor(target: "web" | "macos" | "windows", debug: boolean): string;
+export declare function templatesBaseUrl(env?: NodeJS.ProcessEnv): string;
+export declare function fetchTemplatesManifest(summerVersion: string, overrides?: Partial<TemplatesDependencies>): Promise<{
+    manifest: TemplatesManifest;
+    url: string;
+}>;
+export interface TemplatesInput {
+    action: "list" | "install";
+    /** Template platforms to install (default: web). */
+    platforms?: string[];
+    /** Also install debug templates. */
+    includeDebug?: boolean;
+    /** Summer version of the installed engine, when the tool cannot read it (Windows, Linux). */
+    summerVersion?: string;
+}
+export declare function exportTemplates(input: TemplatesInput, overrides?: Partial<TemplatesDependencies>): Promise<{
+    installed: {
+        file: string;
+        dir: string;
+    }[];
+    available: (TemplateEntry & {
+        installed: boolean;
+    })[] | null;
+    availability: string;
+    note: string;
+    engine: string;
+    folder: string;
+    summerVersion: string | null;
+    searchDirs: string[];
+    ok: true;
+} | {
+    manifest: string;
+    templates: {
+        file: string;
+        path: string;
+        status: "installed" | "already_installed";
+    }[];
+    next: string;
+    engine: string;
+    folder: string;
+    summerVersion: string | null;
+    searchDirs: string[];
+    ok: true;
+}>;

package/dist/core/capabilities/export-templates.js

@@ -0,0 +1,291 @@
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, createWriteStream } from "node:fs";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { homedir, platform as osPlatform } from "node:os";
+import { dirname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { findEngineBinary } from "../engine-install.js";
+import { runEngine } from "./engine-run.js";
+import { hashFile, BuildToolError } from "./summer-bundle.js";
+/**
+ * summer_export_templates: list, download and install Summer Engine export
+ * templates from Summer's CDN.
+ *
+ * The Summer Games store's own builds (summer.games bundles for iOS, Android,
+ * macOS and Windows) need no template. Templates are for the store's web
+ * build (the Summer WebGPU/JSPI Forward+ template, web_summer_jspi_*.zip) and
+ * for native downloads (macos.zip, windows_*_x86_64.exe). The Mac app bundles
+ * only macos.zip, the Windows app only the Windows exes, both bundle the web
+ * pair when packaged with it, and Linux editors bundle nothing; the editor's
+ * own downloader reads the stock Godot mirrors, which never carry Summer's
+ * binaries. So this tool fetches them from
+ *
+ *   <base>/<summerVersion>/manifest.json   (schema summer.export-templates.v1)
+ *
+ * verifies each file's sha256 and installs it where the engine looks:
+ * <user data>/export_templates/<FULL_CONFIG>/ (Godot's folder; Summer has not
+ * renamed it), FULL_CONFIG being the Godot version the engine prints with
+ * --version (4.7.2.stable, plus .mono for the .NET editor).
+ */
+export const TEMPLATES_URL_ENV = "SUMMER_TEMPLATES_URL";
+export const DEFAULT_TEMPLATES_URL = "https://downloads.summer.games/engine-templates";
+export const TEMPLATES_MANIFEST_SCHEMA = "summer.export-templates.v1";
+export const TEMPLATE_PLATFORMS = ["web", "macos", "windows", "linux", "ios", "android"];
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const SAFE_FILE = /^[A-Za-z0-9._-]+$/;
+const VERSION_TIMEOUT_MS = 20_000;
+const defaultDependencies = () => ({
+    findBinary: () => findEngineBinary(osPlatform()),
+    run: runEngine,
+    fetch: (input, init) => globalThis.fetch(input, init),
+    os: osPlatform(),
+    env: process.env,
+    home: homedir(),
+});
+/** Godot's user data folder + export_templates (editor_paths.cpp; get_godot_dir_name is "Godot", "godot" on Linux). */
+export function userTemplatesRoot(os, env, home) {
+    if (os === "darwin")
+        return join(home, "Library", "Application Support", "Godot", "export_templates");
+    if (os === "win32")
+        return join(env.APPDATA || join(home, "AppData", "Roaming"), "Godot", "export_templates");
+    return join(env.XDG_DATA_HOME || join(home, ".local", "share"), "godot", "export_templates");
+}
+/** Templates inside the installed app (editor_export_platform.cpp find_export_template). */
+export function bundledTemplatesRoot(os, engine) {
+    if (os === "darwin")
+        return join(dirname(dirname(engine)), "Resources", "export_templates");
+    if (os === "win32")
+        return join(dirname(engine), "export_templates");
+    return null;
+}
+/** FULL_CONFIG from `--version` output ("4.7.2.stable.mono.custom_build.abc" -> "4.7.2.stable.mono"). */
+export function parseTemplateFolder(output) {
+    const match = /(?<![\d.])(\d+\.\d+(?:\.\d+)?\.(?:stable|dev\d*|alpha\d*|beta\d*|rc\d*)(?:\.mono)?)\b/.exec(output);
+    return match ? match[1] : null;
+}
+/** The Mac app's CFBundleShortVersionString is the Summer version. */
+function macSummerVersion(engine) {
+    const plist = join(dirname(dirname(engine)), "Info.plist");
+    if (!existsSync(plist))
+        return null;
+    const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(readFileSync(plist, "utf8"));
+    return match ? match[1].trim() : null;
+}
+export async function engineTemplateInfo(overrides = {}, summerVersion) {
+    const deps = { ...defaultDependencies(), ...overrides };
+    const engine = deps.findBinary();
+    if (!engine) {
+        throw new BuildToolError("engine_not_installed", "Summer Engine is not installed on this machine.", 'Recovery: run "summer install", or set SUMMER_BIN to the engine executable.');
+    }
+    let run;
+    try {
+        run = await deps.run(engine, ["--headless", "--version"], VERSION_TIMEOUT_MS);
+    }
+    catch (error) {
+        throw new BuildToolError("engine_launch_failed", `Summer Engine could not start: ${error instanceof Error ? error.message : String(error)}.`, 'Recovery: run "summer doctor" and check the engine install.');
+    }
+    const folder = parseTemplateFolder(run.output);
+    if (!folder) {
+        throw new BuildToolError("engine_version_unknown", "Summer Engine did not print a version this tool can read.", 'Recovery: run "summer doctor"; update Summer Engine if it is very old.', undefined, { output: run.output.trim().slice(-400) });
+    }
+    const bundled = bundledTemplatesRoot(deps.os, engine);
+    const userRoot = userTemplatesRoot(deps.os, deps.env, deps.home);
+    const version = summerVersion?.trim() || (deps.os === "darwin" ? macSummerVersion(engine) : null);
+    return {
+        engine,
+        folder,
+        mono: folder.endsWith(".mono"),
+        summerVersion: version,
+        searchDirs: [...(bundled ? [join(bundled, folder)] : []), join(userRoot, folder)],
+        userDir: join(userRoot, folder),
+    };
+}
+/** Where the engine would find this template file, or null. */
+export function findInstalledTemplate(info, file) {
+    for (const dir of info.searchDirs) {
+        const path = join(dir, file);
+        if (existsSync(path))
+            return path;
+    }
+    return null;
+}
+/** Template file the engine needs for a download export (export plugins' template names). */
+export function templateFileFor(target, debug) {
+    if (target === "web")
+        return `web_summer_jspi_${debug ? "debug" : "release"}.zip`;
+    if (target === "macos")
+        return "macos.zip";
+    return `windows_${debug ? "debug" : "release"}_x86_64.exe`;
+}
+export function templatesBaseUrl(env = process.env) {
+    return (env[TEMPLATES_URL_ENV]?.trim() || DEFAULT_TEMPLATES_URL).replace(/\/+$/, "");
+}
+function notPublished(summerVersion, url) {
+    return new BuildToolError("templates_not_published", `Summer has not published export templates for Summer ${summerVersion} (${url}).`, "Recovery: store builds for iOS, Android, macOS and Windows need no template (summer_export_game with format bundle). " +
+        "For web or native downloads use the Summer Engine Mac or Windows app, which bundles them, or update Summer Engine and retry.", 404);
+}
+function parseManifest(raw, url) {
+    const bad = (why) => new BuildToolError("templates_manifest_invalid", `The templates manifest at ${url} is not valid: ${why}.`, "Recovery: retry later; report it if it persists.");
+    const value = raw;
+    if (!value || value.schema !== TEMPLATES_MANIFEST_SCHEMA)
+        throw bad(`schema is not ${TEMPLATES_MANIFEST_SCHEMA}`);
+    if (typeof value.summerVersion !== "string" || typeof value.godotVersion !== "string" || !Array.isArray(value.templates)) {
+        throw bad("summerVersion, godotVersion or templates is missing");
+    }
+    const templates = value.templates.map((item, index) => {
+        if (!TEMPLATE_PLATFORMS.includes(item?.platform) ||
+            typeof item.file !== "string" ||
+            !SAFE_FILE.test(item.file) ||
+            typeof item.path !== "string" ||
+            item.path.split("/").some((part) => !part || part === "." || part === "..") ||
+            typeof item.sha256 !== "string" ||
+            !SHA256.test(item.sha256) ||
+            !Number.isSafeInteger(item.size) ||
+            item.size <= 0 ||
+            typeof item.debug !== "boolean" ||
+            !(item.mono === null || typeof item.mono === "boolean")) {
+            throw bad(`templates[${index}] is malformed`);
+        }
+        return { platform: item.platform, file: item.file, path: item.path, sha256: item.sha256, size: item.size, debug: item.debug, mono: item.mono };
+    });
+    return { schema: TEMPLATES_MANIFEST_SCHEMA, summerVersion: value.summerVersion, godotVersion: value.godotVersion, templates };
+}
+export async function fetchTemplatesManifest(summerVersion, overrides = {}) {
+    const deps = { ...defaultDependencies(), ...overrides };
+    const url = `${templatesBaseUrl(deps.env)}/${encodeURIComponent(summerVersion)}/manifest.json`;
+    let response;
+    try {
+        response = await deps.fetch(url, { headers: { accept: "application/json" } });
+    }
+    catch (error) {
+        throw new BuildToolError("templates_unreachable", `Could not reach ${url}: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: check the network and retry.");
+    }
+    if (response.status === 404 || response.status === 403)
+        throw notPublished(summerVersion, url);
+    if (!response.ok) {
+        throw new BuildToolError("templates_unreachable", `${url} answered ${response.status}.`, "Recovery: retry later.", response.status);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = null;
+    }
+    return { manifest: parseManifest(body, url), url };
+}
+function servesFolder(entry, mono) {
+    return entry.mono === null || entry.mono === mono;
+}
+function wantedPlatforms(platforms) {
+    const list = platforms?.length ? platforms : ["web"];
+    const unknown = list.filter((item) => !TEMPLATE_PLATFORMS.includes(item));
+    if (unknown.length) {
+        throw new BuildToolError("template_platform_unknown", `Unknown template platform ${unknown.join(", ")}.`, `Recovery: use ${TEMPLATE_PLATFORMS.join(", ")}.`);
+    }
+    return TEMPLATE_PLATFORMS.filter((item) => list.includes(item));
+}
+function needVersion(info) {
+    if (info.summerVersion)
+        return info.summerVersion;
+    throw new BuildToolError("summer_version_unknown", "This tool cannot read the installed Summer version on this system.", "Recovery: pass summerVersion (shown in Summer Engine, Help > About, e.g. 0.7.1).");
+}
+async function download(deps, url, entry, target) {
+    let response;
+    try {
+        response = await deps.fetch(url);
+    }
+    catch (error) {
+        throw new BuildToolError("templates_unreachable", `Could not download ${url}: ${error instanceof Error ? error.message : String(error)}.`, "Recovery: retry.");
+    }
+    if (!response.ok || !response.body) {
+        throw new BuildToolError("templates_unreachable", `${url} answered ${response.status}.`, "Recovery: retry later.", response.status);
+    }
+    await mkdir(dirname(target), { recursive: true });
+    const part = `${target}.part`;
+    const hash = createHash("sha256");
+    let size = 0;
+    try {
+        await pipeline(Readable.fromWeb(response.body), async function* (source) {
+            for await (const chunk of source) {
+                hash.update(chunk);
+                size += chunk.length;
+                yield chunk;
+            }
+        }, createWriteStream(part));
+        const sha256 = `sha256:${hash.digest("hex")}`;
+        if (sha256 !== entry.sha256 || size !== entry.size) {
+            throw new BuildToolError("template_checksum_mismatch", `${entry.file} did not match the manifest (got ${sha256}, ${size} bytes).`, "Recovery: retry; nothing was installed.");
+        }
+        await rename(part, target);
+    }
+    finally {
+        await rm(part, { force: true });
+    }
+}
+export async function exportTemplates(input, overrides = {}) {
+    const deps = { ...defaultDependencies(), ...overrides };
+    const info = await engineTemplateInfo(deps, input.summerVersion);
+    const installedFiles = () => info.searchDirs.flatMap((dir) => existsSync(dir) ? readdirSync(dir).filter((name) => !name.endsWith(".part")).map((file) => ({ file, dir })) : []);
+    const engine = { engine: info.engine, folder: info.folder, summerVersion: info.summerVersion, searchDirs: info.searchDirs };
+    if (input.action === "list") {
+        let available = null;
+        let availability;
+        if (info.summerVersion) {
+            try {
+                const { manifest, url } = await fetchTemplatesManifest(info.summerVersion, deps);
+                available = manifest.templates
+                    .filter((entry) => servesFolder(entry, info.mono))
+                    .map((entry) => ({ ...entry, installed: findInstalledTemplate(info, entry.file) !== null }));
+                availability = url;
+            }
+            catch (error) {
+                if (!(error instanceof BuildToolError))
+                    throw error;
+                availability = `${error.code}: ${error.message.replace(` ${error.recovery}`, "")}`;
+            }
+        }
+        else {
+            availability = "summer_version_unknown: pass summerVersion to see what Summer publishes.";
+        }
+        return {
+            ok: true,
+            ...engine,
+            installed: installedFiles(),
+            available,
+            availability,
+            note: "Store builds (summer_export_game, format bundle) need no template. Web and native downloads need web_summer_jspi_release.zip, macos.zip or windows_release_x86_64.exe.",
+        };
+    }
+    const platforms = wantedPlatforms(input.platforms);
+    const summerVersion = needVersion(info);
+    const { manifest, url } = await fetchTemplatesManifest(summerVersion, deps);
+    const godotFolder = info.folder.replace(/\.mono$/, "");
+    if (manifest.godotVersion !== godotFolder) {
+        throw new BuildToolError("templates_version_mismatch", `Summer ${summerVersion} templates are for Godot base ${manifest.godotVersion}, but this engine reads ${info.folder}.`, "Recovery: pass the summerVersion of the installed Summer Engine (Help > About), or update Summer Engine.");
+    }
+    const entries = manifest.templates.filter((entry) => platforms.includes(entry.platform) && (input.includeDebug || !entry.debug) && servesFolder(entry, info.mono));
+    const missing = platforms.filter((item) => !entries.some((entry) => entry.platform === item));
+    if (missing.length) {
+        throw new BuildToolError("template_not_published", `Summer ${summerVersion} publishes no ${missing.join(", ")} template${info.mono ? " for the .NET editor" : ""}.`, `Recovery: install from ${manifest.templates.map((entry) => entry.platform).filter((v, i, a) => a.indexOf(v) === i).join(", ") || "nothing yet"}.`);
+    }
+    const base = url.slice(0, url.lastIndexOf("/") + 1);
+    const results = [];
+    for (const entry of entries) {
+        const target = join(info.userDir, entry.file);
+        if (existsSync(target) && (await hashFile(target)).sha256 === entry.sha256) {
+            results.push({ file: entry.file, path: target, status: "already_installed" });
+            continue;
+        }
+        await download(deps, base + entry.path.split("/").map(encodeURIComponent).join("/"), entry, target);
+        results.push({ file: entry.file, path: target, status: "installed" });
+    }
+    return {
+        ok: true,
+        ...engine,
+        manifest: url,
+        templates: results,
+        next: "Export with summer_export_game (format download) for web, macos or windows.",
+    };
+}

package/dist/core/capabilities/image-generation.d.ts

@@ -6,19 +6,28 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     style: z.ZodDefault<z.ZodString>;
     referenceImageUrl: z.ZodOptional<z.ZodString>;
     removeBackground: z.ZodOptional<z.ZodBoolean>;
+    aspectRatio: z.ZodOptional<z.ZodEnum<["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9"]>>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
     model: string;
     style: string;
+    width?: number | undefined;
+    height?: number | undefined;
     options?: Record<string, any> | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
+    aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }, {
     prompt: string;
+    width?: number | undefined;
+    height?: number | undefined;
     options?: Record<string, any> | undefined;
     model?: string | undefined;
     style?: string | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
+    aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }>;

package/dist/core/capabilities/image-generation.js

@@ -15,8 +15,26 @@ export const imageGenerationArgsSchema = z.object({
         .optional()
         .describe("Source image URL for img2img / edit mode. The prompt describes how to transform this image."),
     removeBackground: z.boolean().optional().describe("Remove the background server-side and return an alpha PNG for sprites, icons, or isolated objects."),
+    aspectRatio: z
+        .enum(["1:1", "16:9", "9:16", "4:3", "3:4", "3:2", "2:3", "5:4", "4:5", "21:9"])
+        .optional()
+        .describe("Aspect ratio of the output (default 1:1). The result reports the real width and height."),
+    width: z
+        .number()
+        .int()
+        .min(64)
+        .max(4096)
+        .optional()
+        .describe("Smallest output width in pixels; pass with height. 1920 with height 1080 for store key art, 1080 with 1920 for a tall cover."),
+    height: z
+        .number()
+        .int()
+        .min(64)
+        .max(4096)
+        .optional()
+        .describe("Smallest output height in pixels; pass with width."),
     options: z
         .record(z.any())
         .optional()
-        .describe("Provider-specific params (guidance_scale, seed, image_size, negative_prompt, etc.)"),
+        .describe("Extra model params (seed, negative_prompt, ...). The result lists any it did not use in ignoredOptions."),
 });