@catalyst-cloud/cli 0.15.2 → 0.15.4

package/dist/setup-onboard-copy.js

@@ -1,5 +1,6 @@
 import { ONBOARD_DEPENDENCIES, ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
-import { onboardReasonText } from "./onboard-next.js";
+import { dispatchStageName, onboardReasonText } from "./onboard-next.js";
+/** The step numbers `--json` reports. People read SETUP_PART_NUMBERS instead (CTC-4680). */
 export const SETUP_NUMBERS = {
     machine: 1,
     cli: 1,
@@ -23,13 +24,94 @@ export const SETUP_NUMBERS = {
     values: 16,
     "first-ticket": 17,
 };
+/** CTC-4680: setup runs in three parts. The times are estimates until setup logs give medians. */
+export const SETUP_PARTS = {
+    1: {
+        title: "This computer",
+        estimate: "about 2 min",
+        summary: "skills and sign-in",
+        done: "This computer is set up.",
+    },
+    2: {
+        title: "Linear and GitHub",
+        estimate: "about 10 min",
+        summary: "approvals in your browser",
+        done: "Linear and GitHub are connected.",
+    },
+    3: {
+        title: "Ready for work",
+        estimate: "about 5 min",
+        summary: "a first ticket",
+        done: "Catalyst is ready for work.",
+    },
+};
+export const SETUP_PART_OF = {
+    machine: 1,
+    cli: 1,
+    skills: 1,
+    legacy: 1,
+    signin: 1,
+    daemon: 1,
+    housekeeping: 1,
+    "linear.workspace": 2,
+    "linear.personal": 2,
+    "linear.team": 2,
+    "linear.adopt": 2,
+    "linear.automations": 2,
+    "github.install": 2,
+    "github.personal": 2,
+    "github.repos": 3,
+    projects: 3,
+    accounts: 3,
+    capacity: 3,
+    runner: 3,
+    settings: 3,
+    values: 3,
+    "first-ticket": 3,
+    ready: 3,
+};
+/** What a person reads: each part restarts at 1, in the order setup runs the steps. Steps that
+ *  share a row (the computer checks, repositories and projects) share a number. */
+export const SETUP_PART_NUMBERS = {
+    machine: 1,
+    cli: 1,
+    skills: 1,
+    legacy: 1,
+    signin: 2,
+    housekeeping: 3,
+    "linear.workspace": 1,
+    "linear.personal": 2,
+    "linear.team": 3,
+    "linear.adopt": 4,
+    "linear.automations": 5,
+    "github.install": 6,
+    "github.personal": 7,
+    "github.repos": 1,
+    projects: 1,
+    accounts: 2,
+    capacity: 3,
+    runner: 4,
+    settings: 5,
+    values: 6,
+    "first-ticket": 7,
+};
+/** CTC-4680: people type `catalyst setup`; `catalyst onboard` stays its alias. What setup draws
+ *  names setup. `--json` and headless output keep their own words. */
+export function setupCommandWords(text) {
+    return text.replace(/\bcatalyst onboard\b/g, "catalyst setup");
+}
+/** "Part 1 of 3 · This computer", with a colon where the output is plain. */
+export function setupPartHeading(part, unicode) {
+    return `Part ${part} of 3${unicode ? " ·" : ":"} ${SETUP_PARTS[part].title}`;
+}
 const TITLES = {
     "linear.adopt": "Set up the team's workflow",
     "linear.automations": "Check Linear's PR automations",
     projects: "Choose repositories",
-    accounts: "Add a coding account",
+    accounts: "Add an AI account",
+    housekeeping: "Daily update",
     capacity: "Check runners",
-    values: "Review repository settings",
+    values: "Check repository values",
 };
 const OPTIONAL = new Set([
     "local_sync_not_selected",
@@ -83,18 +165,23 @@ function succeeded(step) {
         case "projects":
             return "repositories are now Catalyst projects";
         case "accounts":
-            return `${value(step, "provider") === "claude" ? "Claude" : value(step, "provider") === "codex" ? "Codex" : "a coding account"} can take work`;
+            return `${value(step, "provider") === "claude" ? "Claude" : value(step, "provider") === "codex" ? "Codex" : "an AI account"} can take work`;
+        case "housekeeping":
+            return "scheduled, runs daily";
         case "capacity":
             return typeof step.evidence?.remainingUnits === "number"
                 ? `${step.evidence.remainingUnits} runner slots available`
                 : "runners can take work";
         case "settings":
-        case "values":
             return "settings reviewed";
-        case "first-ticket":
-            return value(step, "ticketKey")
-                ? `${value(step, "ticketKey")} started`
+        case "values":
+            return "values set";
+        case "first-ticket": {
+            const key = value(step, "ticket") ?? value(step, "ticketKey");
+            return key
+                ? `${key} moved to ${dispatchStageName(step.evidence?.stage)}. Catalyst picks it up next.`
                 : "first ticket started";
+        }
         case "daemon":
             return "local sync is running";
         case "runner":
@@ -114,15 +201,23 @@ function unfinished(step) {
         return "could not verify the connection's permissions";
     if (step.reason === "housekeeping_service_unverified")
         return "no scheduler here. catalyst says when an update is out";
+    if (step.reason === "housekeeping_off_chosen")
+        return "skipped, as you chose";
+    if (step.reason === "housekeeping_no_scheduler")
+        return "can't run on this computer";
+    if (step.id === "housekeeping")
+        return "not scheduled; the install command turns it on";
     if (step.reason === "local_sync_not_selected")
         return "off, reads come from the cloud";
     if (step.reason === "runner_docker_missing")
         return "Docker is not running";
     if (step.reason === "member_scope")
-        return "an admin handles this step";
+        return step.id === "linear.team" || step.id === "values"
+            ? "run catalyst setup --team <KEY> to choose your team"
+            : "an admin handles this step";
     if (step.reason === "automation_management_unavailable")
         return "could not read them; checked again before work starts";
-    if (step.reason === "interrupted")
+    if (step.reason === "interrupted" || step.reason === "first_ticket_skipped")
         return "skipped for now";
     if (TIMED_OUT_REASONS.has(step.reason ?? ""))
         return "the link timed out";
@@ -134,7 +229,7 @@ function unfinished(step) {
         case "github.install":
             return "not installed yet";
         case "accounts":
-            return "no coding account ready yet";
+            return "no AI account ready yet";
         case "linear.workspace":
         case "linear.personal":
         case "github.personal":
@@ -144,8 +239,13 @@ function unfinished(step) {
         case "capacity":
             return "no runner can take work yet";
         case "settings":
-        case "values":
             return "optional; not reviewed yet";
+        case "values":
+            return step.reason === "required_values_missing"
+                ? "a value is missing"
+                : "not checked yet";
+        case "first-ticket":
+            return "no ticket chosen yet";
         default:
             return step.state === "skipped" ? "not chosen" : "not done yet";
     }
@@ -166,31 +266,192 @@ export function setupStepView(step, journal, required = false) {
                     : "act";
     let outcome = step.state === "done" ? succeeded(step) : unfinished(step);
     if (mark === "later") {
-        const numbers = [
-            ...new Set((ONBOARD_DEPENDENCIES[step.id] ?? [])
-                .filter((id) => {
+        const waitsOn = step.reason === "github_install_pending"
+            ? ["github.install"]
+            : (ONBOARD_DEPENDENCIES[step.id] ?? []).filter((id) => {
                 const s = journal?.steps.find((s) => s.id === id);
                 return s?.state !== "done" && s?.state !== "skipped";
-            })
-                .map((id) => SETUP_NUMBERS[id])
-                .filter((n) => n !== undefined)),
-        ];
-        if (step.reason === "github_install_pending")
-            numbers.splice(0, numbers.length, SETUP_NUMBERS["github.install"]);
+            });
+        // Numbers restart in each part: this part's steps come bare, then each other part once.
+        const byPart = new Map();
+        for (const id of waitsOn) {
+            const n = SETUP_PART_NUMBERS[id];
+            if (n === undefined)
+                continue;
+            const p = SETUP_PART_OF[id];
+            const list = byPart.get(p) ?? [];
+            if (!list.includes(n))
+                byPart.set(p, [...list, n]);
+        }
+        const own = SETUP_PART_OF[step.id];
+        const steps = (ns) => {
+            const sorted = [...ns].sort((x, y) => x - y);
+            const last = sorted.pop();
+            return sorted.length
+                ? `steps ${sorted.join(", ")} and ${last}`
+                : `step ${last}`;
+        };
+        const groups = [...byPart]
+            .sort(([x], [y]) => (x === own ? -1 : y === own ? 1 : x - y))
+            .map(([p, ns]) => (p === own ? steps(ns) : `${steps(ns)} of part ${p}`));
         outcome =
             step.state === "pending" && !step.reason
                 ? "not checked yet"
-                : numbers.length
-                    ? `after ${numbers.length === 1 ? "step" : "steps"} ${numbers.join(" and ")}`
+                : groups.length
+                    ? `after ${groups.length > 1 ? `${groups.slice(0, -1).join(", ")}, and ${groups.at(-1)}` : groups[0]}`
                     : "after an earlier step";
     }
     return {
-        number: SETUP_NUMBERS[step.id] ?? 0,
+        number: SETUP_PART_NUMBERS[step.id] ?? 0,
         title: TITLES[step.id] ?? ONBOARD_TITLES[step.id],
         mark,
         outcome,
     };
 }
+/** The signed-in person's Catalyst role, when the sign-in step recorded one. */
+function signedInRole(journal) {
+    const role = journal?.steps.find((s) => s.id === "signin" && s.state === "done")?.evidence?.role;
+    return typeof role === "string" ? role : undefined;
+}
+const notOwnerOrAdmin = (journal) => {
+    const role = signedInRole(journal);
+    return role !== undefined && role !== "owner" && role !== "admin";
+};
+/** The steps readiness says an owner or admin has left (`admin_setup_pending`), if it said so. */
+function readinessAdminSteps(journal) {
+    const ready = journal?.steps.find((s) => s.id === "ready");
+    const ids = ready?.evidence?.admin;
+    return ready?.reason === "admin_setup_pending" && typeof ids === "string"
+        ? new Set(ids.split(","))
+        : new Set();
+}
+/** A member's skip of their own team (or the values it gates): rerun with --team, nobody else. */
+const memberOwnSkip = (step) => step.reason === "member_scope" &&
+    (step.id === "linear.team" || step.id === "values");
+/**
+ * CTC-4680: a step only an owner or admin of the Catalyst workspace can finish, for the person
+ * running setup. A member's run skips every admin step whether or not the admin has done it, so a
+ * skip waits on an admin only when readiness names that step. Refusals for the person's role, a
+ * member's unverified runner or workflow, and a member's AI account or values do too.
+ */
+export function setupWaitsOnAdmin(step, journal) {
+    if (step.state === "done")
+        return false;
+    const reason = step.reason ?? "";
+    if (reason === "member_scope")
+        return !memberOwnSkip(step) && readinessAdminSteps(journal).has(step.id);
+    if (reason === "github_installation_admin_required")
+        return true;
+    if (reason === "runner_identity_unverified" ||
+        reason === "workflow_identity_unverified")
+        return notOwnerOrAdmin(journal);
+    // Only reasons an owner or admin clears. A probe that could not finish (a stale read, a login
+    // to refresh) is the person's own to check again.
+    if ((step.id === "accounts" &&
+        (reason === "account_enrollment_required" ||
+            reason === "ai_account_not_usable")) ||
+        (step.id === "values" && reason === "required_values_missing"))
+        return notOwnerOrAdmin(journal);
+    return false;
+}
+/** How far each part has got, by its numbered rows. A row is done when every step in it is done
+ *  or skipped by choice, needs someone when any of its steps does, and waits on an owner or admin
+ *  when only they can finish it. */
+export function setupPartProgress(journal, scope, 
+/** "run" before readiness is known: a member's admin skips count aside, neither done nor owed.
+ *  At the end they count done only when readiness passed. */
+moment = "end") {
+    const empty = () => ({ total: 0, done: 0, needs: 0, failed: 0, admin: 0, aside: 0 });
+    const progress = { 1: empty(), 2: empty(), 3: empty() };
+    const readinessPassed = journal.steps.find((s) => s.id === "ready")?.state === "done";
+    const rows = new Map();
+    for (const id of ONBOARD_STEPS) {
+        const number = SETUP_PART_NUMBERS[id];
+        if (number === undefined || (scope && !scope.includes(id)))
+            continue;
+        const step = journal.steps.find((s) => s.id === id) ?? {
+            id,
+            state: "pending",
+        };
+        const key = `${SETUP_PART_OF[id]}:${number}`;
+        rows.set(key, [
+            ...(rows.get(key) ?? []),
+            {
+                // A member's own skip (no --team) is theirs to finish, so it is never counted done.
+                mark: memberOwnSkip(step) ? "act" : setupStepView(step, journal).mark,
+                kind: setupWaitsOnAdmin(step, journal)
+                    ? "admin"
+                    : step.reason === "member_scope" &&
+                        !memberOwnSkip(step) &&
+                        (moment === "run" || !readinessPassed)
+                        ? "aside"
+                        : "own",
+            },
+        ]);
+    }
+    for (const [key, steps] of rows) {
+        const part = progress[Number(key.split(":")[0])];
+        part.total++;
+        const own = steps.filter((s) => s.kind === "own");
+        if (own.length === steps.length && own.every((s) => s.mark === "done" || s.mark === "skip"))
+            part.done++;
+        else if (own.some((s) => s.mark === "act" || s.mark === "fail")) {
+            part.needs++;
+            if (own.some((s) => s.mark === "fail"))
+                part.failed++;
+        }
+        else if (steps.some((s) => s.kind === "admin"))
+            part.admin++;
+        else if (steps.some((s) => s.kind === "aside"))
+            part.aside++;
+    }
+    return progress;
+}
+/**
+ * The tracker's rows: on the first screen (`plan`, the part about to start), at a boundary
+ * (`next`, the part about to start), or at the end. A part with no rows in this run is left out.
+ */
+export function setupTrackerRows(progress, moment) {
+    const steps = (n) => `${n} ${n === 1 ? "step" : "steps"}`;
+    const waiting = (n) => `${steps(n)} ${n === 1 ? "waits" : "wait"} on an owner or admin`;
+    return [1, 2, 3]
+        .filter((p) => progress[p].total > 0)
+        .map((p) => {
+        const { title, estimate, summary } = SETUP_PARTS[p];
+        const got = progress[p];
+        const row = (mark, note) => ({
+            mark,
+            number: p,
+            title,
+            note,
+        });
+        if (typeof moment === "object" && "plan" in moment)
+            return row(p === moment.plan ? "now" : "later", `${estimate} · ${summary}`);
+        const finished = got.done === got.total;
+        const needsMark = got.failed ? "fail" : "act";
+        if (typeof moment === "object") {
+            if (p === moment.next)
+                return row("now", `next · ${estimate}`);
+            if (p > moment.next)
+                return row("later", estimate);
+            if (finished)
+                return row("done", "done");
+            const theirs = got.admin + got.aside;
+            if (theirs && got.done + theirs === got.total)
+                return row("act", `${steps(theirs)} ${theirs === 1 ? "is" : "are"} for an owner or admin`);
+            return row(needsMark, `${steps(got.total - got.done)} not finished`);
+        }
+        if (finished)
+            return row("done", "");
+        if (got.needs)
+            return row(needsMark, `${steps(got.needs)} ${got.needs === 1 ? "needs" : "need"} someone`);
+        if (got.admin)
+            return row("act", waiting(got.admin));
+        if (got.aside)
+            return row("act", `${steps(got.aside)} ${got.aside === 1 ? "is" : "are"} for an owner or admin`);
+        return row("later", `${got.done} of ${steps(got.total)} done`);
+    });
+}
 function page(base, path) {
     try {
         const url = new URL(path, base);
@@ -206,7 +467,8 @@ function page(base, path) {
 }
 function action(step, base, journal) {
     if (CONNECTION_REPAIR_REASONS.has(step.reason ?? "") ||
-        step.reason === "github_installation_approval_pending")
+        step.reason === "github_installation_approval_pending" ||
+        step.reason === "member_scope")
         return onboardReasonText(step, { baseUrl: base, journal });
     const link = (path, verb) => {
         const url = page(base, path);
@@ -229,7 +491,9 @@ function action(step, base, journal) {
         case "github.personal":
             return link("/settings/connected-accounts?connect=github", "connect your GitHub account");
         case "accounts":
-            return link("/settings/coding-accounts", "add a coding account");
+            return step.reason === "ai_account_not_usable"
+                ? onboardReasonText(step, { baseUrl: base, journal })
+                : link("/settings/coding-accounts", "add an AI account");
         case "linear.adopt": {
             const team = journal?.steps.find((row) => row.id === "linear.team" && row.state === "done");
             const key = team && value(team, "teamKey");
@@ -245,24 +509,30 @@ function action(step, base, journal) {
                 ? onboardReasonText(step, { baseUrl: base, journal })
                 : "Run catalyst onboard --runner to check whether this computer can take work.";
         case "settings":
-        case "values":
             return "Open your repository checkout and review its settings.";
+        case "values":
+            return onboardReasonText({ ...step, reason: step.reason ?? "required_values_unverified" }, { baseUrl: base, journal });
         case "linear.team":
             return "Choose a Linear team when setup checks again.";
         case "github.repos":
         case "projects":
             return "Choose repositories when setup checks again.";
         case "first-ticket":
-            return "Choose a first ticket when setup checks again.";
+            return onboardReasonText({ ...step, reason: step.reason ?? "first_ticket_choice_required" }, { baseUrl: base, journal });
         default:
             return "Try this step again when setup checks again.";
     }
 }
 export function setupFinalScreen(journal, base, paused = false, required = new Set()) {
+    // A member's run skips admin steps; readiness names the ones an admin has not finished yet.
+    const readyStep = journal.steps.find((step) => step.id === "ready");
+    const adminLeft = new Set(readyStep?.reason === "admin_setup_pending" && typeof readyStep.evidence?.admin === "string"
+        ? readyStep.evidence.admin.split(",")
+        : []);
     const roots = journal.steps
         .filter((step) => {
         const m = setupStepView(step, journal, required.has(step.id)).mark;
-        return ((m === "act" || m === "fail") &&
+        return ((m === "act" || m === "fail" || adminLeft.has(step.id)) &&
             (ONBOARD_DEPENDENCIES[step.id] ?? []).every((id) => {
                 const parent = journal.steps.find((s) => s.id === id);
                 return parent?.state === "done" || parent?.state === "skipped";
@@ -270,7 +540,7 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
     })
         .filter((step) => step.id !== "ready")
         .sort((a, b) => ONBOARD_STEPS.indexOf(a.id) - ONBOARD_STEPS.indexOf(b.id));
-    const folded = (id) => id === "projects" ? "github.repos" : id === "values" ? "settings" : id;
+    const folded = (id) => id === "projects" ? "github.repos" : id;
     const unique = roots.filter((step, i) => roots.findIndex((s) => folded(s.id) === folded(step.id)) === i);
     const actions = unique
         .slice(0, 5)
@@ -297,16 +567,17 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
                 : journal.exit === 0
                     ? "Ready for work"
                     : "Not ready for work yet";
-    const ticket = journal.steps.find((s) => s.id === "first-ticket" && s.state === "done");
-    const key = ticket && value(ticket, "ticketKey");
+    const firstTicket = journal.steps.find((s) => s.id === "first-ticket");
+    const ticket = firstTicket?.state === "done" ? firstTicket : undefined;
+    const key = ticket && (value(ticket, "ticket") ?? value(ticket, "ticketKey"));
     const savedTicketUrl = ticket && (value(ticket, "url") ?? value(ticket, "ticketUrl"));
     const ticketUrl = savedTicketUrl && page(base, savedTicketUrl);
     const next = paused
         ? "Next: run catalyst onboard to continue."
-        : key && ticketUrl
-            ? `Next: open ${ticketUrl} and follow ${key}.`
+        : key
+            ? `Follow ${ticketUrl ?? key} in Linear; Catalyst comments there as each phase finishes.`
             : heading === "Setup complete"
-                ? "Next: move a ticket to Todo in Linear."
+                ? `Next: move a ticket to ${dispatchStageName(firstTicket?.evidence?.stage)} in Linear.`
                 : journal.exit === 0 && actions[0]
                     ? `Next: ${actions[0].text[0].toLowerCase() + actions[0].text.slice(1)}`
                     : actions.length === 1
@@ -317,7 +588,9 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
                                 ? "Next: run catalyst onboard after you finish 1 to " +
                                     actions.length +
                                     "."
-                                : "Next: run catalyst onboard to check again.";
+                                : readyStep?.reason === "member_team_required"
+                                    ? "Next: run catalyst onboard --team <KEY> to check again."
+                                    : "Next: run catalyst onboard to check again.";
     return {
         heading,
         readinessCause,
@@ -351,8 +624,8 @@ export function setupBrowserInstruction(id, base, opened = false) {
         ],
         accounts: [
             "/settings/coding-accounts",
-            "add the token with your Claude email",
-            "Add a coding account",
+            "add an API key",
+            "Add an API key",
         ],
     };
     const words = copy[id];
@@ -363,9 +636,6 @@ export function setupBrowserInstruction(id, base, opened = false) {
             ? `Opened your browser. ${words[2]} there.`
             : `Open this link and ${words[1]}:`,
         url: page(base, words[0]),
-        preparation: id === "accounts"
-            ? "In another terminal, run claude setup-token."
-            : undefined,
     };
 }
 /** JSON facts use the same reachable actions as the terminal, while retaining the existing journal. */
@@ -412,7 +682,9 @@ export function onboardJsonView(journal, base, paused = false, options = {}) {
             // CTC-4680: refused by the person's Catalyst role, not by GitHub, so a workspace admin acts.
             step.reason === "github_installation_admin_required" ||
             step.reason?.endsWith("_identity_unverified") ||
-            (action.id === "accounts" && role !== "owner" && role !== "admin");
+            ((action.id === "accounts" || action.id === "values") &&
+                role !== "owner" &&
+                role !== "admin");
         const url = action.text
             .match(/https?:\/\/[^\s<>]+/)?.[0]
             ?.replace(/[.,;:!?]+$/, "");