@coderook/cli 0.24.0 → 0.25.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "coderook",
   "displayName": "CodeRook",
   "description": "Save, browse and restore whole-snapshot versions of a project on CodeRook, from Claude Code.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "author": {
     "name": "ACCA Gaming Productions",
     "url": "https://coderook.com"

package/README.md

@@ -126,6 +126,42 @@ and the desktop application all read one file. A `!` line puts something back.
 Personal exclusions that should not reach a collaborator belong in
 `.git/info/exclude`.
 
+## Moving a repository here
+
+`cbx import` takes a snapshot — the files as they are now, one version, no
+history. To move off a host entirely, with the history intact:
+
+```
+cbx transfer https://github.com/owner/project
+```
+
+GitHub, GitLab, Codeberg and any self-hosted Gitea or Forgejo. Every commit
+becomes a version and every branch a line, so it takes a while on a long
+history — the commit count and an estimate are printed before it starts.
+
+**It goes through the public route on purpose.** The history is published by
+running `git push` against the CodeRook remote, exactly as you would by hand.
+A transfer that used a private path would prove only that a private path
+exists.
+
+| | |
+| --- | --- |
+| Comes across | commits, every branch, tags as releases, the description |
+| With `--issues` and a read token | the open issues |
+| Does not come across | pull requests and reviews, CI configuration, collaborators, stars |
+
+The project is created **private** whatever the source was — publishing
+somebody's code as a side effect of moving it is not recoverable. Pass
+`--visibility same` to mirror the source, or `--public`.
+
+A private repository needs a read token in the environment — `GITHUB_TOKEN`,
+`GITLAB_TOKEN` or `FORGE_TOKEN`. It is never taken as a flag, never stored,
+and there is no OAuth flow: holding your forge credentials to run a one-off
+migration sits badly beside a promise that your work is not handed to anybody.
+
+The report at the end lists what arrived and what did not, rather than leaving
+the absence to be discovered later.
+
 ## Using git instead
 
 Installing the CLI also installs `git-remote-coderook`, so git talks to

package/dist/cli/src/api.js

@@ -11,6 +11,7 @@ exports.applyMerge = applyMerge;
 exports.cancelMerge = cancelMerge;
 exports.aiAccess = aiAccess;
 exports.setAiAccess = setAiAccess;
+exports.updateProject = updateProject;
 exports.versions = versions;
 exports.markRelease = markRelease;
 exports.issues = issues;
@@ -68,6 +69,7 @@ async function projects() {
         slug: String(row.slug ?? ""),
         name: String(row.displayName || row.slug || "Untitled"),
         visibility: String(row.visibility ?? "private"),
+        defaultBranch: String(row.defaultBranch || "main"),
         versionCount: Number(row.versionCount ?? 0),
         fileCount: Number(row.fileCount ?? 0),
         storedBytes: Number(row.storedSize ?? 0),
@@ -149,6 +151,18 @@ async function setAiAccess(repositoryId, change) {
         body: change,
     });
 }
