@catalyst-cloud/cli 0.15.3 → 0.15.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.15.5
+
+Setup explains what running work on this computer means and lists every repository registered to your Linear team.
+
+## 0.15.4
+
+- Setup shows a colour mark and clearer progress, with a plain display when your terminal needs it.
+- Setup separates your next steps from tasks waiting on an owner or admin, and reports when it stops waiting for an account connection.
+- Setup wraps long text by words and keeps numbered steps in order.
+
 ## 0.15.3
 
 - Setup can finish once the steps needed to run work are ready. It lists optional next steps and keeps your first-ticket choice when you resume.

package/README.md

@@ -133,6 +133,8 @@ catalyst onboard
 catalyst ready --onboarding --json
 ```
 
+`catalyst setup` opens with the Catalyst Cloud mark in your terminal's colours. It asks the terminal whether its background is light or dark; set `CATALYST_THEME=light` or `CATALYST_THEME=dark` when it guesses wrong. `--no-color` or `NO_COLOR` prints plain text without the mark.
+
 The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
 
 ### Headless setup (CI, image builds, agent VMs)

package/dist/args.js

@@ -64,6 +64,10 @@ export const FLAG_TABLES = {
             value: false,
             help: "do not run Catalyst's work on this machine, and do not ask",
         },
+        "no-color": {
+            value: false,
+            help: "print setup in plain text, without colour or the Catalyst Cloud mark",
+        },
         "resume-from": {
             value: true,
             help: "resume at a verified onboarding step",
@@ -459,7 +463,7 @@ export const FLAG_TABLES = {
 export const VERB_USAGE = {
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",

package/dist/cli.js

@@ -1,6 +1,6 @@
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
-import { createSetupRenderer } from "./setup-render.js";
+import { createSetupRenderer, setupBanner, } from "./setup-render.js";
 import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
 import { Writable } from "node:stream";
@@ -210,6 +210,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
     // CTC-4625: setup passes the install options through to its engine untouched, so they never meet
     // this CLI's own flag tables. CTC-4680: without --engine, `setup` is the name a person types for
     // the onboard flow, so it runs exactly that.
+    const viaSetup = drawsMark(argv);
     if (argv[0] === "setup") {
         const rest = argv.slice(1);
         const own = rest.indexOf("--") === -1 ? rest : rest.slice(0, rest.indexOf("--"));
@@ -278,6 +279,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 // Headless runs drop the terminal UI, browser sign-in and every browser action (CTC-4633).
                 const runOnboard = async (args, ctx, headless) => {
                     let ui = headless ? undefined : deps.setupUi;
+                    // --no-color reaches the renderer as NO_COLOR, so the banner and every step row go plain.
+                    const noColor = args.flags["no-color"] === true;
+                    const rendererEnv = noColor ? { ...ctx.env, NO_COLOR: "1" } : ctx.env;
                     let terminal;
                     let input = process.stdin;
                     const originalRaw = Boolean(input.isRaw);
@@ -300,10 +304,18 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                         }
                         if (input.isTTY) {
                             try {
+                                const banner = await setupBanner({
+                                    setup: viaSetup,
+                                    env: rendererEnv,
+                                    input,
+                                    stdout: process.stdout,
+                                    stream: bannerStream(ctx),
+                                    noColor,
+                                });
                                 ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, {
                                     baseUrl: () => savedOnboardBaseUrl(ctx.home),
                                     verbose: args.flags.verbose === true,
-                                    renderer: createSetupRenderer(process.stdout, ctx.env),
+                                    renderer: createSetupRenderer(process.stdout, rendererEnv, banner),
                                     disposeRenderer: true,
                                     signinTimeoutMs: deps.onboardSigninTimeoutMs,
                                     version: manifest.version,
@@ -326,7 +338,14 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                             });
                         ui = createClackOnboardUi(await import("@clack/prompts"), { input: process.stdin, output }, {
                             baseUrl: () => savedOnboardBaseUrl(ctx.home),
-                            renderer: createSetupRenderer(output, ctx.env),
+                            renderer: createSetupRenderer(output, rendererEnv, await setupBanner({
+                                setup: viaSetup,
+                                env: rendererEnv,
+                                input: process.stdin,
+                                stdout: process.stdout,
+                                stream: bannerStream(ctx),
+                                noColor,
+                            })),
                             disposeRenderer: true,
                             signinTimeoutMs: deps.onboardSigninTimeoutMs,
                             version: manifest.version,
@@ -560,6 +579,23 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "legacy",
     "onboard",
 ].map((v) => [v, true]));
+/** CTC-4680: the Pixel Nucleus mark belongs to `catalyst setup` alone. `setup` runs the onboard
+ *  flow, so this is read from the verb typed, before setup becomes onboard. */
+export function drawsMark(argv) {
+    return argv[0] === "setup";
+}
+/** CTC-4680: the banner goes to stderr, through ctx when stderr is not a terminal. */
+function bannerStream(ctx) {
+    if (process.stderr.isTTY === true)
+        return process.stderr;
+    return {
+        write(chunk) {
+            for (const line of chunk.replace(/\n$/, "").split("\n"))
+                ctx.stderr(line);
+            return true;
+        },
+    };
+}
 /** CTC-4625: `catalyst setup`, wired to this terminal, @clack/prompts and the keyless login. */
 async function runSetup(argv, ctx, deps) {
     if (argv[0] === "--help" || argv[0] === "-h") {

package/dist/onboard-checklist.js

@@ -235,8 +235,9 @@ export function connectChecklistAdapter(options) {
             // The contract advertised the route for this read; the wait's polls read the checklist alone.
             const origin = new URL(url).origin;
             let instruction;
-            if (options.page.openedBy === null ||
-                options.page.openedBy === options.step) {
+            // One tab per run: a second wait (Keep waiting, or another step) points at the page already
+            // open, and the wait still shows its address.
+            if (options.page.openedBy === null) {
                 try {
                     await options.openBrowser(url, signal);
                     options.page.openedBy = options.step;

package/dist/onboard-headless.js

@@ -242,6 +242,9 @@ export function planOnboardHeadless(args, ctx) {
     delete flags["key-file"];
     delete flags.runner;
     delete flags["no-runner"];
+    // CATALYST_ONBOARD_HEADLESS=1 alone leaves the flag unset; the plan names the headless input
+    // rather than a --no-runner nobody typed (CTC-4739).
+    flags.headless = true;
     if (runner === "yes")
         flags.runner = true;
     if (runner === "no")

package/dist/onboard-repositories.js

@@ -97,6 +97,17 @@ export async function readOnboardRepositoryInventory(ctx, journal, signal) {
     const teamId = selectedOnboardTeam(journal);
     if (!teamId)
         return { reason: "team_selection_unverified" };
+    // CTC-4742: the per-person repository list names every project a repository belongs to, so a
+    // team that uses several repositories shows all of them. A member's list is narrowed to their
+    // own access by the server. An older server without the route falls back to the one-per-team
+    // registry below.
+    const agent = await readExistingOnboardJson(ctx, "/api/v1/agent/repos", signal);
+    if (!sameIdentity())
+        return { reason: "repository_identity_unverified" };
+    if (!("reason" in agent))
+        return teamRepositories(ctx, journal, teamId, agent.body, sameIdentity, signal);
+    if (agent.status !== 404)
+        return { reason: "repository_read_unavailable" };
     const read = await readExistingOnboardJson(ctx, "/api/v1/repos", signal);
     if (!sameIdentity())
         return { reason: "repository_identity_unverified" };
@@ -171,6 +182,162 @@ export async function readOnboardRepositoryInventory(ctx, journal, signal) {
     }
     return { repositories };
 }
+/** The saved login is still the person, account and origin this run started with (and, when
+ *  `manager`, an owner or admin). Returns that config, or null. */
+function journalIdentity(ctx, journal, manager = false) {
+    const cfg = loadConfig(ctx.home);
+    return cfg?.user &&
+        cfg.account === journal.account &&
+        cfg.user.id === journal.membershipId &&
+        !!journal.baseUrl &&
+        normalizeBaseUrl(cfg.baseUrl) === normalizeBaseUrl(journal.baseUrl) &&
+        (!manager || ["owner", "admin"].includes(cfg.user.role))
+        ? cfg
+        : null;
+}
+const REGISTER_PATH = "/api/v1/agent/project-repositories";
+/** The fresh contract's repository IDs and the repositories registered to the chosen team (by its
+ *  id), or why they can't be trusted. */
+async function contractIds(ctx, journal, teamId, sameIdentity, signal) {
+    const read = await readExistingOnboardJson(ctx, "/api/v1/agent/contract", signal);
+    if (!sameIdentity())
+        return { reason: "repository_identity_unverified" };
+    if ("reason" in read)
+        return { reason: "repository_contract_unavailable" };
+    const doc = object(read.body);
+    const account = object(doc?.account);
+    const merge = object(doc?.merge);
+    if (!doc ||
+        account?.id !== journal.account ||
+        typeof doc.contractVersion !== "string" ||
+        contractVersionInRange(doc.contractVersion, readManifest().tenantContractRange) !== true ||
+        !merge ||
+        !Array.isArray(merge.repositories) ||
+        merge.repositories.length > 10_000 ||
+        !Array.isArray(doc.teams) ||
+        doc.teams.length > 1_000)
+        return { reason: "repository_contract_unverified" };
+    // The team's repositories, keyed by the team's id (a team key can be renamed or missing).
+    const teams = doc.teams.filter((value) => object(value)?.id === teamId);
+    const names = object(object(teams[0])?.repositories)?.registered;
+    if (teams.length !== 1 ||
+        !Array.isArray(names) ||
+        names.length > 1_000 ||
+        !names.every((name) => typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(name)))
+        return { reason: "team_selection_unverified" };
+    const registered = new Set(names.map((name) => name.toLowerCase()));
+    const ids = new Map();
+    const idNames = new Map();
+    for (const value of merge.repositories) {
+        const row = object(value);
+        if (!row ||
+            typeof row.owner !== "string" ||
+            !part.test(row.owner) ||
+            typeof row.name !== "string" ||
+            !part.test(row.name) ||
+            !isRepositoryId(row.repoId))
+            return { reason: "repository_contract_unverified" };
+        const name = key({ owner: row.owner, name: row.name });
+        if (idNames.has(row.repoId) && idNames.get(row.repoId) !== name)
+            return { reason: "repository_contract_unverified" };
+        idNames.set(row.repoId, name);
+        ids.set(name, [...(ids.get(name) ?? []), row.repoId]);
+    }
+    // Registering is offered only when this account's contract lists the route (CTC-4742).
+    const canRegister = Array.isArray(doc.routes) &&
+        doc.routes.some((value) => {
+            const route = object(value);
+            return route?.method === "POST" && route.path === REGISTER_PATH;
+        });
+    return { registered, ids, canRegister };
+}
+/** CTC-4742: every repository an active project of the chosen team uses, with its contract ID. */
+async function teamRepositories(ctx, journal, teamId, body, sameIdentity, signal) {
+    const list = object(body);
+    if (!list || !Array.isArray(list.repositories) || list.repositories.length > 10_000)
+        return { reason: "repository_inventory_shape" };
+    const contract = await contractIds(ctx, journal, teamId, sameIdentity, signal);
+    if ("reason" in contract)
+        return contract;
+    const repositories = [];
+    const seen = new Set();
+    for (const value of list.repositories) {
+        const row = object(value);
+        if (!row ||
+            typeof row.id !== "string" ||
+            typeof row.owner !== "string" ||
+            !part.test(row.owner) ||
+            typeof row.name !== "string" ||
+            !part.test(row.name))
+            return { reason: "repository_inventory_shape" };
+        // The contract says which repositories the team uses; this person's list says which of them
+        // they can see (the server narrows it for a member).
+        const name = key({ owner: row.owner, name: row.name });
+        if (!contract.registered.has(name))
+            continue;
+        if (seen.has(name))
+            return { reason: "repository_binding_ambiguous" };
+        seen.add(name);
+        const ids = contract.ids.get(name);
+        if (!ids || ids.length !== 1 || ids[0] !== row.id)
+            return { reason: "repository_id_unverified" };
+        repositories.push({ teamId, owner: row.owner, name: row.name, repoId: ids[0], registered: true });
+    }
+    return { repositories, canRegister: contract.canRegister };
+}
+/** CTC-4742: repositories the GitHub App can reach that the team does not use yet, for an owner or
+ *  admin only (only they can register one). Any read problem means no offers, never a stopped step. */
+async function offeredRepositories(ctx, journal, teamId, registered, signal) {
+    if (!journalIdentity(ctx, journal, true))
+        return [];
+    const read = await readExistingOnboardJson(ctx, "/api/v1/me/repositories/options", signal);
+    if (!journalIdentity(ctx, journal, true) || "reason" in read)
+        return [];
+    const github = object(object(read.body)?.github);
+    if (!github || github.connected !== true || !Array.isArray(github.repositories) || github.repositories.length > 10_000)
+        return [];
+    const used = new Set(registered.map(key));
+    const offers = [];
+    for (const value of github.repositories) {
+        const row = object(value);
+        if (!row || typeof row.owner !== "string" || !part.test(row.owner) || typeof row.name !== "string" || !part.test(row.name))
+            return [];
+        const name = key({ owner: row.owner, name: row.name });
+        if (used.has(name))
+            continue;
+        used.add(name);
+        offers.push({ teamId, owner: row.owner, name: row.name, repoId: null, registered: false });
+    }
+    return offers;
+}
+/** CTC-4742: register one repository to the team's project. Only adds; nothing here removes one. */
+async function registerToTeam(ctx, journal, teamId, repository, signal) {
+    // The person who answered the question is the one who registers: checked right before the write.
+    const cfg = journalIdentity(ctx, journal, true);
+    if (!cfg)
+        return "repository_identity_unverified";
+    const expiry = cfg.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+    const bearer = cfg.key || (cfg.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return "project_login_refresh_required";
+    // Bounded like every read here, so a server that never answers can't hold setup.
+    const deadline = AbortSignal.timeout(30_000);
+    const bounded = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    try {
+        const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}${REGISTER_PATH}`, {
+            method: "POST",
+            redirect: "error",
+            signal: bounded,
+            headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ teamId, repository }),
+        });
+        // A response is not evidence: the next read must show the repository on the team.
+        return response.status === 200 ? null : "repository_register_unverified";
+    }
+    catch {
+        return signal?.aborted ? "interrupted" : "repository_register_unverified";
+    }
+}
 export function existingRepositoryAdapter(args, choose) {
     let chosen;
     const requested = (repositories, journal) => {
@@ -218,7 +385,7 @@ export function existingRepositoryAdapter(args, choose) {
         return {
             state: "done",
             evidence: {
-                repository: JSON.stringify(rows),
+                repository: JSON.stringify(rows.map(({ teamId, owner, name, repoId }) => ({ teamId, owner, name, repoId }))),
                 count: rows.length,
                 checkedAt: ctx.now().getTime(),
             },
@@ -234,6 +401,14 @@ export function existingRepositoryAdapter(args, choose) {
                 return waiting("repository_inventory_empty");
             if (!choose)
                 return waiting("repository_choice_required");
+            const teamId = list.repositories[0].teamId;
+            const offers = list.canRegister
+                ? await offeredRepositories(ctx, journal, teamId, list.repositories, signal)
+                : [];
+            const choices = [
+                ...list.repositories.map((row) => ({ ...row })),
+                ...offers.map((row) => ({ ...row })),
+            ];
             let remove = () => { };
             const answer = await new Promise((resolve, reject) => {
                 const stopped = () => resolve(null);
@@ -244,9 +419,8 @@ export function existingRepositoryAdapter(args, choose) {
                 signal?.addEventListener("abort", stopped, { once: true });
                 remove = () => signal?.removeEventListener("abort", stopped);
                 Promise.resolve()
-                    .then(() => signal?.aborted
-                    ? null
-                    : choose(list.repositories.map((row) => ({ ...row }))))
+                    // The hook gets copies: changing one can never change what is matched below.
+                    .then(() => signal?.aborted ? null : choose(choices.map((row) => ({ ...row }))))
                     .then(resolve, reject);
             }).finally(() => remove());
             if (!answer || signal?.aborted)
@@ -259,9 +433,26 @@ export function existingRepositoryAdapter(args, choose) {
             const names = answer.map((name) => name.toLowerCase());
             if (new Set(names).size !== names.length)
                 return waiting("repository_selection_unverified");
-            const rows = names.map((name) => list.repositories.find((row) => key(row) === name));
-            if (!rows.every((row) => !!row))
+            const picked = names.map((name) => choices.find((row) => key(row) === name));
+            if (!picked.every((row) => !!row))
                 return waiting("repository_selection_unverified");
+            // CTC-4742: a selected offer is registered to the team. Leaving a registered repository
+            // unselected never unregisters it; nothing here removes a repository.
+            for (const row of picked) {
+                if (row.registered !== false)
+                    continue;
+                const failed = await registerToTeam(ctx, journal, teamId, `${row.owner}/${row.name}`, signal);
+                if (failed)
+                    return waiting(failed);
+            }
+            const fresh = picked.some((row) => row.registered === false)
+                ? await readOnboardRepositoryInventory(ctx, journal, signal)
+                : list;
+            if ("reason" in fresh)
+                return waiting(fresh.reason);
+            const rows = names.map((name) => fresh.repositories.find((row) => key(row) === name));
+            if (!rows.every((row) => !!row))
+                return waiting("repository_registration_visibility_pending");
             chosen = rows;
             return check(ctx, journal, signal);
         },

package/dist/onboard-standalone-copy.js

@@ -1,5 +1,8 @@
 import { setupPartHeading, setupStepView, SETUP_NUMBERS, SETUP_PART_NUMBERS, SETUP_PART_OF, } from "./setup-onboard-copy.js";
 export const COMPUTER_CHECKS = ["machine", "cli", "skills", "legacy"];
+/** The runner row when no runner was chosen up front, naming where that choice came from, so the
+ *  plan says why no question comes (CTC-4739). */
+const runnerDeclined = (by) => `this computer will not take work, because ${by}`;
 const PLAN = [
     ["On this computer", "signin", "you approve once in your browser"],
     ["On this computer", "housekeeping", "schedule the daily update"],
@@ -22,7 +25,14 @@ const PLAN = [
  * part. `json` is the plain-text plan an agent reads beside `--json` (dry run, --json on stderr,
  * headless): the older groups and the numbers JSON `actions[].number` reports (CTC-4680).
  */
-export function standalonePlan(journal, scope, runnerSelected = false, numbering = "parts") {
+export function standalonePlan(journal, scope, 
+/** `true` for --runner, `false` for --no-runner, absent when setup will ask (CTC-4739). */
+runner, numbering = "parts", 
+/** Why `runner` is false: the flag on an interactive run, the headless input otherwise. */
+declinedBy = "--no-runner was passed") {
+    const runnerSelected = runner === true;
+    const RUNNER_DECLINED = runnerDeclined(declinedBy);
+    const declined = runner === false;
     const json = numbering === "json";
     const includes = (id) => !scope || scope.includes(id);
     const steps = new Map(journal.steps.map((step) => [step.id, step]));
@@ -53,7 +63,9 @@ export function standalonePlan(journal, scope, runnerSelected = false, numbering
             if (includes("runner"))
                 row("runner", runnerSelected
                     ? "start a Catalyst runner here with Docker"
-                    : "optional; this computer takes work only if you choose it");
+                    : declined
+                        ? RUNNER_DECLINED
+                        : "optional; this computer takes work only if you choose it");
             continue;
         }
         // The terminal gives repository values their own row; the plain-text plan keeps them folded
@@ -66,9 +78,13 @@ export function standalonePlan(journal, scope, runnerSelected = false, numbering
             continue;
         const reviewedDetail = id === "capacity" && includes("runner") && runnerSelected
             ? "start a Catalyst runner here with Docker"
-            : id === "capacity" && !includes("capacity")
-                ? "review the optional runner on this machine; start only if selected"
-                : detail;
+            : id === "capacity" && includes("runner") && declined
+                ? includes("capacity")
+                    ? `${detail}; ${RUNNER_DECLINED}`
+                    : RUNNER_DECLINED
+                : id === "capacity" && !includes("capacity")
+                    ? "review the optional runner on this machine; start only if selected"
+                    : detail;
         rows.push({
             group: json ? group : setupPartHeading(SETUP_PART_OF[id], false),
             part: SETUP_PART_OF[id],