@catalyst-cloud/catalyst-skills 0.7.0 → 0.8.0

package/dist/query.js

@@ -1,248 +0,0 @@
-// query.ts — `query issues|issue|pulls|pull|projects|cycles|search|changes`: the replica when it is
-// fresh, else the API, with the source named on stderr every time. Output shape is the read-model
-// view either way. `pull`, `cycles`, `search` and `changes` are API-only (the SDK wraps no view for
-// them and the read-model package is not a declared dependency of this bundle).
-import { flagBool, flagInt, flagString, positionals } from "./args.js";
-import { requireConfig, replicaDbPath } from "./config.js";
-import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./transport.js";
-import { fetchAllPages, fetchPage, rowsOf, truncationNotice } from "./pagination.js";
-import { engineFor, replicaStatus } from "./replica.js";
-import { loadSdk } from "./sdk.js";
-export { rowsOf };
-const REPLICA_CAPABLE = new Set(["issues", "issue", "pulls", "projects"]);
-/** The two keyset routes `--all` can follow. `projects`/`cycles`/`search` are offset-paged or
- *  unpaginated and send no cursor header. */
-const PAGINATED = new Set(["issues", "pulls"]);
-export async function cmdQuery(args, ctx, deps = {}) {
-    const [sub, ...rest] = positionals(args);
-    if (!sub)
-        throw new UsageError("query needs a subcommand: issues | issue <id> | pulls | pull <id> | projects | cycles | search <terms> | changes --since <n>");
-    const cfg = requireConfig(ctx);
-    const filters = {
-        team: flagString(args, "team"),
-        project: flagString(args, "project"),
-        state: flagString(args, "state"),
-        limit: flagInt(args, "limit", 50),
-        all: flagBool(args, "all"),
-    };
-    const forced = flagString(args, "source");
-    if (forced && forced !== "replica" && forced !== "api")
-        throw new UsageError("--source must be replica or api");
-    if (filters.all && !PAGINATED.has(sub)) {
-        throw new UsageError(`--all follows the cloud's keyset pages, which only ${[...PAGINATED].join(" and ")} have`);
-    }
-    if (filters.all && forced === "replica") {
-        throw new UsageError("--all follows the cloud's page cursor; --source replica reads a local mirror that has none. Pick one.");
-    }
-    if (filters.all && flagString(args, "limit") !== undefined) {
-        ctx.stderr("--all reads the whole scope, so --limit is ignored");
-    }
-    const status = replicaStatus(ctx, cfg);
-    let source;
-    let why;
-    if (!REPLICA_CAPABLE.has(sub)) {
-        source = "api";
-        why = `${sub} is api-only`;
-    }
-    else if (forced) {
-        source = forced;
-        why = `--source ${forced}`;
-    }
-    else if (filters.all) {
-        source = "api";
-        why = "--all follows the cloud's pages";
-    }
-    else if (status.verdict === "fresh") {
-        source = "replica";
-        why = `cursor ${status.cursor}`;
-    }
-    else {
-        source = "api";
-        why = `replica ${status.verdict}`;
-    }
-    ctx.stderr(source === "replica" ? `source: replica (${why})` : `source: api (${why})`);
-    let result;
-    if (source === "replica") {
-        if (status.verdict === "absent" || status.verdict === "not-configured") {
-            throw new UsageError(`--source replica but the replica is ${status.verdict}`);
-        }
-        result = await fromReplica(ctx, cfg, sub, rest, filters, deps);
-    }
-    else {
-        result = await fromApi(ctx, cfg, sub, rest, filters, args);
-    }
-    if (result === null) {
-        ctx.stderr(`${sub} ${rest[0] ?? ""}: not found`);
-        return 1;
-    }
-    printResult(ctx, args, sub, result);
-    return 0;
-}
-async function fromReplica(ctx, cfg, sub, rest, f, deps) {
-    const sdk = await loadSdk();
-    const dbPath = replicaDbPath(cfg, ctx.home);
-    const engine = await engineFor(sdk, dbPath, ctx, { ...deps.engineDeps, readonly: true });
-    const replica = await sdk.CatalystReplica.openReadOnly({ dbPath, engine, log: () => { } });
-    try {
-        switch (sub) {
-            case "issues": {
-                const rows = replica.issues({ limit: Math.max(f.limit, 200) });
-                return applyFilters(rows, f).slice(0, f.limit);
-            }
-            case "issue":
-                return replica.issue(needArg(rest, "issue <identifier>"));
-            case "pulls":
-                return replica.pulls({ limit: f.limit });
-            case "projects":
-                return applyFilters(replica.projects({ limit: Math.max(f.limit, 200) }), { limit: f.limit, state: f.state }).slice(0, f.limit);
-            default:
-                throw new UsageError(`${sub} is not readable from the replica`);
-        }
-    }
-    finally {
-        await replica.close();
-    }
-}
-async function fromApi(ctx, cfg, sub, rest, f, args) {
-    const api = apiClient(cfg, ctx);
-    const common = { team: f.team, project: f.project, state: f.state, limit: f.limit };
-    switch (sub) {
-        case "issues": {
-            if (f.all) {
-                const { rows } = await fetchAllPages(api, "/api/v1/issues", { team: f.team, project: f.project, state: f.state });
-                return applyFilters(rows, f); // no .slice — --all means the whole scope
-            }
-            const page = await fetchPage(api, "/api/v1/issues", common);
-            const rows = applyFilters(page.rows, f).slice(0, f.limit);
-            const notice = truncationNotice(page);
-            if (notice)
-                ctx.stderr(notice);
-            return rows;
-        }
-        case "issue": {
-            const id = needArg(rest, "issue <identifier>");
-            const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(id)}`, { accept: [404] });
-            return res.status === 404 ? null : res.body;
-        }
-        case "pulls": {
-            const ticket = flagString(args, "ticket");
-            if (f.all) {
-                const { rows } = await fetchAllPages(api, "/api/v1/pulls", { ticket });
-                return rows;
-            }
-            const page = await fetchPage(api, "/api/v1/pulls", { limit: f.limit, ticket });
-            const rows = page.rows.slice(0, f.limit);
-            const notice = truncationNotice(page);
-            if (notice)
-                ctx.stderr(notice);
-            return rows;
-        }
-        case "pull": {
-            const id = needArg(rest, "pull <node id>");
-            const res = await api.getJson(`/api/v1/pulls/${encodeURIComponent(id)}`, { accept: [404] });
-            return res.status === 404 ? null : res.body;
-        }
-        case "projects": {
-            const res = await api.getJson("/api/v1/projects", { query: { limit: f.limit } });
-            return rowsOf(res.body).slice(0, f.limit);
-        }
-        case "cycles": {
-            const res = await api.getJson("/api/v1/cycles", { query: { team: f.team, limit: f.limit } });
-            return rowsOf(res.body);
-        }
-        case "search": {
-            const q = rest.join(" ").trim();
-            if (!q)
-                throw new UsageError("search needs terms: query search <terms>");
-            const res = await api.getJson("/api/v1/search", { query: { q, limit: f.limit } });
-            return rowsOf(res.body);
-        }
-        case "changes": {
-            const since = flagString(args, "since");
-            if (since === undefined)
-                throw new UsageError("changes needs --since <cursor>, or --since head to start from now");
-            return await readChanges(api, since, f.limit);
-        }
-        default:
-            throw new UsageError(`unknown query subcommand: ${sub}`);
-    }
-}
-/** CTC-137 stamps the live head seq on EVERY `/changes` response — the 200 stream and both 409s. */
-const HEAD_SEQ_HEADER = "x-catalyst-head-seq";
-/**
- * `query changes --since <cursor|head>`.
- *
- * ⛔ THE CHANGEFEED EVICTS, so a refusal must name a cursor that works. `buildChanges` answers a
- * `since` below the oldest retained seq with 409 `cursor_underflow`, and one past the head with 409
- * `cursor_ahead_of_head` — both `{resync: true}`. `--since 0`, the form the docs show, is therefore
- * a 409 on any tenant whose log has rotated, and 0.2.0 surfaced it as a bare "GET /api/v1/changes
- * failed (409)" that left the customer with no way to learn a usable cursor. The head is stamped on
- * the refusal itself, so there is always something actionable to say.
- */
-async function readChanges(api, since, limit) {
-    const resolved = since === "head" ? String(await headCursor(api)) : since;
-    // ⛔ NDJSON ON 200, JSON ON A REFUSAL — see `getNdjson`. Reading this with `getJson` turned every
-    // real success into "returned a non-JSON body" while every refusal parsed, which is why the verb
-    // looked fine: `--since 0` 409s on a rotated feed, so no 200 was ever reached to fail on.
-    const res = await api.getNdjson("/api/v1/changes", {
-        query: { since: resolved, limit },
-        accept: [409],
-    });
-    const head = res.headers.get(HEAD_SEQ_HEADER);
-    if (res.status !== 409) {
-        return { since: Number(resolved), head: head === null ? null : Number(head), changes: res.body };
-    }
-    const where = head === null ? "" : ` The feed's live cursor is ${head}.`;
-    throw new CliError(`cursor ${resolved} is not usable: it is either past the feed's head or no longer in the change log, which keeps only recent changes.${where} Re-run with \`--since head\` to start from now, or with a cursor the feed still holds.`, "changefeed-resync", 1, 409);
-}
-/** The live head, read off any `/changes` response's own header — a 409 carries it too, which is
- *  what makes this work on a tenant whose log has rotated past every cursor the caller could guess. */
-async function headCursor(api) {
-    const probe = await api.getNdjson("/api/v1/changes", { query: { since: "0", limit: 1 }, accept: [409] });
-    const raw = probe.headers.get(HEAD_SEQ_HEADER);
-    const head = raw === null ? Number.NaN : Number(raw);
-    if (!Number.isFinite(head)) {
-        throw new CliError(`--since head needs the feed's live cursor, and this cloud did not send one (no ${HEAD_SEQ_HEADER} header). Pass an explicit --since <cursor>.`, "changefeed-head-unknown", 1);
-    }
-    return head;
-}
-function needArg(rest, usage) {
-    const v = rest[0];
-    if (!v)
-        throw new UsageError(`query ${usage}`);
-    return v;
-}
-export function applyFilters(rows, f) {
-    return rows.filter((r) => {
-        if (f.team && !(String(r.identifier ?? "").toUpperCase().startsWith(`${f.team.toUpperCase()}-`) || r.team_id === f.team || r.team_key === f.team))
-            return false;
-        if (f.project && r.project_id !== f.project)
-            return false;
-        if (f.state && String(r.state ?? "").toLowerCase() !== f.state.toLowerCase())
-            return false;
-        return true;
-    });
-}
-function printResult(ctx, args, sub, result) {
-    if (args.json || !Array.isArray(result)) {
-        ctx.stdout(JSON.stringify(result, null, args.json ? 0 : 2));
-        return;
-    }
-    for (const row of result)
-        ctx.stdout(summaryLine(sub, row));
-}
-export function summaryLine(sub, r) {
-    switch (sub) {
-        case "issues":
-            return `${r.identifier ?? r.id}  ${r.state ?? "?"}  ${r.title ?? ""}${r.assignee_name || r.assignee ? `  (${r.assignee_name ?? r.assignee})` : ""}`;
-        case "pulls":
-            return `#${r.number ?? "?"}  ${r.state ?? "?"}${r.merged ? " merged" : ""}  ${r.title ?? ""}  [${r.node_id ?? ""}]`;
-        case "projects":
-            return `${r.id}  ${r.state ?? "?"}  ${r.name ?? ""}`;
-        case "cycles":
-            return `cycle ${r.number ?? r.id}  ${r.name ?? ""}  ${r.starts_at ?? ""} → ${r.ends_at ?? ""}`;
-        default:
-            return JSON.stringify(r);
-    }
-}

package/dist/ready.js

@@ -1,254 +0,0 @@
-// ready.ts — `ready`: the machine checks plus the tenant's own readiness vector from the contract,
-// one verdict, and per failure the fix and who can apply it. The replica is optional, so its absence
-// is a note, never a failure; the SDK loading IS a check, because the replica and watch need it.
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { defaultSkillsDirFor, loadConfig, readManifest } from "./config.js";
-import { contractVersionInRange, readContractCache } from "./contract.js";
-import { CliError } from "./errors.js";
-import { latestPublishedVersion } from "./published.js";
-import { replicaStatus, writerIsRunning } from "./replica.js";
-import { loadSdk } from "./sdk.js";
-import { semverOlder } from "./semver.js";
-import { FIRST_STAMPED_VERSION } from "./skill-shape.js";
-import { installedBundleVersion } from "./skills.js";
-export { semverOlder };
-/** `ready`'s own wording for the replica. It never recommends adopting the replica — until the
- *  mirror's snapshot path is safe for a large tenant, a customer following that advice is the
- *  failure mode. It DOES name the restart command when the writer gave up, because that is an
- *  instruction about a thing already running, not a nudge to adopt one (CTC-2499). */
-function readyReplicaLine(s) {
-    const w = s.writer;
-    if (w?.stopped) {
-        return (`replica: the writer stopped ${new Date(w.stopped.at).toISOString()}: ${w.stopped.reason} ` +
-            `(last error: ${w.lastError}) — the replica is optional and every read ` +
-            `still works through the API; restart it with: ${w.stopped.restartWith}`);
-    }
-    if (w && w.consecutiveFailures > 0) {
-        // Present tense only for a writer that is actually running: the record survives a SIGKILL, and
-        // "is backing off" about a dead process promises a retry that will never come (CTC-2499).
-        if (!writerIsRunning(s)) {
-            return `replica: the writer recorded ${w.consecutiveFailures} failed snapshot pulls and is no longer running (last error: ${w.lastError}) — the replica is optional and every read still works through the API`;
-        }
-        return `replica: the writer has failed ${w.consecutiveFailures} snapshot pulls in a row and is backing off (last error: ${w.lastError}) — reads fall back to the API`;
-    }
-    switch (s.verdict) {
-        case "not-configured":
-            return "replica: not configured — run login first";
-        case "absent":
-            return `replica: absent at ${s.dbPath} — optional, and off by default for large tenants while the snapshot path is being made safe; every read works through the API`;
-        case "fresh":
-            return `replica: fresh at ${s.dbPath} (cursor ${s.cursor}, heartbeat ${s.heartbeatAgeMs}ms ago${s.lag !== undefined ? `, ${s.lag} behind head ${s.head}` : ""})`;
-        case "stale":
-            return `replica: stale at ${s.dbPath} (${s.reasons.join("; ")}${s.cursor !== null ? `; cursor ${s.cursor}` : ""}) — reads fall back to the API`;
-    }
-}
-function whoCanAnswer(doc) {
-    const roles = doc.humans.map((h) => `${h.role} ${h.linearUserId}`);
-    return roles.length ? roles.join(", ") : "a tenant owner or admin (none resolved on the contract)";
-}
-export async function readyReport(ctx, deps) {
-    const checks = [];
-    const nodeMajor = deps.nodeMajor ?? Number(process.versions.node.split(".")[0]);
-    checks.push(nodeMajor >= 22
-        ? { id: "node", ok: true, line: `node: ${nodeMajor} (22 or newer required)` }
-        : { id: "node", ok: false, line: `node: ${nodeMajor} is too old`, fix: "install Node 22 or newer (the SDK's built-in SQLite engine needs it)", who: "you" });
-    let cfg = null;
-    try {
-        cfg = loadConfig(ctx.home);
-        checks.push(cfg
-            ? {
-                id: "config",
-                ok: true,
-                // `principal` is "service" for every api key (it means "a key, not a browser session"); it
-                // never names a person. Since CTC-2076 a personal key's /me carries a `user` block, so name
-                // the connected person when there is one, and fall back to the account for a host key.
-                line: cfg.user
-                    ? `config: joined ${cfg.name} as ${cfg.user.label} (${cfg.user.role})`
-                    : `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}`,
-            }
-            : { id: "config", ok: false, line: "config: not connected", fix: "npx @catalyst-cloud/catalyst-skills login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)", who: "you (approve the login in your browser)" });
-    }
-    catch (err) {
-        checks.push({ id: "config", ok: false, line: `config: ${err instanceof CliError ? err.message : String(err)}`, fix: "re-run login to rewrite it", who: "you" });
-    }
-    const cache = readContractCache(ctx.home);
-    const range = readManifest().tenantContractRange;
-    if (!cache) {
-        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst-skills contract --refresh", who: "you" });
-    }
-    else if (contractVersionInRange(cache.contractVersion, range) !== true) {
-        checks.push({ id: "contract", ok: false, line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`, fix: "npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login", who: "you" });
-    }
-    else {
-        checks.push({ id: "contract", ok: true, line: `contract: ${cache.contractVersion} cached ${cache.fetchedAt} (range ${range})` });
-    }
-    // The cloud MAY publish the bundle it expects (catalyst-cloud#3746). Read it defensively: warn (never
-    // refuse) when this installed bundle is older than the minimum, and emit nothing when the field is
-    // absent (an older cloud) — a stale bundle is a degrading note, so `ready` still returns READY.
-    const minVersion = cache?.doc.skillsBundle?.minVersion;
-    if (minVersion) {
-        const installed = readManifest().version;
-        if (semverOlder(installed, minVersion)) {
-            checks.push({
-                id: "bundle",
-                ok: false,
-                note: true,
-                line: `bundle: ${installed} installed is older than the tenant's minimum ${minVersion} — upgrade: npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login`,
-            });
-        }
-    }
-    // CTC-2160 — the two artefacts a customer installs drift apart: the CLI comes from npm, the skill
-    // files come from `npx skills add` (GitHub) or the plugin, and only the CLI's own version was ever
-    // knowable here. Both are NOTES: being behind a publish is a degrading fact about an install that
-    // still works, so `ready` stays READY. This is the one place `ready` touches the network, and it is
-    // capped, cached and skippable — see src/published.ts.
-    const skillsDir = cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
-    const offline = deps.offline === true || ctx.env.CATALYST_SKILLS_OFFLINE === "1";
-    if (!offline) {
-        const pub = await (deps.fetchLatestRelease ?? (() => latestPublishedVersion(ctx)))();
-        if (pub.latest === null) {
-            checks.push({
-                id: "cliRelease",
-                ok: false,
-                note: true,
-                line: `cliRelease: could not check for a newer release (${pub.reason}) — nothing about this install is known to be wrong; re-run when the network is back`,
-            });
-        }
-        else {
-            // clause 2 — the CLI. Suppressed when the tenant-minimum note already named this binary (D9).
-            const installedCli = readManifest().version;
-            const bundleNoteFired = checks.some((c) => c.id === "bundle");
-            if (!bundleNoteFired && semverOlder(installedCli, pub.latest)) {
-                checks.push({
-                    id: "cliRelease",
-                    ok: false,
-                    note: true,
-                    line: `cliRelease: ${installedCli} installed is older than the latest published ${pub.latest} — upgrade: npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login`,
-                });
-            }
-            // clause 1 — the skill files on disk, read independently of whichever CLI is answering. Both
-            // facts can hold at once: a machine that pulled at different hours carries some skills stamped
-            // behind AND some old enough to carry no stamp at all — the field report's own mixed install.
-            // So they are ADDITIVE, not exclusive: an unstamped file's real version is unknown and may be
-            // older than any stamp, which is why the stamped half says "oldest STAMPED" and the unstamped
-            // names are always printed rather than hidden behind whichever branch happened to win.
-            const found = installedBundleVersion(skillsDir, deps.skillNames);
-            const stampBehind = found.version !== null && semverOlder(found.version, pub.latest);
-            const unstampedBehind = found.unstamped.length > 0 && !semverOlder(pub.latest, FIRST_STAMPED_VERSION);
-            if (stampBehind || unstampedBehind) {
-                const facts = [];
-                if (stampBehind)
-                    facts.push(`the oldest stamped skill is ${found.version} (${found.skill})`);
-                if (unstampedBehind) {
-                    const one = found.unstamped.length === 1;
-                    facts.push(`${found.unstamped.join(", ")} ${one ? "carries" : "carry"} no version and so ${one ? "predates" : "predate"} ${FIRST_STAMPED_VERSION}`);
-                }
-                checks.push({
-                    id: "skillsRelease",
-                    ok: false,
-                    note: true,
-                    line: `skillsRelease: in ${skillsDir} ${facts.join(", and ")}, while the published bundle is ${pub.latest} — update: npx skills update -y`,
-                });
-            }
-        }
-    }
-    if (cfg) {
-        checks.push(cfg.cliPath && existsSync(cfg.cliPath)
-            ? { id: "cliPath", ok: true, line: `cliPath: ${cfg.cliPath}` }
-            : { id: "cliPath", ok: false, line: `cliPath: ${cfg.cliPath ? `${cfg.cliPath} does not exist` : "not recorded"}`, fix: "re-run login so the skill scripts can find this CLI", who: "you" });
-    }
-    // The skills are installed by the customer's own agent (a plugin, or `npx skills add`), so an
-    // empty copy directory is the normal case and must not read as NOT READY. A PARTIAL copy is the
-    // one broken state this check can see: half a set this package put there and never finished.
-    const present = deps.skillNames.filter((n) => existsSync(join(skillsDir, n, "SKILL.md")));
-    const missing = deps.skillNames.filter((n) => !present.includes(n));
-    if (present.length === 0) {
-        checks.push({ id: "skills", ok: true, note: true, line: `skills: none copied to ${skillsDir} — you are reading one, so your agent installed them its own way` });
-    }
-    else if (missing.length === 0) {
-        checks.push({ id: "skills", ok: true, line: `skills: all ${deps.skillNames.length} present in ${skillsDir}` });
-    }
-    else {
-        checks.push({ id: "skills", ok: false, line: `skills: ${present.length} of ${deps.skillNames.length} in ${skillsDir}, missing ${missing.join(", ")}`, fix: "catalyst-skills install", who: "you" });
-    }
-    try {
-        await (deps.loadSdk ?? loadSdk)();
-        checks.push({ id: "sdk", ok: true, line: "sdk: loads (replica and watch are available)" });
-    }
-    catch (err) {
-        checks.push({ id: "sdk", ok: false, line: `sdk: ${err instanceof Error ? err.message : String(err)}`, fix: "run under Node 22.15 or newer (or bun); every read still works through the API meanwhile", who: "you" });
-    }
-    const replica = replicaStatus(ctx, cfg);
-    checks.push({ id: "replica", ok: replica.verdict === "fresh", note: true, line: readyReplicaLine(replica) });
-    if (cache) {
-        const doc = cache.doc;
-        const who = whoCanAnswer(doc);
-        for (const team of doc.teams) {
-            const label = team.key ?? team.id;
-            // The team's dispatch gate, straight off the cached contract: an older cloud omits it and this
-            // emits nothing (the `skillsBundle` precedent above). A shut gate means NOTHING in the team can
-            // start, so it is a FAIL carrying the cloud's own remedy as the fix — never an informational
-            // note. It is emitted before the `unchecked` branch below so a team whose readiness was never
-            // checked still reports its gate, which is exactly the team most likely to be unmapped.
-            const dg = team.dispatchGate;
-            if (dg && typeof dg.status === "string") {
-                const slots = (dg.missingSlots ?? []).join(", ");
-                checks.push(dg.status === "open"
-                    ? { id: `team:${label}:dispatchGate`, ok: true, line: `team ${label}: dispatch gate open` }
-                    : {
-                        id: `team:${label}:dispatchGate`,
-                        ok: false,
-                        line: `team ${label}: dispatch gate ${dg.status}${slots ? ` (${slots})` : ""}, blocking`,
-                        fix: dg.remedy ?? `open settings for team ${label} and map its stages`,
-                        who,
-                    });
-            }
-            if (team.readiness.status === "unchecked") {
-                checks.push({ id: `team:${label}`, ok: true, note: true, line: `team ${label}: readiness not checked yet` });
-                continue;
-            }
-            const bad = team.readiness.checks.filter((c) => c.state !== "pass");
-            if (bad.length === 0 && team.readiness.status === "ready") {
-                checks.push({ id: `team:${label}`, ok: true, line: `team ${label}: ready` });
-                continue;
-            }
-            for (const c of bad) {
-                const meta = doc.readinessChecks.find((r) => r.id === c.id);
-                const needsAnswer = meta?.needsAnswer ?? true;
-                checks.push({
-                    id: `team:${label}:${c.id}`,
-                    ok: !needsAnswer && c.state !== "fail",
-                    note: !needsAnswer,
-                    line: `team ${label}: ${c.id} is ${c.state}${c.reason ? ` (${c.reason}${c.count !== undefined ? ` ×${c.count}` : ""})` : ""}${meta ? `, ${meta.severity}` : ""}`,
-                    fix: `open settings for team ${label} and resolve ${c.id}`,
-                    who: needsAnswer ? who : "nobody yet; it is informational",
-                });
-            }
-            if (bad.length === 0 && team.readiness.status !== "ready") {
-                checks.push({ id: `team:${label}`, ok: team.readiness.status !== "blocked", note: team.readiness.status === "degraded", line: `team ${label}: ${team.readiness.status}`, fix: `open settings for team ${label}`, who });
-            }
-        }
-    }
-    const ready = checks.every((c) => c.ok || c.note);
-    return { ready, checks, replica };
-}
-export async function cmdReady(args, ctx, deps) {
-    const report = await readyReport(ctx, deps);
-    if (args.json) {
-        ctx.stdout(JSON.stringify(report));
-    }
-    else {
-        for (const c of report.checks) {
-            ctx.stdout(`${c.note ? "note" : c.ok ? "ok " : "FAIL"}  ${c.line}`);
-            if (!c.ok && !c.note) {
-                if (c.fix)
-                    ctx.stdout(`      fix: ${c.fix}`);
-                if (c.who)
-                    ctx.stdout(`      who: ${c.who}`);
-            }
-        }
-        ctx.stdout(report.ready ? "READY" : "NOT READY");
-    }
-    return report.ready ? 0 : 1;
-}

