@catalyst-cloud/cli 0.8.0

package/dist/args.js

@@ -0,0 +1,280 @@
+// args.ts — argument parsing for every verb. Positional 0 is the command, positional 1 the
+// subcommand, the rest are positionals; flags are per-verb tables so an unknown flag is a usage
+// error naming the verb, and every verb's --help is generated from its own table.
+import { UsageError } from "./errors.js";
+const GLOBAL_FLAGS = {
+    key: { value: true, help: "your personal key (or CATALYST_CLOUD_TOKEN)" },
+    "base-url": { value: true, help: "Catalyst Cloud origin (or CATALYST_CLOUD_BASE_URL)" },
+    "skills-dir": { value: true, help: "where the skills are copied (default ~/.claude/skills)" },
+    force: { value: false, help: "replace a skill directory this package did not install" },
+    json: { value: false, help: "machine-readable output" },
+};
+/** Per-verb flag tables. A verb absent here accepts only the global flags. */
+export const FLAG_TABLES = {
+    login: {
+        "start-replica": { value: false, help: "run `replica start --detach` after connecting" },
+    },
+    install: {},
+    status: {},
+    notice: {},
+    me: {},
+    contract: {
+        refresh: { value: false, help: "ignore the cache age and revalidate now" },
+        path: { value: true, help: "print a sub-document, e.g. teams.0.stages" },
+    },
+    query: {
+        team: { value: true, help: "team key filter" },
+        project: { value: true, help: "project id filter" },
+        state: { value: true, help: "state name filter" },
+        limit: { value: true, help: "max rows (default 50); one page only unless --all" },
+        since: { value: true, help: "changes: the cursor to read after" },
+        source: { value: true, help: "replica | api (default: replica when fresh, else api)" },
+        ticket: { value: true, help: "pulls: only PRs linked to this ticket" },
+        all: { value: false, help: "issues/pulls: follow the cloud's page cursor to the end of the scope" },
+    },
+    replica: {
+        detach: { value: false, help: "start: run the writer in the background and write a pidfile" },
+        db: { value: true, help: "replica file path (default from customer.json)" },
+        probe: { value: false, help: "status: also fetch the cloud head and print the lag" },
+        "stale-ms": { value: true, help: "status: heartbeat age that counts as stale (default 15000)" },
+    },
+    events: {
+        type: { value: true, help: "exact event type" },
+        ticket: { value: true, help: "ticket identifier found in the event payload" },
+        after: { value: true, help: "event sequence to read after (tail/wait default to local head)" },
+        limit: { value: true, help: "query: maximum matching events (default 50)" },
+        timeout: { value: true, help: "wait-for: bounded wait in seconds (default 300)" },
+        directory: { value: true, help: "event cache directory (default: SDK XDG path)" },
+    },
+    explain: {
+        history: { value: false, help: "per-ticket execution history instead of the eligibility reason" },
+    },
+    history: {},
+    running: {
+        ticket: { value: true, help: "with --phase: also the lease attributions for this (ticket, phase)" },
+        phase: { value: true, help: "with --ticket: the phase whose lease attributions to read" },
+    },
+    queue: {
+        team: { value: true, help: "team key (default: every team the tenant contract names)" },
+    },
+    watch: {
+        team: { value: true, help: "scope: a team key" },
+        ticket: { value: true, repeat: true, help: "scope: a ticket identifier (repeatable)" },
+        project: { value: true, help: "scope: a project id" },
+        exec: { value: true, help: "run this shell command per frame with the frame on stdin" },
+        "cursor-file": { value: true, help: "cursor file path (default ~/.config/catalyst-cloud/watch-cursor.json)" },
+        from: { value: true, help: "cursor | head (default cursor)" },
+    },
+    write: {
+        body: { value: true, help: "comment: the body text" },
+        stdin: { value: false, help: "comment: read the body from stdin" },
+        parent: { value: true, help: "comment: reply under this comment id" },
+        bookkeeping: { value: false, help: "comment: prefix the contract's bookkeeping marker" },
+        "as-user": { value: false, help: "post with the personal identity instead of the app actor" },
+        slot: { value: true, help: "state: the workflow slot to move to" },
+        "state-id": { value: true, help: "state: an explicit Linear state id" },
+        "state-type": { value: true, help: "state: the first state of this type on the ticket's team (e.g. backlog)" },
+        add: { value: true, repeat: true, help: "label: label name or id to add (repeatable)" },
+        remove: { value: true, repeat: true, help: "label: label name or id to remove (repeatable)" },
+        team: { value: true, help: "create: team key" },
+        title: { value: true, help: "create/attachment/session: title" },
+        label: { value: true, repeat: true, help: "create: label name or id (repeatable)" },
+        priority: { value: true, help: "create: Linear priority 0-4" },
+        comment: { value: true, help: "reaction: react to this comment id instead of the ticket" },
+        emoji: { value: true, help: "reaction: the emoji" },
+        url: { value: true, help: "attachment/session: the URL" },
+        "plan-file": { value: true, help: "session: a JSON file holding the plan" },
+        activity: { value: true, help: "session: one activity line" },
+    },
+    ask: {
+        team: { value: true, help: "raise: team key" },
+        title: { value: true, help: "raise: the question" },
+        context: { value: true, help: "raise: context paragraph" },
+        option: { value: true, repeat: true, help: "raise: an option (repeatable)" },
+        default: { value: true, help: "raise: the default if silent" },
+        blocks: { value: true, repeat: true, help: "raise: a ticket this decision blocks (repeatable)" },
+        "nothing-to-block": { value: false, help: "raise: declare that nothing is blocked" },
+        anyone: { value: false, help: "list: every open ask in the tenant, not only the ones assigned to you" },
+        "ask-key": { value: true, help: "raise: idempotency key" },
+        answer: { value: true, help: "accept: the answering comment id" },
+        role: { value: true, help: "accept: the role recording the answer" },
+    },
+    ready: {
+        offline: { value: false, help: "skip the published-release check (no network)" },
+    },
+    accounts: {},
+    environment: {
+        file: { value: true, help: "propose: a JSON file holding the declaration" },
+        stdin: { value: false, help: "propose: read the declaration from stdin" },
+        "expect-revision": { value: true, help: "propose: refuse unless the stored declaration is still at this revision" },
+        approve: { value: false, help: "propose: approve exactly the revision the propose returned" },
+        revision: { value: true, help: "approve: the revision to approve (with --hash; default is whatever read returns)" },
+        hash: { value: true, help: "approve: the canonical hash to approve (with --revision)" },
+    },
+    secret: {
+        repo: { value: true, help: "the repository, as owner/name (required)" },
+        command: { value: true, help: "set: run this command on this machine and store its output (e.g. 'op read op://Vault/item/field'); the command text is audited, so never put a value in it" },
+        rotate: { value: true, repeat: true, help: "import: replace this name if it is already set (repeatable)" },
+    },
+    release: {
+        because: { value: true, help: "what changed since the ticket was held (required unless --dry-run)" },
+        "retry-unchanged": { value: false, help: "release even though nothing the mirror can see changed (say what did in --because)" },
+        "dry-run": { value: false, help: "show what a release would clear and refuse, and change nothing" },
+        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)" },
+    },
+};
+export const VERB_USAGE = {
+    login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
+    install: "install [--skills-dir <dir>] [--force]",
+    status: "status",
+    notice: "notice",
+    me: "me [--json]",
+    contract: "contract [--refresh] [--path <a.b.c>] [--json]",
+    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--all] [--source replica|api] [--json]",
+    replica: "replica <start [--detach]|stop|status [--probe] [--json]|sql \"<select>\"|schema [table]> [--db <path>]",
+    runtime: "runtime <status [--json]|install|path|uninstall>",
+    events: "events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
+    explain: "explain <ticket> [--history] [--json]",
+    history: "history <ticket> [--json]",
+    running: "running [--ticket T --phase P] [--json]",
+    queue: "queue [--team K] [--json]",
+    watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
+    write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
+    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
+    ready: "ready [--json] [--offline]",
+    accounts: "accounts [--json]",
+    environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]",
+    secret: "secret set <NAME> --repo <owner/name> [--command '<cmd>'] [--json]   (value from --command, stdin, or a hidden prompt) | secret import <file> --repo <owner/name> [--rotate NAME]... [--json]",
+    release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",
+};
+export function parseArgs(argv) {
+    const out = {
+        command: null,
+        subcommand: null,
+        rest: [],
+        flags: {},
+        force: false,
+        help: false,
+        version: false,
+        json: false,
+    };
+    const positionals = [];
+    // The per-verb table is switched in the moment the command positional is seen, so a verb's own
+    // flags are accepted after it and a global flag is accepted anywhere.
+    let table = { ...GLOBAL_FLAGS };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help") {
+            out.help = true;
+            continue;
+        }
+        if (a === "-V" || a === "--version") {
+            out.version = true;
+            continue;
+        }
+        if (a === "--") {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith("--")) {
+            let name = a.slice(2);
+            let inlineValue;
+            const eq = name.indexOf("=");
+            if (eq !== -1) {
+                inlineValue = name.slice(eq + 1);
+                name = name.slice(0, eq);
+            }
+            const spec = table[name];
+            if (!spec) {
+                throw new UsageError(out.command ? `unknown option for ${out.command}: --${name}` : `unknown option: --${name}`);
+            }
+            if (spec.value) {
+                const v = inlineValue ?? requireValue(argv, ++i, `--${name}`);
+                if (spec.repeat) {
+                    const prev = out.flags[name];
+                    out.flags[name] = Array.isArray(prev) ? [...prev, v] : [v];
+                }
+                else {
+                    out.flags[name] = v;
+                }
+            }
+            else {
+                if (inlineValue !== undefined)
+                    throw new UsageError(`--${name} takes no value`);
+                out.flags[name] = true;
+            }
+            continue;
+        }
+        if (a.startsWith("-") && a.length > 1)
+            throw new UsageError(`unknown option: ${a}`);
+        positionals.push(a);
+        if (positionals.length === 1) {
+            out.command = a;
+            table = { ...GLOBAL_FLAGS, ...(FLAG_TABLES[a] ?? {}) };
+        }
+    }
+    out.command = positionals[0] ?? null;
+    out.subcommand = positionals[1] ?? null;
+    out.rest = positionals.slice(2);
+    if (typeof out.flags.key === "string")
+        out.key = out.flags.key;
+    if (typeof out.flags["base-url"] === "string")
+        out.baseUrl = out.flags["base-url"];
+    if (typeof out.flags["skills-dir"] === "string")
+        out.skillsDir = out.flags["skills-dir"];
+    out.force = out.flags.force === true;
+    out.json = out.flags.json === true;
+    return out;
+}
+function requireValue(argv, i, flag) {
+    const v = argv[i];
+    if (v === undefined || v === "")
+        throw new UsageError(`${flag} requires a value`);
+    return v;
+}
+/** The positional arguments after the command: `[subcommand, ...rest]` with nulls dropped. */
+export function positionals(args) {
+    return args.subcommand === null ? [] : [args.subcommand, ...args.rest];
+}
+export function flagString(args, name) {
+    const v = args.flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+export function flagList(args, name) {
+    const v = args.flags[name];
+    if (Array.isArray(v))
+        return v;
+    return typeof v === "string" ? [v] : [];
+}
+export function flagBool(args, name) {
+    return args.flags[name] === true;
+}
+export function flagInt(args, name, fallback) {
+    const v = flagString(args, name);
+    if (v === undefined)
+        return fallback;
+    const n = Number(v);
+    if (!Number.isInteger(n))
+        throw new UsageError(`--${name} must be an integer`);
+    return n;
+}
+/** The help text for one verb: usage line, then every flag in its table and the global ones. */
+export function verbHelp(verb) {
+    const lines = [`Usage: catalyst-skills ${VERB_USAGE[verb] ?? verb}`, ""];
+    const table = FLAG_TABLES[verb] ?? {};
+    const names = Object.keys(table);
+    if (names.length > 0) {
+        lines.push("Options:");
+        for (const name of names)
+            lines.push(`  --${name}${table[name].value ? " <value>" : ""}  ${table[name].help}`);
+        lines.push("");
+    }
+    lines.push("Global options:");
+    for (const name of Object.keys(GLOBAL_FLAGS)) {
+        lines.push(`  --${name}${GLOBAL_FLAGS[name].value ? " <value>" : ""}  ${GLOBAL_FLAGS[name].help}`);
+    }
+    lines.push("  -h, --help  this text", "  -V, --version  the bundle version");
+    return lines.join("\n");
+}

package/dist/ask.js

@@ -0,0 +1,161 @@
+// ask.ts — `ask raise|accept|list`: raise a decision through the contract's ask route (the cloud
+// renders the body from its own template, so this passes fields, never headings), record an answer
+// through ask-accept, and list open asks ranked by the work each one holds.
+import { flagBool, flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract, teamByKey } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+import { fetchAllPages } from "./pagination.js";
+import { fetchWorkflowStates, postAgent, resolveIssue } from "./write.js";
+export async function cmdAsk(args, ctx) {
+    const [sub, ...rest] = positionals(args);
+    if (!sub)
+        throw new UsageError("ask needs a subcommand: raise | accept | list");
+    if (sub === "raise" && !flagBool(args, "nothing-to-block") && flagList(args, "blocks").length === 0) {
+        throw new UsageError("ask raise needs --blocks <ticket>... (what this decision holds) or --nothing-to-block");
+    }
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const api = apiClient(cfg, ctx);
+    switch (sub) {
+        case "raise":
+            return raise(args, ctx, doc, api);
+        case "accept":
+            return accept(args, ctx, doc, api, rest);
+        case "list":
+            return list(args, ctx, doc, api, cfg);
+        default:
+            throw new UsageError(`unknown ask subcommand: ${sub}`);
+    }
+}
+async function raise(args, ctx, doc, api) {
+    const teamKey = flagString(args, "team");
+    const title = flagString(args, "title");
+    if (!teamKey || !title)
+        throw new UsageError("ask raise needs --team <key> and --title <question>");
+    const team = teamByKey(doc, teamKey);
+    const options = flagList(args, "option");
+    if (options.length > doc.askTemplate.maxLetteredOptions) {
+        throw new UsageError(`ask raise takes at most ${doc.askTemplate.maxLetteredOptions} options`);
+    }
+    const blocks = [];
+    for (const t of flagList(args, "blocks"))
+        blocks.push((await resolveIssue(api, t)).id);
+    const body = { title, teamId: team.id };
+    if (flagString(args, "context"))
+        body.context = flagString(args, "context");
+    if (options.length)
+        body.options = options;
+    if (flagString(args, "default"))
+        body.defaultIfSilent = flagString(args, "default");
+    if (blocks.length)
+        body.blocks = blocks;
+    if (flagBool(args, "nothing-to-block"))
+        body.nothingToBlock = true;
+    if (flagString(args, "ask-key"))
+        body.askKey = flagString(args, "ask-key");
+    const result = await postAgent(api, doc, "ask", body);
+    ctx.stdout(args.json ? JSON.stringify(result) : `ask raised: ${String(result.identifier ?? result.id ?? "ok")}${blocks.length ? ` (blocks ${blocks.length})` : ""}`);
+    return 0;
+}
+async function accept(args, ctx, doc, api, rest) {
+    const askTicket = rest[0];
+    const answer = flagString(args, "answer");
+    const role = flagString(args, "role");
+    if (!askTicket || !answer || !role)
+        throw new UsageError("ask accept needs <askTicket> --answer <commentId> --role <role>");
+    const ask = await resolveIssue(api, askTicket);
+    const result = await postAgent(api, doc, "ask-accept", {
+        askIssueId: ask.id,
+        answerCommentId: answer,
+        acceptedByRole: role,
+    });
+    ctx.stdout(args.json ? JSON.stringify(result) : `ask ${ask.identifier}: answer ${answer} recorded by ${role}`);
+    return 0;
+}
+/** Decide the inbox scope from the connected identity and the `--anyone` flag. A personal key with a
+ *  matched Linear identity reads "mine" by default; `--anyone` widens; an unmatched identity or a
+ *  host key cannot mean "me" and says so rather than filtering to nothing. */
+export function inboxScope(cfg, anyone) {
+    if (anyone)
+        return { kind: "anyone" };
+    if (!cfg.user)
+        return { kind: "no-person" };
+    if (!cfg.user.linearUserId)
+        return { kind: "unmatched", label: cfg.user.label };
+    return { kind: "mine", linearUserId: cfg.user.linearUserId, label: cfg.user.label };
+}
+/** Rank open asks by the priority-weighted count of open tickets each one blocks. Priority 1 (urgent)
+ *  weighs 4, 4 (low) weighs 1, 0 (none) weighs 1. */
+export function rankAsks(issues, doc, openState) {
+    const askIds = new Set();
+    for (const team of doc.teams)
+        for (const l of team.labels.ask)
+            for (const id of [l.unscopedId, l.teamScopedId, l.preferredId])
+                if (id)
+                    askIds.add(id);
+    const isAsk = (issue) => {
+        const labels = Array.isArray(issue.labels) ? issue.labels : [];
+        return labels.some((l) => (typeof l.id === "string" && askIds.has(l.id)) || (typeof l.name === "string" && (l.name === doc.vocabulary.askMarkerLabel || l.name.startsWith(doc.vocabulary.askLabelPrefix))));
+    };
+    const byIdentifier = new Map();
+    for (const i of issues)
+        if (typeof i.identifier === "string")
+            byIdentifier.set(i.identifier, i);
+    const weight = (issue) => {
+        const p = typeof issue?.priority === "number" ? issue.priority : 0;
+        return p >= 1 && p <= 4 ? 5 - p : 1;
+    };
+    const out = [];
+    for (const issue of issues) {
+        if (!isAsk(issue) || !openState(issue))
+            continue;
+        const relations = Array.isArray(issue.relations) ? issue.relations : [];
+        const blocked = relations
+            .filter((r) => r.type === "blocks" && r.issue_identifier === issue.identifier && typeof r.related_identifier === "string")
+            .map((r) => r.related_identifier)
+            .filter((id) => {
+            const t = byIdentifier.get(id);
+            return !t || openState(t);
+        });
+        out.push({
+            identifier: String(issue.identifier),
+            title: String(issue.title ?? ""),
+            state: String(issue.state ?? ""),
+            blocks: blocked,
+            score: blocked.reduce((sum, id) => sum + weight(byIdentifier.get(id)), 0),
+            assigneeId: typeof issue.assignee_id === "string" && issue.assignee_id !== "" ? issue.assignee_id : null,
+        });
+    }
+    return out.sort((a, b) => b.score - a.score || a.identifier.localeCompare(b.identifier));
+}
+async function list(args, ctx, doc, api, cfg) {
+    // ⛔ THE INBOX IS THE WHOLE SCOPE, NOT A PAGE. The mirror caps every page at 500 rows regardless of
+    // the requested limit, so a single `limit: 500` read drops every ask past the cap — and, worse,
+    // scores the asks it does show against a partial view of what they block (rankAsks below).
+    const [inbox, states] = await Promise.all([fetchAllPages(api, "/api/v1/issues", {}), fetchWorkflowStates(api)]);
+    const issues = inbox.rows;
+    const terminal = new Set(states.filter((s) => ["completed", "canceled", "cancelled"].includes(s.type.toLowerCase())).map((s) => s.name.toLowerCase()));
+    const openState = (issue) => !terminal.has(String(issue.state ?? "").toLowerCase());
+    const all = rankAsks(issues, doc, openState);
+    const scope = inboxScope(cfg, flagBool(args, "anyone"));
+    const ranked = scope.kind === "mine" ? all.filter((a) => a.assigneeId === scope.linearUserId) : all;
+    if (args.json) {
+        ctx.stdout(JSON.stringify({ scope, asks: ranked }));
+        return 0;
+    }
+    if (scope.kind === "unmatched") {
+        ctx.stderr(`[catalyst-skills] your Linear identity is not matched yet (an admin matches it in Settings → Members), so this is every open ask, not only yours`);
+    }
+    else if (scope.kind === "no-person") {
+        ctx.stderr(`[catalyst-skills] connected with the tenant's account key, which names no person — this is every open ask; log in with your personal key to see only yours`);
+    }
+    if (ranked.length === 0) {
+        ctx.stdout(scope.kind === "mine" ? `no open asks assigned to ${scope.label} (${all.length} open in the tenant — add --anyone to see them)` : "no open asks");
+        return 0;
+    }
+    for (const a of ranked)
+        ctx.stdout(`${a.identifier}  holds ${a.blocks.length} ticket${a.blocks.length === 1 ? "" : "s"} (weight ${a.score})${a.blocks.length ? `: ${a.blocks.join(", ")}` : ""}  ${a.title}`);
+    return 0;
+}

package/dist/browser.js

@@ -0,0 +1,20 @@
+// browser.ts — open the device-flow verification page in the person's default browser. Best-effort:
+// a machine with no browser (a headless mini, a container) simply shows the code and URL instead, so
+// this never throws into the login flow — the caller wraps it, and a spawn failure is swallowed here.
+import { spawn } from "node:child_process";
+/** The platform's "open this URL" command. `open` on macOS, `start` via cmd on Windows, else xdg-open. */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, [...args], { stdio: "ignore", detached: true });
+        child.on("error", () => { }); // no opener installed — the printed URL is the fallback
+        child.unref();
+    }
+    catch {
+        // spawn itself threw (unusual) — the code and URL on screen are the fallback
+    }
+}