@coderook/cli 0.14.0 → 0.15.0

package/README.md

@@ -122,36 +122,69 @@ 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
+## Claude Code
 
-CodeRook can be a tool your assistant uses while it works. Both speak the same
-protocol, so one server covers them.
+```
+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.
+
+## 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 coderook -- coderook mcp
+claude mcp add --scope user coderook -- npx -y @coderook/cli mcp
 ```
 
 Codex, in `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.coderook]
-command = "coderook"
-args = ["mcp"]
+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.
+To share it with everyone on a project, commit this beside the code:
 
-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.
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "coderook": {
+      "command": "npx",
+      "args": ["-y", "@coderook/cli", "mcp"]
+    }
+  }
+}
+```
 
-The server is launched by the assistant and exits with it; there is no reason
-to run `coderook mcp` by hand.
+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
 

package/dist/cli/src/cli.js

@@ -26,6 +26,7 @@ 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 skill_command_js_1 = require("./skill_command.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");
@@ -1444,6 +1445,38 @@ const SPECS = [
         examples: ["coderook runner my-game --labels windows,signing"],
         run: commandRunner,
     },
+    {
+        /*
+          The other way to hand this to an assistant is a plugin marketplace,
+          and marketplaces live in git repositories — an odd thing to require
+          of people using a version host that is deliberately not git. A skill
+          is a file in a folder, and this already knows where the folder is.
+        */
+        name: "skill",
+        group: "Other",
+        summary: "teach Claude Code about CodeRook",
+        usage: "skill [--project]",
+        detail: "Writes a short guide into Claude Code's skills folder, so it knows what\n" +
+            "CodeRook is and how to drive it. After that you ask for it in words:\n" +
+            "'save this to CodeRook', 'what changed?' — or run it by name with\n" +
+            "/coderook.\n" +
+            "\n" +
+            "Personal by default, so it is there in every project on this machine.\n" +
+            "--project writes it into ./.claude instead, where it travels with the\n" +
+            "repository for everybody who clones it.\n" +
+            "\n" +
+            "It teaches the command line rather than the MCP server, because that\n" +
+            "needs no configuration at all. `coderook mcp` is still there when a\n" +
+            "structured connection is wanted.\n",
+        options: [
+            {
+                flags: "--project",
+                description: "install into this project rather than for you",
+            },
+        ],
+        examples: ["coderook skill", "coderook skill --project"],
+        run: skill_command_js_1.commandSkill,
+    },
     {
         /*
           The assistants speak one protocol between them, so this is one server
@@ -1475,7 +1508,7 @@ const SPECS = [
             "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)(),
+        run: () => (0, mcp_js_1.commandMcp)(VERSION),
     },
     {
         name: "doctor",

package/dist/cli/src/mcp.js

@@ -33,6 +33,15 @@ const api_js_1 = require("./api.js");
 const config_js_1 = require("./config.js");
 /** What the protocol calls itself. Both clients accept this revision. */
 const PROTOCOL_VERSION = "2024-11-05";
+/*
+  What this build calls itself, handed in rather than written down here.
+
+  The first version carried a literal, which the CLI already learned not to
+  do: the comment beside its own VERSION says a hardcoded copy had drifted
+  from what was published. Mine drifted within one release — the server
+  announced 0.13.0 to Claude Code while the package was 0.14.0.
+*/
+let serverVersion = "0.0.0";
 /** Beyond this a file is described rather than pasted into a conversation. */
 const READ_LIMIT = 256 * 1024;
 function text(value) {
@@ -269,7 +278,7 @@ async function handle(request) {
         reply(id, {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: {} },
-            serverInfo: { name: "coderook", version: node_process_1.default.env.CODEROOK_CLI_VERSION ?? "0.13.0" },
+            serverInfo: { name: "coderook", version: serverVersion },
         });
         return;
     }
@@ -321,7 +330,8 @@ async function handle(request) {
  * Buffered by line rather than by chunk, because a chunk boundary falls
  * wherever the pipe decides and a half-read message parses as nothing.
  */
-async function commandMcp() {
+async function commandMcp(version) {
+    serverVersion = version;
     node_process_1.default.stdin.setEncoding("utf8");
     let buffer = "";
     await new Promise((done) => {

package/dist/cli/src/skill_command.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Teaching an assistant about CodeRook, in one command.
+ *
+ * The other route in is a plugin marketplace, and marketplaces live in git
+ * repositories — which is a strange thing to require of people using a version
+ * host that is deliberately not git, and stranger still when the recommended
+ * host is the one this product exists as an alternative to.
+ *
+ * A skill is a file in a folder. The command line is already installed and
+ * already knows where that folder is, so it writes it: no marketplace, no
+ * clone, no second account. `coderook skill` and the assistant knows what
+ * CodeRook is and how to drive it from then on, in every project.
+ *
+ * The skill teaches it the command line rather than the MCP server. Both work,
+ * but the command line needs no configuration at all — the assistant already
+ * has a shell, and a thing that works with nothing to set up is the thing most
+ * people should be offered first.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandSkill = commandSkill;
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const dim = (value) => `[2m${value}[0m`;
+const bold = (value) => `[1m${value}[0m`;
+const red = (value) => `[31m${value}[0m`;
+const green = (value) => `[32m${value}[0m`;
+const accent = (value) => `[33m${value}[0m`;
+/**
+ * The skill as it ships, found relative to this file.
+ *
+ * Not read from the working directory, because the command is run from
+ * somebody's project and the file lives wherever npm put the package.
+ */
+async function shipped() {
+    /*
+      `__dirname` rather than `import.meta.url`: this package compiles to
+      CommonJS, where the latter is not available and the build refuses it.
+    */
+    const here = __dirname;
+    /*
+      Compiled to dist/cli/src, so the package root is three levels up. Tried in
+      order rather than assumed, so running from source works as well as running
+      from an install.
+    */
+    const candidates = [
+        node_path_1.default.resolve(here, "../../../skills/coderook/SKILL.md"),
+        node_path_1.default.resolve(here, "../../skills/coderook/SKILL.md"),
+        node_path_1.default.resolve(here, "../skills/coderook/SKILL.md"),
+    ];
+    for (const candidate of candidates) {
+        try {
+            return await (0, promises_1.readFile)(candidate, "utf8");
+        }
+        catch {
+            /* try the next shape */
+        }
+    }
+    throw new Error("The skill file is missing from this installation.");
+}
+/**
+ * Where the assistant looks.
+ *
+ * Personal by default — somebody who installs this wants it in every project,
+ * not only the one they happened to be standing in. `--project` writes it
+ * beside the code instead, which is what to do when it should travel with the
+ * repository for everybody who clones it.
+ */
+function destination(project) {
+    const root = project
+        ? node_path_1.default.join(node_process_1.default.cwd(), ".claude")
+        : node_path_1.default.join(node_os_1.default.homedir(), ".claude");
+    return node_path_1.default.join(root, "skills", "coderook", "SKILL.md");
+}
+async function commandSkill(parsed) {
+    const project = parsed.flags.has("project");
+    const target = destination(project);
+    let body;
+    try {
+        body = await shipped();
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    /*
+      Overwritten without asking, because the file is ours and the only reason it
+      differs is that it is an older copy. Anything a person wrote themselves
+      belongs under a different name.
+    */
+    await (0, promises_1.mkdir)(node_path_1.default.dirname(target), { recursive: true });
+    await (0, promises_1.writeFile)(target, body, "utf8");
+    console.log(green("Installed the CodeRook skill."));
+    console.log(dim("  ") + target);
+    console.log("");
+    console.log(project
+        ? dim("Everyone who opens this project in Claude Code now has it.")
+        : dim("Claude Code has it in every project on this machine."));
+    console.log("");
+    console.log(dim("Ask for it in words — ") + accent("“save this to CodeRook”"));
+    console.log(dim("or run it by name — ") + accent("/coderook"));
+    console.log("");
+    console.log(dim("Signed in? ") +
+        bold("coderook whoami") +
+        dim("  ·  if not: ") +
+        bold("coderook sign-in"));
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",
@@ -20,7 +20,8 @@
     "coderook": "dist/cli/src/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/coderook/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: coderook
+description: Save, browse and restore versions of a project on CodeRook — a version host where every version is a complete snapshot and there is no git to learn. Use when asked to save or submit work to CodeRook, check what has changed, look at a project's versions or files, fetch a project, start or switch a line of work, or resolve a save that landed at the same time as somebody else's.
+allowed-tools: Bash Read
+---
+
+# CodeRook
+
+CodeRook stores whole snapshots of a folder. A version names every file the
+project had at that moment, so restoring one never depends on the versions
+around it, and there is no staging area, no branches to rebase and no history
+to rewrite.
+
+Everything here is the `coderook` command line. Run it with Bash.
+
+## Before anything else
+
+`coderook whoami` says who this machine is signed in as. If it refuses, the
+person needs to run `coderook sign-in` themselves — it takes a personal access
+token, so do not attempt it on their behalf.
+
+## Reading
+
+```bash
+coderook status               # what has changed in this folder since its last version
+coderook projects             # every project on the account
+coderook versions [project]   # what has been saved, newest first
+coderook tracks [project]     # the lines a project has, and any waiting on a decision
+```
+
+`status` is the one to reach for when somebody asks what is uncommitted, what
+changed, or whether anything needs saving. It reads the folder and changes
+nothing.
+
+## Saving
+
+```bash
+coderook submit -m "What changed, in a sentence"
+```
+
+Send only what changed; the version still names every file. Write the message
+yourself from the actual diff rather than asking for one — a message like
+"update" helps nobody reading the history later.
+
+**Ask before running this.** Saving is the one thing here that leaves a mark on
+somebody's account, and a version saved by mistake is a version they have to
+explain. Propose it, say what it would send, and let them agree.
+
+`coderook submit -n` shows exactly what would be sent without sending it. Use
+that freely; it is safe and it is the honest way to answer "what would this
+upload?".
+
+## Fetching
+
+```bash
+coderook get                  # bring this folder up to date
+coderook clone <project> [dir]  # fetch a project into a new folder
+```
+
+`get` protects local edits by default. `coderook get --replace` discards them
+to make an exact copy — only run it when the person has said so in those terms.
+
+## Lines of work
+
+A project can have more than one line, so two people can save without one
+landing on top of the other.
+
+```bash
+coderook track                 # which 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 "…"
+```
+
+Switching says where the next save goes and nothing else — no files move.
+Run `coderook get` afterwards to bring that line's files in.
+
+## When two saves collide
+
+If somebody saved while this folder was behind, the second save becomes a merge
+waiting on a decision rather than overwriting anything.
+
+```bash
+coderook merges                # this folder's saves waiting on a decision
+coderook merge <ref>           # look at one, and decide
+```
+
+Read the conflict out to the person and let them choose. Do not pick a side for
+them: the whole reason it stopped is that the service could not tell which copy
+was wanted.
+
+## What is worth leaving out
+
+```bash
+coderook ignore --suggest          # dependency directories, build output, virtual environments
+coderook ignore --suggest --apply  # add the confident ones to .gitignore
+```
+
+Rules live in the project's own `.gitignore`, so CodeRook, git and the website
+all read one file.
+
+## Bundles
+
+```bash
+coderook bundle . project.cbx   # the whole project, every version, as one file
+coderook inspect project.cbx    # what is inside, without unpacking
+coderook unbundle project.cbx ./restored
+```
+
+## Things not to do
+
+- Do not run `coderook delete` unless the person has asked for that project to
+  be deleted, by name, in this conversation.
+- Do not run `coderook sign-out`. It costs them a token they have to fetch
+  again and gains nothing.
+- Do not guess a project name. `coderook projects` lists them; a folder that is
+  already linked needs no name at all.
+
+## If something refuses
+
+The commands explain themselves — pass the message on rather than rewording it.
+A refusal that says a token was not accepted means signing in; one that says a
+project does not allow machines means its owner turned that off deliberately,
+and the answer is to say so, not to find another route in.