@catalyst-cloud/cli 0.15.2 → 0.15.3

package/dist/onboard-checklist.js

@@ -0,0 +1,309 @@
+import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { verifyOnboardRoutes } from "./onboard-capabilities.js";
+import { pollConsent } from "./onboard-consent.js";
+import { readExistingOnboardJson } from "./onboard-existing.js";
+/** The one read behind the web app's Connect accounts page. Each read runs live provider probes. */
+export const CHECKLIST_PATH = "/api/v1/me/connections/checklist";
+export const CONNECT_PAGE_PATH = "/connect-accounts";
+/** Never poll the checklist faster than this: every read probes Linear and GitHub. */
+export const CHECKLIST_POLL_MS = 10_000;
+/** Exactly the page's own labels, so the terminal and the browser name each row the same way. */
+export const CHECKLIST_LABELS = {
+    "linear-workspace": "Linear workspace",
+    "linear-personal": "Your Linear account",
+    "github-app": "Catalyst on GitHub",
+    "github-personal": "Your GitHub account",
+    "ai-account": "AI account",
+};
+/** The checklist's reason codes in words. Codes stay in receipts; only these reach the screen. */
+const REASON_WORDS = {
+    not_connected: "not connected yet",
+    not_installed: "not installed yet",
+    lapsed: "the connection lapsed and needs connecting again",
+    expired: "the connection expired and needs connecting again",
+    workspace_first: "the Linear workspace needs connecting first",
+    missing_permissions: "needs updated permissions",
+    approval_pending: "waiting for an owner of your GitHub organization to approve it",
+    repository_not_covered: "does not reach every project repository yet",
+    none_usable: "no AI account can take work yet",
+    check_unavailable: "could not be checked just now. Setup keeps checking",
+};
+const ITEM_IDS = new Set(Object.keys(CHECKLIST_LABELS));
+const STATES = new Set([
+    "done",
+    "needed",
+    "outdated",
+    "waiting",
+    "unknown",
+]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : null;
+/** "Catalyst on GitHub: waiting for an owner of your GitHub organization to approve it." */
+export function checklistItemText(item) {
+    return `${CHECKLIST_LABELS[item.id]}: ${(item.reason && REASON_WORDS[item.reason]) || "not done yet"}.`;
+}
+function parse(body, origin) {
+    const row = object(body);
+    if (!row ||
+        row.schema !== 1 ||
+        typeof row.page !== "string" ||
+        typeof row.checkedAt !== "number" ||
+        !Number.isFinite(row.checkedAt) ||
+        !Array.isArray(row.items) ||
+        row.items.length > 20)
+        return null;
+    // The page is opened in a browser: it must be this cloud's own Connect page and nothing else.
+    let page;
+    try {
+        page = new URL(row.page);
+    }
+    catch {
+        return null;
+    }
+    if (page.origin !== origin ||
+        page.pathname !== CONNECT_PAGE_PATH ||
+        page.search ||
+        page.hash ||
+        page.username ||
+        page.password)
+        return null;
+    const items = [];
+    for (const value of row.items) {
+        const item = object(value);
+        if (!item || typeof item.id !== "string")
+            return null;
+        // A row, state or audience a newer cloud adds is not this CLI's to judge. Skipping it leaves the
+        // rows this CLI knows, so the checklist stays on.
+        if (!ITEM_IDS.has(item.id) ||
+            typeof item.state !== "string" ||
+            !STATES.has(item.state) ||
+            (item.who !== "admin" && item.who !== "you"))
+            continue;
+        if (typeof item.canAct !== "boolean" ||
+            !((item.state === "done" && item.reason === null) ||
+                (item.state !== "done" &&
+                    typeof item.reason === "string" &&
+                    /^[a-z][a-z0-9_]{1,63}$/.test(item.reason))) ||
+            items.some((seen) => seen.id === item.id))
+            return null;
+        items.push({
+            id: item.id,
+            state: item.state,
+            reason: item.reason,
+            who: item.who,
+            canAct: item.canAct,
+        });
+    }
+    const kinds = Array.isArray(row.aiAccountKinds) ? row.aiAccountKinds : [];
+    return {
+        page: page.toString(),
+        checkedAt: row.checkedAt,
+        items,
+        aiAccountKinds: kinds.includes("subscription")
+            ? "subscription,api-key"
+            : "api-key",
+    };
+}
+const LOGIN_EXPIRED = {
+    reason: "onboard_login_refresh_required",
+    fatal: true,
+};
+const IDENTITY_CHANGED = {
+    reason: "connect_checklist_identity_unverified",
+    fatal: true,
+};
+/** `unsupported` when the cloud does not advertise the checklist: the caller keeps its own routes.
+ * `verified`: the origin whose contract already advertised the route this wait, so a poll reads the
+ * checklist alone. A revoked login then answers 401 on the checklist itself. */
+export async function readChecklist(ctx, journal, signal, verified) {
+    if (verified !== undefined) {
+        const cfg = loadConfig(ctx.home);
+        if (!cfg?.user ||
+            cfg.account !== (journal.account ?? journal.tenant) ||
+            cfg.user.id !== journal.membershipId ||
+            !journal.baseUrl ||
+            normalizeBaseUrl(cfg.baseUrl) !== normalizeBaseUrl(journal.baseUrl) ||
+            new URL(normalizeBaseUrl(cfg.baseUrl)).origin !== verified)
+            return IDENTITY_CHANGED;
+    }
+    const support = verified !== undefined
+        ? { origin: verified }
+        : await verifyOnboardRoutes(ctx, journal, [{ method: "GET", path: CHECKLIST_PATH }], signal);
+    if ("reason" in support) {
+        if (support.reason === "cloud_capability_unavailable")
+            return { unsupported: true };
+        if (support.reason.endsWith("_login_refresh_required"))
+            return LOGIN_EXPIRED;
+        if (support.reason.endsWith("_identity_unverified") ||
+            support.reason === "personal_login_required")
+            return IDENTITY_CHANGED;
+        return {
+            reason: support.reason,
+            fatal: support.reason === "interrupted",
+        };
+    }
+    const read = await readExistingOnboardJson(ctx, CHECKLIST_PATH, signal);
+    if ("reason" in read) {
+        if (read.reason.endsWith("_login_refresh_required"))
+            return LOGIN_EXPIRED;
+        if (read.reason.endsWith("_identity_unverified") ||
+            read.reason === "personal_login_required")
+            return IDENTITY_CHANGED;
+        if (read.status === 401 || read.status === 403)
+            return { reason: "connect_checklist_refused", fatal: true };
+        return { reason: "connect_checklist_unavailable", fatal: false };
+    }
+    const checklist = parse(read.body, support.origin);
+    return checklist
+        ? { checklist }
+        : { reason: "connect_checklist_unverified", fatal: false };
+}
+const done = (item, checklist) => ({
+    state: "done",
+    evidence: {
+        provider: item.id === "github-app" ? "github" : "ai-account",
+        scope: "checklist",
+        checkedAt: checklist.checkedAt,
+    },
+});
+/** CTC-4680: a step the Connect accounts page also lists. When the cloud advertises the checklist,
+ * its row is the step's answer and the wait sends the person to that page. Without it, the step's
+ * own status routes and links run unchanged. */
+export function connectChecklistAdapter(options) {
+    const { fallback } = options;
+    const enabled = options.enabled !== false;
+    /** The row for this step; null when the cloud has none (the step keeps its own routes). */
+    const read = async (ctx, journal, signal, verified) => {
+        if (!enabled)
+            return null;
+        const cached = options.cache.last;
+        const age = cached ? ctx.now().getTime() - cached.at : Infinity;
+        let result = cached && age >= 0 && age < CHECKLIST_POLL_MS ? cached.read : undefined;
+        if (!result) {
+            // A recent read that never answered (cut off at a deadline) still spaces the next one.
+            if (age >= 0 && age < CHECKLIST_POLL_MS)
+                await (options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(CHECKLIST_POLL_MS - age);
+            const at = ctx.now().getTime();
+            // Recorded before the read starts, so one that is aborted still counts.
+            options.cache.last = { at };
+            result = await readChecklist(ctx, journal, signal, verified);
+            options.cache.last = { at, read: result };
+        }
+        if ("unsupported" in result)
+            return null;
+        if ("reason" in result)
+            return result;
+        kinds = result.checklist.aiAccountKinds;
+        const item = result.checklist.items.find((row) => row.id === options.item);
+        return item ? { checklist: result.checklist, item } : null;
+    };
+    // The AI account step's text follows what the workspace may add, so its results carry the kinds
+    // from the read that answered them. No read, no kinds: the text falls back to API keys.
+    let kinds;
+    const tagged = (run) => async (ctx, journal, signal) => {
+        kinds = undefined;
+        const result = await run(ctx, journal, signal);
+        return options.item === "ai-account" && kinds
+            ? { ...result, evidence: { ...result.evidence, aiAccountKinds: kinds } }
+            : result;
+    };
+    const actionable = (item) => item.state === "needed" && item.canAct && options.wait !== undefined;
+    const adapter = {
+        check: async (ctx, journal, signal) => {
+            const current = await read(ctx, journal, signal);
+            if (current && "item" in current) {
+                if (current.item.state === "done")
+                    return done(current.item, current.checklist);
+                if (actionable(current.item))
+                    return { state: "pending" };
+            }
+            return fallback.check(ctx, journal, signal);
+        },
+        act: async (ctx, journal, signal) => {
+            const current = await read(ctx, journal, signal);
+            if (current && "item" in current && current.item.state === "done")
+                return done(current.item, current.checklist);
+            // Anything the page cannot finish here (no browser wait, an admin's row, a row waiting on
+            // someone else, a checklist that could not be read) keeps the step's own action and reasons.
+            if (!current || !("item" in current) || !actionable(current.item) || !options.wait)
+                return fallback.act
+                    ? fallback.act(ctx, journal, signal)
+                    : fallback.check(ctx, journal, signal);
+            const label = CHECKLIST_LABELS[options.item];
+            const url = current.checklist.page;
+            // 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) {
+                try {
+                    await options.openBrowser(url, signal);
+                    options.page.openedBy = options.step;
+                    instruction = `Opened your browser. Finish "${label}" on the page.`;
+                }
+                catch {
+                    if (signal?.aborted)
+                        return { state: "waiting", reason: "interrupted" };
+                    instruction = `Open this link and finish "${label}":`;
+                    // The page is not a credential, so it is printed on its own line for any browser.
+                    ctx.stderr(`No browser opened on this computer. In a browser signed in to Catalyst, open this page and finish "${label}". Setup keeps waiting here.`);
+                    ctx.stderr(url);
+                }
+            }
+            else
+                instruction = `Finish "${label}" on the page already open in your browser.`;
+            let last = current.item;
+            let finished = current.checklist;
+            let said = "";
+            let failures = 0;
+            const run = () => pollConsent({
+                timeoutMs: options.timeoutMs,
+                intervalMs: CHECKLIST_POLL_MS,
+                signal,
+                sleep: options.sleep,
+                readStatus: async (pollSignal) => {
+                    const next = await read(ctx, journal, pollSignal, origin);
+                    if (!next)
+                        return { outcome: "unavailable" };
+                    if (!("item" in next)) {
+                        // A login that expired or changed, or a refusal, will not fix itself: stop and say so.
+                        if (next.fatal)
+                            return { outcome: "waiting", reason: next.reason };
+                        if (++failures === 3)
+                            options.note?.("Setup could not check the Connect accounts page just now. It keeps checking.");
+                        return { outcome: "unavailable" };
+                    }
+                    failures = 0;
+                    last = next.item;
+                    finished = next.checklist;
+                    if (last.state === "done")
+                        return { outcome: "connected" };
+                    const text = last.state === "needed" ? "" : checklistItemText(last);
+                    if (text && text !== said)
+                        options.note?.(text);
+                    said = text;
+                    return { outcome: "absent" };
+                },
+            });
+            const result = await options.wait(`Waiting for "${label}"`, run, {
+                url,
+                instruction,
+            });
+            if (result.state === "done")
+                return done(last, finished);
+            // A row that ended waiting on someone else, or needing a change elsewhere, gets the step's
+            // own detailed reason; a row still simply needed timed out and can be offered again.
+            const ended = {
+                state: result.state,
+                reason: result.reason ?? "consent_timeout",
+            };
+            if (result.reason === "consent_timeout" && last.state !== "needed") {
+                const detail = await fallback.check(ctx, journal, signal);
+                return detail.state === "pending" ? ended : detail;
+            }
+            return ended;
+        },
+    };
+    return { check: tagged(adapter.check), act: tagged(adapter.act) };
+}

package/dist/onboard-existing.js

@@ -83,7 +83,7 @@ export async function readExistingOnboardJson(ctx, path, external) {
                     signal,
                 });
                 if (response.status !== 200)
