phibelle-kit 1.0.31 → 1.0.33

package/dist/commands/clone-scene.js

@@ -4,11 +4,10 @@ import * as fs from "node:fs/promises";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { WebSocketServer } from "ws";
+import { WS_PORT, CLONE_REQUEST_TYPE, CLONE_RESPONSE_TYPE, SCENE_FILE_NAME, } from "../lib/constants.js";
+import { getExecErrorText } from "../lib/utils.js";
 import { parseSceneJson, unpackageScene } from "../lib/scene/scene-packaging.js";
 import { setupSceneDirectory } from "../scene-setup/setup.js";
-const WS_PORT = 31113;
-const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
-const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";
 const CLONE_TIMEOUT_MS = 30_000;
 const INITIAL_COMMIT_MESSAGE = "Initial scene clone from Phibelle";
 const execFileAsync = promisify(execFile);
@@ -26,7 +25,7 @@ export async function cloneSceneCommand() {
     await ensureDirectoryDoesNotExist(sceneDir);
     await fs.mkdir(sceneDir, { recursive: false });
     setupSceneDirectory(sceneDir);
-    await fs.writeFile(path.join(sceneDir, "scene.phibelle"), payload.sceneData, "utf8");
+    await fs.writeFile(path.join(sceneDir, SCENE_FILE_NAME), payload.sceneData, "utf8");
     await unpackageScene(payload.sceneData, sceneDir, payload.sceneId);
     await initializeGitRepository(sceneDir);
     console.log(chalk.green("  ✓ Scene cloned successfully"));
@@ -148,7 +147,7 @@ async function initializeGitRepository(sceneDir) {
     }
     catch (error) {
         console.log(chalk.yellow("  ! Git initialization or first commit was skipped"));
-        const details = getErrorText(error);
+        const details = getExecErrorText(error);
         if (details) {
             console.log(chalk.gray(`    ${details}`));
         }
@@ -158,12 +157,3 @@ async function initializeGitRepository(sceneDir) {
 async function runGit(args, cwd) {
     await execFileAsync("git", args, { cwd });
 }
-function getErrorText(error) {
-    if (!error || typeof error !== "object")
-        return "";
-    const err = error;
-    const stderr = err.stderr?.trim();
-    if (stderr)
-        return stderr.split("\n").pop() ?? stderr;
-    return err.message?.trim() ?? "";
-}

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

@@ -1,25 +1,22 @@
 import chalk from "chalk";
-import * as path from "path";
-import * as fs from "fs";
+import * as path from "node:path";
+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 { 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";
-import readline from "readline";
-const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-const WS_PORT = 31113;
-const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
-const SCENE_FILE_NAME = "scene.phibelle";
-const MANIFEST_FILE_NAME = "manifest.json";
 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"));
@@ -72,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") {
@@ -98,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)));
@@ -119,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);
@@ -130,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 {
@@ -144,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}`));
@@ -169,44 +177,26 @@ 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);
     });
 }
-function getRequiredManifestSceneId(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.`);
-    }
-    let manifestRaw;
-    try {
-        manifestRaw = fs.readFileSync(manifestPath, "utf8");
-    }
-    catch {
-        throw new Error(`Failed to read ${MANIFEST_FILE_NAME} in ${sceneDir}.`);
-    }
-    let manifest;
-    try {
-        manifest = JSON.parse(manifestRaw);
-    }
-    catch {
-        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: expected valid JSON.`);
-    }
-    if (typeof manifest.sceneId !== "string" || !manifest.sceneId.trim()) {
-        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: missing required "sceneId".`);
-    }
-    return manifest.sceneId.trim();
-}

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/constants.d.ts

@@ -0,0 +1,12 @@
+/** WebSocket port for phibelle-kit CLI ↔ web app communication. Must match app's use-cli-websocket.ts */
+export declare const WS_PORT = 31113;
+/** Scene JSON file in cloned scene directory */
+export declare const SCENE_FILE_NAME = "scene.phibelle";
+/** Manifest file mapping entity IDs to filesystem paths */
+export declare const MANIFEST_FILE_NAME = "manifest.json";
+/** Message type for scene sync over WebSocket */
+export declare const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
+/** Message type for clone request from kit to app */
+export declare const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
+/** Message type for clone response from app to kit */
+export declare const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";

package/dist/lib/constants.js

@@ -0,0 +1,12 @@
+/** WebSocket port for phibelle-kit CLI ↔ web app communication. Must match app's use-cli-websocket.ts */
+export const WS_PORT = 31113;
+/** Scene JSON file in cloned scene directory */
+export const SCENE_FILE_NAME = "scene.phibelle";
+/** Manifest file mapping entity IDs to filesystem paths */
+export const MANIFEST_FILE_NAME = "manifest.json";
+/** Message type for scene sync over WebSocket */
+export const SCENE_SYNC_TYPE = "phibelle-kit-scene-sync";
+/** Message type for clone request from kit to app */
+export const CLONE_REQUEST_TYPE = "phibelle-kit-clone-request";
+/** Message type for clone response from app to kit */
+export const CLONE_RESPONSE_TYPE = "phibelle-kit-clone-response";

package/dist/lib/manifest.d.ts

