@coderook/cli 0.12.0 → 0.14.0

package/README.md

@@ -59,13 +59,51 @@ the desktop is recognised rather than treated as new.
 uploaded again, and the version it records still names every file in the
 project — a version is a snapshot, not a difference.
 
+## Lines of work
+
+A project can have more than one line, so two people can save without one
+landing on top of the other.
+
+```
+coderook tracks                    the lines this project has
+coderook track                     the line this folder saves to
+coderook track spike --new         start a line and switch to it
+coderook track main                switch back
+coderook submit --track spike -m "Try the other encoder"
+```
+
+Switching says where the next save goes and nothing else. No files move and
+nothing is fetched, so it is instant and safe to change your mind — run
+`coderook get` afterwards to bring that line's files into the folder.
+
+The line is remembered per folder, not per account, so two checkouts of one
+project can sit on different lines. A folder that has never been switched
+saves to `main`, which is what every folder meant before lines existed.
+
+A name that does not exist is refused rather than created. A typo in a branch
+name is an ordinary thing to do, and a line called `mian` puts work somewhere
+nobody will look for it — `--new` is how you say you meant it.
+
+If two saves land on the same line anyway, the second becomes a merge waiting
+on a decision. `coderook merges` lists them and `coderook merge <ref>` walks
+through it; `coderook tracks` shows them beside the ordinary lines, because
+somebody looking for where they can save needs to see the one they cannot.
+
 ## Ignore rules
 
 ```
-coderook rules            show the rules in force
-coderook rules --init     write a starter .gitignore
+coderook rules                      show the rules in force
+coderook rules --init               write a starter .gitignore
+coderook rules --suggest            what is here that probably should not be sent
+coderook rules --suggest --apply    add the confident ones
 ```
 
+`--suggest` looks at what the folder would actually send and names the
+dependency directories, virtual environments and build output in it, with how
+much each is costing you. Lines marked `+` are safe to assume and are the ones
+`--apply` writes; anything that might be the work itself is marked `?` and left
+for you, because the cost of guessing wrong is a project that is not backed up.
+
 Rules live in the project's own `.gitignore`, so CodeRook, git, the website
 and the desktop application all read one file. A `!` line puts something back.
 Personal exclusions that should not reach a collaborator belong in
@@ -84,6 +122,37 @@ it helps, raw where it does not, and a SHA-256 for every chunk and file.
 Extraction is verified and atomic — a damaged bundle fails rather than leaving
 a half-written tree.
 
+## Claude Code and Codex
+
+CodeRook can be a tool your assistant uses while it works. Both speak the same
+protocol, so one server covers them.
+
+Claude Code:
+
+```
+claude mcp add coderook -- coderook mcp
+```
+
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.coderook]
+command = "coderook"
+args = ["mcp"]
+```
+
+It offers five things, all of which read: your projects, a project's versions,
+the files in a version, one file's contents at a version, and what has changed
+in a local folder.
+
+It cannot save a version, delete anything, or sign in or out. That is
+deliberate — an assistant that goes wrong can waste your time but not your
+work, and saving stays something a person types. A project whose owner has
+turned off machine reading is refused in words rather than as a status code.
+
+The server is launched by the assistant and exits with it; there is no reason
+to run `coderook mcp` by hand.
+
 ## Checking things
 
 ```

package/dist/cli/src/cli.js

@@ -24,12 +24,15 @@ const registry_js_1 = require("./registry.js");
 const help_js_1 = require("./help.js");
 const progress_js_1 = require("./progress.js");
 const project_commands_js_1 = require("./project_commands.js");
