summer-engine 1.5.0 → 2.0.0

package/dist/commands/create.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join, resolve } from "path";
+import { fetchRemoteTemplates, cloneTemplate, matchTemplate } from "../lib/remote-templates.js";
 const BUILTIN_TEMPLATES = [
     {
         name: "empty",
@@ -22,30 +23,67 @@ const BUILTIN_TEMPLATES = [
     },
 ];
 export const createCommand = new Command("create")
-    .description("Create a new Summer Engine project from a template")
-    .argument("<template>", `Template name (${BUILTIN_TEMPLATES.map((t) => t.name).join(", ")})`)
-    .argument("[name]", "Project directory name (defaults to template name)")
-    .action(async (templateName, projectName) => {
-    const template = BUILTIN_TEMPLATES.find((t) => t.name === templateName);
-    if (!template) {
-        console.error(`Unknown template: ${templateName}`);
-        console.log("\nAvailable templates:");
-        for (const t of BUILTIN_TEMPLATES) {
-            console.log(`  ${t.name.padEnd(12)} ${t.description}`);
-        }
-        console.log("\nMore templates coming soon at github.com/summerengine/templates");
-        process.exit(1);
-    }
+    .description("Create a new Summer Engine project. Built-in templates work offline; community templates clone from github.com/SummerEngine/template-*.")
+    .argument("<template>", `Template slug. Built-in: ${BUILTIN_TEMPLATES.map((t) => t.name).join(", ")}. Or any community slug — see "summer list templates".`)
+    .argument("[name]", "Project directory name (defaults to template slug)")
+    .option("--keep-git", "Keep the upstream .git directory after cloning a remote template (default: detach so you start fresh)")
+    .action(async (templateName, projectName, options) => {
+    const builtin = BUILTIN_TEMPLATES.find((t) => t.name === templateName);
     const dirName = projectName || templateName;
     const fullPath = resolve(dirName);
     if (existsSync(fullPath)) {
         console.error(`Directory already exists: ${fullPath}`);
         process.exit(1);
     }
-    console.log(`Creating project from '${templateName}' template...`);
-    mkdirSync(fullPath, { recursive: true });
-    template.generate(fullPath, dirName);
+    if (builtin) {
+        console.log(`Creating project from built-in '${templateName}' template...`);
+        mkdirSync(fullPath, { recursive: true });
+        builtin.generate(fullPath, dirName);
+        console.log(`\nProject created at ${fullPath}`);
+        console.log("\nNext steps:");
+        console.log(`  summer run ${dirName}`);
+        return;
+    }
+    // Fall back to remote template lookup
+    let remote;
+    try {
+        const all = await fetchRemoteTemplates();
+        remote = matchTemplate(templateName, all);
+        if (!remote) {
+            console.error(`No template matches '${templateName}'.\n`);
+            console.error("Built-in templates:");
+            for (const t of BUILTIN_TEMPLATES) {
+                console.error(`  ${t.name.padEnd(16)} ${t.description}`);
+            }
+            if (all.length > 0) {
+                console.error("\nCommunity templates from github.com/SummerEngine:");
+                for (const t of all.slice(0, 10)) {
+                    console.error(`  ${t.slug.padEnd(40)} ${t.description}`);
+                }
+                if (all.length > 10)
+                    console.error(`  ...and ${all.length - 10} more — run "summer list templates"`);
+            }
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Could not reach GitHub to look up community templates: ${err.message}`);
+        console.error("\nBuilt-in templates that work offline:");
+        for (const t of BUILTIN_TEMPLATES) {
+            console.error(`  ${t.name.padEnd(16)} ${t.description}`);
+        }
+        process.exit(1);
+    }
+    console.log(`Cloning community template '${remote.repo}' (${remote.url}) ...`);
+    try {
+        cloneTemplate(remote, { targetDir: fullPath, detach: !options.keepGit });
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exit(1);
+    }
     console.log(`\nProject created at ${fullPath}`);
+    console.log("Source: " + remote.url);
     console.log("\nNext steps:");
     console.log(`  summer run ${dirName}`);
 });

package/dist/commands/debug.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const debugCommand: Command;

package/dist/commands/debug.js

@@ -0,0 +1,127 @@
+import { Command } from "commander";
+import { withEngineClient } from "../lib/with-engine.js";
+import { outputResult, outputError, isJsonMode } from "../lib/format.js";
+export const debugCommand = new Command("debug").description("Debug and run commands (requires running engine)");
+debugCommand
+    .command("diagnostics")
+    .description("Quick overview of all errors and warnings from editor console and debugger")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.getDiagnostics());
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("play [scene]")
+    .description("Start running the game (optionally a specific scene)")
+    .action(async (scene, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.play(scene));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("stop")
+    .description("Stop the running game")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.stop());
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("console")
+    .description("Read recent messages from the editor Output panel")
+    .option("--max-lines <n>", "Max lines to return", "100")
+    .option("--filter <string>", "Only return lines containing this string")
+    .option("--type <type>", "Filter by type: error, warning, std, editor")
+    .action(async (opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const op = {
+            op: "GetConsoleOutput",
+            max_lines: parseInt(opts.maxLines, 10),
+        };
+        if (opts.filter)
+            op.filter = opts.filter;
+        if (opts.type)
+            op.type = opts.type;
+        const result = await withEngineClient((c) => c.executeOps([op]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("errors")
+    .description("Read runtime errors from the debugger")
+    .option("--max-errors <n>", "Max errors to return", "50")
+    .option("--stack", "Include stack traces")
+    .action(async (opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const op = {
+            op: "GetDebuggerErrors",
+            max_errors: parseInt(opts.maxErrors, 10),
+        };
+        if (opts.stack !== undefined)
+            op.include_stack = opts.stack;
+        const result = await withEngineClient((c) => c.executeOps([op]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("script-errors <path>")
+    .description("Check a GDScript file for parse/compile errors (e.g. res://scripts/player.gd)")
+    .action(async (path, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.getScriptErrors(path));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("clear")
+    .description("Clear the editor Output panel")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.executeOps([{ op: "ClearConsoleOutput" }]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+debugCommand
+    .command("running")
+    .description("Check if the game is currently running")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.executeOps([{ op: "IsGameRunning" }]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});

package/dist/commands/list.js

@@ -1,12 +1,13 @@
 import { Command } from "commander";
 import { readdirSync, existsSync } from "fs";
 import { join } from "path";
+import { fetchRemoteTemplates } from "../lib/remote-templates.js";
 export const listCommand = new Command("list")
     .description("List available templates or local projects")
     .argument("<what>", "'templates' or 'projects'")
     .action(async (what) => {
     if (what === "templates") {
-        listTemplates();
+        await listTemplates();
     }
     else if (what === "projects") {
         listProjects();
@@ -16,12 +17,30 @@ export const listCommand = new Command("list")
         process.exit(1);
     }
 });
-function listTemplates() {
-    console.log("Built-in Templates:\n");
+async function listTemplates() {
+    console.log("Built-in templates (no download required):\n");
     console.log("  empty        Empty 3D project with just a root node");
     console.log("  3d-basic     3D scene with camera, light, and floor");
-    console.log("\nCreate a project: summer create <template> [name]");
-    console.log("\nMore templates coming soon at github.com/summerengine/templates");
+    console.log("\nCommunity templates from github.com/SummerEngine:\n");
+    try {
+        const remote = await fetchRemoteTemplates();
+        if (remote.length === 0) {
+            console.log("  (none yet)");
+        }
+        else {
+            const padTo = Math.max(...remote.map((t) => t.slug.length), 16);
+            for (const t of remote) {
+                const desc = t.description || `(no description)  ${t.url}`;
+                console.log(`  ${t.slug.padEnd(padTo)}  ${desc}`);
+            }
+        }
+    }
+    catch (err) {
+        console.log(`  (could not reach GitHub: ${err.message})`);
+        console.log("  Built-ins above still work offline.");
+    }
+    console.log("\nCreate a project: summer create <name> [project-dir]");
+    console.log("Example:          summer create 3d-third-person-controller my-game");
 }
 function listProjects() {
     const cwd = process.cwd();

package/dist/commands/project.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const projectCommand: Command;

package/dist/commands/project.js

@@ -0,0 +1,170 @@
+import { Command } from "commander";
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { withEngineClient } from "../lib/with-engine.js";
+import { outputResult, outputError, parseValue, readJsonArg, isJsonMode, } from "../lib/format.js";
+async function readMainSceneFromProject(projectPath) {
+    if (!projectPath)
+        return null;
+    try {
+        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
+        const match = text.match(/run\/main_scene="([^"]+)"/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export const projectCommand = new Command("project").description("Project context and settings (requires running engine)");
+projectCommand
+    .command("context")
+    .description("Get project context: health, current scene, main scene, project path")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient(async (client) => {
+            const [health, projectState] = await Promise.all([
+                client.health(),
+                client.getProjectState(),
+            ]);
+            const healthObj = (health ?? {});
+            const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string"
+                ? healthObj.project_path
+                : undefined);
+            return {
+                health,
+                project: projectState,
+                mainScene,
+                guidance: mainScene
+                    ? "Use `summer scene open` with mainScene if no scene is open."
+                    : "Main scene not found in project.godot. Open a known scene path explicitly.",
+            };
+        });
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("open-main")
+    .description("Open the project's main scene from project.godot")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient(async (client) => {
+            const health = (await client.health());
+            const projectPath = typeof health.project_path === "string"
+                ? health.project_path
+                : undefined;
+            const mainScene = await readMainSceneFromProject(projectPath);
+            if (!mainScene) {
+                throw new Error("Could not resolve main_scene from project.godot. Run `summer project context` and open a scene explicitly.");
+            }
+            return client.executeOps([{ op: "OpenScene", path: mainScene }]);
+        });
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("setting <key> <value>")
+    .description('Set a project setting (e.g. summer project setting application/config/name "My Game")')
+    .action(async (key, value, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.executeOps([
+            { op: "ProjectSetting", key, value: parseValue(value) },
+        ]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("input-bind <name> <events>")
+    .description('Bind input events to an action (e.g. summer project input-bind jump \'[{"type":"key","key":"Space"}]\')')
+    .action(async (name, eventsJson, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const events = JSON.parse(eventsJson);
+        const result = await withEngineClient((c) => c.executeOps([
+            { op: "InputMapAddAction", name },
+            { op: "InputMapBind", name, events },
+        ]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("import <url>")
+    .description("Download a file from a URL and import into the project")
+    .option("--path <path>", "Target path in project (auto-inferred from URL if omitted)")
+    .action(async (url, opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const op = { op: "ImportFromUrl", url };
+        if (opts.path)
+            op.path = opts.path;
+        const result = await withEngineClient((c) => c.executeOps([op]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("import-batch <json>")
+    .description('Import multiple files. Pass JSON array of {url, path} or "-" for stdin')
+    .action(async (jsonArg, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const imports = (await readJsonArg(jsonArg));
+        const result = await withEngineClient((c) => c.executeOps([{ op: "ImportFromUrlBatch", imports }]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("playbook")
+    .description("Show the AI agent operating guide for Summer Engine")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    const playbook = {
+        startupChecklist: [
+            "Decide first: file edit or engine operation.",
+            "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+            "Call `summer project context` first.",
+            "If no scene is open, call `summer project open-main`.",
+            "Call `summer scene tree` before structural edits.",
+            "Call `summer scene save` after edits.",
+        ],
+        safeDefaults: [
+            "Never guess scene filenames (main.tscn/Main.tscn).",
+            "Do not route ordinary code edits through engine ops when direct file tools are available.",
+            "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
+            "Never write .tscn/.scn with file write tools; use scene commands.",
+        ],
+        preferredFlow: [
+            "summer project context",
+            "summer project open-main (if needed)",
+            "summer scene tree",
+            "edit via summer scene add / summer scene prop / summer scene rprop",
+            "summer scene save",
+            "summer debug diagnostics",
+        ],
+        recovery: [
+            "If you see 'no scene open': run summer project open-main.",
+            "If open fails: re-check mainScene from summer project context.",
+            "If save fails: verify scene is open and game is not running.",
+        ],
+    };
+    outputResult(playbook, fmt);
+});

package/dist/commands/scene.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const sceneCommand: Command;