castle-web-cli 0.4.122 → 0.4.123

package/dist/versions.js

@@ -0,0 +1,446 @@
+// save-version / list-versions / restore-version.
+//
+// A version is a manual commit of the deck's files. Storage details are in
+// versionStore.ts; this file is the behavior:
+//
+//   save-version              hashes the whole tree and records what moved
+//   save-version <paths...>   records ONLY those paths -- a curated state, not
+//                             the working tree at that moment
+//   list-versions [<id>]      walks back from head (or from the given version)
+//   restore-version <id>      puts the working tree back to that version,
+//                             touching only paths some later version touched
+import * as fs from 'fs';
+import * as path from 'path';
+import { customAlphabet } from 'nanoid';
+import { looksBinary, unifiedDiff } from './diffText.js';
+import { COVER_FILE } from './localPaths.js';
+import * as store from './versionStore.js';
+// Version ids are alphanumeric on purpose: they are filenames, command-line
+// positionals and (later) url segments, and nanoid's default alphabet includes
+// `-`, which reads as a flag wherever an id is typed.
+const newVersionId = customAlphabet('0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', 12);
+function resolveProjectDir(dir) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(projectDir))
+        throw new Error(`No such directory: ${projectDir}`);
+    return projectDir;
+}
+// A path on the command line may name a directory, which stands for every
+// tracked file under it -- on disk AND in the parent manifest, so deleting a
+// whole directory and saving it still records the deletions.
+function expandSelection(projectDir, given, parentFiles) {
+    const workingFiles = store.walkDeckFiles(projectDir);
+    const selected = new Set();
+    for (const raw of given) {
+        const rel = store.toDeckRelative(projectDir, raw);
+        if (!rel)
+            throw new Error(`Path is outside the deck: ${raw}`);
+        if (store.isIgnoredPath(rel))
+            throw new Error(`Path is not tracked: ${rel}`);
+        const isDir = fs.existsSync(path.join(projectDir, rel)) && fs.statSync(path.join(projectDir, rel)).isDirectory();
+        if (isDir) {
+            const prefix = `${rel}/`;
+            for (const p of workingFiles)
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            for (const p of Object.keys(parentFiles))
+                if (p.startsWith(prefix))
+                    selected.add(p);
+            continue;
+        }
+        if (!fs.existsSync(path.join(projectDir, rel)) && !(rel in parentFiles)) {
+            throw new Error(`No such file: ${rel}`);
+        }
+        selected.add(rel);
+    }
+    return [...selected].sort();
+}
+// The whole tree becomes the manifest. Content is stored as we go, so an
+// unchanged file costs a read and a hash and writes nothing new.
+function manifestFromTree(projectDir) {
+    const files = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+    }
+    return files;
+}
+// The parent's manifest with only the selected paths overridden. Everything
+// else keeps the parent's hash -- so the version describes a curated state, and
+// the paths left out stay dirty on disk for the next save to pick up.
+function manifestFromSelection(projectDir, parentFiles, selected) {
+    const files = { ...parentFiles };
+    for (const rel of selected) {
+        const hash = store.storeWorkingFile(projectDir, rel);
+        if (hash)
+            files[rel] = hash;
+        else
+            delete files[rel];
+    }
+    return files;
+}
+// The save itself, with no output -- what the CLI command and the editor's
+// Save version button both run.
+export function createVersion(projectDir, opts = {}) {
+    const parentId = store.readHead(projectDir);
+    const parentFiles = store.parentManifest(projectDir, parentId);
+    const given = opts.paths ?? [];
+    const selected = given.length > 0 ? expandSelection(projectDir, given, parentFiles) : null;
+    const files = selected
+        ? manifestFromSelection(projectDir, parentFiles, selected)
+        : manifestFromTree(projectDir);
+    const changes = store.diffManifests(parentFiles, files, selected ?? undefined);
+    if (Object.keys(changes).length === 0)
+        return { version: null, partial: selected !== null };
+    const version = {
+        id: newVersionId(),
+        parentId,
+        createdAt: new Date().toISOString(),
+        message: opts.message ?? '',
+        files,
+        changes,
+    };
+    store.writeVersion(projectDir, version);
+    store.writeHead(projectDir, version.id);
+    return { version, partial: selected !== null };
+}
+export function saveVersion(dir, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    const { version, partial } = createVersion(projectDir, opts);
+    if (!version) {
+        console.log(partial ? 'No changes in the selected paths. Nothing saved.' : 'No changes. Nothing saved.');
+        return;
+    }
+    const changes = version.changes;
+    const count = Object.keys(changes).length;
+    console.log(`Saved version ${version.id} (${count} file${count === 1 ? '' : 's'} changed).`);
+    for (const [p, change] of Object.entries(changes)) {
+        const mark = change.before === null ? 'added' : change.after === null ? 'deleted' : 'changed';
+        console.log(`  ${mark}  ${p}`);
+    }
+    if (partial) {
+        console.log('Partial save: unselected files are still dirty on disk.');
+    }
+}
+// The deck cover is rewritten every time the deck is played, so it is
+// permanently dirty. It is versioned and restored like any other file, but it
+// never counts as a change worth reporting and never blocks a restore -- the
+// old cover it writes back regenerates on the next play. Without this, every
+// restore refused on a file nobody edited.
+function isReportableChange(path) {
+    return path !== COVER_FILE;
+}
+function changeKind(change) {
+    if (change.before === null)
+        return 'added';
+    if (change.after === null)
+        return 'deleted';
+    return 'changed';
+}
+/**
+ * What has changed on disk since head, in the same shape a version's `changes`
+ * takes. Hashes the tree WITHOUT storing anything -- asking what is outstanding
+ * must not write to the store.
+ */
+export function pendingChanges(projectDir) {
+    const headFiles = store.parentManifest(projectDir, store.readHead(projectDir));
+    const current = {};
+    for (const rel of store.walkDeckFiles(projectDir)) {
+        const hash = store.hashWorkingFile(projectDir, rel);
+        if (hash)
+            current[rel] = hash;
+    }
+    return Object.entries(store.diffManifests(headFiles, current))
+        .filter(([path]) => isReportableChange(path))
+        .map(([path, change]) => ({ path, kind: changeKind(change) }));
+}
+function toSummary(version, later) {
+    return {
+        id: version.id,
+        parentId: version.parentId,
+        createdAt: version.createdAt,
+        message: version.message,
+        changes: Object.entries(version.changes)
+            .filter(([path]) => isReportableChange(path))
+            .map(([path, change]) => ({ path, kind: changeKind(change) })),
+        later,
+    };
+}
+/**
+ * The deck's history newest first. From head (no `fromId`): the chain forward
+ * from head -- marked `later` -- then head, then its ancestors. From a named
+ * version: that version and its ancestors, as it has always been.
+ *
+ * The forward walk is why a restore no longer makes the versions after it
+ * vanish from the panel and from `list-versions`. It follows one chain of
+ * children, newest child at each step. After a save there is nothing to follow,
+ * because the new version is a leaf, so the forward rows drop away on their own
+ * -- the abandoned versions are still on disk, just no longer reachable forward
+ * from head.
+ *
+ * Naming a version asks a different question -- how did THIS version come to be
+ * -- so that form stays a walk back and is unchanged.
+ */
+export function versionSummaries(projectDir, fromId) {
+    const startId = fromId ?? store.readHead(projectDir);
+    if (!startId)
+        return [];
+    if (!store.versionExists(projectDir, startId))
+        throw new Error(`No such version: ${startId}`);
+    const forward = fromId ? [] : store.forwardChain(projectDir, startId);
+    return [
+        // Nearest child first out of the walk, so reverse it: the furthest
+        // descendant is the newest thing there is.
+        ...[...forward].reverse().map((v) => toSummary(v, true)),
+        ...store.versionChain(projectDir, startId).map((v) => toSummary(v, false)),
+    ];
+}
+export function listVersions(dir, version) {
+    const summaries = versionSummaries(resolveProjectDir(dir), version);
+    if (summaries.length === 0) {
+        console.log('No versions yet.');
+        return;
+    }
+    for (const v of summaries) {
+        const count = v.changes.length;
+        const message = v.message ? `  ${v.message}` : '';
+        // The same history the panel shows, marked the same way, so the two never
+        // disagree about what happened.
+        const later = v.later ? '  (later)' : '';
+        console.log(`${v.id}  ${v.createdAt}  ${count} file${count === 1 ? '' : 's'}${later}${message}`);
+    }
+}
+// One file's side of a change, as text -- or null when it wasn't there (an add
+// or a delete) and `binary: true` when it must not be rendered as a patch.
+function blobText(projectDir, hash) {
+    if (hash === null)
+        return null;
+    const content = store.getBlob(projectDir, hash);
+    return looksBinary(content) ? { text: '', binary: true } : { text: content.toString('utf8'), binary: false };
+}
+function showFileChange(projectDir, filePath, change) {
+    const kind = changeKind(change);
+    const before = blobText(projectDir, change.before);
+    const after = blobText(projectDir, change.after);
+    // A sprite or an image must never come out as a garbled patch; a line saying
+    // what happened to it is the whole useful answer.
+    if (before?.binary || after?.binary) {
+        console.log(`${filePath}  ${kind}, binary`);
+        return;
+    }
+    console.log(`${filePath}  ${kind}`);
+    const hunks = unifiedDiff(before?.text ?? '', after?.text ?? '');
+    if (!hunks) {
+        console.log('  (too large to show as a diff)');
+        return;
+    }
+    for (const line of hunks)
+        console.log(line);
+}
+/**
+ * What one version changed, as diffs of the CHANGED FILES ONLY -- built from the
+ * two blobs each entry in `changes` already names, so nothing new is stored and
+ * the whole tree is never read. The CLI counterpart of the panel's row
+ * expansion, for an agent working out what a change did.
+ */
+export function showVersion(dir, versionId) {
+    const projectDir = resolveProjectDir(dir);
+    if (!store.versionExists(projectDir, versionId))
+        throw new Error(`No such version: ${versionId}`);
+    const version = store.readVersion(projectDir, versionId);
+    const paths = Object.keys(version.changes).sort();
+    console.log(`${version.id}  ${version.createdAt}  ${paths.length} file${paths.length === 1 ? '' : 's'}`);
+    if (version.message)
+        console.log(version.message);
+    console.log('');
+    for (const filePath of paths) {
+        showFileChange(projectDir, filePath, version.changes[filePath]);
+        console.log('');
+    }
+}
+/**
+ * The versions from `from` back to `to`, exclusive of `to`, newest first -- or
+ * null when `to` is not an ancestor of `from`. Only `parentId` is stored, so
+ * this is the only direction the history can be walked directly.
+ */
+function chainDownTo(projectDir, from, to) {
+    const chain = [];
+    const seen = new Set();
+    let cursor = from;
+    while (cursor && cursor !== to) {
+        if (seen.has(cursor))
+            throw new Error(`Version history loops at ${cursor}`);
+        seen.add(cursor);
+        const version = store.readVersion(projectDir, cursor);
+        chain.push(version);
+        cursor = version.parentId;
+    }
+    return cursor === to ? chain : null;
+}
+/**
+ * What a restore should write, and what it expects to find on disk first.
+ *
+ * The two directions are mirrors of each other over the SAME set of versions --
+ * the ones between head and the target -- read from opposite ends:
+ *
+ *   backward (the target is an ancestor of head): put back the EARLIEST
+ *     `before`, the state closest to the target; expect the LATEST `after`, the
+ *     state closest to head.
+ *   forward (the target is a descendant of head): put back the LATEST `after`,
+ *     again the state closest to the target; expect the EARLIEST `before`,
+ *     again the state closest to head.
+ *
+ * Either way a path no version between the two touched never enters the plan,
+ * so unsaved work on it survives.
+ */
+function planRestore(projectDir, targetId) {
+    const head = store.readHead(projectDir);
+    if (!head)
+        throw new Error('No versions yet.');
+    const backward = chainDownTo(projectDir, head, targetId);
+    if (backward)
+        return planFromChain(backward, 'backward');
+    const forward = chainDownTo(projectDir, targetId, head);
+    if (forward)
+        return planFromChain(forward, 'forward');
+    throw new NotOnThisLine(targetId, head);
+}
+// `chain` is always newest first, so "first seen wins" reads the end nearest the
+// newer version and "last write wins" reads the end nearest the older one.
+function planFromChain(chain, direction) {
+    const plan = {
+        wanted: {},
+        expected: {},
+        offChain: direction === 'backward' ? chain.length : 0,
+    };
+    for (const version of chain) {
+        for (const [p, change] of Object.entries(version.changes)) {
+            if (direction === 'backward') {
+                plan.wanted[p] = change.before;
+                if (!(p in plan.expected))
+                    plan.expected[p] = change.after;
+            }
+            else {
+                if (!(p in plan.wanted))
+                    plan.wanted[p] = change.after;
+                plan.expected[p] = change.before;
+            }
+        }
+    }
+    return plan;
+}
+function removeEmptyParents(projectDir, relPath) {
+    let dir = path.dirname(path.join(projectDir, relPath));
+    while (dir.startsWith(projectDir) && dir !== projectDir) {
+        try {
+            if (fs.readdirSync(dir).length > 0)
+                return;
+            fs.rmdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        dir = path.dirname(dir);
+    }
+}
+function applyRestore(projectDir, actions) {
+    for (const [rel, hash] of actions) {
+        const abs = path.join(projectDir, rel);
+        if (hash === null) {
+            fs.rmSync(abs, { force: true });
+            removeEmptyParents(projectDir, rel);
+            continue;
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, store.getBlob(projectDir, hash));
+    }
+}
+// Work no version has recorded, which a restore would overwrite. The paths ARE
+// the answer to "what would I lose", so they ride on the error and each caller
+// says what to do about it -- the CLI offers `--force`, the panel has no such
+// thing and says to save a version first.
+export class UnsavedChanges extends Error {
+    paths;
+    constructor(paths) {
+        const count = paths.length;
+        super(`Unsaved changes would be lost in ${count} file${count === 1 ? '' : 's'}:\n` +
+            paths.map((p) => `  ${p}`).join('\n'));
+        this.name = 'UnsavedChanges';
+        this.paths = paths;
+    }
+}
+// A version on a different branch: neither an ancestor of head nor a descendant
+// of it. Restore moves along one line in either direction; getting from here to
+// there would mean merging, which is not something this build does silently.
+export class NotOnThisLine extends Error {
+    constructor(targetId, head) {
+        super(`Version ${targetId} is on a different branch than ${head}. ` +
+            'Restore moves back or forward along one line, not across a fork.');
+        this.name = 'NotOnThisLine';
+    }
+}
+// The restore itself, with no output. Throws on unsaved changes unless forced --
+// the message names every conflicting path, since that list IS the answer to
+// "what would I lose".
+export function applyVersionRestore(projectDir, targetId, opts = {}) {
+    if (!store.versionExists(projectDir, targetId))
+        throw new Error(`No such version: ${targetId}`);
+    if (store.readHead(projectDir) === targetId) {
+        return { alreadyThere: true, applied: [], offChain: 0 };
+    }
+    const plan = planRestore(projectDir, targetId);
+    // Only paths whose content would actually move are checked and applied: a
+    // path already holding what the restore wants is neither a conflict nor work.
+    const actions = [];
+    const conflicts = [];
+    for (const [rel, wanted] of Object.entries(plan.wanted)) {
+        const current = store.hashWorkingFile(projectDir, rel);
+        if (current === wanted)
+            continue;
+        // The cover is exempt: it is dirty by construction, so refusing on it would
+        // refuse every restore. It still gets written back.
+        if (current !== plan.expected[rel] && isReportableChange(rel))
+            conflicts.push(rel);
+        actions.push([rel, wanted]);
+    }
+    if (conflicts.length > 0 && !opts.force)
+        throw new UnsavedChanges(conflicts.sort());
+    applyRestore(projectDir, actions.sort((a, b) => a[0].localeCompare(b[0])));
+    // Head moves to the target, so the next save continues from there and the
+    // versions we walked past fork off. They stay on disk and stay loadable by
+    // id -- they are just no longer on head's chain.
+    store.writeHead(projectDir, targetId);
+    return { alreadyThere: false, applied: actions, offChain: plan.offChain };
+}
+export function restoreVersion(dir, targetId, opts = {}) {
+    const projectDir = resolveProjectDir(dir);
+    let outcome;
+    try {
+        outcome = applyVersionRestore(projectDir, targetId, opts);
+    }
+    catch (e) {
+        // Only the command line has a --force, so only the command line mentions it.
+        if (e instanceof UnsavedChanges) {
+            throw new Error(`${e.message}\nSave a version first, or pass --force to restore anyway.`);
+        }
+        throw e;
+    }
+    if (outcome.alreadyThere) {
+        console.log(`Already at version ${targetId}. Nothing to restore.`);
+        return;
+    }
+    const applied = outcome.applied;
+    if (applied.length === 0) {
+        console.log(`The working tree already matched version ${targetId}.`);
+    }
+    else {
+        console.log(`Restored ${applied.length} file${applied.length === 1 ? '' : 's'} to version ${targetId}.`);
+        for (const [rel, hash] of applied)
+            console.log(`  ${hash === null ? 'deleted' : 'restored'}  ${rel}`);
+    }
+    // A silent head move is the thing people discover a week later. What the move
+    // left behind needs no announcement: `list-versions` shows those versions,
+    // marked `(later)`.
+    console.log(`head is now ${targetId}.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.122",
+  "version": "0.4.123",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"