@coderook/cli 0.39.0 → 0.40.0

package/dist/cli/src/cli.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY = void 0;
 /**
  * cbx — the CodeBox engine from the command line, talking to CodeRook.
  *
@@ -40,6 +41,7 @@ const issue_command_js_1 = require("./issue_command.js");
 const verify_command_js_1 = require("./verify_command.js");
 const community_command_js_1 = require("./community_command.js");
 const pr_command_js_1 = require("./pr_command.js");
+const settings_commands_js_1 = require("./settings_commands.js");
 const project_commands_js_1 = require("./project_commands.js");
 const track_commands_js_1 = require("./track_commands.js");
 const tracks_js_1 = require("../../cbx/src/core/tracks.js");
@@ -722,7 +724,7 @@ async function commandImport(parsed) {
         flags: submitFlags,
     });
     if (code === 0 && plan.temporary) {
-        console.log(dim(`The working copy stays at ${plan.folder} until you remove it.
+        console.log(dim(`The working copy stays at ${plan.folder} until you remove it.
 ` +
             `Run ${accent("cbx get " + plan.name)} anywhere to fetch it fresh.`));
     }
@@ -1008,17 +1010,17 @@ async function commandSubmit(parsed) {
     */
     const shielded = (await (0, worktree_js_1.detectPrivateDirectories)(folder)).filter((finding) => [...sending].some((file) => file === finding.path || file.startsWith(`${finding.path}/`)));
     if (shielded.length && !hasFlag(parsed, "allow-private")) {
-        console.log(red(`
+        console.log(red(`
 ${shielded.length} folder${shielded.length === 1 ? "" : "s"} here belong${shielded.length === 1 ? "s" : ""} to a program, not to your project:`));
         for (const finding of shielded) {
             console.log(`  ${finding.path}  ${dim(`— ${finding.because}`)}`);
         }
-        console.log(`
+        console.log(`
 Nothing was sent. To leave them behind:`);
         for (const finding of shielded) {
             console.log(`  ${accent(`echo "${finding.rule}" >> .gitignore`)}`);
         }
-        console.error(`
+        console.error(`
 Or pass ${accent("--allow-private")} if they genuinely belong in the project.`);
         return 1;
     }
@@ -1067,7 +1069,7 @@ Or pass ${accent("--allow-private")} if they genuinely belong in the project.`);
             `rest were not opened.`));
     }
     if (stillPasted.length) {
-        console.log(red(`
+        console.log(red(`
 ${stillPasted.length} file${stillPasted.length === 1 ? " has a credential" : "s have credentials"} inside:`));
         for (const finding of stillPasted.slice(0, 20)) {
             console.log(`  ${finding.path}`);
@@ -1082,11 +1084,11 @@ ${stillPasted.length} file${stillPasted.length === 1 ? " has a credential" : "s
             console.log(dim(`  …and ${stillPasted.length - 20} more`));
         }
         if (!hasFlag(parsed, "allow-secrets")) {
-            console.error(`
+            console.error(`
 Nothing was sent. Move the key into an environment variable, and if` +
                 ` it has ever been published, replace it at the service that issued` +
                 ` it — a key that has leaked stays leaked.` +
-                `
+                `
 Pass ${accent("--allow-secrets")} if these are not real keys.`);
             return 1;
         }
@@ -1292,7 +1294,7 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
                 continue;
             }
             if (failure?.kind === "interrupted") {
-                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.`);
@@ -1535,7 +1537,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("cbx submit")}, or finish the fetch and ` +
                     `discard them with ${accent("cbx get --replace")}.`);
                 return 1;
@@ -1818,8 +1820,8 @@ async function suggestRules(folder, apply) {
     const addition = (0, detect_js_1.rulesFromSuggestions)(recommended);
     const shared = rules.shared.trimEnd();
     await (0, worktree_js_1.writeRules)(folder, {
-        shared: shared ? `${shared}
-
+        shared: shared ? `${shared}
+
 ${addition}` : addition,
         local: rules.local,
     });
