@catalyst-cloud/cli 0.8.0

package/dist/watch/consumer.js

@@ -0,0 +1,141 @@
+import { readCursorFile, writeCursorFile } from "./cursor-file.js";
+export const LOG_PREFIX = "[live-events]";
+function defaultWsFactory(url) {
+    const Ctor = globalThis.WebSocket;
+    if (!Ctor)
+        throw new Error("global WebSocket unavailable; pass wsFactory (Node >= 22 exposes one)");
+    return new Ctor(url);
+}
+export function printFrame(frame) {
+    console.log(`${LOG_PREFIX} frame ${JSON.stringify(frame)}`);
+}
+async function fetchHeadCursor(opts, signal) {
+    const url = `${opts.baseUrl.replace(/\/+$/, "")}/snapshot?head=1`;
+    const res = await (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${await opts.getToken()}` }, signal });
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 200);
+        throw new Error(`head-only snapshot fetch failed: ${res.status} ${res.statusText} at ${url} — ${body}`);
+    }
+    const head = (await res.json());
+    if (head.accountId !== opts.accountId) {
+        throw new Error(`head-only snapshot is for account ${JSON.stringify(head.accountId)} but this session is for ${JSON.stringify(opts.accountId)} — the key and the configured account disagree`);
+    }
+    if (typeof head.cursor !== "number" || !Number.isInteger(head.cursor) || head.cursor < 0) {
+        throw new Error(`head-only snapshot returned a non-integer cursor: ${JSON.stringify(head.cursor)}`);
+    }
+    return head.cursor;
+}
+/**
+ * Build the events-only client. Construction reads the cursor file ONCE (throwing on a corrupt file
+ * or a cross-account reuse); the position is then kept in memory and persisted after every
+ * SUCCESSFUL reaction. React first, persist second: an async reaction is awaited before its cursor
+ * persists and later frames queue behind it in seq order; a failed reaction halts the stream and
+ * closes the socket so the SDK's reconnect replays from the last good cursor.
+ */
+export function createLiveEventsClient(sdk, opts) {
+    let state = opts.fromHead ? null : readCursorFile(opts.cursorFile, opts.accountId);
+    const log = opts.log ??
+        ((level, msg, extra) => console[level === "error" ? "error" : "log"](`${LOG_PREFIX} ${msg}`, extra ?? ""));
+    const persist = (next) => {
+        state = next;
+        writeCursorFile(opts.cursorFile, next);
+    };
+    const reseedHead = async (signal) => {
+        const cursor = await fetchHeadCursor(opts, signal);
+        persist({ account: opts.accountId, cursor });
+        log("info", `cursor re-seeded to tenant head ${cursor} (head-only; no rows applied)`);
+        opts.onReseed?.(cursor);
+        return cursor;
+    };
+    const react = opts.onEvent ?? printFrame;
+    let socket = null;
+    let halted = false;
+    let inFlight = null;
+    const queued = [];
+    const advance = (frame) => {
+        if (state && state.cursor >= frame.seq)
+            return;
+        persist({ account: frame.accountId, cursor: frame.seq });
+    };
+    const fail = (frame, err) => {
+        halted = true;
+        queued.length = 0;
+        inFlight = null;
+        log("error", `reaction failed for ${frame.entity} seq=${frame.seq}; cursor left at ${state?.cursor ?? "none"} — reconnecting so the replay re-offers it`, err);
+        const ws = socket;
+        socket = null;
+        try {
+            ws?.close();
+        }
+        catch {
+            // already closing/closed
+        }
+    };
+    const settle = (frame) => {
+        advance(frame);
+        inFlight = null;
+        const next = queued.shift();
+        if (next)
+            run(next);
+    };
+    const run = (frame) => {
+        let result;
+        try {
+            result = react(frame);
+        }
+        catch (err) {
+            fail(frame, err);
+            return;
+        }
+        if (result && typeof result.then === "function") {
+            const p = result.then(() => {
+                if (inFlight === p)
+                    settle(frame);
+            }, (err) => {
+                if (inFlight === p)
+                    fail(frame, err);
+            });
+            inFlight = p;
+            return;
+        }
+        advance(frame);
+    };
+    const wrappedFactory = (url) => {
+        const ws = (opts.wsFactory ?? defaultWsFactory)(url);
+        socket = ws;
+        halted = false;
+        queued.length = 0;
+        inFlight = null;
+        return ws;
+    };
+    const client = new sdk.LiveSyncClient({
+        baseUrl: opts.baseUrl,
+        accountId: opts.accountId,
+        auth: opts.auth,
+        reseed: reseedHead,
+        getCursor: () => state?.cursor ?? null,
+        onChange: (frame) => {
+            if (frame.accountId !== opts.accountId) {
+                const msg = `refusing frame for account ${JSON.stringify(frame.accountId)} — this session is for ${JSON.stringify(opts.accountId)} (cursor left at ${state?.cursor ?? "none"})`;
+                log("error", msg);
+                throw new Error(msg);
+            }
+            if (halted)
+                return;
+            if (inFlight) {
+                queued.push(frame);
+                return;
+            }
+            run(frame);
+        },
+        onStatus: opts.onStatus ??
+            ((status) => {
+                log("info", `status=${status}`);
+            }),
+        backoffMs: opts.backoffMs,
+        maxBackoffMs: opts.maxBackoffMs,
+        wsFactory: wrappedFactory,
+        log,
+    });
+    return { client, cursor: () => state?.cursor ?? null, reseedHead };
+}

package/dist/watch/cursor-file.js

@@ -0,0 +1,62 @@
+// watch/cursor-file.ts — the durable cursor store for the events-only `watch` consumer, ported whole
+// from the cloud's tested host-sync implementation. The file is the whole state:
+//
+//   { "account": "<tenant id>", "cursor": 41 }
+//
+// The account field is load-bearing: a cursor is a position in ONE tenant's change log, so the file
+// refuses to be read for a different account than the one stamped in it (a named throw naming both
+// accounts). A torn or corrupt file also fails loudly; the only "no state yet" is the file's absence.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export class CursorFileError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = "CursorFileError";
+    }
+}
+function validateShape(parsed) {
+    if (typeof parsed !== "object" || parsed === null)
+        return { ok: false, error: "content is not a JSON object" };
+    const { account, cursor } = parsed;
+    if (typeof account !== "string" || account.trim() === "")
+        return { ok: false, error: "account is missing or not a non-empty string" };
+    if (typeof cursor !== "number" || !Number.isInteger(cursor) || cursor < 0)
+        return { ok: false, error: "cursor is missing or not a non-negative integer" };
+    return { ok: true, state: { account, cursor } };
+}
+/** Returns null ONLY when the file is absent. Throws CursorFileError on an unreadable, corrupt, or
+ *  wrongly shaped file, and on a cross-account file when `expectAccount` is given. */
+export function readCursorFile(path, expectAccount) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new CursorFileError(`cannot read cursor file: ${err instanceof Error ? err.message : String(err)}`, path);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CursorFileError("cursor file is not valid JSON (torn write?) — delete it to re-seed from the tenant head, at the cost of replaying nothing in between", path);
+    }
+    const shape = validateShape(parsed);
+    if (!shape.ok)
+        throw new CursorFileError(`cursor file is malformed: ${shape.error}`, path);
+    if (expectAccount !== undefined && shape.state.account !== expectAccount) {
+        throw new CursorFileError(`cursor file belongs to account ${JSON.stringify(shape.state.account)} but this session is for ${JSON.stringify(expectAccount)} — a cursor is a position in ONE tenant's feed; move or delete the file rather than replaying one tenant's position against another`, path);
+    }
+    return shape.state;
+}
+/** Atomic: a sibling temp file, then rename over the target. */
+export function writeCursorFile(path, state) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(state)}\n`, "utf8");
+    renameSync(tmp, path);
+}

