castle-web-cli 0.4.121 → 0.4.123

package/dist/agent-prompts.js

@@ -63,6 +63,7 @@ comma-separated active-task titles or ids, or \`all\`
 - Never claim the board is cleared without actually emitting the fence.
 - Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it.
 - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
+- The deck keeps its own version history, and you may READ it: \`castle-web list-versions\` shows the versions newest first, and \`castle-web show-version <id>\` shows what one changed, as diffs of just those files. Use them to answer "what changed" or to ground a claim about recent work. You NEVER run \`save-version\` -- you did not make the changes, so a version of yours would not correspond to a unit of work -- and you NEVER run \`restore-version\`: going back is the user's own decision, not something you do on their behalf.
 
 Asking with options (the \`\`\`ask block). When you need the user to settle a few choices at once, emit ONE fenced block tagged \`ask\` containing JSON -- it renders inline in the chat as grouped options they tap and submit together (far better than stacking questions they can only half-answer). Reach for it to pin a direction fast when their ask is vague ("make me a game" -> ask what kind), NOT to interrogate. Options only, no free text.
 
@@ -233,7 +234,7 @@ export function buildTaskPrompt(opts) {
     // -- blind whole-file rewrites made parallel agents clobber each other's
     // edits. Read-then-edit is slower but safe; that is the right tradeoff.)
     const wrapUp = opts.backend === "claude" || opts.backend === "smith"
-        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
+        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine the 90-progress write, the \`castle-web save-version\` for your paths, the final \`npm run restart\`, and writing the notes file into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
         : "";
     return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions, and reload the served deck after changes (\`npm run restart\`).${quickReference}${layout}${deckSource}
 
@@ -247,6 +248,9 @@ Operating rules:
 - The USER is the verifier -- the whole tasks system exists so the user playtests every change themselves. Your first priority is to finish as soon as possible with the change genuinely in place and reachable in the running deck, so the user can test it right away. Do NOT run verification (screenshots especially) unless you are really sure it will catch something a re-read of your own change cannot -- and even then at most one cheap check, never a retry loop. Time spent verifying is time the user is left waiting.
 - The moment implementation is complete and you switch to verifying, write 90 to the progress file -- verification time must not read as stalled progress.
 - Do this one task completely, then stop. Do not expand scope.
+- SAVE A VERSION when your change is done, so the user can see and undo it: \`castle-web save-version -m "<short description of what you changed>" <each path you touched>\`. Name those paths explicitly -- a bare \`save-version\` with no paths records the WHOLE deck, including files a sibling agent is still working on. One version for the whole task, at the end; not one per file.
+- Overlap with the other agents working in this deck is fine and expected -- do not try to avoid it or wait for them. Saving only your own paths is all that is asked of you; nothing anyone has written is lost by your save.
+- NEVER run \`restore-version\`. Going back to an earlier version is the user's decision alone -- not yours, not even to undo your own work. If your change is wrong, fix it forward.
 - Other task agents may be editing this same deck IN PARALLEL. When you change an existing file, READ it first and make a targeted edit to just the part you need -- never overwrite a whole file you have not read. A blind full-file rewrite clobbers other agents' in-flight changes. Being a bit slower and careful here is the right tradeoff.
 - Favor real, editable assets: for game objects, characters, and scenery, make pixel-art drawings and place them as real actors in the scene rather than code-drawn shapes -- it keeps the deck editable in the editor and remixable. (Data-driven UI like health bars, score/text, and HUD gauges, plus dynamic things like bullets/particles/effects, stay procedural -- don't force those into drawings.)
 - Respect art ownership: if YOUR task is to create art, make it as real, editable drawing files (NOT hand-written pixel grids or code-drawn shapes), following the deck's CLAUDE.md / AGENTS.md for the drawing format and exact command. But if your prompt only REFERENCES drawing names (a sibling task is creating them in parallel), point the scene at those names and do NOT create the drawing files yourself -- two agents drawing the same sprites clobber each other. The deck's CLAUDE.md / AGENTS.md is the source of truth for how to make art. Reference the intended drawing name from the scene right away (the actor renders a plain-block fallback until the file exists), and remember newly written drawing files need \`npm run restart\` before the kit picks them up.
@@ -264,7 +268,7 @@ phase: wiring the paddle to touch
   - \`phase\` -- a SHORT, plain-language line for this moment ("wiring the paddle to touch", "drawing the flag"). No file or code names. Update \`avatar\` and \`phase\` together each time your stage changes -- a few times across the task, not every turn. (You may also include \`progress: NN\` here, but the progress file above is the primary progress channel.)
 - Before finishing, write ${opts.notesPath}: a tiny test guide for the PLAYER -- AT MOST 2-3 bullets (markdown \`- \` lines), each ONE short phrase: what to try and what should happen. NO code, NO API or "integration contract" detail, NO file/behavior names or implementation notes -- those are for you, not the player. Occasionally one bullet may run a little longer, but default to terse. Mention a blocker only if you hit one. The user reads this verbatim to check your work.${wrapUp}
 - If you are truly blocked, write the blocker to the notes file and stop rather than guessing wildly.
-- Never touch files under .castle/ other than those two paths.`;
+- Never touch files under .castle/ other than those two paths. (The version store lives there too, but you never edit it by hand -- \`castle-web save-version\` writes it for you.)`;
 }
 // Appended to claude task agents' system prompt (portable replacement for the
 // machine-specific /goal slash command): commit to autonomous completion.

