@coderook/cli 0.41.0 → 0.41.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +16 -3
  3. package/dist/cbx/src/shared/run_output.js +85 -0
  4. package/dist/cli/src/cli.js +2 -2
  5. package/dist/cli/src/mcp.js +14 -0
  6. package/dist/cli/src/runner.js +63 -24
  7. package/dist/cli/src/workspace_command.js +4 -1
  8. package/package.json +3 -2
  9. package/skills/coderook/SKILL.md +433 -417
package/skills/coderook/SKILL.md CHANGED
@@ -1,417 +1,433 @@
1
- ---
2
- name: coderook
3
- description: Save, browse and restore versions of a project on CodeRook — a version host where every version is a complete snapshot, reached with the cbx command or with plain git. Use when asked to save, submit or push 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, resolve a save that landed at the same time as somebody else's, build a project's executables for Windows, Linux and macOS from one machine (cbx build), or publish a mod to a game's mod repository or set one up (cbx mods).
4
- allowed-tools: Bash Read
5
- ---
6
-
7
- # CodeRook
8
-
9
- CodeRook stores whole snapshots of a folder. A version names every file the
10
- project had at that moment, so restoring one never depends on the versions
11
- around it, and there is no staging area, no branches to rebase and no history
12
- to rewrite.
13
-
14
- Everything here is the `cbx` command line (also installed as `coderook`), or
15
- git itself through CodeRook's remote helper. Run them with Bash.
16
-
17
- **Which one to use.** If the folder is a git repository (`git rev-parse` works
18
- in it), prefer git — see *Working in a git repository* below. Each commit then
19
- arrives with its own message, instead of one snapshot standing in for many.
20
- Use `cbx submit` for folders that are not git repositories.
21
-
22
- ## Remote work without a full checkout
23
-
24
- Use `cbx workspace` when the person wants to continue a CodeRook project from a lightweight laptop. Do not clone the full project unless that work needs local files. Start with `cbx workspace list <project>` or open a named draft with a unique `--key`. Keep its ID and revision, read/search the needed paths, edit with explicit hashes in a JSON `--data-file`, review the diff, then save the authorised revision. Retry a lost response using the same operation key and arguments. Saving and deploying are different actions.
25
-
26
- `cbx workspace show <project> <id>` includes the administrator-configured recipe commands and target information. Run a named recipe, inspect its job with `logs`, and use `cancel` if needed. Only deploy an explicitly requested target and a saved version with applicable checks. A missing recipe requires configuration; running a local terminal command does not change remote files.
27
-
28
- To hand a draft to a machine that is not signed in as the owner, run `cbx workspace assign <project> <draft> --name "Laptop"`. It prints a token that reaches that one draft (read the project, edit, save and run its checks; no deploys, settings, other drafts or more tokens). Tell the person to give it to the other machine privately; never repeat the token yourself. On that machine: `cbx sign-in` (paste the token), `cbx workspace checkout <project> <draft> [folder]`, edit the files, then `cbx workspace push` (add `--save -m "…"` to save, `--dry-run` to preview). A checked-out folder is not a linked folder, so `cbx submit` does not apply there. A handed-over machine's saves never land on the draft's line directly: they go to the draft's own line `drafts/<name>-<id>` and open a pull request into it, which the owner or a reviewer approves and merges (see it with `cbx pr list`). Saves made signed in as the owner go straight to the line. `cbx workspace assignments` lists live tokens and `cbx workspace unassign` ends one; archiving the draft ends them all.
29
-
30
- `cbx machines [project]` shows the PCs working on a project: linked folders and handed-over drafts, the version each holds, how far behind the line it is and its unsaved file count, then the runners. A machine appears when cbx status, get, submit or a workspace command runs there; `CODEROOK_NO_PRESENCE=1` keeps one off the list. Check it before assuming nobody else is mid-change.
31
-
32
- `cbx mcp --workspaces` opts into the remote workspace tools using this account's stored token. The original `cbx mcp` stays read-only. A token needs explicit workspace edit/run/deploy grants for those actions; never print its value. The remote plugin can connect directly without this CLI.
33
-
34
- Native jobs require CLI 0.38.0 or later on the selected Windows laptop and a matching `cbx runner --name` and label. The named recipe can select `includePaths` so only needed inputs download to a temporary job folder. Hosted jobs continue with the desktop PC off. Native execution, local GPU features, toolchains and signed-in services need their own suitable machine/setup. Remote task notes share project handover state, not proprietary chat history.
35
-
36
- ## Before anything else
37
-
38
- `cbx whoami` says who this machine is signed in as. If it refuses, the
39
- person needs to run `cbx sign-in` themselves — it takes a personal access
40
- token, so do not attempt it on their behalf.
41
-
42
- If the command is not found at all, this machine has the skill but not the
43
- command line. Either install it once with
44
- `npm install --global @coderook/cli`, or put `npx -y @coderook/cli` where
45
- `coderook` appears below — the commands are identical, npx is just slower
46
- to start.
47
-
48
- ## Reading
49
-
50
- ```bash
51
- cbx status # what has changed in this folder since its last version
52
- cbx projects # every project on the account
53
- cbx versions [project] # what has been saved, newest first
54
- cbx tracks [project] # the lines a project has, and any waiting on a decision
55
- ```
56
-
57
- `status` is the one to reach for when somebody asks what is uncommitted, what
58
- changed, or whether anything needs saving. It reads the folder and changes
59
- nothing.
60
-
61
- ## Saving
62
-
63
- ```bash
64
- cbx submit -m "What changed, in a sentence"
65
- ```
66
-
67
- **The first save from a folder must say which project it is.** A folder that
68
- is not linked goes to a new project named after it — unless the account has a
69
- project with a name like it, and then `submit` stops and lists them. Do not
70
- guess: show the person the list and ask. Then run one of:
71
-
72
- ```bash
73
- cbx submit --into <project> -m "…" # this folder is that project
74
- cbx submit --new -m "…" # a separate project (add --name if the name is taken)
75
- cbx link <project> # link only; send nothing yet
76
- ```
77
-
78
- Never start a second project for work that already has one. A folder copied to
79
- another machine, another operating system or another path is still the same
80
- project: `cbx link` it.
81
-
82
- Send only what changed; the version still names every file. Write the message
83
- yourself from the actual diff rather than asking for one — a message like
84
- "update" helps nobody reading the history later.
85
-
86
- **Ask before running this.** Saving is the one thing here that leaves a mark on
87
- somebody's account, and a version saved by mistake is a version they have to
88
- explain. Propose it, say what it would send, and let them agree.
89
-
90
- `cbx submit -n` shows exactly what would be sent without sending it. Use
91
- that freely; it is safe and it is the honest way to answer "what would this
92
- upload?".
93
-
94
- ## Working in a git repository
95
-
96
- CodeRook is a git remote. `npm install --global @coderook/cli` puts the helper
97
- (`git-remote-coderook`) on PATH; the plugin and `npx` do not, so check with
98
- `git ls-remote coderook://<project>` before relying on it.
99
-
100
- ```bash
101
- git remote -v # is there a coderook:// remote already?
102
- git remote add coderook coderook://<project> # if not
103
- git push coderook main # each new commit becomes a save
104
- git push coderook <branch> # a branch becomes a line
105
- git push coderook v1.2.0 # a tag names a version
106
- git fetch coderook # bring other people's saves in
107
- ```
108
-
109
- If the project was started with `cbx submit` or the desktop app, the first push
110
- is refused with a message saying so. When the repository holds that project,
111
- `git push -o adopt coderook main` saves the current commit on top of what is
112
- there, once; plain pushes work from then on. **Ask before adopting** — it is a
113
- save like any other. If the project is somebody else's work under the same
114
- name, push to a new name instead.
115
-
116
- Git's limits here: no force pushes or branch deletions (saves are permanent), a
117
- merge commit arrives as one save holding the merged tree, and a commit holding
118
- a credential is refused — take the key out of history rather than looking for
119
- a way round.
120
-
121
- ## Fetching
122
-
123
- ```bash
124
- cbx get # bring this folder up to date
125
- cbx clone <project> [dir] # fetch a project into a new folder
126
- ```
127
-
128
- `get` protects local edits by default. `cbx get --replace` discards them
129
- to make an exact copy — only run it when the person has said so in those terms.
130
-
131
- ## Lines of work
132
-
133
- A project can have more than one line, so two people can save without one
134
- landing on top of the other.
135
-
136
- ```bash
137
- cbx track # which line this folder saves to
138
- cbx track spike --new # start a line and switch to it
139
- cbx track main # switch back
140
- cbx submit --track spike -m "…"
141
- ```
142
-
143
- Switching says where the next save goes and nothing else — no files move.
144
- Run `cbx get` afterwards to bring that line's files in.
145
-
146
- ## A history on this machine
147
-
148
- A folder with a `.cbx/` folder in it keeps its own history, and there
149
- `status`, `diff`, `log`, `switch`, `merge`, `push` and `pull` work on that
150
- history instead of the account. Check with `cbx status`: it names the line and
151
- the last local save.
152
-
153
- ```bash
154
- cbx init # start one (only when asked to)
155
- cbx save -m "…" # record the folder as it is
156
- cbx log # saves on this line
157
- cbx switch -c spike # start a line here; no files change
158
- cbx merge spike # bring that line's work in
159
- cbx restore path --from main~1 # put a file back from an earlier save
160
- cbx push # send new saves to CodeRook
161
- cbx pull # bring CodeRook's saves in, merging if both moved
162
- ```
163
-
164
- A merge that stops on conflicts leaves markers in the files and waits. Show
165
- the person the conflicts (`cbx status`) and let them decide; `cbx save`
166
- finishes the merge once the markers are gone. Do not pass `--force` to
167
- `restore`, `switch`, `save` or `pull` unless the person has said to throw away
168
- the changes it names, and do not run `cbx merge --cancel` unless they asked.
169
-
170
- ## Versions, and going back
171
-
172
- Every save is a commit. A commit becomes a *version* — the thing the public
173
- side of a project offers, and the thing a collaborator pulls — only when
174
- somebody promotes it.
175
-
176
- ```bash
177
- cbx promote # pick from the last ten and name one
178
- cbx mark 41 --pin # pin, hide, rename or label one save
179
- cbx labels add shipped green # the labels a project can wear
180
- cbx undo # put the project back on the save before this one
181
- ```
182
-
183
- `undo` moves where the project stands. Nothing is deleted and nothing is
184
- renumbered — the saves passed over stay in the history, and the next save
185
- carries on from wherever it now stands. It is the answer to "I pushed the
186
- wrong thing"; hiding a version stops strangers reading it but leaves the
187
- project standing on it, so the next person to pull still lands on the mistake.
188
-
189
- **Ask before `undo`, `promote` and `take-down`.** They change what other
190
- people see. `cbx versions` first, so the person can say which save they mean.
191
-
192
- ## Who can reach a project
193
-
194
- ```bash
195
- cbx visibility # what it is now: private, unlisted or public
196
- cbx visibility public --yes # list it on the owner's profile
197
- cbx visibility private # back to the people invited
198
- ```
199
-
200
- **Never make a project public or unlisted unless the person has asked for
201
- exactly that.** `--yes` skips the question the command would otherwise ask
202
- them, so only pass it once they have answered it. Going private is always safe.
203
-
204
- ## Serving a project as a website
205
-
206
- ```bash
207
- cbx pages # is the site on, its address, what it serves
208
- cbx pages auto # find the build in what was published, and offer to serve it
209
- cbx pages on --folder dist # serve a folder of the published version
210
- cbx pages off # stop serving it
211
- ```
212
-
213
- **Never turn Pages on (`auto` or `on`) unless the person has asked for their
214
- project to be served as a site.** It runs their code in strangers' browsers
215
- under the project's name. Pass `--yes` only once they have said yes. Only
216
- published versions are served and the project must be public. When `auto`
217
- finds a build left out by the ignore rules it offers a `.gitignore` line and
218
- lists the next steps; it never saves or publishes — ask before doing those.
219
- Turning Pages off is always safe.
220
-
221
- ## When two saves collide
222
-
223
- If somebody saved while this folder was behind, the second save becomes a merge
224
- waiting on a decision rather than overwriting anything.
225
-
226
- ```bash
227
- cbx merges # this folder's saves waiting on a decision
228
- cbx merge <ref> # look at one, and decide
229
- ```
230
-
231
- Read the conflict out to the person and let them choose. Do not pick a side for
232
- them: the whole reason it stopped is that the service could not tell which copy
233
- was wanted.
234
-
235
- ## What is worth leaving out
236
-
237
- ```bash
238
- cbx ignore --suggest # dependency directories, build output, virtual environments
239
- cbx ignore --suggest --apply # add the confident ones to .gitignore
240
- ```
241
-
242
- Rules live in the project's own `.gitignore`, so CodeRook, git and the website
243
- all read one file.
244
-
245
- ## Bundles
246
-
247
- ```bash
248
- cbx bundle . project.cbx # the whole project, every version, as one file
249
- cbx inspect project.cbx # what is inside, without unpacking
250
- cbx unbundle project.cbx ./restored
251
- ```
252
-
253
- ## Reading a public project without signing in
254
-
255
- Public projects can be read by anything, with no token, from
256
- `https://api.coderook.com/v1/public`. There is no need to read the command
257
- line's source to find these — this is the whole of it:
258
-
259
- ```text
260
- GET /projects?q= public projects, newest first
261
- GET /projects/{owner}/{slug} one project
262
- GET /projects/{owner}/{slug}/versions the versions it offers
263
- GET /projects/{owner}/{slug}/releases every release, with its downloads
264
- GET /projects/{owner}/{slug}/releases/latest newest release and its files
265
- GET /projects/{owner}/{slug}/updates/latest.yml electron-updater feed
266
- GET /projects/{owner}/{slug}/versions/{v}/files every file, with digests
267
- GET /projects/{owner}/{slug}/versions/{v}/file?path= one file
268
- GET /projects/{owner}/{slug}/versions/{v}/archive the version as a zip
269
- GET /projects/{owner}/{slug}/versions/{v}/last-changes?path= which version last changed each entry
270
- GET /projects/{owner}/{slug}/versions/{v}/attachments files attached to it
271
- GET /projects/{owner}/{slug}/versions/{v}/attachments/{id} download one
272
- ```
273
-
274
- `{v}` is a version id or `latest`. A private project answers 404, exactly as
275
- if it did not exist.
276
-
277
- ### An app that updates itself from CodeRook
278
-
279
- Release a version named like a version number and attach the installer:
280
-
281
- ```bash
282
- cbx release 1.4.0
283
- cbx attach ./dist/MyApp-Setup-1.4.0.exe
284
- ```
285
-
286
- An Electron app then needs nothing custom — electron-builder's generic
287
- provider pointed at the feed:
288
-
289
- ```json
290
- "publish": [{ "provider": "generic",
291
- "url": "https://api.coderook.com/v1/public/projects/OWNER/SLUG/updates" }]
292
- ```
293
-
294
- The feed serves `latest.yml`, `latest-mac.yml` and `latest-linux.yml` with
295
- each file's size and SHA-512, and redirects file names to their downloads.
296
- Anything else can read `releases/latest` as JSON: version, notes, and every
297
- file with its size, SHA-256 and `url`. Updaters have no account, so the
298
- project they read must be public, but its source need not be:
299
-
300
- ```bash
301
- cbx release 1.4.0 --downloads public # notes, attachments and feed public; files stay private
302
- cbx releases # public / downloads public / private, and the addresses
303
- ```
304
-
305
- **Ask before `--downloads public`**: it publishes the attached files to anyone.
306
- One project holds the code and ships the app; a second "releases" project is
307
- no longer needed.
308
-
309
- ## Building executables for every platform
310
-
311
- ```bash
312
- cbx build --plan # how this machine would build each target
313
- cbx build --target win,linux,mac # build them into .coderook/build/<target>/
314
- ```
315
-
316
- It builds on this machine, with the tools it has, and uploads nothing. Run
317
- `--plan` first and read it out: a target marked "no" says what would build it
318
- (Docker, a Mac, cargo-zigbuild) — pass that on rather than installing things
319
- unasked. `--ship` attaches the results to the newest save, so **ask before
320
- `--ship`**, as before any save. A project's own build description lives in
321
- `coderook.build.json`.
322
-
323
- ## Pull requests
324
-
325
- A pull request is a proposal: a line offered to another line (`cbx propose`
326
- opens one). Read and review them with `cbx pr`:
327
-
328
- ```bash
329
- cbx pr list # what is open on this project
330
- cbx pr view M-3 # reviews, checks, conversation, what blocks merging
331
- cbx pr files M-3 # what it changes
332
- cbx pr comment M-3 --line src/app.ts:42 -m "…"
333
- cbx pr approve M-3 # or request-changes M-3 -m "…"
334
- cbx pr merge M-3
335
- ```
336
-
337
- **Ask before** `approve`, `request-changes`, `merge`, `close` and any comment:
338
- each is the person speaking or acting, and is seen by others. An approval
339
- stops counting when new saves land on the line, so re-check after pushing.
340
- Every pull request carries a `coderook/malware` check: what the line adds or
341
- changes is scanned before it can land, and a failure names the file. Do not
342
- try to get round it.
343
-
344
- ## Private files
345
-
346
- `cbx private add "design/"` keeps matching files out of everything outside the
347
- project (listings, zips, clone, Pages). Ask before changing the list: it
348
- decides what strangers can see.
349
-
350
- ## Runs
351
-
352
- `cbx runs`, `cbx logs 12 --follow` to watch one, `cbx cancel 12` to stop one,
353
- `cbx rerun 12` to run it again, `cbx approve 14` for one waiting for approval
354
- (ask before each). Workflows can be YAML files in `.rook/workflows`; check
355
- them with `cbx actions check` before saving. Never print or echo secrets:
356
- `cbx secret set NAME` asks for the value itself, so let the person type it.
357
-
358
- Inside a run, `CODEROOK_TOKEN`, `CODEROOK_API` and `CODEROOK_PROJECT` are set,
359
- so `cbx issue comment`, `cbx pr label` and `cbx release` work with no sign-in.
360
-
361
- ## Issues, forks and security
362
-
363
- `cbx issue view|comment|close|label|assign`, `cbx fork`, `cbx security`. Ask
364
- before closing, labelling, assigning, forking, or sending anything: each is the
365
- person acting where others see it. A security report is private to the
366
- project's owner; never put vulnerability details in a public issue.
367
-
368
- ## Releases
369
-
370
- `cbx release v2.0 --draft --generate-notes` then `cbx release publish`;
371
- `cbx verify owner/project v2.0 ./file` checks a download; `cbx deps` lists
372
- known vulnerabilities in the lockfiles. Ask before publishing.
373
-
374
- ## Mod repositories for games
375
-
376
- A game's maker can run a mod repository: players' game clients read a signed
377
- catalogue from it, modders publish to it, and nothing is listed until it
378
- passes the repository's rules and a malware scan.
379
-
380
- ```bash
381
- cbx mods info zt1 # a repository's rules, for anybody
382
- cbx mods publish ./BetterTrees --repo zt1 # zip, upload, wait for the checks
383
- cbx mods publish ./HD-Art --repo zt1 --part animals # one part of a bigger mod
384
- cbx mods list zt1 # your mods and how their checks went
385
- cbx mods create my-game --name "My Game" --allow .png,.ogg,.json
386
- ```
387
-
388
- `publish` reads the folder's `mod.json` (or the repository's manifest) for the
389
- mod's id, name, folder and version; `--id`, `--name`, `--folder` and
390
- `--version` override it. It waits up to 30 minutes for the checks and prints
391
- what failed, file by file — pass that on as it is. Programs and scripts
392
- (`.exe`, `.dll`, `.ps1`, `.js` …) are refused in every repository, so do not
393
- try to rename one past the check. **Ask before `publish`**, as before any
394
- save: it makes the mod public once it passes. Ask before `remove`, `block`
395
- and `delete`, which only the person should decide. The game-side protocol
396
- (signed requests, the catalogue signature, downloads) is at
397
- https://coderook.com/docs#mod-repositories.
398
-
399
- ## Things not to do
400
-
401
- - Do not run `cbx delete` unless the person has asked for that project to
402
- be deleted, by name, in this conversation.
403
- - Do not run `cbx sign-out`. It costs them a token they have to fetch
404
- again and gains nothing.
405
- - Do not guess a project name. `cbx projects` lists them; a folder that is
406
- already linked needs no name at all.
407
- - Do not pass `--new` to get past the question `submit` asks. It exists for a
408
- separate project the person wants, not to avoid choosing.
409
- - Do not run `cbx take-down`. It destroys the files in a version and they do
410
- not come back. Say it exists and let its owner run it.
411
-
412
- ## If something refuses
413
-
414
- The commands explain themselves — pass the message on rather than rewording it.
415
- A refusal that says a token was not accepted means signing in; one that says a
416
- project does not allow machines means its owner turned that off deliberately,
417
- and the answer is to say so, not to find another route in.
1
+ ---
2
+ name: coderook
3
+ description: Save, browse and restore versions of a project on CodeRook — a version host where every version is a complete snapshot, reached with the cbx command or with plain git. Use when asked to save, submit or push 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, resolve a save that landed at the same time as somebody else's, build a project's executables for Windows, Linux and macOS from one machine (cbx build), or publish a mod to a game's mod repository or set one up (cbx mods). Also inspect shared workspace credits and separate PR allowances.
4
+ allowed-tools: Bash Read
5
+ ---
6
+
7
+ # CodeRook
8
+
9
+ CodeRook stores whole snapshots of a folder. A version names every file the
10
+ project had at that moment, so restoring one never depends on the versions
11
+ around it, and there is no staging area, no branches to rebase and no history
12
+ to rewrite.
13
+
14
+ Everything here is the `cbx` command line (also installed as `coderook`), or
15
+ git itself through CodeRook's remote helper. Run them with Bash.
16
+
17
+ **Which one to use.** If the folder is a git repository (`git rev-parse` works
18
+ in it), prefer git — see *Working in a git repository* below. Each commit then
19
+ arrives with its own message, instead of one snapshot standing in for many.
20
+ Use `cbx submit` for folders that are not git repositories.
21
+
22
+ ## Remote work without a full checkout
23
+
24
+ Use `cbx workspace` when the person wants to continue a CodeRook project from a lightweight laptop. Do not clone the full project unless that work needs local files. Start with `cbx workspace list <project>` or open a named draft with a unique `--key`. Keep its ID and revision, read/search the needed paths, edit with explicit hashes in a JSON `--data-file`, review the diff, then save the authorised revision. Retry a lost response using the same operation key and arguments. Saving and deploying are different actions.
25
+
26
+ `cbx workspace show <project> <id>` includes the administrator-configured recipe commands and target information. Run a named recipe, inspect its job with `logs`, and use `cancel` if needed. Only deploy an explicitly requested target and a saved version with applicable checks. A missing recipe requires configuration; running a local terminal command does not change remote files.
27
+
28
+ To hand a draft to a machine that is not signed in as the owner, run `cbx workspace assign <project> <draft> --name "Laptop"`. It prints a token that reaches that one draft (read the project, edit, save and run its checks; no deploys, settings, other drafts or more tokens). Tell the person to give it to the other machine privately; never repeat the token yourself. On that machine: `cbx sign-in` (paste the token), `cbx workspace checkout <project> <draft> [folder]`, edit the files, then `cbx workspace push` (add `--save -m "…"` to save, `--dry-run` to preview). A checked-out folder is not a linked folder, so `cbx submit` does not apply there. A handed-over machine's saves never land on the draft's line directly: they go to the draft's own line `drafts/<name>-<id>` and open a pull request into it, which the owner or a reviewer approves and merges (see it with `cbx pr list`). Saves made signed in as the owner go straight to the line. `cbx workspace assignments` lists live tokens and `cbx workspace unassign` ends one; archiving the draft ends them all.
29
+
30
+ `cbx machines [project]` shows the PCs working on a project: linked folders and handed-over drafts, the version each holds, how far behind the line it is and its unsaved file count, then the runners. A machine appears when cbx status, get, submit or a workspace command runs there; `CODEROOK_NO_PRESENCE=1` keeps one off the list. Check it before assuming nobody else is mid-change.
31
+
32
+ `cbx mcp --workspaces` opts into the remote workspace tools using this account's stored token. The original `cbx mcp` stays read-only. A token needs explicit workspace edit/run/deploy grants for those actions; never print its value. The remote plugin can connect directly without this CLI.
33
+
34
+ Native jobs require CLI 0.38.0 or later on the selected Windows laptop and a matching `cbx runner --name` and label. The named recipe can select `includePaths` so only needed inputs download to a temporary job folder. Hosted jobs continue with the desktop PC off. Native execution, local GPU features, toolchains and signed-in services need their own suitable machine/setup. Remote task notes share project handover state, not proprietary chat history.
35
+
36
+ ## Usage and limits
37
+
38
+ Use `cbx workspace usage <project>` (no draft ID needed), or the remote MCP `workspace_usage` tool, to read the repository payer's current workspace and PR usage. These balances are shared across that payer's repositories, not a separate grant for each project. Report included, spent, reserved and available purchased workspace credits separately, along with the PR allowance and resetsAt. Use returned amounts; do not infer a balance from a plan name. A reservation is held for a running job, not another charge, and remainingCredits already excludes included reservations. Reading usage does not purchase credits or enable alerts.
39
+
40
+ Paid accounts normally receive separate workspace and PR allowances of 20% of normalized monthly base-plan revenue, excluding storage add-ons; returned values also reflect any explicit PR override. Verified free accounts have a small workspace allowance; inspect freeVerified instead of promising it to an unverified account. Hosted execution consumes included workspace allowance first, then purchased workspace credits. AI PR reviews and requested changes use their separate PR allowance; hosted PR checks use the workspace pool once. Workspace top-ups do not refill PR allowance. Ordinary remote file reads/edits and own-machine runners do not consume hosted runtime credits. A positive displayed balance does not guarantee a job can start: funding, reservations, concurrency and execution permissions still apply.
41
+
42
+ When a job is queued, inspect `cbx workspace logs <project> <draft> <run>` or remote `workspace_run_status` and its summary. If it is waiting for credits, explain the wait and the returned reset date; retain the run ID instead of repeatedly queuing replacements or polling in a tight loop. The runner reserves a funded lifecycle before starting and can stop at that deadline; unused funds are released after confirmed teardown. Included allowances reset on the first of each UTC month; purchased credits carry over. When PR allowance is exhausted, AI reviews/changes pause while manual PR work continues.
43
+
44
+ Purchases and recurring/notification settings stay in CodeRook Subscription; an authorized owner can also use the repository Settings top-up popup without leaving the repo. A minimum US$1 top-up funds 750 workspace credits (75% of the retail amount; 1,000 credits represent US$1 of metered usage). Automatic refills require the owner's explicit setup and consent, begin only after included spend is exhausted, and obey the owner's monthly cap. These tools cannot purchase credits, change payment settings or promise an automatic refill. If usage access is refused for a collaborator or a draft-scoped token, explain the restriction and ask the billing owner to inspect it on the site; do not broaden token permissions.
45
+
46
+ ## Before anything else
47
+
48
+ `cbx whoami` says who this machine is signed in as. If it refuses, the
49
+ person needs to run `cbx sign-in` themselves — it takes a personal access
50
+ token, so do not attempt it on their behalf.
51
+
52
+ If the command is not found at all, this machine has the skill but not the
53
+ command line. Either install it once with
54
+ `npm install --global @coderook/cli`, or put `npx -y @coderook/cli` where
55
+ `coderook` appears below — the commands are identical, npx is just slower
56
+ to start.
57
+
58
+ ## Reading
59
+
60
+ ```bash
61
+ cbx status # what has changed in this folder since its last version
62
+ cbx projects # every project on the account
63
+ cbx versions [project] # what has been saved, newest first
64
+ cbx tracks [project] # the lines a project has, and any waiting on a decision
65
+ ```
66
+
67
+ `status` is the one to reach for when somebody asks what is uncommitted, what
68
+ changed, or whether anything needs saving. It reads the folder and changes
69
+ nothing.
70
+
71
+ ## Saving
72
+
73
+ ```bash
74
+ cbx submit -m "What changed, in a sentence"
75
+ ```
76
+
77
+ **The first save from a folder must say which project it is.** A folder that
78
+ is not linked goes to a new project named after it — unless the account has a
79
+ project with a name like it, and then `submit` stops and lists them. Do not
80
+ guess: show the person the list and ask. Then run one of:
81
+
82
+ ```bash
83
+ cbx submit --into <project> -m "…" # this folder is that project
84
+ cbx submit --new -m "…" # a separate project (add --name if the name is taken)
85
+ cbx link <project> # link only; send nothing yet
86
+ ```
87
+
88
+ Never start a second project for work that already has one. A folder copied to
89
+ another machine, another operating system or another path is still the same
90
+ project: `cbx link` it.
91
+
92
+ Send only what changed; the version still names every file. Write the message
93
+ yourself from the actual diff rather than asking for one — a message like
94
+ "update" helps nobody reading the history later.
95
+
96
+ **Ask before running this.** Saving is the one thing here that leaves a mark on
97
+ somebody's account, and a version saved by mistake is a version they have to
98
+ explain. Propose it, say what it would send, and let them agree.
99
+
100
+ `cbx submit -n` shows exactly what would be sent without sending it. Use
101
+ that freely; it is safe and it is the honest way to answer "what would this
102
+ upload?".
103
+
104
+ ## Working in a git repository
105
+
106
+ CodeRook is a git remote. `npm install --global @coderook/cli` puts the helper
107
+ (`git-remote-coderook`) on PATH; the plugin and `npx` do not, so check with
108
+ `git ls-remote coderook://<project>` before relying on it.
109
+
110
+ ```bash
111
+ git remote -v # is there a coderook:// remote already?
112
+ git remote add coderook coderook://<project> # if not
113
+ git push coderook main # each new commit becomes a save
114
+ git push coderook <branch> # a branch becomes a line
115
+ git push coderook v1.2.0 # a tag names a version
116
+ git fetch coderook # bring other people's saves in
117
+ ```
118
+
119
+ If the project was started with `cbx submit` or the desktop app, the first push
120
+ is refused with a message saying so. When the repository holds that project,
121
+ `git push -o adopt coderook main` saves the current commit on top of what is
122
+ there, once; plain pushes work from then on. **Ask before adopting** — it is a
123
+ save like any other. If the project is somebody else's work under the same
124
+ name, push to a new name instead.
125
+
126
+ Git's limits here: no force pushes or branch deletions (saves are permanent), a
127
+ merge commit arrives as one save holding the merged tree, and a commit holding
128
+ a credential is refused — take the key out of history rather than looking for
129
+ a way round.
130
+
131
+ ## Fetching
132
+
133
+ ```bash
134
+ cbx get # bring this folder up to date
135
+ cbx clone <project> [dir] # fetch a project into a new folder
136
+ ```
137
+
138
+ `get` protects local edits by default. `cbx get --replace` discards them
139
+ to make an exact copy — only run it when the person has said so in those terms.
140
+
141
+ ## Lines of work
142
+
143
+ A project can have more than one line, so two people can save without one
144
+ landing on top of the other.
145
+
146
+ ```bash
147
+ cbx track # which line this folder saves to
148
+ cbx track spike --new # start a line and switch to it
149
+ cbx track main # switch back
150
+ cbx submit --track spike -m "…"
151
+ ```
152
+
153
+ Switching says where the next save goes and nothing else — no files move.
154
+ Run `cbx get` afterwards to bring that line's files in.
155
+
156
+ ## A history on this machine
157
+
158
+ A folder with a `.cbx/` folder in it keeps its own history, and there
159
+ `status`, `diff`, `log`, `switch`, `merge`, `push` and `pull` work on that
160
+ history instead of the account. Check with `cbx status`: it names the line and
161
+ the last local save.
162
+
163
+ ```bash
164
+ cbx init # start one (only when asked to)
165
+ cbx save -m "…" # record the folder as it is
166
+ cbx log # saves on this line
167
+ cbx switch -c spike # start a line here; no files change
168
+ cbx merge spike # bring that line's work in
169
+ cbx restore path --from main~1 # put a file back from an earlier save
170
+ cbx push # send new saves to CodeRook
171
+ cbx pull # bring CodeRook's saves in, merging if both moved
172
+ ```
173
+
174
+ A merge that stops on conflicts leaves markers in the files and waits. Show
175
+ the person the conflicts (`cbx status`) and let them decide; `cbx save`
176
+ finishes the merge once the markers are gone. Do not pass `--force` to
177
+ `restore`, `switch`, `save` or `pull` unless the person has said to throw away
178
+ the changes it names, and do not run `cbx merge --cancel` unless they asked.
179
+
180
+ ## Versions, and going back
181
+
182
+ Every save is a commit. A commit becomes a *version* — the thing the public
183
+ side of a project offers, and the thing a collaborator pulls — only when
184
+ somebody promotes it.
185
+
186
+ ```bash
187
+ cbx promote # pick from the last ten and name one
188
+ cbx mark 41 --pin # pin, hide, rename or label one save
189
+ cbx labels add shipped green # the labels a project can wear
190
+ cbx undo # put the project back on the save before this one
191
+ ```
192
+
193
+ `undo` moves where the project stands. Nothing is deleted and nothing is
194
+ renumbered — the saves passed over stay in the history, and the next save
195
+ carries on from wherever it now stands. It is the answer to "I pushed the
196
+ wrong thing"; hiding a version stops strangers reading it but leaves the
197
+ project standing on it, so the next person to pull still lands on the mistake.
198
+
199
+ **Ask before `undo`, `promote` and `take-down`.** They change what other
200
+ people see. `cbx versions` first, so the person can say which save they mean.
201
+
202
+ ## Who can reach a project
203
+
204
+ ```bash
205
+ cbx visibility # what it is now: private, unlisted or public
206
+ cbx visibility public --yes # list it on the owner's profile
207
+ cbx visibility private # back to the people invited
208
+ ```
209
+
210
+ **Never make a project public or unlisted unless the person has asked for
211
+ exactly that.** `--yes` skips the question the command would otherwise ask
212
+ them, so only pass it once they have answered it. Going private is always safe.
213
+
214
+ ## Serving a project as a website
215
+
216
+ ```bash
217
+ cbx pages # is the site on, its address, what it serves
218
+ cbx pages auto # find the build in what was published, and offer to serve it
219
+ cbx pages on --folder dist # serve a folder of the published version
220
+ cbx pages off # stop serving it
221
+ ```
222
+
223
+ **Never turn Pages on (`auto` or `on`) unless the person has asked for their
224
+ project to be served as a site.** It runs their code in strangers' browsers
225
+ under the project's name. Pass `--yes` only once they have said yes. Only
226
+ published versions are served and the project must be public. When `auto`
227
+ finds a build left out by the ignore rules it offers a `.gitignore` line and
228
+ lists the next steps; it never saves or publishes — ask before doing those.
229
+ Turning Pages off is always safe.
230
+
231
+ ## When two saves collide
232
+
233
+ If somebody saved while this folder was behind, the second save becomes a merge
234
+ waiting on a decision rather than overwriting anything.
235
+
236
+ ```bash
237
+ cbx merges # this folder's saves waiting on a decision
238
+ cbx merge <ref> # look at one, and decide
239
+ ```
240
+
241
+ Read the conflict out to the person and let them choose. Do not pick a side for
242
+ them: the whole reason it stopped is that the service could not tell which copy
243
+ was wanted.
244
+
245
+ ## What is worth leaving out
246
+
247
+ ```bash
248
+ cbx ignore --suggest # dependency directories, build output, virtual environments
249
+ cbx ignore --suggest --apply # add the confident ones to .gitignore
250
+ ```
251
+
252
+ Rules live in the project's own `.gitignore`, so CodeRook, git and the website
253
+ all read one file.
254
+
255
+ ## Bundles
256
+
257
+ ```bash
258
+ cbx bundle . project.cbx # the whole project, every version, as one file
259
+ cbx inspect project.cbx # what is inside, without unpacking
260
+ cbx unbundle project.cbx ./restored
261
+ ```
262
+
263
+ ## Reading a public project without signing in
264
+
265
+ Public projects can be read by anything, with no token, from
266
+ `https://api.coderook.com/v1/public`. There is no need to read the command
267
+ line's source to find these — this is the whole of it:
268
+
269
+ ```text
270
+ GET /projects?q= public projects, newest first
271
+ GET /projects/{owner}/{slug} one project
272
+ GET /projects/{owner}/{slug}/versions the versions it offers
273
+ GET /projects/{owner}/{slug}/releases every release, with its downloads
274
+ GET /projects/{owner}/{slug}/releases/latest newest release and its files
275
+ GET /projects/{owner}/{slug}/updates/latest.yml electron-updater feed
276
+ GET /projects/{owner}/{slug}/versions/{v}/files every file, with digests
277
+ GET /projects/{owner}/{slug}/versions/{v}/file?path= one file
278
+ GET /projects/{owner}/{slug}/versions/{v}/archive the version as a zip
279
+ GET /projects/{owner}/{slug}/versions/{v}/last-changes?path= which version last changed each entry
280
+ GET /projects/{owner}/{slug}/versions/{v}/attachments files attached to it
281
+ GET /projects/{owner}/{slug}/versions/{v}/attachments/{id} download one
282
+ ```
283
+
284
+ `{v}` is a version id or `latest`. A private project answers 404, exactly as
285
+ if it did not exist.
286
+
287
+ ### An app that updates itself from CodeRook
288
+
289
+ Release a version named like a version number and attach the installer:
290
+
291
+ ```bash
292
+ cbx release 1.4.0
293
+ cbx attach ./dist/MyApp-Setup-1.4.0.exe
294
+ ```
295
+
296
+ An Electron app then needs nothing custom — electron-builder's generic
297
+ provider pointed at the feed:
298
+
299
+ ```json
300
+ "publish": [{ "provider": "generic",
301
+ "url": "https://api.coderook.com/v1/public/projects/OWNER/SLUG/updates" }]
302
+ ```
303
+
304
+ The feed serves `latest.yml`, `latest-mac.yml` and `latest-linux.yml` with
305
+ each file's size and SHA-512, and redirects file names to their downloads.
306
+ Anything else can read `releases/latest` as JSON: version, notes, and every
307
+ file with its size, SHA-256 and `url`. Updaters have no account, so the
308
+ project they read must be public, but its source need not be:
309
+
310
+ ```bash
311
+ cbx release 1.4.0 --downloads public # notes, attachments and feed public; files stay private
312
+ cbx releases # public / downloads public / private, and the addresses
313
+ ```
314
+
315
+ **Ask before `--downloads public`**: it publishes the attached files to anyone.
316
+ One project holds the code and ships the app; a second "releases" project is
317
+ no longer needed.
318
+
319
+ ## Building executables for every platform
320
+
321
+ ```bash
322
+ cbx build --plan # how this machine would build each target
323
+ cbx build --target win,linux,mac # build them into .coderook/build/<target>/
324
+ ```
325
+
326
+ It builds on this machine, with the tools it has, and uploads nothing. Run
327
+ `--plan` first and read it out: a target marked "no" says what would build it
328
+ (Docker, a Mac, cargo-zigbuild) — pass that on rather than installing things
329
+ unasked. `--ship` attaches the results to the newest save, so **ask before
330
+ `--ship`**, as before any save. A project's own build description lives in
331
+ `coderook.build.json`.
332
+
333
+ ## Pull requests
334
+
335
+ A pull request is a proposal: a line offered to another line (`cbx propose`
336
+ opens one). Read and review them with `cbx pr`:
337
+
338
+ ```bash
339
+ cbx pr list # what is open on this project
340
+ cbx pr view M-3 # reviews, checks, conversation, what blocks merging
341
+ cbx pr files M-3 # what it changes
342
+ cbx pr comment M-3 --line src/app.ts:42 -m "…"
343
+ cbx pr approve M-3 # or request-changes M-3 -m "…"
344
+ cbx pr merge M-3
345
+ ```
346
+
347
+ **Ask before** `approve`, `request-changes`, `merge`, `close` and any comment:
348
+ each is the person speaking or acting, and is seen by others. An approval
349
+ stops counting when new saves land on the line, so re-check after pushing.
350
+ Every pull request carries a `coderook/malware` check: what the line adds or
351
+ changes is scanned before it can land, and a failure names the file. Do not
352
+ try to get round it.
353
+
354
+ ## Private files
355
+
356
+ `cbx private add "design/"` keeps matching files out of everything outside the
357
+ project (listings, zips, clone, Pages). Ask before changing the list: it
358
+ decides what strangers can see.
359
+
360
+ ## Runs
361
+
362
+ `cbx runs`, `cbx logs 12 --follow` to watch one, `cbx cancel 12` to stop one,
363
+ `cbx rerun 12` to run it again, `cbx approve 14` for one waiting for approval
364
+ (ask before each). Workflows can be YAML files in `.rook/workflows`; check
365
+ them with `cbx actions check` before saving. Never print or echo secrets:
366
+ `cbx secret set NAME` asks for the value itself, so let the person type it.
367
+
368
+ Runs receive `CODEROOK_API` and `CODEROOK_PROJECT`. Only jobs allowed to act on
369
+ the project receive a temporary `CODEROOK_TOKEN`; credential-free workspace
370
+ checks and artifact builds do not. Project secrets require approval of the
371
+ saved source and exact execution settings, and never reach PR checks.
372
+ Credential-capable jobs cannot keep artifacts; build them in a separate
373
+ credential-free job and publish the approved artifact in the release job.
374
+ Native runners must use CLI 0.41.1 or newer for chunk-safe masking and isolated
375
+ HOME/npm settings. They remain trusted machines, not a filesystem/network sandbox.
376
+
377
+ ## Issues, forks and security
378
+
379
+ `cbx issue view|comment|close|label|assign`, `cbx fork`, `cbx security`. Ask
380
+ before closing, labelling, assigning, forking, or sending anything: each is the
381
+ person acting where others see it. A security report is private to the
382
+ project's owner; never put vulnerability details in a public issue.
383
+
384
+ ## Releases
385
+
386
+ `cbx release v2.0 --draft --generate-notes` then `cbx release publish`;
387
+ `cbx verify owner/project v2.0 ./file` checks a download; `cbx deps` lists
388
+ known vulnerabilities in the lockfiles. Ask before publishing.
389
+
390
+ ## Mod repositories for games
391
+
392
+ A game's maker can run a mod repository: players' game clients read a signed
393
+ catalogue from it, modders publish to it, and nothing is listed until it
394
+ passes the repository's rules and a malware scan.
395
+
396
+ ```bash
397
+ cbx mods info zt1 # a repository's rules, for anybody
398
+ cbx mods publish ./BetterTrees --repo zt1 # zip, upload, wait for the checks
399
+ cbx mods publish ./HD-Art --repo zt1 --part animals # one part of a bigger mod
400
+ cbx mods list zt1 # your mods and how their checks went
401
+ cbx mods create my-game --name "My Game" --allow .png,.ogg,.json
402
+ ```
403
+
404
+ `publish` reads the folder's `mod.json` (or the repository's manifest) for the
405
+ mod's id, name, folder and version; `--id`, `--name`, `--folder` and
406
+ `--version` override it. It waits up to 30 minutes for the checks and prints
407
+ what failed, file by file — pass that on as it is. Programs and scripts
408
+ (`.exe`, `.dll`, `.ps1`, `.js` …) are refused in every repository, so do not
409
+ try to rename one past the check. **Ask before `publish`**, as before any
410
+ save: it makes the mod public once it passes. Ask before `remove`, `block`
411
+ and `delete`, which only the person should decide. The game-side protocol
412
+ (signed requests, the catalogue signature, downloads) is at
413
+ https://coderook.com/docs#mod-repositories.
414
+
415
+ ## Things not to do
416
+
417
+ - Do not run `cbx delete` unless the person has asked for that project to
418
+ be deleted, by name, in this conversation.
419
+ - Do not run `cbx sign-out`. It costs them a token they have to fetch
420
+ again and gains nothing.
421
+ - Do not guess a project name. `cbx projects` lists them; a folder that is
422
+ already linked needs no name at all.
423
+ - Do not pass `--new` to get past the question `submit` asks. It exists for a
424
+ separate project the person wants, not to avoid choosing.
425
+ - Do not run `cbx take-down`. It destroys the files in a version and they do
426
+ not come back. Say it exists and let its owner run it.
427
+
428
+ ## If something refuses
429
+
430
+ The commands explain themselves — pass the message on rather than rewording it.
431
+ A refusal that says a token was not accepted means signing in; one that says a
432
+ project does not allow machines means its owner turned that off deliberately,
433
+ and the answer is to say so, not to find another route in.