@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

package/dist/contract.js

@@ -1,178 +0,0 @@
-// contract.ts — GET /api/v1/agent/contract, cached with its ETag at ~/.config/catalyst-cloud/contract.json.
-// Every tenant fact a verb needs (stage ids, label ids, route paths, the bookkeeping marker, thresholds)
-// is read from here; no verb carries a literal fallback for any of them.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { contractPathFor, readManifest } from "./config.js";
-import { CliError, MeError } from "./errors.js";
-import { apiClient } from "./transport.js";
-export const CONTRACT_ROUTE = "/api/v1/agent/contract";
-export function readContractCache(home) {
-    const path = contractPathFor(home);
-    if (!existsSync(path))
-        return null;
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof parsed.fetchedAt !== "string" || typeof parsed.contractVersion !== "string" || !parsed.doc)
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-export function writeContractCache(home, cache) {
-    const path = contractPathFor(home);
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(cache, null, 2) + "\n", { mode: 0o600 });
-    renameSync(tmp, path);
-    return path;
-}
-/** `1.x` → major 1; `1.2.3` → exact; `unpinned` → anything. Returns null when the range is unparseable. */
-export function contractVersionInRange(version, range) {
-    if (range === "unpinned")
-        return true;
-    const major = /^(\d+)\.x$/.exec(range);
-    if (major)
-        return version.split(".")[0] === major[1];
-    if (/^\d+\.\d+\.\d+$/.test(range))
-        return version === range;
-    return null;
-}
-export function assertContractRange(version, range) {
-    const ok = contractVersionInRange(version, range);
-    if (ok === null)
-        throw new CliError(`tenantContractRange "${range}" in package.json is not a range this CLI understands`, "contract-range");
-    if (!ok) {
-        throw new CliError(`the tenant serves contract version ${version} but this bundle accepts ${range} — update the bundle (npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login) or ask your tenant admin which version is live`, "contract-version");
-    }
-}
-/**
- * Load the contract per the cloud's own cache policy: a cache younger than `doc.cache.maxAgeSeconds`
- * is used as-is; otherwise a conditional GET revalidates it (304 refreshes `fetchedAt`, 200 replaces
- * the document). A network failure on a cache older than `staleRefusalSeconds` refuses; a 403 (a
- * personal key on an older cloud) refuses naming the cloud version; a major version outside the bundle's range refuses
- * naming both versions.
- */
-export async function loadContract(ctx, cfg, opts = {}) {
-    const path = contractPathFor(ctx.home);
-    const cached = readContractCache(ctx.home);
-    const nowMs = ctx.now().getTime();
-    const ageSeconds = cached ? Math.max(0, Math.floor((nowMs - Date.parse(cached.fetchedAt)) / 1000)) : Infinity;
-    const range = readManifest().tenantContractRange;
-    if (cached && !opts.refresh && ageSeconds < cached.doc.cache.maxAgeSeconds) {
-        assertContractRange(cached.contractVersion, range);
-        return { doc: cached.doc, source: "cache", ageSeconds, path };
-    }
-    if (opts.offline) {
-        if (cached) {
-            assertContractRange(cached.contractVersion, range);
-            return { doc: cached.doc, source: "cache", ageSeconds, path };
-        }
-        throw new CliError("no cached contract and network reads are disabled", "contract-missing");
-    }
-    const api = apiClient(cfg, ctx);
-    let res;
-    try {
-        res = await api.getJson(CONTRACT_ROUTE, { etag: cached?.etag ?? null, accept: [304] });
-    }
-    catch (err) {
-        if (err instanceof CliError && err.status === 403) {
-            throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): this cloud is older than the bundle and does not yet admit a personal key on the contract — update the cloud, or log in with the tenant's account key until it is`, "contract-forbidden", 2, 403);
-        }
-        if (err instanceof MeError && err.kind === "network" && cached) {
-            if (ageSeconds >= cached.doc.cache.staleRefusalSeconds) {
-                throw new CliError(`the cached contract is ${ageSeconds}s old (refusal after ${cached.doc.cache.staleRefusalSeconds}s) and the refresh failed: ${err.message}`, "contract-stale");
-            }
-            assertContractRange(cached.contractVersion, range);
-            return { doc: cached.doc, source: "cache", ageSeconds, path };
-        }
-        throw err;
-    }
-    if (res.status === 304) {
-        if (!cached)
-            throw new CliError(`GET ${CONTRACT_ROUTE} answered 304 with no cache to revalidate`, "contract-shape");
-        assertContractRange(cached.contractVersion, range);
-        writeContractCache(ctx.home, { ...cached, fetchedAt: ctx.now().toISOString() });
-        return { doc: cached.doc, source: "revalidated", ageSeconds: 0, path };
-    }
-    const doc = res.body;
-    if (!doc || typeof doc !== "object" || typeof doc.contractVersion !== "string" || !Array.isArray(doc.teams) || !Array.isArray(doc.routes)) {
-        throw new CliError(`GET ${CONTRACT_ROUTE} returned an unexpected shape`, "contract-shape");
-    }
-    const version = res.headers.get("x-catalyst-contract-version") ?? doc.contractVersion;
-    assertContractRange(version, range);
-    writeContractCache(ctx.home, {
-        etag: res.headers.get("etag"),
-        fetchedAt: ctx.now().toISOString(),
-        contractVersion: version,
-        doc,
-    });
-    return { doc, source: "network", ageSeconds: 0, path };
-}
-// ── helpers every verb uses ──────────────────────────────────────────────────────────────────────
-export function teamByKey(doc, key) {
-    const wanted = key.toUpperCase();
-    const team = doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted);
-    if (!team) {
-        const known = doc.teams.map((t) => t.key ?? t.id).join(", ") || "none";
-        throw new CliError(`team "${key}" is not on this tenant's contract (teams: ${known})`, "team-unknown");
-    }
-    return team;
-}
-export function teamById(doc, id) {
-    return doc.teams.find((t) => t.id === id) ?? null;
-}
-/** The team a ticket identifier belongs to, by its `KEY-` prefix. */
-export function teamForTicket(doc, ticket) {
-    const dash = ticket.indexOf("-");
-    if (dash <= 0)
-        throw new CliError(`"${ticket}" is not a ticket identifier (expected KEY-123)`, "ticket-shape");
-    return teamByKey(doc, ticket.slice(0, dash));
-}
-export function stageIdForSlot(team, slot) {
-    const stage = team.stages[slot];
-    if (!stage) {
-        const mapped = Object.keys(team.stages).join(", ") || "none";
-        throw new CliError(`slot "${slot}" is not mapped for team ${team.key ?? team.id} (mapped: ${mapped})`, "slot-unmapped");
-    }
-    if (!stage.stateStillExists) {
-        throw new CliError(`slot "${slot}" on team ${team.key ?? team.id} maps to state ${stage.stateId}, which no longer exists in Linear — fix the mapping in settings first`, "slot-stale");
-    }
-    return stage.stateId;
-}
-/** Resolve a label by name through the contract's ask/hold/release lists; an unknown name is returned
- *  as-is when it looks like an id (the contract only lists Catalyst's own labels). */
-export function labelId(team, nameOrId) {
-    const all = [...team.labels.ask, ...team.labels.hold, ...team.labels.release];
-    const hit = all.find((l) => l.name === nameOrId);
-    if (hit) {
-        if (!hit.preferredId) {
-            throw new CliError(`label "${nameOrId}" is absent from this workspace (contract scope: ${hit.scope}) — create it in Linear first`, "label-absent");
-        }
-        return hit.preferredId;
-    }
-    return nameOrId;
-}
-/** The route whose last path segment is `name` (e.g. `issue-comment`). The path itself is never assumed. */
-export function routePath(doc, name) {
-    const route = doc.routes.find((r) => r.path.split("/").filter(Boolean).at(-1) === name);
-    if (!route) {
-        throw new CliError(`the tenant contract serves no "${name}" route (routes: ${doc.routes.map((r) => r.path).join(", ")})`, "route-unknown");
-    }
-    return route.path;
-}
-export function bookkeepingPrefix(doc) {
-    return doc.vocabulary.bookkeeping.marker;
-}
-/** Walk a dotted path (`teams.0.stages`) into the document. */
-export function pickPath(doc, path) {
-    let cur = doc;
-    for (const seg of path.split(".").filter(Boolean)) {
-        if (cur === null || typeof cur !== "object")
-            return undefined;
-        cur = cur[seg];
-    }
-    return cur;
-}

package/dist/detach.js

@@ -1,10 +0,0 @@
-// detach.ts — re-spawn this CLI detached (replica start --detach). Isolated so a test can stub it.
-import { spawn } from "node:child_process";
-/** Spawn `process.execPath <argv>` detached from this process, stdio ignored, and let it go. */
-export function detachSelf(argv, env = process.env) {
-    const child = spawn(process.execPath, argv, { detached: true, stdio: "ignore", env });
-    child.unref();
-    if (typeof child.pid !== "number")
-        throw new Error("detached spawn returned no pid");
-    return { pid: child.pid };
-}

package/dist/errors.js

@@ -1,27 +0,0 @@
-// errors.ts — the three error classes the exit contract is built on: usage → 1, MeError/CliError → 2.
-export class UsageError extends Error {
-}
-export class CliError extends Error {
-    code;
-    exitCode;
-    status;
-    constructor(message, code, 
-    /** Exit code the dispatcher returns for this error. Defaults to 2 (the CliError contract). */
-    exitCode = 2, 
-    /** The HTTP status that produced it, when one did. */
-    status) {
-        super(message);
-        this.code = code;
-        this.exitCode = exitCode;
-        this.status = status;
-    }
-}
-export class MeError extends Error {
-    kind;
-    status;
-    constructor(message, kind, status) {
-        super(message);
-        this.kind = kind;
-        this.status = status;
-    }
-}

