@catalyst-cloud/cli 0.13.0 → 0.13.1

package/skills/how-catalyst-works/scripts/lib/cli.mjs

@@ -1,164 +0,0 @@
-#!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
-// this machine connected with (the path recorded in customer.json, else npx) and hands back its
-// output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = CONNECT_COMMAND;
-
-/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
-export function configPath() {
-  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
-  return join(home, ".config", "catalyst-cloud", "customer.json");
-}
-
-/** The config, or a one-line reason it could not be read. Never throws. */
-export function loadConfig() {
-  const path = configPath();
-  if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
-  try {
-    const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing a key or login, or the account` };
-    }
-    return { ok: true, cfg, path };
-  } catch (err) {
-    return { ok: false, reason: `${path} is unreadable: ${err instanceof Error ? err.message : String(err)}` };
-  }
-}
-
-/** Exit 2 with the one line every script prints when this machine is not connected to a tenant. */
-export function notConfigured(reason) {
-  console.error(`not connected to a Catalyst Cloud tenant (${reason}) — run: ${CONNECT_HINT}`);
-  process.exit(2);
-}
-
-/**
- * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
- * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
- * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
- */
-export function runCli(args, { stdin } = {}) {
-  const loaded = loadConfig();
-  if (!loaded.ok) notConfigured(loaded.reason);
-  const { cfg } = loaded;
-  let cmd;
-  let argv;
-  let shell = false;
-  if (typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
-    cmd = process.execPath;
-    argv = [cfg.cliPath, ...args];
-  } else {
-    cmd = process.platform === "win32" ? "npx.cmd" : "npx";
-    argv = [PACKAGE, ...args];
-    shell = process.platform === "win32";
-  }
-  const r = spawnSync(cmd, argv, {
-    encoding: "utf8",
-    input: stdin,
-    env: process.env,
-    shell,
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  if (r.error) {
-    console.error(`could not run ${cmd}: ${r.error.message} — re-run ${CONNECT_HINT} to record the CLI path`);
-    process.exit(2);
-  }
-  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
-}
-
-/** Print the CLI's stderr (the source line, the contract line, any refusal) on our stderr. */
-export function relayStderr(r) {
-  const text = r.stderr.trimEnd();
-  if (text) console.error(text);
-}
-
-/** A non-zero CLI result ends the script with the same code, its stdout shown so nothing is lost. */
-export function exitOnFailure(r) {
-  if (r.code === 0) return;
-  relayStderr(r);
-  const out = r.stdout.trimEnd();
-  if (out) console.log(out);
-  process.exit(r.code);
-}
-
-export function parseJson(text) {
-  try {
-    return JSON.parse(text.trim());
-  } catch {
-    return null;
-  }
-}
-
-/**
- * A small flag parser: `spec.value` names flags that take a value, `spec.bool` boolean flags,
- * `spec.repeat` value flags that may repeat (collected into arrays). Unknown flags are a usage error.
- */
-export function parseFlags(argv, spec = {}) {
-  const value = new Set(spec.value ?? []);
-  const bool = new Set(spec.bool ?? []);
-  const repeat = new Set(spec.repeat ?? []);
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--") {
-      positionals.push(...argv.slice(i + 1));
-      break;
-    }
-    if (!a.startsWith("--")) {
-      positionals.push(a);
-      continue;
-    }
-    let name = a.slice(2);
-    let inline;
-    const eq = name.indexOf("=");
-    if (eq !== -1) {
-      inline = name.slice(eq + 1);
-      name = name.slice(0, eq);
-    }
-    if (bool.has(name)) {
-      flags[name] = true;
-    } else if (value.has(name) || repeat.has(name)) {
-      const v = inline ?? argv[++i];
-      if (v === undefined || v === "") usage(`--${name} needs a value`);
-      if (repeat.has(name)) (flags[name] ??= []).push(v);
-      else flags[name] = v;
-    } else {
-      usage(`unknown option --${name}`);
-    }
-  }
-  return { flags, positionals };
-}
-
-export function usage(message) {
-  console.error(message);
-  process.exit(1);
-}
-
-export function wantsHelp(argv) {
-  return argv.includes("--help") || argv.includes("-h");
-}
-
-const runDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
-if (runDirectly) {
-  if (wantsHelp(process.argv.slice(2)) || process.argv.length <= 2) {
-    console.log(
-      [
-        "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
-        "",
-        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
-        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
-        "",
-        `Connect first with: ${CONNECT_HINT}`,
-        `Config in use: ${configPath()}`,
-      ].join("\n"),
-    );
-    process.exit(0);
-  }
-}

package/skills/how-catalyst-works/scripts/lib/credential.mjs

@@ -1,29 +0,0 @@
-#!/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/how-catalyst-works/scripts/whats-running.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-// whats-running.mjs — what Catalyst is executing right now (fleet activity, the agent roster, lease
-// attributions), optionally the dispatch queue and the coding-account line.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>] [--json]
-
-Prints what is executing on your tenant. Wraps: catalyst-skills running, queue, accounts.
-
-  --queue        also print the dispatch queue (what runs next, in order)
-  --team <key>   with --queue: one team's queue
-  --accounts     also print the coding-account line (provider, state, windows — never a credential)
-  --json         one JSON document: { running, queue?, accounts? }
-  --help         this text
-
-Exit 0, 1 on a usage error, 2 when this machine is not connected to a tenant or the cloud refused
-a read (the line says which).`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags } = parseFlags(argv, { bool: ["queue", "accounts", "json"], value: ["team"] });
-
-const out = {};
-const running = runCli(["running", "--json"]);
-exitOnFailure(running);
-relayStderr(running);
-out.running = parseJson(running.stdout) ?? running.stdout.trimEnd();
-
-if (flags.queue) {
-  const args = ["queue", "--json"];
-  if (flags.team) args.push("--team", flags.team);
-  const queue = runCli(args);
-  exitOnFailure(queue);
-  relayStderr(queue);
-  out.queue = parseJson(queue.stdout) ?? queue.stdout.trimEnd();
-}
-
-if (flags.accounts) {
-  const accounts = runCli(["accounts"]);
-  exitOnFailure(accounts);
-  relayStderr(accounts);
-  out.accounts = accounts.stdout.trimEnd();
-}
-
-if (flags.json) {
-  console.log(JSON.stringify(out));
-  process.exit(0);
-}
-
-const section = (title, value) => {
-  console.log(`== ${title}`);
-  console.log(typeof value === "string" ? value : JSON.stringify(value, null, 2));
-};
-if (out.running && typeof out.running === "object") {
-  section("fleet activity", out.running.fleetActivity ?? out.running);
-  if (out.running.agentRoster !== undefined) section("agent roster", out.running.agentRoster);
-  if (out.running.leaseAttributions !== undefined) section("lease attributions", out.running.leaseAttributions);
-} else {
-  section("running", out.running);
-}
-if (out.queue !== undefined) section("dispatch queue", out.queue);
-if (out.accounts !== undefined) section("coding accounts", out.accounts);

package/skills/whats-happening/references/reading-the-board.md

@@ -1,43 +0,0 @@
-# Reading the board
-
-This reference restates invariants: what the stages are, what order they come in, and what "stuck" means. The names your team uses for each stage, and which state ids they map to, are tenant facts read live from the contract; `node scripts/snapshot.mjs --board` prints the board already grouped and ordered by them.
-
-## Stages are slots, names are display
-
-Catalyst thinks in eleven **slots** in pipeline order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled. Each of your teams maps some or all of those slots onto its own Linear workflow states. The contract carries, per team and per slot, the state id (the authority), the live state name and type (display), and whether the state still exists in Linear. A team may have adopted Catalyst's recommended states, mapped its existing ones, or mixed the two; the contract's `workflowMode` says which.
-
-Five slots are load-bearing and a missing one is a distinct silent failure: **dispatch** (where a card goes to be picked up), **intake** (an optional first pass for tickets that have never entered the ladder), **pr** (where a card sits while its pull request is reviewed and merged), **done** and **canceled**. The other six are informational: a wrong mapping there costs a warning, not a stall.
-
-Read a board by slot, never by name. Two teams can call the same slot different things, and a state renamed in Linear keeps its id and its slot.
-
-## Work in progress by stage
-
-The snapshot's `board` block groups open tickets by state name in slot order, drops terminal states, and lists any state name that maps to no slot at the end. Read it top to bottom:
-
-- **dispatch** holds what is ready and waiting for a container. A long dispatch column with nothing in flight is a capacity or eligibility question, not a work question: run `explain` on the first row. If it says `wip_limit`, the project is at its WIP limit (tickets in progress, counting blocked, parked and waiting ones, not containers): the work in progress is what is waiting, so read that column, not this one.
-- **intake** through **pr** are the ladder. A card advances one slot when the matching phase completes; a failed phase writes no board state, so a card that has not moved is either still running, retrying in place, or moved sideways to remediate.
-- **remediate** is an interrupt, not a step. A card there was moved by a failure and returns to its exact previous stage when a repair round succeeds. Count remediate cards separately; they are not progress.
-- Backlog-type states are not slots. A ticket there is parked or not yet chosen; nothing is offered for it and nothing is wrong with it.
-
-## Aging
-
-Age is time since `updated_at`, or since the lease started for a ticket in flight. Report it in human units. Compare it to the phase, not to a fixed number: a research phase and a merge wait have different natural durations, and the cloud's own retry backoff (the contract's `thresholds.retryBackoffMs`) explains many short waits.
-
-## What counts as stuck
-
-A ticket is **stuck** only when all three hold:
-
-1. Nothing is offered for it: the queue lists it excluded, or `explain` gives a reason rather than a position.
-2. The reason does not release itself. Backoffs, cooldowns that name a callback, and fleet-wide holds that clear when the cloud repins are waits, not stalls. The table in `references/why-is-it-stuck.md` marks which is which.
-3. No one is acting on the release: no open ask names it, no human comment landed after the failure, no push arrived.
-
-Everything else is **waiting**, and the reply says what it is waiting on. Calling a wait "stuck" sends the human to fix something the cloud is already handling.
-
-## The signals the cloud posts on the ticket itself
-
-Before declaring anything, read the ticket's comments (`catalyst-skills query issue <id>`; the `catalyst-linear` skill explains each shape). The cloud posts a phase-outcome card on every completion and failure, a remediate-attempt card per repair round, a board-health note when it detects a stall itself, and a merge-wait note when a merge is held. Those comments are the narrative; the per-ticket ledger behind them — attempts, rounds against the cap, park state — is `catalyst-skills explain --history <ticket>`, and the two must agree.
-
-## Two things that look like work and are not
-
-- A ticket carrying the ask marker label, or whose text reads as a decision request, is a question. It is excluded from dispatch by design and belongs in the waiting-on-human block.
-- A ticket claimed by a worker outside the cloud (the local-lane label) is being worked, but not by Catalyst; report it as in flight elsewhere and do not chase the cloud for it.

