@retasc/cli 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -6,6 +6,44 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.20.0 (2026-08-04)
+
+- **RTSC-561** — the org gained an **admin** role, and the CLI stopped refusing it.
+  `retasc billing` gated on `role !== "owner"` client-side, so it would have refused an
+  admin locally for a call the server allows. Owner-only copy in `bind` and the command
+  help now names both roles.
+
+## 1.19.0 (2026-08-03)
+
+- **RTSC-495** — `retasc bind --setup <code>` sets a folder up with no sign-in and nothing
+  to answer, so an agent can do it on behalf of someone who does not use a terminal.
+
+  The Dash's connect step now hands over a block you paste to your agent, with this command
+  inside it. Everything the interactive `bind` would ask was already answered in the
+  browser, and the code carries those answers across. An agent's shell is not a TTY, so the
+  ordinary path refuses it outright at the first prompt.
+
+  ```
+  npx @retasc/cli bind --setup rtscsetup_…
+  ```
+
+  The code is single-use and lives ten minutes. The alternative — pasting a real API key
+  into the prompt — needed no backend at all, but would have left a long-lived credential in
+  an agent's conversation history forever.
+
+  A folder that is already connected is refused rather than silently replaced, and the
+  refusal happens BEFORE the code is spent, so a mix-up costs nothing.
+
+- **RTSC-532** — the agent says which folder it is in, and the key remembers.
+
+  Binding the wrong folder used to look exactly like success: the agent still called in, so
+  the Dash went green, while the folder you actually work in had no Retasc in it. The prompt
+  now asks the agent to report its full path and wait before it runs anything, and the
+  confirmation names the real path instead of "This folder".
+
+  The key it creates is named after that folder, so the Keys page shows which folder each
+  key belongs to (`client-a`) instead of naming them all after the project (`ENG key`).
+
 ## 1.18.0 (2026-08-02)
 
 - **RTSC-530** — setting up from scratch now asks where your work comes from, and imports it

package/dist/api.js

