@catalyst-cloud/catalyst-skills 0.5.0 → 0.7.0

package/dist/pagination.js

@@ -0,0 +1,76 @@
+// pagination.ts — the mirror's keyset contract, followed. `/issues` and `/pulls` answer a page plus
+// three headers: X-Mirror-Cursor (the head seq the page is consistent with), X-Mirror-Total (the
+// WHOLE scope's count, independent of the page) and X-Mirror-Next-Cursor — present ONLY while rows
+// remain, ABSENT on the last page. A caller that ignores them gets a page and believes it is the
+// answer, which is the whole of CTC-2010.
+//
+// The SDK's createTenantClient parses these same three headers into a typed KeysetPageMeta, and this
+// module deliberately does not use it: that client takes a STATIC `key`, while this bundle resolves
+// its bearer fresh per request through `bearerFor` (an OAuth session refreshes mid-walk), and `ask`
+// must keep working on a runtime where the SDK cannot load (src/sdk.ts). Adopting it is the CTC-2004
+// Tier 2 migration that also deletes transport.ts — not this change.
+import { CliError } from "./errors.js";
+export const NEXT_CURSOR_HEADER = "x-mirror-next-cursor";
+export const TOTAL_HEADER = "x-mirror-total";
+/** The server clamps every page to this regardless of the requested `limit` (MAX_VIEW_LIMIT). */
+export const SERVER_PAGE_CAP = 500;
+/** 100 pages × 500 rows = 50,000. Reaching it is a refusal, not an ending. */
+export const MAX_PAGES = 100;
+/** The API answers a list route with either a bare array or `{rows|items|issues|...: []}`. */
+export function rowsOf(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body && typeof body === "object") {
+        for (const key of ["rows", "items", "issues", "pulls", "projects", "cycles", "results", "changes", "data"]) {
+            const v = body[key];
+            if (Array.isArray(v))
+                return v;
+        }
+    }
+    return [];
+}
+function readTotal(headers) {
+    const raw = headers.get(TOTAL_HEADER);
+    if (raw === null)
+        return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : null;
+}
+export async function fetchPage(api, path, query) {
+    const res = await api.getJson(path, { query });
+    const next = res.headers.get(NEXT_CURSOR_HEADER);
+    return {
+        rows: rowsOf(res.body),
+        nextCursor: next === null || next === "" ? null : next,
+        total: readTotal(res.headers),
+    };
+}
+export async function fetchAllPages(api, path, query) {
+    const rows = [];
+    const seen = new Set();
+    let after;
+    let total = null;
+    for (let pages = 1; pages <= MAX_PAGES; pages++) {
+        const page = await fetchPage(api, path, { ...query, limit: SERVER_PAGE_CAP, after });
+        rows.push(...page.rows);
+        if (page.total !== null)
+            total = page.total;
+        if (page.nextCursor === null)
+            return { rows, total, pages };
+        // ⛔ A cursor that does not advance is an infinite loop, not a long read.
+        if (seen.has(page.nextCursor)) {
+            throw new CliError(`GET ${path} repeated a page cursor after ${rows.length} rows — the cloud is not advancing the keyset, so --all cannot finish`, "pagination-stalled", 1);
+        }
+        seen.add(page.nextCursor);
+        after = page.nextCursor;
+    }
+    throw new CliError(`GET ${path} still had pages after ${MAX_PAGES} of them (${rows.length} rows) — narrow the scope with --team/--project/--state, or read this through the replica`, "pagination-overrun", 1);
+}
+/** ⛔ N IS WHAT THE SERVER SENT, not what a client-side filter left. `--team ZZZ` over a capped page
+ *  would otherwise read "truncated at 0 of 120", which names the filter, not the truncation. */
+export function truncationNotice(page) {
+    if (page.nextCursor === null)
+        return null;
+    const of = page.total === null ? `an unknown total (the cloud sent no ${TOTAL_HEADER})` : String(page.total);
+    return `truncated at ${page.rows.length} of ${of} — re-run with --all to read the whole scope`;
+}

package/dist/published.js