@@ -0,0 +1,12 @@
+export type ManifestIds = {
+    sceneId: string;
+    /** Only present when sceneId === "template" */
+    templateId?: string;
+};
+/**
+ * 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

@@ -0,0 +1,40 @@
+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 sceneId and optional templateId.
+ * Throws with user-facing errors if manifest is missing, unreadable, invalid JSON, or missing sceneId.
+ */
+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 init" or "phibelle-kit clone" first.`);
+    }
+    let manifestRaw;
+    try {
+        manifestRaw = fs.readFileSync(manifestPath, "utf8");
+    }
+    catch {
+        throw new Error(`Failed to read ${MANIFEST_FILE_NAME} in ${sceneDir}.`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch {
+        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: expected valid JSON.`);
+    }
+    if (typeof manifest.sceneId !== "string" || !manifest.sceneId.trim()) {
+        throw new Error(`Invalid ${MANIFEST_FILE_NAME}: missing required "sceneId".`);
+    }
+    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/file-system.d.ts

@@ -1,5 +1,6 @@
+import { SCENE_FILE_NAME } from "../constants.js";
 export declare const SCENE_APP_DIR = "app";
-export declare const SCENE_FILE_NAME = "scene.phibelle";
+export { SCENE_FILE_NAME };
 export declare function getSceneAppDir(sceneDir: string): string;
 export declare function folderExists(folderPath: string): boolean;
 export declare function createFolder(folderPath: string): void;

package/dist/lib/scene/file-system.js

@@ -1,7 +1,8 @@
 import * as path from "node:path";
-import * as fs from "fs";
+import * as fs from "node:fs";
+import { SCENE_FILE_NAME } from "../constants.js";
 export const SCENE_APP_DIR = "app";
-export const SCENE_FILE_NAME = "scene.phibelle";
+export { SCENE_FILE_NAME };
 export function getSceneAppDir(sceneDir) {
     return path.join(sceneDir, SCENE_APP_DIR);
 }

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

@@ -1,7 +1,7 @@
-import * as fs from "fs/promises";
-import * as path from "path";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { getSceneAppDir } from "./file-system.js";
-const MANIFEST_FILE_NAME = "manifest.json";
+import { MANIFEST_FILE_NAME } from "../constants.js";
 const LEGACY_SCENE_FILE = "scene.tsx";
 const CHILDREN_DIR_NAME = "children";
 /** Scene-level file names in app/. */
@@ -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/scene/script-watcher.js

@@ -1,5 +1,6 @@
-import * as path from "path";
+import * as path from "node:path";
 import chokidar from "chokidar";
+import { MANIFEST_FILE_NAME } from "../constants.js";
 import { getSceneAppDir } from "./file-system.js";
 import { packageSceneFromFilesystem, ENTITY_SCRIPT_FILE, ENTITY_PROPERTIES_FILE, ENTITY_TRANSFORMS_FILE, SCENE_SCRIPT_FILE, SCENE_PROPERTIES_FILE, } from "./scene-packaging.js";
 const DEBOUNCE_MS = 100;
@@ -48,7 +49,7 @@ export function createScriptWatcher(sceneDir, getLatestSceneJson, onSceneUpdated
     const watcher = chokidar.watch(appDir, { ignoreInitial: true });
     function handlePathEvent(filePath) {
         const relativePath = toRelativePath(filePath);
-        if (relativePath === "manifest.json")
+        if (relativePath === MANIFEST_FILE_NAME)
             return;
         if (isRelevantPath(relativePath))
             schedule(relativePath);

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/dist/lib/utils.d.ts

@@ -1 +1,3 @@
 export declare function toErrorMessage(err: unknown): string;
+/** For exec/child_process errors: prefer stderr (last line), otherwise message. */
+export declare function getExecErrorText(error: unknown): string;

package/dist/lib/utils.js

@@ -1,3 +1,13 @@
 export function toErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** For exec/child_process errors: prefer stderr (last line), otherwise message. */
+export function getExecErrorText(error) {
+    if (!error || typeof error !== "object")
+        return "";
+    const err = error;
+    const stderr = err.stderr?.trim();
+    if (stderr)
+        return stderr.split("\n").pop() ?? stderr;
+    return err.message?.trim() ?? "";
+}

package/dist/scene-setup/setup.d.ts

@@ -1,4 +1,3 @@
 export declare function setupSceneDirectory(sceneDir: string): {
     shouldPromptInstall: boolean;
 };
-export declare function getInstallHint(sceneDir: string): string;

package/dist/scene-setup/setup.js

@@ -39,18 +39,3 @@ export function setupSceneDirectory(sceneDir) {
     }
     return { shouldPromptInstall };
 }
-export function getInstallHint(sceneDir) {
-    const hasPnpm = fs.existsSync(path.join(sceneDir, "pnpm-lock.yaml"));
-    const hasYarn = fs.existsSync(path.join(sceneDir, "yarn.lock"));
-    const hasBun = fs.existsSync(path.join(sceneDir, "bun.lockb"));
-    const hasNpm = fs.existsSync(path.join(sceneDir, "package-lock.json"));
-    if (hasPnpm)
-        return "pnpm install";
-    if (hasBun)
-        return "bun install";
-    if (hasYarn)
-        return "yarn install";
-    if (hasNpm)
-        return "npm install";
-    return "npm install (or pnpm / bun / yarn install)";
-}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "phibelle-kit",
-  "version": "1.0.31",
+  "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",