@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/dist/contract.js

@@ -0,0 +1,178 @@
+// contract.ts — GET /api/v1/agent/contract, cached with its ETag at ~/.config/catalyst-cloud/contract.json.
+// Every tenant fact a verb needs (stage ids, label ids, route paths, the bookkeeping marker, thresholds)
+// is read from here; no verb carries a literal fallback for any of them.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { contractPathFor, readManifest } from "./config.js";
+import { CliError, MeError } from "./errors.js";
+import { apiClient } from "./http.js";
+export const CONTRACT_ROUTE = "/api/v1/agent/contract";
+export function readContractCache(home) {
+    const path = contractPathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.fetchedAt !== "string" || typeof parsed.contractVersion !== "string" || !parsed.doc)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeContractCache(home, cache) {
+    const path = contractPathFor(home);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+    return path;
+}
+/** `1.x` → major 1; `1.2.3` → exact; `unpinned` → anything. Returns null when the range is unparseable. */
+export function contractVersionInRange(version, range) {
+    if (range === "unpinned")
+        return true;
+    const major = /^(\d+)\.x$/.exec(range);
+    if (major)
+        return version.split(".")[0] === major[1];
+    if (/^\d+\.\d+\.\d+$/.test(range))
+        return version === range;
+    return null;
+}
+export function assertContractRange(version, range) {
+    const ok = contractVersionInRange(version, range);
+    if (ok === null)
+        throw new CliError(`tenantContractRange "${range}" in package.json is not a range this CLI understands`, "contract-range");
+    if (!ok) {
+        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm update -g @catalyst-cloud/catalyst-skills) or ask your tenant admin which version is live`, "contract-version");
+    }
+}
+/**
+ * Load the contract per the cloud's own cache policy: a cache younger than `doc.cache.maxAgeSeconds`
+ * is used as-is; otherwise a conditional GET revalidates it (304 refreshes `fetchedAt`, 200 replaces
+ * the document). A network failure on a cache older than `staleRefusalSeconds` refuses; a 403 (a
+ * workstation key) refuses naming the account key; a major version outside the bundle's range refuses
+ * naming both versions.
+ */
+export async function loadContract(ctx, cfg, opts = {}) {
+    const path = contractPathFor(ctx.home);
+    const cached = readContractCache(ctx.home);
+    const nowMs = ctx.now().getTime();
+    const ageSeconds = cached ? Math.max(0, Math.floor((nowMs - Date.parse(cached.fetchedAt)) / 1000)) : Infinity;
+    const range = readManifest().tenantContractRange;
+    if (cached && !opts.refresh && ageSeconds < cached.doc.cache.maxAgeSeconds) {
+        assertContractRange(cached.contractVersion, range);
+        return { doc: cached.doc, source: "cache", ageSeconds, path };
+    }
+    if (opts.offline) {
+        if (cached) {
+            assertContractRange(cached.contractVersion, range);
+            return { doc: cached.doc, source: "cache", ageSeconds, path };
+        }
+        throw new CliError("no cached contract and network reads are disabled", "contract-missing");
+    }
+    const api = apiClient(cfg, ctx);
+    let res;
+    try {
+        res = await api.getJson(CONTRACT_ROUTE, { etag: cached?.etag ?? null, accept: [304] });
+    }
+    catch (err) {
+        if (err instanceof CliError && err.status === 403) {
+            throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): the contract needs an account key (ctc_acct_…); this key is a workstation key — ask your tenant admin for an account key`, "contract-forbidden", 2, 403);
+        }
+        if (err instanceof MeError && err.kind === "network" && cached) {
+            if (ageSeconds >= cached.doc.cache.staleRefusalSeconds) {
+                throw new CliError(`the cached contract is ${ageSeconds}s old (refusal after ${cached.doc.cache.staleRefusalSeconds}s) and the refresh failed: ${err.message}`, "contract-stale");
+            }
+            assertContractRange(cached.contractVersion, range);
+            return { doc: cached.doc, source: "cache", ageSeconds, path };
+        }
+        throw err;
+    }
+    if (res.status === 304) {
+        if (!cached)
+            throw new CliError(`GET ${CONTRACT_ROUTE} answered 304 with no cache to revalidate`, "contract-shape");
+        assertContractRange(cached.contractVersion, range);
+        writeContractCache(ctx.home, { ...cached, fetchedAt: ctx.now().toISOString() });
+        return { doc: cached.doc, source: "revalidated", ageSeconds: 0, path };
+    }
+    const doc = res.body;
+    if (!doc || typeof doc !== "object" || typeof doc.contractVersion !== "string" || !Array.isArray(doc.teams) || !Array.isArray(doc.routes)) {
+        throw new CliError(`GET ${CONTRACT_ROUTE} returned an unexpected shape`, "contract-shape");
+    }
+    const version = res.headers.get("x-catalyst-contract-version") ?? doc.contractVersion;
+    assertContractRange(version, range);
+    writeContractCache(ctx.home, {
+        etag: res.headers.get("etag"),
+        fetchedAt: ctx.now().toISOString(),
+        contractVersion: version,
+        doc,
+    });
+    return { doc, source: "network", ageSeconds: 0, path };
+}
+// ── helpers every verb uses ──────────────────────────────────────────────────────────────────────
+export function teamByKey(doc, key) {
+    const wanted = key.toUpperCase();
+    const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted);
+    if (!team) {
+        const known = doc.teams.map((t) => t.key ?? t.id).join(", ") || "none";
+        throw new CliError(`team "${key}" is not on this tenant's contract (teams: ${known})`, "team-unknown");
+    }
+    return team;
+}
+export function teamById(doc, id) {
+    return doc.teams.find((t) => t.id === id) ?? null;
+}
+/** The team a ticket identifier belongs to, by its `KEY-` prefix. */
+export function teamForTicket(doc, ticket) {
+    const dash = ticket.indexOf("-");
+    if (dash <= 0)
+        throw new CliError(`"${ticket}" is not a ticket identifier (expected KEY-123)`, "ticket-shape");
+    return teamByKey(doc, ticket.slice(0, dash));
+}
+export function stageIdForSlot(team, slot) {
+    const stage = team.stages[slot];
+    if (!stage) {
+        const mapped = Object.keys(team.stages).join(", ") || "none";
+        throw new CliError(`slot "${slot}" is not mapped for team ${team.key ?? team.id} (mapped: ${mapped})`, "slot-unmapped");
+    }
+    if (!stage.stateStillExists) {
+        throw new CliError(`slot "${slot}" on team ${team.key ?? team.id} maps to state ${stage.stateId}, which no longer exists in Linear — fix the mapping in settings first`, "slot-stale");
+    }
+    return stage.stateId;
+}
+/** Resolve a label by name through the contract's ask/hold/release lists; an unknown name is returned
+ *  as-is when it looks like an id (the contract only lists Catalyst's own labels). */
+export function labelId(team, nameOrId) {
+    const all = [...team.labels.ask, ...team.labels.hold, ...team.labels.release];
+    const hit = all.find((l) => l.name === nameOrId);
+    if (hit) {
+        if (!hit.preferredId) {
+            throw new CliError(`label "${nameOrId}" is absent from this workspace (contract scope: ${hit.scope}) — create it in Linear first`, "label-absent");
+        }
+        return hit.preferredId;
+    }
+    return nameOrId;
+}
+/** The route whose last path segment is `name` (e.g. `issue-comment`). The path itself is never assumed. */
+export function routePath(doc, name) {
+    const route = doc.routes.find((r) => r.path.split("/").filter(Boolean).at(-1) === name);
+    if (!route) {
+        throw new CliError(`the tenant contract serves no "${name}" route (routes: ${doc.routes.map((r) => r.path).join(", ")})`, "route-unknown");
+    }
+    return route.path;
+}
+export function bookkeepingPrefix(doc) {
+    return doc.vocabulary.bookkeeping.marker;
+}
+/** Walk a dotted path (`teams.0.stages`) into the document. */
+export function pickPath(doc, path) {
+    let cur = doc;
+    for (const seg of path.split(".").filter(Boolean)) {
+        if (cur === null || typeof cur !== "object")
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}

package/dist/detach.js

@@ -0,0 +1,10 @@
+// detach.ts — re-spawn this CLI detached (replica start --detach). Isolated so a test can stub it.
+import { spawn } from "node:child_process";
+/** Spawn `process.execPath <argv>` detached from this process, stdio ignored, and let it go. */
+export function detachSelf(argv, env = process.env) {
+    const child = spawn(process.execPath, argv, { detached: true, stdio: "ignore", env });
+    child.unref();
+    if (typeof child.pid !== "number")
+        throw new Error("detached spawn returned no pid");
+    return { pid: child.pid };
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// errors.ts — the three error classes the exit contract is built on: usage → 1, MeError/CliError → 2.
+export class UsageError extends Error {
+}
+export class CliError extends Error {
+    code;
+    exitCode;
+    status;
+    constructor(message, code, 
+    /** Exit code the dispatcher returns for this error. Defaults to 2 (the CliError contract). */
+    exitCode = 2, 
+    /** The HTTP status that produced it, when one did. */
+    status) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.status = status;
+    }
+}
+export class MeError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+    }
+}

