phibelle-kit 1.0.32 → 1.0.33

package/dist/commands/init-scene.d.ts

@@ -1 +1 @@
-export declare function initSceneCommand(): void;
+export declare function initSceneCommand(): Promise<void>;

package/dist/commands/init-scene.js

@@ -1,16 +1,85 @@
 import chalk from "chalk";
-import { setupSceneDirectory, getInstallHint } from "../scene-setup/setup.js";
-export function initSceneCommand() {
-    const sceneDir = process.cwd();
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import readline from "node:readline";
+import { SCENE_FILE_NAME } from "../lib/constants.js";
+import { unpackageScene } from "../lib/scene/scene-packaging.js";
+import { setupSceneDirectory } from "../scene-setup/setup.js";
+import { MINIMAL_SCENE_JSON } from "../lib/minimal-scene.js";
+import { TEMPLATE_IDS } from "../lib/template-ids.js";
+function askQuestion(rl, prompt) {
+    return new Promise((resolve) => {
+        rl.question(prompt, resolve);
+    });
+}
+function sanitizeProjectName(input) {
+    return input
+        .trim()
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, "-")
+        .replace(/\s+/g, "-")
+        .replace(/\.+$/g, "")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export async function initSceneCommand() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const parentDir = process.cwd();
     console.log();
-    console.log(chalk.bold.cyan("  Initializing scene..."));
-    console.log(chalk.gray(`  Dir: ${sceneDir}`));
+    console.log(chalk.bold.cyan("  Initialize a new Phibelle scene project"));
+    console.log(chalk.gray(`  Parent dir: ${parentDir}`));
     console.log();
-    const { shouldPromptInstall } = setupSceneDirectory(sceneDir);
-    console.log(chalk.green("  ✓ Created package.json, tsconfig.json, global.d.ts, AGENTS.md, CLAUDE.md, .gitignore"));
-    if (shouldPromptInstall) {
-        console.log(chalk.yellow("  Install dependencies: ") + chalk.cyan(getInstallHint(sceneDir)));
-    }
-    console.log(chalk.gray("  Next: open a scene in the app, then run ") + chalk.cyan("pnpm run watch") + chalk.gray(" to sync."));
+    const projectName = await promptProjectName(rl);
+    const templateId = await promptTemplateId(rl);
+    const safeDirName = sanitizeProjectName(projectName) || "phibelle-scene";
+    const sceneDir = path.join(parentDir, safeDirName);
+    await ensureDirectoryDoesNotExist(sceneDir);
+    await fs.mkdir(sceneDir, { recursive: false });
+    setupSceneDirectory(sceneDir);
+    await fs.writeFile(path.join(sceneDir, SCENE_FILE_NAME), MINIMAL_SCENE_JSON, "utf8");
+    await unpackageScene(MINIMAL_SCENE_JSON, sceneDir, "template", templateId);
+    console.log(chalk.green("  ✓ Project initialized"));
+    console.log(chalk.gray(`  Directory: ${sceneDir}`));
+    console.log(chalk.yellow("  Next steps:"));
+    console.log(chalk.cyan(`    1. cd "${safeDirName}"`));
+    console.log(chalk.cyan(`    2. npm install`));
+    console.log(chalk.cyan(`    3. npm run watch`));
+    console.log(chalk.gray(`  Then open the editor URL shown by watch and accept the template scene to sync.`));
     console.log();
+    rl.close();
+    process.exit(0);
+}
+async function promptProjectName(rl) {
+    while (true) {
+        const answer = await askQuestion(rl, chalk.cyan("  Project name: "));
+        const trimmed = answer.trim();
+        if (trimmed)
+            return trimmed;
+        console.log(chalk.yellow("  Please enter a non-empty project name."));
+    }
+}
+async function promptTemplateId(rl) {
+    console.log(chalk.cyan("  Template:"));
+    TEMPLATE_IDS.forEach((id, i) => {
+        console.log(chalk.gray(`    ${i + 1}. ${id}`));
+    });
+    while (true) {
+        const answer = (await askQuestion(rl, chalk.cyan("  Choose template [1-" + TEMPLATE_IDS.length + "]: "))).trim();
+        const num = parseInt(answer, 10);
+        if (num >= 1 && num <= TEMPLATE_IDS.length) {
+            return TEMPLATE_IDS[num - 1];
+        }
+        if (TEMPLATE_IDS.includes(answer)) {
+            return answer;
+        }
+        console.log(chalk.yellow(`  Please enter 1-${TEMPLATE_IDS.length} or a template ID.`));
+    }
+}
+async function ensureDirectoryDoesNotExist(sceneDir) {
+    try {
+        await fs.access(sceneDir);
+    }
+    catch {
+        return;
+    }
+    throw new Error(`Target folder already exists: ${sceneDir}. Choose a different project name.`);
 }