package/dist/watch.js

@@ -0,0 +1,175 @@
+// watch.ts — `watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file] [--from]`:
+// one JSON line per in-scope change frame, cursor advanced after the reaction, over the SDK's live
+// stream. Scope is filtered on the client from the frame's entity and row; a project scope resolves
+// an issue reference to its project through GET /api/v1/issues/:ref, cached in memory.
+import { spawn } from "node:child_process";
+import { flagList, flagString } from "./args.js";
+import { apiBase, requireConfig, watchCursorPathFor } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+import { authStrategyFor, bearerFor } from "./oauth.js";
+import { loadSdk } from "./sdk.js";
+import { createLiveEventsClient } from "./watch/consumer.js";
+import { CursorFileError } from "./watch/cursor-file.js";
+const ROW_ISSUE_REFS = ["identifier", "linear_issue_identifier", "issue_identifier", "issue_id", "linear_issue_id"];
+/** Decide whether one frame falls inside the scope. An empty scope admits everything. Rows that only
+ *  carry an issue reference (comments, sessions, PRs) resolve it through `resolve` for project scope. */
+export async function inScope(frame, scope, resolve) {
+    const hasScope = Boolean(scope.teamId || scope.teamKey || (scope.tickets && scope.tickets.length) || scope.projectId);
+    if (!hasScope)
+        return true;
+    const row = frame.row ?? {};
+    const refs = ROW_ISSUE_REFS.map((k) => row[k]).filter((v) => typeof v === "string" && v !== "");
+    const upperTickets = (scope.tickets ?? []).map((t) => t.toUpperCase());
+    if (upperTickets.length > 0) {
+        if (refs.some((r) => upperTickets.includes(r.toUpperCase())))
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info?.identifier && upperTickets.includes(info.identifier.toUpperCase()))
+                return true;
+        }
+    }
+    if (scope.projectId) {
+        if (row.project_id === scope.projectId || row.id === scope.projectId)
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info?.projectId === scope.projectId)
+                return true;
+        }
+    }
+    if (scope.teamId || scope.teamKey) {
+        if (scope.teamId && (row.team_id === scope.teamId || row.teamId === scope.teamId))
+            return true;
+        if (scope.teamKey && refs.some((r) => /^[A-Za-z]+-\d+$/.test(r) && r.toUpperCase().startsWith(`${scope.teamKey.toUpperCase()}-`)))
+            return true;
+        for (const r of refs) {
+            const info = await resolve(r);
+            if (info && scope.teamId && info.teamId === scope.teamId)
+                return true;
+            if (info?.identifier && scope.teamKey && info.identifier.toUpperCase().startsWith(`${scope.teamKey.toUpperCase()}-`))
+                return true;
+        }
+    }
+    return false;
+}
+/** Resolve issue references through the API, cached per process. */
+export function apiIssueResolver(cfg, ctx) {
+    const api = apiClient(cfg, ctx);
+    const cache = new Map();
+    return async (ref) => {
+        if (cache.has(ref))
+            return cache.get(ref);
+        let out = null;
+        try {
+            const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ref)}`, { accept: [404] });
+            if (res.status !== 404 && res.body) {
+                out = {
+                    id: typeof res.body.id === "string" ? res.body.id : null,
+                    identifier: typeof res.body.identifier === "string" ? res.body.identifier : null,
+                    projectId: typeof res.body.project_id === "string" ? res.body.project_id : null,
+                    teamId: typeof res.body.team_id === "string" ? res.body.team_id : null,
+                };
+            }
+        }
+        catch {
+            out = null;
+        }
+        cache.set(ref, out);
+        return out;
+    };
+}
+/**
+ * Run `--exec CMD` once with the frame on stdin; a non-zero exit is a failed reaction.
+ *
+ * The child's EXIT CODE is the whole contract, and a broken pipe is not a failure on its own. A
+ * handler that exits before reading the frame is ordinary and often correct — `grep -q`, `head -1`,
+ * a script that fails fast — and so is one that simply died. In every one of those cases the write
+ * lands on a pipe with nothing at the other end and raises EPIPE asynchronously. Node delivers that
+ * as an `error` event on the child's stdin, and a stream with no `error` listener rethrows it as an
+ * unhandled error, which takes down the whole watch: one misbehaving handler and the customer stops
+ * receiving their tenant's events. So the pipe is allowed to break, and the exit code still decides.
+ */
+export function execReaction(cmd, env) {
+    return (frame) => new Promise((resolve, reject) => {
+        const child = spawn("sh", ["-c", cmd], { stdio: ["pipe", "inherit", "inherit"], env });
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`--exec exited ${code}`))));
+        // Listen before writing: attaching afterwards races the synchronous part of `end()`.
+        child.stdin.on("error", () => { });
+        try {
+            if (child.stdin.writable)
+                child.stdin.end(`${JSON.stringify(frame)}\n`);
+        }
+        catch {
+            // A stdin already destroyed throws here rather than emitting; same verdict, wait for close.
+        }
+    });
+}
+export async function runWatch(ctx, cfg, opts, deps = {}) {
+    const sdk = deps.sdk ?? (await loadSdk());
+    const resolve = deps.resolver ?? apiIssueResolver(cfg, ctx);
+    const react = opts.exec ? execReaction(opts.exec, ctx.env) : undefined;
+    let handle;
+    try {
+        handle = buildHandle();
+    }
+    catch (err) {
+        if (err instanceof CursorFileError)
+            throw new CliError(`${err.message} (${err.path})`, "cursor-file");
+        throw err;
+    }
+    deps.onHandle?.(handle);
+    const stopped = deps.waitForStop ??
+        (() => new Promise((done) => {
+            process.once("SIGINT", () => done());
+            process.once("SIGTERM", () => done());
+        }));
+    const running = handle.client.start();
+    await stopped();
+    handle.client.stop();
+    await running;
+    return 0;
+    function buildHandle() {
+        return createLiveEventsClient(sdk, {
+            baseUrl: apiBase(cfg),
+            accountId: cfg.account,
+            auth: authStrategyFor(ctx, cfg),
+            getToken: () => bearerFor(ctx, cfg),
+            cursorFile: opts.cursorFile ?? watchCursorPathFor(ctx.home),
+            fromHead: opts.fromHead,
+            fetchImpl: ctx.fetch,
+            wsFactory: deps.wsFactory,
+            backoffMs: deps.backoffMs,
+            maxBackoffMs: deps.maxBackoffMs,
+            log: (level, msg) => ctx.stderr(`[watch ${level}] ${msg}`),
+            onStatus: (s) => ctx.stderr(`[watch] status=${s}`),
+            onReseed: (cursor) => ctx.stderr(`[watch] resync: cursor moved to head ${cursor}`),
+            onEvent: async (frame) => {
+                if (!(await inScope(frame, opts.scope, resolve)))
+                    return;
+                ctx.stdout(JSON.stringify(frame));
+                if (react)
+                    await react(frame);
+            },
+        });
+    }
+}
+export async function cmdWatch(args, ctx, deps = {}) {
+    const cfg = requireConfig(ctx);
+    const from = flagString(args, "from") ?? "cursor";
+    if (from !== "cursor" && from !== "head")
+        throw new UsageError("--from must be cursor or head");
+    const scope = { tickets: flagList(args, "ticket"), projectId: flagString(args, "project") };
+    const teamKey = flagString(args, "team");
+    if (teamKey) {
+        const { doc } = await loadContract(ctx, cfg);
+        const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+        scope.teamKey = teamKey;
+        if (team)
+            scope.teamId = team.id;
+    }
+    return runWatch(ctx, cfg, { scope, exec: flagString(args, "exec"), cursorFile: flagString(args, "cursor-file"), fromHead: from === "head" }, deps);
+}

package/dist/write.js

@@ -0,0 +1,224 @@
+// write.ts — writes to Linear as the app actor through the agent proxy. Every route path comes from
+// the contract's route table (never a literal); every stage id from `teams[].stages` by slot; every
+// label id from `teams[].labels`; the bookkeeping marker from `vocabulary`. `delegate` is never offered.
+import { readFileSync } from "node:fs";
+import { flagBool, flagInt, flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { bookkeepingPrefix, labelId, loadContract, routePath, stageIdForSlot, teamByKey, teamForTicket } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./transport.js";
+/** A ticket identifier → its Linear id (and team/project) through GET /api/v1/issues/:identifier. */
+export async function resolveIssue(api, ticket) {
+    const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}`, { accept: [404] });
+    if (res.status === 404 || !res.body || typeof res.body.id !== "string") {
+        throw new CliError(`ticket ${ticket} is not in the mirror — check the identifier`, "ticket-unknown");
+    }
+    return {
+        id: res.body.id,
+        identifier: typeof res.body.identifier === "string" ? res.body.identifier : ticket,
+        teamId: typeof res.body.team_id === "string" ? res.body.team_id : null,
+        projectId: typeof res.body.project_id === "string" ? res.body.project_id : null,
+    };
+}
+/** GET /api/v1/workflow-stages, read tolerantly: `{teams:[{teamId|id|key, states|stages:[...]}]}`,
+ *  `{stages:[...]}` or a bare array of states each carrying `team_id|teamId`. */
+export async function fetchWorkflowStates(api) {
+    const res = await api.getJson("/api/v1/workflow-stages");
+    const out = [];
+    const push = (s, teamId) => {
+        if (typeof s.id !== "string")
+            return;
+        out.push({
+            id: s.id,
+            name: String(s.name ?? ""),
+            type: String(s.type ?? ""),
+            teamId: (typeof s.team_id === "string" ? s.team_id : typeof s.teamId === "string" ? s.teamId : teamId) ?? null,
+        });
+    };
+    const body = res.body;
+    if (Array.isArray(body)) {
+        for (const s of body)
+            push(s, null);
+    }
+    else if (body && typeof body === "object") {
+        const teams = body.teams;
+        if (Array.isArray(teams)) {
+            for (const t of teams) {
+                const teamId = typeof t.teamId === "string" ? t.teamId : typeof t.id === "string" ? t.id : typeof t.team_id === "string" ? t.team_id : null;
+                const states = (t.states ?? t.stages);
+                if (Array.isArray(states))
+                    for (const s of states)
+                        push(s, teamId);
+            }
+        }
+        const stages = body.stages ?? body.states;
+        if (Array.isArray(stages))
+            for (const s of stages)
+                push(s, null);
+    }
+    return out;
+}
+/** The first state of `type` on `teamId`, in the order the route lists them. */
+export function firstStateOfType(states, teamId, type) {
+    const hit = states.find((s) => s.teamId === teamId && s.type.toLowerCase() === type.toLowerCase());
+    if (!hit) {
+        const seen = [...new Set(states.filter((s) => s.teamId === teamId).map((s) => s.type))].join(", ") || "none";
+        throw new CliError(`team ${teamId} has no state of type "${type}" (types seen: ${seen})`, "state-type-unknown");
+    }
+    return hit;
+}
+/** Post to a contract route by name; a budget refusal names the contract's daily budget. */
+export async function postAgent(api, doc, routeName, body) {
+    try {
+        const res = await api.postJson(routePath(doc, routeName), body);
+        return res.body;
+    }
+    catch (err) {
+        if (err instanceof CliError && err.code === "budget") {
+            throw new CliError(`${err.message} — the contract's thresholds.hostDailyWriteBudget is ${doc.thresholds.hostDailyWriteBudget} writes per host per day`, "budget", 2, 429);
+        }
+        throw err;
+    }
+}
+export async function cmdWrite(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (!sub)
+        throw new UsageError("write needs a subcommand: comment | state | label | create | reaction | attachment | session");
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const api = apiClient(cfg, ctx);
+    const asUser = flagBool(args, "as-user");
+    let result;
+    switch (sub) {
+        case "comment": {
+            const ticket = needTicket(rest, "comment <ticket>");
+            let body = flagString(args, "body");
+            if (flagBool(args, "stdin"))
+                body = (await (deps.readStdin ?? readStdin)()).trimEnd();
+            if (!body)
+                throw new UsageError("write comment needs --body <text> or --stdin");
+            if (flagBool(args, "bookkeeping"))
+                body = `${bookkeepingPrefix(doc)} ${body}`;
+            const issue = await resolveIssue(api, ticket);
+            result = await postAgent(api, doc, "issue-comment", {
+                issueId: issue.id,
+                body,
+                ...(flagString(args, "parent") ? { parentId: flagString(args, "parent") } : {}),
+                ...(asUser ? { createAsUser: true } : {}),
+            });
+            break;
+        }
+        case "state": {
+            const ticket = needTicket(rest, "state <ticket>");
+            const issue = await resolveIssue(api, ticket);
+            const slot = flagString(args, "slot");
+            const stateId = flagString(args, "state-id");
+            const stateType = flagString(args, "state-type");
+            let target;
+            if (stateId)
+                target = stateId;
+            else if (slot)
+                target = stageIdForSlot(teamForTicket(doc, issue.identifier), slot);
+            else if (stateType) {
+                const team = teamForTicket(doc, issue.identifier);
+                target = firstStateOfType(await fetchWorkflowStates(api), issue.teamId ?? team.id, stateType).id;
+            }
+            else
+                throw new UsageError("write state needs --slot <slot>, --state-id <id> or --state-type <type>");
+            result = await postAgent(api, doc, "issue-state", { issueId: issue.id, stateId: target });
+            break;
+        }
+        case "label": {
+            const ticket = needTicket(rest, "label <ticket>");
+            const add = flagList(args, "add");
+            const remove = flagList(args, "remove");
+            if (add.length === 0 && remove.length === 0)
+                throw new UsageError("write label needs --add <name|id> and/or --remove <name|id>");
+            const issue = await resolveIssue(api, ticket);
+            const team = teamForTicket(doc, issue.identifier);
+            const results = [];
+            if (add.length)
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: add.map((n) => labelId(team, n)), mode: "add" }));
+            if (remove.length)
+                results.push(await postAgent(api, doc, "issue-label", { issueId: issue.id, labelIds: remove.map((n) => labelId(team, n)), mode: "remove" }));
+            result = results.length === 1 ? results[0] : results;
+            break;
+        }
+        case "create": {
+            const teamKey = flagString(args, "team");
+            const title = flagString(args, "title");
+            if (!teamKey || !title)
+                throw new UsageError("write create needs --team <key> and --title <text>");
+            const team = teamByKey(doc, teamKey);
+            const labels = flagList(args, "label").map((n) => labelId(team, n));
+            const priority = flagString(args, "priority") !== undefined ? flagInt(args, "priority", 0) : undefined;
+            result = await postAgent(api, doc, "issue-create", {
+                teamId: team.id,
+                title,
+                ...(labels.length ? { labelIds: labels } : {}),
+                ...(priority !== undefined ? { priority } : {}),
+                ...(asUser ? { createAsUser: true } : {}),
+            });
+            break;
+        }
+        case "reaction": {
+            const emoji = flagString(args, "emoji");
+            if (!emoji)
+                throw new UsageError("write reaction needs --emoji <e>");
+            const commentId = flagString(args, "comment");
+            const body = { emoji, ...(asUser ? { createAsUser: true } : {}) };
+            if (commentId)
+                body.commentId = commentId;
+            else
+                body.issueId = (await resolveIssue(api, needTicket(rest, "reaction <ticket>|--comment <id>"))).id;
+            result = await postAgent(api, doc, "reaction", body);
+            break;
+        }
+        case "attachment": {
+            const ticket = needTicket(rest, "attachment <ticket>");
+            const title = flagString(args, "title");
+            const url = flagString(args, "url");
+            if (!title || !url)
+                throw new UsageError("write attachment needs --title <t> and --url <u>");
+            const issue = await resolveIssue(api, ticket);
+            result = await postAgent(api, doc, "attachment", { issueId: issue.id, title, url });
+            break;
+        }
+        case "session": {
+            const ticket = needTicket(rest, "session <ticket>");
+            const issue = await resolveIssue(api, ticket);
+            const planFile = flagString(args, "plan-file");
+            const plan = planFile ? JSON.parse(readFileSync(planFile, "utf8")) : undefined;
+            result = await postAgent(api, doc, "session", {
+                issueId: issue.id,
+                ...(flagString(args, "title") ? { title: flagString(args, "title") } : {}),
+                ...(plan !== undefined ? { plan } : {}),
+                ...(flagString(args, "activity") ? { activity: flagString(args, "activity") } : {}),
+                ...(flagString(args, "url") ? { url: flagString(args, "url") } : {}),
+            });
+            break;
+        }
+        case "delegate":
+            throw new UsageError("write delegate is not offered: delegation is an operator action, not a tenant write");
+        default:
+            throw new UsageError(`unknown write subcommand: ${sub}`);
+    }
+    ctx.stdout(args.json ? JSON.stringify(result ?? {}) : describeWrite(sub, result));
+    return 0;
+}
+function needTicket(rest, usage) {
+    const t = rest[0];
+    if (!t)
+        throw new UsageError(`write ${usage}`);
+    return t;
+}
+function describeWrite(sub, result) {
+    const id = result && typeof result === "object" ? result.id ?? result.commentId ?? result.issueId : undefined;
+    return `${sub}: ok${id ? ` (${String(id)})` : ""}`;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@catalyst-cloud/cli",
+  "version": "0.8.0",
+  "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coalesce-labs/catalyst-cloud-skills.git"
+  },
+  "homepage": "https://github.com/coalesce-labs/catalyst-cloud-skills#readme",
+  "bugs": {
+    "url": "https://github.com/coalesce-labs/catalyst-cloud-skills/issues"
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "bin": {
+    "catalyst": "bin/catalyst.js",
+    "catalyst-skills": "bin/catalyst-skills.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "vendor"
+  ],
+  "catalystCloud": {
+    "tenantContractRange": "1.x",
+    "pinnedNode": "24.21.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "version:sync": "node scripts/sync-plugin-version.mjs",
+    "skill-lib:sync": "node scripts/sync-skill-lib.mjs",
+    "skills:scan": "node scripts/scan-skills.mjs",
+    "evals": "node scripts/run-evals.mjs",
+    "paths:check": "node scripts/vendor-paths.mjs --check"
+  },
+  "dependencies": {
+    "@catalyst-cloud/sdk": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.0"
+  }
+}