@retasc/cli 1.25.0 → 1.27.0

package/CHANGELOG.md

@@ -6,6 +6,33 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.27.0 (2026-08-19)
+
+- **RTSC-673** — `bind` ends by telling you what to do, not by dumping config. It used to
+  close on fourteen lines of MCP JSON plus "(Claude Code CLI not detected)": a block
+  instructing you to paste something we had just written to disk for you, and a note that
+  reads like a fault on a screen whose whole content is that everything worked. Between
+  them they buried the one thing a new owner needed. Now it prints a receipt card — org,
+  project, where the key went, what landed in your repo — and then says to start your
+  agent. The closing lines follow the project: an empty one invites you to describe what
+  you're building, a project with work in it tells you to say "next issue". The JSON still
+  prints when the marker could not be written anywhere, which is the case it exists for.
+
+## 1.26.0 (2026-08-19)
+
+- **RTSC-670** — `retasc bind` can sign you in again. It has opened with the device flow
+  since 1.20-era, but a leftover session guard in the command wrapper exited first, so on
+  a machine that had never signed in — the only state a new owner is ever in — `bind`
+  printed "Not signed in" and stopped. Owner onboarding dead-ended at its first
+  documented command, on every release for three weeks. The guard was correct when it was
+  written and became redundant the moment `bind` grew its own sign-in; nothing noticed
+  because no test ran the CLI with no session. Four now do.
+- **RTSC-671** — errors name the command you actually ran. Told to `npx @retasc/cli bind`
+  and then answered with "Run `retasc login` first", you were pointed at a binary that
+  invocation never installs — a recoverable stumble turned into a dead end. Every "run X
+  first" message now renders `npx -y @retasc/cli@<version> …` or `retasc …` to match how
+  you started it.
+
 ## 1.25.0 (2026-08-19)
 
 - **RTSC-669** — the invite project picker takes several projects. 1.24.0 shipped it

package/dist/api.js

@@ -2,6 +2,8 @@ import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { loadConfig } from "./config.js";
 import { refreshSession, deviceLogin } from "./auth.js";
+import { selfCommand } from "./lib/launcher.js";
+import { VERSION } from "./version.js";
 // Typed-ish references to the public management functions in convex/manage.ts.
 // The CLI is a standalone package, so we reference functions by name rather than
 // importing the parent's generated api.
