@retasc/cli 1.16.1 → 1.18.0

package/CHANGELOG.md

@@ -6,6 +6,57 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.18.0 (2026-08-02)
+
+- **RTSC-530** — setting up from scratch now asks where your work comes from, and imports it
+  in the same command.
+
+  `retasc bind` used to offer one thing at the project step: name a new project. So someone
+  arriving from Jira had to invent a project they didn't want, run `retasc import`
+  afterwards to get the one they did, and leave the empty one behind — and projects can't be
+  deleted individually.
+
+  ```
+  Where does your work come from?
+    1) Linear
+    2) Jira
+    3) Asana
+    4) ClickUp
+    5) Shortcut
+    6) Start from scratch   (name a project; your agents file into it)
+  ```
+
+  Pick a tracker and the import runs right there, then the folder binds to the project it
+  created. Pick "start from scratch" and it behaves exactly as before. This is the same fork
+  the Dash has always offered; importing isn't a separate errand, it's one of the ways a
+  first project comes into existence.
+
+  Only when the org has no projects — binding a second folder in an existing org is still
+  just picking from the list. Declining at the import confirmation falls back to naming a
+  project rather than abandoning setup: you still asked to bind the folder.
+
+## 1.17.0 (2026-08-02)
+
+- **RTSC-529** — the column mapping is a numbered picker, like every other prompt.
+
+  It was the only one that made you type a word. Picking an org, a project, a source, a
+  list, a reviewer, a sign-in door or whether to install globally are all numbered lists
+  reading `Choose a number` — and the reviewer picker appears two lines below this one, so a
+  single import taught two input styles within four lines of output.
+
+  ```
+    to do
+      1) todo   (suggested)
+      2) doing
+      3) done
+      4) canceled
+    Choose a number [1]:
+  ```
+
+  Enter still takes the suggestion, now marked in the list rather than described beside it.
+  Typing the word still works for anyone who has learned the vocabulary; it just isn't what
+  the prompt advertises.
+
 ## 1.16.1 (2026-08-02)
 
 - **RTSC-528** — two things the first real `retasc import` run turned up.

package/dist/commands/bind.js

@@ -208,6 +208,59 @@ function remember(globalInstall) {
     patchConfig({ globalInstall });
     return globalInstall;
 }
