@retasc/cli 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -6,6 +6,62 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.16.0 (2026-08-02)
+
+- **RTSC-526** — `retasc import` catches up with the Dash on four things.
+
+  **It warns before a second import.** Re-importing does not duplicate anything, but it
+  does re-sync: status, labels, title and body are replaced with whatever the source says
+  now. Import from Jira, spend two weeks moving issues along in Retasc, re-import to pick up
+  new tickets, and those two weeks of changes snap back. You now get told, with the date of
+  the last import, before the confirmation.
+
+  **The run shows progress**, as a bar that fills while it works, rather than a silent wait
+  that looks like it has hung. The run is server-side, so pressing Ctrl-C out of boredom
+  never stopped it anyway.
+
+  **The column list is grouped** under your own tool's sections (Not started, Active, Done,
+  Closed) instead of arriving flat. On a twenty-column board that is the difference between
+  scannable and a wall.
+
+  **Columns that were not mapped are named.** If a column appears between the moment you set
+  the mapping and the moment the import runs, its issues land in `todo`. They used to show
+  as a number; now they are listed, with what to do about 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.

package/dist/api.js

@@ -28,6 +28,18 @@ 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"),
+    // RTSC-526: `latestImport` is LIVE progress and is swept after 24h; `importHistory` is
+    // permanent and per source, so it is the only thing that can answer "has this org
+    // imported from X before?" once the progress row is gone.
+    latestImport: makeFunctionReference("import:latestImport"),
+    importHistory: makeFunctionReference("import:importHistory"),
     claimableGhosts: makeFunctionReference("ghosts:claimableGhosts"),
     claimGhost: makeFunctionReference("ghosts:claimGhost"),
     dismissGhostPrompt: makeFunctionReference("ghosts:dismissGhostPrompt"),