@@ -163,7 +165,7 @@ async function withAuth(call) {
         if (await refreshSession())
             return await call();
         if (!process.stdout.isTTY) {
-            throw new Error("Session expired and could not refresh. Run `retasc login`.");
+            throw new Error(`Session expired and could not refresh. Run \`${selfCommand(VERSION)} login\`.`);
         }
         console.error("Session expired — re-authenticating with GitHub…");
         await deviceLogin();

package/dist/commands/bind.js

@@ -2,12 +2,13 @@ import { basename } from "node:path";
 import { api, cliError } from "../api.js";
 import { deviceLogin } from "../auth.js";
 import { loadConfig, patchConfig } from "../config.js";
-import { installMarker } from "./mcp.js";
+import { installMarker, printMarkerBlock } from "./mcp.js";
 import { readLocalBinding, resolveBinding } from "../lib/binding.js";
 import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
 import { resolveLauncher, launcherNote, runsOk, selfCommand } from "../lib/launcher.js";
 import { ask, confirm, isInteractive } from "../lib/prompt.js";
 import { clean } from "../lib/text.js";
+import { card, DOT } from "../lib/card.js";
 import { VERSION } from "../version.js";
 // RTSC-508: `ask`/`confirm`/`isInteractive` now live in lib/prompt.ts so `auth.ts`
 // can use them without closing an import cycle (bind → auth → bind). Re-exported
@@ -217,7 +218,7 @@ async function nameAProject(orgId) {
         throw new Error("project name and prefix required");
     const p = (await api.createProject({ orgId, name, prefix: pfx }));
     console.log(`✓ Created project ${p.prefix}.`);
-    return { projectId: p.projectId, prefix: p.prefix };
+    return { projectId: p.projectId, prefix: p.prefix, empty: true };
 }
 /**
  * "Where does your work come from?" — the first project, for an org that has none.
@@ -260,7 +261,8 @@ async function firstProject(orgId, orgLabel) {
         console.log("\nNo import. Let's make an empty project instead.");
         return nameAProject(orgId);
     }
-    return done;
+    // An import that ran has work in it by definition — that is what it did.
+    return { ...done, empty: false };
 }
 /**
  * Everything from "which project" to a working folder: pick the project, make `retasc`
@@ -284,6 +286,11 @@ export async function completeWorkspaceSetup(args) {
     // --- resolve project (pick / flag / create) --------------------------------
     let projectId = opts.projectId;
     let prefix;
+    // RTSC-673 — does this project have anything in it yet? Decides which two sentences
+    // close the run. UNKNOWN defaults to "has work": a --project-id we never listed could
+    // be either, and telling someone with 200 issues that their project is empty is the
+    // worse half of that guess.
+    let emptyProject = false;
     if (!projectId && opts.project && opts.prefix) {
         if (!args.canCreateProject) {
             cliError("FORBIDDEN", "Only an owner or admin can create a project.", `Ask one of them to add one, then pass --project-id <id>.`);
@@ -291,10 +298,13 @@ export async function completeWorkspaceSetup(args) {
         const p = (await api.createProject({ orgId, name: opts.project, prefix: opts.prefix }));
         projectId = p.projectId;
         prefix = p.prefix;
+        emptyProject = true;
         console.log(`✓ Created project ${p.prefix}.`);
     }
     if (!projectId) {
         const { projects } = (await api.listProjects({ orgId }));
+        // `counter` is the last ISSUED number, so 0 means nothing was ever filed here —
+        // which is the only question RTSC-673 asks of it. It is NOT an open count.
         const list = projects ?? [];
         if (!args.canCreateProject) {
             // A member cannot create one, so an empty org is a dead end here — and it has to say
@@ -308,11 +318,13 @@ export async function completeWorkspaceSetup(args) {
             if (list.length === 1) {
                 projectId = list[0].id;
                 prefix = list[0].prefix;
+                emptyProject = projectIsEmpty(list[0]);
             }
             else if (isInteractive()) {
                 const chosen = await pickExisting("Select a project", list, (p) => `${clean(p.prefix)} — ${clean(p.name)}`);
                 projectId = chosen.id;
                 prefix = chosen.prefix;
+                emptyProject = projectIsEmpty(chosen);
             }
             else {
                 cliError("AMBIGUOUS", `Org ${org} has ${list.length} projects, so one has to be named.`, `Pass --project-id <id> (or run interactively): ${list.map((p) => `${p.prefix}=${p.id}`).join(", ")}`);
@@ -330,17 +342,20 @@ export async function completeWorkspaceSetup(args) {
             const made = await firstProject(orgId, org);
             projectId = made.projectId;
             prefix = made.prefix;
+            emptyProject = made.empty;
         }
         else if (isInteractive()) {
             const chosen = await pick("Select a project", list, (p) => `${clean(p.prefix)} — ${clean(p.name)}`);
             if (chosen) {
                 projectId = chosen.id;
                 prefix = chosen.prefix;
+                emptyProject = projectIsEmpty(chosen);
             }
             else {
                 const made = await nameAProject(orgId);
                 projectId = made.projectId;
                 prefix = made.prefix;
+                emptyProject = made.empty;
             }
         }
         else if (list.length === 1) {
@@ -376,7 +391,8 @@ export async function completeWorkspaceSetup(args) {
         runtime: opts.runtime ?? "claude-code",
         keyName: prefix ? `${prefix} key` : undefined,
     }));
-    console.log(`✓ Minted key for this workspace (${minted.key.slice(0, 14)}…).\n`);
+    // The key is named in the receipt card below, not here — one mention, in the place
+    // that says where it went (RTSC-673).
     // RTSC-92: the secret stays OUT of the repo. Store it in the home keystore
     // keyed by a workspace id; reuse this folder's existing id (so a re-bind, or a
     // teammate's committed marker, keeps the same id) or mint a fresh one.
@@ -394,16 +410,31 @@ export async function completeWorkspaceSetup(args) {
     args.onBound?.();
     // Per-folder only (local scope), always watchdog. The marker carries only the
     // workspace id — no secret — so ./.mcp.json is safe to commit.
-    installMarker({ workspaceId, scope: "local", launcher });
-    // Confirm the binding the same way the agent will see it.
+    const marker = installMarker({ workspaceId, scope: "local", launcher, quiet: true });
+    // Confirm the binding the same way the agent will see it, and print it as the receipt
+    // (RTSC-673). Resolved rather than echoed from what we just sent: this is the last
+    // chance to notice a folder bound to something other than what was asked for, and a
+    // card built from our own inputs could never show that.
+    let bound = null;
     try {
         const b = await resolveBinding(cfg.mcpUrl, minted.key);
-        console.log(`\n✓ This folder is bound to org "${clean(b.org.name)}" / project ${clean(b.project.prefix)}.\n` +
-            `  Agents launched here can only ever read or write ${clean(b.project.prefix)}.`);
+        bound = { org: clean(b.org.name), prefix: clean(b.project.prefix), name: b.project.name };
     }
     catch {
-        /* binding written; whoami confirmation is best-effort */
+        /* binding written; whoami confirmation is best-effort — fall back to what we sent */
     }