@@ -2024,7 +2026,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 cbx merge <reference> to look at one.`));
     return 0;
 }
@@ -2127,7 +2129,7 @@ async function commandMerge(parsed) {
             console.log(dim(`  waiting on ${waiting.map((person) => person.displayName).join(", ")}`));
         }
     }
-    console.log(`
+    console.log(`
 ${accent(now.mergeTrack.reference)} · ` +
         /*
           The combined version is only counted once it can be built; until then
@@ -2146,7 +2148,7 @@ ${accent(now.mergeTrack.reference)} · ` +
             return 1;
         }
         const applied = await (0, api_js_1.applyMerge)(summary.id);
-        console.log(`
+        console.log(`
 Applied as ${accent(`v${applied.version.sequence}`)}.`);
         if (applied.closedIssues?.length) {
             console.log(`Closed ${applied.closedIssues.map((number) => `#${number}`).join(", ")}.`);
@@ -2156,13 +2158,13 @@ Applied as ${accent(`v${applied.version.sequence}`)}.`);
     }
     const stillOpen = now.conflicts.some((conflict) => !conflict.resolvedAt);
     if (!decision && stillOpen) {
-        console.log(dim(`
+        console.log(dim(`
 --mine keeps yours, --theirs keeps what was already saved,` +
-            ` --both keeps theirs and saves yours beside it, --drop removes the file.
+            ` --both keeps theirs and saves yours beside it, --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 cbx merge ${now.mergeTrack.reference} --apply to publish it.`));
     }
     return 0;
@@ -2320,7 +2322,7 @@ const SPECS = [
     },
     {
         name: "status",
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "what is here that is not saved yet",
         usage: "status [folder]",
         detail: "Compares the folder against the last version you sent and lists what\n" +
@@ -2332,7 +2334,7 @@ const SPECS = [
     {
         name: "submit",
         aliases: ["publish"],
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "send the changes as a new save",
         usage: 'submit [folder] -m "…"',
         detail: "Sends everything that changed since the last save. If the folder is\n" +
@@ -2386,7 +2388,7 @@ const SPECS = [
     {
         name: "diff",
         aliases: ["changes"],
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "what changed, line by line",
         usage: "diff [from] [to]",
         detail: "With nothing after it, compares this folder against the version it is\n" +
@@ -2463,6 +2465,7 @@ const SPECS = [
         group: "History on this machine",
         summary: "put files back the way a save had them",
         usage: "restore [paths…] [--from <save>]",
+        brief: "restore [paths…]",
         detail: "With no paths, makes the whole folder match the save; with paths,\n" +
             "only those files and folders. The default is the last save, which\n" +
             "throws away what you changed since.\n\n" +
@@ -2497,7 +2500,7 @@ const SPECS = [
     },
     {
         name: "link",
-        group: "Working with a folder",
+        group: "Getting started",
         summary: "connect this folder to a project already on your account",
         usage: "link <project> [folder]",
         detail: "Says which project this folder is a copy of, without sending or\n" +
@@ -2511,7 +2514,7 @@ const SPECS = [
     },
     {
         name: "unlink",
-        group: "Working with a folder",
+        group: "Getting started",
         summary: "detach this folder from its project",
         usage: "unlink [folder]",
         detail: "Forgets which project this folder belongs to. Nothing is deleted:\n" +
@@ -2600,7 +2603,7 @@ const SPECS = [
         */
         name: "track",
         aliases: ["checkout"],
-        group: "Working with a folder",
+        group: "Saving work",
         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" +
@@ -2621,7 +2624,7 @@ const SPECS = [
     {
         name: "tracks",
         aliases: ["branch", "branches"],
-        group: "Your projects",
+        group: "Lines, merges and pull requests",
         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" +
@@ -2633,7 +2636,7 @@ const SPECS = [
     },
     {
         name: "get",
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "bring this folder up to date",
         usage: "get [folder]",
         options: [
@@ -2643,7 +2646,7 @@ const SPECS = [
     },
     {
         name: "clone",
-        group: "Working with a folder",
+        group: "Getting started",
         summary: "fetch a project into a new folder",
         usage: "clone <project> [dir]",
         options: [
@@ -2658,7 +2661,7 @@ const SPECS = [
     {
         name: "licence",
         aliases: ["license"],
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "choose a licence, so people may actually use your work",
         usage: "licence [name] [folder]",
         detail: "A project with no licence cannot be used by anybody, whatever else it\n" +
@@ -2688,7 +2691,7 @@ const SPECS = [
     {
         name: "ignore",
         aliases: ["rules"],
-        group: "Working with a folder",
+        group: "Saving work",
         summary: "show the ignore rules for this folder",
         usage: "ignore [folder]",
         detail: "The local list of things not to send — build output, dependencies,\n" +
@@ -2722,14 +2725,14 @@ const SPECS = [
     },
     {
         name: "projects",
-        group: "Your projects",
+        group: "Getting started",
         summary: "every project on your account",
         usage: "projects",
         run: () => commandProjects(),
     },
     {
         name: "versions",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "what has been saved to a project",
         usage: "versions [project]",
         detail: "Newest first. Run it inside a linked folder to leave the name out.\n\n" +
@@ -2750,9 +2753,10 @@ const SPECS = [
     },
     {
         name: "workspace",
-        group: "Your projects",
+        group: "Workspaces",
         summary: "edit, save and run a private project remotely without a checkout",
         usage: "workspace <open|list|show|read|files|search|diff|patch|save|run|logs|cancel|deploy|preview|handoff|close|recipe|assign|assignments|unassign|checkout> <project> [workspace] [job] | workspace push [folder]",
+        brief: "workspace <action> <project>",
         detail: "Works on CodeRook's durable remote draft, never the current local folder. Use --data-file for structured edits or recipe configuration. Mutations need the reviewed --revision and a unique --key; reuse the same key and request when retrying. Recipes reference existing project workflows. Saving and deploying are separate operations.",
         options: [
             { flags: "--data-file <path>", description: "read an operation's JSON from this local file" },
@@ -2780,8 +2784,8 @@ const SPECS = [
     },
     {
         name: "machines",
-        group: "Your projects",
-        summary: "the PCs working on a project, how far behind each is, and its runners",
+        group: "Actions and builds",
+        summary: "the PCs on a project, how far behind each is, and its runners",
         usage: "machines [project]",
         detail: "Every PC with a folder linked to the project, or working on a draft handed to it, says which version it holds when cbx runs there. " +
             "This lists them with how many versions behind the project's line each is and how many files it has not saved, then the project's runners. " +
@@ -2791,26 +2795,20 @@ const SPECS = [
     },
     {
         name: "ai",
-        group: "Your projects",
-        summary: "what this project says about machines",
-        usage: "ai [project] [--read off]",
-        detail: "Shows the four answers a project gives about automated clients, and\n" +
-            "changes them. Everything is allowed until you say otherwise.\n\n" +
+        group: "Project settings",
+        summary: "what this project lets AI do (read only)",
+        usage: "ai [project]",
+        detail: "Shows the four answers a project gives about automated clients: can AI\n" +
+            "read it, download it, contribute to it, and make requests to it.\n" +
+            "Everything is allowed until somebody says otherwise.\n\n" +
             "Turning reading off is the one that refuses model training: it declares\n" +
             "the project as not-for-training in the page, in the response headers,\n" +
-            "and in the service's robots.txt. Turning downloads off does not — those\n" +
-            "are separate questions and answering one says nothing about the other.",
-        options: [
-            { flags: "--read [off]", description: "reading, indexing, summarising, training" },
-            { flags: "--download [off]", description: "taking the files" },
-            { flags: "--contribute [off]", description: "automated contributions" },
-            { flags: "--request [off]", description: "automated calls to its endpoints" },
-        ],
-        examples: [
-            "cbx ai my-project",
-            "cbx ai my-project --read off",
-            "cbx ai my-project --download off --request off",
-        ],
+            "and in the service's robots.txt.\n\n" +
+            "These are changed by a person, on the website (the project's Settings →\n" +
+            "Access & AI) or in the desktop app, never from the command line. The\n" +
+            "service refuses the change from any token, so an assistant holding one\n" +
+            "cannot switch off the rule that keeps it out.",
+        examples: ["cbx ai", "cbx ai my-project"],
         run: project_commands_js_1.commandAi,
     },
     {
@@ -2819,7 +2817,7 @@ const SPECS = [
           release. This is who can reach the project, and it is named for that.
         */
         name: "visibility",
-        group: "Your projects",
+        group: "Project settings",
         summary: "who can reach a project: private, link only or public",
         usage: "visibility [level] [project]",
         detail: "The level is public, unlisted or private. With none, says what the\n" +
@@ -2842,9 +2840,158 @@ const SPECS = [
         ],
         run: project_commands_js_1.commandVisibility,
     },
+    {
+        /*
+          Not `name` or `rename`, which read as acting on a file or a line. This
+          is what the project says about itself: the website's Settings → General.
+        */
+        name: "about",
+        group: "Project settings",
+        summary: "a project's name, description and address",
+        usage: "about [project] [--name <text>] [--description <text>]",
+        brief: "about [project]",
+        detail: "Shows the project's name, description, address and visibility, and\n" +
+            "changes the name or the description. The address comes from the\n" +
+            "project's short name, which stays as it is. An empty description\n" +
+            "clears it.",
+        options: [
+            { flags: "--name <text>", description: "what the project is called" },
+            { flags: "--description <text>", description: "one or two sentences about it" },
+            { flags: "--project <name>", description: "a project other than this folder's" },
+        ],
+        examples: [
+            "cbx about",
+            'cbx about --name "Night Owl Diner"',
+            'cbx about my-project --description "A diner sim set after midnight."',
+        ],
+        run: settings_commands_js_1.commandAbout,
+    },
+    {
+        /*
+          Beside `cbx tracks` rather than inside it. That lists where somebody can
+          save and is read all day; these are the rules an owner sets once.
+        */
+        name: "line-rules",
+        group: "Lines, merges and pull requests",
+        summary: "protection, approvals and required checks on each line",
+        usage: "line-rules [line] [--protect|--unprotect] [--approvals <n>] [--checks <a,b>] [--code-owners on|off] [--project <p>]",
+        brief: "line-rules [line] [options]",
+        detail: "With no line, lists every line with its rules and the code owners read\n" +
+            "from the default line's CODEOWNERS file. Name a line to change it — the\n" +
+            "website's Settings → Lines & reviews. Only the owner and admins can.\n\n" +
+            "A protected line refuses restores and merges that would overwrite it.\n" +
+            "Approvals is how many people must approve before a merge may land (0 to\n" +
+            "10). Checks are the names that must pass, comma separated; none clears\n" +
+            "them. Code owners on means a code owner of what changed must approve.",
+        options: [
+            { flags: "--protect", description: "protect the line" },
+            { flags: "--unprotect", description: "stop protecting it" },
+            { flags: "--approvals <n>", description: "approvals a merge needs, 0 to 10" },
+            { flags: "--checks <a,b>", description: "checks that must pass; none for no checks" },
+            { flags: "--code-owners <on|off>", description: "whether a code owner must approve" },
+            { flags: "--project <name>", description: "a project other than this folder's" },
+        ],
+        examples: [
+            "cbx line-rules",
+            "cbx line-rules main --protect --approvals 1",
+            "cbx line-rules main --checks build,test --code-owners on",
+            "cbx line-rules release --unprotect --checks none",
+        ],
+        run: settings_commands_js_1.commandLineRules,
+    },
+    {
+        name: "upload-rules",
+        group: "Project settings",
+        summary: "what uploads leave out, and encrypting secret files",
+        usage: "upload-rules [--ignore <file>] [--keep <file>] [--encrypt on|off] [--warn-large <MiB>] [--hold-pushes on|off] [--project <p>]",
+        brief: "upload-rules [options]",
+        detail: "The project's upload rules — the website's Settings → Files & privacy →\n" +
+            "Encrypted uploads. The desktop app and the website's scans read them.\n" +
+            "Ignore rules leave files out; keep rules bring back what an ignore rule\n" +
+            "caught. Both are read from a file of patterns, one per line, in the\n" +
+            "shape of a .gitignore; none clears them. This folder's own ignore file\n" +
+            "is `cbx ignore`.\n\n" +
+            "--encrypt covers files recognised as secrets before they are stored.\n" +
+            "--hold-pushes makes saves from anybody below admin wait for an admin to\n" +
+            "accept them (see `cbx held`). Owners and admins change these.",
+        options: [
+            { flags: "--ignore <file>", description: "replace the ignore rules with this file's" },
+            { flags: "--keep <file>", description: "replace the keep rules with this file's" },
+            { flags: "--encrypt <on|off>", description: "encrypt files recognised as secrets" },
+            { flags: "--warn-large <MiB>", description: "warn about files larger than this" },
+            { flags: "--hold-pushes <on|off>", description: "saves below admin wait to be accepted" },
+            { flags: "--project <name>", description: "a project other than this folder's" },
+        ],
+        examples: [
+            "cbx upload-rules",
+            "cbx upload-rules --ignore .coderookignore --warn-large 512",
+            "cbx upload-rules --encrypt on --keep none",
+        ],
+        run: settings_commands_js_1.commandUploadRules,
+    },
+    {
+        name: "assistant",
+        group: "Project settings",
+        summary: "the pull-request assistant: when it works and what it may do",
+        usage: "assistant [manual|automated] [project] [--review on|off] [--describe on|off] [--suggest on|off] [--change on|off] [--approve on|off] [--merge on|off]",
+        brief: "assistant [manual|automated]",
+        detail: "Manual means it works only when somebody asks on a pull request.\n" +
+            "Automated means it works on its own, doing what is switched on:\n" +
+            "reviewing, describing, suggesting, changing, approving and merging.\n" +
+            "Merging needs approving on too. Automated comes with a subscription on\n" +
+            "the owner's account. Only the project's admins change it — the\n" +
+            "website's Settings → Automation.",
+        options: [
+            { flags: "--review <on|off>", description: "review each pull request" },
+            { flags: "--describe <on|off>", description: "write the description" },
+            { flags: "--suggest <on|off>", description: "suggest changes" },
+            { flags: "--change <on|off>", description: "make changes when asked" },
+            { flags: "--approve <on|off>", description: "approve when it finds nothing" },
+            { flags: "--merge <on|off>", description: "merge what it approved (needs --approve on)" },
+            { flags: "--project <name>", description: "a project other than this folder's" },
+        ],
+        examples: [
+            "cbx assistant",
+            "cbx assistant automated --review on --describe on",
+            "cbx assistant --approve on --merge on",
+            "cbx assistant manual",
+        ],
+        run: settings_commands_js_1.commandAssistant,
+    },
+    {
+        /*
+          Not `transfer`, which already brings a project in from GitHub, GitLab
+          or Codeberg. This hands one of yours to somebody else.
+        */
+        name: "hand-over",
+        group: "Project settings",
+        summary: "offer a project to another owner, or answer an offer",
+        usage: "hand-over <username|email> [project] [--drop-access] [--yes] | hand-over offers | hand-over accept|decline|cancel <project>",
+        brief: "hand-over <user> [project]",
+        detail: "Offers the project to another account, as the website's Settings →\n" +
+            "Danger zone does. Nothing moves until they accept, and the offer lapses\n" +
+            "after fourteen days. Once accepted it is theirs, and only they can give\n" +
+            "it back, so this asks for TRANSFER to be typed unless --yes is given.\n" +
+            "Only the owner can offer a project.\n\n" +
+            "You keep admin access afterwards unless --drop-access says otherwise.\n" +
+            "`hand-over offers` lists offers to you and by you; accept or decline one\n" +
+            "made to you, or cancel one you made.",
+        options: [
+            { flags: "--drop-access", description: "give up your access when they accept" },
+            { flags: "-y, --yes", description: "offer it without asking, for scripts" },
+            { flags: "--project <name>", description: "a project other than this folder's" },
+        ],
+        examples: [
+            "cbx hand-over sam my-project",
+            "cbx hand-over sam@example.com --drop-access",
+            "cbx hand-over offers",
+            "cbx hand-over accept night-owl-diner",
+        ],
+        run: settings_commands_js_1.commandHandOver,
+    },
     {
         name: "pages",
-        group: "Your projects",
+        group: "Project settings",
         summary: "serve a public project as a website",
         usage: "pages [auto|on|off] [project]",
         detail: "With no word, says whether the project's site is on, its address, which\n" +
@@ -2877,9 +3024,10 @@ const SPECS = [
     },
     {
         name: "private",
-        group: "Your projects",
+        group: "Project settings",
         summary: "files and folders only the project's own people may see",
         usage: "private [list|add|remove|set] [pattern…] [--project <project>]",
+        brief: "private [list|add|remove|set]",
         detail: "Keeps chosen files out of sight in a public project: visitors, the\n" +
             "public API, git clone, zips, Pages and search leave them out, while\n" +
             "members see everything. Patterns work like a .gitignore:\n\n" +
@@ -2902,9 +3050,10 @@ const SPECS = [
     },
     {
         name: "mods",
-        group: "Your projects",
+        group: "Mods and bundles",
         summary: "mod repositories for games: set one up, publish to one",
         usage: "mods <create|repos|info|settings|builds|list|publish|remove|block|reports|delete> …",
+        brief: "mods <action> …",
         detail: "A mod repository is where a game's players get mods from. Its owner\n" +
             "sets the rules — which file types a mod may hold, archives opened and\n" +
             "checked too, the manifest each upload carries, size limits, and whether\n" +
@@ -2968,7 +3117,7 @@ const SPECS = [
     },
     {
         name: "issues",
-        group: "Your projects",
+        group: "Issues",
         summary: "issues on a project, or open one",
         usage: "issues [project]",
         detail: "Labels are given when the issue is opened rather than added\n" +
@@ -2990,20 +3139,39 @@ const SPECS = [
     },
     {
         name: "issue",
-        group: "Your projects",
-        summary: "read, answer, close, label or assign one issue",
-        usage: "issue view|comment|close|reopen|label|assign <number> … | issue labels | issue rules",
+        group: "Issues",
+        summary: "read, answer, close, label or assign one issue; labels and rules",
+        usage: "issue view|comment|close|reopen|label|assign <number> … | issue labels [add|change|remove <name>] | issue rules [add <kind> | on|off|change|remove <n>]",
+        brief: "issue <action> [number]",
         detail: "Closing says why: completed (the default), --reason not-planned, or\n" +
             "--duplicate-of <n>. Labels and assignment need write access; replying\n" +
             "needs only read access, as on the website.\n\n" +
+            "The project's labels and issue rules are the website's Settings → Issues.\n" +
+            "`issue labels` lists the labels; add, change and remove manage them.\n" +
+            "`issue rules` lists the rules, numbered; a rule is changed by its number.\n" +
+            "The kinds and what each takes:\n\n" +
+            "  auto-label   --words <a,b> --label <name> [--in title|body|both]\n" +
+            "  auto-assign  --assignees <a,b> [--label <name>]\n" +
+            "  welcome      -m <message>\n" +
+            "  stale        [--days <n>] [--close-after <n>] [--label] [-m] [--exempt <a,b>]\n\n" +
             "Inside a run, CODEROOK_TOKEN and CODEROOK_PROJECT are set, so a workflow\n" +
             "can comment on or label the issue that started it with no setup.",
         options: [
-            { flags: "-m, --message <text>", description: "what to say (comment, or a note when closing)" },
+            { flags: "-m, --message <text>", description: "what to say (comment, a note when closing, a rule's message)" },
             { flags: "--reason <completed|not-planned>", description: "why it is closed" },
             { flags: "--duplicate-of <n>", description: "close as a duplicate of another issue" },
             { flags: "--remove", description: "take the labels off instead" },
             { flags: "--starter", description: "with labels: add the usual set" },
+            { flags: "--colour <hex>", description: "labels add/change: its colour, like d73a4a" },
+            { flags: "--description <text>", description: "labels add/change: what it is for" },
+            { flags: "--name <text>", description: "labels change: rename it" },
+            { flags: "--words <a,b>", description: "rules: words that earn the label (auto-label)" },
+            { flags: "--label <name>", description: "rules: the label to add, or to act on" },
+            { flags: "--in <where>", description: "rules: title, body or both (auto-label)" },
+            { flags: "--assignees <a,b>", description: "rules: who to assign (auto-assign)" },
+            { flags: "--days <n>", description: "rules: quiet days before an issue is stale" },
+            { flags: "--close-after <n>", description: "rules: days after that before it is closed" },
+            { flags: "--exempt <a,b>", description: "rules: labels that keep an issue from going stale" },
             { flags: "--project <name>", description: "which project" },
         ],
         examples: [
@@ -3013,13 +3181,18 @@ const SPECS = [
             "cbx issue label 12 bug,ui",
             "cbx issue assign 12 sam",
             "cbx issue labels --starter",
+            'cbx issue labels add crash --colour d73a4a --description "It falls over"',
+            "cbx issue labels remove wontfix",
+            "cbx issue rules add auto-label --words crash,freeze --label crash",
+            'cbx issue rules add welcome -m "Thanks — we read every report."',
+            "cbx issue rules off 2",
         ],
         run: issue_command_js_1.commandIssue,
     },
     {
         name: "releases",
         aliases: ["tags"],
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "what has been released, and its files",
         usage: "releases [project]",
         detail: "Each release with its files and who can take them: public (source and\n" +
@@ -3037,7 +3210,7 @@ const SPECS = [
         */
         name: "hooks",
         aliases: ["webhooks"],
-        group: "Your projects",
+        group: "Project settings",
         summary: "where this project tells something else what happened",
         usage: "hooks [project]",
         detail: "A signed POST to an address of yours when something happens here.\n" +
@@ -3047,17 +3220,31 @@ const SPECS = [
             "check.reported, change_request.opened, change_request.reviewed,\n" +
             "issue.opened, issue.closed, issue.reopened, issue.commented,\n" +
             "issue.labeled, run.finished, run.failed, release.published.\n" +
-            "Naming none of them sends all of them.",
+            "Naming none of them sends all of them.\n\n" +
+            "A hook is named by its id or its address. With only one hook on the\n" +
+            "project, --test, --deliveries, --redeliver and --on need no name.\n" +
+            "Twenty failures in a row switch a hook off; --on switches it back on\n" +
+            "with a clean count.",
         options: [
             { flags: "--add <url>", description: "notify this address; https only" },
-            { flags: "--events <a,b>", description: "only these, comma separated" },
+            { flags: "--events <a,b>", description: "only these, comma separated (with --hook: change them; all for every one)" },
             { flags: "--remove <id>", description: "stop notifying it" },
+            { flags: "--hook <id>", description: "which hook --events or --redeliver is about" },
+            { flags: "--test [id]", description: "send a signed ping now and say how it was answered" },
+            { flags: "--deliveries [id]", description: "the most recent deliveries and how each went" },
+            { flags: "--redeliver <delivery>", description: "send a delivery again (the start of its id is enough)" },
+            { flags: "--on [id]", description: "switch a hook that was switched off back on" },
             { flags: "--project <name>", description: "which project" },
         ],
         examples: [
             "cbx hooks",
             "cbx hooks --add https://example.com/coderook",
             "cbx hooks --add https://example.com/builds --events version.published",
+            "cbx hooks --test",
+            "cbx hooks --deliveries 3f2a9c10-…",
+            "cbx hooks --redeliver 7b1e04aa --hook 3f2a9c10-…",
+            "cbx hooks --hook 3f2a9c10-… --events release.published,run.failed",
+            "cbx hooks --on 3f2a9c10-…",
         ],
         run: service_commands_js_1.commandHooks,
     },
@@ -3070,7 +3257,7 @@ const SPECS = [
           This moves the project.
         */
         name: "undo",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "put the project back on an earlier save",
         usage: "undo [n] [project]",
         detail: "Goes back one save unless you name another to go back to.\n\n" +
@@ -3089,7 +3276,7 @@ const SPECS = [
           actually offers.
         */
         name: "promote",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "turn a commit into a version people can fetch",
         usage: "promote [n] [project]",
         detail: "Shows the last ten commits and asks which one. Give a number to skip\n" +
@@ -3125,7 +3312,7 @@ const SPECS = [
           hides it, labels it — which is what it does anyway.
         */
         name: "attach",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "put a file people can download on a version",
         usage: "attach <file> [n] [project]",
         detail: "A version can carry downloads — an installer, a build, a changelog —\n" +
@@ -3150,7 +3337,7 @@ const SPECS = [
     {
         name: "notes",
         aliases: ["release-notes"],
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "read or write what a version says about itself",
         usage: "notes [n] [project]",
         detail: "The release info the website shows on a version, and the same field\n" +
@@ -3178,7 +3365,7 @@ const SPECS = [
     {
         name: "mark",
         aliases: ["set"],
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "name, hide, pin or label one save",
         usage: "mark [n] [project]",
         detail: "Changes the newest version unless you name another.\n" +
@@ -3210,9 +3397,10 @@ const SPECS = [
     },
     {
         name: "labels",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "the labels this project puts on versions",
         usage: "labels [list|add|remove] [name] [colour]",
+        brief: "labels [list|add|remove]",
         detail: "A label is a name and a colour. Put as many on a version as you like —\n" +
             "how you group and colour your own history is yours to decide.",
         examples: [
@@ -3226,7 +3414,7 @@ const SPECS = [
     {
         name: "held",
         aliases: ["waiting"],
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "versions waiting for somebody to approve them",
         usage: "held [project]",
         detail: "A project can be set to hold pushes from anyone below admin until an\n" +
@@ -3236,9 +3424,10 @@ const SPECS = [
     },
     {
         name: "review",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "accept a held version, or turn it down",
         usage: "review <n> --approve | --decline",
+        brief: "review <n> --approve|--decline",
         options: [
             {
                 flags: "--approve",
@@ -3260,7 +3449,7 @@ const SPECS = [
           saying what was removed and by whom.
         */
         name: "take-down",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "remove a version's files, for something published by mistake",
         usage: "take-down <n> --yes",
         detail: "The files go and do not come back. The version stays in the history as\n" +
@@ -3280,7 +3469,7 @@ const SPECS = [
         */
         name: "release",
         aliases: ["tag"],
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "give a version a name, so people know which one to fetch",
         usage: "release <name> [project]",
         detail: "Names the newest version unless you name another with --version.\n" +
@@ -3315,9 +3504,10 @@ const SPECS = [
     },
     {
         name: "fork",
-        group: "Your projects",
+        group: "Project settings",
         summary: "your own copy of somebody's project, and offering work back",
         usage: "fork <owner/project> [--name <slug>] | fork offer [line] --title <text> | fork sync",
+        brief: "fork <owner/project>",
         detail: "A fork is a private project under your account with the original's latest\n" +
             "public version (its private files left out). Nothing is uploaded again.\n\n" +
             "Inside a fork, `cbx fork offer <line>` offers that line to the original as\n" +
@@ -3336,32 +3526,44 @@ const SPECS = [
     },
     {
         name: "security",
-        group: "Your projects",
-        summary: "report a vulnerability privately, or handle reports",
-        usage: "security report <owner/project> --title <text> | security list | view|reply|mark S-<n>",
+        group: "Project settings",
+        summary: "report a vulnerability privately, handle reports, set the policy",
+        usage: "security report <owner/project> --title <text> | security list | view|reply|mark S-<n> | security policy [--on|--off] [--text <file>]",
+        brief: "security <action> [S-n]",
         detail: "A report is seen only by the project's owner and admins, and by whoever\n" +
             "sent it. Please use this rather than a public issue for anything that\n" +
-            "could hurt people using the project.",
+            "could hurt people using the project.\n\n" +
+            "`security policy` shows whether the project takes private reports and\n" +
+            "what it tells people about sending one (the website's Settings →\n" +
+            "Security). --text reads a file when one by that name exists, and uses\n" +
+            "the words themselves otherwise. Owners and admins change it.",
         options: [
             { flags: "--title <text>", description: "report: what is wrong" },
             { flags: "--body <text>", description: "report: details and how to reproduce it" },
             { flags: "--severity <level>", description: "report: low, medium, high or critical" },
             { flags: "-m, --message <text>", description: "reply: what to say" },
-            { flags: "--project <name>", description: "list/view/reply/mark: which project" },
+            { flags: "--on", description: "policy: take private reports" },
+            { flags: "--off", description: "policy: stop taking them" },
+            { flags: "--text <file or text>", description: "policy: the reporting policy" },
+            { flags: "--clear", description: "policy: remove the written policy" },
+            { flags: "--project <name>", description: "list/view/reply/mark/policy: which project" },
         ],
         examples: [
             'cbx security report sam/editor --title "Path traversal in export" --severity high',
             "cbx security list",
             'cbx security reply S-3 -m "Confirmed; fix in 2.0.1"',
             "cbx security mark S-3 fixed",
+            "cbx security policy",
+            "cbx security policy --on --text SECURITY.md",
         ],
         run: community_command_js_1.commandSecurity,
     },
     {
         name: "verify",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "check a download against its release's signed manifest",
         usage: "verify <owner/project> <release> <file…>",
+        brief: "verify <owner/project> …",
         detail: "Every public release has a manifest listing each file with its size and\n" +
             "SHA-256, signed with CodeRook's release key. This checks the signature,\n" +
             "then the files you downloaded. A mismatch means do not run it.",
@@ -3371,7 +3573,7 @@ const SPECS = [
     },
     {
         name: "deps",
-        group: "Your projects",
+        group: "Versions and releases",
         summary: "known vulnerabilities in a save's dependencies",
         usage: "deps [version]",
         detail: "Reads the lockfiles in the save (package-lock.json, yarn.lock,\n" +
@@ -3389,7 +3591,7 @@ const SPECS = [
     {
         name: "actions",
         aliases: ["workflows"],
-        group: "Your projects",
+        group: "Actions and builds",
         summary: "the automations a project has",
         usage: "actions [project]",
         detail: "Shows what each action runs, what it runs on, and how many of its\n" +
@@ -3429,9 +3631,10 @@ const SPECS = [
     },
     {
         name: "pr",
-        group: "Working with a folder",
+        group: "Lines, merges and pull requests",
         summary: "pull requests: list, read, review, comment, merge",
         usage: "pr <list|view|files|comment|approve|request-changes|ask|label|title|ready|draft|retarget|close|reopen|merge> [M-3] …",
+        brief: "pr <action> [M-3]",
         detail: "A pull request is a line offered to another line (cbx propose opens one).\n" +
             "This is the Pull requests tab of the website, from here:\n\n" +
             "  list [--all|--state merged] [--mine] [--label bug]   the project's pull requests\n" +
@@ -3474,7 +3677,7 @@ const SPECS = [
     },
     {
         name: "cancel",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "stop a run that is waiting or working",
         usage: "cancel <number> [project]",
         detail: "Marks the run cancelled at once. A runner working on it is told at its next\n" +
@@ -3484,7 +3687,7 @@ const SPECS = [
     },
     {
         name: "rerun",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "run a finished run again",
         usage: "rerun <number> [project]",
         detail: "Queues the same action against the same save. When the run was checking a\n" +
@@ -3494,7 +3697,7 @@ const SPECS = [
     },
     {
         name: "approve",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "let a run that waits for approval start",
         usage: "approve <number> [project]",
         detail: "An action marked as needing approval (often one that publishes) waits\n" +
@@ -3505,9 +3708,10 @@ const SPECS = [
     {
         name: "secret",
         aliases: ["secrets"],
-        group: "Actions",
+        group: "Project settings",
         summary: "values runs need that must not be in the files",
         usage: "secret list | set <NAME> | remove <NAME>",
+        brief: "secret list|set|remove [NAME]",
         detail: "A secret is handed to each run as an environment variable of the same\n" +
             "name, but only to runs started by people who can change the project.\n" +
             "Run logs show *** in its place. Its value is never shown again.\n\n" +
@@ -3528,7 +3732,7 @@ const SPECS = [
     },
     {
         name: "runs",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "what has run, and how it went",
         usage: "runs [project]",
         detail: "Newest first, with the machine that took each one. A run that is still\n" +
@@ -3545,7 +3749,7 @@ const SPECS = [
     },
     {
         name: "logs",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "what one run printed",
         usage: "logs <number> [project]",
         detail: "The output the runner sent up, in order. Anything the command wrote to\n" +
@@ -3557,7 +3761,7 @@ const SPECS = [
     },
     {
         name: "delete",
-        group: "Your projects",
+        group: "Project settings",
         summary: "delete a project",
         usage: "delete [project]",
         detail: "Asks for the project name to be typed before it does anything. The\n" +
@@ -3569,25 +3773,34 @@ const SPECS = [
     {
         name: "people",
         aliases: ["collaborators"],
-        group: "People",
-        summary: "who can reach a project, and invite somebody",
+        group: "Project settings",
+        summary: "who can reach a project: invite, change a role, remove",
         usage: "people [project]",
+        detail: "Lists the project's people and the invites waiting on a reply. Somebody\n" +
+            "is named by their email address or display name, as the list shows them.\n" +
+            "Only the project's owner and admins can see the list or change it.",
         options: [
             { flags: "--invite <email>", description: "ask somebody to join" },
-            { flags: "--role <role>", description: "write, read or admin (default write)" },
+            { flags: "--role <role>", description: "write, read or admin (default write when inviting)" },
+            { flags: "--change <who>", description: "give one of the project's people the --role named" },
+            { flags: "--remove <who>", description: "take somebody off the project" },
+            { flags: "--cancel-invite <email>", description: "withdraw an invite nobody has accepted" },
             { flags: "--accept <link>", description: "join a project you were invited to" },
         ],
         examples: [
             "cbx people my-project --invite sam@example.com",
+            "cbx people --change sam@example.com --role admin",
+            "cbx people --remove sam@example.com",
             "cbx people --accept https://coderook.com/?invite=…",
         ],
         run: service_commands_js_1.commandCollaborators,
     },
     {
         name: "watch",
-        group: "People",
+        group: "Project settings",
         summary: "what reaches you about a project",
         usage: "watch [project] [--level versions]",
+        brief: "watch [project]",
         options: [
             {
                 flags: "--level <level>",
@@ -3599,7 +3812,7 @@ const SPECS = [
     },
     {
         name: "tokens",
-        group: "Other",
+        group: "For assistants",
         summary: "the tokens that can act as your account",
         usage: "tokens",
         detail: "Lists personal access tokens with when each was last used, which is\n" +
@@ -3610,9 +3823,10 @@ const SPECS = [
     },
     {
         name: "propose",
-        group: "Working with a folder",
+        group: "Lines, merges and pull requests",
         summary: "offer this folder's line to main",
         usage: 'propose -m "title" [--into main] [--body text] [folder]',
+        brief: "propose -m \"title\" [folder]",
         options: [
             { flags: "-m, --message <text>", description: "the proposal's title" },
             { flags: "--into <line>", description: "the line to propose into (default main)" },
@@ -3627,7 +3841,7 @@ const SPECS = [
     },
     {
         name: "proposals",
-        group: "Working with a folder",
+        group: "Lines, merges and pull requests",
         summary: "open proposals on this project",
         usage: "proposals [--all] [folder]",
         options: [{ flags: "--all", description: "include merged and cancelled ones" }],
@@ -3635,7 +3849,7 @@ const SPECS = [
     },
     {
         name: "merges",
-        group: "When somebody saved first",
+        group: "Lines, merges and pull requests",
         summary: "this folder's uploads waiting on a decision",
         usage: "merges [folder]",
         detail: "Both merge commands read the project this folder is linked to, so run\n" +
@@ -3644,7 +3858,7 @@ const SPECS = [
     },
     {
         name: "merge",
-        group: "When somebody saved first",
+        group: "Lines, merges and pull requests",
         summary: "merge a line here, or decide one waiting on CodeRook",
         usage: "merge <line | ref>",
         detail: "In a folder with a history of its own, merges a line or a save into\n" +
@@ -3668,21 +3882,21 @@ const SPECS = [
     },
     {
         name: "bundle",
-        group: "Bundles",
+        group: "Mods and bundles",
         summary: "pack the project as a .cbx",
         usage: "bundle [folder] [out]",
         run: commandBundle,
     },
     {
         name: "unbundle",
-        group: "Bundles",
+        group: "Mods and bundles",
         summary: "extract a .cbx",
         usage: "unbundle <file> [dir]",
         run: commandUnbundle,
     },
     {
         name: "inspect",
-        group: "Bundles",
+        group: "Mods and bundles",
         summary: "what a .cbx contains",
         usage: "inspect <file>",
         options: [{ flags: "--files", description: "list every file inside" }],
@@ -3690,7 +3904,7 @@ const SPECS = [
     },
     {
         name: "runner",
-        group: "Actions",
+        group: "Actions and builds",
         summary: "take this project's runs and do them here",
         usage: "runner <project>",
         detail: "Claims queued runs for a project and executes them on this machine.\n" +
@@ -3712,7 +3926,7 @@ const SPECS = [
           is a file in a folder, and this already knows where the folder is.
         */
         name: "skill",
-        group: "Other",
+        group: "For assistants",
         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" +
@@ -3744,7 +3958,7 @@ const SPECS = [
           stdin and stdout, and exits with them.
         */
         name: "mcp",
-        group: "Other",
+        group: "For assistants",
         summary: "serve CodeRook to Claude Code, Codex and other assistants",
         usage: "mcp [--workspaces]",
         options: [{ flags: "--workspaces", description: "opt into the remote connector's write/run/deploy tools and workspace permissions" }],
@@ -3772,7 +3986,7 @@ const SPECS = [
     },
     {
         name: "doctor",
-        group: "Other",
+        group: "Getting started",
         summary: "check the service, config and sign-in",
         usage: "doctor",
         run: () => commandDoctor(),
@@ -3797,9 +4011,10 @@ function localTwin(name, original, local, row, extra) {
 }
 SPECS.push({
     name: "build",
-    group: "Actions",
+    group: "Actions and builds",
     summary: "build executables for Windows, Linux and macOS on this machine",
     usage: "build [folder] [--target win,linux,mac]",
+    brief: "build [folder] [--target …]",
     detail: "Builds the project in this folder for each target, using whatever this\n" +
         "machine has: Go, Bun, Deno and .NET build every platform from any one;\n" +
         "Rust does with cargo-zigbuild; Electron builds Linux from Windows with\n" +
@@ -3848,7 +4063,8 @@ SPECS.push(localTwin("push", "submit", local_commands_js_1.localPush, {
         "Anywhere else, this is `cbx get`.",
     examples: ["cbx pull", "cbx pull my-project"],
 }, [{ flags: "-f, --force", description: "discard unsaved changes that are in the way" }]));
-const REGISTRY = (0, registry_js_1.buildRegistry)(SPECS);
+/* Exported for the help test (test/help_listing.test.ts); nothing else imports this file. */
+exports.REGISTRY = (0, registry_js_1.buildRegistry)(SPECS);
 async function main(argv) {
     const old = (0, node_check_js_1.nodeTooOld)();
     if (old) {
@@ -3857,7 +4073,7 @@ async function main(argv) {
     }
     const [name, ...rest] = argv;
     if (!name || name === "--help" || name === "-h") {
-        console.log((0, help_js_1.renderHelp)(REGISTRY, version_js_1.VERSION));
+        console.log((0, help_js_1.renderHelp)(exports.REGISTRY, version_js_1.VERSION));
         return 0;
     }
     if (name === "--version" || name === "-v" || name === "version") {
@@ -3872,20 +4088,20 @@ async function main(argv) {
     if (name === "help") {
         const wanted = rest[0];
         if (!wanted) {
-            console.log((0, help_js_1.renderHelp)(REGISTRY, version_js_1.VERSION));
+            console.log((0, help_js_1.renderHelp)(exports.REGISTRY, version_js_1.VERSION));
             return 0;
         }
-        const spec = REGISTRY.lookup.get(wanted);
+        const spec = exports.REGISTRY.lookup.get(wanted);
         if (!spec) {
-            console.error((0, help_js_1.renderUnknown)(wanted, (0, registry_js_1.nearestCommand)(REGISTRY, wanted)));
+            console.error((0, help_js_1.renderUnknown)(wanted, (0, registry_js_1.nearestCommand)(exports.REGISTRY, wanted)));
             return 1;
         }
         console.log((0, help_js_1.renderCommandHelp)(spec));
         return 0;
     }
-    const spec = REGISTRY.lookup.get(name);
+    const spec = exports.REGISTRY.lookup.get(name);
     if (!spec) {
-        console.error((0, help_js_1.renderUnknown)(name, (0, registry_js_1.nearestCommand)(REGISTRY, name)));
+        console.error((0, help_js_1.renderUnknown)(name, (0, registry_js_1.nearestCommand)(exports.REGISTRY, name)));
         return 1;
     }
     if (rest.includes("--help") || rest.includes("-h")) {
@@ -3908,10 +4124,17 @@ async function main(argv) {
 function leave(code) {
     node_process_1.default.exitCode = code;
 }
-(0, network_js_1.tuneNetwork)();
-main(node_process_1.default.argv.slice(2))
-    .then(leave)
-    .catch((error) => {
-    console.error(red((0, network_js_1.describeError)(error)));
-    leave(1);
-});
+/*
+  Run only when started as the program. A test loads this file to read the
+  command table — that every command is listed once, and fits — and must not
+  find itself running a command with the test runner's own arguments.
+*/
+if (require.main === module) {
+    (0, network_js_1.tuneNetwork)();
+    main(node_process_1.default.argv.slice(2))
+        .then(leave)
+        .catch((error) => {
+        console.error(red((0, network_js_1.describeError)(error)));
+        leave(1);
+    });
+}