+/** Name and create a project by hand — the "start from scratch" ending. */
+async function nameAProject(orgId) {
+    const name = await ask("New project name: ");
+    const pfx = (await ask("Project prefix (e.g. ACME): ")).toUpperCase();
+    if (!name || !pfx)
+        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 };
+}
+/**
+ * "Where does your work come from?" — the first project, for an org that has none.
+ *
+ * RTSC-530. Mirrors the Dash's `ProjectSetup`: the trackers first, then "start from
+ * scratch" as the last row rather than a footer escape hatch. The Dash records why it is a
+ * ROW — as a button it read as a way out of the five real options, which is the wrong
+ * framing when most people arriving have work to bring.
+ *
+ * The import flow is CALLED, not re-implemented (`runImportFlow`). A second copy of the
+ * auth prompt, target picker and column mapping is how the two drift, and the mapping is
+ * the part that decides where a whole backlog lands.
+ *
+ * Imported dynamically: `commands/import.ts` imports `pickExisting` from here, so a static
+ * import would close a cycle. Same pattern `join` uses for `identityLoop`.
+ */
+async function firstProject(orgId, orgLabel) {
+    let sources = [];
+    try {
+        sources = (await api.listImportSources());
+    }
+    catch {
+        // Never block setting up a workspace on the importer list being reachable. A person
+        // who just wants an empty project should not be stopped by a source catalogue.
+        sources = [];
+    }
+    if (!sources.length)
+        return nameAProject(orgId);
+    const SCRATCH = { source: "", label: "Start from scratch   (name a project; your agents file into it)" };
+    const picked = await pickExisting("Where does your work come from?", [...sources, SCRATCH], (x) => clean(x.label));
+    // Compared by REFERENCE, so a source that ever arrives with an empty id cannot be
+    // mistaken for the scratch row.
+    if (picked === SCRATCH)
+        return nameAProject(orgId);
+    const { runImportFlow } = await import("./import.js");
+    const done = await runImportFlow({ orgId, orgLabel, source: picked.source });
+    // Declining at the import confirmation is not an error, and must not abandon setup —
+    // they still asked to bind this folder. Fall back to the other branch of the same fork.
+    if (!done) {
+        console.log("\nNo import. Let's make an empty project instead.");
+        return nameAProject(orgId);
+    }
+    return done;
+}
 /**
  * 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.
@@ -264,6 +317,19 @@ export async function completeWorkspaceSetup(args) {
                 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(", ")}`);
             }
         }
+        else if (isInteractive() && list.length === 0) {
+            // RTSC-530 — the FROM-SCRATCH case, and the Dash's question rather than ours.
+            //
+            // `Onboarding.tsx` asks "Where does your work come from?" and offers the five
+            // trackers AND "start from scratch" as one fork, because importing is not a separate
+            // act: it is one of the ways a first project comes into existence. The CLI used to
+            // ask only "New project name:", so someone arriving from Jira had to invent a project
+            // they did not want, run `retasc import` afterwards, and leave an empty one behind
+            // that cannot be deleted (org-granularity delete only).
+            const made = await firstProject(orgId, org);
+            projectId = made.projectId;
+            prefix = made.prefix;
+        }
         else if (isInteractive()) {
             const chosen = await pick("Select a project", list, (p) => `${clean(p.prefix)} — ${clean(p.name)}`);
             if (chosen) {
@@ -271,14 +337,9 @@ export async function completeWorkspaceSetup(args) {
                 prefix = chosen.prefix;
             }
             else {
-                const name = await ask("New project name: ");
-                const pfx = (await ask("Project prefix (e.g. ACME): ")).toUpperCase();
-                if (!name || !pfx)
-                    throw new Error("project name and prefix required");
-                const p = (await api.createProject({ orgId, name, prefix: pfx }));
-                projectId = p.projectId;
-                prefix = p.prefix;
-                console.log(`✓ Created project ${p.prefix}.`);
+                const made = await nameAProject(orgId);
+                projectId = made.projectId;
+                prefix = made.prefix;
             }
         }
         else if (list.length === 1) {

package/dist/commands/import.js

@@ -180,7 +180,7 @@ export async function mapStatuses(statuses, reviewers, askFn) {
     const statusMap = {};
     const reviewerByStatus = {};
     console.log(`\nWhat does each column mean? ${statuses.length} to confirm.\n` +
-        "  Press Enter to keep the suggested answer, or type a different one.\n" +
+        "  Press Enter to take the suggested answer, or pick another number.\n" +
         "  The suggestion 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
@@ -196,36 +196,44 @@ export async function mapStatuses(statuses, reviewers, askFn) {
         const suggested = allowed.includes(s.suggested)
             ? s.suggested
             : "todo";
+        // RTSC-529 — NUMBERED, like every other prompt in the CLI.
+        //
+        // This was the only one that asked you to type a word. Org, project, source, list,
+        // reviewer, sign-in door (RTSC-508) and install choice (RTSC-523) are all numbered
+        // pickers reading "Choose a number" — and the reviewer picker appears two lines below
+        // THIS one, so a single run taught two input styles within four lines of output.
+        //
+        // RTSC-528 tried to fix that by making the typing instruction explicit. That treated
+        // the symptom: a prompt that has to teach you its own input method is usually the
+        // wrong input method.
+        //
+        // The default is marked in the list rather than described outside it, and the words
+        // are still accepted — someone ten columns in knows the vocabulary, and typing `doing`
+        // beats re-reading a list. That is a shortcut, not the advertised path, so it is not
+        // in the instruction.
+        console.log(`\n  ${clean(s.name)}`);
+        allowed.forEach((m, i) => console.log(`    ${i + 1}) ${m}${m === suggested ? "   (suggested)" : ""}`));
+        const defaultSlot = allowed.indexOf(suggested) + 1;
         for (let attempt = 0;; attempt++) {
-            // RTSC-528 — the prompt has to name the ACTION. It used to read
-            //   `to do  [todo]  (todo / doing / done / canceled):`
-            // where nothing is a verb: the bracket is the default and the parenthesis is a bare
-            // word list, so the first person to run it had to guess that you type one of them.
-            // The reviewer picker two lines below says "Choose a number" and is unambiguous,
-            // which made the contrast worse.
-            //
-            // The suggestion is also removed from the alternatives — it is already what Enter
-            // does, and listing it again is what made the line read as four equal options with a
-            // mysterious bracket in front.
-            const others = allowed.filter((m) => m !== suggested);
-            const answer = (await askFn(`\n  ${clean(s.name)}\n` +
-                `    Enter to keep ${suggested}, or type: ${others.join(", ")}\n` +
-                `  > `)).trim().toLowerCase();
-            const choice = answer === "" ? suggested : answer;
-            if (allowed.includes(choice)) {
+            const answer = (await askFn(`  Choose a number [${defaultSlot}]: `)).trim().toLowerCase();
+            // Enter takes the suggestion; a digit picks a row; a word still works.
+            const byNumber = /^\d+$/.test(answer) ? allowed[Number(answer) - 1] : undefined;
+            const choice = answer === "" ? suggested : (byNumber ?? answer);
+            if (choice && 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.
+            // Say WHY when the answer names something real but not permitted here. The server
+            // would reject it anyway, and repeating the list explains nothing.
+            if (answer === "review" && !reviewAllowed(s.group)) {
                 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") {
+            else if (answer === "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(", ")}`);
+                console.log(`    Enter a number between 1 and ${allowed.length}.`);
             }
             if (attempt >= 2)
                 throw new Error("no valid choice — aborting");
@@ -304,25 +312,21 @@ function followProgress(orgId) {
         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");
+/**
+ * The whole import, from source to finished run, returning the project it landed in.
+ *
+ * RTSC-530 — split out of `importAction` so `retasc bind` can offer "bring your tracker
+ * across" as one of the ways a FIRST project comes into existence, the way the Dash's
+ * project step does. It calls this; it does not resemble it. Two copies of the auth prompt,
+ * target picker and column mapping is how the two drift, and the mapping is the part that
+ * decides where a whole backlog lands.
+ *
+ * Returns null when the human declines at the confirmation, so the caller can fall back
+ * rather than treat a deliberate "no" as a failure.
+ */
+export async function runImportFlow(opts) {
+    const { orgId, orgLabel } = opts;
+    // --- which tracker --------------------------------------------------------
     // --- which tracker --------------------------------------------------------
     const sources = (await api.listImportSources());
     if (!sources.length)
@@ -335,7 +339,7 @@ export async function importAction(opts) {
     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 }));
