@coderook/cli 0.5.0 → 0.7.0

package/dist/cli/src/api.js

@@ -10,6 +10,7 @@ exports.resolveMergeConflict = resolveMergeConflict;
 exports.applyMerge = applyMerge;
 exports.cancelMerge = cancelMerge;
 /** The small part of the API the command-line tool needs directly. */
+const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const config_js_1 = require("./config.js");
 async function call(route, options = {}) {
     const token = await (0, config_js_1.loadToken)();
@@ -22,6 +23,7 @@ async function call(route, options = {}) {
             accept: "application/json",
             authorization: `Bearer ${token}`,
             "user-agent": "CodeRook-CLI/0.1",
+            ...(0, identify_js_1.clientHeaders)(),
             ...(options.body ? { "content-type": "application/json" } : {}),
         },
         body: options.body ? JSON.stringify(options.body) : undefined,

package/dist/cli/src/cli.js

@@ -22,6 +22,8 @@ const api_js_1 = require("./api.js");
 const worktree_js_1 = require("../../desktop-app/src/main/worktree.js");
 const upload_js_1 = require("../../desktop-app/src/main/upload.js");
 const download_js_1 = require("../../desktop-app/src/main/download.js");
+const faults_js_1 = require("../../desktop-app/src/main/faults.js");
+const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const cbx_js_1 = require("../../desktop-app/src/main/cbx.js");
 const api_js_2 = require("./api.js");
 const config_js_1 = require("./config.js");
@@ -38,6 +40,12 @@ const VERSION = (() => {
         return "0.0.0";
     }
 })();
+/*
+  Said once, before anything reaches the service. The version comes from the
+  package rather than a constant, so it cannot drift from what was published
+  and claim a behaviour this build does not have.
+*/
+(0, identify_js_1.declareClient)("cli", VERSION);
 // ── presentation ────────────────────────────────────────────────────────────
 const colour = node_process_1.default.stdout.isTTY && !node_process_1.default.env.NO_COLOR;
 const dim = (text) => (colour ? `${text}` : text);
