@coderook/cli 0.22.2 → 0.24.0

package/dist/cli/src/cli.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * CodeRook from the command line.
+ * cbx — the CodeBox engine from the command line, talking to CodeRook.
  *
  * The same engines the desktop application uses — the same scanner, the same
  * ignore rules, the same upload and download — with a terminal in front of
@@ -17,12 +17,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const promises_1 = require("node:readline/promises");
 const node_os_1 = __importDefault(require("node:os"));
+const promises_2 = require("node:fs/promises");
 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 progress_js_1 = require("./progress.js");
+const publish_js_1 = require("./publish.js");
 const project_commands_js_1 = require("./project_commands.js");
 const track_commands_js_1 = require("./track_commands.js");
 const mcp_js_1 = require("./mcp.js");
@@ -37,11 +39,12 @@ const identify_js_1 = require("../../desktop-app/src/main/identify.js");
 const detect_js_1 = require("../../desktop-app/src/main/detect.js");
 const cbx_js_1 = require("../../desktop-app/src/main/cbx.js");
 const api_js_2 = require("./api.js");
+const import_command_js_1 = require("./import_command.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
-  already drifted from the published version, which makes `coderook doctor`
+  already drifted from the published version, which makes `cbx doctor`
   worse than useless when working out what somebody is actually running.
 */
 const VERSION = (() => {
@@ -295,7 +298,7 @@ async function commandStatus(parsed) {
     if (stale.length) {
         console.log(dim(`${stale.length} file${stale.length === 1 ? "" : "s"} in the saved version ` +
             `${stale.length === 1 ? "is" : "are"} newer than the cop${stale.length === 1 ? "y" : "ies"} here ` +
-            `— run ${accent("coderook get")} to bring ${stale.length === 1 ? "it" : "them"} down.`));
+            `— run ${accent("cbx get")} to bring ${stale.length === 1 ? "it" : "them"} down.`));
         for (const [path] of stale.slice(0, 10))
             console.log(dim(`  behind  ${path}`));
     }
@@ -313,6 +316,103 @@ async function commandStatus(parsed) {
         console.log(dim(`  …and ${files.length - 50} more`));
     return 0;
 }
+/**
+ * Bring an existing repository in from another host.
+ *
+ * Snapshot only, and it says so. The files arrive, the history does not —
+ * see `import_command.ts` for why that is a limit rather than an omission.
+ * Everything after the fetch is the ordinary save path, so an import
+ * produces exactly the Version that saving the same folder would.
+ */
+async function commandImport(parsed) {
+    const url = parsed.positional[0];
+    if (!url) {
+        console.error(red("Nothing to import from."));
+        console.error("Give the address of a repository, for example:");
+        console.error(`  ${accent("cbx import https://github.com/owner/project")}`);
+        return 1;
+    }
+    if (!(0, import_command_js_1.looksLikeRepositoryUrl)(url)) {
+        console.error(red(`${url} does not look like a repository address.`));
+        console.error("Expected something like https://github.com/owner/project or\n" +
+            "git@github.com:owner/project.git");
+        return 1;
+    }
+    if (!(await (0, import_command_js_1.gitAvailable)())) {
+        console.error(red("Import needs git on this machine, and it was not found."));
+        console.error("Git is used to fetch the files once; nothing about your project\n" +
+            "afterwards depends on it.");
+        return 1;
+    }
+    const destination = parsed.positional[1] ?? null;
+    let plan;
+    try {
+        plan = await (0, import_command_js_1.fetchSnapshot)(url, destination, (line) => console.log(dim(line)));
+    }
+    catch (error) {
+        console.error(red("Could not fetch that repository."));
+        const detail = error instanceof Error ? error.message : String(error);
+        /*
+          git puts the useful sentence last and a stack of its own noise first.
+          A private repository with no credentials is by far the most common
+          failure, so it is named rather than left to be inferred.
+        */
+        console.error(detail.split("\n").filter(Boolean).slice(-3).join("\n"));
+        if (/authentication|denied|not found|could not read/i.test(detail)) {
+            console.error("\nIf it is private, sign in to it with git first — CodeRook uses\n" +
+                "the credentials git already has and never asks for a token.");
+        }
+        return 1;
+    }
+    const { files, bytes } = await (0, import_command_js_1.measure)(plan.folder);
+    if (!files) {
+        console.error(red("That repository has no files in it."));
+        if (plan.temporary)
+            await (0, promises_2.rm)(node_path_1.default.dirname(plan.folder), { recursive: true, force: true });
+        return 1;
+    }
+    console.log(`Fetched ${files} file${files === 1 ? "" : "s"}, ${(0, import_command_js_1.humanBytes)(bytes)}, ` +
+        `into ${plan.folder}`);
+    /*
+      Said before the upload rather than after it fails. The window is a share
+      of the plan allowance per week, so a large import is a thing somebody
+      should know about while they can still choose a smaller repository.
+    */
+    if (bytes > 1024 ** 3) {
+        console.log(dim("This is a large import. Uploads are limited to a share of your\n" +
+            "allowance each week, so a project this size may need more than one\n" +
+            "sitting; the save resumes rather than starting over."));
+    }
+    console.log(dim("History is not imported — this becomes the first version."));
+    /*
+      Hand the fetched folder to the ordinary save path. --allow-ignored is set
+      because git tracks files committed before the rule that excludes them,
+      and dropping those would make the import quietly lossy.
+    */
+    const submitFlags = new Map(parsed.flags);
+    submitFlags.set("allow-ignored", true);
+    /*
+      Name the project after the repository, not after wherever the files were
+      put. Without this an import into a temporary folder produces a project
+      called something like `tmp-4f21`, and the name is the thing somebody
+      types afterwards to fetch it.
+    */
+    if (!submitFlags.has("name"))
+        submitFlags.set("name", plan.name);
+    if (!submitFlags.has("m") && !submitFlags.has("message")) {
+        submitFlags.set("message", `Imported from ${url}`);
+    }
+    const code = await commandSubmit({
+        positional: [plan.folder],
+        flags: submitFlags,
+    });
+    if (code === 0 && plan.temporary) {
+        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.`));
+    }
+    return code;
+}
 async function commandSubmit(parsed) {
     const folder = folderFor(parsed);
     const message = flagText(parsed, "m", "message") ?? "";
@@ -340,8 +440,39 @@ async function commandSubmit(parsed) {
         await (0, api_js_2.whoami)()
             .then((account) => account.displayName || account.username || "")
             .catch(() => ""), hasFlag(parsed, "no-licence"));
-    const rules = await (0, worktree_js_1.readRules)(folder);
-    const files = await (0, worktree_js_1.changedFiles)(folder, rules, baseline);
+    /*
+      Import sends what it fetched, filtering nothing.
+  
+      The ignore rules exist to keep build output and local mess out of a
+      working folder, and applying them to a fresh clone gets the wrong answer
+      twice over: a clone holds exactly the files the source repository tracked
+      and nothing else, so there is no mess to exclude — while a repository
+      that tracks something its own `.gitignore` now names (which git does,
+      for anything committed before the rule) would have those files dropped.
+      Dropping them makes an import quietly lossy, which is worse than
+      refusing to import at all.
+    */
+    const importing = hasFlag(parsed, "allow-ignored");
+    const rules = importing
+        ? { shared: "", local: "" }
+        : await (0, worktree_js_1.readRules)(folder);
+    /*
+      Whether a file that is no longer here means "delete it".
+  
+      The default says no, and that is the right default: a missing path is
+      usually an unmounted drive, a folder moved while something was open, or a
+      scan that ran mid-copy — and the cost of guessing wrong is somebody's work
+      removed from the one place it was safe. So the saved copy is left alone
+      (docs/UPLOAD_POLICY.md).
+  
+      It also meant nothing on this side could ever remove a file. Publishing
+      from git can, because there the question does not arise: `git rm` is a
+      recorded act, so the deletion is known rather than inferred. That left the
+      remote helper as the only route to something the tool itself could not do,
+      which is the wrong way round — so this is that capability, asked for
+      plainly.
+    */
+    const files = await (0, worktree_js_1.changedFiles)(folder, rules, baseline, hasFlag(parsed, "sync") ? "synchronize" : "add-and-update");
     /*
       An upgraded folder with no materialisation record and something that
       differs from its recorded version is ambiguous in the one way that
@@ -364,8 +495,8 @@ async function commandSubmit(parsed) {
             console.error(`${files.length} file${files.length === 1 ? " differs" : "s differ"} here:`);
             for (const file of files.slice(0, 20))
                 console.error(`  ${file.path}`);
-            console.error(`\nIf that is your work, send it with ${accent("coderook submit --force")}.` +
-                `\nIf it is an old copy, take theirs with ${accent("coderook get --replace")}.`);
+            console.error(`\nIf that is your work, send it with ${accent("cbx submit --force")}.` +
+                `\nIf it is an old copy, take theirs with ${accent("cbx get --replace")}.`);
             return 1;
         }
     }
@@ -379,7 +510,7 @@ async function commandSubmit(parsed) {
         console.log(behindOn
             ? `Nothing to submit; your own work is all saved. ${behindOn} file` +
                 `${behindOn === 1 ? "" : "s"} here ${behindOn === 1 ? "is" : "are"} ` +
-                `behind the saved version — run ${accent("coderook get")}.`
+                `behind the saved version — run ${accent("cbx get")}.`
             : "Nothing to submit; this folder matches the saved version.");
         return 0;
     }
@@ -404,17 +535,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;
     }
@@ -449,7 +580,7 @@ Or pass ${accent("--allow-private")} if they genuinely belong in the project.`);
     const pasted = await (0, worktree_js_1.detectPastedCredentials)(folder, files.map((file) => file.path));
     const stillPasted = pasted.filter((finding) => !exposed.includes(finding.path));
     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}`);
@@ -464,11 +595,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;
         }
@@ -477,31 +608,47 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
     if (added) {
         console.log(`${accent("Added an MIT licence")}, so other people may use this.`);
         console.log(dim(`  Change it with `) +
-            accent("coderook licence <name>") +
+            accent("cbx licence <name>") +
             dim(`, or remove it with `) +
-            accent("coderook licence none") +
+            accent("cbx licence none") +
             dim("."));
         console.log("");
     }
     const line = progressLine();
     const uploader = new upload_js_1.Uploader(config_js_1.credentials);
-    const uploadRequest = {
+    /*
+      Built by the shared description, so this and the git remote helper cannot
+      drift. They already had: the helper listed deletions in `deletions` alone
+      and published versions that still held the deleted file.
+    */
+    const uploadRequest = (0, publish_js_1.uploadRequestFor)({
         localPath: folder,
-        include: files.map((file) => file.path),
-        deletions: files.filter((file) => file.deleted).map((file) => file.path),
+        changed: files.filter((file) => !file.deleted).map((file) => file.path),
+        deleted: files.filter((file) => file.deleted).map((file) => file.path),
         message,
-        projectName: link?.slug ?? node_path_1.default.basename(folder),
+        /*
+          A folder's name is the right default and the wrong answer for import,
+          where the folder is somewhere temporary and the project should carry
+          the name it had at the place it came from. An existing link always
+          wins: renaming somebody's project because they passed a flag would be
+          a surprise, and the flag exists for projects that do not exist yet.
+        */
+        projectName: link?.slug ?? flagText(parsed, "name") ?? node_path_1.default.basename(folder),
         repositoryId: link?.repositoryId ?? null,
         // Every current CLI publish states its ancestry. A brand-new project is
         // explicitly based on an empty Track; a linked folder names the immutable
         // Version it was last reconciled with.
         baseVersionId: link?.baseVersionId ?? null,
         track: flagText(parsed, "track") ?? (await (0, track_commands_js_1.trackFor)(folder)),
-        ...(link?.baseVersionId
-            ? { expectedHeadVersionId: link.baseVersionId }
-            : {}),
+        /*
+          Only import sets this. Git keeps tracking files committed before the
+          rule that excludes them, so a faithful import carries paths the
+          project's own ignore rules now refuse; without the override the server
+          would reject the publication and the import would be lossy.
+        */
+        ...(hasFlag(parsed, "allow-ignored") ? { allowIgnored: true } : {}),
         ...(link ? { known: link.local ?? link.manifest ?? {} } : {}),
-    };
+    });
     let result;
     try {
         const plan = await uploader.plan(uploadRequest, (progress) => {
@@ -532,23 +679,22 @@ Pass ${accent("--allow-secrets")} if these are not real keys.`);
     }
     catch (error) {
         done(line);
-        const code = error.code;
-        const text = error instanceof Error ? error.message : String(error);
         /*
-          A connection that fails part way through says nothing about whether
-          the work was done. It may well have been — the service records the
-          attempt, so running the same command again is answered with the
-          version it already made rather than a second one. Saying so is the
-          difference between a person retrying and a person wondering.
+          Classified by the shared description rather than by a private regular
+          expression, so a push and a submit disagree about nothing — including
+          what counts as "the connection failed" and what that means for whether
+          the work was saved.
         */
-        if (!code && /fetch failed|ECONNRESET|socket hang up|network|ETIMEDOUT/i.test(text)) {
-            console.error(red(`
+        const failure = (0, publish_js_1.classifyPublishFailure)(error);
+        const text = error instanceof Error ? error.message : String(error);
+        if (failure?.kind === "interrupted") {
+            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.`);
             return 1;
         }
-        if (code === "merge_required" || code === "track_moved") {
+        if (failure?.kind === "conflict") {
             /*
               Somebody else saved to this project first. Everything that did not
               overlap has already been combined by the service; what is left is a
@@ -556,7 +702,7 @@ The connection failed: ${text}`));
               at it rather than to try again harder.
             */
             console.error(red(error instanceof Error ? error.message : String(error)));
-            console.error(`\nRun ${accent("coderook get")} to bring the latest version down, then` +
+            console.error(`\nRun ${accent("cbx get")} to bring the latest version down, then` +
                 ` submit again. Nothing was changed on your account.`);
             return 1;
         }
@@ -576,8 +722,8 @@ The connection failed: ${text}`));
         for (const conflict of result.mergeTrack.conflicts.slice(0, 20)) {
             console.log(`  ${red(conflict.path)}  ${dim(conflict.kind)}`);
         }
-        console.log(`\nRun ${accent(`coderook merge ${result.mergeTrack.reference}`)} to decide,` +
-            ` or ${accent("coderook merges")} to see everything waiting.`);
+        console.log(`\nRun ${accent(`cbx merge ${result.mergeTrack.reference}`)} to decide,` +
+            ` or ${accent("cbx merges")} to see everything waiting.`);
         return 0;
     }
     /*
@@ -586,9 +732,29 @@ The connection failed: ${text}`));
       attempt name exists to make survivable.
     */
     (0, faults_js_1.maybeFail)("submit:after-commit");
+    /*
+      What the project is actually called, not what this folder is called.
+  
+      A first publish recorded the folder's own name, which is right only when
+      nothing renamed the project — and two things routinely do: `--name`, and
+      the service turning a display name into a slug. When they differ, every
+      command that finds the project through this folder looks up a name that
+      does not exist: `tracks`, `versions`, `issues`, `releases`, `people`,
+      `watch`, `delete` and the rest all answered "No project matching …" in a
+      folder that had just published to it successfully.
+  
+      Asked of the service rather than guessed, and only on a first publish,
+      because that is the only time this is not already known.
+    */
+    let recordedSlug = link?.slug;
+    if (!recordedSlug) {
+        recordedSlug = await (0, api_js_2.projects)()
+            .then((all) => all.find((candidate) => candidate.id === result.repositoryId)?.slug)
+            .catch(() => undefined);
+    }
     await (0, config_js_1.writeLink)(folder, {
         repositoryId: result.repositoryId,
-        slug: link?.slug ?? node_path_1.default.basename(folder),
+        slug: recordedSlug ?? uploadRequest.projectName ?? node_path_1.default.basename(folder),
         sequence: result.sequence,
         // What this folder is now working from, so the next submit can say so.
         versionId: result.versionId,
@@ -687,8 +853,8 @@ async function commandGet(parsed) {
             console.error(red("This folder was connected by an older version of CodeRook,"));
             console.error("which did not record what it had received, so changed files here");
             console.error("cannot be told apart from copies left behind by a merge.\n");
-            console.error(`Save them with ${accent("coderook submit")} if they are your work, or ` +
-                `take the\nsaved version exactly with ${accent("coderook get --replace")}.`);
+            console.error(`Save them with ${accent("cbx submit")} if they are your work, or ` +
+                `take the\nsaved version exactly with ${accent("cbx get --replace")}.`);
             return 1;
         }
     }
@@ -724,9 +890,9 @@ 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(`
-Save them with ${accent("coderook submit")}, or finish the fetch and ` +
-                    `discard them with ${accent("coderook get --replace")}.`);
+                console.error(`
+Save them with ${accent("cbx submit")}, or finish the fetch and ` +
+                    `discard them with ${accent("cbx get --replace")}.`);
                 return 1;
             }
             /*
@@ -746,8 +912,8 @@ Save them with ${accent("coderook submit")}, or finish the fetch and ` +
                     console.error(`  ${file.path}`);
                 if (atRisk.length > 20)
                     console.error(dim(`  …and ${atRisk.length - 20} more`));
-                console.error(`\nSave them first with ${accent("coderook submit")}, or discard them ` +
-                    `with ${accent("coderook get --replace")}.`);
+                console.error(`\nSave them first with ${accent("cbx submit")}, or discard them ` +
+                    `with ${accent("cbx get --replace")}.`);
                 return 1;
             }
         }
@@ -762,7 +928,7 @@ Save them with ${accent("coderook submit")}, or finish the fetch and ` +
 async function commandClone(parsed) {
     const reference = parsed.positional[0];
     if (!reference) {
-        console.error(red("Which project? Try: coderook clone <project>"));
+        console.error(red("Which project? Try: cbx clone <project>"));
         return 1;
     }
     const project = await (0, api_js_2.findProject)(reference);
@@ -866,7 +1032,7 @@ async function suggestRules(folder, apply) {
     const recommended = suggestions.filter((one) => one.recommended);
     if (!apply) {
         console.log("");
-        console.log(dim("Add the + ones with ") + accent("coderook ignore --suggest --apply"));
+        console.log(dim("Add the + ones with ") + accent("cbx ignore --suggest --apply"));
         return 0;
     }
     if (!recommended.length) {
@@ -877,8 +1043,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,
     });
@@ -928,7 +1094,7 @@ async function commandBundle(parsed) {
 async function commandUnbundle(parsed) {
     const source = parsed.positional[0];
     if (!source) {
-        console.error(red("Which bundle? Try: coderook unbundle <file.cbx> [folder]"));
+        console.error(red("Which bundle? Try: cbx unbundle <file.cbx> [folder]"));
         return 1;
     }
     const manifest = await (0, cbx_js_1.readManifest)(node_path_1.default.resolve(source));
@@ -945,7 +1111,7 @@ async function commandUnbundle(parsed) {
 async function commandInspect(parsed) {
     const source = parsed.positional[0];
     if (!source) {
-        console.error(red("Which bundle? Try: coderook inspect <file.cbx>"));
+        console.error(red("Which bundle? Try: cbx inspect <file.cbx>"));
         return 1;
     }
     const manifest = await (0, cbx_js_1.readManifest)(node_path_1.default.resolve(source));
@@ -962,7 +1128,7 @@ async function commandInspect(parsed) {
 }
 async function commandDoctor() {
     const service = await (0, api_js_2.health)().catch(() => null);
-    console.log(`CodeRook CLI ${VERSION} · Node ${node_process_1.default.versions.node} · ${node_process_1.default.platform}`);
+    console.log(`cbx ${VERSION} · Node ${node_process_1.default.versions.node} · ${node_process_1.default.platform}`);
     console.log(`Config: ${(0, config_js_1.configDirectory)()}`);
     console.log(service
         ? `Service: ${service.status} · schema ${service.schemaVersion}` +
@@ -1005,8 +1171,8 @@ 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(`
-Run coderook merge <reference> to look at one.`));
+    console.log(dim(`
+Run cbx merge <reference> to look at one.`));
     return 0;
 }
 /** Find a merge by the reference a person would type, such as M-2. */
@@ -1029,7 +1195,7 @@ async function findMerge(folder, reference) {
 async function commandMerge(parsed) {
     const reference = parsed.positional[0];
     if (!reference) {
-        console.error(red("Which merge? Try: coderook merge M-1"));
+        console.error(red("Which merge? Try: cbx merge M-1"));
         return 1;
     }
     const folder = folderFor({ ...parsed, positional: parsed.positional.slice(1) });
@@ -1071,7 +1237,7 @@ async function commandMerge(parsed) {
         }
     }
     const now = await (0, api_js_1.mergeTrack)(summary.id);
-    console.log(`
+    console.log(`
 ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
         (now.provisional.ready
             ? "ready to apply"
@@ -1086,20 +1252,20 @@ ${accent(now.mergeTrack.reference)} · ${now.provisional.fileCount} files · ` +
             return 1;
         }
         const applied = await (0, api_js_1.applyMerge)(summary.id);
-        console.log(`
+        console.log(`
 Applied as ${accent(`v${applied.version.sequence}`)}.`);
-        console.log(dim("Run coderook get to bring it down to this folder."));
+        console.log(dim("Run cbx get to bring it down to this folder."));
         return 0;
     }
     if (!decision) {
-        console.log(dim(`
+        console.log(dim(`
 --mine keeps yours, --theirs keeps what was already saved,` +
-            ` --drop removes the file.
+            ` --drop removes the file.
 Add --path <file> for one file, then --apply when ready.`));
     }
     else if (now.provisional.ready) {
-        console.log(dim(`
-Run coderook merge ${now.mergeTrack.reference} --apply to publish it.`));
+        console.log(dim(`
+Run cbx merge ${now.mergeTrack.reference} --apply to publish it.`));
     }
     return 0;
 }
@@ -1119,7 +1285,7 @@ Run coderook merge ${now.mergeTrack.reference} --apply to publish it.`));
 async function commandRunner(parsed) {
     const reference = parsed.positional[0] ?? flagText(parsed, "project", "p");
     if (!reference) {
-        console.error(red("Which project? coderook runner <project>"));
+        console.error(red("Which project? cbx runner <project>"));
         return 1;
     }
     const project = await (0, api_js_2.findProject)(reference);
@@ -1265,7 +1431,7 @@ const SPECS = [
     },
     {
         name: "submit",
-        aliases: ["publish"],
+        aliases: ["publish", "push"],
         group: "Working with a folder",
         summary: "send the changes as a new version",
         usage: 'submit [folder] -m "…"',
@@ -1275,10 +1441,18 @@ const SPECS = [
         options: [
             { flags: "-m, --message <text>", description: "what changed, in a sentence" },
             { flags: "-n, --dry-run", description: "show what would be sent, send nothing" },
+            {
+                flags: "--name <name>",
+                description: "name a new project this, instead of after the folder",
+            },
             {
                 flags: "--allow-secrets",
                 description: "send files that look like credentials, and files with keys inside",
             },
+            {
+                flags: "--sync",
+                description: "treat a file that is no longer here as deleted, rather than keeping the saved copy",
+            },
             {
                 flags: "--track <name>",
                 description: "save onto this line, just this once",
@@ -1289,11 +1463,43 @@ const SPECS = [
             },
         ],
         examples: [
-            'coderook submit -m "Fix the export dialog"',
-            'coderook submit --track spike -m "Try the other encoder"',
+            'cbx submit -m "Fix the export dialog"',
+            'cbx submit --track spike -m "Try the other encoder"',
         ],
         run: commandSubmit,
     },
+    {
+        name: "import",
+        group: "Getting started",
+        summary: "bring a project in from another host",
+        usage: "import <address> [folder]",
+        detail: "Fetches a repository from GitHub, GitLab or anywhere else git can\n" +
+            "reach, and saves it as the first version of a CodeRook project.\n\n" +
+            "The files come across; the history does not. Every past commit would\n" +
+            "have to be published as its own version, which on a large project\n" +
+            "takes days — so this takes an honest snapshot rather than leaving a\n" +
+            "half-finished import behind. What arrives is the current state of the\n" +
+            "default branch.\n\n" +
+            "A public repository needs nothing. A private one uses the credentials\n" +
+            "git already has on this machine; CodeRook never asks for, stores or\n" +
+            "forwards a token.\n\n" +
+            "Files that the project's own ignore rules exclude are sent anyway,\n" +
+            "because git keeps tracking anything committed before the rule that\n" +
+            "excludes it, and leaving them out would lose files the source has.",
+        options: [
+            { flags: "-m, --message <text>", description: "the first version's message" },
+            { flags: "--track <name>", description: "save onto this line" },
+            {
+                flags: "--no-licence",
+                description: "do not add a licence to the new project",
+            },
+        ],
+        examples: [
+            "cbx import https://github.com/owner/project",
+            "cbx import git@github.com:owner/project.git ./project",
+        ],
+        run: commandImport,
+    },
     {
         /*
           Where the next save goes, which is a property of this folder rather
@@ -1301,14 +1507,14 @@ const SPECS = [
           different lines, which is most of the point of having them.
         */
         name: "track",
-        aliases: ["switch"],
+        aliases: ["switch", "checkout"],
         group: "Working with a folder",
         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" +
             "to it. Switching says where the next save goes and nothing else: no\n" +
             "files move and nothing is fetched, so it is instant and safe to change\n" +
-            "your mind. Run `coderook get` afterwards to bring that line's files\n" +
+            "your mind. Run `cbx get` afterwards to bring that line's files\n" +
             "into the folder.\n\n" +
             "A name that does not exist is refused rather than created, because a\n" +
             "typo in a branch name is an ordinary thing to do and a line called\n" +
@@ -1317,23 +1523,25 @@ const SPECS = [
         options: [
             { flags: "-n, --new", description: "start this line from where the project is now" },
         ],
-        examples: ["coderook track", "coderook track spike --new", "coderook track main"],
+        examples: ["cbx track", "cbx track spike --new", "cbx track main"],
         run: track_commands_js_1.commandTrack,
     },
     {
         name: "tracks",
+        aliases: ["branch", "branches"],
         group: "Your projects",
         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" +
             "Merges waiting on a decision are listed beside them rather than hidden,\n" +
             "because somebody looking for where they can save needs to see the one\n" +
-            "they cannot. Finish one with `coderook merge`.",
-        examples: ["coderook tracks", "coderook tracks my-project"],
+            "they cannot. Finish one with `cbx merge`.",
+        examples: ["cbx tracks", "cbx tracks my-project"],
         run: track_commands_js_1.commandTracks,
     },
     {
         name: "get",
+        aliases: ["pull"],
         group: "Working with a folder",
         summary: "bring this folder up to date",
         usage: "get [folder]",
@@ -1376,7 +1584,7 @@ const SPECS = [
                 description: "replace a licence that is already there",
             },
         ],
-        examples: ["coderook licence", "coderook licence MIT", "coderook licence Apache-2.0"],
+        examples: ["cbx licence", "cbx licence MIT", "cbx licence Apache-2.0"],
         run: licence_commands_js_1.commandLicence,
     },
     {
@@ -1423,6 +1631,7 @@ const SPECS = [
     },
     {
         name: "versions",
+        aliases: ["log"],
         group: "Your projects",
         summary: "what has been saved to a project",
         usage: "versions [project]",
@@ -1448,9 +1657,9 @@ const SPECS = [
             { 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",
+            "cbx ai my-project",
+            "cbx ai my-project --read off",
+            "cbx ai my-project --download off --request off",
         ],
         run: project_commands_js_1.commandAi,
     },
@@ -1463,16 +1672,43 @@ const SPECS = [
             { 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"'],
+        examples: ['cbx issues my-project --new "Crash on export"'],
         run: service_commands_js_1.commandIssues,
     },
     {
         name: "releases",
+        aliases: ["tags"],
         group: "Your projects",
         summary: "what has been released, and its files",
         usage: "releases [project]",
         run: service_commands_js_1.commandReleases,
     },
+    {
+        /*
+          A release is a version with a name on it, so this names one rather than
+          creating anything. Pushing a git tag does the same thing by the same
+          route — the tag is the name, the tagged commit picks the version.
+        */
+        name: "release",
+        aliases: ["tag"],
+        group: "Your projects",
+        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" +
+            "Nothing is uploaded: a release is a version with a name on it, so the\n" +
+            "version has to exist already.\n\n" +
+            "The same thing happens when a git tag is pushed to a CodeRook remote —\n" +
+            "`git push cbx v1.0` and `cbx release v1.0` are one action.",
+        options: [
+            { flags: "--version <n>", description: "name this version instead of the newest" },
+            { flags: "--notes <text>", description: "what changed, for the release page" },
+        ],
+        examples: [
+            "cbx release v1.0",
+            'cbx release v1.2 --version 41 --notes "Fixes the export dialog"',
+        ],
+        run: service_commands_js_1.commandRelease,
+    },
     {
         name: "actions",
         aliases: ["workflows"],
@@ -1480,7 +1716,7 @@ const SPECS = [
         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.",
+            "runs have passed. Use `cbx runner` to execute them on this machine.",
         run: service_commands_js_1.commandWorkflows,
     },
     {
@@ -1497,7 +1733,7 @@ const SPECS = [
                 description: "queued, running, passed, failed or cancelled",
             },
         ],
-        examples: ["coderook runs --status failed"],
+        examples: ["cbx runs --status failed"],
         run: service_commands_js_1.commandRuns,
     },
     {
@@ -1508,7 +1744,7 @@ const SPECS = [
         detail: "The output the runner sent up, in order. Anything the command wrote to\n" +
             "stderr is shown in red. Exits 1 when the run failed, so this can be\n" +
             "the last line of a script.",
-        examples: ["coderook logs 12", "coderook logs #12 my-project"],
+        examples: ["cbx logs 12", "cbx logs #12 my-project"],
         run: service_commands_js_1.commandLogs,
     },
     {
@@ -1532,7 +1768,7 @@ const SPECS = [
             { 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"],
+        examples: ["cbx people my-project --invite sam@example.com"],
         run: service_commands_js_1.commandCollaborators,
     },
     {
@@ -1617,7 +1853,7 @@ const SPECS = [
             { 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"],
+        examples: ["cbx runner my-game --labels windows,signing"],
         run: commandRunner,
     },
     {
@@ -1641,7 +1877,7 @@ const SPECS = [
             "repository for everybody who clones it.\n" +
             "\n" +
             "It teaches the command line rather than the MCP server, because that\n" +
-            "needs no configuration at all. `coderook mcp` is still there when a\n" +
+            "needs no configuration at all. `cbx mcp` is still there when a\n" +
             "structured connection is wanted.\n",
         options: [
             {
@@ -1649,7 +1885,7 @@ const SPECS = [
                 description: "install into this project rather than for you",
             },
         ],
-        examples: ["coderook skill", "coderook skill --project"],
+        examples: ["cbx skill", "cbx skill --project"],
         run: skill_command_js_1.commandSkill,
     },
     {
@@ -1668,11 +1904,11 @@ const SPECS = [
             "assistant at it and it starts and stops the process itself.\n" +
             "\n" +
             "Claude Code:\n" +
-            "  claude mcp add coderook -- coderook mcp\n" +
+            "  claude mcp add coderook -- cbx mcp\n" +
             "\n" +
             "Codex, in ~/.codex/config.toml:\n" +
             "  [mcp_servers.coderook]\n" +
-            "  command = 'coderook'\n" +
+            "  command = 'cbx'\n" +
             "  args = ['mcp']\n" +
             "\n" +
             "Everything it offers reads. It lists projects, versions and files, shows\n" +
@@ -1682,7 +1918,7 @@ const SPECS = [
             "\n" +
             "A project whose owner has turned off machine reading is refused, in\n" +
             "words rather than as a status code.\n",
-        examples: ["claude mcp add coderook -- coderook mcp"],
+        examples: ["claude mcp add coderook -- cbx mcp"],
         run: () => (0, mcp_js_1.commandMcp)(VERSION),
     },
     {
@@ -1705,7 +1941,7 @@ async function main(argv) {
         return 0;
     }
     /*
-      `coderook help submit` and `coderook submit --help` reach the same page.
+      `cbx help submit` and `cbx 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.
     */