+const track_commands_js_1 = require("./track_commands.js");
+const mcp_js_1 = require("./mcp.js");
 const service_commands_js_1 = require("./service_commands.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 detect_js_1 = require("../../desktop-app/src/main/detect.js");
 const cbx_js_1 = require("../../desktop-app/src/main/cbx.js");
 const api_js_2 = require("./api.js");
 const runner_js_1 = require("./runner.js");
@@ -379,6 +382,14 @@ async function commandSubmit(parsed) {
             message,
             projectName: link?.slug ?? node_path_1.default.basename(folder),
             repositoryId: link?.repositoryId ?? null,
+            /*
+              The line this save belongs on: named on the command, or whichever one
+              the folder is set to. Sent by name rather than resolved here, because
+              the service owns the rules about which names exist and which may be
+              written to — a rule enforced in two places is one that will disagree
+              with itself.
+            */
+            track: flagText(parsed, "track") ?? (await (0, track_commands_js_1.trackFor)(folder)),
             /*
               Only claimed when this folder has actually been reconciled with a
               known version. A folder linked before versions were recorded says
@@ -409,7 +420,7 @@ async function commandSubmit(parsed) {
           difference between a person retrying and a person wondering.
         */
         if (!code && /fetch failed|ECONNRESET|socket hang up|network|ETIMEDOUT/i.test(text)) {
-            console.error(red(`
+            console.error(red(`
 The connection failed: ${text}`));
             console.error(`Your work may already have been saved. Run the same command again —` +
                 ` it will not create a second version.`);
@@ -589,7 +600,7 @@ async function commandGet(parsed) {
                     `changed while the interrupted fetch was stopped:`));
                 for (const file of changedInTheGap.slice(0, 20))
                     console.error(`  ${file.path}`);
-                console.error(`
+                console.error(`
 Save them with ${accent("coderook submit")}, or finish the fetch and ` +
                     `discard them with ${accent("coderook get --replace")}.`);
                 return 1;
@@ -695,8 +706,66 @@ held, mode = "replace") {
     console.log(`${accent(`v${latest.sequence}`)} · ${result.files} files · ${bytes(result.bytes)} into ${destination}`);
     return 0;
 }
+/**
+ * What this folder is carrying that probably is not the work.
+ *
+ * The desktop offers these when a folder is added — a virtual environment, a
+ * node_modules, a build directory — and the command line never did, so a
+ * project set up from a terminal sent its dependencies to the service and
+ * paid for the storage. The detector is the desktop's own rather than a
+ * second opinion written here, because two rules about what counts as
+ * generated output is two answers to the same question.
+ *
+ * Nothing is written without being asked for. Listing is the default: a tool
+ * that silently edits your .gitignore is one you have to check up on.
+ */
+async function suggestRules(folder, apply) {
+    const rules = await (0, worktree_js_1.readRules)(folder);
+    const files = await (0, worktree_js_1.changedFiles)(folder, rules, null);
+    const suggestions = (0, detect_js_1.suggestExclusions)(await (0, worktree_js_1.fileSizes)(folder, files));
+    if (!suggestions.length) {
+        console.log(dim("Nothing here looks like it should be left out."));
+        return 0;
+    }
+    for (const one of suggestions) {
+        const mark = one.recommended ? green("+") : dim("?");
+        console.log(`${mark} ${one.pattern.padEnd(26)} ${dim(`${bytes(one.bytes)} · ${one.files} file${one.files === 1 ? "" : "s"} · ${one.reason}`)}`);
+    }
+    /*
+      Only the confident ones are written. Generated output and dependency
+      directories are safe to assume; anything that might be the work itself is
+      marked with a question and left for a person, because the cost of guessing
+      wrong is somebody's project not being backed up.
+    */
+    const recommended = suggestions.filter((one) => one.recommended);
+    if (!apply) {
+        console.log("");
+        console.log(dim("Add the + ones with ") + accent("coderook ignore --suggest --apply"));
+        return 0;
+    }
+    if (!recommended.length) {
+        console.log("");
+        console.log(dim("None of these are safe to assume — add them by hand."));
+        return 0;
+    }
+    const addition = (0, detect_js_1.rulesFromSuggestions)(recommended);
+    const shared = rules.shared.trimEnd();
+    await (0, worktree_js_1.writeRules)(folder, {
+        shared: shared ? `${shared}
+
+${addition}` : addition,
+        local: rules.local,
+    });
+    console.log("");
+    console.log(green(`Added ${recommended.length} rule${recommended.length === 1 ? "" : "s"} to `) +
+        node_path_1.default.join(folder, ".gitignore"));
+    return 0;
+}
 async function commandRules(parsed) {
     const folder = folderFor(parsed);
+    if (hasFlag(parsed, "suggest")) {
+        return suggestRules(folder, hasFlag(parsed, "apply"));
+    }
     if (hasFlag(parsed, "init")) {
         const existing = await (0, worktree_js_1.readRules)(folder);
         await (0, worktree_js_1.writeRules)(folder, {
@@ -810,7 +879,7 @@ async function commandMerges(parsed) {
         const counts = merge.conflicts;
         console.log(`${accent(merge.reference)}  ${counts ? `${counts.unresolved} of ${counts.total} still to decide` : ""}  ${dim(new Date(merge.createdAt).toLocaleString())}`);
     }
-    console.log(dim(`
+    console.log(dim(`
 Run coderook merge <reference> to look at one.`));
     return 0;
 }
@@ -876,7 +945,7 @@ async function commandMerge(parsed) {
         }
     }
     const now = await (0, api_js_1.mergeTrack)(summary.id);
-    console.log(`
+    console.log(`
 ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
         (now.provisional.ready
             ? "ready to apply"
@@ -891,19 +960,19 @@ ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
             return 1;
         }
         const applied = await (0, api_js_1.applyMerge)(summary.id);
-        console.log(`
+        console.log(`
 Applied as ${accent(`v${applied.version.sequence}`)}.`);
         console.log(dim("Run coderook get to bring it down to this folder."));
         return 0;
     }
     if (!decision) {
-        console.log(dim(`
+        console.log(dim(`
 --mine keeps yours, --theirs keeps what was already saved,` +
-            ` --drop removes the file.
+            ` --drop removes the file.
 Add --path <file> for one file, then --apply when ready.`));
     }
     else if (now.provisional.ready) {
-        console.log(dim(`
+        console.log(dim(`
 Run coderook merge ${now.mergeTrack.reference} --apply to publish it.`));
     }
     return 0;
@@ -1081,10 +1150,55 @@ const SPECS = [
             { flags: "-m, --message <text>", description: "what changed, in a sentence" },
             { flags: "-n, --dry-run", description: "show what would be sent, send nothing" },
             { flags: "--allow-secrets", description: "send files that look like credentials" },
+            {
+                flags: "--track <name>",
+                description: "save onto this line, just this once",
+            },
+        ],
+        examples: [
+            'coderook submit -m "Fix the export dialog"',
+            'coderook submit --track spike -m "Try the other encoder"',
         ],
-        examples: ['coderook submit -m "Fix the export dialog"'],
         run: commandSubmit,
     },
+    {
+        /*
+          Where the next save goes, which is a property of this folder rather
+          than of the account — two checkouts of one project can sit on
+          different lines, which is most of the point of having them.
+        */
+        name: "track",
+        aliases: ["switch"],
+        group: "Working with a folder",
+        summary: "show or change the line this folder saves to",
+        usage: "track [name]",
+        detail: "With no name, prints the line this folder saves to. With one, switches\n" +
+            "to it. Switching says where the next save goes and nothing else: no\n" +
+            "files move and nothing is fetched, so it is instant and safe to change\n" +
+            "your mind. Run `coderook get` afterwards to bring that line's files\n" +
+            "into the folder.\n\n" +
+            "A name that does not exist is refused rather than created, because a\n" +
+            "typo in a branch name is an ordinary thing to do and a line called\n" +
+            "`mian` puts work somewhere nobody will look for it. Pass --new to\n" +
+            "start one deliberately.",
+        options: [
+            { flags: "-n, --new", description: "start this line from where the project is now" },
+        ],
+        examples: ["coderook track", "coderook track spike --new", "coderook track main"],
+        run: track_commands_js_1.commandTrack,
+    },
+    {
+        name: "tracks",
+        group: "Your projects",
+        summary: "the lines a project has, and any waiting on a decision",
+        usage: "tracks [project]",
+        detail: "Lists every line on the project, marking the one this folder saves to.\n" +
+            "Merges waiting on a decision are listed beside them rather than hidden,\n" +
+            "because somebody looking for where they can save needs to see the one\n" +
+            "they cannot. Finish one with `coderook merge`.",
+        examples: ["coderook tracks", "coderook tracks my-project"],
+        run: track_commands_js_1.commandTracks,
+    },
     {
         name: "get",
         group: "Working with a folder",
@@ -1111,7 +1225,17 @@ const SPECS = [
         detail: "The local list of things not to send — build output, dependencies,\n" +
             "anything private. Unrelated to a project's rules on the service, which\n" +
             "are about who may do what.",
-        options: [{ flags: "--init", description: "write a starting set of rules" }],
+        options: [
+            { flags: "--init", description: "write a starting set of rules" },
+            {
+                flags: "--suggest",
+                description: "list what is here that probably should not be sent",
+            },
+            {
+                flags: "--apply",
+                description: "with --suggest, add the confident ones to .gitignore",
+            },
+        ],
         run: commandRules,
     },
     {
@@ -1320,6 +1444,39 @@ const SPECS = [
         examples: ["coderook runner my-game --labels windows,signing"],
         run: commandRunner,
     },
+    {
+        /*
+          The assistants speak one protocol between them, so this is one server
+          rather than two integrations. Hidden from nobody but unlikely to be
+          typed by hand: it is launched by Claude Code or Codex, talks on its own
+          stdin and stdout, and exits with them.
+        */
+        name: "mcp",
+        group: "Other",
+        summary: "serve CodeRook to Claude Code, Codex and other assistants",
+        usage: "mcp",
+        detail: "Speaks the Model Context Protocol on stdin and stdout, so an assistant\n" +
+            "can look at your projects while it works. Not run by hand — point the\n" +
+            "assistant at it and it starts and stops the process itself.\n" +
+            "\n" +
+            "Claude Code:\n" +
+            "  claude mcp add coderook -- coderook mcp\n" +
+            "\n" +
+            "Codex, in ~/.codex/config.toml:\n" +
+            "  [mcp_servers.coderook]\n" +
+            "  command = 'coderook'\n" +
+            "  args = ['mcp']\n" +
+            "\n" +
+            "Everything it offers reads. It lists projects, versions and files, shows\n" +
+            "one file at a version, and reports what has changed in a folder. It\n" +
+            "cannot save a version, delete anything, or sign in or out — an assistant\n" +
+            "that goes wrong can waste your time but not your work.\n" +
+            "\n" +
+            "A project whose owner has turned off machine reading is refused, in\n" +
+            "words rather than as a status code.\n",
+        examples: ["claude mcp add coderook -- coderook mcp"],
+        run: () => (0, mcp_js_1.commandMcp)(),
+    },
     {
         name: "doctor",
         group: "Other",