package/dist/release.js

@@ -1,142 +0,0 @@
-// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
-// ticket on one team parked under one failure class, through the contract's `ticket-release` and
-// `ticket-release-class` routes. The cloud reads every governor holding the ticket and either releases
-// all of them or releases nothing and names, per governor, the human action that does fix it; this verb
-// prints that answer and exits 1 on a refusal so a script can branch on it.
-//
-// ⛔ NOTHING IS RELEASED WITHOUT A REASON. `--because` (what changed) is required on a real release and
-// is recorded in the tenant's release audit; only `--dry-run` may omit it. `--retry-unchanged` is the
-// explicit statement that something the mirror cannot see changed — the cloud refuses an unchanged
-// cause without it.
-import { flagBool, flagString, positionals } from "./args.js";
-import { requireConfig } from "./config.js";
-import { loadContract } from "./contract.js";
-import { CliError, UsageError } from "./errors.js";
-import { needsNewerCloud } from "./execution.js";
-import { apiClient } from "./transport.js";
-/** One release written as a person reads it: "unparked implement", "cleared the validate hold". */
-export function describeAction(a) {
-    switch (a.op) {
-        case "unpark":
-            return `unparked ${a.phase ?? "a phase"}`;
-        case "clear_validate_hold":
-            return "cleared the validate hold";
-        case "clear_no_change_hold":
-            return "cleared the no-change hold";
-        case "grant_round_threshold_cycle":
-            return "bought one more repair cycle";
-        default:
-            return `${a.op}${a.phase ? ` at ${a.phase}` : ""}`;
-    }
-}
-const refusalLine = (r) => `  ${r.code}: ${r.humanAction}`;
-export function renderTicketRelease(ticket, r) {
-    if (r.error === "team_changed") {
-        return [`${ticket} moved from team ${r.expectedTeamKey ?? "(none)"} to ${r.teamKey ?? "(none)"} while the release was being checked — run it again`];
-    }
-    const lines = [];
-    const dry = r.dryRun === true;
-    if (r.outcome === "nothing-held") {
-        lines.push(`${ticket}: nothing holds this ticket — run \`catalyst-skills explain ${ticket}\` for why it is not running`);
-    }
-    else if (r.outcome === "refused") {
-        lines.push(dry ? `${ticket} (dry run): would be refused — nothing would be released:` : `${ticket}: refused — nothing was released:`);
-        for (const x of r.refused ?? [])
-            lines.push(refusalLine(x));
-        const blocked = r.releasable ?? [];
-        if (blocked.length > 0)
-            lines.push(`  (it would otherwise have ${blocked.map(describeAction).join(", ")})`);
-    }
-    else if (dry) {
-        lines.push(`${ticket} (dry run): would release — ${(r.releasable ?? []).map(describeAction).join(", ")}`);
-    }
-    else {
-        lines.push(`${ticket}: released — ${(r.released ?? []).map(describeAction).join(", ")}`);
-    }
-    for (const w of r.warnings ?? [])
-        lines.push(`warning: ${w}`);
-    return lines;
-}
-export function renderClassRelease(r) {
-    const released = r.released ?? [];
-    const refused = r.refused ?? [];
-    const nothing = r.nothingHeld ?? [];
-    const head = `${r.team ?? "?"} ${r.class ?? "?"}${r.dryRun ? " (dry run)" : ""}: released ${released.length}, refused ${refused.length}, nothing held ${nothing.length}${r.truncated ? " (more remain — run it again)" : ""}`;
-    const lines = [head];
-    for (const t of released) {
-        const actions = r.dryRun ? (t.releasable ?? []) : (t.released ?? []);
-        lines.push(`  ${r.dryRun ? "would release" : "released"} ${t.ticket ?? "?"}: ${actions.map(describeAction).join(", ")}`);
-    }
-    for (const t of refused) {
-        for (const x of t.refused ?? [])
-            lines.push(`  refused ${t.ticket ?? "?"} — ${x.code}: ${x.humanAction}`);
-    }
-    if (nothing.length > 0)
-        lines.push(`  nothing held: ${nothing.join(", ")}`);
-    return lines;
-}
-/** The contract's route by name, or the "your cloud is older" error when this tenant does not serve it. */
-function releaseRoute(doc, name, cfg) {
-    const route = doc.routes.find((r) => r.method === "POST" && r.path.split("/").filter(Boolean).at(-1) === name);
-    if (!route)
-        throw needsNewerCloud(`release (the tenant contract serves no "${name}" route)`, cfg);
-    return route.path;
-}
-export async function cmdRelease(args, ctx) {
-    const [ticket, ...extra] = positionals(args);
-    const failureClass = flagString(args, "class");
-    const team = flagString(args, "team");
-    const because = flagString(args, "because");
-    const dryRun = flagBool(args, "dry-run");
-    const retryUnchanged = flagBool(args, "retry-unchanged");
-    if (extra.length > 0)
-        throw new UsageError("release takes one ticket");
-    if (failureClass !== undefined && ticket !== undefined) {
-        throw new UsageError("release takes a ticket or --class with --team, not both");
-    }
-    if (failureClass === undefined && ticket === undefined) {
-        throw new UsageError("release needs a ticket, or --class <failure-class> --team <K>");
-    }
-    if (failureClass !== undefined && team === undefined)
-        throw new UsageError("release --class needs --team <K>");
-    if (because === undefined && !dryRun) {
-        throw new UsageError("release needs --because <what changed> (recorded in the release audit), or --dry-run to preview");
-    }
-    const limitRaw = flagString(args, "limit");
-    const limit = limitRaw === undefined ? undefined : Number(limitRaw);
-    if (limit !== undefined && !Number.isInteger(limit))
-        throw new UsageError("--limit must be an integer");
-    const cfg = requireConfig(ctx);
-    const { doc } = await loadContract(ctx, cfg);
-    const api = apiClient(cfg, ctx);
-    const common = { ...(because !== undefined ? { because } : {}), retryUnchanged, dryRun };
-    if (failureClass !== undefined) {
-        const path = releaseRoute(doc, "ticket-release-class", cfg);
-        const res = await api.postJson(path, {
-            team,
-            class: failureClass,
-            ...common,
-            ...(limit !== undefined ? { limit } : {}),
-        });
-        if (args.json)
-            ctx.stdout(JSON.stringify(res.body));
-        else
-            for (const line of renderClassRelease(res.body))
-                ctx.stdout(line);
-        // A real class release that refused any ticket exits 1, the same contract as a single refusal.
-        return res.body.dryRun !== true && (res.body.refused ?? []).length > 0 ? 1 : 0;
-    }
-    const id = ticket;
-    const path = releaseRoute(doc, "ticket-release", cfg);
-    const res = await api.postJson(path, { ticket: id, ...common }, { accept: [404, 409] });
-    if (res.status === 404) {
-        throw new CliError(`ticket ${id} is not in this tenant's mirror — check the identifier`, "ticket-unknown");
-    }
-    if (args.json)
-        ctx.stdout(JSON.stringify(res.body));
-    else
-        for (const line of renderTicketRelease(id, res.body))
-            ctx.stdout(line);
-    const refused = res.status === 409 || (res.body.outcome === "refused" && res.body.dryRun !== true);
-    return refused ? 1 : 0;
-}