+/**
+ * Change what a project says about itself.
+ *
+ * The same PATCH the AI switches use, which is where these live: a handful of
+ * columns on the repository rather than a resource of their own.
+ */
+async function updateProject(repositoryId, change) {
+    await call(`/v1/repositories/${encodeURIComponent(repositoryId)}`, {
+        method: "PATCH",
+        body: change,
+    });
+}
 /** Every saved version of a project, newest first. */
 async function versions(repositoryId) {
     const body = await call(`/v1/repositories/${encodeURIComponent(repositoryId)}/versions`);

package/dist/cli/src/cli.js

@@ -27,6 +27,8 @@ 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 tracks_js_1 = require("../../desktop-app/src/main/tracks.js");
+const transfer_command_js_1 = require("./transfer_command.js");
 const mcp_js_1 = require("./mcp.js");
 const skill_command_js_1 = require("./skill_command.js");
 const licence_commands_js_1 = require("./licence_commands.js");
@@ -884,7 +886,7 @@ async function commandGet(parsed) {
                     incoming.has(file.path) &&
                     edited.some((one) => one.path === file.path));
                 if (!changedInTheGap.length) {
-                    return fetchInto(link.repositoryId, folder, link.slug, link.local ?? null, "replace");
+                    return fetchInto(link.repositoryId, folder, link.slug, link.local ?? null, "replace", await (0, track_commands_js_1.trackFor)(folder));
                 }
                 console.error(red(`${changedInTheGap.length} file${changedInTheGap.length === 1 ? "" : "s"} ` +
                     `changed while the interrupted fetch was stopped:`));
@@ -923,7 +925,9 @@ Save them with ${accent("cbx submit")}, or finish the fetch and ` +
       what the version actually changed is written over — unless somebody asks
       for an exact copy, which is how a damaged folder is repaired.
     */
-    return fetchInto(link.repositoryId, folder, link.slug, link.local ?? null, replacing ? "replace" : "reconcile");
+    return fetchInto(link.repositoryId, folder, link.slug, link.local ?? null, replacing ? "replace" : "reconcile", 
+    // The line this folder saves to, so catching up brings that line down.
+    await (0, track_commands_js_1.trackFor)(folder));
 }
 async function commandClone(parsed) {
     const reference = parsed.positional[0];
@@ -941,7 +945,34 @@ async function commandClone(parsed) {
         return 1;
     }
     const destination = node_path_1.default.resolve(parsed.positional[1] ?? project.slug);
-    return fetchInto(project.id, destination, project.slug);
+    /*
+      A clone opens on the project's default line, or on the one named.
+  
+      It used to take whichever version was newest across every line, which is
+      only the same thing while a project has one. As soon as somebody pushed to
+      a branch, that branch held the newest version — so cloning the project
+      handed you their unfinished work under the impression it was the project.
+      Nothing said so: the fetch reported a version number and the files looked
+      like a project, just not the one anybody asked for.
+  
+      Naming a line here also removes the clone-switch-fetch dance that was the
+      only way to get a branch before, which is what exposed the same fault in
+      `get`.
+    */
+    const wanted = flagText(parsed, "track") ?? project.defaultBranch;
+    /*
+      Falling back rather than failing when the default line does not exist.
+      `defaultBranch` is a property of the project and a line can be renamed out
+      from under it; refusing to clone at all in that case would be a worse
+      answer than the old behaviour. An explicitly named line is still refused,
+      because there the person said which one they meant.
+    */
+    const lines = await new tracks_js_1.Tracks(config_js_1.credentials).list(project.id);
+    const usable = lines.some((line) => line.kind === "line" && line.name === wanted && line.headVersionId);
+    if (!usable && !flagText(parsed, "track")) {
+        console.log(dim(`This project has no line called ${wanted}; taking its newest version.`));
+    }
+    return fetchInto(project.id, destination, project.slug, null, "replace", usable || flagText(parsed, "track") ? wanted : undefined);
 }
 async function fetchInto(repositoryId, destination, slug, 
 /*
@@ -950,9 +981,45 @@ async function fetchInto(repositoryId, destination, slug,
   is removed, because "missing from the version" cannot then be told from
   "never came from the version at all".
 */
-held, mode = "replace") {
+held, mode = "replace", 
+/*
+  The line to fetch. Omitted means the project's newest version, which is
+  right for a clone and wrong for a folder that has chosen a line.
+*/
+trackName) {
     const downloader = new download_js_1.Downloader(config_js_1.credentials);
-    const latest = (await downloader.versions(repositoryId))[0];
+    const all = await downloader.versions(repositoryId);
+    /*
+      The head of this folder's line, not the newest version in the project.
+  
+      Those are the same thing only while a project has one line. With two, the
+      newest version usually belongs to the *other* one — so switching to a line
+      and fetching brought down the line you had just left, reported success,
+      and left the folder holding the wrong contents while still claiming to
+      save to the line you asked for. The next publish would then be computed
+      against a baseline from somewhere else.
+  
+      Worse than a wrong answer: `track` ends by telling you to run `get`, so
+      the command that set this up was the one recommending it.
+    */
+    let latest = all[0];
+    if (trackName) {
+        const chosen = (await new tracks_js_1.Tracks(config_js_1.credentials).list(repositoryId)).find((candidate) => candidate.name === trackName && candidate.kind === "line");
+        if (!chosen) {
+            console.error(red(`This project has no line called ${trackName}.`));
+            return 1;
+        }
+        if (!chosen.headVersionId) {
+            console.error(red(`The line ${trackName} has nothing saved to it yet.`));
+            return 1;
+        }
+        const head = all.find((version) => version.id === chosen.headVersionId);
+        if (!head) {
+            console.error(red(`Could not read the current version of ${trackName}.`));
+            return 1;
+        }
+        latest = head;
+    }
     if (!latest) {
         console.error(red("That project has no saved version."));
         return 1;
@@ -991,6 +1058,16 @@ held, mode = "replace") {
         // version holds and the two agree again.
         local: result.manifest,
         manifest: result.manifest,
+        /*
+          The line this folder is on survives being caught up.
+    
+          This record is built fresh rather than merged, so anything not named
+          here is dropped — and `track` was not named. Fetching therefore moved
+          the folder back to `main` every time, silently: the files were right,
+          the folder reported the wrong line, and the next publish went somewhere
+          nobody chose.
+        */
+        ...(trackName ? { track: trackName } : {}),
         // Reached the end, so there is no longer a fetch in flight.
     });
     // The record is written; the run has not reported success yet.
@@ -1500,6 +1577,43 @@ const SPECS = [
         ],
         run: commandImport,
     },
+    {
+        /*
+          Distinct from `import`, which takes a snapshot. This moves the history,
+          the branches, the tags and what the project says about itself — the
+          things somebody leaving a host is actually worried about losing.
+        */
+        name: "transfer",
+        aliases: ["migrate"],
+        group: "Getting started",
+        summary: "move a whole repository here from GitHub, GitLab or Codeberg",
+        usage: "transfer <address>",
+        detail: "Brings the commits, every branch, the tags and the description across.\n" +
+            "Each commit becomes a version and each branch a line, so a long history\n" +
+            "takes a while; the count and an estimate are printed before it starts.\n\n" +
+            "The history is published by running `git push` against the CodeRook\n" +
+            "remote — the same route anybody else uses, deliberately, because the\n" +
+            "claim being made is that git repositories work here.\n\n" +
+            "A private repository needs a read token in the environment:\n" +
+            "GITHUB_TOKEN, GITLAB_TOKEN or FORGE_TOKEN. It is never asked for on the\n" +
+            "command line and never stored.\n\n" +
+            "The project is created private whatever the source was, unless you say\n" +
+            "otherwise. Pull requests, CI configuration and collaborators do not come\n" +
+            "across; the report at the end lists what did and what did not.",
+        options: [
+            { flags: "--name <name>", description: "call the project this, rather than the repository's name" },
+            {
+                flags: "--visibility <how>",
+                description: "private (default), same as the source, or public",
+            },
+            { flags: "--issues", description: "also bring the open issues; needs a read token" },
+        ],
+        examples: [
+            "cbx transfer https://github.com/owner/project",
+            "cbx transfer https://codeberg.org/owner/project --visibility same",
+        ],
+        run: transfer_command_js_1.commandTransfer,
+    },
     {
         /*
           Where the next save goes, which is a property of this folder rather
@@ -1555,6 +1669,13 @@ const SPECS = [
         group: "Working with a folder",
         summary: "fetch a project into a new folder",
         usage: "clone <project> [dir]",
+        options: [
+            {
+                flags: "--track <name>",
+                description: "fetch this line rather than the project's newest version",
+            },
+        ],
+        examples: ["cbx clone my-project", "cbx clone my-project --track spike"],
         run: commandClone,
     },
     {

package/dist/cli/src/forge_url.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Reading a repository address, and nothing else.
+ *
+ * Kept apart from the transfer itself so a test can exercise it directly:
+ * importing the command drags in the API client and the upload engine, and
+ * none of that is needed to decide that `gitlab.com/group/subgroup/project`
+ * belongs to `group/subgroup`. It is also the piece where a mistake is quiet —
+ * a URL parsed into the wrong owner still clones and still pushes, and only
+ * the project name afterwards says anything was wrong.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readForgeUrl = readForgeUrl;
+/**
+ * Work out which forge a URL points at.
+ *
+ * Gitea is the fallback rather than a failure: Codeberg, Forgejo and every
+ * self-hosted Gitea share one API shape, so an unknown host is far more likely
+ * to be one of those than to be nothing. Guessing wrong costs a failed
+ * metadata read, which is reported; refusing outright would cost the transfer.
+ */
+function readForgeUrl(input) {
+    let raw = input.trim();
+    // `git@host:owner/repo.git` is not a URL; make it one.
+    const ssh = raw.match(/^git@([^:]+):(.+)$/);
+    if (ssh)
+        raw = `https://${ssh[1]}/${ssh[2]}`;
+    if (!/^[a-z]+:\/\//i.test(raw))
+        raw = `https://${raw}`;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`That does not look like a repository address: ${input}`);
+    }
+    const parts = parsed.pathname.replace(/\.git$/i, "").split("/").filter(Boolean);
+    if (parts.length < 2) {
+        throw new Error(`That address names no repository: ${input}\n` +
+            `  Expected something like https://github.com/owner/project`);
+    }
+    /*
+      GitLab allows groups within groups, so the project is the last segment and
+      the owner is everything before it. Taking parts[0] would address the top
+      group and miss the project entirely.
+    */
+    const repo = parts[parts.length - 1];
+    const owner = parts.slice(0, -1).join("/");
+    const host = parsed.host;
+    const kind = /(^|\.)github\.com$/i.test(host)
+        ? "github"
+        : /(^|\.)gitlab\.com$/i.test(host)
+            ? "gitlab"
+            : "gitea";
+    return {
+        kind,
+        label: kind === "github" ? "GitHub" : kind === "gitlab" ? "GitLab" : `Gitea (${host})`,
+        host,
+        owner,
+        repo,
+        clone: `https://${host}/${owner}/${repo}.git`,
+        tokenNames: kind === "github"
+            ? ["GITHUB_TOKEN", "GH_TOKEN"]
+            : kind === "gitlab"
+                ? ["GITLAB_TOKEN"]
+                : ["FORGE_TOKEN", "GITEA_TOKEN"],
+    };
+}

