@catalyst-cloud/catalyst-skills 0.4.0 → 0.5.0

package/skills/unstick/scripts/lib/cli.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
+// to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
+// Run any script beside this one with --help; this file is a library and is never run directly.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
+ * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = loadConfig();
+  const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const cmd = useRecorded ? process.execPath : "npx";
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

package/skills/unstick/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/unstick/scripts/unstick.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// unstick.mjs — "why is this stuck, and can it be released?" in one JSON document. Runs
+// `catalyst-skills explain`, `explain --history` and a dry-run `release` for one ticket (or a dry-run
+// class release for one team), and only with --because runs the real release. Reaches the cloud only
+// by spawning the CLI.
+import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+
+const SPEC = {
+  because: { value: true, help: "what changed since the ticket was held; runs the real release after the preview" },
+  "retry-unchanged": { value: false, help: "release even though nothing the cloud can see changed (say what did in --because)" },
+  class: { value: true, help: "release every ticket on --team parked under this failure class" },
+  team: { value: true, help: "with --class: the team key" },
+  limit: { value: true, help: "with --class: at most this many tickets (the cloud caps it at 25)" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const ticket = positionals[0];
+const byClass = typeof flags.class === "string";
+if (help || (!ticket && !byClass) || (byClass && (ticket || typeof flags.team !== "string"))) {
+  printHelp("node scripts/unstick.mjs <ticket> [--because <text>] [--retry-unchanged] [--help] | --class <c> --team <K> [--because <text>] [--retry-unchanged] [--limit N] [--help]", SPEC, [
+    "Without --because it changes nothing: it prints the explanation, the history (every governor holding the ticket",
+    "and past releases) and a dry-run release. With --because it then runs the real release. Read references/playbook.md",
+    "before passing --because. A refused release exits 1 with the refusals in the document.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const releaseArgs = byClass ? ["release", "--class", flags.class, "--team", flags.team] : ["release", ticket];
+if (flags["retry-unchanged"]) releaseArgs.push("--retry-unchanged");
+if (byClass && typeof flags.limit === "string") releaseArgs.push("--limit", flags.limit);
+
+const out = {};
+if (!byClass) {
+  out.explain = parseJson(mustRun(["explain", ticket, "--json"]).stdout, "explain");
+  out.history = parseJson(mustRun(["explain", ticket, "--history", "--json"]).stdout, "history");
+}
+
+const preview = runCli([...releaseArgs, "--dry-run", "--json"]);
+if (preview.code !== 0 && preview.code !== 1) {
+  process.stderr.write(preview.stderr);
+  process.exit(preview.code);
+}
+out.preview = parseJson(preview.stdout, "the dry-run release");
+
+let exit = 0;
+if (typeof flags.because === "string") {
+  const real = runCli([...releaseArgs, "--because", flags.because, "--json"]);
+  if (real.code !== 0 && real.code !== 1) {
+    process.stderr.write(real.stderr);
+    process.exit(real.code);
+  }
+  out.release = parseJson(real.stdout, "the release");
+  exit = real.code;
+}
+
+process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+process.exit(exit);

package/skills/what-needs-me/scripts/lib/cli.mjs

@@ -6,6 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -21,7 +22,7 @@ export function loadConfig() {
   if (!existsSync(path)) notConfigured(`no config at ${path}`);
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof cfg !== "object" || cfg === null || typeof cfg.key !== "string") notConfigured(`config at ${path} has no key`);
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
     return cfg;
   } catch (err) {
     if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
@@ -30,7 +31,7 @@ export function loadConfig() {
 }
 
 function notConfigured(why) {
-  process.stderr.write(`not connected (${why}) — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login\n`);
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/what-needs-me/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/whats-happening/SKILL.md

@@ -36,7 +36,7 @@ For depth beyond these, load the fact skills: `how-catalyst-works` (the ladder,
 - **Their tenant, as them.** Every read goes through the CLI, which holds the person's own key, the tenant and who they are. You never name, guess at, or try another tenant, and you never paste the key anywhere. "You" in your reply means the connected person: their assigned tickets, their asks.
 - **Tenant facts come from the contract, live.** Stage names, label names, team keys, thresholds and the ladder are in the snapshot's `tenant` block; read them there each time and never restate them from memory.
 - **One reply, ticket ids on every line, source named.** The reply opens with when the snapshot was taken and whether the replica or the API answered. A stale replica is stated, never hidden.
-- **Say what a key cannot see.** PR labels and reactions are not mirrored, and a park is released only by an operator; the CLI prints the settings URL, and you repeat it instead of guessing. Coding-account status (`accounts`) and per-ticket execution history (`explain --history`) are readable — read them.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI prints the settings URL, and you repeat it instead of guessing. A park or hold is released from the person's own login once its cause is fixed: route that to the `unstick` skill (`catalyst-skills release`), never tell them it needs an operator. Coding-account status (`accounts`) and per-ticket execution history (`explain --history`) are readable — read them.
 - **No polling.** One snapshot per question. Waiting on a change is the project owner's job (`run-this-project` subscribes to the tenant stream); the desk never loops a read.
 - **You are not the owner.** You route work and make it visible; you do not dispatch, overrule a project owner, or run long work in this session.
 - **Never answer as the human.** A decision is an ask through `what-needs-me`, filed before anyone proceeds on its default; the answer is recorded there as the app actor.

package/skills/whats-happening/references/why-is-it-stuck.md

@@ -34,13 +34,18 @@ This reference restates an invariant: the vocabulary the cloud's eligibility exp
 | `repo_paused` | an operator paused the repository | the operator resumes it |
 | `scope_overlap` | its declared file scope intersects a ticket already in flight | wait for the other ticket, or the human decides which goes first |
 
-## Reasons that need an operator, and what a key cannot do
+## Reasons a release clears once the cause is fixed
+
+These do not release themselves, and nobody but the person needs to act: once the recorded cause is fixed, the person's own login releases them with `catalyst-skills release <ticket>`. The desk does not release; route the ticket to the `unstick` skill, which reads the history, previews the release and runs it, or names what a person must do first.
 
 | reason | what it means | note |
 | -- | -- | -- |
-| `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | an operator unparks it; your key has no unpark verb, so the reply names the park (from `explain --history`) and the settings page |
+| `phase_parked` / `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | `unstick`; `explain --history` names the park and the failure class it recorded |
 | `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above |
-| `validate_class_spent` | this validate failure already spent its one repair round in this episode | as above; a human comment may release the hold |
+| `validate_class_spent` | this validate failure already spent its one repair round in this episode | a push or a comment saying what to change releases it on its own; otherwise `unstick` |
+| `human_owned_pr` | a person's own pull request holds the ticket | that person closes or merges it; no release clears it |
+| `review_not_converging` | review and repair kept finding new problems without converging | a person reads the findings and comments on the ticket to resume; raise an ask for that read |
+| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud raised, or pushes a fix |
 | `no_branch_to_remediate` / `branch_missing` / `branch_gone` | a branch-dependent phase has no branch to clone | the cloud releases missing-branch parks on its own budget; a deleted branch needs a human to decide |
 | `stale_failure_episode` | the ladder advanced after the recorded failure | informational; the round is dropped |
 
@@ -50,7 +55,7 @@ This reference restates an invariant: the vocabulary the cloud's eligibility exp
 
 ## When the cloud could not judge
 
-A status of `unknown` with a reason such as `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. If one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
+A status of `unknown` with a reason such as `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. `workflow_mapping_unknown`, and `ordering_never_published` beside it, does not clear by itself when the team has no saved stage mapping: `explain` then names the missing stages, and a tenant owner or admin maps the team in Settings → Linear teams. If any other one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
 
 ## The one advisory
 

package/skills/whats-happening/scripts/lib/cli.mjs

@@ -6,6 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -21,7 +22,7 @@ export function loadConfig() {
   if (!existsSync(path)) notConfigured(`no config at ${path}`);
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof cfg !== "object" || cfg === null || typeof cfg.key !== "string") notConfigured(`config at ${path} has no key`);
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
     return cfg;
   } catch (err) {
     if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
@@ -30,7 +31,7 @@ export function loadConfig() {
 }
 
 function notConfigured(why) {
-  process.stderr.write(`not connected (${why}) — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login\n`);
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/whats-happening/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}