@catalyst-cloud/cli 0.9.5 → 0.13.1

package/dist/env/scan-wrangler.js

@@ -0,0 +1,120 @@
+const BINDING_KEY_BY_TABLE = {
+    kv_namespaces: "binding",
+    d1_databases: "binding",
+    r2_buckets: "binding",
+    "durable_objects.bindings": "name",
+    "queues.producers": "binding",
+    "queues.consumers": "binding",
+};
+// ⛔ TABLE_RE AND QUOTED_RE ARE END-ANCHORED, SO AN INLINE `#` COMMENT MUST BE STRIPPED FIRST
+// (validate attempt 29, CR-1 / CR-4). `[vars] # public settings` never matched TABLE_RE, so
+// `currentTable` stayed null and the scanner returned NOTHING for the whole file — zero bindings,
+// zero vars, zero notes: a silent, total failure in a tool whose entire value is completeness. And
+// `binding = "SESSIONS" # the session store` never matched QUOTED_RE, so the `: value` fallback
+// below made the raw remainder — quotes, comment and all — the binding NAME the customer is asked to
+// keep, drop or move. `stripInlineComment` is quote-aware, so a `#` inside a value (`id = "ab#cd"`)
+// is still value material and is left alone.
+const QUOTED_RE = /^"(.*)"$|^'(.*)'$/;
+const KEY_VALUE_RE = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.*)$/;
+const TABLE_RE = /^\[\[?([^\]]+)\]\]?$/;
+const ENV_TABLE_RE = /^env\.([^.]+)\.(.+)$/;
+export function scanWrangler(file, text) {
+    const sightings = [];
+    const lines = text.split("\n");
+    let currentTable = null;
+    let currentEnvironment;
+    // Tracks an open triple-quoted string, so a line INSIDE one (e.g. `a = not_a_name`) is never
+    // mined for a key — the key that opened the string (e.g. `MULTI = """`) already was.
+    let insideMultiline = null;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (insideMultiline) {
+            if (trimmed.includes(insideMultiline))
+                insideMultiline = null;
+            continue;
+        }
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const uncommented = stripInlineComment(trimmed).trim();
+        if (uncommented === "")
+            continue;
+        const tableMatch = TABLE_RE.exec(uncommented);
+        if (tableMatch) {
+            let name = tableMatch[1].trim();
+            currentEnvironment = undefined;
+            const envMatch = ENV_TABLE_RE.exec(name);
+            if (envMatch) {
+                currentEnvironment = envMatch[1];
+                name = envMatch[2];
+            }
+            currentTable = name;
+            continue;
+        }
+        if (currentTable === null)
+            continue;
+        const kv = KEY_VALUE_RE.exec(uncommented);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        const value = kv[2].trim();
+        if (isOpeningMultiline(value, '"""'))
+            insideMultiline = '"""';
+        else if (isOpeningMultiline(value, "'''"))
+            insideMultiline = "'''";
+        if (currentTable === "vars" || currentTable.endsWith(".vars")) {
+            sightings.push({
+                name: key,
+                finding: { file, line: i + 1, consumer: "wrangler.toml vars", consumerKind: "vars" },
+                isWranglerVar: true,
+                wranglerEnvironment: currentEnvironment,
+                localSource: "value committed in wrangler.toml — nothing to declare",
+            });
+            continue;
+        }
+        const bindingKey = BINDING_KEY_BY_TABLE[currentTable];
+        if (bindingKey && key === bindingKey) {
+            const qm = QUOTED_RE.exec(value);
+            const bindingName = qm ? (qm[1] ?? qm[2] ?? "") : value;
+            if (bindingName) {
+                sightings.push({
+                    name: bindingName,
+                    finding: { file, line: i + 1, consumer: `${currentTable} binding`, consumerKind: currentTable },
+                    isBinding: true,
+                    wranglerEnvironment: currentEnvironment,
+                    localSource: "Cloudflare binding",
+                });
+            }
+        }
+    }
+    return sightings;
+}
+/**
+ * The line with any TOML inline comment removed. A `#` only starts a comment outside a string, so
+ * the scan tracks the quote it is inside. A line whose quotes do not balance — a `"""` opener, most
+ * importantly — is returned untouched rather than guessed at.
+ */
+function stripInlineComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote !== null) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "#")
+            return line.slice(0, i);
+    }
+    return line;
+}
+function isOpeningMultiline(value, marker) {
+    if (!value.startsWith(marker))
+        return false;
+    return !(value.length > marker.length && value.endsWith(marker));
+}