package/dist/cli/src/git_remote.js

@@ -253,6 +253,54 @@ async function applyCommit(catFile, scratch, fromCommit, toCommit) {
     }
     return { written, deleted, skipped };
 }
+/*
+  The service's answer when a line is already there.
+
+  Matched on the wording as well as the shape because the message is the only
+  thing that reaches here: `This project already has a track called main`. The
+  previous test looked for "exist", which that sentence does not contain — so a
+  branch arriving after the project had been created was reported as a hard
+  failure rather than the ordinary "it is already there".
+*/
+const TRACK_EXISTS = /already has a track|track_exists|exists/i;
+/**
+ * The order refs are published in, which is not the order git sends them.
+ *
+ * `git push --all` hands over every branch at once, and on a project that does
+ * not exist yet the first one creates it — along with an empty `main`. If a
+ * side branch happens to go first it takes the whole history, and `main`
+ * arrives to find its own line already made and nothing it can do with it:
+ * there is no way to move an existing line's head, only to start one at a
+ * version. The result was a project whose default line was permanently empty.
+ *
+ * Publishing the branch the others fork from first makes every later branch an
+ * ordinary fork, which is the case that already worked. Local HEAD wins,
+ * because that is what the person is standing on; `main` and `master` are the
+ * conventional fallbacks; everything else keeps a stable order so two runs of
+ * the same push behave the same way.
+ */
+function ordered(requests) {
+    let head = "";
+    try {
+        head = git(["symbolic-ref", "--short", "HEAD"]).trim();
+    }
+    catch {
+        // A detached HEAD has no branch to prefer; the fallbacks still apply.
+    }
+    const rank = (request) => {
+        const branch = (0, git_history_js_1.branchOf)(request.dst);
+        if (!branch)
+            return 4; // tags last: they name versions that must exist
+        if (branch === head)
+            return 0;
+        if (branch === "main")
+            return 1;
+        if (branch === "master")
+            return 2;
+        return 3;
+    };
+    return [...requests].sort((left, right) => rank(left) - rank(right) || left.dst.localeCompare(right.dst));
+}
 /**
  * The refs the remote already holds, as far as we can tell.
  *
@@ -612,18 +660,44 @@ async function doImport(refs, url) {
 }
 async function doPush(requests, url) {
     const { slug } = (0, git_history_js_1.parseRemoteUrl)(url);
-    const project = await (0, api_js_1.findProject)(slug);
-    const repositoryId = project?.id ?? null;
-    const state = repositoryId ? await remoteState(repositoryId) : null;
     const marks = await readMarks();
-    const known = new Map();
-    for (const track of state?.tracks ?? []) {
-        if (track.kind !== "line" || !track.headVersionId)
-            continue;
-        const sha = headCommit(track.headVersionId, state, marks);
-        if (sha)
-            known.set(`refs/heads/${track.name}`, sha);
-    }
+    /*
+      Re-read the project before every ref, not once before the batch.
+  
+      `git push --all` sends every branch in one batch, and the first of them
+      routinely creates the project. Reading the state once meant every later
+      ref in that same push still believed the project did not exist: it
+      published against a null repository, started its history from nothing, and
+      left its line without a head. Pushing two branches to a new project
+      produced one working line and one empty one, and reported success for
+      both — which is the shape a whole-repository transfer takes, so it failed
+      exactly where it mattered most.
+  
+      One extra listing per ref. A push carries a handful of refs and each one
+      publishes versions costing seconds, so the cost is not worth the class of
+      bug avoiding it creates.
+    */
+    let repositoryId = (await (0, api_js_1.findProject)(slug))?.id ?? null;
+    let state = repositoryId
+        ? await remoteState(repositoryId)
+        : null;
+    const refreshProject = async () => {
+        if (!repositoryId)
+            repositoryId = (await (0, api_js_1.findProject)(slug))?.id ?? null;
+        state = repositoryId ? await remoteState(repositoryId) : null;
+    };
+    const knownRefs = () => {
+        const found = new Map();
+        for (const track of state?.tracks ?? []) {
+            if (track.kind !== "line" || !track.headVersionId)
+                continue;
+            const sha = headCommit(track.headVersionId, state, marks);
+            if (sha)
+                found.set(`refs/heads/${track.name}`, sha);
+        }
+        return found;
+    };
+    let known = knownRefs();
     let nextPushMark = 1;
     for (const mark of marks?.sha.keys() ?? []) {
         nextPushMark = Math.max(nextPushMark, mark + 1);
@@ -633,7 +707,13 @@ async function doPush(requests, url) {
     const scratch = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "coderook-push-"));
     let warnedAboutMerges = false;
     try {
-        for (const request of requests) {
+        for (const request of ordered(requests)) {
+            /*
+              Whatever the previous ref did, this one starts from what the project
+              actually holds now — including a project the previous ref created.
+            */
+            await refreshProject();
+            known = knownRefs();
             /*
               A tag names a version, which is exactly what a CodeRook release is:
               "a Version with a name on it, not a different kind of object". So a tag
@@ -808,7 +888,7 @@ async function doPush(requests, url) {
                     }
                     catch (error) {
                         const text = error instanceof Error ? error.message : String(error);
-                        if (!/exist/i.test(text)) {
+                        if (!TRACK_EXISTS.test(text)) {
                             send(`error ${request.dst} ${text}`);
                             continue;
                         }
@@ -871,7 +951,7 @@ async function doPush(requests, url) {
                     }
                     catch (error) {
                         const text = error instanceof Error ? error.message : String(error);
-                        if (!/exist/i.test(text))
+                        if (!TRACK_EXISTS.test(text))
                             throw error;
                     }
                 }
@@ -1052,7 +1132,26 @@ async function main(argv) {
                     const sha = mark === undefined ? undefined : marks?.sha.get(mark);
                     send(`${sha ?? "?"} refs/heads/${track.name}`);
                 }
-                const head = lines.find((track) => track.name === "main") ?? lines[0];
+                /*
+                  Which line a clone opens on.
+        
+                  The project's own default first, then the conventional names, then
+                  whatever has content. Looking only for `main` was wrong for a
+                  transferred repository: creating a project always makes an empty
+                  `main`, so a repository whose default is `master` ends up with a
+                  `main` that holds nothing — and `main` is filtered out of `lines`
+                  for exactly that reason, leaving HEAD to fall on whichever branch
+                  happened to sort first. It landed on `master` by luck rather than
+                  because anything chose it.
+                */
+                const preferred = [
+                    project?.defaultBranch,
+                    "main",
+                    "master",
+                ].filter((name) => Boolean(name));
+                const head = preferred
+                    .map((name) => lines.find((track) => track.name === name))
+                    .find(Boolean) ?? lines[0];
                 if (head)
                     send(`@refs/heads/${head.name} HEAD`);
             }

package/dist/cli/src/transfer_command.js

@@ -0,0 +1,331 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandTransfer = commandTransfer;
+/**
+ * Moving a whole repository off a git host and onto CodeRook.
+ *
+ * `cbx import` takes a snapshot: the files as they are now, one version, no
+ * history. That is the right answer for "get this onto CodeRook quickly" and
+ * the wrong one for "move off GitHub", where the history, the branches, the
+ * tags and the issues are most of what somebody is worried about losing.
+ *
+ * ## It uses the public route on purpose
+ *
+ * The history goes across by running `git push` against the CodeRook remote —
+ * the same command anybody else would type, through the same helper. Nothing
+ * here reaches past it into a private path.
+ *
+ * That is deliberate, because the claim being made is interoperability. A
+ * transfer that worked through a back door would prove only that a back door
+ * exists. This one works because `git push coderook --all` works; if that ever
+ * breaks, this breaks with it, loudly, rather than quietly diverging from what
+ * users are told to do.
+ *
+ * ## What crosses, and what cannot
+ *
+ * Commits, branches, tags and the project's own description come across.
+ * Issues come across when a read token is supplied. Pull requests, reviews,
+ * CI configuration, stars and collaborator lists do not — some because
+ * CodeRook has no such object, and one because it would be wrong: adding
+ * somebody to a project is an invitation they have to accept, not a field to
+ * copy. The report at the end says which is which rather than leaving the
+ * absence to be discovered.
+ *
+ * ## Tokens
+ *
+ * Read from the environment, never from a flag and never stored. A read-only
+ * token is enough, and no OAuth flow is offered: holding somebody's forge
+ * credentials to run a one-off migration sits badly beside a front page that
+ * promises their work is not handed to anybody.
+ */
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_process_1 = __importDefault(require("node:process"));
+const api_js_1 = require("./api.js");
+const forge_url_js_1 = require("./forge_url.js");
+const dim = (value) => `${value}`;
+const bold = (value) => `${value}`;
+const red = (value) => `${value}`;
+const green = (value) => `${value}`;
+const accent = (value) => `${value}`;
+/** A read token from the environment, or nothing. Never a flag. */
+function forgeToken(forge) {
+    for (const name of forge.tokenNames) {
+        const value = node_process_1.default.env[name]?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+async function readJson(url, token, forge) {
+    const headers = {
+        accept: "application/json",
+        "user-agent": "cbx-transfer",
+    };
+    if (token) {
+        headers.authorization =
+            forge.kind === "gitlab" ? `Bearer ${token}` : `token ${token}`;
+    }
+    const response = await fetch(url, { headers });
+    if (!response.ok) {
+        throw new Error(`${response.status} from ${new URL(url).pathname}`);
+    }
+    return response.json();
+}
+/** What the forge says about the repository itself. */
+async function describeSource(forge, token) {
+    const encoded = encodeURIComponent(`${forge.owner}/${forge.repo}`);
+    const url = forge.kind === "github"
+        ? `https://api.${forge.host}/repos/${forge.owner}/${forge.repo}`
+        : forge.kind === "gitlab"
+            ? `https://${forge.host}/api/v4/projects/${encoded}`
+            : `https://${forge.host}/api/v1/repos/${forge.owner}/${forge.repo}`;
+    try {
+        const body = (await readJson(url, token, forge));
+        const isPrivate = body.private === true || body.visibility === "private" || body.internal === true;
+        return {
+            description: String(body.description ?? "").slice(0, 1000),
+            visibility: isPrivate ? "private" : "public",
+            defaultBranch: body.default_branch ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Open issues on the source, oldest first so numbering reads sensibly. */
+async function readIssues(forge, token) {
+    const encoded = encodeURIComponent(`${forge.owner}/${forge.repo}`);
+    const url = forge.kind === "github"
+        ? `https://api.${forge.host}/repos/${forge.owner}/${forge.repo}/issues?state=open&per_page=100`
+        : forge.kind === "gitlab"
+            ? `https://${forge.host}/api/v4/projects/${encoded}/issues?state=opened&per_page=100`
+            : `https://${forge.host}/api/v1/repos/${forge.owner}/${forge.repo}/issues?state=open&limit=100`;
+    const body = (await readJson(url, token, forge));
+    return body
+        /*
+          GitHub returns pull requests through the issues endpoint. They are not
+          issues, and CodeRook has nothing that a pull request becomes, so copying
+          them across as issues would be inventing content rather than moving it.
+        */
+        .filter((one) => !one.pull_request)
+        .map((one) => ({
+        title: String(one.title ?? "").slice(0, 200),
+        body: String(one.body ?? one.description ?? "").slice(0, 20_000),
+        number: Number(one.number ?? one.iid ?? 0),
+        closed: false,
+    }))
+        .filter((one) => one.title)
+        .reverse();
+}
+function run(command, args, cwd) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024 * 64,
+    });
+    return {
+        ok: result.status === 0,
+        out: `${result.stdout ?? ""}${result.stderr ?? ""}`,
+    };
+}
+async function commandTransfer(parsed) {
+    const address = parsed.positional[0];
+    if (!address) {
+        console.error(red("Which repository? Try: cbx transfer https://github.com/owner/project"));
+        return 1;
+    }
+    let forge;
+    try {
+        forge = (0, forge_url_js_1.readForgeUrl)(address);
+    }
+    catch (error) {
+        console.error(red(error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    if (!run("git", ["--version"]).ok) {
+        console.error(red("Transferring needs git on this machine."));
+        return 1;
+    }
+    /*
+      The push goes through the remote helper, which git finds on PATH by name.
+      Checking now turns a confusing failure halfway through a clone into one
+      sentence before anything is downloaded.
+    */
+    if (!run("git", ["remote-coderook", "--probe"]).ok) {
+        const help = run("git", ["help", "-a"]);
+        if (!/remote-coderook/.test(help.out)) {
+            console.error(red("git cannot find `git-remote-coderook` on this machine."));
+            console.error("It ships with this tool, so this usually means cbx was run from a\n" +
+                "checkout rather than installed. Install it globally and try again:\n" +
+                `  ${accent("npm install --global @coderook/cli")}`);
+            return 1;
+        }
+    }
+    const wanted = (typeof parsed.flags.get("name") === "string"
+        ? String(parsed.flags.get("name"))
+        : forge.repo).toLowerCase();
+    const existing = await (0, api_js_1.findProject)(wanted);
+    if (existing) {
+        console.error(red(`You already have a project called ${existing.slug}.`));
+        console.error(`Transfer creates a project; it does not merge into one. Choose another\n` +
+            `name with ${accent("--name")}, or delete that project first.`);
+        return 1;
+    }
+    const token = forgeToken(forge);
+    console.log(`${bold("Transferring")} ${forge.owner}/${forge.repo} ${dim(`from ${forge.label}`)}`);
+    console.log(dim(token
+        ? `  Using the read token in ${forge.tokenNames.find((name) => node_process_1.default.env[name]?.trim())}.`
+        : `  No token set. Public repositories work; set ${forge.tokenNames[0]} for a private one or for issues.`));
+    const scratch = await (0, promises_1.mkdtemp)(node_path_1.default.join(node_os_1.default.tmpdir(), "cbx-transfer-"));
+    const checkout = node_path_1.default.join(scratch, forge.repo);
+    const report = [];
+    try {
+        /*
+          A full clone, not the shallow one `import` uses. The whole point here is
+          the history, and `--depth 1` would silently deliver a single commit under
+          a command whose name promises everything.
+        */
+        console.log(`\n${dim("Fetching the repository with its full history…")}`);
+        const cloned = run("git", ["clone", "--no-single-branch", forge.clone, checkout]);
+        if (!cloned.ok) {
+            console.error(red(`\nCould not clone ${forge.clone}`));
+            console.error(cloned.out.trim().split("\n").slice(-4).join("\n"));
+            if (!token) {
+                console.error(dim(`\nIf it is private, set ${forge.tokenNames[0]} and try again.`));
+            }
+            return 1;
+        }
+        /*
+          Every branch, not only the one checked out. A fresh clone has remote
+          tracking refs for the rest, and nothing local pointing at them, so
+          `--all` would push exactly one branch.
+        */
+        const remoteBranches = run("git", [
+            "for-each-ref", "--format=%(refname:short)", "refs/remotes/origin",
+        ], checkout).out
+            .split("\n").map((one) => one.trim()).filter(Boolean)
+            /*
+              The remote's HEAD symref comes back as plain `origin`, not
+              `origin/HEAD`, so filtering on the latter leaves a phantom entry that
+              inflates the branch count and sends git looking for `origin/origin`.
+            */
+            .filter((one) => one.startsWith("origin/"))
+            .map((one) => one.slice("origin/".length))
+            .filter((one) => one && one !== "HEAD");
+        for (const branch of remoteBranches) {
+            run("git", ["branch", "--force", branch, `origin/${branch}`], checkout);
+        }
+        const commits = Number(run("git", ["rev-list", "--all", "--count"], checkout).out.trim() || "0");
+        const tags = run("git", ["tag", "-l"], checkout).out.split("\n").filter(Boolean);
+        console.log(`  ${commits} commit${commits === 1 ? "" : "s"} · ` +
+            `${remoteBranches.length} branch${remoteBranches.length === 1 ? "" : "es"} · ` +
+            `${tags.length} tag${tags.length === 1 ? "" : "s"}`);
+        if (commits > 200) {
+            console.log(dim(`  Each commit becomes a version, so this will take a while —\n` +
+                `  roughly ${Math.round((commits * 11) / 60)} minutes. It resumes if interrupted.`));
+        }
+        run("git", ["remote", "add", "coderook", `coderook://${wanted}`], checkout);
+        console.log(`\n${dim("Publishing the history…")}`);
+        const pushed = run("git", ["push", "coderook", "--all"], checkout);
+        node_process_1.default.stderr.write(pushed.out);
+        if (!pushed.ok) {
+            console.error(red("\nThe history did not transfer completely."));
+            return 1;
+        }
+        report.push(`${commits} commits across ${remoteBranches.length} branch(es)`);
+        if (tags.length) {
+            const pushedTags = run("git", ["push", "coderook", "--tags"], checkout);
+            node_process_1.default.stderr.write(pushedTags.out);
+            report.push(pushedTags.ok
+                ? `${tags.length} tag(s) as releases`
+                : `tags were refused — see above`);
+        }
+        const project = await (0, api_js_1.findProject)(wanted);
+        if (!project) {
+            console.error(red("\nThe project was not created. Nothing else was changed."));
+            return 1;
+        }
+        // What the repository says about itself.
+        const facts = await describeSource(forge, token);
+        if (facts) {
+            const asked = parsed.flags.get("visibility");
+            /*
+              Private unless asked otherwise, even when the source is public.
+              Mirroring visibility is the faithful thing and publishing somebody's
+              code by side effect is the unrecoverable thing, so the safe reading
+              wins and the report says what was chosen.
+            */
+            const visibility = asked === "same"
+                ? facts.visibility
+                : asked === "public"
+                    ? "public"
+                    : "private";
+            await (0, api_js_1.updateProject)(project.id, {
+                ...(facts.description ? { description: facts.description } : {}),
+                visibility,
+            });
+            report.push(`description and visibility (${visibility}` +
+                `${visibility !== facts.visibility ? `, source was ${facts.visibility}` : ""})`);
+            /*
+              Said rather than left to be noticed. Creating a project always makes a
+              `main` line, so a repository whose default is anything else arrives
+              with an empty one beside its real branches — and `cbx tracks` marks it
+              as the current line, which reads as though the transfer lost the work.
+            */
+            if (facts.defaultBranch && facts.defaultBranch !== "main") {
+                report.push(`default line is ${facts.defaultBranch}; the empty "main" beside it ` +
+                    `was made when the project was created`);
+            }
+        }
+        else {
+            report.push("description could not be read from the source");
+        }
+        // Issues, only when asked and only with a token.
+        if (parsed.flags.has("issues")) {
+            if (!token) {
+                report.push(`issues skipped — set ${forge.tokenNames[0]} and run with --issues again`);
+            }
+            else {
+                try {
+                    const issues = await readIssues(forge, token);
+                    let made = 0;
+                    for (const issue of issues) {
+                        await (0, api_js_1.createIssue)(project.id, {
+                            title: issue.title,
+                            body: `${issue.body}\n\n` +
+                                `— transferred from ${forge.label} ${forge.owner}/${forge.repo}#${issue.number}`,
+                        });
+                        made += 1;
+                    }
+                    report.push(`${made} open issue(s)`);
+                }
+                catch (error) {
+                    report.push(`issues failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+        console.log(`\n${green("Transferred")} ${bold(project.slug)}`);
+        for (const line of report)
+            console.log(`  ${green("·")} ${line}`);
+        console.log(`\n${dim("Not carried across:")}`);
+        console.log(dim("  · pull requests and reviews — CodeRook has no equivalent object"));
+        console.log(dim("  · CI configuration — runs are started deliberately, not by a push"));
+        console.log(dim("  · collaborators — access is an invitation to accept, not a field to copy"));
+        console.log(dim("  · stars, forks and watchers"));
+        if (!parsed.flags.has("issues")) {
+            console.log(dim("  · issues — pass --issues to bring the open ones"));
+        }
+        console.log(`\nFetch it anywhere with ${accent(`cbx clone ${project.slug}`)}` +
+            `${dim(", or ")}${accent(`git clone coderook://${project.slug}`)}${dim(".")}`);
+        return 0;
+    }
+    finally {
+        await (0, promises_1.rm)(scratch, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderook/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "CodeRook from the command line, on any operating system",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderook.com",
@@ -36,7 +36,7 @@
     "test:matrix": "node test/state-matrix.mjs",
     "test:attempt": "node test/attempt-identity.mjs",
     "test:get": "node test/get-safety.mjs",
-    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/upgrade-migration.mjs --allow-production && node test/fault-get.mjs --allow-production && node test/version-floor.mjs --allow-production && node test/fault-submit.mjs --allow-production && node test/race-attempts.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
+    "test:live": "node test/e2e.mjs --allow-production && node test/state-matrix.mjs --allow-production && node test/get-safety.mjs --allow-production && node test/get-track.mjs --allow-production && node test/get-protects-edits.mjs --allow-production && node test/upgrade-migration.mjs --allow-production && node test/fault-get.mjs --allow-production && node test/version-floor.mjs --allow-production && node test/fault-submit.mjs --allow-production && node test/race-attempts.mjs --allow-production && node test/attempt-identity.mjs --allow-production",
     "test:getedits": "node test/get-protects-edits.mjs",
     "test:upgrade": "node test/upgrade-migration.mjs",
     "test:faultget": "node test/fault-get.mjs",
@@ -44,7 +44,8 @@
     "test:faultsubmit": "node test/fault-submit.mjs",
     "test:race": "node test/race-attempts.mjs",
     "test:runner": "node test/runner-live.mjs",
-    "sync:plugin": "node scripts/sync-plugin-version.mjs"
+    "sync:plugin": "node scripts/sync-plugin-version.mjs",
+    "test:track": "node test/get-track.mjs"
   },
   "devDependencies": {
     "@types/node": "24.10.1",