@@ -0,0 +1,75 @@
+// published.ts — "what is the newest release of this package?", read from the npm registry. This is
+// the ONLY non-tenant host this package contacts. `ready` has always been an offline command, so the
+// answer is cached for six hours, the request is capped at 1500ms, and EVERY failure returns a
+// reason instead of throwing: a customer who cannot reach npm must still get a verdict (CTC-2160).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { PACKAGE_NAME, publishedCachePathFor } from "./config.js";
+export const REGISTRY_DIST_TAGS_URL = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+export const PUBLISHED_TTL_SECONDS = 6 * 60 * 60;
+export const PUBLISHED_TIMEOUT_MS = 1500;
+function readPublishedCache(home) {
+    const path = publishedCachePathFor(home);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.fetchedAt !== "string" || typeof parsed.latest !== "string")
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** A write failure (read-only home) must not break the lookup — best-effort only. */
+function writePublishedCache(home, cache) {
+    try {
+        const path = publishedCachePathFor(home);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, JSON.stringify(cache, null, 2) + "\n", { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    catch {
+        // best-effort: a stale or missing cache next time is not a new failure mode
+    }
+}
+function fallback(cached, reason) {
+    return cached ? { latest: cached.latest, reason: null, source: "stale-cache" } : { latest: null, reason, source: "none" };
+}
+export async function latestPublishedVersion(ctx, opts = {}) {
+    const cached = readPublishedCache(ctx.home);
+    const ageSeconds = cached ? Math.max(0, Math.floor((ctx.now().getTime() - Date.parse(cached.fetchedAt)) / 1000)) : Infinity;
+    if (cached && ageSeconds < PUBLISHED_TTL_SECONDS) {
+        return { latest: cached.latest, reason: null, source: "cache" };
+    }
+    if (opts.offline) {
+        return cached ? { latest: cached.latest, reason: null, source: "cache" } : { latest: null, reason: "offline", source: "none" };
+    }
+    let res;
+    try {
+        res = await ctx.fetch(REGISTRY_DIST_TAGS_URL, {
+            signal: AbortSignal.timeout(PUBLISHED_TIMEOUT_MS),
+            headers: { accept: "application/json" },
+        });
+    }
+    catch (err) {
+        const reason = err instanceof Error && err.name === "TimeoutError" ? "timed out" : err instanceof Error ? err.message : String(err);
+        return fallback(cached, reason);
+    }
+    if (!res.ok)
+        return fallback(cached, `registry answered ${res.status}`);
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return fallback(cached, "the registry sent an unreadable body");
+    }
+    const latest = body?.latest;
+    if (typeof latest !== "string")
+        return fallback(cached, "the registry sent no dist-tags.latest");
+    writePublishedCache(ctx.home, { fetchedAt: ctx.now().toISOString(), latest });
+    return { latest, reason: null, source: "network" };
+}

package/dist/query.js

@@ -2,13 +2,18 @@
 // 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 { flagInt, flagString, positionals } from "./args.js";
+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)
@@ -19,10 +24,20 @@ export async function cmdQuery(args, ctx, deps = {}) {
         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;
@@ -34,6 +49,10 @@ export async function cmdQuery(args, ctx, deps = {}) {
         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}`;
@@ -90,8 +109,16 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
     const common = { team: f.team, project: f.project, state: f.state, limit: f.limit };
     switch (sub) {
         case "issues": {
-            const res = await api.getJson("/api/v1/issues", { query: common });
-            return applyFilters(rowsOf(res.body), f).slice(0, f.limit);
+            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>");
@@ -99,8 +126,17 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
             return res.status === 404 ? null : res.body;
         }
         case "pulls": {
-            const res = await api.getJson("/api/v1/pulls", { query: { limit: f.limit, ticket: flagString(args, "ticket") } });
-            return rowsOf(res.body).slice(0, f.limit);
+            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>");
@@ -177,19 +213,6 @@ function needArg(rest, usage) {
         throw new UsageError(`query ${usage}`);
     return v;
 }
-/** The API answers a list route with either a bare array or `{rows|items|issues|...: []}`. */
-export function rowsOf(body) {
-    if (Array.isArray(body))
-        return body;
-    if (body && typeof body === "object") {
-        for (const key of ["rows", "items", "issues", "pulls", "projects", "cycles", "results", "changes", "data"]) {
-            const v = body[key];
-            if (Array.isArray(v))
-                return v;
-        }
-    }
-    return [];
-}
 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))

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);