+    const { targets } = (await api.listImportTargets({ 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.");
     }
@@ -347,13 +351,13 @@ export async function importAction(opts) {
     let reviewerByStatus;
     if (src.supportsStatusMapping) {
         const { statuses } = (await api.listImportStatuses({
-            orgId: orgId,
+            orgId,
             source: src.source,
             auth,
             targetRef: target.id,
         }));
         if (statuses.length) {
-            const reviewers = (await api.listReviewCandidates({ orgId: orgId }));
+            const reviewers = (await api.listReviewCandidates({ orgId }));
             const mapped = await mapStatuses(statuses, reviewers, ask);
             statusMap = mapped.statusMap;
             reviewerByStatus = Object.keys(mapped.reviewerByStatus).length
@@ -371,13 +375,13 @@ export async function importAction(opts) {
     // 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 history = (await api.importHistory({ 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;
+        return null;
     }
     // --- run -------------------------------------------------------------------
     console.log("\nImporting…\n");
@@ -388,7 +392,7 @@ export async function importAction(opts) {
     let res;
     try {
         res = (await api.runImport({
-            orgId: orgId,
+            orgId,
             source: src.source,
             auth,
             target: { id: target.id, key: target.key, name: target.name },
@@ -421,4 +425,26 @@ export async function importAction(opts) {
     console.log("");
     const { identityLoop } = await import("./join.js");
     await identityLoop(orgId, {}, orgLabel);
+    return { projectId: res.projectId, prefix: target.key };
+}
+/** `retasc import` — the standalone command. Resolves the org, then runs the flow above. */
+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.");
+    }
+    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");
+    await runImportFlow({ orgId: orgId, orgLabel, source: opts.source, yes: opts.yes });
 }

package/package.json

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