@retasc/cli 1.13.1 → 1.15.0

package/CHANGELOG.md

@@ -6,6 +6,73 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.15.0 (2026-08-02)
+
+- **RTSC-524** — new command: `retasc import`. Bring a Linear, Jira, Asana, ClickUp or
+  Shortcut project across without opening a browser.
+
+  This was the last thing the terminal could not do. Everything else — sign in, make or join
+  an org, create a project, wire the folder, pull work — already worked end to end, but
+  importing meant stopping and finishing in the Dash.
+
+  ```
+  retasc import
+  retasc import --source jira --org-id …
+  ```
+
+  It walks you through the source, your credentials, which team or project to take, and then
+  **what each of your columns means**. That last part is the point, and it is asked rather
+  than guessed: a tool lets its users name their own columns, so the only honest way to know
+  what one means is to ask you. Pressing Enter accepts a suggestion derived from the
+  column's *type* in your tool, never its name — a column called "Rejected" that is really
+  an in-progress lane maps to `doing`, not `canceled`.
+
+  A column mapped to `review` needs a named reviewer, chosen per column, because two
+  "awaiting acceptance" columns can belong to different people. Columns holding work nobody
+  has started cannot be mapped to `review` at all, and the CLI says why rather than letting
+  the server refuse it later.
+
+  **Your source token is never an argument.** There is no `--token`, because anything passed
+  that way lands in shell history and in `ps` output. Secrets are typed with echo off, or
+  taken from `RETASC_IMPORT_<FIELD>` for scripted runs.
+
+  The run is confirmed before anything is written, and afterwards you are offered the
+  imported identity the migration just created for you, through the same prompt
+  `retasc join` uses.
+
+## 1.14.0 (2026-08-02)
+
+- **RTSC-523** — setup asks before installing anything on your machine.
+
+  `retasc bind` and `retasc join` are one command you paste and answer, and somewhere in the
+  middle they ran `npm install -g @retasc/cli`. It said so, but it never asked. That is the
+  only step in a folder-scoped command that changes the machine rather than the folder, and
+  a shared npm prefix is exactly what plenty of developers keep clean.
+
+  ```
+  Install the retasc command on this machine?
+
+    1) Yes, globally          A `retasc` command you can use anywhere.
+                              Best if you'll use Retasc in more than one project.
+    2) No, run it on demand   Nothing is installed. Your agent fetches it when it
+                              starts, which adds a couple of seconds and needs a
+                              network connection.
+  ```
+
+  Both answers leave the folder bound identically. Option 2 is not a per-project install:
+  nothing is written to the folder, so it needs no `package.json` and cannot fail for want
+  of an npm project. Your answer is remembered, because it is a question about the machine
+  and the machine has not changed by the time you bind a second folder.
+
+  You are only asked when it would actually happen. If `retasc` already works, there is
+  nothing to decide and nothing is said.
+
+  **Without a TTY it installs, exactly as before.** That is deliberate rather than a
+  leftover: when an agent runs setup on someone's behalf, that person never types `retasc`,
+  but their agent starts the MCP server every session, and the on-demand route would cost
+  them seconds and a network dependency every single time. `--no-install` on `bind` and
+  `join` declines without a TTY, for a developer whose own agent is doing the setup.
+
 ## 1.13.1 (2026-08-02)
 
 - **RTSC-522** — the changelog is public, and five releases that were never written down now

package/dist/api.js