+    const orgLabel = bound?.org ?? clean(args.orgLabel ?? "");
+    const pfx = bound?.prefix ?? clean(prefix ?? "");
+    console.log("\n" +
+        card(`✓ This folder is bound to ${orgLabel} / ${pfx}`, [
+            { label: "Org", value: orgLabel },
+            { label: "Project", value: bound?.name ? `${pfx} ${DOT} ${bound.name}` : pfx },
+            { label: "Agent key", value: `${minted.key.slice(0, 14)}…`, note: "never leaves ~/.retasc" },
+            { label: "MCP wired", value: marker.where, note: "secret-free, safe to commit" },
+        ], `Agents launched here can only ever read or write ${pfx}.`));
+    // Only when we could write it nowhere. See printMarkerBlock.
+    if (!marker.wroteFile && marker.where === "")
+        printMarkerBlock(workspaceId, launcher);
     // RTSC-519 — say that setup FINISHED, and what to do with it.
     //
     // Here rather than in either command, because it is true of both and this is the tail
@@ -415,7 +446,43 @@ export async function completeWorkspaceSetup(args) {
     // AFTER the confirmation, and after everything that can throw, so it is only ever
     // printed by a run that actually finished. Nothing below it can fail.
     if (isInteractive())
-        console.log(`\n${NEXT_STEP}`);
+        console.log(`\n${NEXT_STEP}\n\n${whatNow(pfx, emptyProject)}`);
+}
+/**
+ * The two sentences under `NEXT_STEP`, chosen by whether there is anything to pull yet
+ * (RTSC-673).
+ *
+ * `NEXT_STEP` says how to connect an agent. It cannot say what to ASK it, because the
+ * right first thing differs entirely: a project created ten seconds ago has an empty
+ * queue, and telling that person to say "next issue" sends them to a blank result as
+ * their first experience of the product. Telling the person who just imported 142 issues
+ * to "describe what you're building" wastes the work they already have.
+ *
+ * No count in either branch, deliberately. `projects.counter` is the last ISSUED number,
+ * so a project with 200 created and 195 closed still reads 200 — printing it as an open
+ * count would be a precise lie. The importer already reports its own totals during the
+ * import step, which is where a real number belongs. A true count here needs an
+ * open-issue query the CLI does not have yet.
+ *
+ * "0 issues" is never printed for the empty case either: zero is the expected state for
+ * a project someone just named, and stating it as a quantity reads like a failure.
+ */
+export function projectIsEmpty(p) {
+    // `counter` is the last ISSUED number, never a count of open work: a project with 200
+    // filed and 195 closed still reads 200. So it answers exactly one question — has
+    // anything ever been filed here — which is the only one `whatNow` asks. Absent
+    // (an older payload, or a caller that never listed the project) reads as NOT empty:
+    // telling someone with 200 issues that their project is empty is the worse half of
+    // that guess.
+    return p.counter === 0;
+}
+export function whatNow(prefix, empty) {
+    return empty
+        ? `  ${prefix} is empty, so start by talking with the agent. Tell it what you're\n` +
+            `  building and it will file the work as it goes.\n\n` +
+            `  Once there's a backlog, saying "next issue" is how you pull from it.`
+        : `  There's already work in ${prefix}. Say "next issue" and your agent takes\n` +
+            `  the top unblocked one and starts.`;
 }
 export async function setupFromToken(token, opts, deps = {}) {
     const cfg = loadConfig();
@@ -493,7 +560,7 @@ export async function ensureSignedIn() {
     if (loadConfig().token)
         return;
     if (!isInteractive()) {
-        throw new Error("Not signed in. Run `retasc login` first (no TTY here for the device flow).");
+        throw new Error(`Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`);
     }
     // RTSC-508: don't name a provider here. `deviceLogin` asks which door, and
     // announcing "GitHub" before the question would be wrong for the invited

package/dist/commands/identity.js

@@ -1,6 +1,8 @@
 import { api } from "../api.js";
 import { clean } from "../lib/text.js";
 import { isInteractive } from "./bind.js";
+import { selfCommand } from "../lib/launcher.js";
+import { VERSION } from "../version.js";
 import { identityLoop } from "./join.js";
 /**
  * Which org's placeholders to offer.
@@ -65,7 +67,7 @@ function report(outcome, orgLabel) {
             console.log("Noted. That covers those tools only, so a later import will ask again.");
             return;
         case "left":
-            console.log("Nothing linked. Run `retasc identity` again whenever you want to look.");
+            console.log(`Nothing linked. Run \`${selfCommand(VERSION)} identity\` again whenever you want to look.`);
             return;
         case "skipped":
             // Only reachable non-interactively; the interactive guard below catches that first.

package/dist/commands/mcp.js

@@ -229,15 +229,30 @@ export function installMarker(opts) {
     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}).`);
+        if (!opts.quiet)
+            console.log(`✓ Registered Retasc watchdog (secret-free marker, scope: ${scope}).`);
+        return { where: `Claude Code (${scope})`, wroteFile: false };
     }
-    else {
-        // Always ./.mcp.json, whatever scope was asked for, so always the shared form.
-        const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId, shared));
+    // Always ./.mcp.json, whatever scope was asked for, so always the shared form.
+    const path = writeProjectMcpJson(mcpMarkerEntry(opts.workspaceId, shared));
+    if (!opts.quiet) {
         console.log(`✓ Wrote secret-free watchdog marker to ${path}`);
         console.log(`  ${fallbackNote(res)}`);
     }
+    return { where: path, wroteFile: true };
+}
+/**
+ * The MCP config block, printed ONLY when we could not write it anywhere (RTSC-673).
+ *
+ * It exists for someone wiring a client we do not know how to configure, and that is a
+ * real case. It is not the case where we just wrote the identical content to
+ * `.mcp.json` for them — there it was fourteen lines instructing a person to perform a
+ * job already finished, at the end of the one screen that should have said what to do
+ * next. `retasc doctor` prints it on demand for anyone who does need it.
+ */
+export function printMarkerBlock(workspaceId, launcher) {
+    const shared = portableLauncher(launcher ?? resolveLauncher({ version: VERSION, install: false }), VERSION);
     console.log("\nMarker block (any stdio MCP client) — no secret, safe to commit:\n");
-    console.log(mcpMarkerConfigBlock(opts.workspaceId, shared));
+    console.log(mcpMarkerConfigBlock(workspaceId, shared));
     console.log("\nThe key lives in your home keystore (~/.retasc/bindings.json), not in the repo.");
 }

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { VERSION } from "./version.js";
+import { selfCommand } from "./lib/launcher.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, normalizeScope } from "./commands/mcp.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
@@ -25,7 +26,10 @@ program
     .version(VERSION);
 function requireLogin() {
     if (!isLoggedIn()) {
-        console.error("Not signed in. Run `retasc login` first.");
+        // RTSC-671 — `selfCommand` renders the form they actually used. The docs send a
+        // new owner through `npx @retasc/cli`, which never puts `retasc` on PATH, so naming
+        // it here answers a failure with a second `command not found`.
+        console.error(`Not signed in. Run \`${selfCommand(VERSION)} login\` first.`);
         process.exit(1);
     }
 }
@@ -87,7 +91,7 @@ program
     // confirm scope before any work. Resolved from the local key, server-enforced.
     const local = readLocalBinding(process.cwd());
     if (local?.markerOnly) {
-        console.log("This folder → has a Retasc marker but no key on this machine. Run `retasc bind`.\n");
+        console.log(`This folder → has a Retasc marker but no key on this machine. Run \`${selfCommand(VERSION)} bind\`.\n`);
     }
     else if (local) {
         try {
@@ -107,10 +111,10 @@ program
         }
     }
     else {
-        console.log("This folder → not bound. Run `retasc bind`.\n");
+        console.log(`This folder → not bound. Run \`${selfCommand(VERSION)} bind\`.\n`);
     }
     if (!isLoggedIn()) {
-        console.log("Not signed in (management). Run `retasc login` to manage orgs/projects.");
+        console.log(`Not signed in (management). Run \`${selfCommand(VERSION)} login\` to manage orgs/projects.`);
         return;
     }
     try {
@@ -200,7 +204,16 @@ program
         await setupFromToken(opts.setup, opts).catch(fail);
         return;
     }
-    requireLogin();
+    // NO requireLogin here (RTSC-670). `bindAction` opens with `ensureSignedIn`, which
+    // runs the device flow when there is no session — that IS the documented first step
+    // of owner onboarding, and it is the only state a new owner is ever in. This guard
+    // predated that (it was correct in 285ec74, when bindAction had no sign-in of its
+    // own) and `ensureSignedIn` arriving in 72182c3 left it in front of a door it
+    // permanently closed: every `bind` on a fresh machine exited 1 before reaching it.
+    //
+    // `ensureSignedIn` also refuses BETTER — it says why ("no TTY here for the device
+    // flow") where this said only that you weren't signed in, which is the diagnosis
+    // that sends someone looking in the wrong place.
     await bindAction(opts).catch(fail);
 });
 // `retasc doctor` — verify this folder's binding + flag any illegal global server.
