@retasc/cli 1.7.2 → 1.9.0

package/dist/commands/join.js

@@ -0,0 +1,200 @@
+import { api, formatError } from "../api.js";
+import { loadConfig } from "../config.js";
+import { parseInviteCode } from "../lib/invite.js";
+import { selfCommand } from "../lib/launcher.js";
+import { clean } from "../lib/text.js";
+import { VERSION } from "../version.js";
+import { ask, confirm, ensureSignedIn, isInteractive, pickExisting, rebindGuard, completeWorkspaceSetup, } from "./bind.js";
+/** A ghost whose origin predates `sourceLabel`. Never invent a tool we don't know. */
+const UNKNOWN_SOURCE = "another tool";
+/**
+ * A stop that cannot loop forever.
+ *
+ * The loop is driven by a server list that shrinks on every claim, so it terminates on its
+ * own — but it is a `while (true)` around a network call, and a backend that ever returned
+ * an unchanged list would spin a human's terminal rather than fail. Well above any real
+ * number of migrated tools.
+ */
+const MAX_IDENTITY_ROUNDS = 10;
+/** How one row reads: the person, and the tool they were carried in from. */
+function ghostRow(g) {
+    // BOTH fields are third-party text: the name was typed by someone in ClickUp/Jira/Asana
+    // and carried across verbatim, and `sourceLabel` is the adapter's own record of where.
+    // They print into a terminal that acts on escape sequences, right above a prompt.
+    return `${clean(g.name)}      from ${clean(g.sourceLabel ?? UNKNOWN_SOURCE)}`;
+}
+/**
+ * "Which of these imported people is you?" — the CLI half of RTSC-433/473.
+ *
+ * Mirrors the Dash notice (`dash/src/components/GhostClaim.tsx`) deliberately, down to the
+ * confirm wording in `dash/src/lib/ghostPrompt.ts`. Two surfaces asking the same
+ * irreversible question in two different voices is how someone ends up answering the one
+ * they trust less.
+ *
+ * Never fatal. Everything here is about attribution; the bind that follows is what makes
+ * the folder work, and a failure to offer a claim must not cost someone their workspace.
+ */
+export async function identityLoop(orgId, opts, orgLabel, 
+// Injected so the question itself can be pinned by tests. It is asked once per human per
+// org and it is irreversible, so "we ran it live and it looked right" is not evidence —
+// the live orgs available to us have all already answered, which exercises only the
+// silent path. What has to be provable is the loud one.
+deps = {}) {
+    const d = {
+        claimableGhosts: api.claimableGhosts,
+        claimGhost: api.claimGhost,
+        dismissGhostPrompt: api.dismissGhostPrompt,
+        askFn: ask,
+        confirmFn: confirm,
+        interactive: isInteractive,
+        ...deps,
+    };
+    // `--yes` may SKIP this question. It may never answer it: claiming pulls another human's
+    // authorship AND their dispatch lane onto your account, irreversibly, and there is no
+    // CLI path back. A scripted run has nobody to be wrong on behalf of.
+    if (!d.interactive() || opts.yes)
+        return;
+    for (let round = 0; round < MAX_IDENTITY_ROUNDS; round++) {
+        let ghosts;
+        try {
+            const res = await d.claimableGhosts({ orgId });
+            if (res.asked || !res.ghosts.length)
+                return;
+            ghosts = res.ghosts;
+        }
+        catch (e) {
+            const { message } = formatError(e);
+            console.error(`  ! Couldn't check for imported history (${message}). Carrying on.`);
+            return;
+        }
+        console.log(round === 0
+            ? `\nWhen ${orgLabel ?? "this org"} migrated, some people were carried across.\n` +
+                "One of them may be you:"
+            : "\nAnything else here you recognise?");
+        // "Don't ask again" is not decoration. Declining writes `ghostPromptDismissedAt` on the
+        // member row and `claimGhost` refuses for good afterwards, org-wide — so a bare "none
+        // of these are me" would read as "none of these ClickUp ones" and quietly close the
+        // door on a second tool's placeholder too.
+        // Compared by REFERENCE below, not by a magic id value: a sentinel that is merely a
+        // row with an empty id would let any future ghost with a falsy id read as a decline —
+        // and a decline is permanent.
+        const NONE = { id: "", name: "None of these are me (don't ask again)", sourceLabel: null };
+        // No label: the heading above is the prompt, and `choose` would print a second one.
+        const chosen = await pickExisting("", [...ghosts, NONE], (g) => (g === NONE ? g.name : ghostRow(g)), d.askFn);
+        if (chosen === NONE) {
+            try {
+                await d.dismissGhostPrompt({ orgId });
+            }
+            catch (e) {
+                console.error(`  ! ${formatError(e).message}`);
+            }
+            return;
+        }
+        // Confirm before claiming — it is irreversible and it moves dispatch routing, so it
+        // must not be a single keystroke on a row in a list. Same qualitative wording as the
+        // Dash: counting "12 issues, 4 comments" would mean an org-wide scan on exactly the
+        // orgs that just ingested a migration.
+        const from = clean(chosen.sourceLabel ?? UNKNOWN_SOURCE);
+        const question = `\n  Link "${clean(chosen.name)}" to your account? Everything they wrote, commented on,\n` +
+            `  or were assigned in ${from} becomes yours. This can't be undone.`;
+        if (!(await d.confirmFn(question))) {
+            // NOT a dismissal. They declined THIS row, which is not the same as "none of these
+            // are me" — and dismissing is permanent, so it only ever happens when said outright.
+            console.log("  Left unlinked.");
+            continue;
+        }
+        try {
+            const res = await d.claimGhost({ orgId, memberId: chosen.id });
+            console.log(`✓ Linked ${clean(res.name)}.`);
+        }
+        catch (e) {
+            // SOURCE_ALREADY_CLAIMED, IMPORT_RUNNING, NOT_CLAIMABLE — all readable, all reachable
+            // by racing the Dash, and none of them a reason to abandon the setup.
+            const { code, message, hint } = formatError(e);
+            console.error(`  ✗ ${code ? `${code}: ` : ""}${message}`);
+            if (hint)
+                console.error(`    → ${hint}`);
+            return;
+        }
+        // Claiming one ClickUp identity removes EVERY remaining ClickUp row (`claimableGhosts`
+        // filters by spent source), so the next round can only ever offer a different tool.
+    }
+}
+export async function joinAction(link, opts) {
+    // Client-side, before anything else: the code is what the server matches, and someone
+    // who pasted the wrong thing should hear it here rather than as "not recognized".
+    const code = parseInviteCode(link);
+    await ensureSignedIn();
+    // --- 2. redeem ------------------------------------------------------------
+    // Any failure here stops the run. A dead invite means there is no org to bind to, and
+    // binding this folder to nothing would be worse than stopping.
+    const res = (await api.acceptInvite({ code }));
+    const orgLabel = res.slug ? clean(res.slug) : undefined;
+    const where = orgLabel ? ` "${orgLabel}"` : "";
+    if (res.alreadyMember) {
+        // Not a failure: the code stays unconsumed by design, so the person it was meant for
+        // can still use it. Say so and carry on into the folder half.
+        console.log(`• You're already a member of org${where} (${res.role}).`);
+    }
+    else {
+        console.log(`✓ Joined org${where} as a ${res.role}.`);
+    }
+    if (opts.bind === false) {
+        // `--no-bind` is redeem-only, exactly as `join` behaved before RTSC-492 — including
+        // asking nothing, so anything scripted against it sees the same output and the same
+        // exit code. The identity prompt still reaches them through the Dash.
+        return;
+    }
+    // --- 3. identity ----------------------------------------------------------
+    // BEFORE anything about this folder, including the re-bind guard. Ghosts are rows in
+    // `members`, which carries an `orgId` and no `projectId`: the question belongs to the org
+    // just joined, and this is the only time `join` asks it. Gating it behind the folder half
+    // would mean someone whose folder is already bound elsewhere — who declines the re-bind —
+    // silently never sees it, and their imported history stays stranded.
+    await identityLoop(res.orgId, opts, orgLabel);
+    // --- the folder half ------------------------------------------------------
+    const cfg = loadConfig();
+    const self = selfCommand(VERSION);
+    const resume = `${self} bind --org-id ${res.orgId}`;
+    const guard = await rebindGuard({
+        cwd: process.cwd(),
+        mcpUrl: cfg.mcpUrl,
+        orgId: res.orgId,
+        projectId: opts.projectId,
+        yes: opts.yes,
+    });
+    if (!guard.proceed) {
+        // The membership landed either way — never let a declined or no-op re-bind read as a
+        // failed join. `rebindGuard` has already said what it did with the folder, INCLUDING
+        // setting a non-zero exit code for the non-interactive refusal, so don't paper over
+        // that with a line that reads like everything is finished.
+        if (process.exitCode)
+            console.error(`  You did join org${where}; only the folder was left alone.`);
+        else
+            console.log(`  You're a member of org${where}. Nothing else to do here.`);
+        return;
+    }
+    try {
+        await completeWorkspaceSetup({
+            orgId: res.orgId,
+            orgLabel,
+            opts,
+            existing: guard.existing,
+            // `createProject` is `requireOwner`, and an invite only ever grants `member`. Offering
+            // "+ create new" here would be offering a refusal dressed as a choice.
+            canCreateProject: false,
+        });
+    }
+    catch (e) {
+        // Say what SUCCEEDED before reporting the failure, and name the command that resumes.
+        // The membership (and any identity claim) already landed and cannot be re-done: the
+        // invite is consumed now, so re-running `join` with the same link would report
+        // "already used" and read like the whole thing failed.
+        console.error(`\n  You did join org${where} — only this folder's setup didn't finish.`);
+        console.error(`  Resume with:  ${resume}`);
+        throw e;
+    }
+    if (isInteractive()) {
+        console.log("\nStart your agent in this folder and it'll pull from the queue.");
+    }
+}