package/dist/execution.js

@@ -0,0 +1,156 @@
+// execution.ts — what Catalyst is doing: `explain <ticket>`, `running`, `queue`, `accounts`.
+// `explain` turns one work-eligibility row into a paragraph a human can act on, translating every
+// exclusion reason and unknown the cloud names; an unlisted reason prints its raw string, never nothing.
+import { flagBool, flagString, positionals } from "./args.js";
+import { normalizeBaseUrl, requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+/** Every exclusion reason the eligibility evaluator names, in plain English. */
+export const EXCLUSION_REASONS = {
+    ticket_terminal: "the ticket is in a done or canceled state, so there is nothing left to run",
+    pipeline_complete: "every relay phase has already completed",
+    not_at_dispatch_stage: "the card is not in the team's dispatch column, so nothing is offered until it is moved there",
+    not_at_pr_stage: "merge is next but the card is not in the PR column",
+    blocked: "a live blocking relation holds it — the blocker has to close first",
+    cooling_down: "the offered phase is parked; a callback or an operator releases it, not a clock",
+    lease_held: "a live container already holds the lease for the offered phase",
+    intake_lease_held: "a later phase is offered while an intake container still holds this ticket",
+    ask_ticket: "it carries an ask label, and a question is never work",
+    ask_shape_suspected: "its own text reads as a decision request; a human releases it with the not-an-ask label",
+    externally_claimed: "a worker outside the cloud has claimed it",
+    environment_check_required: "the repository's environment check has not been run",
+    environment_check_running: "the repository's environment check is in flight",
+    environment_check_failed: "the repository's environment check failed",
+    environment_check_expired: "the repository's environment check verdict aged out",
+    environment_check_hash_mismatch: "the environment changed since its recorded verdict",
+    scope_overlap: "its declared file scope intersects a ticket already in flight",
+    waiting_on: "a merge-gate failure with no remediable cause holds the card at PR",
+    branch_missing: "the ticket branch has never been seen, so a branch-dependent phase has nothing to clone",
+    branch_gone: "the ticket branch was deleted after it existed",
+    pr_merged: "its PR has merged and no other PR is open — nothing is left to clone or re-merge",
+    no_change_hold: "a remediate round changed nothing; a human comment or a new push releases it",
+    validate_class_spent: "this validate failure already spent its one repair round in this episode",
+    stale_failure_episode: "the ladder advanced after the recorded failure, so the round would repair a phase already passed",
+    runner_image_breaker: "fleet-wide: the live runner image is failing every phase at startup; dispatch resumes when the pin moves",
+    no_branch_to_remediate: "a remediate round is queued on a ticket with no recorded branch",
+    retry_backoff: "the failed phase is retrying in place and waiting out its backoff",
+    routing_unavailable: "the unit was claimed and refused at kickoff (no route, no eligible coding-account slot, or the provider is unavailable)",
+    repo_paused: "an operator paused the repository",
+    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired",
+};
+/** Every fail-closed unknown the evaluator names. */
+export const UNKNOWN_REASONS = {
+    ordering_never_published: "the dispatch order has never been published for this team",
+    ordering_stale: "the dispatch order is stale",
+    workflow_mapping_unknown: "the team's workflow mapping could not be read",
+    ticket_unknown: "the ticket is not in the mirror",
+    dependency_snapshot_unknown: "the dependency snapshot has never completed",
+    blocker_unknown: "a blocking relation could not be resolved",
+    label_snapshot_unknown: "the labels poll has never completed, so ask labels cannot be read",
+    prior_artifact_unknown: "a prior phase artifact could not be read",
+    scope_unknown: "the ticket declared no scope, or the declaration was truncated",
+    scope_occupancy_unknown: "an in-flight ticket's state could not be resolved",
+    branch_snapshot_unknown: "the pull-request poll has never completed, so branch evidence cannot be read",
+};
+export const ADVISORIES = {
+    human_addressed_unlabeled_ask_suspect: "assigned to a human with no delegate: this may be an unlabelled ask",
+};
+export function describeReason(reason) {
+    if (!reason)
+        return "no reason was given";
+    return EXCLUSION_REASONS[reason] ?? UNKNOWN_REASONS[reason] ?? `reason "${reason}" (not in this bundle's table; read it as the cloud spelled it)`;
+}
+export function renderExplain(ticket, row, team) {
+    if (!row)
+        return `${ticket}: not in the ${team} eligibility explainer — the ticket is unknown to the mirror, terminal, or on another team.`;
+    const parts = [];
+    const pos = typeof row.position === "number" ? `position ${row.position}` : "no queue position";
+    const status = row.status ?? "unknown";
+    if (status === "offered" || status === "eligible") {
+        parts.push(`${ticket} is ${status} (${pos})${row.phase ? ` for phase ${row.phase}` : ""}.`);
+    }
+    else if (status === "unknown") {
+        parts.push(`${ticket} cannot be judged (${pos}): ${describeReason(row.unknown ?? row.reason)}.`);
+    }
+    else {
+        parts.push(`${ticket} is ${status} (${pos}): ${describeReason(row.reason)}.`);
+    }
+    if (row.detail)
+        parts.push(`Detail: ${row.detail}.`);
+    if (row.marker)
+        parts.push(`Marker: ${row.marker}.`);
+    if (row.nextPhase)
+        parts.push(`Next phase would be ${row.nextPhase}.`);
+    if (row.release)
+        parts.push(`Release: ${row.release}.`);
+    if (row.failure && typeof row.failure === "object") {
+        const f = row.failure;
+        const bits = ["phase", "class", "attempts", "consecutive", "lastFailedAt", "message", "summary"]
+            .filter((k) => f[k] !== undefined && f[k] !== null)
+            .map((k) => `${k}=${typeof f[k] === "string" ? f[k] : JSON.stringify(f[k])}`);
+        parts.push(`Last failure: ${bits.length ? bits.join(", ") : JSON.stringify(f)}.`);
+    }
+    if (row.advisories && row.advisories.length > 0) {
+        parts.push(`Advisories: ${row.advisories.map((a) => ADVISORIES[a] ?? a).join("; ")}.`);
+    }
+    return parts.join(" ");
+}
+export async function cmdExplain(args, ctx) {
+    const [ticket] = positionals(args);
+    if (!ticket)
+        throw new UsageError("explain needs a ticket: explain <ticket>");
+    const cfg = requireConfig(ctx);
+    if (flagBool(args, "history")) {
+        ctx.stdout(`${ticket}: per-ticket execution history is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings`);
+        return 0;
+    }
+    const { doc } = await loadContract(ctx, cfg);
+    const dash = ticket.indexOf("-");
+    if (dash <= 0)
+        throw new UsageError(`"${ticket}" is not a ticket identifier (expected KEY-123)`);
+    const team = ticket.slice(0, dash).toUpperCase();
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/work-eligibility", {
+        query: { team, capabilities: doc.ladder.phases.join(",") },
+    });
+    const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
+    const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+    if (args.json) {
+        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team) }));
+    }
+    else {
+        ctx.stdout(renderExplain(ticket, row, team));
+    }
+    return 0;
+}
+export async function cmdRunning(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const [activity, roster, leases] = await Promise.all([
+        api.getJson("/api/v1/fleet-activity/current"),
+        api.getJson("/api/v1/agent-roster/current"),
+        api.getJson("/api/v1/lease/attributions"),
+    ]);
+    const out = { fleetActivity: activity.body, agentRoster: roster.body, leaseAttributions: leases.body };
+    if (args.json) {
+        ctx.stdout(JSON.stringify(out));
+        return 0;
+    }
+    ctx.stdout(`fleet activity: ${JSON.stringify(out.fleetActivity)}`);
+    ctx.stdout(`agent roster: ${JSON.stringify(out.agentRoster)}`);
+    ctx.stdout(`lease attributions: ${JSON.stringify(out.leaseAttributions)}`);
+    return 0;
+}
+export async function cmdQueue(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/dispatch-queue/current", { query: { team: flagString(args, "team") } });
+    ctx.stdout(args.json ? JSON.stringify(res.body) : JSON.stringify(res.body, null, 2));
+    return 0;
+}
+export function cmdAccounts(ctx) {
+    const cfg = requireConfig(ctx);
+    ctx.stdout(`coding-account status is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+    return 0;
+}

package/dist/http.js

@@ -0,0 +1,142 @@
+import { normalizeBaseUrl } from "./config.js";
+import { CliError, MeError } from "./errors.js";
+export const REQUEST_TIMEOUT_MS = 15_000;
+export class ApiClient {
+    cfg;
+    fetchImpl;
+    constructor(cfg, fetchImpl) {
+        this.cfg = cfg;
+        this.fetchImpl = fetchImpl;
+    }
+    /** `path` is absolute under the origin (e.g. `/api/v1/issues`). */
+    url(path, query) {
+        const u = new URL(`${normalizeBaseUrl(this.cfg.baseUrl)}${path}`);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined)
+                u.searchParams.set(k, String(v));
+        return u.toString();
+    }
+    async getJson(path, opts = {}) {
+        const headers = {
+            authorization: `Bearer ${this.cfg.key}`,
+            accept: "application/json",
+        };
+        if (opts.etag)
+            headers["if-none-match"] = opts.etag;
+        const url = this.url(path, opts.query);
+        const res = await this.send(url, { method: "GET", headers });
+        if (opts.accept?.includes(res.status)) {
+            return { status: res.status, body: undefined, headers: res.headers };
+        }
+        await this.refuseIfNotOk(res, `GET ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
+    }
+    async postJson(path, body) {
+        const url = this.url(path);
+        const res = await this.send(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.cfg.key}`,
+                accept: "application/json",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        await this.refuseIfNotOk(res, `POST ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
+    }
+    async send(url, init) {
+        try {
+            return await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        }
+        catch (err) {
+            throw new MeError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+        }
+    }
+    async parseBody(res, what) {
+        try {
+            return (await res.json());
+        }
+        catch {
+            throw new MeError(`${what} returned a non-JSON body`, "shape");
+        }
+    }
+    async refuseIfNotOk(res, what) {
+        if (res.ok)
+            return;
+        let reason = "";
+        let raw = "";
+        try {
+            raw = await res.text();
+            const body = JSON.parse(raw);
+            reason = body.reason ?? body.error ?? body.message ?? "";
+        }
+        catch {
+            reason = raw.slice(0, 200);
+        }
+        if (res.status === 401) {
+            throw new CliError(`${what} failed (401): credential not accepted — ask your tenant admin for a valid account key`, "unauthorized", 2, 401);
+        }
+        if (res.status === 403) {
+            throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a machine-gated route needs an account key (ctc_acct_…), not a workstation key`, "forbidden", 2, 403);
+        }
+        if (res.status === 429) {
+            const retryAfter = res.headers.get("retry-after");
+            const budget = /budget/i.test(raw) || /budget/i.test(reason);
+            throw new CliError(`${what} refused (429)${budget ? ": the per-host daily write budget is spent" : ": rate limited"}${reason ? ` — ${reason}` : ""}${retryAfter ? ` — retry after ${retryAfter}s` : ""}`, budget ? "budget" : "rate-limited", 2, 429);
+        }
+        throw new CliError(`${what} failed (${res.status})${reason ? `: ${reason}` : ""}`, "http", 2, res.status);
+    }
+}
+export function apiClient(cfg, ctx) {
+    return new ApiClient(cfg, ctx.fetch);
+}
+/** GET /api/v1/me — how a key learns its own tenant. Unchanged contract from 0.1. */
+export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const url = `${normalizeBaseUrl(baseUrl)}/api/v1/me`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${key}`, accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        throw new MeError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+    if (!res.ok) {
+        let reason;
+        try {
+            const body = (await res.json());
+            reason = body.reason ?? body.error ?? "";
+        }
+        catch {
+            reason = "";
+        }
+        const detail = res.status === 401
+            ? "credential not accepted — ask your tenant admin for a valid account key"
+            : reason || `HTTP ${res.status}`;
+        throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new MeError("GET /me returned a non-JSON body", "shape");
+    }
+    if (typeof body.account !== "string" ||
+        typeof body.slug !== "string" ||
+        typeof body.name !== "string" ||
+        (body.permissions !== null && !Array.isArray(body.permissions)) ||
+        (body.principal !== "service" && body.principal !== "session")) {
+        throw new MeError("GET /me returned an unexpected shape", "shape");
+    }
+    return {
+        account: body.account,
+        slug: body.slug,
+        name: body.name,
+        permissions: body.permissions,
+        principal: body.principal,
+    };
+}

package/dist/prompt.js

@@ -0,0 +1,35 @@
+// prompt.ts — the one interactive read in the CLI: asking for the account key on a terminal without
+// echoing it. The streams are parameters so the tests can drive it without a real TTY.
+import { createInterface } from "node:readline";
+/** True when there is a terminal to prompt on. Both ends matter: the question needs somewhere to go. */
+export function stdinIsTty() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+ * Read one line without echoing it. Everything readline would write after the question itself goes
+ * to a muted stream, so the key never reaches the screen or a scrollback buffer; the caller still
+ * gets it back, trimmed.
+ */
+export async function promptSecret(question, io) {
+    const input = io?.input ?? process.stdin;
+    const target = io?.output ?? process.stdout;
+    let muted = false;
+    const output = Object.create(target);
+    output.write = (chunk) => {
+        if (!muted)
+            target.write(chunk);
+        return true;
+    };
+    const rl = createInterface({ input, output, terminal: true });
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question(question, (value) => resolve(value));
+            muted = true;
+        });
+        target.write("\n");
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}