package/dist/diffText.d.ts

@@ -0,0 +1,14 @@
+export type DiffOp = {
+    kind: 'same' | 'add' | 'remove';
+    text: string;
+};
+/** True for content that is not text: a NUL byte, or bytes that aren't UTF-8. */
+export declare function looksBinary(content: Buffer): boolean;
+/** Every line of both sides, in order, marked same / add / remove. */
+export declare function diffOps(beforeText: string, afterText: string): DiffOp[] | null;
+/**
+ * A unified diff of two texts, or null when the change is too large to be worth
+ * rendering as one. Header lines are the caller's business -- this is only the
+ * hunks.
+ */
+export declare function unifiedDiff(beforeText: string, afterText: string): string[] | null;

package/dist/diffText.js

@@ -0,0 +1,138 @@
+// A small unified-diff generator, for `show-version`.
+//
+// Deliberately not a dependency: the only diff this CLI needs is between two
+// blobs it already has, and a hand-rolled line diff is a few dozen lines with
+// no supply chain attached.
+//
+// Shape of the algorithm: strip the common head and tail first -- a real edit
+// usually touches a few lines in a long file, so this leaves a small middle --
+// then run a longest-common-subsequence over what remains. The LCS table is
+// quadratic, so a middle that stays large after trimming reports a summary
+// instead of a patch rather than eating memory.
+const CONTEXT_LINES = 3;
+const MAX_DIFF_LINES = 2000;
+/** True for content that is not text: a NUL byte, or bytes that aren't UTF-8. */
+export function looksBinary(content) {
+    const sample = content.subarray(0, 8000);
+    if (sample.includes(0))
+        return true;
+    // A lone replacement char means the decoder hit a byte sequence that isn't
+    // valid UTF-8 -- unless the file genuinely contains one, which is rare enough
+    // to accept and harmless to treat as binary.
+    return sample.toString('utf8').includes('�');
+}
+function splitLines(text) {
+    const lines = text.split('\n');
+    // A trailing newline yields a final empty element that is not a line.
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines;
+}
+// Ops for the middle section, by LCS backtracking.
+function diffMiddle(before, after) {
+    const rows = before.length;
+    const cols = after.length;
+    const table = Array.from({ length: rows + 1 }, () => new Array(cols + 1).fill(0));
+    for (let i = rows - 1; i >= 0; i--) {
+        for (let j = cols - 1; j >= 0; j--) {
+            table[i][j] =
+                before[i] === after[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < rows && j < cols) {
+        if (before[i] === after[j]) {
+            ops.push({ kind: 'same', text: before[i] });
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            ops.push({ kind: 'remove', text: before[i] });
+            i++;
+        }
+        else {
+            ops.push({ kind: 'add', text: after[j] });
+            j++;
+        }
+    }
+    while (i < rows)
+        ops.push({ kind: 'remove', text: before[i++] });
+    while (j < cols)
+        ops.push({ kind: 'add', text: after[j++] });
+    return ops;
+}
+/** Every line of both sides, in order, marked same / add / remove. */
+export function diffOps(beforeText, afterText) {
+    const before = splitLines(beforeText);
+    const after = splitLines(afterText);
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head++;
+    let tail = 0;
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail]) {
+        tail++;
+    }
+    const beforeMiddle = before.slice(head, before.length - tail);
+    const afterMiddle = after.slice(head, after.length - tail);
+    if (beforeMiddle.length > MAX_DIFF_LINES || afterMiddle.length > MAX_DIFF_LINES)
+        return null;
+    return [
+        ...before.slice(0, head).map((text) => ({ kind: 'same', text })),
+        ...diffMiddle(beforeMiddle, afterMiddle),
+        ...before.slice(before.length - tail).map((text) => ({ kind: 'same', text })),
+    ];
+}
+function opsToHunks(ops) {
+    const changedAt = ops.map((op) => op.kind !== 'same');
+    const hunks = [];
+    let beforeLine = 1;
+    let afterLine = 1;
+    let current = null;
+    for (let index = 0; index < ops.length; index++) {
+        const op = ops[index];
+        // A same-line belongs to a hunk when a change is within CONTEXT_LINES of it
+        // on either side; that is what turns scattered edits into readable blocks.
+        const near = op.kind !== 'same' ||
+            changedAt.slice(Math.max(0, index - CONTEXT_LINES), index + CONTEXT_LINES + 1).some(Boolean);
+        if (near) {
+            if (!current)
+                current = { beforeStart: beforeLine, afterStart: afterLine, lines: [], beforeCount: 0, afterCount: 0 };
+            current.lines.push(`${op.kind === 'add' ? '+' : op.kind === 'remove' ? '-' : ' '}${op.text}`);
+            if (op.kind !== 'add')
+                current.beforeCount++;
+            if (op.kind !== 'remove')
+                current.afterCount++;
+        }
+        else if (current) {
+            hunks.push(current);
+            current = null;
+        }
+        if (op.kind !== 'add')
+            beforeLine++;
+        if (op.kind !== 'remove')
+            afterLine++;
+    }
+    if (current)
+        hunks.push(current);
+    return hunks;
+}
+/**
+ * A unified diff of two texts, or null when the change is too large to be worth
+ * rendering as one. Header lines are the caller's business -- this is only the
+ * hunks.
+ */
+export function unifiedDiff(beforeText, afterText) {
+    const ops = diffOps(beforeText, afterText);
+    if (!ops)
+        return null;
+    const out = [];
+    for (const hunk of opsToHunks(ops)) {
+        out.push(`@@ -${hunk.beforeStart},${hunk.beforeCount} +${hunk.afterStart},${hunk.afterCount} @@`);
+        out.push(...hunk.lines);
+    }
+    return out;
+}

