@retasc/cli 1.26.0 → 1.28.0

package/CHANGELOG.md

@@ -6,6 +6,30 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.28.0 (2026-08-19)
+
+- **RTSC-676** — signing in opens your browser. It used to print a URL and an
+  eight-character code and leave you to switch windows, navigate, and retype it. Now the
+  page opens for you, pre-filled when the provider supplies RFC 8628's complete URL. The
+  URL and code are still printed first and always: there is no browser inside a container
+  or over SSH, which is where `bind` runs most, so the browser is a convenience layered
+  on top and never the only way through. A missing `xdg-open` changes nothing.
+  `RETASC_NO_BROWSER=1` turns it off.
+- **RTSC-676** — the finish screen's closing lines are flush left, and it ends with a
+  blank line instead of welding the shell prompt to the last thing you read.
+
+## 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

package/dist/auth.js

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { loadConfig, patchConfig } from "./config.js";
@@ -28,11 +29,61 @@ async function postForm(url, body) {
     return res.json();
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Print the two lines a human has to act on, identically for both doors. */
-function announceCode(where, url, code) {
+/**
+ * Open a URL in the machine's browser, best effort (RTSC-676).
+ *
+ * BEST EFFORT is the whole contract. There is no browser inside a container or over
+ * SSH, which is where `bind` most often runs, so this must never be the only way
+ * through and must never turn a failure of its own into a failure of sign-in. It is
+ * spawned detached and every outcome is swallowed: the printed URL and code below are
+ * the real path, and this only saves the person who does have a browser a trip through
+ * their address bar.
+ *
+ * `xdg-open` on Linux is frequently absent even under a desktop; that is a miss, not an
+ * error. `start` needs a shell on Windows, and its first quoted argument is the window
+ * TITLE, hence the empty string.
+ */
+function openBrowser(url) {
+    if (process.env.RETASC_NO_BROWSER)
+        return;
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["start", ['""', url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, {
+            stdio: "ignore",
+            detached: true,
+            shell: process.platform === "win32",
+        });
+        // Without this the CLI would wait on a browser that outlives it by hours.
+        child.unref();
+        // A missing `xdg-open` surfaces here rather than as a throw.
+        child.on("error", () => { });
+    }
+    catch {
+        /* no browser, no shell, no matter — the URL is printed below */
+    }
+}
+/**
+ * Print the two lines a human has to act on, identically for both doors, and open the
+ * browser for them if this machine has one.
+ *
+ * The lines are printed FIRST and unconditionally. Someone reading a terminal in a
+ * container has to see the URL whatever happened, and an auto-open that silently
+ * failed must leave the screen exactly as useful as it was before (RTSC-676).
+ *
+ * `complete` is RFC 8628's pre-filled URL when the provider sent one. It is opened in
+ * preference to the plain one, but never PRINTED in its place: the code stays on its own
+ * line so it can be read aloud, retyped on a phone, or pasted into a browser on another
+ * machine — none of which a link helps with.
+ */
+function announceCode(where, url, code, complete) {
     console.log(`\n  Open: ${url}`);
     console.log(`  Enter code: ${code}\n`);
     console.log(`  Waiting for ${where} authorization…`);
+    openBrowser(complete || url);
 }
 /** Run GitHub's device flow (talking to GitHub directly) and return its access token. */
 async function githubDeviceToken() {
@@ -46,7 +97,7 @@ async function githubDeviceToken() {
     if (!start.device_code) {
         throw new Error(`GitHub device-flow start failed: ${JSON.stringify(start)}`);
     }
-    announceCode("GitHub", start.verification_uri, start.user_code);
+    announceCode("GitHub", start.verification_uri, start.user_code, start.verification_uri_complete);
     // Poll GitHub for the access token.
     let intervalMs = (start.interval || 5) * 1000;
     const deadline = Date.now() + start.expires_in * 1000;
@@ -80,7 +131,7 @@ async function githubDeviceToken() {
  */
 async function googleDeviceToken(convex) {
     const start = (await convex.action(googleDeviceStart, {}));
-    announceCode("Google", start.verificationUrl, start.userCode);
+    announceCode("Google", start.verificationUrl, start.userCode, start.verificationUrlComplete);
     let intervalMs = (start.intervalSeconds || 5) * 1000;
     const deadline = Date.now() + start.expiresInSeconds * 1000;
     while (Date.now() < deadline) {

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,46 @@ 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)}\n`);
+}
+/**
+ * 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) {
+    // FLUSH LEFT (RTSC-676). Indented, these read as subordinate to the line above them
+    // when they are in fact continuing it — the eye takes the block for a nested detail
+    // rather than the instruction it is.
+    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();

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/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.26.0",
+  "version": "1.28.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": {