@coderook/cli 0.9.0 → 0.10.0

package/dist/cli/src/cli.js

@@ -16,9 +16,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * version, submit it.
  */
 const promises_1 = require("node:readline/promises");
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_process_1 = __importDefault(require("node:process"));
 const api_js_1 = require("./api.js");
+const registry_js_1 = require("./registry.js");
+const help_js_1 = require("./help.js");
+const project_commands_js_1 = require("./project_commands.js");
+const service_commands_js_1 = require("./service_commands.js");
 const worktree_js_1 = require("../../desktop-app/src/main/worktree.js");
 const upload_js_1 = require("../../desktop-app/src/main/upload.js");
 const download_js_1 = require("../../desktop-app/src/main/download.js");
@@ -26,6 +31,7 @@ const faults_js_1 = require("../../desktop-app/src/main/faults.js");
 const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const cbx_js_1 = require("../../desktop-app/src/main/cbx.js");
 const api_js_2 = require("./api.js");
+const runner_js_1 = require("./runner.js");
 const config_js_1 = require("./config.js");
 /*
   Read from the package rather than written twice. A hardcoded copy had
@@ -52,6 +58,7 @@ const dim = (text) => (colour ? `${text}` : text);
 const bold = (text) => (colour ? `${text}` : text);
 const accent = (text) => (colour ? `${text}` : text);
 const red = (text) => (colour ? `${text}` : text);
+const green = (text) => (colour ? `${text}` : text);
 function bytes(value) {
     if (value >= 1024 ** 3)
         return `${(value / 1024 ** 3).toFixed(2)} GB`;
@@ -767,42 +774,6 @@ async function commandDoctor() {
     }
     return 0;
 }
-const USAGE = `${bold("coderook")} — CodeRook from the command line
-
-${bold("Getting started")}
-  coderook sign-in                 Store a personal access token
-  coderook whoami                  Who this machine is signed in as
-  coderook projects                Every project on your account
-
-${bold("Working with a folder")}
-  coderook status [folder]         What is here that is not saved yet
-  coderook submit [folder] -m "…"  Send the changes as a new version
-  coderook get [folder]            Bring this folder up to date
-                                   (--replace for an exact copy)
-  coderook clone <project> [dir]   Fetch a project into a new folder
-  coderook rules [folder]          Show the ignore rules  (--init to start one)
-
-${bold("When somebody saved first")}
-  coderook merges                  Uploads of yours waiting on a decision
-  coderook merge <ref>             Look at one  (--mine --theirs --both --drop)
-
-${bold("Bundles")}
-  coderook bundle [folder] [out]   Pack the project as a .cbx
-  coderook unbundle <file> [dir]   Extract a .cbx
-  coderook inspect <file>          What a .cbx contains  (--files to list them)
-
-${bold("Other")}
-  coderook doctor                  Check the service, config and sign-in
-  coderook sign-out                Forget the token on this machine
-
-${bold("Options")}
-  -m, --message   The version message for submit
-  -n, --dry-run   Show what submit would send, without sending
-      --allow-secrets  Send files that look like credentials anyway
-      --token     Supply the token to sign-in instead of being asked
-
-${dim("The environment variable CODEROOK_TOKEN is used when set, so automated")}
-${dim("runs need nothing on disk. CODEROOK_API_URL points at another service.")}`;
 /**
  * Everything waiting on a decision, for one folder's project.
  *
@@ -924,43 +895,439 @@ Run coderook merge ${now.mergeTrack.reference} --apply to publish it.`));
     }
     return 0;
 }
-const COMMANDS = {
-    "sign-in": commandSignIn,
-    login: commandSignIn,
-    "sign-out": commandSignOut,
-    logout: commandSignOut,
-    whoami: () => commandWhoami(),
-    projects: () => commandProjects(),
-    status: commandStatus,
-    submit: commandSubmit,
-    publish: commandSubmit,
-    get: commandGet,
-    clone: commandClone,
-    rules: commandRules,
-    bundle: commandBundle,
-    unbundle: commandUnbundle,
-    inspect: commandInspect,
-    merges: commandMerges,
-    merge: commandMerge,
-    doctor: () => commandDoctor(),
-};
+/**
+ * Do this project's work on this machine.
+ *
+ * The other half of Actions. CodeRook writes down that a run is wanted; this
+ * asks whether there is one, fetches the version into a throwaway folder,
+ * runs the workflow's command there, sends the output up as it goes, and
+ * reports the verdict.
+ *
+ * The trust boundary is said out loud rather than buried in documentation,
+ * because it is the thing somebody should decide on purpose: anybody who can
+ * set a workflow's command on this project can run that command on this
+ * machine, as whoever started this.
+ */
+async function commandRunner(parsed) {
+    const reference = parsed.positional[0] ?? flagText(parsed, "project", "p");
+    if (!reference) {
+        console.error(red("Which project? coderook runner <project>"));
+        return 1;
+    }
+    const project = await (0, api_js_2.findProject)(reference);
+    if (!project) {
+        console.error(red(`No project of yours matches "${reference}".`));
+        return 1;
+    }
+    const name = flagText(parsed, "name") ?? node_os_1.default.hostname();
+    /*
+      What this machine will answer to. Its own platform unless told otherwise,
+      because that is what somebody means when they write a workflow that has to
+      produce a Windows installer.
+    */
+    const labels = (flagText(parsed, "labels", "label") ?? "")
+        .split(",")
+        .map((one) => one.trim())
+        .filter(Boolean);
+    const answersTo = labels.length ? labels : (0, runner_js_1.defaultLabels)();
+    const once = hasFlag(parsed, "once");
+    const every = Math.min(Math.max(Number(flagText(parsed, "poll") ?? 5), 1), 300);
+    console.log(`${bold("CodeRook runner")} ${dim(`· ${name}`)}`);
+    console.log(`Taking work for ${accent(project.slug)} ` +
+        dim(`· answering to ${answersTo.join(", ")}`));
+    /*
+      Printed every time rather than once on first use. Somebody who left this
+      running in a terminal a fortnight ago should be able to look at it and
+      see what it is permitted to do, without going to find the manual.
+    */
+    console.log(dim("Anyone who can set a workflow's command on this project can run it " +
+        "here, as you."));
+    /*
+      Said separately because it is the part people get wrong. The account token
+      is kept out of the command's environment, but a command runs as this user
+      and this user can read the token file — so the honest advice is a token
+      made for the runner, which can be revoked without taking the desktop
+      application and the command line down with it.
+    */
+    console.log(dim(`A command here runs as you and can read ${(0, config_js_1.configDirectory)()}. ` +
+        "Use a token minted for this machine, not your everyday one."));
+    console.log(dim("Stop with Ctrl-C."));
+    if (once)
+        console.log(dim("Taking one job, then stopping."));
+    console.log("");
+    let stopping = false;
+    node_process_1.default.on("SIGINT", () => {
+        if (stopping)
+            node_process_1.default.exit(130);
+        stopping = true;
+        console.log("");
+        console.log(dim("Finishing the current job, then stopping."));
+    });
+    for (;;) {
+        let job = null;
+        try {
+            job = await (0, runner_js_1.claim)(project.id, name, VERSION, answersTo);
+        }
+        catch (error) {
+            /*
+              Kept going rather than exiting. A runner is meant to be left alone,
+              and the network being briefly unavailable is not a reason to need
+              somebody to come back and start it again.
+            */
+            console.error(red(error instanceof Error ? error.message : String(error)));
+            if (once)
+                return 1;
+            await new Promise((wake) => setTimeout(wake, every * 1000));
+            continue;
+        }
+        if (!job) {
+            if (once || stopping) {
+                if (once)
+                    console.log(dim("Nothing waiting."));
+                return 0;
+            }
+            await new Promise((wake) => setTimeout(wake, every * 1000));
+            continue;
+        }
+        const label = `#${job.number} ${job.workflowName}`;
+        console.log(`${accent("▶")} ${label}${job.attempts > 1 ? dim(` (attempt ${job.attempts})`) : ""}`);
+        const began = Date.now();
+        const verdict = await (0, runner_js_1.performRun)(project.id, job, name);
+        try {
+            await (0, runner_js_1.report)(project.id, job.runId, verdict, Date.now() - began);
+        }
+        catch (error) {
+            console.error(red(`Could not report ${label}: ` +
+                (error instanceof Error ? error.message : String(error))));
+        }
+        console.log(verdict.status === "passed"
+            ? `${green("✓")} ${label} — ${verdict.summary}`
+            : `${red("×")} ${label} — ${verdict.summary}`);
+        if (once || stopping)
+            return verdict.status === "passed" ? 0 : 1;
+    }
+}
+/*
+  The commands, described where they are defined.
+
+  This replaced a plain name-to-function map sitting beside a hand-written
+  usage string. The two drifted, as they always do — the help is now generated
+  from these rows, so a command that exists is documented and a command that is
+  documented exists.
+*/
+const SPECS = [
+    {
+        name: "sign-in",
+        aliases: ["login"],
+        group: "Getting started",
+        summary: "store a personal access token on this machine",
+        usage: "sign-in",
+        detail: "Asks for a personal access token and saves it. Create one in your\n" +
+            "account settings on the website. The token is stored in your user\n" +
+            "configuration, not in the project folder, so it never lands in a\n" +
+            "version by accident.",
+        options: [
+            { flags: "--token <value>", description: "supply it instead of being asked" },
+        ],
+        run: commandSignIn,
+    },
+    {
+        name: "whoami",
+        group: "Getting started",
+        summary: "who this machine is signed in as",
+        usage: "whoami",
+        run: () => commandWhoami(),
+    },
+    {
+        name: "sign-out",
+        aliases: ["logout"],
+        group: "Getting started",
+        summary: "forget the token on this machine",
+        usage: "sign-out",
+        run: commandSignOut,
+    },
+    {
+        name: "status",
+        group: "Working with a folder",
+        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" +
+            "changed. Says nothing about other people's work — use `merges` for that.",
+        run: commandStatus,
+    },
+    {
+        name: "submit",
+        aliases: ["publish"],
+        group: "Working with a folder",
+        summary: "send the changes as a new version",
+        usage: 'submit [folder] -m "…"',
+        detail: "Sends everything that changed since the last version. If the folder is\n" +
+            "not linked to a project yet, one is created on your account, named\n" +
+            "after the folder and private to begin with.",
+        options: [
+            { flags: "-m, --message <text>", description: "what changed, in a sentence" },
+            { flags: "-n, --dry-run", description: "show what would be sent, send nothing" },
+            { flags: "--allow-secrets", description: "send files that look like credentials" },
+        ],
+        examples: ['coderook submit -m "Fix the export dialog"'],
+        run: commandSubmit,
+    },
+    {
+        name: "get",
+        group: "Working with a folder",
+        summary: "bring this folder up to date",
+        usage: "get [folder]",
+        options: [
+            { flags: "--replace", description: "make it an exact copy, discarding local changes" },
+        ],
+        run: commandGet,
+    },
+    {
+        name: "clone",
+        group: "Working with a folder",
+        summary: "fetch a project into a new folder",
+        usage: "clone <project> [dir]",
+        run: commandClone,
+    },
+    {
+        name: "ignore",
+        aliases: ["rules"],
+        group: "Working with a folder",
+        summary: "show the ignore rules for this folder",
+        usage: "ignore [folder]",
+        detail: "The local list of things not to send — build output, dependencies,\n" +
+            "anything private. Unrelated to a project's rules on the service, which\n" +
+            "are about who may do what.",
+        options: [{ flags: "--init", description: "write a starting set of rules" }],
+        run: commandRules,
+    },
+    {
+        name: "projects",
+        group: "Your projects",
+        summary: "every project on your account",
+        usage: "projects",
+        run: () => commandProjects(),
+    },
+    {
+        name: "versions",
+        group: "Your projects",
+        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.",
+        options: [{ flags: "--limit <n>", description: "how many to show (default 20)" }],
+        run: project_commands_js_1.commandVersions,
+    },
+    {
+        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" +
+            "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: [
+            "coderook ai my-project",
+            "coderook ai my-project --read off",
+            "coderook ai my-project --download off --request off",
+        ],
+        run: project_commands_js_1.commandAi,
+    },
+    {
+        name: "issues",
+        group: "Your projects",
+        summary: "issues on a project, or open one",
+        usage: "issues [project]",
+        options: [
+            { flags: '--new "<title>"', description: "open a new issue" },
+            { flags: "--body <text>", description: "the description for a new one" },
+        ],
+        examples: ['coderook issues my-project --new "Crash on export"'],
+        run: service_commands_js_1.commandIssues,
+    },
+    {
+        name: "releases",
+        group: "Your projects",
+        summary: "what has been released, and its files",
+        usage: "releases [project]",
+        run: service_commands_js_1.commandReleases,
+    },
+    {
+        name: "actions",
+        aliases: ["workflows"],
+        group: "Your projects",
+        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" +
+            "runs have passed. Use `coderook runner` to execute them on this machine.",
+        run: service_commands_js_1.commandWorkflows,
+    },
+    {
+        name: "delete",
+        group: "Your projects",
+        summary: "delete a project",
+        usage: "delete [project]",
+        detail: "Asks for the project name to be typed before it does anything. The\n" +
+            "service keeps deleted projects for 30 days before reclaiming the\n" +
+            "storage, so a mistake made today is recoverable this month.",
+        options: [{ flags: "--yes", description: "skip the confirmation" }],
+        run: service_commands_js_1.commandDelete,
+    },
+    {
+        name: "people",
+        aliases: ["collaborators"],
+        group: "People",
+        summary: "who can reach a project, and invite somebody",
+        usage: "people [project]",
+        options: [
+            { flags: "--invite <email>", description: "ask somebody to join" },
+            { flags: "--role <role>", description: "what they may do (default member)" },
+        ],
+        examples: ["coderook people my-project --invite sam@example.com"],
+        run: service_commands_js_1.commandCollaborators,
+    },
+    {
+        name: "watch",
+        group: "People",
+        summary: "what reaches you about a project",
+        usage: "watch [project] [--level versions]",
+        options: [
+            {
+                flags: "--level <level>",
+                description: "everything, versions, issues, releases, ignore",
+            },
+            { flags: "--email [off]", description: "include it in the daily email" },
+        ],
+        run: service_commands_js_1.commandWatch,
+    },
+    {
+        name: "tokens",
+        group: "Other",
+        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" +
+            "how you find one that is no longer needed. Create new ones on the\n" +
+            "website; they are only shown once.",
+        options: [{ flags: "--revoke <id>", description: "stop one working now" }],
+        run: service_commands_js_1.commandTokens,
+    },
+    {
+        name: "merges",
+        group: "When somebody saved first",
+        summary: "uploads of yours waiting on a decision",
+        usage: "merges",
+        run: commandMerges,
+    },
+    {
+        name: "merge",
+        group: "When somebody saved first",
+        summary: "look at one, and decide",
+        usage: "merge <ref>",
+        options: [
+            { flags: "--mine", description: "keep your side" },
+            { flags: "--theirs", description: "keep theirs" },
+            { flags: "--both", description: "keep both" },
+            { flags: "--drop", description: "abandon the upload" },
+        ],
+        run: commandMerge,
+    },
+    {
+        name: "bundle",
+        group: "Bundles",
+        summary: "pack the project as a .cbx",
+        usage: "bundle [folder] [out]",
+        run: commandBundle,
+    },
+    {
+        name: "unbundle",
+        group: "Bundles",
+        summary: "extract a .cbx",
+        usage: "unbundle <file> [dir]",
+        run: commandUnbundle,
+    },
+    {
+        name: "inspect",
+        group: "Bundles",
+        summary: "what a .cbx contains",
+        usage: "inspect <file>",
+        options: [{ flags: "--files", description: "list every file inside" }],
+        run: commandInspect,
+    },
+    {
+        name: "runner",
+        group: "Actions",
+        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" +
+            "Credentials in your environment are not passed to the commands it runs.",
+        options: [
+            { flags: "--once", description: "do one job and stop" },
+            { flags: "--name <label>", description: "how this machine is listed" },
+            { flags: "--labels <a,b>", description: "what kinds of run it answers to" },
+            { flags: "--poll <seconds>", description: "how long between asks" },
+        ],
+        examples: ["coderook runner my-game --labels windows,signing"],
+        run: commandRunner,
+    },
+    {
+        name: "doctor",
+        group: "Other",
+        summary: "check the service, config and sign-in",
+        usage: "doctor",
+        run: () => commandDoctor(),
+    },
+];
+const REGISTRY = (0, registry_js_1.buildRegistry)(SPECS);
 async function main(argv) {
     const [name, ...rest] = argv;
-    if (!name || name === "help" || name === "--help" || name === "-h") {
-        console.log(USAGE);
+    if (!name || name === "--help" || name === "-h") {
+        console.log((0, help_js_1.renderHelp)(REGISTRY, VERSION));
         return 0;
     }
     if (name === "--version" || name === "-v" || name === "version") {
         console.log(VERSION);
         return 0;
     }
-    const command = COMMANDS[name];
-    if (!command) {
-        console.error(red(`Unknown command: ${name}`));
-        console.error(dim("Run coderook help to see what there is."));
+    /*
+      `coderook help submit` and `coderook submit --help` reach the same page.
+      People reach for both, and one of them silently doing something else is
+      the kind of small betrayal that makes a tool feel unreliable.
+    */
+    if (name === "help") {
+        const wanted = rest[0];
+        if (!wanted) {
+            console.log((0, help_js_1.renderHelp)(REGISTRY, VERSION));
+            return 0;
+        }
+        const spec = REGISTRY.lookup.get(wanted);
+        if (!spec) {
+            console.error((0, help_js_1.renderUnknown)(wanted, (0, registry_js_1.nearestCommand)(REGISTRY, wanted)));
+            return 1;
+        }
+        console.log((0, help_js_1.renderCommandHelp)(spec));
+        return 0;
+    }
+    const spec = REGISTRY.lookup.get(name);
+    if (!spec) {
+        console.error((0, help_js_1.renderUnknown)(name, (0, registry_js_1.nearestCommand)(REGISTRY, name)));
         return 1;
     }
-    return command(parse(rest));
+    if (rest.includes("--help") || rest.includes("-h")) {
+        console.log((0, help_js_1.renderCommandHelp)(spec));
+        return 0;
+    }
+    if (spec.deprecatedBy) {
+        console.error(dim(`"${name}" is now "${spec.deprecatedBy}". The old name still works.`));
+    }
+    return spec.run(parse(rest));
 }
 /**
  * Set the status and let Node wind down on its own.

package/dist/cli/src/help.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * What `coderook help` prints.
+ *
+ * Generated from the registry rather than written out, so a command that
+ * exists is listed and a command that is listed exists. The previous usage
+ * text was maintained by hand next to the dispatch table, which is the
+ * arrangement where the two drift and nobody finds out until somebody follows
+ * the help and it does not work.
+ *
+ * Two levels, because they answer different questions. The list answers "what
+ * can this thing do", and is scanned rather than read — so it is one line per
+ * command, aligned, grouped by what somebody is trying to achieve. The detail
+ * answers "how exactly do I use this one", and is read properly, so it can
+ * afford whole sentences and examples.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderHelp = renderHelp;
+exports.renderCommandHelp = renderCommandHelp;
+exports.renderUnknown = renderUnknown;
+const registry_js_1 = require("./registry.js");
+const bold = (value) => `${value}`;
+const dim = (value) => `${value}`;
+const accent = (value) => `${value}`;
+/** Longest visible name, so the summary column lines up across every group. */
+function nameColumn(specs) {
+    return specs.reduce((widest, spec) => Math.max(widest, spec.usage.length), 0);
+}
+function renderHelp(registry, version) {
+    const listed = registry.specs.filter((spec) => !spec.deprecatedBy);
+    const column = Math.min(nameColumn(listed), 34);
+    const lines = [
+        `${bold("coderook")} ${dim(version)} — CodeRook from the command line`,
+        "",
+    ];
+    for (const group of registry_js_1.GROUP_ORDER) {
+        const inGroup = listed.filter((spec) => spec.group === group);
+        if (!inGroup.length)
+            continue;
+        lines.push(bold(group));
+        for (const spec of inGroup) {
+            lines.push(`  ${spec.usage.padEnd(column)}  ${spec.summary}`);
+        }
+        lines.push("");
+    }
+    lines.push(dim("coderook help <command>   what one command does, in full"), dim("CODEROOK_TOKEN is used when set, so automated runs need nothing on disk."), dim("CODEROOK_API_URL points at another service."));
+    return lines.join("\n");
+}
+function renderCommandHelp(spec) {
+    const lines = [
+        `${bold("coderook " + spec.name)} — ${spec.summary}`,
+        "",
+        bold("Usage"),
+        `  coderook ${spec.usage}`,
+    ];
+    if (spec.aliases?.length) {
+        lines.push("", bold("Also"), `  ${spec.aliases.map((alias) => `coderook ${alias}`).join("  ")}`);
+    }
+    if (spec.detail) {
+        lines.push("", spec.detail.trim());
+    }
+    if (spec.options?.length) {
+        const width = spec.options.reduce((widest, option) => Math.max(widest, option.flags.length), 0);
+        lines.push("", bold("Options"));
+        for (const option of spec.options) {
+            lines.push(`  ${option.flags.padEnd(width)}  ${option.description}`);
+        }
+    }
+    if (spec.examples?.length) {
+        lines.push("", bold("Examples"));
+        for (const example of spec.examples)
+            lines.push(`  ${accent(example)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * What to print when somebody asks for help on something that is not a command.
+ *
+ * Suggests a near match where there is one, and otherwise points at the list —
+ * a confident wrong suggestion sends somebody off to read the wrong page.
+ */
+function renderUnknown(typed, suggestion) {
+    const lines = [`Unknown command: ${typed}`];
+    if (suggestion)
+        lines.push(`Did you mean ${accent("coderook " + suggestion)}?`);
+    lines.push(dim("Run coderook help to see everything."));
+    return lines.join("\n");
+}