@@ -159,6 +171,13 @@ 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)),
+    latestImport: (args) => withAuth(() => client().query(fns.latestImport, args)),
+    importHistory: (args) => withAuth(() => client().query(fns.importHistory, 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/import.js

@@ -0,0 +1,369 @@
+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"];
+/**
+ * The source's own section names, so the list reads as the shape the human already knows
+ * from their tool. Mirrors `GROUP_LABEL` in `dash/src/lib/statusMapping.ts` (RTSC-436).
+ */
+const GROUP_LABEL = {
+    not_started: "Not started",
+    active: "Active",
+    done: "Done",
+    closed: "Closed",
+};
+/** Section order, matching the Dash. */
+const GROUP_ORDER = ["not_started", "active", "done", "closed"];
+/**
+ * What to say before a SECOND import into the same org (RTSC-526).
+ *
+ * Not a formality. `convex/importWrite.ts` upserts by `sourceIssueId` and patches the match,
+ * so a re-import does not duplicate — the identifier and number survive even a rename — but
+ * it DOES replace status, labels, title and body with whatever the source says now. Two
+ * weeks of moving issues along in Retasc snap back to the source's version.
+ *
+ * Read from `importHistory`, NOT `latestImport`. The latter is live progress and is swept
+ * after 24h, so gating on it means the warning stops firing for exactly the person most at
+ * risk: the one who imported last week and has been working in Retasc since.
+ *
+ * Null when this source has never been imported, so a first run says nothing.
+ */
+export function reimportWarning(history, source, label) {
+    const prior = history.find((h) => h.source === source);
+    if (!prior)
+        return null;
+    const when = prior.lastImportedAt
+        ? ` (last on ${new Date(prior.lastImportedAt).toISOString().slice(0, 10)})`
+        : "";
+    return (`\n! You've imported from ${clean(label)} into this org before${when}.\n` +
+        `  Re-importing re-syncs those issues, so any edits you made in Retasc to them\n` +
+        `  (status, labels, and so on) will be replaced by ${clean(label)}'s version.`);
+}
+/**
+ * The summary after a run, with the one field that needs words rather than a number.
+ *
+ * `unmappedStatuses` holds columns that appeared BETWEEN the mapping being set and the run;
+ * their issues landed in `todo`. As a count it is a silent slice of work in the wrong place,
+ * which is the whole reason the Dash names them.
+ */
+export function summaryLines(summary, label) {
+    const out = [];
+    const unmapped = [];
+    for (const [k, v] of Object.entries(summary ?? {})) {
+        if (k === "unmappedStatuses") {
+            if (Array.isArray(v))
+                unmapped.push(...v.map(String));
+            continue;
+        }
+        if (typeof v === "number" || typeof v === "string")
+            out.push(`  ${k.padEnd(20)}${clean(v)}`);
+    }
+    if (unmapped.length) {
+        out.push("", `! These ${clean(label)} statuses weren't mapped, so their issues landed in todo:`, `    ${unmapped.map((u) => clean(u)).join(", ")}`, "  They appeared after you set the mapping. Re-import to place them.");
+    }
+    return out;
+}
+// --- the progress bar --------------------------------------------------------
+/** Lime, in 256-colour. Bright enough to read on both a light and a dark terminal. */
+const LIME = "\x1b[38;5;154m";
+const DIM = "\x1b[38;5;240m";
+const RESET = "\x1b[0m";
+/**
+ * One line of progress bar.
+ *
+ * Pure, so the shape can be tested without a terminal. Colour is opt-out via `color`, which
+ * the caller ties to a TTY and to `NO_COLOR` — a bar full of escape sequences in a piped log
+ * is worse than no bar.
+ */
+export function progressBar(done, total, width = 24, color = true) {
+    const known = typeof total === "number" && total > 0;
+    // Clamp: a server that reports more done than total must not print a bar wider than the
+    // terminal, or a negative one.
+    const frac = known ? Math.max(0, Math.min(1, done / total)) : 0;
+    const filled = Math.round(frac * width);
+    const bar = known
+        ? `${color ? LIME : ""}${"█".repeat(filled)}${color ? DIM : ""}${"░".repeat(width - filled)}${color ? RESET : ""}`
+        : `${color ? DIM : ""}${"░".repeat(width)}${color ? RESET : ""}`;
+    const count = known ? `${Math.round(frac * 100)}%  ${done}/${total}` : `${done} so far`;
+    return `  ${bar}  ${count}`;
+}
+/**
+ * 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.");
+    // Grouped under the source's own section names, in the source's own order within each
+    // (RTSC-436/526). On a twenty-column Jira board a flat list is a wall; the sections are
+    // the shape the human already has in front of them in their tool.
+    const ordered = GROUP_ORDER.flatMap((g) => {
+        const rows = statuses.filter((s) => s.group === g).sort((a, b) => a.order - b.order);
+        return rows.map((s, i) => ({ s, heading: i === 0 ? GROUP_LABEL[g] : null }));
+    });
+    for (const { s, heading } of ordered) {
+        if (heading)
+            console.log(`\n  ${heading}`);
+        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 };
+}
+/**
+ * Poll `latestImport` and redraw one line until told to stop. Returns the stopper.
+ *
+ * One LINE, rewritten in place, rather than a scrolling log: the interesting number is the
+ * current one. Silent without a TTY — a progress bar in a piped log is noise, and the
+ * escape codes would end up in whatever reads it.
+ *
+ * Every failure here is swallowed. This is decoration on top of a run that is happening
+ * server-side regardless; a hiccup in the progress query must never be what surfaces as an
+ * import failure.
+ */
+function followProgress(orgId) {
+    const tty = Boolean(stdout.isTTY) && !process.env.NO_COLOR;
+    if (!stdout.isTTY)
+        return () => { };
+    let stopped = false;
+    const tick = async () => {
+        while (!stopped) {
+            try {
+                const p = (await api.latestImport({ orgId }));
+                if (!stopped && p && p.status === "running") {
+                    stdout.write(`\r\x1b[2K${progressBar(p.issuesDone ?? 0, p.issuesTotal ?? null, 24, tty)}`);
+                }
+            }
+            catch {
+                /* progress is decoration; never let it speak for the run */
+            }
+            await new Promise((r) => setTimeout(r, 1200));
+        }
+    };
+    void tick();
+    return () => {
+        stopped = true;
+        // Clear the line so the summary does not land on top of a half-drawn bar.
+        stdout.write("\r\x1b[2K");
+    };
+}
+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.`);
+    // RTSC-526 — the second run is the dangerous one, and the terminal is where a command
+    // gets re-run casually. Read from `importHistory` (permanent) rather than `latestImport`
+    // (live progress, swept after 24h), so this still fires for someone who imported last
+    // week and has been working in Retasc since — the person with the most to lose.
+    const history = (await api.importHistory({ orgId: orgId }));
+    const warning = reimportWarning(history, src.source, src.label);
+    if (warning)
+        console.log(warning);
+    if (!opts.yes && !(await confirm("This can't be undone. Go ahead?"))) {
+        console.log("Nothing imported.");
+        return;
+    }
+    // --- run -------------------------------------------------------------------
+    console.log("\nImporting…\n");
+    // RTSC-526 — show it moving. The run is server-side and can take minutes on a big
+    // project; a silent wait is exactly when someone decides it has hung and presses Ctrl-C,
+    // which is the worst moment to do it because the server keeps going regardless.
+    const stop = followProgress(orgId);
+    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) {
+        stop();
+        // 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;
+    }
+    stop();
+    console.log("\n✓ Imported.");
+    for (const line of summaryLines(res.summary, src.label)) {
+        console.log(line);
+    }
+    // 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/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";
@@ -429,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.14.0",
+  "version": "1.16.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": {