@catalyst-cloud/catalyst-skills 0.4.0 → 0.7.0

package/dist/ready.js

@@ -6,23 +6,42 @@ import { join } from "node:path";
 import { defaultSkillsDirFor, loadConfig, readManifest } from "./config.js";
 import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
-import { replicaStatus, statusLine } from "./replica.js";
+import { latestPublishedVersion } from "./published.js";
+import { replicaStatus, writerIsRunning } from "./replica.js";
 import { loadSdk } from "./sdk.js";
-/** True when `a` is a semver-older release than `b`. Prerelease/build metadata is ignored; a segment
- *  that does not parse counts as 0. A tiny compare on purpose — no dependency for three fields. */
-export function semverOlder(a, b) {
-    const parse = (v) => {
-        const core = v.split("-")[0].split("+")[0];
-        const p = core.split(".");
-        return [Number(p[0]) || 0, Number(p[1]) || 0, Number(p[2]) || 0];
-    };
-    const [a0, a1, a2] = parse(a);
-    const [b0, b1, b2] = parse(b);
-    if (a0 !== b0)
-        return a0 < b0;
-    if (a1 !== b1)
-        return a1 < b1;
-    return a2 < b2;
+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}`);
@@ -79,6 +98,61 @@ export async function readyReport(ctx, deps) {
             });
         }
     }
+    // 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}` }
@@ -87,7 +161,6 @@ export async function readyReport(ctx, deps) {
     // 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 skillsDir = cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
     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) {
@@ -107,12 +180,30 @@ export async function readyReport(ctx, deps) {
         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: statusLine(replica) });
+    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;
@@ -140,7 +231,7 @@ export async function readyReport(ctx, deps) {
         }
     }
     const ready = checks.every((c) => c.ok || c.note);
-    return { ready, checks };
+    return { ready, checks, replica };
 }
 export async function cmdReady(args, ctx, deps) {
     const report = await readyReport(ctx, deps);

package/dist/release.js

@@ -0,0 +1,142 @@
+// 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;
+}