@retasc/cli 1.27.0 → 1.29.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.29.0 (2026-08-19)
+
+- **RTSC-672** — every command we hand out now says `npx @retasc/cli@latest`. npx caches
+  by spec, so a bare `npx @retasc/cli` can keep serving whatever version you first ran —
+  which meant the people most likely to re-run a command, the ones who hit a bug and were
+  told it was fixed, were exactly the ones liable to be served the broken build again.
+  `@latest` is a tag, not a pin: it re-resolves every time and can never go stale, where a
+  version number written into docs absolutely can.
+- **RTSC-672** — a first-run failure names the build that produced it, so "it still
+  doesn't work" and "you're running last week's CLI" stop looking identical.
+
+## 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

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

@@ -5,7 +5,7 @@ import { loadConfig, patchConfig } from "../config.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 { resolveLauncher, launcherNote, runsOk, selfCommand, versionStamp } 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";
@@ -446,7 +446,7 @@ 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}\n\n${whatNow(pfx, emptyProject)}`);
+        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
@@ -477,12 +477,15 @@ export function projectIsEmpty(p) {
     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.`;
+        ? `${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();
@@ -560,7 +563,11 @@ export async function ensureSignedIn() {
     if (loadConfig().token)
         return;
     if (!isInteractive()) {
-        throw new Error(`Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`);
+        // RTSC-672 — the stamp rides in the HINT, not the message. `formatError` keeps only
+        // the first line of a message (deliberately, to strip stack noise), so a second line
+        // here would be silently dropped — which is how a diagnostic aimed at silent failures
+        // would itself fail silently.
+        cliError("UNAUTHENTICATED", `Not signed in. Run \`${selfCommand(VERSION)} login\` first (no TTY here for the device flow).`, versionStamp(VERSION).trim());
     }
     // 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/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from "commander";
 import { VERSION } from "./version.js";
-import { selfCommand } from "./lib/launcher.js";
+import { selfCommand, versionStamp } 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";
@@ -27,9 +27,13 @@ program
 function requireLogin() {
     if (!isLoggedIn()) {
         // 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
+        // new owner through `npx @retasc/cli@latest`, 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.`);
+        // RTSC-672 — say which build spoke. A stale CLI and a broken one produce the same
+        // sentence otherwise, and the people most likely to re-run this are the ones who
+        // were just told a fix shipped.
+        console.error(versionStamp(VERSION));
         process.exit(1);
     }
 }
@@ -403,7 +407,7 @@ members
         // 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}`);
+        console.log(`      npx @retasc/cli@latest join ${res.code}`);
     }
     catch (e) {
         fail(e);

package/dist/lib/launcher.js

@@ -96,6 +96,25 @@ export function portableLauncher(r, version) {
 export function selfCommand(version, argv1 = process.argv[1] ?? "") {
     return /[\\/]_npx[\\/]/.test(argv1) ? `npx -y ${PKG}@${version}` : "retasc";
 }
+/**
+ * A one-line stamp of which build just spoke (RTSC-672).
+ *
+ * A failure report is only diagnosable if it says what produced it. After 1.26.0 fixed
+ * sign-in, a container kept printing the 1.25.0 message and the only way to learn why was
+ * a round trip asking someone to run `--version` — because nothing in the output said.
+ * Worse, the population most likely to re-run a command is the population that hit a bug
+ * and was told it is fixed, which is exactly the population liable to be holding a stale
+ * build. "It still doesn't work" and "you are running last week's CLI" look identical
+ * without this.
+ *
+ * The EXACT version, not `@latest`: this names the code that emitted the message, which
+ * is a different question from how to fetch the current one. `npx` in the prefix when
+ * that is how they started, so the line doubles as a runnable command.
+ */
+export function versionStamp(version, argv1 = process.argv[1] ?? "") {
+    const how = /[\\/]_npx[\\/]/.test(argv1) ? `npx ${PKG}@${version}` : `${PKG} ${version}`;
+    return `  (${how})`;
+}
 /** Install (or upgrade to) an exact version globally. Returns null on success. */
 function installGlobal(version) {
     // A cold global install takes seconds with no output of its own. Silence here reads as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.27.0",
+  "version": "1.29.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": {