package/dist/env/types.js

@@ -0,0 +1 @@
+export {};

package/dist/env/walk.js

@@ -0,0 +1,87 @@
+// walk.ts — the one definition of "the files this repository is made of", shared by every scanner
+// that needs to enumerate a tree. Skips the directories no scan should ever descend into.
+//
+// ⛔ A SYMLINK IS REPOSITORY CONTENT, AND REPOSITORY CONTENT IS UNTRUSTED (validate attempt 29,
+// M-2 / CR-5). `statSync` FOLLOWS a link, so the previous walk had no way to tell a real directory
+// from a link out of the tree, and no visited set to stop a cycle. Measured: a single `pkg/up -> ..`
+// link reported one name 41 times with absurd file:line pairs, and a committed `elsewhere -> /tmp/x`
+// walked a directory outside the repository entirely. So every entry is classified with a DIRENT
+// (never a followed stat), and a link is followed only when its real path is inside the repository
+// root and has not been walked before.
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+export const SKIP_DIRS = new Set(["node_modules", "dist", "coverage", ".git"]);
+/** Every file under `root`, relative paths, POSIX-separated, skipping SKIP_DIRS. */
+export function walkRepo(root) {
+    const out = [];
+    let realRoot;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        return out;
+    }
+    // Real paths already descended into. Seeded with the root so a link back to it is a cycle.
+    const walked = new Set([realRoot]);
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = entry.name;
+            const full = join(dir, name);
+            let isDirectory = entry.isDirectory();
+            if (entry.isSymbolicLink()) {
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (!contains(realRoot, real))
+                    continue; // points out of the repository
+                try {
+                    isDirectory = statSync(full).isDirectory();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                if (SKIP_DIRS.has(name))
+                    continue;
+                // Every directory is keyed by its REAL path, link or not: `pkg/up -> pkg` is a cycle only
+                // because the link and the directory resolve to the same place, and checking the link alone
+                // would still walk the tree one extra time under its second name.
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (walked.has(real))
+                    continue; // a cycle, or a second route to the same tree
+                walked.add(real);
+                stack.push(full);
+            }
+            else {
+                out.push(relative(root, full).split("\\").join("/"));
+            }
+        }
+    }
+    return out.sort();
+}
+/** True when `child` is `root` itself or lies beneath it. Both must already be real paths. */
+export function contains(root, child) {
+    const a = resolve(root);
+    const b = resolve(child);
+    return b === a || b.startsWith(a.endsWith(sep) ? a : a + sep);
+}

package/dist/env.js