@@ -270,9 +278,36 @@ async function commandStatus(parsed) {
 async function commandSubmit(parsed) {
     const folder = folderFor(parsed);
     const message = flagText(parsed, "m", "message") ?? "";
-    const { link, baseline } = await reconcile(folder);
+    const { link, baseline, behind } = await reconcile(folder);
     const rules = await (0, worktree_js_1.readRules)(folder);
     const files = await (0, worktree_js_1.changedFiles)(folder, rules, baseline);
+    /*
+      An upgraded folder with no materialisation record and something that
+      differs from its recorded version is ambiguous in the one way that
+      matters: the difference is either work to send, or a copy left behind by
+      somebody's merge. Sending the second reverts their change.
+  
+      While the folder is level with the project the question does not arise —
+      nothing can have merged underneath it — so only a folder that is behind
+      is stopped, and only until somebody says which it is.
+    */
+    if (link && !link.local && files.length && behind) {
+        if (await establishMaterialisation(folder, link)) {
+            link.local = { ...link.manifest };
+            await (0, config_js_1.writeLink)(folder, link);
+        }
+        else if (!hasFlag(parsed, "f", "force")) {
+            console.error(red("This folder was connected by an older version of CodeRook,"));
+            console.error("which did not record what it had received — and somebody");
+            console.error(`has saved since (the project is on v${behind.sequence}).\n`);
+            console.error(`${files.length} file${files.length === 1 ? " differs" : "s differ"} here:`);
+            for (const file of files.slice(0, 20))
+                console.error(`  ${file.path}`);
+            console.error(`\nIf that is your work, send it with ${accent("coderook submit --force")}.` +
+                `\nIf it is an old copy, take theirs with ${accent("coderook get --replace")}.`);
+            return 1;
+        }
+    }
     if (!files.length) {
         // Having nothing to send is not the same as holding the whole version:
         // a merge can leave this folder with an older copy of somebody else's
@@ -415,6 +450,20 @@ The connection failed: ${text}`));
         ` · version holds ${bytes(result.sourceBytes)}`);
     return 0;
 }
+/**
+ * Work out what an upgraded folder actually holds, or admit that it cannot.
+ *
+ * Returns the materialisation when the folder matches its recorded version
+ * exactly — which proves the manifest describes what is here — and null when
+ * anything differs, because a difference is either somebody's unsaved edit or
+ * a copy their merge left stale, and nothing on disk says which.
+ */
+async function establishMaterialisation(folder, link) {
+    const rules = await (0, worktree_js_1.readRules)(folder);
+    const against = new Map(Object.entries(link.manifest));
+    const differing = await (0, worktree_js_1.changedFiles)(folder, rules, against);
+    return differing.length ? null : { ...link.manifest };
+}
 async function commandGet(parsed) {
     const folder = folderFor(parsed);
     const { link } = await reconcile(folder);
@@ -433,7 +482,49 @@ async function commandGet(parsed) {
       copy. Only the edits are worth stopping for, and only when the incoming
       version would actually change those files.
     */
+    /*
+      A fetch that did not finish leaves the folder part-way to a version, with
+      the record still describing what was there before. Every difference it
+      shows is this operation's own work, not somebody's edit, so finishing the
+      job is the only sensible reading — and refusing would strand the folder in
+      the one state that ought to be easiest to leave.
+  
+      It could only have started if there was nothing conflicting here, so
+      completing it cannot bury anybody's changes.
+    */
+    const resuming = Boolean(link.fetching);
+    if (resuming) {
+        console.log(dim(`A fetch of v${link.fetching.sequence} did not finish; completing it.`));
+    }
     const replacing = hasFlag(parsed, "replace", "f", "force");
+    /*
+      A folder connected by a client older than the materialisation record has
+      only the Version manifest, which says what the project held — not what
+      was placed here. The two are the same only until somebody's merge makes
+      them differ, so assuming it would be the very guess that lost work in the
+      first place.
+  
+      It can be established rather than assumed: if the folder matches its own
+      recorded version exactly, then it demonstrably holds that version and the
+      manifest is the materialisation. If it does not match, an edit cannot be
+      told from a stale copy, and fetching is refused until somebody says which
+      it is.
+    */
+    if (!link.local) {
+        const settled = await establishMaterialisation(folder, link);
+        if (settled) {
+            link.local = settled;
+            await (0, config_js_1.writeLink)(folder, link);
+        }
+        else if (!replacing) {
+            console.error(red("This folder was connected by an older version of CodeRook,"));
+            console.error("which did not record what it had received, so changed files here");
+            console.error("cannot be told apart from copies left behind by a merge.\n");
+            console.error(`Save them with ${accent("coderook submit")} if they are your work, or ` +
+                `take the\nsaved version exactly with ${accent("coderook get --replace")}.`);
+            return 1;
+        }
+    }
     if (link.local && !replacing) {
         const rules = await (0, worktree_js_1.readRules)(folder);
         const edited = await (0, worktree_js_1.changedFiles)(folder, rules, new Map(Object.entries(link.local)));
@@ -446,6 +537,31 @@ async function commandGet(parsed) {
                     file.sha256,
                 ])
                 : []);
+            /*
+              Resuming needs a different question. Half these files differ from the
+              record because the interrupted run already replaced them, and those
+              are finished work rather than anybody's edit. What matters is a file
+              that matches neither what was here nor what is arriving — that one was
+              changed by hand while the fetch was stopped, and completing over it
+              would bury the only copy.
+            */
+            if (resuming) {
+                const notYetArrived = await (0, worktree_js_1.changedFiles)(folder, rules, incoming);
+                const changedInTheGap = notYetArrived.filter((file) => !file.deleted &&
+                    incoming.has(file.path) &&
+                    edited.some((one) => one.path === file.path));
+                if (!changedInTheGap.length) {
+                    return fetchInto(link.repositoryId, folder, link.slug, link.local ?? null, "replace");
+                }
+                console.error(red(`${changedInTheGap.length} file${changedInTheGap.length === 1 ? "" : "s"} ` +
+                    `changed while the interrupted fetch was stopped:`));
+                for (const file of changedInTheGap.slice(0, 20))
+                    console.error(`  ${file.path}`);
+                console.error(`
+Save them with ${accent("coderook submit")}, or finish the fetch and ` +
+                    `discard them with ${accent("coderook get --replace")}.`);
+                return 1;
+            }
             /*
               Only a genuine collision stops the fetch: this folder changed the
               file and so did the incoming version. An edit to a file the version
@@ -508,6 +624,18 @@ held, mode = "replace") {
         console.error(red("That project has no saved version."));
         return 1;
     }
+    /*
+      Recorded before the folder is touched. If this run does not reach the
+      end, the next one finds this and knows the differences it sees are its
+      own unfinished work rather than somebody's edits.
+    */
+    const before = await (0, config_js_1.readLink)(destination);
+    if (before) {
+        await (0, config_js_1.writeLink)(destination, {
+            ...before,
+            fetching: { versionId: latest.id, sequence: latest.sequence },
+        });
+    }
     const line = progressLine();
     const result = await downloader.run(repositoryId, latest.id, destination, (progress) => {
         line(`  ${String(progress.percent).padStart(3)}%  ${progress.files}/${progress.totalFiles}` +
@@ -527,7 +655,10 @@ held, mode = "replace") {
         // version holds and the two agree again.
         local: result.manifest,
         manifest: result.manifest,
+        // Reached the end, so there is no longer a fetch in flight.
     });
+    // The record is written; the run has not reported success yet.
+    (0, faults_js_1.maybeFail)("get:after-record");
     console.log(`${accent(`v${latest.sequence}`)} · ${result.files} files · ${bytes(result.bytes)} into ${destination}`);
     return 0;
 }

package/dist/desktop-app/src/main/download.js

@@ -15,6 +15,8 @@ exports.Downloader = exports.DownloadCancelled = void 0;
 const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
+const identify_js_1 = require("./identify.js");
+const faults_js_1 = require("./faults.js");
 async function exists(target) {
     try {
         await (0, promises_1.stat)(target);
@@ -83,11 +85,21 @@ class Downloader {
             headers: {
                 authorization: `Bearer ${token}`,
                 "user-agent": "CodeRook/0.1",
+                ...(0, identify_js_1.clientHeaders)(),
             },
             signal: this.controller.signal,
         });
         if (!response.ok) {
             const text = await response.text().catch(() => "");
+            /*
+              A refusal for being too old is not a network failure and must not read
+              like one: the person can fix it, and only if they are told how.
+            */
+            const tooOld = (0, identify_js_1.readRefusal)(response.status, text);
+            if (tooOld) {
+                throw new Error(`${tooOld.message} You are running ${tooOld.yourVersion ?? "an older build"}; ` +
+                    `update from ${tooOld.upgradeUrl}.`);
+            }
             let message = `${route} failed (${response.status})`;
             try {
                 message = JSON.parse(text)?.error?.message ?? message;
@@ -187,7 +199,10 @@ class Downloader {
               one volume is atomic, so no file is ever seen half-written, and
               anything the version does not mention is left exactly as it is.
             */
+            // Everything has arrived and verified; the folder is still untouched.
+            (0, faults_js_1.maybeFail)("get:after-staging");
             await (0, promises_1.mkdir)(destination, { recursive: true });
+            let placed = 0;
             for (const file of files) {
                 const parts = file.path.split("/").filter(Boolean);
                 const target = node_path_1.default.join(destination, ...parts);
@@ -206,6 +221,9 @@ class Downloader {
                 await (0, promises_1.mkdir)(node_path_1.default.dirname(target), { recursive: true });
                 await (0, promises_1.rm)(target, { recursive: true, force: true });
                 await (0, promises_1.rename)(node_path_1.default.join(staging, ...parts), target);
+                placed += 1;
+                if (placed === 1)
+                    (0, faults_js_1.maybeFail)("get:after-first-file");
             }
             /*
               A file this folder received but the version no longer holds is gone
@@ -229,7 +247,10 @@ class Downloader {
                     continue;
                 await (0, promises_1.rm)(target, { force: true });
                 await pruneEmpty(destination, target);
+                (0, faults_js_1.maybeFail)("get:after-delete");
             }
+            // The folder is now the new version; nothing has recorded that yet.
+            (0, faults_js_1.maybeFail)("get:before-record");
             await (0, promises_1.rm)(staging, { recursive: true, force: true });
             report({
                 files: written,

package/dist/desktop-app/src/main/faults.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Deliberate failure points, for proving that interruption recovers.
+ *
+ * Every operation that touches a folder is a sequence of individually correct
+ * steps, and the dangerous state is between two of them: half the files
+ * replaced, a deletion applied but the record not yet written, a version
+ * committed but never learned about. Those states cannot be reached by
+ * ordinary testing, because ordinary testing runs the sequence to the end.
+ *
+ * So the sequence can be cut, at named points, by setting an environment
+ * variable. Nothing here does anything at all unless that variable names a
+ * point — there is no configuration, no flag and no code path that reaches it
+ * otherwise, which is what makes it safe to leave in the shipped build rather
+ * than maintaining a separate instrumented one that nobody ever runs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectedFault = void 0;
+exports.maybeFail = maybeFail;
+class InjectedFault extends Error {
+    point;
+    constructor(point) {
+        super(`Interrupted deliberately at ${point}`);
+        this.point = point;
+        this.name = "InjectedFault";
+    }
+}
+exports.InjectedFault = InjectedFault;
+/**
+ * Stop here, if this is the point somebody asked to be interrupted at.
+ *
+ * Reads the environment on every call rather than caching it, so a test can
+ * drive several runs in one process without the first one deciding for all
+ * the others.
+ */
+function maybeFail(point) {
+    if (process.env.CODEROOK_FAULT === point)
+        throw new InjectedFault(point);
+}

package/dist/desktop-app/src/main/identify.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declareClient = declareClient;
+exports.clientHeaders = clientHeaders;
+exports.readRefusal = readRefusal;
+/** Set once at start-up, because the two clients learn their version differently. */
+let identity = "";
+function declareClient(kind, version) {
+    identity = `${kind}/${version}`;
+}
+/**
+ * The identifying headers, or nothing when start-up has not declared yet.
+ *
+ * Returning nothing rather than a guess matters: an unrecognised client is
+ * allowed through, so a wrong guess would be worse than silence — it would
+ * claim a version whose behaviour this build does not have.
+ */
+function clientHeaders() {
+    return identity ? { "x-coderook-client": identity } : {};
+}
+function readRefusal(status, body) {
+    if (status !== 426)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        const error = parsed.error;
+        if (!error || error.code !== "client_too_old")
+            return null;
+        return {
+            capability: String(error.capability ?? "that"),
+            minimumSupported: String(error.minimumSupported ?? "a newer version"),
+            yourVersion: error.yourVersion ? String(error.yourVersion) : null,
+            upgradeUrl: String(error.upgradeUrl ?? "https://coderook.com/download"),
+            message: String(error.message ?? "This version is too old."),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/desktop-app/src/main/upload.js

@@ -16,6 +16,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
+const identify_js_1 = require("./identify.js");
 const worktree_js_1 = require("./worktree.js");
 const publish_name_js_1 = require("./publish_name.js");
 /** Above this the API insists on a multipart session. */
@@ -87,6 +88,7 @@ class Uploader {
                 accept: "application/json",
                 authorization: `Bearer ${token}`,
                 "user-agent": "CodeRook/0.1",
+                ...(0, identify_js_1.clientHeaders)(),
                 ...(init.contentType ? { "content-type": init.contentType } : {}),
             },
             body: init.body,

package/package.json

@@ -1,42 +1,45 @@
-{
-  "name": "@coderook/cli",
-  "version": "0.5.0",
-  "description": "CodeRook from the command line, on any operating system",
-  "license": "SEE LICENSE IN LICENSE.txt",
-  "homepage": "https://coderook.com",
-  "bugs": {
-    "url": "https://coderook.com/contact"
-  },
-  "keywords": [
-    "coderook",
-    "versioning",
-    "backup",
-    "cbx"
-  ],
-  "engines": {
-    "node": ">=20.11.0"
-  },
-  "bin": {
-    "coderook": "dist/cli/src/cli.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit",
-    "test": "tsc -p tsconfig.json && node --test --experimental-strip-types test/*.test.ts",
-    "start": "node dist/cli/src/cli.js",
-    "prepublishOnly": "npm run build",
-    "test:e2e": "node test/e2e.mjs",
-    "test:matrix": "node test/state-matrix.mjs",
-    "test:attempt": "node test/attempt-identity.mjs",
-    "test:get": "node test/get-safety.mjs",
-    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
-    "test:getedits": "node test/get-protects-edits.mjs"
-  },
-  "devDependencies": {
-    "@types/node": "24.10.1",
-    "typescript": "5.9.3"
-  }
-}
+{
+  "name": "@coderook/cli",
+  "version": "0.7.0",
+  "description": "CodeRook from the command line, on any operating system",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "homepage": "https://coderook.com",
+  "bugs": {
+    "url": "https://coderook.com/contact"
+  },
+  "keywords": [
+    "coderook",
+    "versioning",
+    "backup",
+    "cbx"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "bin": {
+    "coderook": "dist/cli/src/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json && node --test --experimental-strip-types test/*.test.ts",
+    "start": "node dist/cli/src/cli.js",
+    "prepublishOnly": "npm run build",
+    "test:e2e": "node test/e2e.mjs",
+    "test:matrix": "node test/state-matrix.mjs",
+    "test:attempt": "node test/attempt-identity.mjs",
+    "test:get": "node test/get-safety.mjs",
+    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/upgrade-migration.mjs --allow-production && node test/fault-get.mjs --allow-production && node test/version-floor.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
+    "test:getedits": "node test/get-protects-edits.mjs",
+    "test:upgrade": "node test/upgrade-migration.mjs",
+    "test:faultget": "node test/fault-get.mjs",
+    "test:floor": "node test/version-floor.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "typescript": "5.9.3"
+  }
+}