package/dist/commands/watch-scene.js

@@ -4,20 +4,19 @@ import * as fs from "node:fs";
 import readline from "node:readline";
 import { WebSocketServer } from "ws";
 import { WS_PORT, SCENE_SYNC_TYPE, SCENE_FILE_NAME } from "../lib/constants.js";
-import { getRequiredManifestSceneId } from "../lib/manifest.js";
+import { getRequiredManifestIds } from "../lib/manifest.js";
 import { unpackageScene, parseSceneJson, packageSceneFromFilesystem } from "../lib/scene/scene-packaging.js";
 import { createScriptWatcher } from "../lib/scene/script-watcher.js";
 import { toErrorMessage } from "../lib/utils.js";
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 export const BASE_URL = process.env.NODE_ENV === "development" ? "http://localhost:3131" : "https://phibelle.studio";
 export async function watchSceneCommand() {
     const sceneDir = process.cwd();
-    const manifestSceneId = getRequiredManifestSceneId(sceneDir);
+    const { sceneId, templateId } = getRequiredManifestIds(sceneDir);
     let lastPrintedEditorLink = null;
     console.log();
     console.log(chalk.bold.cyan("  Watching for scene sync (WebSocket)"));
     console.log(chalk.gray(`  Dir: ${sceneDir}`));
-    lastPrintedEditorLink = printEditorLink(manifestSceneId, lastPrintedEditorLink);
+    lastPrintedEditorLink = printEditorLink(sceneId, templateId, lastPrintedEditorLink);
     console.log(chalk.yellow("  Waiting for connection from local development server..."));
     console.log();
     console.log(chalk.gray("  Press Ctrl+C to stop"));
@@ -70,11 +69,13 @@ export async function watchSceneCommand() {
                     startWatcher();
                     return;
                 }
-                const choice = await promptForInitialSyncChoice().catch((error) => {
-                    console.log(chalk.red("  ✖ " + toErrorMessage(error)));
-                    ws.close();
-                    return null;
-                });
+                const choice = sceneId === "template"
+                    ? "push-local"
+                    : await promptForInitialSyncChoice().catch((error) => {
+                        console.log(chalk.red("  ✖ " + toErrorMessage(error)));
+                        ws.close();
+                        return null;
+                    });
                 if (!choice || currentClient !== ws)
                     return;
                 if (choice === "push-local") {
@@ -96,11 +97,13 @@ export async function watchSceneCommand() {
             latestSceneJson = incoming.sceneData;
             const scenePath = path.join(sceneDir, SCENE_FILE_NAME);
             fs.writeFileSync(scenePath, incoming.sceneData, "utf8");
+            const resolvedTemplateId = incoming.templateId ??
+                (incoming.sceneId === "template" ? getRequiredManifestIds(sceneDir).templateId : undefined);
             try {
-                await unpackageScene(incoming.sceneData, sceneDir, incoming.sceneId);
+                await unpackageScene(incoming.sceneData, sceneDir, incoming.sceneId, resolvedTemplateId);
                 console.log(chalk.green("  ✓ Synced scene from app"));
-                const updatedManifestSceneId = getRequiredManifestSceneId(sceneDir);
-                lastPrintedEditorLink = printEditorLink(updatedManifestSceneId, lastPrintedEditorLink);
+                const updatedIds = getRequiredManifestIds(sceneDir);
+                lastPrintedEditorLink = printEditorLink(updatedIds.sceneId, updatedIds.templateId, lastPrintedEditorLink);
             }
             catch (e) {
                 console.log(chalk.yellow("  ⚠ Unpackage: " + toErrorMessage(e)));
@@ -117,7 +120,6 @@ export async function watchSceneCommand() {
         scriptWatcher?.close();
         scriptWatcher = null;
         wss.close();
-        rl.close();
         console.log(chalk.gray("  Goodbye"));
         console.log();
         process.exit(0);
@@ -128,7 +130,11 @@ function parseIncomingSceneMessage(raw) {
     try {
         const parsed = JSON.parse(raw);
         if (isSceneSyncMessage(parsed)) {
-            return { sceneData: parsed.sceneData, sceneId: parsed.sceneId?.trim() || undefined };
+            return {
+                sceneData: parsed.sceneData,
+                sceneId: parsed.sceneId?.trim() || undefined,
+                templateId: parsed.templateId?.trim() || undefined,
+            };
         }
     }
     catch {
@@ -142,10 +148,14 @@ function isSceneSyncMessage(value) {
     const obj = value;
     return (obj.type === SCENE_SYNC_TYPE &&
         typeof obj.sceneData === "string" &&
-        (obj.sceneId === undefined || typeof obj.sceneId === "string"));
+        (obj.sceneId === undefined || typeof obj.sceneId === "string") &&
+        (obj.templateId === undefined || typeof obj.templateId === "string"));
 }
-function printEditorLink(sceneId, lastPrintedLink) {
-    const editorUrl = `${BASE_URL}/editor?sceneId=${encodeURIComponent(sceneId)}&wsEnabled=true`;
+function printEditorLink(sceneId, templateId, lastPrintedLink) {
+    let editorUrl = `${BASE_URL}/editor?sceneId=${encodeURIComponent(sceneId)}&wsEnabled=true`;
+    if (sceneId === "template" && templateId) {
+        editorUrl += `&id=${encodeURIComponent(templateId)}`;
+    }
     if (editorUrl === lastPrintedLink)
         return lastPrintedLink;
     console.log(chalk.cyan(`  Editor: ${editorUrl}`));
@@ -167,19 +177,25 @@ async function packageAndPersistLocalScene(sceneDir, sceneJson) {
     return packagedSceneJson;
 }
 async function promptForInitialSyncChoice() {
-    console.log(chalk.yellow("  Choose initial sync direction:"));
-    console.log(chalk.cyan("    [p] Push local scene to the web app"));
-    console.log(chalk.cyan("    [a] Accept the current web app scene"));
-    while (true) {
-        const answer = (await askQuestion("  Initial sync [p/a]: ")).trim().toLowerCase();
-        if (answer === "p" || answer === "push" || answer === "local")
-            return "push-local";
-        if (answer === "a" || answer === "accept" || answer === "web" || answer === "app")
-            return "accept-web";
-        console.log(chalk.yellow("  Please enter 'p' to push local or 'a' to accept the web app scene."));
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log(chalk.yellow("  Choose initial sync direction:"));
+        console.log(chalk.cyan("    [p] Push local scene to the web app"));
+        console.log(chalk.cyan("    [a] Accept the current web app scene"));
+        while (true) {
+            const answer = (await askQuestion(rl, "  Initial sync [p/a]: ")).trim().toLowerCase();
+            if (answer === "p" || answer === "push" || answer === "local")
+                return "push-local";
+            if (answer === "a" || answer === "accept" || answer === "web" || answer === "app")
+                return "accept-web";
+            console.log(chalk.yellow("  Please enter 'p' to push local or 'a' to accept the web app scene."));
+        }
+    }
+    finally {
+        rl.close();
     }
 }
-function askQuestion(prompt) {
+function askQuestion(rl, prompt) {
     return new Promise((resolve) => {
         rl.question(prompt, resolve);
     });

package/dist/index.js

@@ -2,9 +2,14 @@
 import chalk from "chalk";
 import { watchSceneCommand } from "./commands/watch-scene.js";
 import { cloneSceneCommand } from "./commands/clone-scene.js";
-const USAGE = "  Usage: phibelle-kit watch | phibelle-kit clone";
+import { initSceneCommand } from "./commands/init-scene.js";
+const USAGE = "  Usage: phibelle-kit init | phibelle-kit watch | phibelle-kit clone";
 async function main() {
     const command = process.argv[2];
+    if (command === "init") {
+        await initSceneCommand();
+        return;
+    }
     if (command === "watch") {
         await watchSceneCommand();
         return;

package/dist/lib/manifest.d.ts

@@ -1,5 +1,12 @@
+export type ManifestIds = {
+    sceneId: string;
+    /** Only present when sceneId === "template" */
+    templateId?: string;
+};
 /**
- * Read manifest.json from sceneDir and return the required sceneId.
+ * Read manifest.json from sceneDir and return sceneId and optional templateId.
  * Throws with user-facing errors if manifest is missing, unreadable, invalid JSON, or missing sceneId.
  */
+export declare function getRequiredManifestIds(sceneDir: string): ManifestIds;
+/** @deprecated Use getRequiredManifestIds instead */
 export declare function getRequiredManifestSceneId(sceneDir: string): string;

package/dist/lib/manifest.js

@@ -2,13 +2,13 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { MANIFEST_FILE_NAME } from "./constants.js";
 /**
- * Read manifest.json from sceneDir and return the required sceneId.
+ * Read manifest.json from sceneDir and return sceneId and optional templateId.
  * Throws with user-facing errors if manifest is missing, unreadable, invalid JSON, or missing sceneId.
  */
-export function getRequiredManifestSceneId(sceneDir) {
+export function getRequiredManifestIds(sceneDir) {
     const manifestPath = path.join(sceneDir, MANIFEST_FILE_NAME);
     if (!fs.existsSync(manifestPath)) {
-        throw new Error(`Missing ${MANIFEST_FILE_NAME} in ${sceneDir}. Run "phibelle-kit clone" first or watch from a cloned scene folder.`);
+        throw new Error(`Missing ${MANIFEST_FILE_NAME} in ${sceneDir}. Run "phibelle-kit init" or "phibelle-kit clone" first.`);
     }
     let manifestRaw;
     try {
@@ -27,5 +27,14 @@ export function getRequiredManifestSceneId(sceneDir) {
     if (typeof manifest.sceneId !== "string" || !manifest.sceneId.trim()) {
         throw new Error(`Invalid ${MANIFEST_FILE_NAME}: missing required "sceneId".`);
     }
-    return manifest.sceneId.trim();
+    const sceneId = manifest.sceneId.trim();
+    const result = { sceneId };
+    if (sceneId === "template" && typeof manifest.templateId === "string" && manifest.templateId.trim()) {
+        result.templateId = manifest.templateId.trim();
+    }
+    return result;
+}
+/** @deprecated Use getRequiredManifestIds instead */
+export function getRequiredManifestSceneId(sceneDir) {
+    return getRequiredManifestIds(sceneDir).sceneId;
 }

package/dist/lib/minimal-scene.d.ts

@@ -0,0 +1,2 @@
+/** Minimal valid scene JSON for init (empty entities; watch will sync from editor). */
+export declare const MINIMAL_SCENE_JSON: string;

package/dist/lib/minimal-scene.js

@@ -0,0 +1,28 @@
+/** Minimal valid scene JSON for init (empty entities; watch will sync from editor). */
+export const MINIMAL_SCENE_JSON = JSON.stringify({
+    entityStore: {
+        _currId: 0,
+        rootEntities: [],
+        entities: {},
+        rootRenderVersion: 0,
+        lastRenderedVersion: 0,
+        selectedEntityIds: [],
+    },
+    editorCameraStore: {
+        orthographic: false,
+        cameraPosition: [0, 0, 0],
+        cameraRotation: [0, 0, 0, "XYZ"],
+        targetPosition: [0, 0, 0],
+    },
+    errorStore: {},
+    sceneScriptStore: {
+        sceneScript: "// Empty scene script. Run phibelle-kit watch to start the scene.\n",
+        sceneProperties: [],
+        lastModifiedSceneScript: 0,
+    },
+    engineModeStore: {
+        engineMode: "edit",
+        transformMode: "translate",
+    },
+    version: "1",
+});

package/dist/lib/scene/scene-packaging.d.ts

@@ -12,6 +12,6 @@ export declare function entityNameToSlug(name: string): string;
 /** Convert slug to display name: "main-enemy" -> "Main Enemy". */
 export declare function slugToEntityName(slug: string): string;
 /** Unpackage scene JSON to filesystem. No DB; accepts full scene JSON string. */
-export declare function unpackageScene(sceneJson: string, sceneDir: string, sceneId?: string): Promise<void>;
+export declare function unpackageScene(sceneJson: string, sceneDir: string, sceneId?: string, templateId?: string): Promise<void>;
 export declare function patchSceneFromFile(sceneJson: string, sceneDir: string, _relativePath: string, _eventType: "change" | "add" | "unlink" | "addDir" | "unlinkDir"): Promise<string>;
 export declare function packageSceneFromFilesystem(sceneJson: string, sceneDir: string): Promise<string>;

package/dist/lib/scene/scene-packaging.js

@@ -40,7 +40,7 @@ export function slugToEntityName(slug) {
         .join(" ");
 }
 /** Unpackage scene JSON to filesystem. No DB; accepts full scene JSON string. */
-export async function unpackageScene(sceneJson, sceneDir, sceneId) {
+export async function unpackageScene(sceneJson, sceneDir, sceneId, templateId) {
     const parsed = parseSceneJson(sceneJson);
     const parsedSceneId = typeof parsed._id === "string"
         ? parsed._id
@@ -50,8 +50,12 @@ export async function unpackageScene(sceneJson, sceneDir, sceneId) {
     await fs.mkdir(appDir, { recursive: true });
     await cleanupKnownEntityDirectories(appDir, previousManifest);
     await cleanupLegacySceneFiles(appDir);
+    const resolvedSceneId = sceneId?.trim() || parsedSceneId;
     const manifest = {
-        sceneId: sceneId?.trim() || parsedSceneId,
+        sceneId: resolvedSceneId,
+        ...(resolvedSceneId === "template" && templateId?.trim()
+            ? { templateId: templateId.trim() }
+            : {}),
         sceneScript: SCENE_SCRIPT_FILE,
         sceneProperties: SCENE_PROPERTIES_FILE,
         entities: {},
@@ -136,8 +140,12 @@ async function readManifest(sceneDir) {
     try {
         const manifestRaw = await fs.readFile(path.join(sceneDir, MANIFEST_FILE_NAME), "utf8");
         const parsed = JSON.parse(manifestRaw);
+        const sceneId = typeof parsed.sceneId === "string" ? parsed.sceneId : "";
         return {
-            sceneId: typeof parsed.sceneId === "string" ? parsed.sceneId : "",
+            sceneId,
+            ...(sceneId === "template" && typeof parsed.templateId === "string" && parsed.templateId.trim()
+                ? { templateId: parsed.templateId.trim() }
+                : {}),
             sceneScript: typeof parsed.sceneScript === "string" ? parsed.sceneScript : SCENE_SCRIPT_FILE,
             sceneProperties: typeof parsed.sceneProperties === "string" ? parsed.sceneProperties : SCENE_PROPERTIES_FILE,
             entities: parsed.entities ?? {},

package/dist/lib/template-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Template IDs - must match src/lib/templates/template-ids.ts in the main app.
+ * Used by init command for template selection.
+ */
+export declare const TEMPLATE_IDS: readonly ["basic-cube", "maze", "blocks-destroyer"];
+export type TemplateId = (typeof TEMPLATE_IDS)[number];

package/dist/lib/template-ids.js

@@ -0,0 +1,9 @@
+/**
+ * Template IDs - must match src/lib/templates/template-ids.ts in the main app.
+ * Used by init command for template selection.
+ */
+export const TEMPLATE_IDS = [
+    "basic-cube",
+    "maze",
+    "blocks-destroyer",
+];

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "phibelle-kit",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "description": "CLI tool for interacting with the Phibelle engine",
   "type": "module",
   "bin": {
-    "phibelle-kit": "./dist/index.js"
+    "phibelle-kit": "./dist/index.js",
+    "create-phibelle": "./dist/index.js init"
   },
   "scripts": {
     "build": "tsc",