@@ -28,6 +28,13 @@ const fns = {
     // Imported-identity claim (RTSC-433/473), wired for `join` by RTSC-492 and shared with
     // RTSC-477's standalone `retasc identity`. Member-gated already — nothing was widened
     // server-side for the CLI, and nothing should be.
+    // RTSC-524 — the import surface. Owner-gated on the server, authenticated by the same
+    // user session every other management call uses.
+    listImportSources: makeFunctionReference("import:listImportSources"),
+    listImportTargets: makeFunctionReference("import:listImportTargets"),
+    listImportStatuses: makeFunctionReference("import:listImportStatuses"),
+    listReviewCandidates: makeFunctionReference("import:listReviewCandidates"),
+    runImport: makeFunctionReference("import:runImport"),
     claimableGhosts: makeFunctionReference("ghosts:claimableGhosts"),
     claimGhost: makeFunctionReference("ghosts:claimGhost"),
     dismissGhostPrompt: makeFunctionReference("ghosts:dismissGhostPrompt"),
@@ -159,6 +166,11 @@ export const api = {
     billingStatus: (args) => withAuth(() => client().query(fns.billingStatus, args)),
     chargeHistory: (args) => withAuth(() => client().query(fns.chargeHistory, args)),
     orgPayments: (args) => withAuth(() => client().action(fns.orgPayments, args)),
+    listImportSources: () => withAuth(() => client().query(fns.listImportSources, {})),
+    listImportTargets: (args) => withAuth(() => client().action(fns.listImportTargets, args)),
+    listImportStatuses: (args) => withAuth(() => client().action(fns.listImportStatuses, args)),
+    listReviewCandidates: (args) => withAuth(() => client().query(fns.listReviewCandidates, args)),
+    runImport: (args) => withAuth(() => client().action(fns.runImport, 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/bind.js

@@ -1,10 +1,10 @@
 import { api, cliError } from "../api.js";
 import { deviceLogin } from "../auth.js";
-import { loadConfig } from "../config.js";
+import { loadConfig, patchConfig } from "../config.js";
 import { installMarker } from "./mcp.js";
 import { readLocalBinding, resolveBinding } from "../lib/binding.js";
 import { getBinding, setBinding, newWorkspaceId } from "../lib/keystore.js";
-import { resolveLauncher, launcherNote, selfCommand } from "../lib/launcher.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 { VERSION } from "../version.js";
@@ -151,6 +151,63 @@ export async function rebindGuard(args) {
     }
     return { proceed: false, existing };
 }
+/**
+ * May we install `retasc` on this machine? (RTSC-523)
+ *
+ * Asked only when it would actually happen. `runsOk` is the same probe
+ * `resolveLauncher` opens with, so if `retasc` already works there is nothing to decide and
+ * a question would have exactly one possible outcome.
+ *
+ * A DEFAULT is right here, unlike the sign-in door (RTSC-508), which deliberately has none.
+ * A wrong answer costs a couple of seconds per agent start, not a second identity that
+ * cannot be merged back. The two questions look alike and are not.
+ *
+ * NO TTY ⇒ install, silently, exactly as before. That is not laziness about the default: it
+ * is the right answer for the person it affects most. The non-technical member of RTSC-497
+ * never opens a terminal — her AGENT runs this (RTSC-495/496), with no TTY. She will never
+ * type `retasc` herself, but her agent spawns the MCP server on every start, and the npx
+ * route would cost her seconds and a network dependency every single time, forever.
+ * `--no-install` exists for the developer who wants to decline without a TTY.
+ */
+export async function chooseInstall(
+/** `--no-install` ⇒ false. Undefined means "not stated". */
+flag, deps = {}) {
+    if (flag === false)
+        return false;
+    const onPath = deps.onPath ?? (() => runsOk("retasc") !== null);
+    // Nothing to install, so nothing to ask.
+    if (onPath())
+        return true;
+    const remembered = (deps.remembered ?? (() => loadConfig().globalInstall))();
+    if (remembered !== undefined)
+        return remembered;
+    const interactive = deps.interactive ?? isInteractive;
+    if (!interactive())
+        return true;
+    console.log("\nInstall the retasc command on this machine?");
+    console.log("  1) Yes, globally          A `retasc` command you can use anywhere.");
+    console.log("                            Best if you'll use Retasc in more than one project.");
+    console.log("  2) No, run it on demand   Nothing is installed. Your agent fetches it when it");
+    console.log("                            starts, which adds a couple of seconds and needs a");
+    console.log("                            network connection.");
+    const askFn = deps.askFn ?? ask;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const a = await askFn("Choose a number [1]: ");
+        // Either answer leaves this folder bound identically — only the machine differs — so
+        // an empty answer taking the default is safe here in a way it is not for the door.
+        if (a === "" || a === "1")
+            return remember(true);
+        if (a === "2")
+            return remember(false);
+        console.log("Please enter 1 or 2.");
+    }
+    throw new Error("no valid choice — aborting");
+}
+/** Record the answer, so binding a second folder does not re-ask about the same machine. */
+function remember(globalInstall) {
+    patchConfig({ globalInstall });
+    return globalInstall;
+}
 /**
  * Everything from "which project" to a working folder: pick the project, make `retasc`
  * durable, mint a key for that (org, project), write the binding, and wire the marker.
@@ -237,7 +294,15 @@ export async function completeWorkspaceSetup(args) {
     // name one proved to run on this machine. Resolved (and announced) here so the install
     // can't land after a key exists, and so every later message knows what to tell the user
     // to type.
-    const launcher = resolveLauncher({ version: VERSION });
+    //
+    // RTSC-523 — and ASK first, because this is the one step in a folder-scoped command that
+    // changes the MACHINE. It used to just run `npm install -g`. The project already holds
+    // the opposite position everywhere else: `resolveLauncher` leaves a working `retasc`
+    // alone ("no surprise installs for someone who already manages their own"), and RTSC-520
+    // decided an update must ask. The first command a new developer runs was the one place
+    // we did it anyway.
+    const install = await chooseInstall(opts.install);
+    const launcher = resolveLauncher({ version: VERSION, install });
     const note = launcherNote(launcher);
     if (note)
         console.log(note);

package/dist/commands/import.js

@@ -0,0 +1,226 @@
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { api, cliError, formatError } from "../api.js";
+import { clean } from "../lib/text.js";
+import { ask, confirm, isInteractive } from "../lib/prompt.js";
+import { pickExisting } from "./bind.js";
+/** The five destinations a column can be mapped to. Mirrors `MappedStatus`. */
+const MAPPED = ["todo", "doing", "review", "done", "canceled"];
+/**
+ * May this column be mapped to `review`?
+ *
+ * Mirrors `reviewAllowedForGroup` in `convex/lib/importAdapter.ts`, and the reasoning is
+ * the server's: `review` means the work is FINISHED and waiting for someone to accept it,
+ * and it is non-terminal, so it keeps blocking dependents. Routing a not-yet-started column
+ * there manufactures review issues with nothing to review, each jamming whatever depends on
+ * it. Offering an option the server will reject is worse than not offering it.
+ */
+export function reviewAllowed(group) {
+    return group === "active" || group === "done";
+}
+/** Read a secret without echoing it, so a token never lands in scrollback. */
+async function askSecret(question) {
+    if (!stdin.isTTY)
+        return await ask(question);
+    const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+    // readline has no built-in masking, so suppress the echo ourselves and restore it in
+    // `finally` — a thrown error mid-prompt must not leave the terminal silent.
+    const out = stdout;
+    const real = out.write.bind(out);
+    try {
+        const answer = rl.question(question);
+        out.write = (chunk) => (chunk.includes("\n") ? real(chunk) : true);
+        const value = await answer;
+        return value.trim();
+    }
+    finally {
+        out.write = real;
+        rl.close();
+        real("\n");
+    }
+}
+/**
+ * Collect the source's credentials.
+ *
+ * NEVER from an argument. A token passed as `--token …` lands in shell history, in `ps`
+ * output, and in any transcript of the session. Secret fields are read with echo off; an
+ * env var (`RETASC_IMPORT_<KEY>`) covers the scripted case without either problem.
+ */
+async function collectAuth(src) {
+    const auth = {};
+    for (const f of src.authFields) {
+        const envKey = `RETASC_IMPORT_${f.key.toUpperCase()}`;
+        const fromEnv = process.env[envKey];
+        if (fromEnv) {
+            console.log(`  ${clean(f.label)}: taken from ${envKey}`);
+            auth[f.key] = fromEnv;
+            continue;
+        }
+        if (!isInteractive()) {
+            cliError("MISSING_AUTH", `${clean(src.label)} needs ${clean(f.label)}, and there is no terminal to ask on.`, `Set ${envKey} and run again.`);
+        }
+        if (f.hint)
+            console.log(`  ${clean(f.hint)}`);
+        const value = f.secret
+            ? await askSecret(`  ${clean(f.label)} (hidden): `)
+            : await ask(`  ${clean(f.label)}: `);
+        if (!value)
+            cliError("MISSING_AUTH", `${clean(f.label)} is required.`);
+        auth[f.key] = value;
+    }
+    return auth;
+}
+/**
+ * Walk every column and record what it means. The heart of the command.
+ *
+ * Each row arrives with a `suggested` value derived server-side from the source's own
+ * STRUCTURAL type, never from the column's name, so pressing Enter through the list is a
+ * defensible mapping rather than a guess. This is a review-and-correct surface, exactly as
+ * the Dash panel is.
+ */
+export async function mapStatuses(statuses, reviewers, askFn) {
+    const statusMap = {};
+    const reviewerByStatus = {};
+    console.log(`\nWhat does each column mean? ${statuses.length} to confirm.\n` +
+        "  Enter keeps the suggestion. It comes from the column's type in your tool, not its name.");
+    // The source's own order, so the list reads the way it does in the tool they know.
+    for (const s of [...statuses].sort((a, b) => a.order - b.order)) {
+        const allowed = MAPPED.filter((m) => m !== "review" || (reviewAllowed(s.group) && reviewers.length > 0));
+        const suggested = allowed.includes(s.suggested)
+            ? s.suggested
+            : "todo";
+        for (let attempt = 0;; attempt++) {
+            const answer = (await askFn(`\n  ${clean(s.name)}  [${suggested}]  (${allowed.join(" / ")}): `)).trim().toLowerCase();
+            const choice = answer === "" ? suggested : answer;
+            if (allowed.includes(choice)) {
+                statusMap[s.id] = choice;
+                break;
+            }
+            if (choice === "review" && !reviewAllowed(s.group)) {
+                // Say WHY, rather than repeating the list. The server would reject it anyway.
+                console.log("    Not for this column: review means finished and awaiting acceptance,");
+                console.log("    and this one holds work nobody has started.");
+            }
+            else if (choice === "review") {
+                console.log("    No one in this org can be a reviewer yet, so review isn't available.");
+            }
+            else {
+                console.log(`    Pick one of: ${allowed.join(", ")}`);
+            }
+            if (attempt >= 2)
+                throw new Error("no valid choice — aborting");
+        }
+        // A review column needs a named reviewer, per column rather than per run: two
+        // "awaiting acceptance" columns can legitimately belong to different people.
+        if (statusMap[s.id] === "review") {
+            const who = await pickExisting(`    Who reviews "${clean(s.name)}"?`, reviewers, (m) => clean(m.name), askFn);
+            reviewerByStatus[s.id] = who.id;
+        }
+    }
+    return { statusMap, reviewerByStatus };
+}
+export async function importAction(opts) {
+    if (!isInteractive() && !opts.yes) {
+        cliError("NEEDS_TERMINAL", "Importing asks what each of your columns means, so it needs a terminal.", "Run it interactively, or use the Dash.");
+    }
+    // --- which org ------------------------------------------------------------
+    const me = (await api.me());
+    const orgs = me.orgs ?? [];
+    let orgId = opts.orgId;
+    if (!orgId) {
+        if (orgs.length === 0)
+            cliError("NO_ORG", "You're not a member of any org yet.");
+        else if (orgs.length === 1)
+            orgId = orgs[0].id;
+        else {
+            const chosen = await pickExisting("Import into which org", orgs, (o) => `${clean(o.name)}${o.slug ? ` (${clean(o.slug)})` : ""}`);
+            orgId = chosen.id;
+        }
+    }
+    const orgLabel = clean(orgs.find((o) => o.id === orgId)?.name ?? "this org");
+    // --- which tracker --------------------------------------------------------
+    const sources = (await api.listImportSources());
+    if (!sources.length)
+        cliError("NO_SOURCES", "No import sources are available.");
+    const src = opts.source
+        ? sources.find((s) => s.source === opts.source) ??
+            cliError("UNKNOWN_SOURCE", `There's no import source called "${clean(opts.source)}".`, `Try one of: ${sources.map((s) => s.source).join(", ")}`)
+        : await pickExisting("Bring work across from", sources, (s) => clean(s.label));
+    // --- credentials ----------------------------------------------------------
+    console.log(`\nConnect to ${clean(src.label)}:`);
+    const auth = await collectAuth(src);
+    // --- which team/project/workspace -----------------------------------------
+    const { targets } = (await api.listImportTargets({ orgId: orgId, source: src.source, auth }));
+    if (!targets.length) {
+        cliError("NO_TARGETS", `That ${clean(src.label)} account has no ${clean(src.targetNoun)} we can import.`, "Check the credentials belong to the right account.");
+    }
+    const target = targets.length === 1
+        ? targets[0]
+        : await pickExisting(`Which ${clean(src.targetNoun)}`, targets, (t) => `${clean(t.name)} (${clean(t.key)})`);
+    // --- what each column means ------------------------------------------------
+    let statusMap;
+    let reviewerByStatus;
+    if (src.supportsStatusMapping) {
+        const { statuses } = (await api.listImportStatuses({
+            orgId: orgId,
+            source: src.source,
+            auth,
+            targetRef: target.id,
+        }));
+        if (statuses.length) {
+            const reviewers = (await api.listReviewCandidates({ orgId: orgId }));
+            const mapped = await mapStatuses(statuses, reviewers, ask);
+            statusMap = mapped.statusMap;
+            reviewerByStatus = Object.keys(mapped.reviewerByStatus).length
+                ? mapped.reviewerByStatus
+                : undefined;
+        }
+    }
+    // --- confirm ---------------------------------------------------------------
+    // Named in full before anything is written. An import creates a project's worth of
+    // issues and mints a placeholder per source author, and there is no per-project delete —
+    // undoing a mistake means an org-level cleanup.
+    console.log(`\nAbout to import ${clean(target.name)} from ${clean(src.label)} into org ${orgLabel},\n` +
+        `as a new project. Issues, comments and their authors come across.`);
+    if (!opts.yes && !(await confirm("This can't be undone. Go ahead?"))) {
+        console.log("Nothing imported.");
+        return;
+    }
+    // --- run -------------------------------------------------------------------
+    console.log("\nImporting. This can take a few minutes on a big project…");
+    let res;
+    try {
+        res = (await api.runImport({
+            orgId: orgId,
+            source: src.source,
+            auth,
+            target: { id: target.id, key: target.key, name: target.name },
+            statusMap,
+            reviewerByStatus,
+        }));
+    }
+    catch (e) {
+        // The run is server-side, so a dead connection here does NOT mean a dead import.
+        // Saying "failed" would be a guess, and the wrong one sends someone re-importing on
+        // top of a run that is still writing.
+        const { code, message, hint } = formatError(e);
+        console.error(`\n✗ ${code ? `${code}: ` : ""}${message}`);
+        if (hint)
+            console.error(`  → ${hint}`);
+        console.error("  If this was a connection problem the import may still be running.");
+        console.error("  Check the Dash before running it again.");
+        throw e;
+    }
+    console.log("\n✓ Imported.");
+    for (const [k, v] of Object.entries(res.summary ?? {})) {
+        if (typeof v === "number" || typeof v === "string")
+            console.log(`  ${k.padEnd(18)}${clean(v)}`);
+    }
+    // The import just minted a placeholder for whoever authored that work, and the person
+    // who ran it is very often one of them. `identityLoop` is the same prompt `join` uses and
+    // is per-source since RTSC-507, so offering it here costs one round trip and saves them
+    // finding it later.
+    console.log("");
+    const { identityLoop } = await import("./join.js");
+    await identityLoop(orgId, {}, orgLabel);
+}

package/dist/config.js

@@ -61,6 +61,10 @@ export function loadConfig() {
         loginProvider: stored.loginProvider === "github" || stored.loginProvider === "google"
             ? stored.loginProvider
             : undefined,
+        // Same rule (RTSC-523): only a real boolean counts. Anything else reads as
+        // "never asked", so a mangled file leads to a question rather than to an
+        // install nobody agreed to.
+        globalInstall: typeof stored.globalInstall === "boolean" ? stored.globalInstall : undefined,
     };
 }
 /** Move a corrupt config aside to a unique sibling so a human can recover any

package/dist/index.js

@@ -8,6 +8,7 @@ import { claimAction } from "./commands/claim.js";
 import { bindAction } from "./commands/bind.js";
 import { joinAction } from "./commands/join.js";
 import { identityAction } from "./commands/identity.js";
+import { importAction } from "./commands/import.js";
 import { doctorAction } from "./commands/doctor.js";
 import { billingAction } from "./commands/billing.js";
 import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
@@ -178,6 +179,10 @@ program
     .option("--agent <name>", "Agent member name (default: auto)")
     .option("--runtime <runtime>", "Agent runtime", "claude-code")
     .option("-y, --yes", "Don't prompt to confirm replacing an existing binding")
+    // RTSC-523 — decline the global install without a TTY. `bind`/`join` ask when a human
+    // 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")
     .action(async (opts) => {
     requireLogin();
     await bindAction(opts).catch(fail);
@@ -400,6 +405,10 @@ program
     // RTSC-477 — name the way back. `--yes` skips the identity question and must never answer
     // it, so the flag that causes the gap is the right place to say how to close it.
     .option("-y, --yes", "Don't prompt to replace an existing binding, and skip the identity question (ask it later with `retasc identity`)")
+    // RTSC-523 — decline the global install without a TTY. `bind`/`join` ask when a human
+    // 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")
     .allowExcessArguments(false)
     .action(async (link, opts) => {
     await joinAction(link, opts).catch(fail);
@@ -421,6 +430,24 @@ program
     requireLogin();
     await identityAction({ orgId: opts.orgId }).catch(fail);
 });
+// RTSC-524 — bring another tracker across without leaving the terminal. The status
+// mapping is ASKED, never guessed: a source lets its users name their own columns, so the
+// only honest way to know what one means is the human running the import (the reasoning is
+// recorded in convex/lib/importAdapter.ts, which deleted the name-based heuristics after a
+// `Rejected` column imported live work as `canceled`, out of dispatch, silently).
+program
+    .command("import")
+    .description("Bring a Linear/Jira/Asana/ClickUp/Shortcut project across into a new Retasc project.")
+    .option("--org-id <id>", "Which org to import into (defaults to your only one).")
+    .option("--source <source>", "Skip the source picker: linear | jira | asana | clickup | shortcut")
+    // No `--token`: a credential passed as an argument lands in shell history and in `ps`.
+    // Secrets are read with echo off, or from RETASC_IMPORT_<FIELD>.
+    .option("-y, --yes", "Skip the final confirmation (the column mapping is still asked)")
+    .allowExcessArguments(false)
+    .action(async (opts) => {
+    requireLogin();
+    await importAction({ orgId: opts.orgId, source: opts.source, yes: opts.yes }).catch(fail);
+});
 // --- mcp wiring ------------------------------------------------------------
 const mcp = program.command("mcp").description("Wire the Retasc MCP server into your agent.");
 mcp

package/package.json

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