@@ -43,6 +43,10 @@ const fns = {
     claimableGhosts: makeFunctionReference("ghosts:claimableGhosts"),
     claimGhost: makeFunctionReference("ghosts:claimGhost"),
     dismissGhostPrompt: makeFunctionReference("ghosts:dismissGhostPrompt"),
+    // RTSC-495 — the ONLY unauthenticated call the CLI makes. Redeemed by `bind --setup`
+    // on a machine that has never signed in, because the human answered everything in the
+    // Dash and it is her agent, not her, running this.
+    redeemSetupToken: makeFunctionReference("setupToken:redeemSetupToken"),
 };
 function client() {
     const cfg = loadConfig();
@@ -51,6 +55,18 @@ function client() {
         c.setAuth(cfg.token);
     return c;
 }
+/**
+ * A client that NEVER attaches a session (RTSC-495).
+ *
+ * `client()` attaches `cfg.token` whenever one exists, and a setup-token redeem must not
+ * depend on it either way: the machine usually has no session at all, and where it has a
+ * STALE one, sending it risks failing an auth check on a call that never needed identity.
+ * Separate function rather than a flag, so "this call is unauthenticated" is visible at
+ * the call site instead of buried in an argument.
+ */
+function anonClient() {
+    return new ConvexHttpClient(loadConfig().deploymentUrl);
+}
 /**
  * Read a caught backend error into the parts a command wants to show (RTSC-261).
  *
@@ -178,6 +194,9 @@ export const api = {
     runImport: (args) => withAuth(() => client().action(fns.runImport, args)),
     latestImport: (args) => withAuth(() => client().query(fns.latestImport, args)),
     importHistory: (args) => withAuth(() => client().query(fns.importHistory, args)),
+    // NOT wrapped in `withAuth`: there is no session to refresh, and its retry path would
+    // start a device flow — the exact interactive prompt this whole flow exists to avoid.
+    redeemSetupToken: (args) => anonClient().action(fns.redeemSetupToken, args),
     claimableGhosts: (args) => withAuth(() => client().query(fns.claimableGhosts, args)),
     claimGhost: (args) => withAuth(() => client().mutation(fns.claimGhost, args)),
     dismissGhostPrompt: (args) => withAuth(() => client().mutation(fns.dismissGhostPrompt, args)),

package/dist/commands/billing.js

@@ -44,8 +44,10 @@ export async function billingAction(opts) {
     const org = me.orgs.find((o) => o.id === orgId);
     orgLabel = org ? `${org.name}${org.slug ? ` (${org.slug})` : ""}` : String(orgId);
     // Fail early with the actionable message rather than a raw FORBIDDEN from the server.
-    if (org && org.role !== "owner") {
-        throw new Error(`Billing is owner-only — your role in ${orgLabel} is "${org.role}".`);
+    // Owner OR admin (RTSC-561) — this mirrors `requireOwnerOrAdmin`, and a stale copy of
+    // the rule here would refuse an admin locally for a call the server would have allowed.
+    if (org && org.role !== "owner" && org.role !== "admin") {
+        throw new Error(`Billing needs the owner or admin role — yours in ${orgLabel} is "${org.role}".`);
     }
     const [status, charges] = await Promise.all([
         api.billingStatus({ orgId: orgId }),

package/dist/commands/bind.js

@@ -1,3 +1,4 @@
+import { basename } from "node:path";
 import { api, cliError } from "../api.js";
 import { deviceLogin } from "../auth.js";
 import { loadConfig, patchConfig } from "../config.js";
@@ -285,7 +286,7 @@ export async function completeWorkspaceSetup(args) {
     let prefix;
     if (!projectId && opts.project && opts.prefix) {
         if (!args.canCreateProject) {
-            cliError("FORBIDDEN", "Only an owner can create a project.", `Ask an owner to add one, then pass --project-id <id>.`);
+            cliError("FORBIDDEN", "Only an owner or admin can create a project.", `Ask one of them to add one, then pass --project-id <id>.`);
         }
         const p = (await api.createProject({ orgId, name: opts.project, prefix: opts.prefix }));
         projectId = p.projectId;
@@ -300,7 +301,7 @@ export async function completeWorkspaceSetup(args) {
             // what to ask for, by name. A bare FORBIDDEN from `createProject` would be both
             // wrong (they never asked to create anything) and unactionable.
             if (!list.length) {
-                cliError("NO_PROJECTS", `Org ${org} has no projects yet, and only an owner can create one.`, `Ask an owner to add a project, then finish this folder with:  ${selfCommand(VERSION)} bind --org-id ${orgId}`);
+                cliError("NO_PROJECTS", `Org ${org} has no projects yet, and only an owner or admin can create one.`, `Ask one of them to add a project, then finish this folder with:  ${selfCommand(VERSION)} bind --org-id ${orgId}`);
             }
             // One project is not a choice. Asking anyway would be the only question in the
             // common invite path, for an answer that was never in doubt.
@@ -416,6 +417,53 @@ export async function completeWorkspaceSetup(args) {
     if (isInteractive())
         console.log(`\n${NEXT_STEP}`);
 }
+export async function setupFromToken(token, opts, deps = {}) {
+    const cfg = loadConfig();
+    const cwd = process.cwd();
+    const guard = deps.guard ?? rebindGuard;
+    const redeem = deps.redeem ??
+        ((t, label) => api.redeemSetupToken({ token: t, label }));
+    // BEFORE the redeem. `rebindGuard` prints its own explanation and, with no TTY,
+    // refuses with exit 1 unless `--yes` — which is exactly the required behaviour, so it
+    // is reused rather than restated. No org/project passed: its idempotent-converge
+    // shortcut needs ids we do not have yet, and cannot apply to a single-use token anyway.
+    const { proceed, existing } = await guard({ cwd, mcpUrl: cfg.mcpUrl, yes: opts.yes });
+    if (!proceed)
+        return;
+    // Resolve (and if needed install) `retasc` BEFORE the token is spent, so a machine that
+    // cannot get a working launcher fails while the code is still redeemable.
+    const install = await chooseInstall(opts.install);
+    const launcher = resolveLauncher({ version: VERSION, install });
+    const note = launcherNote(launcher);
+    if (note)
+        console.log(note);
+    // RTSC-532 — the LEAF name, never the full path. It names the key in the Dash, so it
+    // has to be recognisable ("client-a → ENG") without publishing where on her disk it
+    // sits. `basename` of the cwd is exactly that.
+    const redeemed = await redeem(token.trim(), basename(cwd));
+    const workspaceId = existing?.workspaceId ?? newWorkspaceId();
+    (deps.bind ?? setBinding)(workspaceId, {
+        orgId: redeemed.orgId,
+        projectId: redeemed.projectId,
+        key: redeemed.key,
+        url: cfg.mcpUrl,
+        prefix: redeemed.prefix,
+        orgName: redeemed.orgName,
+        boundPath: cwd,
+        createdAt: Date.now(),
+    });
+    (deps.marker ?? installMarker)({ workspaceId, scope: "local", launcher });
+    // RTSC-532 — name the PATH, not "this folder". A binding is folder → project, and
+    // until this line said which folder, a wrong one was undetectable: the agent still
+    // calls in, so the Dash shows success while the folder she actually works in has no
+    // Retasc tools. Her agent relays this sentence to her, so it is also the last chance
+    // to notice.
+    console.log(`✓ ${clean(cwd)} is connected to ${clean(redeemed.orgName)} / ${clean(redeemed.prefix)}.`);
+    // NOT gated on isInteractive(), unlike the interactive path's copy of this line. There
+    // is never a TTY here, and this is the one instruction the agent has to pass on — the
+    // Dash waits on a tool call that cannot happen until the restart does (RTSC-496).
+    console.log(`\n${NEXT_STEP}`);
+}
 /**
  * What to do with a workspace that is now set up.
  *

package/dist/commands/join.js

@@ -223,8 +223,9 @@ export async function joinAction(link, opts) {
             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.
+            // `createProject` is `requireOwnerOrAdmin`, and an invite only ever grants `member`
+            // (admin is granted by `setMemberRole` after joining, never by a bearer code —
+            // RTSC-561). Offering "+ create new" here would be offering a refusal as a choice.
             canCreateProject: false,
         });
     }

package/dist/index.js

@@ -5,7 +5,7 @@ import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./c
 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 { bindAction, setupFromToken } from "./commands/bind.js";
 import { joinAction } from "./commands/join.js";
 import { identityAction } from "./commands/identity.js";
 import { importAction } from "./commands/import.js";
@@ -183,7 +183,22 @@ program
     // is present; this is how a scripted run, or a developer whose own agent runs setup,
     // says no up front instead of being installed onto.
     .option("--no-install", "Don't install `retasc` on this machine; wire the pinned npx launcher instead")
+    // RTSC-495 — the agent's door. Everything this command normally asks was already
+    // answered in the Dash, so the token stands in for all of it and nothing is prompted.
+    .option("--setup <token>", "Complete setup from a Dash setup code — no sign-in, no prompts")
     .action(async (opts) => {
+    // BEFORE requireLogin: the whole point is a machine that has never signed in. The
+    // token is the authorization, and asking for a session here would refuse every
+    // caller this flag exists for.
+    //
+    // `!== undefined`, not truthiness: `--setup ""` is a stated intent to use a setup
+    // code, and it must fail as a bad code. Falling through to the interactive path
+    // would answer it with "Not signed in", which is the one diagnosis that sends the
+    // reader looking in exactly the wrong place.
+    if (opts.setup !== undefined) {
+        await setupFromToken(opts.setup, opts).catch(fail);
+        return;
+    }
     requireLogin();
     await bindAction(opts).catch(fail);
 });
@@ -196,7 +211,7 @@ program
 });
 program
     .command("billing")
-    .description("Show the org's billing: subscription, what's owed now, and the charge + on-chain payment history across every payment link ever used (owner only).")
+    .description("Show the org's billing: subscription, what's owed now, and the charge + on-chain payment history across every payment link ever used (owner or admin).")
     .option("--org-id <id>", "Which org (defaults to your only one).")
     .option("--json", "Emit the raw payload instead of the summary.")
     .action(async (opts) => {
@@ -341,7 +356,7 @@ key
 const members = program.command("members").description("Invite people to an org and manage invites.");
 members
     .command("invite")
-    .description("Mint a single-use invite code for an org (owner only). Shown once.")
+    .description("Mint a single-use invite code for an org (owner or admin). Shown once.")
     .requiredOption("--org-id <id>")
     .option("--expires-days <n>", "Days until the code expires (1–30, default 7)", (v) => parseInt(v, 10))
     .action(async (opts) => {
@@ -362,7 +377,7 @@ members
 });
 members
     .command("list")
-    .description("List an org's invites and their status (owner only).")
+    .description("List an org's invites and their status (owner or admin).")
     .requiredOption("--org-id <id>")
     .option("--json", "Emit the raw payload instead of the table.")
     .action(async (opts) => {
@@ -377,7 +392,7 @@ members
 });
 members
     .command("revoke")
-    .description("Revoke an unused invite (owner only).")
+    .description("Revoke an unused invite (owner or admin).")
     .requiredOption("--invite-id <id>")
     .action(async (opts) => {
     requireLogin();

package/package.json

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