@catalyst-cloud/catalyst-skills 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.3.1
+
+`ready` now names the person you connected as: when your key is a personal key, the config line reads "joined <tenant> as <you> (<role>)" instead of the generic "as service" that every api key showed, and an account (host) key still names the tenant with no person. `ready` also learns the bundle version your tenant expects, when the cloud publishes one: if this installed bundle is older than that minimum you get a one-line warning that names both versions and the upgrade command, but it stays a note — `ready` never refuses over a stale bundle, and a cloud that does not publish a minimum changes nothing. `explain` no longer calls every ticket with no dispatch row "unknown": a ticket that merely sits in Backlog (or any non-dispatch state) is now named as known to the mirror with the state it is in, and only a ticket the mirror has never seen keeps the unknown wording.
+
 ## 0.3.0
 
 You connect with your own personal key now, not the tenant's shared account key: mint it yourself at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed), and `login` prints who you connected as beside which tenant. Your agent acts as you — an ask it raises names you, and "what needs me" means you: `ask list` (and the what-needs-me skill) keeps only the asks assigned to your Linear user by default, `--anyone` lists the whole tenant, and when your Linear identity is not matched yet it says so and shows everything rather than an empty list. `customer.json` gains a `user` block (id, label, role, your Linear user id); an older config is still read unchanged. Connecting with the account key still works — it is the right credential for a host or daemon — but `login` tells you it names no person. Every skill, reference and help line that said "account key", or said execution history and coding-account status were not readable, has been rewritten: `explain --history` and `accounts` read them, and the two things your key genuinely cannot do (release a park, read PR labels or reactions) are named instead. The catalyst-setup reference now lists all eleven team checks, including `environment_declared`. Needs a cloud that admits personal keys on the agent routes; on an older cloud the contract read says so by name, and the account key still works until it is updated.

package/README.md

@@ -145,10 +145,10 @@ The skill files themselves are written by whichever install command you ran, in
 
 ## Updating
 
-A plugin install updates when we ship. Skills copied by `npx skills add` do not; run `npx skills update -y` to refresh them. Update the CLI with `npm update -g @catalyst-cloud/catalyst-skills`, or run any command against the latest publish with `npx @catalyst-cloud/catalyst-skills@latest login`. The next `catalyst-skills` run prints a one-line notice:
+A plugin install updates when we ship. Skills copied by `npx skills add` do not; run `npx skills update -y` to refresh them. Update the CLI with `npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login` — the re-login rewrites the CLI path the skills spawn, so they stop running the old bundle. To run one command against the latest publish without installing, use `npx @catalyst-cloud/catalyst-skills@latest login`. The next `catalyst-skills` run prints a one-line notice:
 
 ```
-[catalyst-skills] updated 0.1.1 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm update -g @catalyst-cloud/catalyst-skills (or: npx @catalyst-cloud/catalyst-skills@latest login)
+[catalyst-skills] updated 0.1.1 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login
 ```
 
 A `customer.json` written by an older bundle is still read unchanged; it gains the CLI path and the cached contract the next time you run `catalyst-skills login`.

package/dist/contract.js

@@ -45,7 +45,7 @@ export function assertContractRange(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");
+        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login) or ask your tenant admin which version is live`, "contract-version");
     }
 }
 /**

package/dist/execution.js

@@ -61,9 +61,15 @@ export function describeReason(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)
+export function renderExplain(ticket, row, team, knownState) {
+    if (!row) {
+        // A null dispatch row is not proof the ticket does not exist — the explainer is a dispatch scan. When
+        // `knownState` is set (the mirror answered GET /issues/:id) the ticket is real; it just sits outside a
+        // dispatch column. Only a 404 (knownState null/absent) is truly unknown to the mirror.
+        if (knownState)
+            return `${ticket}: known to the mirror; state ${knownState} is not a dispatch state.`;
         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";
@@ -115,11 +121,20 @@ export async function cmdExplain(args, ctx) {
     });
     const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
     const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as known.
+    // The mirror compares identifiers exactly, so normalize (uppercase) as the row lookup above does —
+    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 as unknown.
+    let knownState = null;
+    if (!row) {
+        const probe = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket.toUpperCase())}`, { accept: [404] });
+        if (probe.status !== 404)
+            knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
+    }
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team) }));
+        ctx.stdout(JSON.stringify({ ticket, row, explanation: renderExplain(ticket, row, team, knownState) }));
     }
     else {
-        ctx.stdout(renderExplain(ticket, row, team));
+        ctx.stdout(renderExplain(ticket, row, team, knownState));
     }
     return 0;
 }

package/dist/ready.js

@@ -8,6 +8,22 @@ import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
 import { replicaStatus, statusLine } 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;
+}
 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)";
@@ -22,7 +38,16 @@ export async function readyReport(ctx, deps) {
     try {
         cfg = loadConfig(ctx.home);
         checks.push(cfg
-            ? { id: "config", ok: true, line: `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}` }
+            ? {
+                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: "CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login", who: "you (mint the key at Settings → API keys)" });
     }
     catch (err) {
@@ -34,11 +59,26 @@ export async function readyReport(ctx, deps) {
         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 update -g @catalyst-cloud/catalyst-skills", who: "you" });
+        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`,
+            });
+        }
+    }
     if (cfg) {
         checks.push(cfg.cliPath && existsSync(cfg.cliPath)
             ? { id: "cliPath", ok: true, line: `cliPath: ${cfg.cliPath}` }

package/dist/skills.js

@@ -70,5 +70,9 @@ export function readChangelog() {
 }
 export function updateNoticeLine(previous, current, entry) {
     const summary = entry ?? "see CHANGELOG.md";
-    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm update -g ${PACKAGE_NAME} (or: npx ${PACKAGE_NAME}@latest login)`;
+    // `npm update -g` treats a global install as a caret range, and a caret below 1.0.0 never moves a
+    // minor — so it never crosses 0.2.x → 0.3.0. Pin @latest via `npm install`, THEN re-run login: the
+    // install alone does not rewrite customer.json.cliPath, so the skill helpers would keep spawning the
+    // stale recorded bundle and repeat this notice forever; the new global bin records its own path.
+    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm install -g ${PACKAGE_NAME}@latest && catalyst-skills login`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Customer skill bundle for Catalyst Cloud: eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",