-                    return { reason: "team_read_unavailable" };
+                    return { reason: "team_read_unavailable", status: response.status };
                 const body = await response.json();
                 const current = loadConfig(ctx.home);
                 if (!current?.user ||

package/dist/onboard-first-ticket.js

@@ -0,0 +1,199 @@
+import { loadConfig } from "./config.js";
+import { loadContract, readContractCache } from "./contract.js";
+import { CliError } from "./errors.js";
+import { selectedOnboardTeam } from "./onboard-existing.js";
+import { dispatchStageName } from "./onboard-next.js";
+import { onboardStatePath, writeOnboardJournal, } from "./onboard.js";
+import { fetchPage } from "./pagination.js";
+import { apiClient } from "./transport.js";
+import { postAgent } from "./write.js";
+/** The person's answer: a ticket identifier from the offered list, or one of these two. */
+export const FIRST_TICKET_SAMPLE = "create-sample";
+export const FIRST_TICKET_SKIP = "skip";
+// A documentation-only starter: it changes one file and no code, so a first run is safe to watch.
+const SAMPLE_TITLE = "Document how to run repository tests";
+const SAMPLE_DESCRIPTION = "Update only CONTRIBUTING.md to document existing test commands from repository configuration. Do not change executable code, configuration, dependencies, or credentials. If the test commands cannot be established from source, stop and report the missing information.";
+/** Linear's state types for a ticket nobody has started. */
+const OPEN_TYPES = new Set(["triage", "backlog", "unstarted"]);
+const IDENTIFIER = /^[A-Z][A-Z0-9]{0,7}-[0-9]{1,9}$/;
+const waiting = (reason) => ({ state: "waiting", reason });
+function linearUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && url.hostname === "linear.app" && !url.username && !url.password
+            ? url.href
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A recorded outcome is kept: a moved ticket stays moved, and a skip stays the person's choice. */
+function recorded(step) {
+    const ticket = step?.evidence?.ticket;
+    if (step?.state === "done" && typeof ticket === "string" && IDENTIFIER.test(ticket))
+        return { state: "done", evidence: { ...step.evidence } };
+    if (step?.state === "skipped" && step.reason === "first_ticket_skipped")
+        return {
+            state: "skipped",
+            reason: "first_ticket_skipped",
+            ...(typeof step.evidence?.stage === "string" ? { evidence: { stage: step.evidence.stage } } : {}),
+        };
+    return undefined;
+}
+/** What this setup already chose, saved in the receipt before any write: a ticket identifier or the
+ * sample. A run that stopped after the write, or lost its answer, finishes that choice instead of
+ * offering the list again, so it can never move a second ticket. */
+const CHOSEN = /:first-ticket:([A-Z][A-Z0-9]{0,7}-[0-9]{1,9}|sample)$/;
+/** Interactive only. The person picks one of the team's open tickets (smallest estimate first), a
+ * documentation-only sample, or skips. The chosen ticket moves to the team's dispatch stage through
+ * the same write route `catalyst write state` uses; a sample is created straight into it. Without
+ * `choose` (--yes, JSON, headless) the step only waits: it never lists, picks or creates a ticket.
+ * Done means the ticket is in the dispatch stage, not that a runner has started it. */
+export function onboardFirstTicketAdapter(hooks) {
+    // The engine checks again right after an action, before the receipt holds its evidence.
+    let acted;
+    return {
+        check: async (ctx, journal) => {
+            const kept = acted ?? recorded(journal.steps.find((step) => step.id === "first-ticket"));
+            if (kept)
+                return kept;
+            if (hooks.choose)
+                return { state: "pending" };
+            // The contract this computer already has names the stage; no network read and no listing.
+            const teamId = selectedOnboardTeam(journal);
+            const stage = teamId
+                ? readContractCache(ctx.home)?.doc.teams.find((team) => team.id === teamId)?.stages.dispatch?.name
+                : undefined;
+            return {
+                ...waiting("first_ticket_choice_required"),
+                ...(typeof stage === "string" ? { evidence: { stage } } : {}),
+            };
+        },
+        act: async (ctx, journal, signal) => {
+            if (!hooks.choose)
+                return waiting("first_ticket_choice_required");
+            const cfg = loadConfig(ctx.home);
+            const teamId = selectedOnboardTeam(journal);
+            if (!cfg || !teamId)
+                return waiting("first_ticket_team_unverified");
+            let stage;
+            let writing = false;
+            const result = (state, reason, evidence = {}) => ({
+                state,
+                ...(reason ? { reason } : {}),
+                ...(stage || Object.keys(evidence).length
+                    ? { evidence: { ...evidence, ...(stage ? { stage } : {}) } }
+                    : {}),
+            });
+            try {
+                const { doc } = await loadContract(ctx, cfg, { refresh: true, signal });
+                const team = doc.teams.find((row) => row.id === teamId);
+                const dispatch = team?.stages.dispatch;
+                if (!team?.key || !dispatch?.stateStillExists)
+                    return waiting("first_ticket_dispatch_unmapped");
+                stage = dispatch.name ?? undefined;
+                const api = apiClient(cfg, ctx);
+                const catalystStages = new Set(Object.values(team.stages).map((row) => row?.stateId));
+                const slug = doc.account.linearWorkspaceSlug;
+                const done = (identifier, url) => {
+                    if (typeof identifier !== "string" || !IDENTIFIER.test(identifier))
+                        return result("waiting", "first_ticket_unverified");
+                    url ??=
+                        slug && /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(slug)
+                            ? `https://linear.app/${slug}/issue/${identifier}`
+                            : undefined;
+                    return (acted = result("done", undefined, {
+                        ticket: identifier,
+                        teamKey: team.key,
+                        ...(url ? { url } : {}),
+                    }));
+                };
+                const createSample = async () => {
+                    writing = true;
+                    const created = await postAgent(api, doc, "issue-create", {
+                        teamId: team.id,
+                        title: SAMPLE_TITLE,
+                        description: SAMPLE_DESCRIPTION,
+                        stateId: dispatch.stateId,
+                        // The same key on every run of this setup: a resent create answers with the first ticket.
+                        idempotencyId: `${journal.runId}:first-ticket`,
+                    });
+                    return done(created?.identifier, linearUrl(created?.url));
+                };
+                const move = async (issueId, identifier, url) => {
+                    writing = true;
+                    await postAgent(api, doc, "issue-state", { issueId, stateId: dispatch.stateId });
+                    return done(identifier, url);
+                };
+                const page = await fetchPage(api, "/api/v1/issues", {
+                    team_key: team.key,
+                    limit: 200,
+                });
+                const chosen = CHOSEN.exec(journal.operations?.["first-ticket"] ?? "")?.[1];
+                if (chosen === "sample")
+                    return await createSample();
+                if (chosen) {
+                    const detail = await api.getJson(`/api/v1/issues/${encodeURIComponent(chosen)}`, { accept: [404] });
+                    const row = detail.status === 404 ? undefined : detail.body;
+                    const url = linearUrl(row?.url);
+                    // Already in a Catalyst stage: the move landed, or Catalyst has taken it further.
+                    if (row && catalystStages.has(String(row.state_id)))
+                        return done(chosen, url);
+                    // Still open: the move never landed, so it is sent again for the same ticket only.
+                    if (row && typeof row.id === "string" && !row.completed_at && !row.canceled_at)
+                        return await move(row.id, chosen, url);
+                    // Closed some other way: the choice no longer stands, so the person chooses again.
+                }
+                const open = page.rows
+                    .filter((row) => row.team_id === team.id &&
+                    typeof row.id === "string" &&
+                    typeof row.identifier === "string" &&
+                    IDENTIFIER.test(row.identifier) &&
+                    OPEN_TYPES.has(String(row.state_type)) &&
+                    !catalystStages.has(String(row.state_id)))
+                    .map((row) => ({
+                    id: row.id,
+                    identifier: row.identifier,
+                    title: String(row.title ?? "")
+                        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+                        .slice(0, 120),
+                    estimate: typeof row.estimate === "number" && Number.isFinite(row.estimate)
+                        ? row.estimate
+                        : null,
+                }))
+                    .sort((a, b) => (a.estimate ?? Infinity) - (b.estimate ?? Infinity) ||
+                    Number(a.identifier.split("-")[1]) - Number(b.identifier.split("-")[1]))
+                    .slice(0, 5);
+                const choice = await hooks.choose(open.map(({ identifier, title, estimate }) => ({ identifier, title, estimate })), { teamKey: team.key, stage: dispatchStageName(stage) });
+                if (choice === null || signal?.aborted)
+                    return waiting("interrupted");
+                if (choice === FIRST_TICKET_SKIP)
+                    return (acted = result("skipped", "first_ticket_skipped"));
+                const ticket = open.find((row) => row.identifier === choice);
+                if (choice !== FIRST_TICKET_SAMPLE && !ticket)
+                    return result("waiting", "first_ticket_choice_required");
+                journal.operations = {
+                    ...journal.operations,
+                    "first-ticket": `${journal.runId}:first-ticket:${ticket ? ticket.identifier : "sample"}`,
+                };
+                writeOnboardJournal(onboardStatePath(ctx.home, ctx.env), journal);
+                return ticket ? await move(ticket.id, ticket.identifier) : await createSample();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return waiting("interrupted");
+                const refused = error instanceof CliError && error.status === 403;
+                // A refused write changed nothing, so the choice is forgotten and the next run asks again.
+                if (refused && writing)
+                    journal.operations = {
+                        ...journal.operations,
+                        "first-ticket": `${journal.runId}:first-ticket`,
+                    };
+                return result("waiting", refused ? "first_ticket_move_refused" : "first_ticket_unavailable");
+            }
+        },
+    };
+}

package/dist/onboard-headless.js

@@ -201,7 +201,7 @@ export function planOnboardHeadless(args, ctx) {
             id: "coding_account",
             kind: "input",
             reason: "coding_account_input_missing",
-            text: `Name the coding account with --coding-account <slot> or CATALYST_ONBOARD_CODING_ACCOUNT. catalyst accounts lists the slots; enroll one at ${url.codingAccounts}.`,
+            text: `Name the AI account with --coding-account <slot> or CATALYST_ONBOARD_CODING_ACCOUNT. catalyst accounts lists them; add one at ${url.codingAccounts}.`,
             flag: "--coding-account",
             env: "CATALYST_ONBOARD_CODING_ACCOUNT",
             url: url.codingAccounts,
@@ -211,7 +211,7 @@ export function planOnboardHeadless(args, ctx) {
             id: "coding_account",
             kind: "input",
             reason: "coding_account_input_invalid",
-            text: "The coding-account slot may hold only letters, digits, - and _. catalyst accounts lists the slots.",
+            text: "The AI account name given to --coding-account may hold only letters, digits, - and _. catalyst accounts lists them.",
             flag: "--coding-account",
             env: "CATALYST_ONBOARD_CODING_ACCOUNT",
         });

package/dist/onboard-housekeeping.js

@@ -0,0 +1,93 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/** The names install.sh schedules the daily update under (catalyst-cloud's install-script.ts). */
+export const HOUSEKEEPING_LABEL = "dev.catalystcloud.housekeeping";
+export const HOUSEKEEPING_TIMER = "catalyst-housekeeping.timer";
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5_000 });
+    return {
+        status: r.status ?? 1,
+        stdout: r.stdout ?? "",
+        stderr: r.error ? r.error.message : (r.stderr ?? ""),
+    };
+};
+function onPath(name, env) {
+    return (env.PATH ?? process.env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .some((dir) => {
+        try {
+            accessSync(join(dir, name), constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** The installer's own test for "systemctl is here but nothing manages user services". */
+const NO_USER_MANAGER = /failed to connect to bus: (no medium found|no such file or directory)|system has not been booted with systemd/i;
+/** Every answer but "scheduled" is a skip: the daily update is optional, so it never holds setup
+ * or becomes its next action. The reason keeps which case it is. */
+const skipped = (reason, path) => ({
+    state: "skipped",
+    reason,
+    ...(path ? { evidence: { path } } : {}),
+});
+/** CTC-4680: the daily update step reports what this computer actually has. It only observes:
+ * scheduling stays the installer's job. */
+export function onboardHousekeepingAdapter(options = {}) {
+    const run = options.run ?? defaultRun;
+    return {
+        check: async (ctx, journal) => {
+            const platform = options.platform ?? process.platform;
+            const choice = journal.dailyUpdate;
+            const notChosen = () => choice?.state === "off"
+                ? skipped("housekeeping_off_chosen")
+                : choice?.state === "skipped"
+                    ? skipped("housekeeping_no_scheduler")
+                    : undefined;
+            if (platform === "darwin") {
+                if (!onPath("launchctl", ctx.env))
+                    return notChosen() ?? skipped("housekeeping_no_scheduler");
+                const plist = join(ctx.home, "Library", "LaunchAgents", `${HOUSEKEEPING_LABEL}.plist`);
+                if (!existsSync(plist))
+                    return notChosen() ?? skipped("housekeeping_not_scheduled");
+                const uid = options.uid ?? process.getuid?.() ?? 0;
+                // `print` answers for a loaded job only; the plist alone schedules nothing.
+                if (run("launchctl", ["print", `gui/${uid}/${HOUSEKEEPING_LABEL}`]).status === 0)
+                    return {
+                        state: "done",
+                        evidence: { scheduled: true, provider: "launchd", path: plist },
+                    };
+                return notChosen() ?? skipped("housekeeping_not_loaded", plist);
+            }
+            if (platform === "linux") {
+                if (!onPath("systemctl", ctx.env))
+                    return notChosen() ?? skipped("housekeeping_no_scheduler");
+                const timer = join(ctx.env.XDG_CONFIG_HOME ?? join(ctx.home, ".config"), "systemd", "user", HOUSEKEEPING_TIMER);
+                if (existsSync(timer)) {
+                    const enabled = run("systemctl", ["--user", "is-enabled", HOUSEKEEPING_TIMER]);
+                    if (enabled.status === 0 && enabled.stdout.trim() === "enabled")
+                        return {
+                            state: "done",
+                            evidence: { scheduled: true, provider: "systemd", path: timer },
+                        };
+                    if (NO_USER_MANAGER.test(enabled.stderr))
+                        return notChosen() ?? skipped("housekeeping_no_scheduler");
+                    return notChosen() ?? skipped("housekeeping_not_enabled", timer);
+                }
+                const chosen = notChosen();
+                if (chosen)
+                    return chosen;
+                // A systemctl binary is not a scheduler: a container or WSL has it with no user manager.
+                const manager = run("systemctl", ["--user", "show-environment"]);
+                return manager.status !== 0 && NO_USER_MANAGER.test(manager.stderr)
+                    ? skipped("housekeeping_no_scheduler")
+                    : skipped("housekeeping_not_scheduled");
+            }
+            return notChosen() ?? skipped("housekeeping_no_scheduler");
+        },
+    };
+}