@catalyst-cloud/cli 0.14.9 → 0.15.0

package/dist/onboard-automation-management.js

@@ -1,15 +1,33 @@
-/** Rule management is unbuilt. This disposition does not assess the customer's actual rules.
- * Cloud readiness and first-ticket eligibility must still reject conflicting or unreadable rules.
- */
-export function onboardAutomationManagementAdapter(input = {}) {
+import { selectedOnboardTeam } from "./onboard-existing.js";
+/** Setup cannot change Linear's pull request automations. It reports what cloud readiness saw for
+ * the selected team, as the workflow step recorded it, and never reads the network itself. Only a
+ * fresh record for the same team proves "nothing to change"; anything else stays the plain skip,
+ * which keeps counting as satisfied because readiness and first-ticket eligibility check again. */
+export function onboardAutomationManagementAdapter() {
     return {
-        check: async (_ctx, _journal, signal) => {
+        check: async (ctx, journal, signal) => {
             if (signal?.aborted)
                 return { state: "waiting", reason: "interrupted" };
-            input.message?.("Linear automation management is unavailable. Setup made no automation change. Cloud readiness still checks your existing rules.");
-            if (signal?.aborted)
-                return { state: "waiting", reason: "interrupted" };
-            return { state: "skipped", reason: "automation_management_unavailable" };
+            const skip = {
+                state: "skipped",
+                reason: "automation_management_unavailable",
+            };
+            const adopt = journal.steps.find((step) => step.id === "linear.adopt");
+            const team = selectedOnboardTeam(journal);
+            const evidence = adopt?.state === "done" ? adopt.evidence : undefined;
+            const checkedAt = evidence?.checkedAt;
+            const automations = evidence?.automations;
+            if (!team ||
+                evidence?.team !== team ||
+                typeof checkedAt !== "number" ||
+                ctx.now().getTime() - checkedAt >= 300_000 ||
+                ctx.now().getTime() < checkedAt ||
+                typeof automations !== "string" ||
+                !/^(?:none|(?:open|review|ready|merge)(?:,(?:open|review|ready|merge))*)$/.test(automations))
+                return skip;
+            return automations === "none"
+                ? { state: "done", reason: "automations_compatible" }
+                : { ...skip, evidence: { automations } };
         },
     };
 }

package/dist/onboard-capacity.js

@@ -104,7 +104,7 @@ const selection = (journal) => JSON.stringify([
     selectedOnboardTeam(journal),
     selectedOnboardRepositories(journal),
 ]);
-async function liveTeamKey(ctx, teamId, signal) {
+export async function liveTeamKey(ctx, teamId, signal) {
     const read = await readExistingOnboardJson(ctx, "/api/v1/agent/teams", signal);
     if ("reason" in read)
         return null;
@@ -132,6 +132,15 @@ async function liveTeamKey(ctx, teamId, signal) {
     }
     return selected;
 }
+/** Whether `teamKey`'s pool admits hosts, from a fresh capacity read. Null when the read is
+ * unavailable, stale or does not name the team. */
+export async function onboardTeamAdmission(ctx, teamKey, signal) {
+    const read = await readExistingOnboardJson(ctx, route, signal);
+    if ("reason" in read)
+        return null;
+    const teams = snapshot(read.body, ctx.now().getTime())?.buckets.flatMap((b) => b.teams.filter((t) => t.key === teamKey));
+    return teams?.length ? teams.some((t) => t.admission) : null;
+}
 async function liveIdentity(ctx, journal, signal) {
     const read = await readExistingOnboardJson(ctx, "/api/v1/me", signal);
     if ("reason" in read)

package/dist/onboard-existing.js

@@ -1,5 +1,7 @@
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { CliError } from "./errors.js";
+import { onboardReasonText } from "./onboard-next.js";
+import { CREATE_TEAM_CHOICE, postNewTeam, teamCreateOffer, } from "./onboard-team-create.js";
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 const waiting = (reason) => ({
     state: "waiting",
@@ -9,6 +11,25 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
     ? value
     : null;
 const label = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 120);
+/** A team this setup created whose workflow adoption has not been seen yet: kept so a resume can
+ * select it once it is adopted, and so its retry command stays on screen until then. */
+export function createdOnboardTeam(journal) {
+    const step = journal?.steps.find((row) => row.id === "linear.team");
+    if (step?.state !== "waiting" || step.reason !== "team_created_not_adopted")
+        return undefined;
+    const id = step.evidence?.team, key = step.evidence?.teamKey;
+    return typeof id === "string" &&
+        idPattern.test(id) &&
+        typeof key === "string" &&
+        idPattern.test(key)
+        ? { id, key }
+        : undefined;
+}
+const notAdopted = (team) => ({
+    state: "waiting",
+    reason: "team_created_not_adopted",
+    evidence: { team: team.id, teamKey: team.key },
+});
 /** A receipt keeps an explicit selection, never the team used to inspect the tenant grant. */
 export function selectedOnboardTeam(journal) {
     const step = journal?.steps.find((row) => row.id === "linear.team");
@@ -144,8 +165,17 @@ async function observe(ctx, id, signal) {
     }
     return { checkedAt: row.checkedAt, revision: row.workflowRev, checks };
 }
-export function existingLinearAdapters(args, choose) {
+export function existingLinearAdapters(args, choose, nameNewTeam, message = () => { }) {
     let chosen;
+    let uncertain;
+    const uncertainResult = (state = "waiting") => uncertain?.key
+        ? {
+            state,
+            reason: "team_create_unverified",
+            evidence: { teamKey: uncertain.key },
+        }
+        : undefined;
+    const stopTeam = (reason) => uncertainResult() ?? waiting(reason);
     const requested = (teams, journal) => {
         const explicit = args.flags.team;
         if (typeof explicit === "string") {
@@ -155,24 +185,38 @@ export function existingLinearAdapters(args, choose) {
             const keys = teams.filter((team) => team.key === explicit);
             return keys.length === 1 ? keys[0] : undefined;
         }
-        const saved = chosen ?? selectedOnboardTeam(journal);
+        const saved = chosen ?? selectedOnboardTeam(journal) ?? createdOnboardTeam(journal)?.id;
         return saved ? teams.find((team) => team.id === saved) : undefined;
     };
     const teamCheck = async (ctx, journal, signal) => {
+        const prior = journal.steps.find((step) => step.id === "linear.team");
+        const key = prior?.evidence?.teamKey;
+        if (prior?.reason === "team_create_unverified" &&
+            typeof key === "string" &&
+            /^[A-Z][A-Z0-9]{0,6}$/.test(key))
+            uncertain = { key, problem: onboardReasonText(prior) };
+        const pending = createdOnboardTeam(journal);
         const list = await readOnboardTeamInventory(ctx, signal);
         if ("reason" in list)
-            return waiting(list.reason);
+            return pending ? notAdopted(pending) : stopTeam(list.reason);
         if (!list.teams.length)
-            return waiting("team_inventory_empty");
+            return pending ? notAdopted(pending) : stopTeam("team_inventory_empty");
         const team = requested(list.teams, journal);
         if (!team) {
+            // The census lists a created team once its workflow is adopted (`catalyst team adopt`).
+            if (pending)
+                return notAdopted(pending);
             if (typeof args.flags.team === "string")
-                return waiting("team_selection_unverified");
-            return choose ? { state: "pending" } : waiting("team_choice_required");
+                return stopTeam("team_selection_unverified");
+            return choose
+                ? (uncertainResult("pending") ?? { state: "pending" })
+                : stopTeam("team_choice_required");
         }
         const result = await observe(ctx, team.id, signal);
         if (!result || result.checks.get("team_visible") !== "pass")
-            return waiting("team_selection_unverified");
+            return pending
+                ? notAdopted(pending)
+                : stopTeam("team_selection_unverified");
         return {
             state: "done",
             evidence: {
@@ -211,32 +255,89 @@ export function existingLinearAdapters(args, choose) {
             act: async (ctx, journal, signal) => {
                 const list = await readOnboardTeamInventory(ctx, signal);
                 if ("reason" in list)
-                    return waiting(list.reason);
-                if (!list.teams.length)
-                    return waiting("team_inventory_empty");
+                    return stopTeam(list.reason);
                 if (!choose)
-                    return waiting("team_choice_required");
-                let remove = () => { };
-                const answer = await new Promise((resolve, reject) => {
-                    const stopped = () => resolve(null);
-                    if (signal?.aborted) {
-                        stopped();
-                        return;
+                    return stopTeam(list.teams.length ? "team_choice_required" : "team_inventory_empty");
+                let offer = nameNewTeam && typeof args.flags.team !== "string"
+                    ? await teamCreateOffer(ctx, journal, signal)
+                    : undefined;
+                if (signal?.aborted)
+                    return stopTeam("interrupted");
+                if (!list.teams.length && !offer?.available)
+                    return stopTeam("team_inventory_empty");
+                const ask = (question) => {
+                    let remove = () => { };
+                    return new Promise((resolve, reject) => {
+                        const stopped = () => resolve(null);
+                        if (signal?.aborted) {
+                            stopped();
+                            return;
+                        }
+                        signal?.addEventListener("abort", stopped, { once: true });
+                        remove = () => signal?.removeEventListener("abort", stopped);
+                        Promise.resolve()
+                            .then(() => (signal?.aborted ? null : question()))
+                            .then(resolve, reject);
+                    }).finally(() => remove());
+                };
+                if (uncertain?.problem)
+                    message(uncertain.problem);
+                // Going back from naming, or Linear refusing the person, returns here; each pass asks again.
+                for (;;) {
+                    const answer = await ask(() => choose(list.teams.map((team) => ({ ...team })), offer ? { ...offer } : undefined));
+                    if (!answer || signal?.aborted)
+                        return stopTeam("interrupted");
+                    if (answer !== CREATE_TEAM_CHOICE) {
+                        if (!list.teams.some((team) => team.id === answer))
+                            return stopTeam("team_selection_unverified");
+                        chosen = answer;
+                        return teamCheck(ctx, journal, signal);
+                    }
+                    if (!offer?.available || !nameNewTeam)
+                        return stopTeam("team_selection_unverified");
+                    let question = uncertain ? { ...uncertain } : {};
+                    for (;;) {
+                        const named = await ask(() => nameNewTeam({ ...question }));
+                        if (signal?.aborted)
+                            return stopTeam("interrupted");
+                        if (!named)
+                            break;
+                        const reply = await postNewTeam(ctx, journal, named, signal, uncertain?.key);
+                        if (reply.kind === "reask") {
+                            question = { ...named, problem: reply.message };
+                            continue;
+                        }
+                        if (reply.kind === "refused") {
+                            message(reply.linearMessage
+                                ? `${reply.message}\nLinear said: ${reply.linearMessage}`
+                                : reply.message);
+                            offer = { available: false, reason: reply.message };
+                            if (!list.teams.length)
+                                return stopTeam("team_inventory_empty");
+                            break;
+                        }
+                        if (reply.kind === "failed") {
+                            if (reply.message)
+                                message(reply.message);
+                            // The key rides along when the team may exist, so the next action can name it.
+                            return reply.key
+                                ? {
+                                    state: "waiting",
+                                    reason: reply.reason,
+                                    evidence: { teamKey: reply.key },
+                                }
+                                : stopTeam(reply.reason);
+                        }
+                        const team = reply.team;
+                        if (!reply.adoption.adopted) {
+                            message(`Created Linear team ${team.name} (${team.key}), but Catalyst's workflow is not set up on it yet: ${reply.adoption.reason}`);
+                            return notAdopted(team);
+                        }
+                        message(`Created Linear team ${team.name} (${team.key}) and set up Catalyst's workflow on it.`);
+                        chosen = team.id;
+                        return teamCheck(ctx, journal, signal);
                     }
-                    signal?.addEventListener("abort", stopped, { once: true });
-                    remove = () => signal?.removeEventListener("abort", stopped);
-                    Promise.resolve()
-                        .then(() => signal?.aborted
-                        ? null
-                        : choose(list.teams.map((team) => ({ ...team }))))
-                        .then(resolve, reject);
-                }).finally(() => remove());
-                if (!answer || signal?.aborted)
-                    return waiting("interrupted");
-                if (!list.teams.some((team) => team.id === answer))
-                    return waiting("team_selection_unverified");
-                chosen = answer;
-                return teamCheck(ctx, journal, signal);
+                }
             },
         },
     };

package/dist/onboard-github.js

@@ -1,6 +1,7 @@
 import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
+import { GITHUB_PERMISSION, githubInstallationPage, parsePermissions, } from "./onboard-permissions.js";
 const STATUS = "/api/v1/me/connections/github/workspace";
 const HANDOFF = "/connect/github/workspace/handoff";
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
@@ -19,6 +20,16 @@ const waiting = (reason) => ({
     reason,
 });
 const nullableText = (v) => v === null || typeof v === "string";
+const orgPattern = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;
+const repositoryPattern = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/;
+const coverageUnknown = new Set([
+    "registry-unavailable",
+    "over-bound",
+    "not-run",
+    "installation-unverified",
+    "unreachable",
+    "listing-truncated",
+]);
 /** A bounded read never rotates credentials or writes a token after the receipt lock is released. */
 async function read(ctx, journal, path, timeoutMs, external) {
     const cfg = loadConfig(ctx.home);
@@ -116,6 +127,9 @@ function observation(body, now) {
         row.installations.length + row.pending.length > 100)
         return waiting("github_installation_status_shape");
     const ids = [];
+    const granted = [];
+    let outdated;
+    let permissionsUnverified = false;
     let unknown = false;
     let allConnected = row.installations.length > 0;
     let checkedAt = now + 30_000;
@@ -128,7 +142,7 @@ function observation(body, now) {
             ids.includes(item.installationId) ||
             !nullableText(item.githubOrg) ||
             (typeof item.githubOrg === "string" &&
-                !/^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(item.githubOrg)) ||
+                !orgPattern.test(item.githubOrg)) ||
             !verification)
             return waiting("github_installation_status_shape");
         ids.push(item.installationId);
@@ -152,20 +166,41 @@ function observation(body, now) {
                 verification.missing.length > 128 ||
                 !verification.missing.every((name) => typeof name === "string" &&
                     (/^[A-Za-z0-9_-]{1,128}$/.test(name) ||
-                        /^[A-Za-z0-9_-]{1,80} \((?:read|write|admin)\)$/.test(name)))))
+                        GITHUB_PERMISSION.test(name)))))
             return waiting("github_installation_status_shape");
         checkedAt = Math.min(checkedAt, verification.checkedAt);
         if (verification.state === "unreachable")
             unknown = true;
         if (verification.state !== "connected")
             allConnected = false;
+        // CTC-4629: the typed verdict must agree with the verification it was derived from.
+        const org = typeof item.githubOrg === "string" ? item.githubOrg : null;
+        const permissions = parsePermissions(item.permissions, {
+            grant: "github-installation",
+            action: "review-permissions",
+            label: GITHUB_PERMISSION,
+            actorFor: (url) => githubInstallationPage(url, item.installationId, org, true)
+                ?.actor ?? null,
+        });
+        if (permissions === null ||
+            (permissions?.state === "current" &&
+                verification.state !== "connected") ||
+            (permissions?.state === "outdated" &&
+                verification.state !== "missing-scope"))
+            return waiting("github_installation_status_shape");
+        if (permissions?.state === "current")
+            granted.push(`${org ?? item.installationId}: ${permissions.granted.join(", ")}`);
+        if (permissions?.state === "unknown")
+            permissionsUnverified = true;
+        if (permissions?.state === "outdated" && !outdated)
+            outdated = permissionsOutdated(item.installationId, org, permissions);
     }
     for (const value of row.pending) {
         const pending = object(value);
         if (!pending ||
             !nullableText(pending.githubOrg) ||
             (typeof pending.githubOrg === "string" &&
-                !/^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(pending.githubOrg)) ||
+                !orgPattern.test(pending.githubOrg)) ||
             typeof pending.requestedAt !== "number" ||
             !Number.isFinite(pending.requestedAt) ||
             pending.requestedAt < 0)
@@ -173,19 +208,146 @@ function observation(body, now) {
     }
     if (row.connected !== allConnected)
         return waiting("github_installation_status_shape");
+    const coverage = repositoryCoverage(row.repositories, ids);
+    if (coverage === null)
+        return waiting("github_installation_status_shape");
     if (unknown)
         return waiting("github_installation_status_unavailable");
+    if (outdated)
+        return outdated;
     if (!allConnected)
         return { state: "pending" };
+    if (permissionsUnverified)
+        return waiting("github_app_permissions_unverified");
+    if (coverage)
+        return coverage;
     return {
         state: "done",
         evidence: {
             provider: "github",
             installation: JSON.stringify(ids),
             checkedAt,
+            ...(granted.length ? { granted: granted.join("; ") } : {}),
         },
     };
 }
+/** A wait whose fix is a page on github.com: polling longer cannot finish it. */
+const githubSideAction = (result) => result.state === "waiting" &&
+    (result.reason === "github_app_permissions_outdated" ||
+        result.reason === "github_app_repository_missing" ||
+        result.reason === "github_app_permissions_unverified" ||
+        result.reason === "github_app_repository_access_unverified");
+/** A pending permission request is the org's to accept on GitHub, never a new installation. */
+function permissionsOutdated(installation, org, permissions) {
+    const login = githubInstallationPage(new URL(permissions.url), installation, org, true)?.login;
+    const name = org ?? login;
+    return {
+        state: "waiting",
+        reason: "github_app_permissions_outdated",
+        evidence: {
+            provider: "github",
+            grant: "github-installation",
+            installation,
+            ...(name ? { org: name } : {}),
+            granted: permissions.granted.join(", "),
+            missing: permissions.missing.join(", "),
+            url: permissions.url,
+            actor: permissions.actor,
+        },
+    };
+}
+/** CTC-4629: whether the installations reach every repository the account's projects register.
+ * `undefined` when covered or when an older cloud sent no verdict; `null` for a malformed one. */
+function repositoryCoverage(value, installations) {
+    if (value === undefined)
+        return undefined;
+    const row = object(value);
+    if (!row)
+        return null;
+    if (row.state === "unknown")
+        return typeof row.reason === "string" && coverageUnknown.has(row.reason)
+            ? waiting("github_app_repository_access_unverified")
+            : null;
+    const names = (list) => Array.isArray(list) &&
+        list.length <= 50 &&
+        list.every((name) => typeof name === "string" && repositoryPattern.test(name));
+    if (!names(row.checked))
+        return null;
+    const checked = row.checked;
+    if (row.state === "covered")
+        return row.missing === undefined && row.unchecked === undefined ? undefined : null;
+    if (row.state !== "missing" ||
+        !Array.isArray(row.missing) ||
+        row.missing.length < 1 ||
+        row.missing.length > 50 ||
+        !Array.isArray(row.unchecked) ||
+        row.unchecked.length > 50 ||
+        !row.unchecked.every((value) => {
+            const item = object(value);
+            return (!!item &&
+                names([item.repository]) &&
+                !checked.includes(item.repository) &&
+                typeof item.reason === "string" &&
+                coverageUnknown.has(item.reason));
+        }))
+        return null;
+    const results = [];
+    for (const value of row.missing) {
+        const item = object(value);
+        if (!item ||
+            typeof item.repository !== "string" ||
+            !repositoryPattern.test(item.repository) ||
+            !checked.includes(item.repository) ||
+            !nullableText(item.githubOrg) ||
+            (typeof item.githubOrg === "string" && !orgPattern.test(item.githubOrg)))
+            return null;
+        const org = item.githubOrg;
+        if (item.installationId === null) {
+            if (item.settingsUrl !== null || item.actor !== null)
+                return null;
+            results.push({
+                state: "pending",
+                reason: "github_app_repository_not_installed",
+                evidence: {
+                    provider: "github",
+                    repository: item.repository,
+                    ...(org ? { org } : {}),
+                },
+            });
+            continue;
+        }
+        if (typeof item.installationId !== "string" ||
+            !installations.includes(item.installationId) ||
+            typeof item.settingsUrl !== "string" ||
+            item.settingsUrl.length > 2048)
+            return null;
+        let url;
+        try {
+            url = new URL(item.settingsUrl);
+        }
+        catch {
+            return null;
+        }
+        const page = githubInstallationPage(url, item.installationId, org, false);
+        if (!page || url.protocol !== "https:" || url.username || url.password || url.search || url.hash || page.actor !== item.actor)
+            return null;
+        results.push({
+            state: "waiting",
+            reason: "github_app_repository_missing",
+            evidence: {
+                provider: "github",
+                installation: item.installationId,
+                ...(org ? { org } : {}),
+                repository: item.repository,
+                url: url.toString(),
+                actor: page.actor,
+            },
+        });
+    }
+    // A repository an existing installation lacks is fixed on GitHub; one with no installation at all
+    // is this step's own install action, which runs only once nothing else waits.
+    return results.find((result) => result.state === "waiting") ?? results[0];
+}
 function safeHandoff(body, ctx) {
     const row = object(body);
     const cfg = loadConfig(ctx.home);
@@ -263,6 +425,8 @@ export function githubInstallationAdapter(options) {
                 return before.result;
             if (before.unsupported)
                 return waiting("cloud_capability_unavailable");
+            if (!options.wait)
+                return waiting("github_installation_approval_required");
             const start = await read(ctx, journal, `${STATUS}/start`, timeoutMs, signal);
             if ("status" in start && [404, 405].includes(start.status))
                 return waiting("cloud_capability_unavailable");
@@ -291,7 +455,6 @@ export function githubInstallationAdapter(options) {
                     state: "refused",
                     reason: "github_installation_admin_required",
                 };
-            ctx.stderr("Approve the GitHub App installation in your browser. Your personal GitHub connection is checked separately.");
             // The signed URL is transient credential material: only the browser receives it.
             let browserUnavailable = false;
             try {
@@ -316,7 +479,8 @@ export function githubInstallationAdapter(options) {
                             outcome: "waiting",
                             reason: "cloud_capability_unavailable",
                         };
-                    if (latest.reason === "github_installation_login_refresh_required")
+                    if (latest.reason === "github_installation_login_refresh_required" ||
+                        githubSideAction(latest))
                         return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
@@ -330,7 +494,8 @@ export function githubInstallationAdapter(options) {
             const result = options.wait
                 ? await options.wait("Waiting for GitHub App approval", run)
                 : await run();
-            if (result.state === "done")
+            // An installation that now exists but still needs a GitHub-side change keeps its action URL.
+            if (result.state === "done" || githubSideAction(latest))
                 return latest;
             return browserUnavailable && result.reason === "consent_timeout"
                 ? waiting("github_installation_browser_unavailable")