package/skills/whats-happening/references/reprioritising.md

@@ -1,37 +0,0 @@
-# Reprioritising
-
-This reference restates invariants: how Catalyst orders work and which levers a person actually has. The live queue is `catalyst-skills queue [--team K]` (inside `node scripts/snapshot.mjs`); the thresholds behind backoffs and parks are the contract's `thresholds` block, printed in the snapshot's `tenant` section.
-
-## How the cloud orders work
-
-Each team's queue is derived by the cloud itself from the team's own tickets, so there is nothing a session publishes and nothing that goes stale between sessions. The order is:
-
-1. **Priority** ascending, as set on the Linear ticket (urgent first).
-2. **Created time** ascending: older tickets first among equals.
-3. **Identifier** ascending, as the final tiebreak.
-
-Tickets that are already **mid-ladder** join the same candidate set and sort ahead by how many phases they have completed, so a ticket that is nearly done finishes before a fresh one starts. That is an ordering rule only; it never makes an ineligible ticket eligible.
-
-Within the order, dispatch is bounded per repository (a concurrency cap of 20 running phases by default that an operator raises or lowers — the tenant's own settings page displays it and does not change it — and a paused repository resolves to zero without losing the stored value) and split across teams so one team cannot starve another. Comment-wake work, where the cloud answers a human comment on a ticket, shares the same cap as relay work.
-
-The queue is recomputed on every ingest that touches the team and on each alarm pass, so a change you make shows up within seconds, not on a schedule.
-
-## The three levers a person has
-
-**1. Priority on the ticket.** Change the Linear priority and the queue reorders itself. This is the lever for "do this one first". It does not jump a running phase; it changes what is picked up next.
-
-**2. The dispatch column.** A card is offered only when it sits in the team's dispatch slot (and, for a ticket that has never entered the ladder, the intake slot when intake is enabled). Moving a card into that slot is how work is started; moving it out to a backlog-type state is how work is stopped without cancelling it. The `run-this-project` skill has the script; through this skill you describe the move and let the person or the project owner make it.
-
-**3. Holds.** A PR label from the contract's `merge.prLabels` set keeps an otherwise-mergeable pull request out of the merge queue until a person removes it. A blocking relation from an ask holds every ticket the ask names. Applying the release label the contract names frees a ticket the ask-shape detector flagged by mistake.
-
-Everything else that looks like a lever is not one from a key: unparking a phase, clearing a repair hold, resetting a validate budget and re-pinning a base are operator actions today, and the reply says so and names the settings page rather than promising them.
-
-## What not to promise
-
-- **A running phase is not interrupted** by any of the three levers. It finishes or fails on its own; then the new order applies.
-- **A failed phase does not need re-queueing.** A pre-branch failure or an infrastructure failure retries in place after a backoff; a later failure moves the card to the remediate slot and queues a repair round, capped by the contract's `thresholds.remediateRoundCap`; repeated failures park it after `thresholds.parkAfterConsecutiveFailures`. Moving the card by hand during that sequence usually restarts the count rather than shortening it.
-- **Priority is not urgency to the human.** An urgent ticket that is blocked on an ask still waits for the ask. The what-needs-me ranking (by what an answer releases) is the right list for the human; the queue is the right list for the fleet.
-
-## Answering "why is that one not next?"
-
-Run `explain` on it. If the answer is a position, it is next in order and the cloud is bounded by capacity: say how many are ahead and whether any run at all (if nothing runs anywhere, the likely cause is coding-account capacity, which a key cannot read yet, so name the settings page). If the answer is a reason, use `references/why-is-it-stuck.md`. If the answer is that the ticket is not in the explainer, it is on another team, terminal, or unknown to the mirror: check the identifier before anything else.