@catalyst-cloud/cli 0.14.6 → 0.14.8

package/dist/onboard-login-candidate.js

@@ -0,0 +1,261 @@
+import { constants, closeSync, fsyncSync, openSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { DEFAULT_BASE_URL, cliPath, configPathFor, contractPathFor, defaultReplicaDbFor, loadConfig, normalizeBaseUrl, readManifest, writeConfig, } from "./config.js";
+import { contractVersionInRange } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { deviceFlowLogin } from "./oauth.js";
+import { fetchMe } from "./transport.js";
+import { onboardFileSnapshot } from "./onboard-file-snapshot.js";
+const stopped = () => new CliError("Sign-in paused. Your saved connection was not changed.", "onboard-signin-paused", 11);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
+async function bounded(external, ms, run) {
+    const owned = new AbortController();
+    const signal = external
+        ? AbortSignal.any([owned.signal, external])
+        : owned.signal;
+    const timer = setTimeout(() => owned.abort(), ms);
+    let remove = () => { };
+    try {
+        return await new Promise((resolve, reject) => {
+            const abort = () => reject(stopped());
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener("abort", abort, { once: true });
+            remove = () => signal.removeEventListener("abort", abort);
+            Promise.resolve()
+                .then(() => {
+                if (signal.aborted)
+                    throw stopped();
+                return run(signal);
+            })
+                .then((value) => (signal.aborted ? abort() : resolve(value)), reject);
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        remove();
+        owned.abort();
+    }
+}
+function boundedResponse(response, signal) {
+    if (!response.body)
+        return response;
+    let bytes = 0;
+    const limit = new TransformStream({
+        transform(chunk, controller) {
+            if (signal.aborted)
+                throw stopped();
+            bytes += chunk.byteLength;
+            if (bytes > 1024 * 1024)
+                throw new CliError("The sign-in response could not be verified.", "onboard-response-unverified", 11);
+            controller.enqueue(chunk);
+        },
+    });
+    return new Response(response.body.pipeThrough(limit), {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+/** Staging keeps tokens in this closure. Neither config nor receipt nor auth caches is changed. */
+export async function stageOnboardLogin(ctx, input) {
+    const timeoutMs = input.timeoutMs ?? 600_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 600_000)
+        throw new UsageError("onboarding sign-in timeout must be 1 to 600000 milliseconds");
+    const reviewDeadline = Date.now() + timeoutMs;
+    const original = onboardFileSnapshot(configPathFor(ctx.home));
+    const saved = loadConfig(ctx.home);
+    const originalContract = onboardFileSnapshot(contractPathFor(ctx.home));
+    const baseUrl = normalizeBaseUrl(saved?.baseUrl ??
+        input.baseUrl ??
+        ctx.env.CATALYST_CLOUD_BASE_URL ??
+        DEFAULT_BASE_URL);
+    if (input.baseUrl && normalizeBaseUrl(input.baseUrl) !== baseUrl)
+        throw new CliError("Resume against the original cloud to change this login.", "onboard-base-url-mismatch", 12);
+    const url = new URL(baseUrl);
+    if (url.protocol !== "https:" || url.origin !== baseUrl)
+        throw new CliError("The saved cloud origin could not be verified.", "onboard-base-url-mismatch", 12);
+    const manifest = readManifest();
+    const validate = async (auth, signal) => {
+        if (signal.aborted)
+            throw stopped();
+        if (!Number.isFinite(Date.parse(auth.expiresAt)) ||
+            Date.parse(auth.expiresAt) - ctx.now().getTime() <= 30_000)
+            throw new CliError("Sign in again before accepting this plan.", "onboard-login-refresh-required", 11);
+        const fetchImpl = async (request, init) => boundedResponse(await ctx.fetch(request, {
+            ...init,
+            redirect: "error",
+            signal: init?.signal
+                ? AbortSignal.any([signal, init.signal])
+                : signal,
+        }), signal);
+        const me = await fetchMe(baseUrl, auth.accessToken, fetchImpl);
+        if (signal.aborted)
+            throw stopped();
+        if (!me.user)
+            throw new CliError("Onboarding needs your personal login.", "onboard-person-required", 12);
+        // Cached contracts and loadContract's stale fallback cannot approve a staged identity.
+        const response = await fetchImpl(`${baseUrl}/api/v1/agent/contract`, {
+            headers: {
+                authorization: `Bearer ${auth.accessToken}`,
+                accept: "application/json",
+            },
+        });
+        if (!response.ok)
+            throw new CliError("The workspace could not be verified. Your saved connection was not changed.", "onboard-candidate-unverified", 11);
+        const text = await response.text();
+        if (signal.aborted)
+            throw stopped();
+        if (Buffer.byteLength(text) > 1024 * 1024)
+            throw new CliError("The workspace response could not be verified.", "onboard-candidate-unverified", 11);
+        let contract;
+        try {
+            contract = object(JSON.parse(text));
+        }
+        catch {
+            contract = null;
+        }
+        if (object(contract?.account)?.id !== me.account ||
+            typeof contract?.contractVersion !== "string" ||
+            contractVersionInRange(contract.contractVersion, manifest.tenantContractRange) !== true)
+            throw new CliError("The workspace response did not match this login.", "onboard-candidate-unverified", 11);
+        return me;
+    };
+    const staged = await bounded(input.signal, timeoutMs, async (signal) => {
+        const stageCtx = {
+            ...ctx,
+            env: { ...ctx.env, CATALYST_CLOUD_TOKEN: undefined },
+            fetch: async (request, init) => boundedResponse(await ctx.fetch(request, {
+                ...init,
+                redirect: "error",
+                signal: init?.signal
+                    ? AbortSignal.any([signal, init.signal])
+                    : signal,
+            }), signal),
+        };
+        let auth;
+        try {
+            auth = await deviceFlowLogin(stageCtx, baseUrl, {
+                ...input.device,
+                discoveryCache: false,
+                signal,
+            });
+        }
+        catch {
+            if (signal.aborted)
+                throw stopped();
+            throw new CliError("Sign-in could not be verified. Your saved connection was not changed.", "onboard-signin-unverified", 11);
+        }
+        const me = await bounded(signal, 30_000, (readSignal) => validate(auth, readSignal));
+        if (onboardFileSnapshot(configPathFor(ctx.home)) !== original)
+            throw new CliError("Your saved login changed. Run setup again.", "onboard-login-changed", 11);
+        return { auth, me };
+    });
+    const user = staged.me.user;
+    if (!user)
+        throw new CliError("Onboarding needs your personal login.", "onboard-person-required", 12);
+    const identity = {
+        account: staged.me.account,
+        membershipId: user.id,
+        baseUrl,
+        role: user.role,
+        display: Object.freeze({
+            personLabel: user.label,
+            email: user.email,
+            workspaceName: staged.me.name,
+            workspaceSlug: staged.me.slug,
+        }),
+    };
+    let accepted = false;
+    return {
+        identity: Object.freeze(identity),
+        get accepted() {
+            return accepted;
+        },
+        async accept(signal, beforePublish) {
+            if (accepted)
+                throw new CliError("This sign-in preview was already accepted.", "onboard-candidate-used", 11);
+            const remaining = reviewDeadline - Date.now();
+            if (remaining <= 0)
+                throw stopped();
+            const me = await bounded(signal, Math.min(30_000, remaining), (readSignal) => validate(staged.auth, readSignal));
+            if (me.account !== identity.account ||
+                me.user?.id !== identity.membershipId ||
+                me.user.role !== identity.role)
+                throw new CliError("This login changed during review. Run setup again.", "onboard-login-changed", 11);
+            if (signal?.aborted)
+                throw stopped();
+            if (onboardFileSnapshot(configPathFor(ctx.home)) !== original)
+                throw new CliError("Your saved login changed. Run setup again.", "onboard-login-changed", 11);
+            if (onboardFileSnapshot(contractPathFor(ctx.home)) !== originalContract)
+                throw new CliError("Your setup files changed during review. Run setup again.", "onboard-login-changed", 11);
+            beforePublish?.();
+            const config = {
+                baseUrl,
+                account: me.account,
+                slug: me.slug,
+                name: me.name,
+                principal: me.principal,
+                permissions: me.permissions,
+                user: me.user,
+                auth: staged.auth,
+                joinedAt: ctx.now().toISOString(),
+                lastSkillBundleVersion: manifest.version,
+                cliPath: cliPath(),
+                ...(saved?.skillsDir ? { skillsDir: saved.skillsDir } : {}),
+                // A new workspace never inherits the old workspace's database path.
+                replicaDb: saved?.account === me.account
+                    ? (saved.replicaDb ?? defaultReplicaDbFor(ctx.home))
+                    : undefined,
+            };
+            // This is an accepted connection, not a two-file transaction. Existing config writers do
+            // not share the receipt lock; the precheck refuses visible changes but is not a CAS claim.
+            try {
+                writeConfig(ctx.home, config);
+            }
+            catch (error) {
+                const current = loadConfig(ctx.home);
+                accepted =
+                    current?.account === config.account &&
+                        current.user?.id === config.user?.id &&
+                        current.auth?.accessToken === config.auth?.accessToken;
+                if (accepted)
+                    throw new CliError("Your connection was accepted, but setup could not be recorded. Run catalyst onboard to resume.", "onboard-connection-accepted", 11);
+                throw error;
+            }
+            accepted = true;
+            const fd = openSync(configPathFor(ctx.home), constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            const directory = openSync(dirname(configPathFor(ctx.home)), constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                fsyncSync(directory);
+            }
+            finally {
+                closeSync(directory);
+            }
+            // The old cache has no identity scope. Invalidate it only after this reviewed connection
+            // is accepted, and only while its observed bytes still match. A failure remains partial.
+            if (onboardFileSnapshot(contractPathFor(ctx.home)) !== originalContract)
+                throw new CliError("Your connection was accepted, but setup could not be recorded. Run catalyst onboard to resume.", "onboard-connection-accepted", 11);
+            if (originalContract !== null) {
+                unlinkSync(contractPathFor(ctx.home));
+                const cacheDirectory = openSync(dirname(contractPathFor(ctx.home)), constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    fsyncSync(cacheDirectory);
+                }
+                finally {
+                    closeSync(cacheDirectory);
+                }
+            }
+        },
+    };
+}

package/dist/onboard-next.js

@@ -0,0 +1,139 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+/** What a person reads for a step that is not done. Each line ends in an action they can take. */
+const REASONS = {
+    account_identity_unverified: "Your login changed while coding accounts were checked. Run catalyst onboard again to verify your person and workspace.",
+    account_inventory_unavailable: "Coding accounts could not be read. Run catalyst onboard again to retry.",
+    account_inventory_unverified: "The server did not return a fresh supported coding-account list. Run catalyst onboard after the server update.",
+    account_validation_admin_required: "An administrator must check the workspace's coding-account access.",
+    account_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
+    account_validation_unavailable: "The provider check could not finish. Run catalyst onboard again to retry.",
+    account_validation_unverified: "The server did not return a fresh provider check. Run catalyst onboard after the server update.",
+    account_provider_access_unverified: "Coding-account provider access is not freshly verified. Check the account in the workspace's coding-account settings, then resume setup.",
+    codex_provider_access_unverified: "Codex credentials are stored, but provider access is not freshly verified. Setup did not refresh or rotate the Codex login.",
+    account_provider_walled: "Claude's usage limit is spent for now. Check the account's reset time, then run catalyst onboard again.",
+    account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's coding-account settings, then resume setup.",
+    personal_consent_handoff: "The browser approval link could not be verified. Run catalyst onboard to try again.",
+    personal_identity_refused: "Your current login no longer matches this setup. Resume with the original workspace and person.",
+    personal_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    onboard_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    personal_status_unavailable: "Your personal connection could not be checked. Run catalyst onboard to try again.",
+    workspace_browser_unavailable: "This computer could not open a browser. Connect Linear from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
+    personal_browser_unavailable: "This computer could not open a browser. Finish this login’s connection from Connected accounts in your browser, then run catalyst onboard to resume.",
+    onboarding_capability_unavailable: "The server's setup capabilities could not be checked. Run catalyst onboard to try again.",
+    onboarding_capability_identity_unverified: "The server's setup capabilities belong to another login or workspace. Sign in to the original workspace to resume.",
+    onboarding_capability_login_refresh_required: "Your login needs a refresh before setup capabilities can be checked. Run catalyst login, then catalyst onboard.",
+    workspace_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    workspace_consent_refused: "The server did not accept this login for Linear workspace setup. Sign in again or ask your workspace administrator.",
+    github_installation_status_unavailable: "Your GitHub App installation could not be checked. Run catalyst onboard to try again.",
+    github_installation_status_shape: "The server returned a GitHub installation result that could not be verified.",
+    github_installation_consent_handoff: "The GitHub installation approval link could not be verified. Run catalyst onboard to try again.",
+    github_installation_consent_refused: "The server did not accept this login for GitHub App setup. Sign in again or ask your workspace administrator.",
+    github_installation_identity_refused: "GitHub setup belongs to another login or workspace. Sign in to the original workspace to resume.",
+    github_installation_admin_required: "A workspace owner or administrator approves the GitHub App installation.",
+    github_installation_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    github_installation_browser_unavailable: "This computer could not open a browser. Install the GitHub App from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
+    step_not_available_in_this_release: "This setup step is not available yet.",
+    prerequisite_not_ready: "Waiting for an earlier setup step.",
+    local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
+    local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
+    member_scope: "Your workspace administrator handles this step.",
+    onboarding_checks_pending: "Some required checks are still unverified.",
+    interrupted: "Setup paused. Run the same command to resume.",
+    signin_timeout: "Sign-in timed out. Run catalyst onboard to try again.",
+    linear_workspace_unverified: "Your Linear workspace connection could not be verified.",
+    team_inventory_empty: "No existing Linear teams could be verified.",
+    team_inventory_shape: "The cloud returned a team list that could not be verified.",
+    team_read_unavailable: "Your existing Linear teams could not be read. Run catalyst onboard to try again.",
+    team_read_identity_unverified: "Your login changed while setup was reading this workspace. Resume with the original workspace and person.",
+    project_identity_unverified: "Your login changed while setup was checking this project. Resume with the original workspace and person.",
+    project_options_unavailable: "Available teams and repositories could not be checked. Run catalyst onboard to try again.",
+    project_provider_inventory_unavailable: "Linear or GitHub access could not be verified. Check this workspace's connections, then resume.",
+    project_options_unverified: "The server returned a team or repository list that could not be verified.",
+    project_registration_visibility_pending: "Your project exists, but its repository binding is not visible yet. Run catalyst onboard to check again.",
+    project_binding_conflict: "This team or repository is already bound to a project. Ask your workspace administrator to check its binding, then resume.",
+    project_login_refresh_required: "Renew your login with catalyst onboard, then review the plan before creating this project.",
+    project_create_unverified: "Project creation could not be confirmed. Run catalyst onboard to check for the project before trying again.",
+    team_read_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
+    team_choice_required: "Choose an existing team with catalyst onboard --team <team ID or key>.",
+    team_selection_unverified: "Your selected Linear team could not be verified. Run catalyst onboard --team <team ID or key> to choose again.",
+    repository_choice_required: "Choose repositories with catalyst onboard --repo <owner/name>. Repeat --repo to choose more than one.",
+    repository_inventory_empty: "No accessible repositories are registered to this Linear team yet.",
+    repository_read_unavailable: "Your repository list could not be read. Run catalyst onboard to try again.",
+    repository_inventory_shape: "The cloud returned a repository list that could not be verified.",
+    repository_contract_unavailable: "Current repository IDs could not be checked. Run catalyst onboard to try again.",
+    repository_contract_unverified: "The cloud returned repository IDs that could not be verified for this workspace.",
+    repository_id_unverified: "A repository's current ID could not be verified. Keep your selection and try again.",
+    repository_binding_ambiguous: "A repository's Linear team binding is ambiguous. Your administrator needs to check it.",
+    repository_identity_unverified: "Sign in to the original workspace to choose repositories.",
+    settings_review_timeout: "The settings review timed out. Run catalyst onboard to resume.",
+    settings_checkout_unverified: "Setup could not verify the repository's local checkout or settings file. Settings are optional for a first ticket. To finish them later, run catalyst onboard from the repository's checkout.",
+    settings_draft_storage_unavailable: "A private settings draft could not be kept. Run catalyst onboard to retry.",
+    settings_draft_storage_timeout: "Keeping your settings draft took too long. Run catalyst onboard to retry.",
+    settings_approval_unverified: "Settings still need review and approval; kept drafts do not count. Settings are optional for a first ticket. To finish them later, run catalyst onboard from the repository's checkout.",
+    repository_selection_unverified: "Your selected repositories could not be verified. Run catalyst onboard --repo <owner/name> to choose again.",
+    workflow_identity_unverified: "Setup could not confirm the signed-in workspace, person or role for this team. Run catalyst onboard again as a workspace owner or administrator.",
+    workflow_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
+    workflow_mapping_changed: "The team's workflow changed while setup checked it. Run catalyst onboard again.",
+    workflow_unavailable: "Setup could not read the team's workflow. Run catalyst onboard again to retry.",
+    capacity_admission_unverified: "No runner is allowed to take work for this workspace yet. Enroll a self-hosted runner host, or ask Catalyst to enable cloud runners for it. Then run catalyst onboard.",
+    capacity_currently_full: "Every runner slot for this repository is in use. Run catalyst onboard again after current work finishes.",
+    capacity_unavailable: "Setup could not read runner capacity. Run catalyst onboard again to retry.",
+    housekeeping_service_unverified: "The daily update needs a user service manager, launchd on macOS or systemd --user on Linux. Setup cannot schedule it on this computer. It is optional, and work does not depend on it.",
+};
+/** The saved login's web address, or nothing when the config is missing, unreadable or not http(s). */
+export function savedOnboardBaseUrl(home) {
+    try {
+        const cfg = loadConfig(home);
+        const url = cfg ? webUrl(cfg.baseUrl) : undefined;
+        return url ? normalizeBaseUrl(url) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Receipt and config text reaches the terminal only after URL parsing has escaped it.
+function webUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        return ["https:", "http:"].includes(url.protocol) &&
+            !url.username &&
+            !url.password
+            ? url.href
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The selected team's key from the receipt, only when it is plain enough to print in a command. */
+export function onboardTeamKey(journal) {
+    const step = journal?.steps.find((row) => row.id === "linear.team");
+    const key = step?.state === "done" ? step.evidence?.teamKey : undefined;
+    return typeof key === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(key)
+        ? key
+        : undefined;
+}
+/** One step's next action. `waitsFor` names the unfinished step a prerequisite wait is blocked on. */
+export function onboardReasonText(step, context = {}) {
+    const reason = step.reason ?? "";
+    if (reason === "workflow_mapping_unverified")
+        return `This team's workflow mapping is not verified yet. Run catalyst team adopt ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} to preview the adoption plan. Run it again with the --yes --plan-hash value it prints. Then run catalyst onboard.`;
+    if (reason === "account_enrollment_required") {
+        const where = context.baseUrl
+            ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts, the Settings → AI accounts page`
+            : "in the web app on the Settings → AI accounts page";
+        return `No coding account is enrolled. A workspace owner or administrator adds one ${where}. A Claude account needs its email and the token printed by \`claude setup-token\`. Then run catalyst onboard.`;
+    }
+    if (reason === "cloud_capability_unavailable") {
+        // The capability guard records the web page in evidence.path only when it printed it.
+        const page = webUrl(step.evidence?.path);
+        return page
+            ? `This setup step is not available on this server yet. Continue in the web app at ${page}, then run catalyst onboard.`
+            : "This setup step is not available on this server yet. Run catalyst onboard after the server update.";
+    }
+    if (reason === "prerequisite_not_ready" && context.waitsFor)
+        return `Runs after "${context.waitsFor}".`;
+    return REASONS[reason] ?? reason.replaceAll("_", " ");
+}

package/dist/onboard-personal.js

@@ -1,3 +1,4 @@
+import { finishOnTheWeb } from "./consent-browser.js";
 import { loadConfig, normalizeBaseUrl, } from "./config.js";
 import { pollConsent } from "./onboard-consent.js";
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
@@ -198,11 +199,15 @@ export function personalConsentAdapter(options) {
             const name = options.provider === "linear" ? "Linear" : "GitHub";
             ctx.stderr(`Approve your personal ${name} connection in the browser.`);
             // Signed continuation credentials belong only to the browser, never transcript or journal.
+            let browserUnavailable = false;
             try {
-                options.openBrowser(url);
+                await options.openBrowser(url, signal);
             }
             catch {
-                return waiting("personal_browser_unavailable");
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                browserUnavailable = true;
+                ctx.stderr(finishOnTheWeb(cfg.baseUrl, "connected-accounts", `connect your ${name} account`));
             }
             let latest = waiting("personal_status_unavailable");
             const run = () => pollConsent({
@@ -213,6 +218,8 @@ export function personalConsentAdapter(options) {
                     latest = await inspect(ctx, journal, pollSignal);
                     if (latest.reason === "cloud_capability_unavailable")
                         return { outcome: "waiting", reason: latest.reason };
+                    if (latest.reason === "personal_login_refresh_required")
+                        return { outcome: "waiting", reason: latest.reason };
                     if (latest.state === "done")
                         return { outcome: "connected" };
                     if (latest.state === "refused" || latest.state === "failed")
@@ -225,7 +232,11 @@ export function personalConsentAdapter(options) {
             const result = options.wait
                 ? await options.wait(`Waiting for your ${name} approval`, run)
                 : await run();
-            return result.state === "done" ? latest : result;
+            if (result.state === "done")
+                return latest;
+            return browserUnavailable && result.reason === "consent_timeout"
+                ? waiting("personal_browser_unavailable")
+                : result;
         },
     };
 }