@catalyst-cloud/cli 0.14.6 → 0.14.8

package/dist/onboard-capacity.js

@@ -0,0 +1,226 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { verifyOnboardRoutes } from "./onboard-capabilities.js";
+import { readExistingOnboardJson, selectedOnboardTeam, } from "./onboard-existing.js";
+import { readOnboardRepositoryInventory, selectedOnboardRepositories, } from "./onboard-repositories.js";
+const route = "/api/v1/me/runner-capacity";
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
+const integer = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const text = (value) => typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= 256 &&
+    !Array.from(value).some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127);
+const waiting = (reason) => ({
+    state: "waiting",
+    reason,
+});
+function snapshot(value, now) {
+    const body = object(value);
+    if (!body ||
+        body.status !== "ok" ||
+        body.scope !== "mapped-team-defaults" ||
+        !integer(body.observedAtMs) ||
+        body.observedAtMs < now - 30_000 ||
+        body.observedAtMs > now + 5_000 ||
+        !Array.isArray(body.buckets) ||
+        body.buckets.length > 500)
+        return null;
+    const buckets = [], seen = new Set(), seenTeam = new Set();
+    let totalTeams = 0;
+    for (const value of body.buckets) {
+        const b = object(value);
+        if (!b ||
+            !text(b.repoId) ||
+            seen.has(b.repoId) ||
+            !integer(b.effectiveLimit) ||
+            !integer(b.occupiedUnits) ||
+            !Array.isArray(b.teams) ||
+            !b.teams.length ||
+            b.teams.length > 500)
+            return null;
+        seen.add(b.repoId);
+        totalTeams += b.teams.length;
+        if (totalTeams > 1000)
+            return null;
+        const teams = [];
+        let minimum = Number.MAX_SAFE_INTEGER;
+        for (const value of b.teams) {
+            const t = object(value);
+            if (!t ||
+                !text(t.teamKey) ||
+                seenTeam.has(t.teamKey) ||
+                !integer(t.defaultLimit) ||
+                t.defaultLimit < 1 ||
+                !(t.configuredLimit === null ||
+                    (integer(t.configuredLimit) && t.configuredLimit > 0)) ||
+                typeof t.paused !== "boolean" ||
+                typeof t.admissionEnabled !== "boolean" ||
+                !integer(t.effectiveTeamLimit))
+                return null;
+            const configured = t.configuredLimit === null ? t.defaultLimit : t.configuredLimit;
+            if (t.source !== (t.configuredLimit === null ? "default" : "configured") ||
+                t.effectiveTeamLimit !== (t.paused ? 0 : configured))
+                return null;
+            const remaining = t.admissionEnabled
+                ? Math.max(0, b.effectiveLimit - b.occupiedUnits)
+                : null;
+            if (t.remainingUnits !== remaining)
+                return null;
+            seenTeam.add(t.teamKey);
+            minimum = Math.min(minimum, t.effectiveTeamLimit);
+            teams.push({ key: t.teamKey, admission: t.admissionEnabled, remaining });
+        }
+        if (minimum !== b.effectiveLimit)
+            return null;
+        buckets.push({
+            repo: b.repoId,
+            limit: b.effectiveLimit,
+            occupied: b.occupiedUnits,
+            teams,
+        });
+    }
+    return { at: body.observedAtMs, buckets };
+}
+function binding(ctx, journal) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.user ||
+        !["owner", "admin"].includes(cfg.user.role) ||
+        cfg.account !== (journal.account ?? journal.tenant) ||
+        cfg.user.id !== journal.membershipId ||
+        !journal.baseUrl ||
+        normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(journal.baseUrl))
+        return null;
+    return JSON.stringify([
+        cfg.account,
+        cfg.user.id,
+        cfg.user.role,
+        normalizeBaseUrl(cfg.baseUrl),
+        cfg.permissions,
+        cfg.key ?? cfg.auth?.sessionId,
+    ]);
+}
+const selection = (journal) => JSON.stringify([
+    selectedOnboardTeam(journal),
+    selectedOnboardRepositories(journal),
+]);
+async function liveTeamKey(ctx, teamId, signal) {
+    const read = await readExistingOnboardJson(ctx, "/api/v1/agent/teams", signal);
+    if ("reason" in read)
+        return null;
+    const body = object(read.body), live = object(body?.liveTeamRead);
+    if (!body ||
+        !Array.isArray(body.teams) ||
+        body.teams.length > 1000 ||
+        (live?.error !== undefined && live.error !== null))
+        return null;
+    const ids = new Set(), keys = new Set();
+    let selected = null;
+    for (const value of body.teams) {
+        const team = object(value);
+        if (!team ||
+            !text(team.teamId) ||
+            !text(team.teamKey) ||
+            !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(team.teamKey) ||
+            ids.has(team.teamId) ||
+            keys.has(team.teamKey))
+            return null;
+        ids.add(team.teamId);
+        keys.add(team.teamKey);
+        if (team.teamId === teamId)
+            selected = team.teamKey;
+    }
+    return selected;
+}
+async function liveIdentity(ctx, journal, signal) {
+    const read = await readExistingOnboardJson(ctx, "/api/v1/me", signal);
+    if ("reason" in read)
+        return false;
+    const me = object(read.body), user = object(me?.user), cfg = loadConfig(ctx.home);
+    return (!!cfg?.user &&
+        me?.account === (journal.account ?? journal.tenant) &&
+        user?.id === cfg.user.id &&
+        user.role === cfg.user.role &&
+        ["owner", "admin"].includes(cfg.user.role) &&
+        me?.principal === cfg.principal);
+}
+/** Fresh advisory for the selected team's DEFAULT mapped repo. It grants no lease and does not
+ * establish provider eligibility, host liveness or selected-repo overrides. No extra question. */
+export function onboardCapacityAdapter(input = {}) {
+    return {
+        check: async (ctx, journal, external) => {
+            if (external?.aborted)
+                return waiting("interrupted");
+            const expected = binding(ctx, journal), selected = selection(journal), teamId = selectedOnboardTeam(journal), repos = selectedOnboardRepositories(journal);
+            if (!expected)
+                return waiting("capacity_identity_unverified");
+            if (!teamId || repos.length !== 1 || repos[0].teamId !== teamId)
+                return waiting("capacity_context_unverified");
+            const controller = new AbortController(), signal = external
+                ? AbortSignal.any([external, controller.signal])
+                : controller.signal;
+            const timer = setTimeout(() => controller.abort(), 30_000);
+            const current = () => !signal.aborted &&
+                binding(ctx, journal) === expected &&
+                selection(journal) === selected;
+            const pause = (reason) => waiting(external?.aborted
+                ? "interrupted"
+                : controller.signal.aborted
+                    ? "capacity_unavailable"
+                    : reason);
+            try {
+                const support = await verifyOnboardRoutes(ctx, journal, [{ method: "GET", path: route }], signal);
+                if ("reason" in support)
+                    return pause(support.reason);
+                if (!current() ||
+                    !(await liveIdentity(ctx, journal, signal)) ||
+                    !current())
+                    return pause("capacity_identity_unverified");
+                const teamKey = await liveTeamKey(ctx, teamId, signal);
+                if (!teamKey || !current())
+                    return pause("capacity_context_unverified");
+                const inventory = await readOnboardRepositoryInventory(ctx, journal, signal);
+                if ("reason" in inventory ||
+                    !current() ||
+                    !inventory.repositories.some((r) => r.repoId === repos[0].repoId &&
+                        r.teamId === teamId &&
+                        r.owner.toLowerCase() === repos[0].owner.toLowerCase() &&
+                        r.name.toLowerCase() === repos[0].name.toLowerCase()))
+                    return pause("capacity_context_unverified");
+                const read = await readExistingOnboardJson(ctx, route, signal);
+                if ("reason" in read || !current())
+                    return pause("capacity_unavailable");
+                if (!(await liveIdentity(ctx, journal, signal)) || !current())
+                    return pause("capacity_identity_unverified");
+                const observed = snapshot(read.body, ctx.now().getTime());
+                const bucket = observed?.buckets.find((b) => b.repo === repos[0].repoId), mapped = bucket?.teams.find((t) => t.key === teamKey);
+                if (!observed || !bucket || !mapped)
+                    return pause("capacity_context_unverified");
+                if (!mapped.admission || mapped.remaining === null)
+                    return pause("capacity_admission_unverified");
+                if (mapped.remaining === 0)
+                    return pause("capacity_currently_full");
+                input.message?.(`Runner capacity observed: ${bucket.occupied} of ${bucket.limit} units in use. Starting work will check admission again.`);
+                if (!current())
+                    return pause("capacity_identity_unverified");
+                return {
+                    state: "done",
+                    evidence: {
+                        repoId: bucket.repo,
+                        effectiveLimit: bucket.limit,
+                        occupiedUnits: bucket.occupied,
+                        remainingUnits: mapped.remaining,
+                        observedAtMs: observed.at,
+                        advisory: true,
+                    },
+                };
+            }
+            catch {
+                return pause(external?.aborted ? "interrupted" : "capacity_unavailable");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}

package/dist/onboard-existing.js

@@ -1,12 +1,17 @@
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { CliError } from "./errors.js";
 const idPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
-const waiting = (reason) => ({ state: "waiting", reason });
-const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+const waiting = (reason) => ({
+    state: "waiting",
+    reason,
+});
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
 const label = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").slice(0, 120);
 /** 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");
+    const step = journal?.steps.find((row) => row.id === "linear.team");
     const id = step?.state === "done" ? step.evidence?.team : undefined;
     return typeof id === "string" && idPattern.test(id) ? id : undefined;
 }
@@ -15,15 +20,23 @@ export async function readExistingOnboardJson(ctx, path, external) {
     const cfg = loadConfig(ctx.home);
     if (!cfg?.user)
         return { reason: "personal_login_required" };
+    const personId = cfg.user.id;
     // Identity verification refreshes before adapters run. These bounded reads never rotate a grant
     // that could finish after the engine has released its lock.
-    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);
+    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 { reason: "team_read_login_refresh_required" };
     const deadline = new AbortController();
     const timer = setTimeout(() => deadline.abort(), 30_000);
-    const signal = external ? AbortSignal.any([external, deadline.signal]) : deadline.signal;
+    const signal = external
+        ? AbortSignal.any([external, deadline.signal])
+        : deadline.signal;
     let remove = () => { };
     try {
         return await new Promise((resolve, reject) => {
@@ -36,17 +49,32 @@ export async function readExistingOnboardJson(ctx, path, external) {
             }
             signal.addEventListener("abort", stopped, { once: true });
             remove = () => signal.removeEventListener("abort", stopped);
-            Promise.resolve().then(async () => {
+            Promise.resolve()
+                .then(async () => {
                 if (signal.aborted)
                     return { reason: "team_read_unavailable" };
                 const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}${path}`, {
-                    headers: { authorization: `Bearer ${bearer}`, accept: "application/json" }, signal,
+                    redirect: "error",
+                    headers: {
+                        authorization: `Bearer ${bearer}`,
+                        accept: "application/json",
+                    },
+                    signal,
                 });
                 if (response.status !== 200)
                     return { reason: "team_read_unavailable" };
                 const body = await response.json();
+                const current = loadConfig(ctx.home);
+                if (!current?.user ||
+                    current.account !== cfg.account ||
+                    current.user.id !== personId ||
+                    normalizeBaseUrl(current.baseUrl) !== normalizeBaseUrl(cfg.baseUrl))
+                    return { reason: "team_read_identity_unverified" };
                 return { body };
-            }).then(value => signal.aborted ? stopped() : resolve(value), () => signal.aborted ? stopped() : resolve({ reason: "team_read_unavailable" }));
+            })
+                .then((value) => (signal.aborted ? stopped() : resolve(value)), () => signal.aborted
+                ? stopped()
+                : resolve({ reason: "team_read_unavailable" }));
         });
     }
     finally {
@@ -54,7 +82,7 @@ export async function readExistingOnboardJson(ctx, path, external) {
         remove();
     }
 }
-async function inventory(ctx, signal) {
+export async function readOnboardTeamInventory(ctx, signal) {
     const read = await readExistingOnboardJson(ctx, "/api/v1/agent/teams", signal);
     if ("reason" in read)
         return read;
@@ -68,11 +96,19 @@ async function inventory(ctx, signal) {
     const seen = new Set();
     for (const value of body.teams) {
         const row = object(value);
-        if (!row || typeof row.teamId !== "string" || !idPattern.test(row.teamId) || seen.has(row.teamId) ||
-            typeof row.teamKey !== "string" || typeof row.teamName !== "string")
+        if (!row ||
+            typeof row.teamId !== "string" ||
+            !idPattern.test(row.teamId) ||
+            seen.has(row.teamId) ||
+            typeof row.teamKey !== "string" ||
+            typeof row.teamName !== "string")
             return { reason: "team_inventory_shape" };
         seen.add(row.teamId);
-        teams.push({ id: row.teamId, key: label(row.teamKey), name: label(row.teamName) });
+        teams.push({
+            id: row.teamId,
+            key: label(row.teamKey),
+            name: label(row.teamName),
+        });
     }
     return { teams };
 }
@@ -82,14 +118,27 @@ async function observe(ctx, id, signal) {
         return null;
     const row = object(object(read.body)?.readiness);
     // The GET owns expiry/revision freshness. Do not invent an expiresAt absent from its wire shape.
-    if (!row || row.teamId !== id || typeof row.status !== "string" || !["ready", "degraded", "blocked"].includes(row.status) || typeof row.checkedAt !== "number" ||
-        !Number.isFinite(row.checkedAt) || row.checkedAt < 0 || row.checkedAt > ctx.now().getTime() ||
-        typeof row.workflowRev !== "number" || !Number.isSafeInteger(row.workflowRev) || row.workflowRev < 0 || !Array.isArray(row.checks))
+    if (!row ||
+        row.teamId !== id ||
+        typeof row.status !== "string" ||
+        !["ready", "degraded", "blocked"].includes(row.status) ||
+        typeof row.checkedAt !== "number" ||
+        !Number.isFinite(row.checkedAt) ||
+        row.checkedAt < 0 ||
+        row.checkedAt > ctx.now().getTime() ||
+        typeof row.workflowRev !== "number" ||
+        !Number.isSafeInteger(row.workflowRev) ||
+        row.workflowRev < 0 ||
+        !Array.isArray(row.checks))
         return null;
     const checks = new Map();
     for (const value of row.checks) {
         const check = object(value);
-        if (!check || typeof check.id !== "string" || checks.has(check.id) || typeof check.state !== "string" || !["pass", "fail", "unknown"].includes(check.state))
+        if (!check ||
+            typeof check.id !== "string" ||
+            checks.has(check.id) ||
+            typeof check.state !== "string" ||
+            !["pass", "fail", "unknown"].includes(check.state))
             return null;
         checks.set(check.id, check.state);
     }
@@ -100,17 +149,17 @@ export function existingLinearAdapters(args, choose) {
     const requested = (teams, journal) => {
         const explicit = args.flags.team;
         if (typeof explicit === "string") {
-            const ids = teams.filter(team => team.id === explicit);
+            const ids = teams.filter((team) => team.id === explicit);
             if (ids.length === 1)
                 return ids[0];
-            const keys = teams.filter(team => team.key === explicit);
+            const keys = teams.filter((team) => team.key === explicit);
             return keys.length === 1 ? keys[0] : undefined;
         }
         const saved = chosen ?? selectedOnboardTeam(journal);
-        return saved ? teams.find(team => team.id === saved) : undefined;
+        return saved ? teams.find((team) => team.id === saved) : undefined;
     };
     const teamCheck = async (ctx, journal, signal) => {
-        const list = await inventory(ctx, signal);
+        const list = await readOnboardTeamInventory(ctx, signal);
         if ("reason" in list)
             return waiting(list.reason);
         if (!list.teams.length)
@@ -124,23 +173,43 @@ export function existingLinearAdapters(args, choose) {
         const result = await observe(ctx, team.id, signal);
         if (!result || result.checks.get("team_visible") !== "pass")
             return waiting("team_selection_unverified");
-        return { state: "done", evidence: { team: team.id, teamKey: team.key, checkedAt: result.checkedAt, revision: result.revision } };
+        return {
+            state: "done",
+            evidence: {
+                team: team.id,
+                teamKey: team.key,
+                checkedAt: result.checkedAt,
+                revision: result.revision,
+            },
+        };
     };
     return {
-        "linear.workspace": { check: async (ctx, journal, signal) => {
-                const list = await inventory(ctx, signal);
+        "linear.workspace": {
+            check: async (ctx, journal, signal) => {
+                const list = await readOnboardTeamInventory(ctx, signal);
                 if ("reason" in list)
                     return waiting(list.reason);
                 const candidate = requested(list.teams, journal) ?? list.teams[0];
                 if (!candidate)
                     return waiting("linear_workspace_unverified");
                 const result = await observe(ctx, candidate.id, signal);
-                return result?.checks.get("oauth_scope") === "pass" && result.checks.get("token_live") === "pass"
-                    ? { state: "done", evidence: { checkedAt: result.checkedAt, revision: result.revision } }
+                return result?.checks.get("oauth_scope") === "pass" &&
+                    result.checks.get("token_live") === "pass"
+                    ? {
+                        state: "done",
+                        evidence: {
+                            checkedAt: result.checkedAt,
+                            revision: result.revision,
+                        },
+                    }
                     : waiting("linear_workspace_unverified");
-            }, act: async () => waiting("cloud_capability_unavailable") },
-        "linear.team": { check: teamCheck, act: async (ctx, journal, signal) => {
-                const list = await inventory(ctx, signal);
+            },
+            act: async () => waiting("cloud_capability_unavailable"),
+        },
+        "linear.team": {
+            check: teamCheck,
+            act: async (ctx, journal, signal) => {
+                const list = await readOnboardTeamInventory(ctx, signal);
                 if ("reason" in list)
                     return waiting(list.reason);
                 if (!list.teams.length)
@@ -156,14 +225,19 @@ export function existingLinearAdapters(args, choose) {
                     }
                     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);
+                    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))
+                if (!list.teams.some((team) => team.id === answer))
                     return waiting("team_selection_unverified");
                 chosen = answer;
                 return teamCheck(ctx, journal, signal);
-            } },
+            },
+        },
     };
 }

package/dist/onboard-file-snapshot.js

@@ -0,0 +1,45 @@
+import { constants, closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { CliError } from "./errors.js";
+/** Bounded, regular-file snapshot for the review precheck. This is not a CAS primitive. */
+export function onboardFileSnapshot(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error !== null &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return null;
+        throw new CliError("The saved setup files could not be verified. Keep them and try again.", "onboard-file-unverified", 12);
+    }
+    try {
+        const before = fstatSync(fd);
+        const limit = 1024 * 1024;
+        if (!before.isFile() || before.size > limit)
+            throw new Error("invalid file");
+        const bytes = Buffer.alloc(limit + 1);
+        let used = 0;
+        for (;;) {
+            const read = readSync(fd, bytes, used, bytes.length - used, null);
+            used += read;
+            if (used > limit)
+                throw new Error("oversized file");
+            if (read === 0)
+                break;
+        }
+        const after = fstatSync(fd);
+        if (before.size !== after.size ||
+            before.mtimeMs !== after.mtimeMs ||
+            used !== after.size)
+            throw new Error("changed file");
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, used));
+    }
+    catch {
+        throw new CliError("The saved setup files could not be verified. Keep them and try again.", "onboard-file-unverified", 12);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/onboard-github.js

@@ -1,3 +1,4 @@
+import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 const STATUS = "/api/v1/me/connections/github/workspace";
@@ -292,11 +293,15 @@ export function githubInstallationAdapter(options) {
                 };
             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 {
-                options.openBrowser(url);
+                await options.openBrowser(url, signal);
             }
             catch {
-                return waiting("github_installation_browser_unavailable");
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                browserUnavailable = true;
+                ctx.stderr(finishOnTheWeb(current.baseUrl, "connections", "install the GitHub App"));
             }
             let latest = waiting("github_installation_status_unavailable");
             const run = () => pollConsent({
@@ -311,6 +316,8 @@ export function githubInstallationAdapter(options) {
                             outcome: "waiting",
                             reason: "cloud_capability_unavailable",
                         };
+                    if (latest.reason === "github_installation_login_refresh_required")
+                        return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
                     if (latest.state === "refused" || latest.state === "failed")
@@ -323,7 +330,11 @@ export function githubInstallationAdapter(options) {
             const result = options.wait
                 ? await options.wait("Waiting for GitHub App approval", run)
                 : await run();
-            return result.state === "done" ? latest : result;
+            if (result.state === "done")
+                return latest;
+            return browserUnavailable && result.reason === "consent_timeout"
+                ? waiting("github_installation_browser_unavailable")
+                : result;
         },
     };
 }