package/dist/editorConfig.d.ts

@@ -15,11 +15,16 @@ export interface FileTypeConfig {
     new?: string;
     icon?: string;
     editor?: string;
-    data?: boolean;
+    data?: boolean | DataMode;
     unsupported?: string;
 }
+export type DataMode = 'json' | 'text';
+export declare function dataModeOf(type: {
+    data?: boolean | DataMode;
+}): DataMode | null;
 export interface ResolvedFileType extends FileTypeConfig {
     from?: string;
+    module?: string;
 }
 export interface EditorConfig {
     initialPanels?: InitialPanel[];

package/dist/editorConfig.js

@@ -17,6 +17,13 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { readCastleJson } from './castleJson.js';
 import { IMPORTS_DIR } from './imports.js';
+export function dataModeOf(type) {
+    if (type.data === true)
+        return 'json';
+    if (type.data === 'json' || type.data === 'text')
+        return type.data;
+    return null;
+}
 // An array with no usable entries stays an (empty) array rather than becoming
 // undefined: "I declare no file types" is a real answer, distinct from "I say
 // nothing about file types", and only the second one defers to the imports.
@@ -121,5 +128,17 @@ export function resolveFileTypes(deckDir) {
         if (imported)
             add(imported, alias);
     }
-    return anyDeclared ? [...byExt.values()] : null;
+    if (!anyDeclared)
+        return null;
+    // Rewrite each declared editor path so it is addressable from the DECK root.
+    // This is the whole routing decision: the deck's entry imports the named
+    // module, whoever declared it, instead of anything guessing which page owns
+    // the type.
+    for (const type of byExt.values()) {
+        if (!type.editor || type.editor === 'kit')
+            continue;
+        const declared = type.editor.replace(/^\.\//, '');
+        type.module = type.from ? `${IMPORTS_DIR}/${type.from}/${declared}` : declared;
+    }
+    return [...byExt.values()];
 }

package/dist/ide.d.ts

@@ -1,6 +1,7 @@
 import * as http from 'http';
 import { Duplex } from 'stream';
 import { type RawData } from 'ws';
+import { COVER_FILE } from './localPaths.js';
 export declare const IDE_ASSET_PREFIX = "/__castle/ide/";
 export declare const PTY_WS_PATH = "/__castle/pty";
 export declare const VENDOR_PREFIX = "/__castle/vendor/";
@@ -8,7 +9,7 @@ export declare const FAVICON_FILES: string[];
 export declare const FAVICON_LINK_TAGS: string;
 export declare const FILES_API_PREFIX = "/__castle/files/";
 export declare const COVER_API_PATH = "/__castle/cover";
-export declare const COVER_FILE = "preview.png";
+export { COVER_FILE };
 export declare function rawDataToString(data: RawData): string;
 export interface IdeServer {
     /** Serve the IDE page + its static assets. Returns true if it handled the request. */

package/dist/ide.js

@@ -20,6 +20,8 @@ import { readEditorConfig, resolveFileTypes, } from './editorConfig.js';
 import { UNSUPPORTED_MEDIA } from './unsupportedMedia.js';
 import { IMPORT_API_PREFIX, handleImportApi } from './importBrowse.js';
 import { readRequestBody, sendJson } from './httpJson.js';
+import { COVER_FILE } from './localPaths.js';
+import { applyVersionRestore, createVersion, NotOnThisLine, pendingChanges, UnsavedChanges, versionSummaries, } from './versions.js';
 import { envForUserShell, installCliShims } from './byo-auth.js';
 const HeadlessTerminal = headlessPkg.Terminal;
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -140,10 +142,22 @@ export const FILES_API_PREFIX = '/__castle/files/';
 // upload deliberately refuses to clobber. A cover is platform vocabulary, not a
 // kit's -- `save-deck` is what publishes preview.png -- so it belongs here.
 export const COVER_API_PATH = '/__castle/cover';
-export const COVER_FILE = 'preview.png';
+// Re-exported so `save-deck` and anything else that already asks the serve for
+// the cover's name keeps working.
+export { COVER_FILE };
 // Directories never surfaced in the file list / never read or written through
 // the builtin editor: VCS, deck-private state, and dependency trees.
 const FILES_IGNORE_DIRS = new Set(['.git', '.castle', 'node_modules', 'dist']);
+// Never writable through the files API, whatever the tree shows. `.castle` holds
+// the deck's private state, and since build 1 that includes the version store --
+// the one place where losing bytes loses history rather than a file. The list
+// above is about what the tree SHOWS and could reasonably change; this is about
+// what a write may touch, so the store stays safe if it ever does.
+//
+// A guard, not a lock: the directory keeps its normal permissions. Making it
+// read-only and unlocking around writes races with concurrent processes, gets
+// clobbered by tools, and still would not stop a raw shell write.
+const PROTECTED_WRITE_DIRS = new Set(['.castle']);
 // Ceiling on one uploaded file. A deck is saved whole (source tar + bundle), so
 // a huge asset is a problem for the deck long before it is a problem here --
 // refuse it at the door with a message rather than let it land and break `save`.
@@ -197,6 +211,12 @@ function resolveDeckPath(deckDir, requestedPath, opts = {}) {
         return { ok: false, error: `Path outside the deck: ${requestedPath}` };
     }
     const parts = normalized.split(path.sep);
+    if (opts.mutation && parts.some((p) => PROTECTED_WRITE_DIRS.has(p))) {
+        return {
+            ok: false,
+            error: `${requestedPath} is the deck's own state (the version store lives here) and is not writable.`,
+        };
+    }
     if (parts.some((p) => FILES_IGNORE_DIRS.has(p))) {
         return { ok: false, error: `Protected deck path: ${requestedPath}` };
     }
@@ -250,7 +270,9 @@ function listDeckFiles(deckDir) {
 // editors, and the builtin code editor renders everything.
 function kitEditorExtensions(config, fileTypes) {
     if (fileTypes) {
-        return fileTypes.filter((t) => t.editor === 'kit').map((t) => t.ext);
+        // ANY declared editor means "not the builtin code editor" -- the legacy
+        // "kit" (this deck's own dispatcher) and a named module both count.
+        return fileTypes.filter((t) => Boolean(t.editor)).map((t) => t.ext);
     }
     // A deck saved before file types existed named its kit extensions directly.
     return config.extensions ?? [];
@@ -345,6 +367,61 @@ function sendFailure(res, action, rel, err) {
     const message = err instanceof Error ? err.message : String(err);
     sendJson(res, 500, { error: `Could not ${action} ${rel}: ${message}` });
 }
+// The version panel's three calls, on the same store the `save-version` /
+// `restore-version` commands use -- the editor is another way to run them, not
+// a second history.
+function handleVersionsList(deckDir, res) {
+    try {
+        // The history and what is outstanding against it, together: the panel shows
+        // them as one picture, and two calls could disagree about the moment.
+        sendJson(res, 200, { versions: versionSummaries(deckDir), pending: pendingChanges(deckDir) });
+    }
+    catch (e) {
+        sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+    }
+}
+// Saves everything dirty: the panel has no path selection, so partial saves
+// stay a CLI and agent thing.
+function handleVersionSave(deckDir, req, res) {
+    withJsonBody(req, res, (body) => {
+        const message = typeof body.message === 'string' ? body.message : '';
+        try {
+            const { version } = createVersion(deckDir, { message });
+            sendJson(res, 200, { ok: true, id: version?.id ?? null });
+        }
+        catch (e) {
+            sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+        }
+    });
+}
+// Never forced. Unsaved work that a restore would overwrite comes back as a 409
+// naming the files, which the panel shows -- saving a version first is the fix,
+// and it is one click away in the same panel.
+function handleVersionRestore(deckDir, req, res) {
+    withJsonBody(req, res, (body) => {
+        if (typeof body.id !== 'string' || !body.id) {
+            return sendJson(res, 400, { error: 'Missing version id.' });
+        }
+        try {
+            const outcome = applyVersionRestore(deckDir, body.id);
+            sendJson(res, 200, {
+                ok: true,
+                restored: outcome.applied.length,
+                offChain: outcome.offChain,
+                alreadyThere: outcome.alreadyThere,
+            });
+        }
+        catch (e) {
+            // Both refusals are answers, not faults: the caller asked for something
+            // this history can't do, and the message says which.
+            const refused = e instanceof UnsavedChanges || e instanceof NotOnThisLine;
+            const message = e instanceof Error ? e.message : String(e);
+            sendJson(res, refused ? 409 : 500, {
+                error: e instanceof UnsavedChanges ? `${message}\nSave a version first.` : message,
+            });
+        }
+    });
+}
 function handleFilesWrite(deckDir, req, res) {
     withMutationPath(deckDir, req, res, (target, body) => {
         if (typeof body.contents !== 'string') {
@@ -686,6 +763,18 @@ function handleFilesApi(deckDir, req, res, reqPath) {
         })();
         return true;
     }
+    if (action === 'versions') {
+        handleVersionsList(deckDir, res);
+        return true;
+    }
+    if (action === 'save-version') {
+        handleVersionSave(deckDir, req, res);
+        return true;
+    }
+    if (action === 'restore-version') {
+        handleVersionRestore(deckDir, req, res);
+        return true;
+    }
     if (action === 'list') {
         // `?all=1` returns the unfiltered listing (the "show hidden files & folders"
         // toggle) -- still minus the always-ignored dirs (node_modules/.castle/...),

package/dist/index.js

@@ -10,6 +10,7 @@ import { listDecks } from './list-decks.js';
 import { getCliVersion, init } from './init.js';
 import { install } from './install.js';
 import { connectWS, savePreviewImage, takeScreenshot } from './preview.js';
+import { listVersions, restoreVersion, saveVersion, showVersion } from './versions.js';
 const args = process.argv.slice(2);
 const command = args[0];
 const FLAGS_WITH_VALUES = new Set([
@@ -23,10 +24,19 @@ const FLAGS_WITH_VALUES = new Set([
     '--visibility',
     '--as',
     '--kind',
+    '--dir',
+    '--message',
+    '-m',
 ]);
+// `--foo` is always a flag; a single dash only when it is one we know (`-m`).
+// Anything else starting with `-` is a positional -- a path can begin with one,
+// and so can an opaque version id.
+function isFlag(arg) {
+    return arg.startsWith('--') || FLAGS_WITH_VALUES.has(arg);
+}
 function findPositionalDir() {
     for (let i = 1; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
+        if (isFlag(args[i])) {
             if (FLAGS_WITH_VALUES.has(args[i]))
                 i++;
             continue;
@@ -41,7 +51,7 @@ function findPositionalDir() {
 function readPositionals() {
     const out = [];
     for (let i = 1; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
+        if (isFlag(args[i])) {
             if (FLAGS_WITH_VALUES.has(args[i]))
                 i++;
             continue;
@@ -88,6 +98,10 @@ function usage() {
   castle-web add-import <deckId|url> [dir] [--as ALIAS]   (adds another deck as a read-only dependency in imports/)
   castle-web update-import [alias] [dir] [--check] [--revert]   (re-fetches imports; no alias means all)
   castle-web install [dir]
+  castle-web save-version [-m MESSAGE] [paths...] [--dir DIR]   (no paths saves the whole deck)
+  castle-web list-versions [version] [--dir DIR]   (defaults to the latest version)
+  castle-web show-version <version> [--dir DIR]   (diffs of the files that version changed)
+  castle-web restore-version <version> [--force] [--dir DIR]
   castle-web login
   castle-web --version
 
@@ -173,6 +187,38 @@ async function main() {
             await install(findPositionalDir());
             break;
         }
+        // The version commands spend their positionals on their own arguments --
+        // paths to save, a version to list from or restore to -- so the deck dir is
+        // `--dir`, defaulting to the cwd.
+        case 'save-version': {
+            saveVersion(getFlagValue('--dir') ?? '.', {
+                message: getFlagValue('-m') ?? getFlagValue('--message'),
+                paths: readPositionals(),
+            });
+            break;
+        }
+        case 'list-versions': {
+            listVersions(getFlagValue('--dir') ?? '.', readPositionals()[0]);
+            break;
+        }
+        case 'show-version': {
+            const target = readPositionals()[0];
+            if (!target) {
+                console.error('Usage: castle-web show-version <version>');
+                process.exit(1);
+            }
+            showVersion(getFlagValue('--dir') ?? '.', target);
+            break;
+        }
+        case 'restore-version': {
+            const target = readPositionals()[0];
+            if (!target) {
+                console.error('Usage: castle-web restore-version <version> [--force]');
+                process.exit(1);
+            }
+            restoreVersion(getFlagValue('--dir') ?? '.', target, { force: hasFlag('--force') });
+            break;
+        }
         case 'restart': {
             const dir = findPositionalDir();
             const wsPort = getWsPort(dir);

package/dist/init.js

@@ -6,6 +6,7 @@ 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';
+import { createVersion } from './versions.js';
 const INDEX_HTML = `<!DOCTYPE html>
 <html>
 <head>
@@ -386,6 +387,34 @@ function scaffoldFromKitImport(kit, projectDir) {
     appendCommonInstructions(projectDir);
     lockImportTree(importDir);
 }
+// The scaffold as version 1, so a creator can always get back to the pristine
+// deck. AFTER the install: it rewrites package.json and writes a lockfile, so a
+// version taken before it describes a tree that never existed on disk, and a
+// later restore would fight the package manager.
+//
+// This is the ordinary save path with no parent -- `parentId: null` and every
+// file as an addition -- so the store has no special case for it. It composes
+// with the no-op rule for free: `save-version` straight after init records
+// nothing, so a fresh deck has exactly one version.
+//
+// The message is the only place a deck's kit lineage is recorded at all.
+// Existing decks get none of this: their history starts at their first save,
+// because a baseline synthesized from mid-work content would be labelled
+// pristine while being nothing of the sort.
+function saveInitialVersion(projectDir, kit) {
+    try {
+        const { version } = createVersion(projectDir, {
+            message: kit ? `New deck from ${kit}` : 'New deck',
+        });
+        if (version)
+            console.log(`Saved version ${version.id} — the deck as scaffolded.`);
+    }
+    catch (e) {
+        // A deck that scaffolded but failed to record its first version is still a
+        // deck. Losing the scaffold over it would be the wrong trade.
+        console.log(`Could not save the initial version: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
     if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
@@ -423,6 +452,7 @@ export async function init(dir, opts = {}) {
     catch {
         console.error('dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.');
     }
+    saveInitialVersion(projectDir, bare ? null : kit);
     const autoServe = opts.serve !== false;
     if (autoServe && installed) {
         // Call serve() with detach so init returns once the server is up. serve()

package/dist/localPaths.d.ts

@@ -3,4 +3,5 @@ export declare function getRepoRoot(): string;
 export declare function getCliEntryPath(): string;
 export declare function getSdkPackagePath(): string;
 export declare function getKitsDir(): string;
+export declare const COVER_FILE = "preview.png";
 export declare function toPosixPath(filepath: string): string;

package/dist/localPaths.js

@@ -28,6 +28,11 @@ export function getKitsDir() {
         return bundled;
     return path.join(getRepoRoot(), 'kits');
 }
+// The deck's local cover image, deck-relative. Lives here rather than in the
+// serve that writes it, because the version code needs to know about it too and
+// `ide.ts` already imports that -- naming it here keeps the two from importing
+// each other.
+export const COVER_FILE = 'preview.png';
 export function toPosixPath(filepath) {
     return filepath.split(path.sep).join('/');
 }