@@ -527,7 +540,7 @@ gate
         if (r.source !== "--prefix")
             console.log(`Prefix ${r.prefix} — from ${r.source}.`);
         if (r.source === "global config") {
-            console.log("  (This folder isn't bound — `retasc bind` makes the prefix folder-scoped.)");
+            console.log(`  (This folder isn't bound — \`${selfCommand(VERSION)} bind\` makes the prefix folder-scoped.)`);
         }
         if (r.shadowedDefault) {
             console.log(`  ⚠ Ignoring global default prefix ${r.shadowedDefault} — this folder's binding wins.`);

package/dist/lib/card.js

@@ -0,0 +1,66 @@
+import { clean } from "./text.js";
+// RTSC-673 — the receipt a finished `bind` prints.
+//
+// It replaces a tail that ended on fourteen lines of MCP config plus a note reading
+// "(Claude Code CLI not detected)". Both were wrong at the moment they were read: the
+// JSON told someone to paste a block we had just written to disk for them, and the note
+// announced a detection miss on a screen whose whole content is that everything worked.
+// Between them they buried the one thing a new owner needed, which is what to do next.
+//
+// A box rather than a list because this is a RECEIPT: bounded, glanced at once,
+// confirming the four facts someone might reasonably doubt (which org, which project,
+// where the secret went, what got written into their repo). The call to action stays
+// OUTSIDE it, so the thing to act on is not one more row to scan past.
+/** Inner width. 62 + borders fits an 80-column terminal with room to spare. */
+const W = 62;
+/**
+ * Does this terminal render box-drawing characters and `…` reliably?
+ *
+ * Windows `cmd.exe` is the one that does not, and it is the same distinction
+ * `lib/launcher.ts` already draws for spawning. A garbled box is worse than a plain
+ * one: it reads as corruption at the exact moment we are telling someone everything
+ * worked.
+ */
+const FANCY = process.platform !== "win32";
+const B = FANCY
+    ? { tl: "╭", tr: "╮", bl: "╰", br: "╯", h: "─", v: "│", ml: "├", mr: "┤", dot: "·", ell: "…" }
+    : { tl: "+", tr: "+", bl: "+", br: "+", h: "-", v: "|", ml: "+", mr: "+", dot: "-", ell: "..." };
+/**
+ * Fit `s` to `n` columns, ellipsing rather than letting it blow the box open.
+ *
+ * Truncation, not padding alone: an org can be named anything, and a name one character
+ * over the width turns every following line into a ragged edge. Padding is the easy half
+ * and the half that looks fine in testing, because test fixtures are short.
+ */
+function fit(s, n) {
+    const t = clean(s);
+    if (t.length <= n)
+        return t.padEnd(n);
+    return t.slice(0, Math.max(0, n - B.ell.length)) + B.ell;
+}
+/** One bordered card: a title line, labelled rows, then a footer line. */
+export function card(title, rows, footer) {
+    const inner = W - 2; // one space of padding each side
+    const line = (s) => `${B.v} ${fit(s, inner)} ${B.v}`;
+    const rule = (l, r) => `${l}${B.h.repeat(W)}${r}`;
+    const LABEL = 12;
+    const VALUE = 20;
+    const out = [rule(B.tl, B.tr), line(title), rule(B.ml, B.mr)];
+    for (const r of rows) {
+        // A note sits in a third column, so the values stay in one scannable rail. Without a
+        // note the value simply runs on — padding it anyway would leave a trench of spaces
+        // in the middle of the card.
+        const body = r.note
+            ? `${fit(r.label, LABEL)}${fit(r.value, VALUE)}${r.note}`
+            : `${fit(r.label, LABEL)}${r.value}`;
+        out.push(line(body));
+    }
+    if (footer) {
+        out.push(rule(B.ml, B.mr));
+        out.push(line(footer));
+    }
+    out.push(rule(B.bl, B.br));
+    return out.join("\n");
+}
+/** The `·` the CLI already uses between a prefix and its name, ASCII-safe. */
+export const DOT = B.dot;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Retasc CLI \u2014 the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {