@coderook/cli 0.22.2 → 0.24.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coderook",
   "displayName": "CodeRook",
   "description": "Save, browse and restore whole-snapshot versions of a project on CodeRook, from Claude Code.",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/README.md

@@ -1,220 +1,342 @@
-# CodeRook CLI
-
-CodeRook from the terminal, on Windows, macOS and Linux alike. It uses the
-same engines as the desktop application — the same scanner, the same
-`.gitignore` rules, the same upload, download and `.cbx` bundling — so a
-project moved by one is understood by the other.
-
-## Install
-
-Requires Node 20.11 or later, and nothing else.
-
-```
-npm install --global @coderook/cli
-```
-
-Or from this repository:
-
-```
-cd cli
-npm install
-npm run build
-npm link
-```
-
-## Sign in
-
-Create a personal access token in **Settings** on coderook.com, then:
-
-```
-coderook sign-in
-```
-
-The token is written to a file only your account can read:
-
-| Platform | Location |
-| --- | --- |
-| Windows | `%APPDATA%\CodeRook` |
-| macOS | `~/Library/Application Support/CodeRook` |
-| Linux | `$XDG_CONFIG_HOME/coderook`, or `~/.config/coderook` |
-
-For automation, set `CODEROOK_TOKEN` instead and nothing is written to disk.
-`CODEROOK_API_URL` points the tool at a different service.
-
-## Everyday use
-
-```
-coderook status                    what is here that is not saved yet
-coderook submit -m "Fixed the parser"
-coderook get                       fetch the latest version over this folder
-coderook clone my-project          fetch a project into a new folder
-```
-
-`status` and `submit` act on the current directory unless you name another.
-The first time either runs in a folder, it looks for a project on your account
-whose name matches and links the two, so a folder you already uploaded from
-the desktop is recognised rather than treated as new.
-
-`submit` sends only what changed. Files the service already holds are not
-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 --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
-`.git/info/exclude`.
-
-## Bundles
-
-```
-coderook bundle                    pack this project as <name>.cbx
-coderook unbundle backup.cbx       extract one
-coderook inspect backup.cbx        see what it holds  (--files to list them)
-```
-
-A `.cbx` is the CodeBox bundle format: content-defined chunks, Zstandard where
-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
-
-```
-coderook skill
-```
-
-That is the whole setup. It writes a short guide into Claude Code's skills
-folder, and from then on you ask for what you want in ordinary words:
-
-> save this to CodeRook
-
-> what have I changed?
-
-> what versions does this project have?
-
-Claude works out which commands to run. You can also call it by name with
-`/coderook`.
-
-`coderook skill --project` writes it into `./.claude` instead of your home
-folder, so it travels with the repository and everybody who clones it has it
-too.
-
-Sign in once per machine first — `coderook sign-in` — or set `CODEROOK_TOKEN`
-in automation. The skill will not save anything without asking you first, and
-never deletes.
-
-## Installing it as a plugin instead
-
-If you would rather not install the command line first, CodeRook publishes a
-plugin marketplace of its own:
-
-```
-/plugin marketplace add https://coderook.com/marketplace.json
-/plugin install coderook@coderook
-```
-
-That fetches the same package from npm and brings the skill with it. The
-marketplace is a plain file on coderook.com rather than a git repository, so
-there is no repository to clone and no second account anywhere.
-
-One thing to know: a plugin install puts the package in Claude Code's plugin
-folder, not on your `PATH`. The skill copes with that on its own by falling
-back to `npx -y @coderook/cli`, but `npm install --global @coderook/cli` is
-faster if you plan to run commands yourself as well.
-
-## A structured connection instead
-
-The skill teaches Claude the command line, which needs no configuration. If you
-would rather it had structured tools, there is an MCP server as well. It works
-with Codex too, which is the reason it exists.
-
-Claude Code:
-
-```
-claude mcp add --scope user coderook -- npx -y @coderook/cli mcp
-```
-
-Codex, in `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.coderook]
-command = "npx"
-args = ["-y", "@coderook/cli", "mcp"]
-```
-
-To share it with everyone on a project, commit this beside the code:
-
-```json
-// .mcp.json
-{
-  "mcpServers": {
-    "coderook": {
-      "command": "npx",
-      "args": ["-y", "@coderook/cli", "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, delete, or sign in or out.
-
-## Checking things
-
-```
-coderook doctor
-```
-
-Reports the tool's version, where its configuration lives, whether the service
-is reachable, and who this machine is signed in as.
-
-## Exit codes
-
-`0` on success, `1` on failure. Every command prints why it failed on standard
-error, so a script can branch on the status and log the reason.
+# cbx
+
+The command is `cbx`, and the split it names is the same one git and GitHub
+have. **CBX is the engine** — content-defined chunking, whole-snapshot
+versions, the `.cbx` bundle format. **CodeRook is the host** it talks to. You
+run `cbx`; you sign in to CodeRook.
+
+That is why the names do not match everywhere, and the mismatch is on purpose:
+
+| | |
+| --- | --- |
+| `cbx …` | the tool — what you type |
+| `coderook.com`, `@coderook/cli` | the service, and the package it ships in |
+| `coderook://project` | a remote URL, which names the host it points at |
+| `CODEROOK_TOKEN`, `%APPDATA%\CodeRook` | credentials for a CodeRook account |
+
+It uses the same engines as the desktop application — the same scanner, the
+same `.gitignore` rules, the same upload, download and `.cbx` bundling — so a
+project moved by one is understood by the other.
+
+## Install
+
+Requires Node 20.11 or later, and nothing else.
+
+```
+npm install --global @coderook/cli
+```
+
+That installs `cbx`. It also installs `coderook` as an alias for it, so
+anything written against the old name keeps working; the two are the same
+program and either can be used.
+
+Or from this repository:
+
+```
+cd cli
+npm install
+npm run build
+npm link
+```
+
+## Sign in
+
+Create a personal access token in **Settings** on coderook.com, then:
+
+```
+cbx sign-in
+```
+
+The token is written to a file only your account can read:
+
+| Platform | Location |
+| --- | --- |
+| Windows | `%APPDATA%\CodeRook` |
+| macOS | `~/Library/Application Support/CodeRook` |
+| Linux | `$XDG_CONFIG_HOME/coderook`, or `~/.config/coderook` |
+
+For automation, set `CODEROOK_TOKEN` instead and nothing is written to disk.
+`CODEROOK_API_URL` points the tool at a different service.
+
+## Everyday use
+
+```
+cbx status                    what is here that is not saved yet
+cbx submit -m "Fixed the parser"
+cbx get                       fetch the latest version over this folder
+cbx clone my-project          fetch a project into a new folder
+```
+
+`status` and `submit` act on the current directory unless you name another.
+The first time either runs in a folder, it looks for a project on your account
+whose name matches and links the two, so a folder you already uploaded from
+the desktop is recognised rather than treated as new.
+
+`submit` sends only what changed. Files the service already holds are not
+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.
+
+```
+cbx tracks                    the lines this project has
+cbx track                     the line this folder saves to
+cbx track spike --new         start a line and switch to it
+cbx track main                switch back
+cbx 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
+`cbx 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. `cbx merges` lists them and `cbx merge <ref>` walks
+through it; `cbx tracks` shows them beside the ordinary lines, because
+somebody looking for where they can save needs to see the one they cannot.
+
+## Ignore rules
+
+```
+cbx rules                      show the rules in force
+cbx rules --init               write a starter .gitignore
+cbx rules --suggest            what is here that probably should not be sent
+cbx 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
+`.git/info/exclude`.
+
+## Using git instead
+
+Installing the CLI also installs `git-remote-coderook`, so git talks to
+CodeRook directly — both ways:
+
+```
+git clone coderook://my-project
+git push coderook main
+git fetch
+```
+
+It exists so that every editor's built-in git panel works with CodeRook
+without a plugin. If you are not already living in git, `cbx submit` is
+the simpler tool and this is not an upgrade on it.
+
+**Pushing.** Each commit becomes a version, oldest first, with its message
+kept. Later pushes send only what is new, so the usual case — a few commits —
+is quick; a first push of a long history is not, and the helper says how many
+commits it is about to publish before it starts. Branches become lines, and a
+branch pushed for the first time starts from the commit it forked at rather
+than from wherever the project happens to be.
+
+**Cloning and fetching.** Every version becomes a commit, keeping its message,
+its date and who published it. This works on any project, including one that
+has never been near git — a project built entirely with `cbx submit`
+clones into a normal git history. A fetch only downloads versions this clone
+does not already have.
+
+**What it does not do:**
+
+| | |
+| --- | --- |
+| Tag kind | A lightweight tag comes back annotated. CodeRook records a name, not which sort of tag made it. |
+| Force pushes, branch deletion | Refused — versions are immutable, so there is nothing to rewind to. |
+| Submodules | Skipped on push, and it says which paths. |
+| The executable bit | Everything arrives as a normal file. A script cloned back needs `chmod +x`. |
+
+**On round trips.** Push then clone gives you back the same *files*, not the
+same *commit ids*. A commit id covers its author, committer and timestamps,
+and CodeRook records who published a version rather than the original stamps —
+so the history you get back is a faithful copy of the contents and an honest
+approximation of the commits. Two people cloning the same project do get
+identical ids as each other.
+
+Merges are asymmetric for the same reason. A publish states one base version,
+so pushing a git merge records one parent and the fork is lost — the merged
+tree is exact, the shape is not. Reading back is richer: a version that really
+has two parents is rebuilt as a real git merge.
+
+Each version records the commit it came from, so a colleague pushing the same
+project does not republish history the project already holds. Pushing a git
+history into a project whose versions came from somewhere else is refused
+rather than interleaved.
+
+### The names are the same
+
+There is no translation table to learn, because there is nothing to translate.
+The commands carry git's names:
+
+```
+cbx push          cbx pull          cbx clone
+cbx log           cbx status        cbx branch
+cbx checkout      cbx merge         cbx tag
+```
+
+Each is the CodeRook command it always was, reachable by the name a git user
+would reach for: `push` is `submit`, `pull` is `get`, `log` is `versions`,
+`branch` is `tracks`, `checkout` is `track`, `tag` is `release`. The original
+names still work and mean the same thing.
+
+That is also what the git remote does. `git push` performs the operation
+`cbx push` performs — the same code decides what changed, the same code
+publishes it. The remote is a way to reach these commands from git, not a
+second implementation of them that happens to agree.
+
+**What does not appear on that list**, because git has no such idea and
+inventing one would be pretending: `projects`, `delete`, `people`, `watch`,
+`issues`, `actions`, `runs`, `logs`, `runner`, `tokens`, `licence`, `ai`. Use
+them by name; nothing about them changes when a version arrives through git.
+
+`git commit` has no CodeRook equivalent either, and should not: it is local to
+git, and a version is not made until something is published.
+
+### Tags and releases
+
+`git push --tags` publishes each tag as a release, because that is the same
+statement in the other vocabulary — the service puts it plainly: *"a release
+is a Version with a name on it, not a different kind of object."*
+
+```
+git tag -a v1.0 -m "First stable release"
+git push coderook v1.0
+```
+
+The tag names the version its commit already became; it does not publish
+anything, so push the branch first. An annotated tag's message becomes the
+release notes and a lightweight tag brings none — the commit's own message is
+deliberately *not* used, since nobody wrote it about the release.
+
+Cloning reverses it: every release comes back as a tag on the right commit.
+
+Assets are separate and unaffected. They attach to a version from a run's
+artifacts, so a release made by pushing a tag simply has none until something
+adds them — which is what a release without a build has always looked like.
+
+## Bundles
+
+```
+cbx bundle                    pack this project as <name>.cbx
+cbx unbundle backup.cbx       extract one
+cbx inspect backup.cbx        see what it holds  (--files to list them)
+```
+
+A `.cbx` is the CodeBox bundle format: content-defined chunks, Zstandard where
+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
+
+```
+cbx skill
+```
+
+That is the whole setup. It writes a short guide into Claude Code's skills
+folder, and from then on you ask for what you want in ordinary words:
+
+> save this to CodeRook
+
+> what have I changed?
+
+> what versions does this project have?
+
+Claude works out which commands to run. You can also call it by name with
+`/coderook`.
+
+`cbx skill --project` writes it into `./.claude` instead of your home
+folder, so it travels with the repository and everybody who clones it has it
+too.
+
+Sign in once per machine first — `cbx sign-in` — or set `CODEROOK_TOKEN`
+in automation. The skill will not save anything without asking you first, and
+never deletes.
+
+## Installing it as a plugin instead
+
+If you would rather not install the command line first, CodeRook publishes a
+plugin marketplace of its own:
+
+```
+/plugin marketplace add https://coderook.com/marketplace.json
+/plugin install coderook@coderook
+```
+
+That fetches the same package from npm and brings the skill with it. The
+marketplace is a plain file on coderook.com rather than a git repository, so
+there is no repository to clone and no second account anywhere.
+
+One thing to know: a plugin install puts the package in Claude Code's plugin
+folder, not on your `PATH`. The skill copes with that on its own by falling
+back to `npx -y @coderook/cli`, but `npm install --global @coderook/cli` is
+faster if you plan to run commands yourself as well.
+
+## A structured connection instead
+
+The skill teaches Claude the command line, which needs no configuration. If you
+would rather it had structured tools, there is an MCP server as well. It works
+with Codex too, which is the reason it exists.
+
+Claude Code:
+
+```
+claude mcp add --scope user coderook -- npx -y @coderook/cli mcp
+```
+
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.coderook]
+command = "npx"
+args = ["-y", "@coderook/cli", "mcp"]
+```
+
+To share it with everyone on a project, commit this beside the code:
+
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "coderook": {
+      "command": "npx",
+      "args": ["-y", "@coderook/cli", "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, delete, or sign in or out.
+
+## Checking things
+
+```
+cbx doctor
+```
+
+Reports the tool's version, where its configuration lives, whether the service
+is reachable, and who this machine is signed in as.
+
+## Exit codes
+
+`0` on success, `1` on failure. Every command prints why it failed on standard
+error, so a script can branch on the status and log the reason.

package/dist/cli/src/api.js

@@ -12,6 +12,7 @@ exports.cancelMerge = cancelMerge;
 exports.aiAccess = aiAccess;
 exports.setAiAccess = setAiAccess;
 exports.versions = versions;
+exports.markRelease = markRelease;
 exports.issues = issues;
 exports.createIssue = createIssue;
 exports.releases = releases;
@@ -31,7 +32,7 @@ const config_js_1 = require("./config.js");
 async function call(route, options = {}) {
     const token = await (0, config_js_1.loadToken)();
     if (!token) {
-        throw new Error("Not signed in. Run: coderook sign-in");
+        throw new Error("Not signed in. Run: cbx sign-in");
     }
     const response = await fetch(`${(0, config_js_1.apiOrigin)()}${route}`, {
         method: options.method ?? "GET",
@@ -48,7 +49,7 @@ async function call(route, options = {}) {
     const body = text ? JSON.parse(text) : {};
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("That token was not accepted. Run: coderook sign-in");
+            throw new Error("That token was not accepted. Run: cbx sign-in");
         }
         throw new Error(body?.error?.message ?? `${route} failed (${response.status})`);
     }
@@ -158,8 +159,31 @@ async function versions(repositoryId) {
         fileCount: Number(row.fileCount ?? 0),
         storedSize: Number(row.storedSize ?? row.sourceSize ?? 0),
         createdAt: String(row.createdAt ?? ""),
+        parentVersionIds: Array.isArray(row.parentVersionIds)
+            ? row.parentVersionIds.map(String)
+            : [],
+        authorName: String(row.author?.displayName ?? ""),
     }));
 }
+/**
+ * Give a version a name, which is all a release is.
+ *
+ * Used to carry a pushed git tag across. `markRelease` on the service side is
+ * an update on the version row rather than a new object, so this is idempotent
+ * — pushing the same tag twice renames the same version to the same thing
+ * rather than making a second release.
+ */
+async function markRelease(repositoryId, versionId, name, notes) {
+    const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}` +
+        `/versions/${encodeURIComponent(versionId)}/release`, 
+    // `call` serialises the body itself; handing it a string would send a
+    // JSON-encoded string where the service expects an object.
+    { method: "PUT", body: { name, ...(notes ? { notes } : {}) } });
+    return {
+        name: String(body.release?.name ?? name),
+        versionId: String(body.release?.versionId ?? versionId),
+    };
+}
 async function issues(repositoryId) {
     const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/issues`);
     return {
@@ -188,6 +212,7 @@ async function createIssue(repositoryId, input) {
 async function releases(repositoryId) {
     const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/releases`);
     return (body.releases ?? []).map((row) => ({
+        versionId: String(row.versionId ?? ""),
         sequence: Number(row.sequence ?? 0),
         name: String(row.name ?? ""),
         notes: String(row.notes ?? ""),