castle-web-cli 0.4.114 → 0.4.116

package/dist/imports.js

@@ -5,7 +5,7 @@ import * as api from './api.js';
 import { runTar } from './save-deck.js';
 import { normalizeDeckPackageJson } from './normalize.js';
 import { getKitsDir } from './localPaths.js';
-import { readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
+import { readCastleJson as tryReadCastleJson, readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
 // Adding another deck as a dependency (`castle-web add-import`; removing one is a
 // later command). Deliberately NOT `get-deck`: that one
 // replaces THIS deck's own source from the server (and carries guards for the
@@ -80,11 +80,7 @@ function slugifyAlias(name) {
 // An explicit `--as` may already be qualified (`someone.their-deck`); slugify
 // each part so the separator survives.
 function slugifyGivenAlias(name) {
-    return name
-        .split('.')
-        .map(slugifyAlias)
-        .filter(Boolean)
-        .join('.');
+    return name.split('.').map(slugifyAlias).filter(Boolean).join('.');
 }
 // Aliases are qualified by author -- `lovefromtom.fish-town` -- because deck
 // titles are not unique across users (nor even within one), and an import's name
@@ -255,7 +251,8 @@ export async function restoreMissingImports(deckDir) {
             fs.cpSync(kitDir, destDir, {
                 recursive: true,
                 verbatimSymlinks: true,
-                filter: (src) => src === kitDir || !['node_modules', '.castle', 'dist', '.git'].includes(path.basename(src)),
+                filter: (src) => src === kitDir ||
+                    !['node_modules', '.castle', 'dist', '.git'].includes(path.basename(src)),
             });
         }
         else {
@@ -438,7 +435,9 @@ async function addTransitiveImports(deckDir, viaAlias, seen) {
 // loop on a cycle.
 export function importedDeckIds(deckDir) {
     const pins = readCastleJson(deckDir)?.imports ?? {};
-    return new Set(Object.values(pins).map((p) => p?.deckId).filter((id) => !!id));
+    return new Set(Object.values(pins)
+        .map((p) => p?.deckId)
+        .filter((id) => !!id));
 }
 // The import itself. Throws ImportError rather than exiting, because this also
 // runs inside the serve (from the editor's Import panel), where taking the
@@ -477,7 +476,52 @@ export async function addImportTo(dir, options = {}) {
     const { replaced } = await placeImport(targetDir, alias, deckId, source);
     const transitive = await addTransitiveImports(targetDir, alias, importedDeckIds(targetDir));
     const dependencies = syncImportDependencies(targetDir);
-    return { deckId, alias, replaced, transitive, dependencies };
+    // A kit declares its entry module (castle.json `main`). Importing one into a
+    // deck that is still the untouched `--kit none` scaffold means "start from this
+    // kit", so adopt its entry -- otherwise the deck keeps booting its own stub and
+    // the kit's runtime and editors never mount. A deck with any work in it is left
+    // alone and just told the option exists, since repointing it would go dark.
+    const importDir = path.join(targetDir, IMPORTS_DIR, alias);
+    const declaredMain = tryReadCastleJson(importDir)?.main;
+    let adoptedMain = null;
+    if (typeof declaredMain === 'string' && declaredMain.trim()) {
+        const { isPristineBareDeck, adoptImportEntry, writeStarterScene } = await import('./init.js');
+        if (isPristineBareDeck(targetDir)) {
+            adoptImportEntry(targetDir, alias, declaredMain.trim());
+            adoptedMain = declaredMain.trim();
+            // A kit's runtime with no scene to run is a blank screen, and the agent
+            // has nothing to edit. Give the deck the kit's own starter, same as
+            // `init --kit`. Only when the deck has no scenes -- never overwrite.
+            if (!fs.existsSync(path.join(targetDir, 'scenes'))) {
+                try {
+                    writeStarterScene(targetDir, importDir, alias);
+                }
+                catch (e) {
+                    console.warn(`Adopted ${alias} but could not write its starter scene: ${e instanceof Error ? e.message : String(e)}`);
+                }
+            }
+        }
+    }
+    // An import's packages have to be ON DISK, not just named in package.json:
+    // the deck fails to load the moment its code imports one. Telling the caller
+    // to run `castle-web install` only worked for the CLI -- an import taken from
+    // the editor left the deck broken with no visible reason why.
+    if (dependencies.length > 0) {
+        try {
+            // Imported here rather than at the top: install.ts imports THIS module,
+            // and a top-level import back would be a cycle.
+            const { installDeps } = await import('./install.js');
+            await installDeps(targetDir, false);
+        }
+        catch (e) {
+            // Never fail the import over this: the files are already in place, and a
+            // hand-run install still fixes it.
+            console.warn(`Imported ${alias}, but installing its dependencies failed -- run \`castle-web install\`. ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const trimmedMain = typeof declaredMain === 'string' && declaredMain.trim() ? declaredMain.trim() : null;
+    const offersMain = trimmedMain && !adoptedMain ? trimmedMain : null;
+    return { deckId, alias, replaced, transitive, dependencies, adoptedMain, offersMain };
 }
 export async function addImport(dir, options = {}) {
     let result;
@@ -500,8 +544,101 @@ export async function addImport(dir, options = {}) {
     }
     for (const dep of result.dependencies)
         console.log(`Added dependency ${dep}`);
-    if (result.dependencies.length > 0)
-        console.log('Run `castle-web install` to install them.');
+    if (result.adoptedMain) {
+        console.log(`This deck now runs ${result.alias} (index.html -> ${result.adoptedMain}).`);
+    }
+    else if (result.offersMain) {
+        console.log(`${result.alias} is a kit. To run this deck on it, point index.html at ` +
+            `/${IMPORTS_DIR}/${result.alias}/${result.offersMain}.`);
+    }
+}
+// Take one import's update: replace its files with the version the server has
+// now, then follow that version's own pins for anything newly required. Both
+// `update-import` and the serve-start auto update come through here, so there
+// is one path that replaces an import's files rather than two that have to be
+// kept in step. `log` is how the caller labels the lines it produces.
+async function applyImportUpdate(deckDir, alias, update, source, log) {
+    await placeImport(deckDir, alias, update.deckId, source, update.via);
+    log(`Updated ${alias} (${update.from} -> ${source.updatedAt})`);
+    // Its own dependencies may have moved too.
+    const transitive = await addTransitiveImports(deckDir, alias, importedDeckIds(deckDir));
+    for (const t of transitive)
+        log(`Also imported ${IMPORTS_DIR}/${t} (needed by ${alias})`);
+}
+// Whether the deck behind an import asked to be tracked rather than pinned --
+// `autoUpdateWhenImported` in ITS castle.json, which is a statement its author
+// makes about their own deck (see castleJson.ts).
+//
+// Read from the copy already on disk, NOT from the version about to be fetched.
+// The flag the importer has is the one that was there when they took this
+// version; letting the incoming version answer would let any deck start pushing
+// to everyone who already imported it, after the fact. The cost is a one-update
+// lag both ways -- turning the flag on reaches an existing importer only once
+// they take an update by hand, and turning it off gets delivered by one last
+// auto update -- which is the safe direction for both.
+function importOptsIntoAutoUpdate(deckDir, alias) {
+    const config = tryReadCastleJson(path.join(deckDir, IMPORTS_DIR, alias));
+    return config?.autoUpdateWhenImported === true;
+}
+// Auto-update is honored only for imports of decks on the castle account. The
+// flag is the mechanism and this is a leash on it: a deck that pushes new code
+// to everyone who imported it is asking for a lot of trust, and until decks
+// carry some other signal of it, the only ones that get it are the ones we
+// publish (the framework kits -- the same account `init` qualifies their aliases
+// with).
+//
+// Deliberately not a setting: nothing a deck or a person can flip, since that
+// would be the leash undoing itself. The env var is a test seam -- the automated
+// check can't publish a deck to the castle account (nothing should), so it
+// substitutes which account counts and exercises both branches for real.
+const AUTO_UPDATE_ACCOUNT = process.env.CASTLE_AUTO_UPDATE_TRUSTED_ACCOUNT ?? 'castle';
+// Who published a deck. Readable without auth for the same decks webDeckSource
+// is, so this answers in a sandbox with no login. A lookup that fails answers
+// "not trusted": the failure direction has to be the one that leaves an import
+// where its deck's author pinned it.
+async function importIsOnTrustedAccount(deckId) {
+    const meta = await api.deckMeta(deckId).catch(() => null);
+    return meta?.creator?.username === AUTO_UPDATE_ACCOUNT;
+}
+// Move every opted-in import that the account gate allows to the version the
+// server has now.
+//
+// Called once from serve start (see serve.ts) and nowhere else: that is the one
+// moment where replacing a dependency's files can't pull the rug out from under
+// anything -- no editor is holding unsaved state and no play session is running
+// yet. A page reload happens mid-session, so it deliberately does not do this.
+//
+// Silent when nothing moves. Nothing here is fatal: an import that can't be
+// checked (offline, no source on the server, a bad archive) stays exactly as it
+// is pinned, and the serve starts anyway.
+export async function autoUpdateImports(deckDir) {
+    const pins = tryReadCastleJson(deckDir)?.imports ?? {};
+    const updated = [];
+    for (const [alias, pin] of Object.entries(pins)) {
+        // A kit copied from the CLI has no deck to ask; it moves when the CLI does.
+        if (!pin?.deckId)
+            continue;
+        if (!importOptsIntoAutoUpdate(deckDir, alias))
+            continue;
+        try {
+            if (!(await importIsOnTrustedAccount(pin.deckId)))
+                continue;
+            const source = await api.webDeckSource(pin.deckId);
+            if (!source || source.updatedAt === pin.version)
+                continue;
+            await applyImportUpdate(deckDir, alias, { deckId: pin.deckId, from: pin.version, via: pin.via }, source, (message) => console.log(`auto-update: ${message}`));
+            updated.push({ alias, from: pin.version, to: source.updatedAt });
+        }
+        catch (e) {
+            console.warn(`auto-update: left "${alias}" as it is -- ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (updated.length > 0) {
+        for (const dep of syncImportDependencies(deckDir)) {
+            console.log(`auto-update: added dependency ${dep}`);
+        }
+    }
+    return updated;
 }
 // `castle-web update-import [alias] [dir]`: re-fetch an import (or all of them)
 // at the version the server has now. Updates happen while editing, never on
@@ -552,12 +689,7 @@ export async function updateImport(dir, options = {}) {
             changed = true;
             continue;
         }
-        await placeImport(deckDir, alias, pin.deckId, source, pin.via);
-        console.log(`Updated ${alias} (${pin.version} -> ${source.updatedAt})`);
-        // Its own dependencies may have moved too.
-        const transitive = await addTransitiveImports(deckDir, alias, importedDeckIds(deckDir));
-        for (const t of transitive)
-            console.log(`Also imported ${IMPORTS_DIR}/${t} (needed by ${alias})`);
+        await applyImportUpdate(deckDir, alias, { deckId: pin.deckId, from: pin.version, via: pin.via }, source, (message) => console.log(message));
         changed = true;
     }
     if (!changed)

package/dist/init.d.ts

@@ -5,7 +5,10 @@ export declare function resolveScaffoldRefs(): {
     cliDistAbs: string | null;
     sdkPathPosix: string | null;
 };
+export declare function isPristineBareDeck(dir: string): boolean;
+export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
 export declare function getCliVersion(): string;
+export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;

package/dist/init.js

@@ -1,10 +1,11 @@
-import * as fs from "fs";
-import * as path from "path";
-import { COMMON_INSTRUCTIONS } from "./commonInstructions.js";
-import { installDeps } from "./install.js";
-import { IMPORTS_DIR, lockImportTree } from "./imports.js";
-import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from "./localPaths.js";
-import { serve } from "./serve.js";
+import * as fs from 'fs';
+import * as path from 'path';
+import { COMMON_INSTRUCTIONS } from './commonInstructions.js';
+import { installDeps } from './install.js';
+import { deckMainFile, deckStarterScene } from './castleJson.js';
+import { IMPORTS_DIR, lockImportTree } from './imports.js';
+import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from './localPaths.js';
+import { serve } from './serve.js';
 const INDEX_HTML = `<!DOCTYPE html>
 <html>
 <head>
@@ -32,27 +33,22 @@ card.appendChild(el);
 `;
 // Default kit imported by `init` when no --kit is given. `none`/`bare` skip the
 // kit and produce the minimal index.html + game.js stub above.
-const DEFAULT_KIT = "physics-2d";
+const DEFAULT_KIT = 'physics-2d';
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = "0.4.11";
+const PUBLISHED_SDK_VERSION = '0.4.12';
 // The account the first-party kits are (to be) published under, so a kit
 // imported from the CLI's copy is named the same as one fetched from the server.
-const KIT_AUTHOR = "castle";
+const KIT_AUTHOR = 'castle';
 // Never copied into a deck's import: build/dependency junk.
-const KIT_COPY_EXCLUDE = new Set([
-    "node_modules",
-    ".castle",
-    "dist",
-    ".git",
-]);
+const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git']);
 // The bare (`--kit none`) deck's default editor config: just the Files panel and
 // a Play panel. No file filtering -- a bare deck is hand-rolled, so the author
 // knows what's there; show everything for now.
 const BARE_CASTLE_JSON = {
     editor: {
-        initialPanels: [{ type: "files" }, { type: "playtest" }],
+        initialPanels: [{ type: 'files' }, { type: 'playtest' }],
         hiddenPaths: [],
         visiblePaths: [],
     },
@@ -70,17 +66,11 @@ export function resolveScaffoldRefs() {
     // npm package and need the published refs + `castle-web` binary.
     const workspaceMode = fs.existsSync(sdkPath);
     const sdkPathPosix = workspaceMode ? toPosixPath(sdkPath) : null;
-    const cliDistAbs = workspaceMode
-        ? toPosixPath(path.dirname(getCliEntryPath()))
-        : null;
+    const cliDistAbs = workspaceMode ? toPosixPath(path.dirname(getCliEntryPath())) : null;
     return {
         workspaceMode,
-        sdkRef: workspaceMode
-            ? `file:${sdkPathPosix}`
-            : `^${PUBLISHED_SDK_VERSION}`,
-        cliCommand: workspaceMode
-            ? `node ${toPosixPath(getCliEntryPath())}`
-            : "castle-web",
+        sdkRef: workspaceMode ? `file:${sdkPathPosix}` : `^${PUBLISHED_SDK_VERSION}`,
+        cliCommand: workspaceMode ? `node ${toPosixPath(getCliEntryPath())}` : 'castle-web',
         cliDistAbs,
         sdkPathPosix,
     };
@@ -90,9 +80,9 @@ function makeClaudeMd() {
     // castle-experimental-web checkout, but breaks when the scaffold lives
     // outside the repo (the relative path no longer resolves).
     const repoRoot = getRepoRoot();
-    const upstream = path.join(repoRoot, "CLAUDE.md");
+    const upstream = path.join(repoRoot, 'CLAUDE.md');
     try {
-        return fs.readFileSync(upstream, "utf8").trimEnd() + "\n";
+        return fs.readFileSync(upstream, 'utf8').trimEnd() + '\n';
     }
     catch {
         return `# Castle Experimental Web\n\nSee https://github.com/castle-xyz/castle-experimental-web for the agent guide.\n`;
@@ -102,15 +92,15 @@ function makeClaudeMd() {
 // the kit's (or bare) CLAUDE.md is written; the AGENTS.md symlink picks the
 // appended content up for free.
 function appendCommonInstructions(projectDir) {
-    const claudePath = path.join(projectDir, "CLAUDE.md");
+    const claudePath = path.join(projectDir, 'CLAUDE.md');
     const existing = fs.existsSync(claudePath)
-        ? fs.readFileSync(claudePath, "utf8").trimEnd() + "\n\n"
-        : "";
+        ? fs.readFileSync(claudePath, 'utf8').trimEnd() + '\n\n'
+        : '';
     fs.writeFileSync(claudePath, existing + COMMON_INSTRUCTIONS);
 }
 function tryMakeAgentsSymlink(agentsPath) {
     try {
-        fs.symlinkSync("CLAUDE.md", agentsPath);
+        fs.symlinkSync('CLAUDE.md', agentsPath);
     }
     catch {
         // symlink already exists / unsupported FS — non-fatal
@@ -124,11 +114,11 @@ function makeKitDeckScripts(kitDir, alias, cliCommand) {
     const scripts = {
         restart: `${cliCommand} restart .`,
         screenshot: `${cliCommand} screenshot .`,
-        "save-deck": `${cliCommand} save-deck .`,
+        'save-deck': `${cliCommand} save-deck .`,
     };
     // `draw` is a kit script, not a CLI one, so it only exists if this kit ships
     // it -- and it runs from the deck root, where the sprites belong.
-    if (fs.existsSync(path.join(kitDir, "scripts", "draw.mjs"))) {
+    if (fs.existsSync(path.join(kitDir, 'scripts', 'draw.mjs'))) {
         scripts.draw = `node ${IMPORTS_DIR}/${alias}/scripts/draw.mjs`;
     }
     return scripts;
@@ -138,38 +128,59 @@ function makePackageJson(projectDir) {
     return {
         name: path.basename(projectDir),
         private: true,
-        type: "module",
+        type: 'module',
         scripts: {
             restart: `${cliCommand} restart .`,
             screenshot: `${cliCommand} screenshot .`,
-            "save-deck": `${cliCommand} save-deck .`,
+            'save-deck': `${cliCommand} save-deck .`,
         },
         dependencies: {
-            "castle-web-sdk": sdkRef,
+            'castle-web-sdk': sdkRef,
         },
     };
 }
 // Some coding agents read AGENTS.md by convention. Symlink so they get the
 // same guidance without a duplicate copy.
 function ensureAgentsSymlink(projectDir) {
-    const agentsPath = path.join(projectDir, "AGENTS.md");
+    const agentsPath = path.join(projectDir, 'AGENTS.md');
     if (fs.lstatSync(agentsPath, { throwIfNoEntry: false }))
         return;
     // Don't create a dangling link — only symlink when CLAUDE.md is present.
-    if (!fs.existsSync(path.join(projectDir, "CLAUDE.md")))
+    if (!fs.existsSync(path.join(projectDir, 'CLAUDE.md')))
         return;
     tryMakeAgentsSymlink(agentsPath);
 }
 // Bare scaffold: a plain code-only deck with no kit framework.
+// Whether a deck is still exactly what `--kit none` produced -- both the entry
+// and the stub game it boots, untouched. `addImportTo` asks before repointing a
+// deck's entry at an imported kit: on a pristine scaffold there is nothing to
+// lose, and one edited character anywhere makes this false, so a deck someone
+// has actually worked in is never quietly taken over.
+export function isPristineBareDeck(dir) {
+    try {
+        return (fs.readFileSync(path.join(dir, 'index.html'), 'utf8') === INDEX_HTML &&
+            fs.readFileSync(path.join(dir, 'game.js'), 'utf8') === GAME_JS);
+    }
+    catch {
+        return false;
+    }
+}
+// Repoint a deck's entry at an imported deck's main module.
+export function adoptImportEntry(deckDir, alias, mainFile) {
+    const file = path.join(deckDir, 'index.html');
+    const html = fs.readFileSync(file, 'utf8');
+    fs.writeFileSync(file, html.replace(/<script type="module" src="[^"]*"><\/script>/, `<script type="module" src="/${IMPORTS_DIR}/${alias}/${mainFile}"></script>`), 'utf8');
+    fs.rmSync(path.join(deckDir, 'game.js'), { force: true });
+}
 function scaffoldBare(projectDir) {
     fs.mkdirSync(projectDir, { recursive: true });
-    fs.writeFileSync(path.join(projectDir, "index.html"), INDEX_HTML);
-    fs.writeFileSync(path.join(projectDir, "game.js"), GAME_JS);
-    fs.writeFileSync(path.join(projectDir, "castle.json"), JSON.stringify(BARE_CASTLE_JSON, null, 2) + "\n");
-    fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeClaudeMd());
+    fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
+    fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
+    fs.writeFileSync(path.join(projectDir, 'castle.json'), JSON.stringify(BARE_CASTLE_JSON, null, 2) + '\n');
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeClaudeMd());
     appendCommonInstructions(projectDir);
     ensureAgentsSymlink(projectDir);
-    fs.writeFileSync(path.join(projectDir, "package.json"), JSON.stringify(makePackageJson(projectDir), null, 2) + "\n");
+    fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
 }
 // Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
 // build/dependency junk and castle.json.
@@ -180,7 +191,7 @@ function requireKitDir(kit) {
     if (fs.existsSync(kitDir) && fs.statSync(kitDir).isDirectory())
         return kitDir;
     console.error(`Kit "${kit}" not found at ${kitDir}.`);
-    console.error("Available kits:");
+    console.error('Available kits:');
     try {
         const kits = fs
             .readdirSync(getKitsDir())
@@ -189,34 +200,34 @@ function requireKitDir(kit) {
             for (const name of kits)
                 console.error(`  ${name}`);
         else
-            console.error("  (none)");
+            console.error('  (none)');
     }
     catch {
-        console.error("  (none — kits/ directory is missing)");
+        console.error('  (none — kits/ directory is missing)');
     }
-    console.error("Or use `--kit none` for a bare code-only deck.");
+    console.error('Or use `--kit none` for a bare code-only deck.');
     return process.exit(1);
 }
 function readJsonFile(file) {
     try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
     catch {
         return null;
     }
 }
 function writeJsonFile(file, value) {
-    fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n", "utf8");
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n', 'utf8');
 }
 export function getCliVersion() {
-    const pkg = readJsonFile(path.join(getKitsDir(), "..", "package.json"));
-    return typeof pkg?.version === "string" ? pkg.version : "0.0.0";
+    const pkg = readJsonFile(path.join(getKitsDir(), '..', 'package.json'));
+    return typeof pkg?.version === 'string' ? pkg.version : '0.0.0';
 }
 // The deck's entry point is the KIT's -- the deck has no engine code of its own
 // -- so index.html points into the import. Everything the kit's main.jsx imports
 // is relative to itself, so it needs no rewriting to run from there.
-function writeDeckIndexHtml(projectDir, alias, title) {
-    fs.writeFileSync(path.join(projectDir, "index.html"), `<!doctype html>
+function writeDeckIndexHtml(projectDir, alias, title, mainFile) {
+    fs.writeFileSync(path.join(projectDir, 'index.html'), `<!doctype html>
 <html>
   <head>
     <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
@@ -236,31 +247,34 @@ function writeDeckIndexHtml(projectDir, alias, title) {
     <div id="root"></div>
     <!-- Engine and editors come from the imported kit; this deck holds its own
          scenes, drawings and behaviors. -->
-    <script type="module" src="/${IMPORTS_DIR}/${alias}/main.jsx"></script>
+    <script type="module" src="/${IMPORTS_DIR}/${alias}/${mainFile}"></script>
   </body>
 </html>
-`, "utf8");
+`, 'utf8');
 }
 // The deck starts with its own copy of the kit's starter scene, so there is
 // something to open and edit on the first run. Refs inside it are rewritten to
 // point at the kit's copies of what they name (the scene is the deck's now, but
 // the blueprint and art it places still live in the import).
-function writeStarterScene(projectDir, kitDir, alias) {
-    const scene = readJsonFile(path.join(kitDir, "scenes", "main.scene"));
+// Give a deck the scene its kit says to start from, with every path that names a
+// kit file rewritten to reach it through the import. Exported because both
+// scaffold paths need it: `init --kit`, and adopting a kit via `add-import`.
+export function writeStarterScene(projectDir, kitDir, alias) {
+    const scene = readJsonFile(path.join(kitDir, deckStarterScene(kitDir)));
     const prefix = `${IMPORTS_DIR}/${alias}/`;
     const rewrite = (value) => {
-        if (typeof value === "string") {
+        if (typeof value === 'string') {
             return fs.existsSync(path.join(kitDir, value)) ? prefix + value : value;
         }
         if (Array.isArray(value))
             return value.map(rewrite);
-        if (value && typeof value === "object") {
+        if (value && typeof value === 'object') {
             return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, rewrite(v)]));
         }
         return value;
     };
-    fs.mkdirSync(path.join(projectDir, "scenes"), { recursive: true });
-    writeJsonFile(path.join(projectDir, "scenes", "main.scene"), scene ? rewrite(scene) : { name: "Main", actors: [] });
+    fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
+    writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), scene ? rewrite(scene) : { name: 'Main', actors: [] });
 }
 function makeImportedKitClaudeMd(alias) {
     return `# Castle deck
@@ -291,10 +305,17 @@ something in the kit behaves, define your own behavior of the same name in
 function makeKitPin(kitConfig, kit) {
     const deckId = kitConfig.deckId;
     const version = kitConfig.publishedVersion;
-    if (typeof deckId === "string" && typeof version === "string") {
+    if (typeof deckId === 'string' && typeof version === 'string') {
         return { deckId, version };
     }
-    return { source: "builtin", kit, version: getCliVersion() };
+    return { source: 'builtin', kit, version: getCliVersion() };
+}
+// The kit's editor block minus `fileTypes` -- the layout and file filters a new
+// deck starts from, without the vocabulary it resolves from the kit itself.
+function withoutFileTypes(editor) {
+    const rest = { ...(editor ?? {}) };
+    delete rest.fileTypes;
+    return rest;
 }
 // Scaffold a deck that IMPORTS its kit instead of copying it. The kit's files
 // land in `imports/<kit>/` (read-only, like any dependency) and the deck itself
@@ -323,16 +344,22 @@ function scaffoldFromKitImport(kit, projectDir) {
         verbatimSymlinks: true,
         filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
     });
-    const kitConfig = readJsonFile(path.join(kitDir, "castle.json")) ?? {};
-    const kitPkg = readJsonFile(path.join(kitDir, "package.json")) ?? {};
-    const title = typeof kitConfig.title === "string" ? kitConfig.title : kit;
-    writeDeckIndexHtml(projectDir, alias, title);
+    const kitConfig = readJsonFile(path.join(kitDir, 'castle.json')) ?? {};
+    const kitPkg = readJsonFile(path.join(kitDir, 'package.json')) ?? {};
+    const title = typeof kitConfig.title === 'string' ? kitConfig.title : kit;
+    writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
     writeStarterScene(projectDir, kitDir, alias);
     // The deck's own castle.json: the kit's editor config (panel layout, file
     // filters) as a starting point -- it is the deck's to edit from here -- plus
     // the import pin.
-    writeJsonFile(path.join(projectDir, "castle.json"), {
-        ...(kitConfig.editor ? { editor: kitConfig.editor } : {}),
+    //
+    // `fileTypes` is deliberately NOT copied. It is the kit's own vocabulary, and
+    // the deck resolves it live from every import's castle.json (see
+    // editorConfig.resolveFileTypes) -- so the kit keeps owning it, a kit fix
+    // reaches the deck like any other, and a kit imported LATER contributes its
+    // types too, which a copy taken at scaffold time never could.
+    writeJsonFile(path.join(projectDir, 'castle.json'), {
+        ...(kitConfig.editor ? { editor: withoutFileTypes(kitConfig.editor) } : {}),
         imports: { [alias]: makeKitPin(kitConfig, kit) },
     });
     // The kit's code runs from THIS deck's node_modules, so its dependencies are
@@ -342,18 +369,16 @@ function scaffoldFromKitImport(kit, projectDir) {
     const dependencies = {};
     for (const [name, range] of Object.entries(kitPkg.dependencies ?? {})) {
         dependencies[name] =
-            name === "castle-web-sdk" && String(range).startsWith("file:")
-                ? sdkRef
-                : String(range);
+            name === 'castle-web-sdk' && String(range).startsWith('file:') ? sdkRef : String(range);
     }
-    writeJsonFile(path.join(projectDir, "package.json"), {
+    writeJsonFile(path.join(projectDir, 'package.json'), {
         name: path.basename(projectDir),
         private: true,
-        type: "module",
+        type: 'module',
         scripts: makeKitDeckScripts(kitDir, alias, cliCommand),
         dependencies,
     });
-    fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeImportedKitClaudeMd(alias));
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), makeImportedKitClaudeMd(alias));
     appendCommonInstructions(projectDir);
     lockImportTree(importDir);
 }
@@ -364,14 +389,14 @@ export async function init(dir, opts = {}) {
         process.exit(1);
     }
     const kit = opts.kit ?? DEFAULT_KIT;
-    const bare = kit === "none" || kit === "bare";
+    const bare = kit === 'none' || kit === 'bare';
     if (bare) {
         scaffoldBare(projectDir);
     }
     else {
         scaffoldFromKitImport(kit, projectDir);
     }
-    console.log(`Created project in ${projectDir}/${bare ? "" : ` (from kit "${kit}")`}`);
+    console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     // Always install deps so the deck is ready to serve/edit immediately.
     // `--no-serve` only skips the serve step below (callers like the cloud
     // launcher run their own serve, but still want deps in place).
@@ -381,18 +406,18 @@ export async function init(dir, opts = {}) {
     // decks rewrite the sdk to file:../../sdk, which the shipped (published)
     // lockfile won't match -> drop it and let pnpm resolve. Bare decks have no
     // lockfile -> non-frozen.
-    const lockPath = path.join(projectDir, "pnpm-lock.yaml");
+    const lockPath = path.join(projectDir, 'pnpm-lock.yaml');
     if (resolveScaffoldRefs().workspaceMode)
         fs.rmSync(lockPath, { force: true });
     const frozen = fs.existsSync(lockPath);
-    console.log("");
+    console.log('');
     let installed = false;
     try {
-        installDeps(projectDir, frozen);
+        await installDeps(projectDir, frozen);
         installed = true;
     }
     catch {
-        console.error("dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.");
+        console.error('dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.');
     }
     const autoServe = opts.serve !== false;
     if (autoServe && installed) {
@@ -402,16 +427,16 @@ export async function init(dir, opts = {}) {
         // the served page; users can override host on a subsequent serve call.
         // Open in the user's default browser unless we're clearly headless (SSH
         // session) or the user has opted out via CASTLE_WEB_CLI_NO_OPEN=1.
-        const noOpen = process.env.CASTLE_WEB_CLI_NO_OPEN === "1" ||
+        const noOpen = process.env.CASTLE_WEB_CLI_NO_OPEN === '1' ||
             !!process.env.SSH_CONNECTION ||
             !!process.env.SSH_TTY;
-        await serve(projectDir, { host: "0.0.0.0", detach: true, open: !noOpen });
+        await serve(projectDir, { host: '0.0.0.0', detach: true, open: !noOpen });
         return;
     }
-    console.log("");
-    console.log("Next steps:");
+    console.log('');
+    console.log('Next steps:');
     console.log(`  cd ${dir}`);
     if (!installed)
-        console.log("  pnpm install   # or: npm install");
-    console.log("  castle-web serve .   # & in your shell to background it");
+        console.log('  pnpm install   # or: npm install');
+    console.log('  castle-web serve .   # & in your shell to background it');
 }

package/dist/install.d.ts

@@ -1,2 +1,2 @@
-export declare function installDeps(projectDir: string, frozen: boolean): void;
+export declare function installDeps(projectDir: string, frozen: boolean): Promise<void>;
 export declare function install(dir: string): Promise<void>;