@@ -0,0 +1,76 @@
+// env.ts — `catalyst env inventory` / `env check`: a LOCAL, OFFLINE, repo-scoped reporter and
+// validator. Unlike every other verb in this file's siblings, `cmdEnv` never calls `requireConfig` or
+// `apiClient` — it needs neither a login nor a network call, which is the whole point of the feature:
+// a person reviews what a repository declares without connecting anything first.
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { positionals } from "./args.js";
+import { validateDeclaration } from "./env/declaration-rules.js";
+import { inventoryRepo } from "./env/inventory.js";
+import { inventoryToJson, renderCheck, renderInventory } from "./env/render.js";
+import { UsageError } from "./errors.js";
+export async function cmdEnv(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (sub === undefined)
+        throw new UsageError("env needs a subcommand: inventory | check");
+    if (sub === "inventory") {
+        if (rest.length > 1)
+            throw new UsageError(`env inventory takes at most one path (got an extra "${rest[1]}")`);
+        const root = resolve(rest[0] ?? ".");
+        // C-3: walkRepo swallows a readdir failure and returns [], so without this an unreadable or
+        // mistyped path printed three empty groups and exited 0 — a typo that reads as "declares nothing".
+        let stat;
+        try {
+            stat = statSync(root);
+        }
+        catch {
+            ctx.stderr(`${root} does not exist — env inventory takes a path to a repository`);
+            return 1;
+        }
+        if (!stat.isDirectory()) {
+            ctx.stderr(`${root} is not a directory — env inventory takes a path to a repository`);
+            return 1;
+        }
+        const inv = inventoryRepo(root, deps);
+        if (args.json)
+            ctx.stdout(JSON.stringify(inventoryToJson(inv)));
+        else
+            for (const line of renderInventory(inv))
+                ctx.stdout(line);
+        return 0;
+    }
+    if (sub === "check") {
+        const file = rest[0];
+        if (!file)
+            throw new UsageError("env check needs a file: catalyst env check <path to catalyst.env.json>");
+        if (rest.length > 1)
+            throw new UsageError(`env check takes exactly one file (got an extra "${rest[1]}")`);
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch (err) {
+            ctx.stderr(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
+        let doc;
+        try {
+            doc = JSON.parse(text);
+        }
+        catch {
+            // C-4/S-2: JSON.parse's own message embeds the first ten characters of the input, so
+            // forwarding it prints content from the file — on a verb documented as never printing a value.
+            ctx.stderr(`${file} is not valid JSON`);
+            return 1;
+        }
+        const errors = validateDeclaration(doc);
+        const state = errors.length === 0 ? "valid" : "invalid";
+        if (args.json)
+            ctx.stdout(JSON.stringify({ state, errors }));
+        else
+            for (const line of renderCheck({ state, errors }, file))
+                ctx.stdout(line);
+        return state === "valid" ? 0 : 1;
+    }
+    throw new UsageError(`unknown env subcommand "${sub}": inventory | check`);
+}

package/dist/environment.js

@@ -1,4 +1,4 @@
-// environment.ts — `catalyst-skills environment`: the tenant-scope environment declaration, through
+// environment.ts — `catalyst environment`: the tenant-scope environment declaration, through
 // the contract's account-environment routes. This is the ONE setup write a person's own key can
 // perform: the cloud has admitted it since the routes shipped, and until this verb existed nothing
 // could call it, so every setup action was a settings page.

package/dist/legacy.js

@@ -0,0 +1,224 @@
+// legacy.ts — `catalyst legacy`: leftovers of the old LOCAL Catalyst runtime (the archived repository
+// whose plugin, daemons, scheduled jobs and state folders a machine may still carry), found from a
+// FIXED list and removed only on a yes, through the tools that own each piece. The cloud runtime
+// replaced all of it; what is left can start old jobs or shadow current commands, so removal is
+// recommended, and never automatic: a run with no terminal and no --yes only reports.
+//
+// The list is fixed on purpose. A prefix match would one day catch a current job (the housekeeping
+// job, the sandbox credit guard, jobs a person made); this matches names the old runtime installed,
+// read at the source commit below, and nothing else. Data folders are a separate yes (--data).
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+import { promptSecret, stdinIsTty } from "./prompt.js";
+/** The archived repository's commit the list below was read at. */
+export const LEGACY_SOURCE_COMMIT = "73bc0645252ce8be38f8c87be6b67b950b3f0b56";
+/** The old runtime's marketplace source, as Claude Code records it in known_marketplaces.json. */
+export const OLD_MARKETPLACE_REPO = "coalesce-labs/catalyst";
+/** launchd labels the old runtime installed under ~/Library/LaunchAgents (macOS). `com.catalyst.role.<name>`
+ *  is the old role supervisor's per-role instance, matched by that exact prefix. Never `dev.catalystcloud.*`
+ *  (the current housekeeping job and runner jobs) and never `dev.catalyst.*` (the sandbox credit guard). */
+export const OLD_LAUNCHD_LABELS = [
+    "com.catalyst.agent",
+    "com.catalyst.reaper-watch",
+    "com.catalyst.quiet-fleet",
+    "com.catalyst.dead-man",
+    "com.catalyst.holding-sentinel",
+    "com.catalyst.orch-monitor",
+    "com.catalyst.role",
+    "ai.coalesce.catalyst-stack",
+    "ai.coalesce.catalyst-thoughts-sync",
+    "ai.coalesce.catalyst-orphan-sweep",
+    "ai.coalesce.catalyst-log-shipper",
+    "ai.coalesce.catalyst-cloud-sync",
+    "ai.coalesce.catalyst-usage-page",
+    "ai.coalesce.catalyst-claude-update",
+    "ai.coalesce.catalyst-updater",
+    "ai.coalesce.catalyst-replica-sync",
+    "ai.coalesce.catalyst-channel-watcher",
+    "ai.coalesce.catalyst-event-mirror",
+    "ai.coalesce.catalyst-monitor",
+];
+const OLD_ROLE_PREFIX = "com.catalyst.role.";
+/** systemd user units (~/.config/systemd/user) the old runtime's workstation pieces used on Linux. System
+ *  units under /etc/systemd/system are a host's, current, and never looked at. */
+export const OLD_USER_UNITS = ["catalyst.service", "catalyst-monitor.service"];
+/** Command files the old runtime put on the person's PATH. `~/.local/bin/catalyst` is NOT one: that
+ *  name belongs to the current CLI wherever npm put it. */
+export const OLD_BINS = [".catalyst/bin", ".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
+/** State the old runtime kept. `~/.config/catalyst-cloud` is the current CLI's and never touched. */
+export const OLD_DATA_DIRS = [".catalyst", ".config/catalyst", ".local/state/catalyst", ".local/state/catalyst-fleet-runner", ".local/state/catalyst-ledger"];
+const RECOMMEND = "Remove them: the cloud runtime replaced them, and left in place they can start old jobs or shadow current commands.";
+function readJson(path) {
+    try {
+        const v = JSON.parse(readFileSync(path, "utf8"));
+        return v !== null && typeof v === "object" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Marketplaces whose recorded source is the old repository, and the plugins installed from them. */
+function findPlugins(home) {
+    const dir = join(home, ".claude", "plugins");
+    const marketplaces = readJson(join(dir, "known_marketplaces.json")) ?? {};
+    const old = Object.entries(marketplaces)
+        .filter(([, v]) => {
+        const src = v?.source;
+        return typeof src?.repo === "string" && src.repo.toLowerCase() === OLD_MARKETPLACE_REPO;
+    })
+        .map(([name]) => name);
+    if (old.length === 0)
+        return [];
+    const installed = (readJson(join(dir, "installed_plugins.json")) ?? {}).plugins ?? {};
+    const items = [];
+    for (const key of Object.keys(installed)) {
+        const at = key.lastIndexOf("@");
+        if (at > 0 && old.includes(key.slice(at + 1)))
+            items.push({ kind: "plugin", name: key, path: join(dir, "installed_plugins.json") });
+    }
+    for (const name of old)
+        items.push({ kind: "marketplace", name, path: join(dir, "known_marketplaces.json") });
+    return items;
+}
+function findJobs(home, platform) {
+    if (platform === "darwin") {
+        const dir = join(home, "Library", "LaunchAgents");
+        let files = [];
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        return files
+            .filter((f) => f.endsWith(".plist"))
+            .map((f) => f.slice(0, -".plist".length))
+            .filter((label) => OLD_LAUNCHD_LABELS.includes(label) || label.startsWith(OLD_ROLE_PREFIX))
+            .sort()
+            .map((label) => ({ kind: "job", name: label, path: join(dir, `${label}.plist`) }));
+    }
+    if (platform === "linux") {
+        const dir = join(home, ".config", "systemd", "user");
+        return OLD_USER_UNITS.filter((u) => existsSync(join(dir, u))).map((u) => ({ kind: "job", name: u, path: join(dir, u) }));
+    }
+    return [];
+}
+const tilde = (rel) => `~/${rel}`;
+function findFiles(home) {
+    const bins = OLD_BINS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "bin", name: tilde(rel), path: join(home, rel) }));
+    const data = OLD_DATA_DIRS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "data", name: tilde(rel), path: join(home, rel), data: true }));
+    return [...bins, ...data];
+}
+/** Every old piece on this machine, in removal order: plugins, their marketplace, jobs, bins, data. Never writes. */
+export function findLegacy(home, platform) {
+    return [...findPlugins(home), ...findJobs(home, platform), ...findFiles(home)];
+}
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 60_000 });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
+};
+/** Remove one item through the tool that owns it. Returns null on success, else the reason it is still there. */
+function remove(item, run, platform, uid) {
+    const tool = (cmd, args, what) => {
+        const r = run(cmd, args);
+        return r.status === 0 ? null : `${what} failed: ${(r.stderr || r.stdout).trim().split("\n")[0] || `exit ${r.status}`}`;
+    };
+    try {
+        if (item.kind === "plugin")
+            return tool("claude", ["plugin", "uninstall", item.name], "claude plugin uninstall");
+        if (item.kind === "marketplace")
+            return tool("claude", ["plugin", "marketplace", "remove", item.name], "claude plugin marketplace remove");
+        if (item.kind === "job") {
+            const why = platform === "darwin" ? tool("launchctl", ["bootout", `gui/${uid}/${item.name}`], "launchctl bootout") : tool("systemctl", ["--user", "disable", "--now", item.name], "systemctl --user disable --now");
+            if (why !== null)
+                return why;
+            unlinkSync(item.path);
+            return null;
+        }
+        // a bin or a data folder: a file goes with unlink, a directory (~/.catalyst/bin, the data) with rm -rf
+        if (lstatSync(item.path).isDirectory())
+            rmSync(item.path, { recursive: true, force: true });
+        else
+            unlinkSync(item.path);
+        return null;
+    }
+    catch (err) {
+        return `could not remove: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+export async function cmdLegacy(args, ctx, deps = {}) {
+    if (positionals(args).length > 0)
+        throw new UsageError("legacy takes no positional argument; flags are --remove, --data, --yes, --json");
+    const wantRemove = flagBool(args, "remove");
+    const withData = flagBool(args, "data");
+    if (withData && !wantRemove)
+        throw new UsageError("--data belongs with --remove");
+    const platform = deps.platform ?? process.platform;
+    const uid = deps.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+    const run = deps.run ?? defaultRun;
+    const found = findLegacy(ctx.home, platform);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (found.length === 0) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found: [], removed: [], remaining: [] }, ["no leftovers of the old local Catalyst runtime on this machine"]);
+        return 0;
+    }
+    const listLines = [
+        `Leftovers of the old local Catalyst runtime on this machine (${found.length}):`,
+        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept unless --data)" : ""}`),
+    ];
+    if (!wantRemove) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (add --data to delete its data folders too)"]);
+        return 1;
+    }
+    // the one question, only on a terminal; --yes answers it without asking
+    let go = flagBool(args, "yes");
+    if (!go) {
+        const tty = (deps.isTty ?? stdinIsTty)();
+        if (!tty) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: false }, [...listLines, RECOMMEND, "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (add --data for the data folders)"]);
+            return 1;
+        }
+        for (const l of listLines)
+            ctx.stdout(l);
+        ctx.stdout(RECOMMEND);
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}${withData ? ", data folders included" : ", keeping the data folders"}? [y/N] `)).trim().toLowerCase();
+        go = answer === "y" || answer === "yes";
+        if (!go) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: true }, ["nothing removed; run catalyst legacy --remove again when ready"]);
+            return 1;
+        }
+    }
+    const removed = [];
+    const failed = [];
+    const kept = [];
+    const lines = [];
+    for (const item of found) {
+        if (item.data && !withData) {
+            kept.push(item);
+            lines.push(`kept: ${item.kind} ${item.name} (run with --data to delete it)`);
+            continue;
+        }
+        const why = remove(item, run, platform, uid);
+        if (why === null) {
+            removed.push(item);
+            lines.push(`removed: ${item.kind} ${item.name}`);
+        }
+        else {
+            failed.push({ item, why });
+            lines.push(`still present: ${item.kind} ${item.name} (${why})`);
+        }
+    }
+    // re-check from the same list, so the report says what the machine holds now, not what was attempted
+    const remaining = findLegacy(ctx.home, platform).filter((f) => !(f.data && !withData));
+    const keptNote = kept.length > 0 ? " except the data folders you kept" : "";
+    lines.push(remaining.length === 0 ? `re-checked: nothing of the old runtime remains${keptNote}` : `re-checked: ${remaining.length} item${remaining.length === 1 ? "" : "s"} of the old runtime remain${remaining.length === 1 ? "s" : ""}${keptNote}: ${remaining.map((r) => `${r.kind} ${r.name}`).join(", ")}`);
+    emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed, remaining: [...remaining, ...kept], kept, failed }, lines);
+    return remaining.length === 0 ? 0 : 1;
+}

package/dist/project.js

@@ -0,0 +1,129 @@
+// project.ts — `catalyst project wip-limit get|set`: a project's new-start WIP limit, on the
+// person's own login. Any active member reads it; a workspace owner or admin sets it. The limit is
+// per Catalyst project (one Linear team across all its repositories): the project's stored value,
+// else the workspace value, else the default the cloud reports. It holds only NEW starts, so the
+// reply carries the work in progress beside the limit: that count, not a runner count, is what a
+// person compares. The route is the cloud's own member route; the reply shape is the cloud's, so a
+// field this CLI does not know is passed through under --json untouched.
+import { flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+/** The limit's bounds, as the cloud clamps them. A value outside is refused here, before any request. */
+export const WIP_LIMIT_MIN = 0;
+export const WIP_LIMIT_MAX = 9999;
+/** The agent twin of the member route: a bearer reads it with `?team=<key or id>` and writes it with a
+ *  body naming the team, the way the team-workflow verbs do. The contract's route table lists these
+ *  two strings, so `capabilities` can judge them. */
+export const WIP_LIMIT_ROUTE = "/api/v1/agent/team-wip-limit";
+export const wipLimitPath = (team) => `${WIP_LIMIT_ROUTE}?team=${encodeURIComponent(team)}`;
+const SOURCE_TEXT = { project: "set for this project", flag: "workspace value", default: "default" };
+const sourceText = (source) => SOURCE_TEXT[String(source)] ?? String(source ?? "unknown");
+/** The project `--team` names, or the only mapped project when the flag is absent. Never a guess between two. */
+export function resolveTeam(doc, wanted) {
+    const teams = Array.isArray(doc.teams) ? doc.teams : [];
+    if (wanted !== undefined) {
+        const lower = wanted.toLocaleLowerCase();
+        const found = teams.find((t) => (t.key ?? "").toLocaleLowerCase() === lower || t.id === wanted);
+        if (!found)
+            throw new UsageError(`no mapped project has the team key ${wanted}${teams.length ? ` (mapped: ${teams.map((t) => t.key ?? t.id).join(", ")})` : " (no project is mapped yet)"}`);
+        return found;
+    }
+    if (teams.length === 1)
+        return teams[0];
+    if (teams.length === 0)
+        throw new UsageError("no project is mapped yet; map one first (catalyst team map <KEY>)");
+    throw new UsageError(`--team is needed: ${teams.length} projects are mapped (${teams.map((t) => t.key ?? t.id).join(", ")})`);
+}
+/** `set`'s value: an integer inside the cloud's bounds, or the word default. Parsed before any request. */
+export function parseLimit(raw) {
+    if (raw === undefined)
+        throw new UsageError("project wip-limit set needs a value: an integer, or default");
+    if (raw === "default")
+        return null;
+    if (!/^-?\d+$/.test(raw))
+        throw new UsageError(`the limit must be an integer from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX}, or default (got ${raw})`);
+    const n = Number(raw);
+    if (n < WIP_LIMIT_MIN || n > WIP_LIMIT_MAX)
+        throw new UsageError(`the limit must be from ${WIP_LIMIT_MIN} to ${WIP_LIMIT_MAX} (got ${raw}); 0 holds every new start`);
+    return n;
+}
+/** The in-progress tickets as identifiers, tolerant of the cloud sending strings or objects; [] when absent. */
+export function ticketIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((t) => (typeof t === "string" ? t : t && typeof t === "object" ? String(t.identifier ?? t.id ?? "") : ""))
+        .filter((t) => t !== "");
+}
+/** One line naming what holds the WIP, capped so a big team does not scroll; null when the cloud sent none. */
+function inProgressLine(view) {
+    const ids = ticketIds(view.inProgressTickets);
+    if (ids.length === 0)
+        return null;
+    const shown = ids.slice(0, 12);
+    return `in progress: ${shown.join(", ")}${ids.length > shown.length ? ` and ${ids.length - shown.length} more` : ""} — these are what a new ticket waits on; unstick them, not the queue`;
+}
+function line(key, view) {
+    const limit = view.limit;
+    const inProgress = view.inProgress;
+    const at = typeof limit === "number" && typeof inProgress === "number" && inProgress >= limit ? " — at the limit: a new ticket waits until one in progress finishes" : "";
+    return `${key}: ${typeof inProgress === "number" ? inProgress : "?"} in progress, limit ${typeof limit === "number" ? limit : "?"} (${sourceText(view.source)})${at}`;
+}
+export async function cmdProject(args, ctx) {
+    const [sub, action, value, ...extra] = positionals(args);
+    if (sub !== "wip-limit")
+        throw new UsageError("project needs wip-limit <get|set <n>|default>");
+    if (action !== "get" && action !== "set")
+        throw new UsageError("project wip-limit needs get, or set <n>|default");
+    if (action === "get" && value !== undefined)
+        throw new UsageError("project wip-limit get takes no value; set does");
+    if (extra.length > 0)
+        throw new UsageError("project wip-limit takes one value at most");
+    const limit = action === "set" ? parseLimit(value) : null;
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const team = resolveTeam(doc, flagString(args, "team"));
+    const key = team.key ?? team.id;
+    const client = apiClient(cfg, ctx);
+    const accept = [400, 403, 404];
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    const refuse = (status, reply) => {
+        // The cloud's error bodies carry `error` (the code to match on) and a human `message`.
+        const body = reply ?? {};
+        const detail = body.message || body.reason ? ` (${String(body.message ?? body.reason)})` : "";
+        const why = status === 403
+            ? `setting the limit needs a workspace owner or admin; any member can read it with catalyst project wip-limit get${detail}`
+            : status === 404 && body.error === "team-unknown"
+                ? `this cloud does not know a team ${key}; check the key with catalyst team list${detail}`
+                : status === 404
+                    ? "this Catalyst Cloud does not serve the wip-limit route yet (needs a newer cloud)"
+                    : `${String(body.error ?? body.code ?? "bad request")}${detail}`;
+        emit({ status, team: { id: team.id, key }, ...body }, [`refused (${status}): ${why}`]);
+        return 1;
+    };
+    const before = await client.getJson(wipLimitPath(team.id), { accept, parseAccepted: true });
+    if (before.status !== 200)
+        return refuse(before.status, before.body);
+    if (action === "get") {
+        emit({ team: { id: team.id, key }, ...before.body }, [
+            line(key, before.body),
+            ...(inProgressLine(before.body) === null ? [] : [inProgressLine(before.body)]),
+            `change it: catalyst project wip-limit set <n> --team ${key} (owner or admin; set default returns to the workspace value)`,
+        ]);
+        return 0;
+    }
+    const after = await client.postJson(WIP_LIMIT_ROUTE, { team: team.id, limit }, { accept });
+    if (after.status !== 200)
+        return refuse(after.status, after.body);
+    emit({ team: { id: team.id, key }, ...after.body, previous: { limit: before.body.limit, source: before.body.source } }, [
+        `${key}: limit ${String(before.body.limit)} (${sourceText(before.body.source)}) → ${String(after.body.limit)} (${sourceText(after.body.source)})${after.body.limit === 0 ? "; 0 holds every new start" : ""}`,
+        line(key, after.body),
+    ]);
+    return 0;
+}

package/dist/release.js

@@ -1,4 +1,4 @@
-// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
+// release.ts — `catalyst 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