package/dist/commands/mcp.js

@@ -1,6 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
+import { resolveLauncher, launcherNote, portableLauncher, } from "../lib/launcher.js";
+import { VERSION } from "../version.js";
 export const SERVER_NAME = "retasc";
 /** Normalize a user-supplied scope string. `user` (global) is refused and
  * downgraded to `local`, loudly — per-folder binding is the only right way. */
@@ -32,31 +34,31 @@ export function mcpConfigBlock(url, key) {
  * claimed issues' leases alive automatically. url+key go via env (not a header,
  * since this is a spawned command). Harness-agnostic: any stdio MCP client works.
  */
-export function mcpProxyEntry(url, key) {
+export function mcpProxyEntry(url, key, launcher) {
     return {
-        command: "retasc",
-        args: ["mcp-proxy"],
+        command: launcher.command,
+        args: [...launcher.args, "mcp-proxy"],
         env: { RETASC_MCP_URL: url, RETASC_MCP_KEY: key },
     };
 }
 /** Copy-pasteable watchdog block for Codex / OpenCode / any stdio MCP client. */
-export function mcpProxyConfigBlock(url, key) {
-    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key) } }, null, 2);
+export function mcpProxyConfigBlock(url, key, launcher) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key, launcher) } }, null, 2);
 }
 /**
  * RTSC-92: the SECRET-FREE watchdog marker. No key — only the opaque workspace
  * id, which the proxy resolves to a key through the home keystore. Safe to
  * commit; doubles as the "this repo is a Retasc workspace" marker.
  */
-export function mcpMarkerEntry(workspaceId) {
+export function mcpMarkerEntry(workspaceId, launcher) {
     return {
-        command: "retasc",
-        args: ["mcp-proxy"],
+        command: launcher.command,
+        args: [...launcher.args, "mcp-proxy"],
         env: { RETASC_WORKSPACE: workspaceId },
     };
 }
-export function mcpMarkerConfigBlock(workspaceId) {
-    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpMarkerEntry(workspaceId) } }, null, 2);
+export function mcpMarkerConfigBlock(workspaceId, launcher) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpMarkerEntry(workspaceId, launcher) } }, null, 2);
 }
 // --- `claude mcp add` argv builders (pure, exported for tests) -------------
 // RTSC-99: the stdio builders put SERVER_NAME *before* the variadic `--env`
@@ -75,7 +77,7 @@ export function buildHttpAddArgs(url, key, scope) {
     ];
 }
 /** Build argv for the stdio watchdog proxy (RTSC-44). */
-export function buildWatchdogAddArgs(url, key, scope) {
+export function buildWatchdogAddArgs(url, key, scope, launcher) {
     return [
         "mcp", "add",
         SERVER_NAME,
@@ -83,28 +85,28 @@ export function buildWatchdogAddArgs(url, key, scope) {
         "--scope", scope,
         "--env", `RETASC_MCP_URL=${url}`,
         "--env", `RETASC_MCP_KEY=${key}`,
-        "--", "retasc", "mcp-proxy",
+        "--", launcher.command, ...launcher.args, "mcp-proxy",
     ];
 }
 /** Build argv for the secret-free stdio marker (RTSC-92). */
-export function buildMarkerAddArgs(workspaceId, scope) {
+export function buildMarkerAddArgs(workspaceId, scope, launcher) {
     return [
         "mcp", "add",
         SERVER_NAME,
         "--transport", "stdio",
         "--scope", scope,
         "--env", `RETASC_WORKSPACE=${workspaceId}`,
-        "--", "retasc", "mcp-proxy",
+        "--", launcher.command, ...launcher.args, "mcp-proxy",
     ];
 }
 function tryClaudeCli(url, key, scope) {
     return runClaudeAdd(buildHttpAddArgs(url, key, scope));
 }
-function tryClaudeCliWatchdog(url, key, scope) {
-    return runClaudeAdd(buildWatchdogAddArgs(url, key, scope));
+function tryClaudeCliWatchdog(url, key, scope, launcher) {
+    return runClaudeAdd(buildWatchdogAddArgs(url, key, scope, launcher));
 }
-function tryClaudeCliMarker(workspaceId, scope) {
-    return runClaudeAdd(buildMarkerAddArgs(workspaceId, scope));
+function tryClaudeCliMarker(workspaceId, scope, launcher) {
+    return runClaudeAdd(buildMarkerAddArgs(workspaceId, scope, launcher));
 }
 function runClaudeAdd(args) {
     const r = spawnSync("claude", args, { encoding: "utf8" });
@@ -167,17 +169,23 @@ export function installMcp(opts) {
     const scope = opts.scope ?? "local";
     // Watchdog mode (RTSC-44): wire the stdio proxy so claims stay alive automatically.
     if (opts.watchdog) {
-        const res = tryClaudeCliWatchdog(opts.url, opts.key, scope);
+        // Only the stdio forms spawn a command; the plain HTTP entry below carries a URL and
+        // needs nothing installed, so resolving is scoped to the branch that depends on it.
+        const resolved = resolveLauncher({ version: VERSION, install: opts.install });
+        const note = launcherNote(resolved);
+        if (note)
+            console.log(note);
+        const res = tryClaudeCliWatchdog(opts.url, opts.key, scope, resolved.launcher);
         if (res.ok) {
             console.log(`✓ Registered Retasc with the liveness watchdog (stdio proxy, scope: ${scope}).`);
         }
         else {
-            const path = writeProjectMcpJson(mcpProxyEntry(opts.url, opts.key));
+            const path = writeProjectMcpJson(mcpProxyEntry(opts.url, opts.key, resolved.launcher));
             console.log(`✓ Wrote watchdog MCP config to ${path}`);
             console.log(`  ${fallbackNote(res)}`);
         }
         console.log("\nWatchdog MCP config (Codex / OpenCode / any stdio MCP client):\n");
-        console.log(mcpProxyConfigBlock(opts.url, opts.key));
+        console.log(mcpProxyConfigBlock(opts.url, opts.key, resolved.launcher));
         console.log("\nThe watchdog keeps your claims alive automatically — no per-claim heartbeats. If it ever isn't running you just fall back to the normal lease timeout (safe).");
         return;
     }
@@ -201,16 +209,30 @@ export function installMcp(opts) {
  */
 export function installMarker(opts) {
     const scope = opts.scope ?? "local";
-    const res = tryClaudeCliMarker(opts.workspaceId, scope);
+    // RTSC-493: resolve BEFORE writing anything. The marker names a command something else
+    // will spawn later, so it has to name one that has been proved to run on this machine.
+    const resolved = opts.launcher ?? resolveLauncher({ version: VERSION, install: opts.install });
+    // Only announce a resolve we did ourselves — a caller that passed one in already printed
+    // its note at the point in ITS sequence where the install actually happened.
+    const note = opts.launcher ? null : launcherNote(resolved);
+    if (note)
+        console.log(note);
+    // `local` scope lands in this machine's own Claude config, where the absolute path is
+    // both correct and fastest. `project` scope, and the ./.mcp.json fallback below, are
+    // SHARED — a path under this user's home directory would leak their username into a
+    // committed file and break every teammate who clones it. See portableLauncher.
+    const shared = portableLauncher(resolved, VERSION);
+    const res = tryClaudeCliMarker(opts.workspaceId, scope, scope === "project" ? shared : resolved.launcher);
     if (res.ok) {
         console.log(`✓ Registered Retasc watchdog (secret-free marker, scope: ${scope}).`);
     }
     else {
-        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId));
+        // Always ./.mcp.json, whatever scope was asked for, so always the shared form.
+        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId, shared));
         console.log(`✓ Wrote secret-free watchdog marker to ${path}`);
         console.log(`  ${fallbackNote(res)}`);
     }
     console.log("\nMarker block (any stdio MCP client) — no secret, safe to commit:\n");
-    console.log(mcpMarkerConfigBlock(opts.workspaceId));
+    console.log(mcpMarkerConfigBlock(opts.workspaceId, shared));
     console.log("\nThe key lives in your home keystore (~/.retasc/bindings.json), not in the repo.");
 }

package/dist/index.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { VERSION } from "./version.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate } from "./commands/gate.js";
 import { claimAction } from "./commands/claim.js";
 import { bindAction } from "./commands/bind.js";
+import { joinAction } from "./commands/join.js";
 import { doctorAction } from "./commands/doctor.js";
 import { billingAction } from "./commands/billing.js";
 import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
@@ -15,16 +14,11 @@ import { tidyAction, doneAction } from "./commands/tidy.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
 import { api, formatError } from "./api.js";
-// Single source of truth for the version: read package.json at runtime from the
-// compiled file's location (dist/index.js -> ../package.json). A JSON import won't
-// work here — tsconfig has rootDir "src", so importing ../package.json is outside
-// rootDir and fails tsc.
-const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
 const program = new Command();
 program
     .name("retasc")
     .description("Retasc — sign in, create projects, mint agent API keys, and wire your agent to the MCP server.")
-    .version(pkg.version);
+    .version(VERSION);
 function requireLogin() {
     if (!isLoggedIn()) {
         console.error("Not signed in. Run `retasc login` first.");
@@ -327,7 +321,11 @@ members
         const res = (await api.createInvite({ orgId: opts.orgId, expiresInDays: opts.expiresDays }));
         console.log(`✓ Invite code: ${res.code}`);
         console.log(`  Expires ${new Date(res.expiresAt).toISOString().slice(0, 10)}. Single-use — shown once.`);
-        console.log(`  Share it; they run:  retasc login && retasc join ${res.code}`);
+        // RTSC-492: one command, and one that needs nothing installed first. `join` signs
+        // them in, binds the folder and wires their agent, so this must not tell them to run
+        // `retasc login` first — nor name a `retasc` binary they don't have yet.
+        console.log(`  Share it. In the folder their agent works in, they run:`);
+        console.log(`      npx @retasc/cli join ${res.code}`);
     }
     catch (e) {
         fail(e);
@@ -361,25 +359,23 @@ members
         fail(e);
     }
 });
+// RTSC-492 — the WHOLE of an invited teammate's setup, in one command run from the folder
+// their agent will work in: sign in, redeem, claim any imported history, pick the project,
+// make `retasc` durable, mint a key, bind the folder and wire the MCP marker. It signs
+// itself in (no `requireLogin` gate) because "run this, but run the other one first" is
+// not a single instruction.
 program
     .command("join")
-    .description("Redeem an invite code to join an org (as the signed-in GitHub user).")
-    .argument("<code>", "The invite code you were given")
-    .action(async (code) => {
-    requireLogin();
-    try {
-        const res = (await api.acceptInvite({ code }));
-        const where = res.slug ? ` "${res.slug}"` : "";
-        if (res.alreadyMember) {
-            console.log(`• You're already a member of org${where} (${res.role}). Nothing to do.`);
-        }
-        else {
-            console.log(`✓ Joined org${where} as ${res.role}. It'll show up in \`retasc whoami\`.`);
-        }
-    }
-    catch (e) {
-        fail(e);
-    }
+    .description("Join an org from an invite link and set this folder up completely — one command.")
+    .argument("<link>", "The invite link you were given (or just the rtscinv_… code)")
+    .option("--no-bind", "Redeem only — don't set this folder up")
+    .option("--project-id <id>", "Which project to bind to (skips the picker)")
+    .option("--agent <name>", "Agent member name (default: auto)")
+    .option("--runtime <runtime>", "Agent runtime", "claude-code")
+    .option("-y, --yes", "Don't prompt to replace an existing binding, and skip the identity question")
+    .allowExcessArguments(false)
+    .action(async (link, opts) => {
+    await joinAction(link, opts).catch(fail);
 });
 // --- mcp wiring ------------------------------------------------------------
 const mcp = program.command("mcp").description("Wire the Retasc MCP server into your agent.");

package/dist/lib/binding.js

@@ -26,13 +26,17 @@ function parseServerEntry(s, source) {
     if (!s)
         return undefined;
     // Canonical (RTSC-92): secret-free marker → resolve the key from the keystore.
+    // RTSC-493: the spawned command, when this is one of the stdio forms.
+    const spawn = typeof s.command === "string"
+        ? { command: s.command, args: Array.isArray(s.args) ? s.args.map(String) : [] }
+        : {};
     const workspaceId = s.env?.RETASC_WORKSPACE;
     if (workspaceId) {
         const entry = getBinding(workspaceId);
         if (entry)
-            return { key: entry.key, url: entry.url, watchdog: true, workspaceId, source };
+            return { key: entry.key, url: entry.url, watchdog: true, workspaceId, source, ...spawn };
         // Marker present but no keystore entry (e.g. a cloned repo) → needs binding.
-        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true, source };
+        return { key: "", url: "", watchdog: true, workspaceId, markerOnly: true, source, ...spawn };
     }
     // Legacy inline-key forms (pre-RTSC-92): key in env or the Authorization header.
     if (s.env?.RETASC_MCP_KEY) {
@@ -42,6 +46,7 @@ function parseServerEntry(s, source) {
             watchdog: true,
             legacy: true,
             source,
+            ...spawn,
         };
     }
     const auth = s.headers?.Authorization ?? s.headers?.authorization;

package/dist/lib/invite.js

@@ -0,0 +1,38 @@
+// RTSC-492 — turn whatever the person was handed into the code the server matches.
+//
+// An invite reaches someone as a LINK (`https://dash.retasc.com/join#rtscinv_…`), and a
+// link is what they paste. `acceptInvite` matches an exact string, and it should stay that
+// way: normalising a paste is a property of the edge that accepts typed input, not of the
+// mutation that grants membership. So the unwrapping happens here.
+/** Every invite code the product has ever minted starts with this. */
+const INVITE_PREFIX = "rtscinv_";
+/**
+ * The invite code inside a link, a bare code, or a code someone pasted with prose
+ * around it.
+ *
+ * One rule rather than a parser: find the first token that LOOKS like an invite code,
+ * anywhere in the input. That covers the fragment (`…/join#rtscinv_x`), a query string
+ * (`?code=rtscinv_x`), a path segment, an email client's `<…>` wrapper and a trailing
+ * period from a sentence, without needing to know which of those the sender used — and
+ * without the URL-shape guessing that gets one of them wrong.
+ *
+ * A token that isn't our shape is still passed through UNCHANGED as long as it can't be a
+ * link. A future code format then keeps working with no CLI release, and the server's
+ * "That invite code isn't recognized" stays the authority on what's valid. Something
+ * link-shaped with no code in it is the one case we refuse locally, because forwarding a
+ * URL as a code can only ever produce that same message with none of the diagnosis.
+ */
+export function parseInviteCode(input) {
+    const raw = String(input ?? "").trim();
+    // Hex today, but accept the wider token charset a future format might use rather than
+    // pinning this to `[0-9a-f]{48}` and having to ship a release to read a new code.
+    const match = raw.match(new RegExp(`${INVITE_PREFIX}[A-Za-z0-9_-]+`));
+    if (match)
+        return match[0];
+    const bare = raw.replace(/^[<"'(]+|[>"'.,)]+$/g, "");
+    if (bare && !/[\s/:]/.test(bare))
+        return bare;
+    throw new Error(raw
+        ? "That doesn't contain an invite code. Paste the whole invite link, or just the `rtscinv_…` code."
+        : "No invite code given. Pass the invite link, or just the `rtscinv_…` code.");
+}