package/dist/events.js

@@ -1,106 +0,0 @@
-import { flagInt, flagString, positionals } from "./args.js";
-import { apiBase, requireConfig } from "./config.js";
-import { CliError, UsageError } from "./errors.js";
-import { authStrategyFor } from "./oauth.js";
-const eventsModule = "@catalyst-cloud/sdk/events";
-export const loadEventsSdk = () => import(eventsModule);
-export async function createEventSync(ctx, deps = {}) {
-    const cfg = requireConfig(ctx);
-    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
-    const auth = authStrategyFor(ctx, cfg);
-    if (auth.kind === "cookie")
-        throw new CliError("event sync requires a token or OAuth session", "events-auth");
-    return new sdk.CatalystEventSync({
-        baseUrl: apiBase(cfg),
-        auth,
-        tenantId: cfg.account,
-        fetch: ctx.fetch,
-    });
-}
-export async function cmdEvents(args, ctx, deps = {}) {
-    const [sub] = positionals(args);
-    if (!sub)
-        throw new UsageError("events needs a subcommand: tail | wait-for | query");
-    if (!["tail", "wait-for", "query"].includes(sub))
-        throw new UsageError(`unknown events subcommand: ${sub}`);
-    const cfg = requireConfig(ctx);
-    const sdk = await (deps.loadSdk ?? loadEventsSdk)();
-    const directory = flagString(args, "directory") ??
-        sdk.defaultEventCacheDirectory(cfg.account);
-    const after = startingCursor(args, sub === "query");
-    const matches = matcher(args);
-    if (sub === "query") {
-        const events = (await sdk.readCachedEvents({ tenantId: cfg.account, directory, after }))
-            .filter(matches)
-            .slice(-flagInt(args, "limit", 50));
-        for (const event of events)
-            ctx.stdout(JSON.stringify(event));
-        return 0;
-    }
-    const controller = new AbortController();
-    const abort = () => controller.abort(deps.signal?.reason);
-    if (deps.signal?.aborted)
-        abort();
-    else
-        deps.signal?.addEventListener("abort", abort, { once: true });
-    const timer = sub === "wait-for"
-        ? setTimeout(() => controller.abort(new Error("event wait timed out")), flagInt(args, "timeout", 300) * 1_000)
-        : undefined;
-    try {
-        for await (const event of sdk.tailCachedEvents({
-            tenantId: cfg.account,
-            directory,
-            after,
-            signal: controller.signal,
-        })) {
-            if (!matches(event))
-                continue;
-            ctx.stdout(JSON.stringify(event));
-            if (sub === "wait-for")
-                return 0;
-        }
-        return sub === "wait-for" ? 1 : 0;
-    }
-    catch (error) {
-        if (controller.signal.aborted)
-            return sub === "wait-for" ? 1 : 0;
-        if (error.code === "ENOENT")
-            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst-skills replica start --detach`, "events-absent", 3);
-        throw error;
-    }
-    finally {
-        if (timer)
-            clearTimeout(timer);
-        deps.signal?.removeEventListener("abort", abort);
-    }
-}
-function startingCursor(args, history) {
-    const requested = flagString(args, "after");
-    if (requested !== undefined) {
-        const parsed = Number(requested);
-        if (!Number.isSafeInteger(parsed) || parsed < 0)
-            throw new UsageError("--after must be a non-negative event sequence");
-        return parsed;
-    }
-    if (history)
-        return undefined;
-    return undefined;
-}
-function matcher(args) {
-    const type = flagString(args, "type");
-    const ticket = flagString(args, "ticket")?.toUpperCase();
-    return (event) => (!type || event.type === type) &&
-        (!ticket || payloadReferences(event.payload, ticket));
-}
-function payloadReferences(value, ticket) {
-    if (typeof value === "string")
-        return value.toUpperCase() === ticket;
-    if (Array.isArray(value))
-        return value.some((item) => payloadReferences(item, ticket));
-    if (!value || typeof value !== "object")
-        return false;
-    return Object.entries(value).some(([key, item]) => ["ticket", "identifier", "workItemKey", "issueIdentifier"].includes(key) &&
-        typeof item === "string"
-        ? item.toUpperCase() === ticket
-        : payloadReferences(item, ticket));
-}