@catalyst-cloud/cli 0.8.0

package/dist/contract.js

@@ -0,0 +1,184 @@
+// 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, upgradeCommand } 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 (${upgradeCommand()}) 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;
+}
+/** The contract's team for a key, or null. `teamByKey` refuses; this one answers "is it there?" for
+ *  readers (explain's cached dispatch gate) that must stay silent for a team the contract omits. */
+export function findTeamByKey(doc, key) {
+    const wanted = key.toUpperCase();
+    return doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted) ?? null;
+}
+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

@@ -0,0 +1,10 @@
+// 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/environment.js

@@ -0,0 +1,207 @@
+// environment.ts — `catalyst-skills 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.
+//
+// ⛔ THE ROUTE PATHS ARE DISCOVERED, NEVER ASSUMED. `read` is the route the contract's table names;
+// `propose` and `approve` are derived from it the way the Worker derives them (one prefix, three
+// verbs) and then CHECKED against the same table. A tenant whose cloud predates the routes gets the
+// "needs a newer cloud" refusal by name rather than a 404 from a hand-copied path.
+//
+// ⭐ APPROVE IS A COMPARE-AND-SET on `(revision, canonicalHash)`, and with no flags this verb reads
+// the current state and approves exactly what it just read. Hand-copying a hash between two commands
+// is the failure that shape exists to prevent; making the caller do it anyway would reintroduce it.
+import { readFileSync } from "node:fs";
+import { flagBool, flagInt, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { needsNewerCloud } from "./execution.js";
+import { apiClient } from "./transport.js";
+/**
+ * The three account-environment paths this tenant serves.
+ *
+ * ⛔ `propose` and `approve` are NOT looked up by their own last path segment. `routePath`-style
+ * last-segment matching takes the FIRST route ending in that word, so the day a repo-scope
+ * `.../repo-environment/propose` joins the table, a lookup for "propose" could silently return it
+ * and this verb would write a repo's declaration into the account's name. Deriving both from the
+ * account prefix — and then asserting each derived path is really in the table — cannot do that.
+ */
+export function environmentRoutes(doc, cfg) {
+    const base = doc.routes.find((r) => r.method === "GET" && r.path.split("/").filter(Boolean).at(-1) === "account-environment");
+    if (!base) {
+        throw needsNewerCloud('the tenant environment declaration (the contract serves no "account-environment" route)', cfg);
+    }
+    const routes = {
+        read: base.path,
+        propose: `${base.path}/propose`,
+        approve: `${base.path}/approve`,
+    };
+    for (const verb of ["propose", "approve"]) {
+        const served = doc.routes.some((r) => r.method === "POST" && r.path === routes[verb]);
+        if (!served) {
+            throw needsNewerCloud(`the tenant environment declaration's ${verb} route (${routes[verb]} is absent from the contract)`, cfg);
+        }
+    }
+    return routes;
+}
+/** The declaration to send: a JSON file, or stdin. Never invented, and never partially parsed. */
+async function readDeclaration(args, readStdin) {
+    const file = flagString(args, "file");
+    const useStdin = flagBool(args, "stdin");
+    if (file !== undefined && useStdin)
+        throw new UsageError("environment propose takes --file <path> or --stdin, not both");
+    if (file === undefined && !useStdin) {
+        throw new UsageError("environment propose needs --file <path> or --stdin (the declaration is JSON; this verb never invents one)");
+    }
+    const text = file === undefined ? await readStdin() : readFileSync(file, "utf8");
+    if (text.trim() === "")
+        throw new UsageError(`the declaration ${file === undefined ? "on stdin" : `in ${file}`} is empty`);
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new UsageError(`the declaration ${file === undefined ? "on stdin" : `in ${file}`} is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function renderRead(r) {
+    const lines = [];
+    if (r.current === null || r.current === undefined) {
+        lines.push("no tenant environment declaration yet — nothing is delivered to a phase's checkout");
+        return lines;
+    }
+    lines.push(`revision ${r.current.revision} (${r.current.canonicalHash})${r.current.proposedBy ? `, proposed by ${r.current.proposedBy}` : ""}`);
+    lines.push(r.isApproved ? `approved${r.approvedBy ? ` by ${r.approvedBy}` : ""}` : "NOT approved — it is not delivered until someone approves it");
+    lines.push(r.delivered
+        ? `delivered to phases: revision ${r.delivered.revision} (${r.delivered.canonicalHash})`
+        : "delivered to phases: nothing yet");
+    // A name the declaration references that no tenant secret or variable carries RIGHT NOW. A warning,
+    // never a refusal: the secret may be created next, and a repo may supply the name at checkout.
+    const unresolved = r.unresolvedReferences ?? [];
+    if (unresolved.length > 0) {
+        lines.push(`referenced but not set on this tenant yet: ${unresolved.join(", ")} — add them in the app, or a phase that needs one will fail on it`);
+    }
+    return lines;
+}
+function renderState(state, verb) {
+    if (!state)
+        return [`${verb}, but the cloud returned no state`];
+    return [`${verb}: revision ${state.revision} (${state.canonicalHash})`];
+}
+async function readState(api, routes) {
+    const res = await api.getJson(routes.read);
+    return res.body;
+}
+async function approveExact(api, routes, revision, canonicalHash) {
+    const res = await api.postJson(routes.approve, { revision, canonicalHash }, { accept: [404, 409] });
+    return { body: res.body, status: res.status };
+}
+export async function cmdEnvironment(args, ctx, deps = {}) {
+    const [sub = "read", ...extra] = positionals(args);
+    if (extra.length > 0)
+        throw new UsageError(`environment takes one subcommand (got an extra "${extra[0]}")`);
+    if (sub !== "read" && sub !== "propose" && sub !== "approve") {
+        throw new UsageError(`unknown environment subcommand "${sub}": read | propose | approve`);
+    }
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const routes = environmentRoutes(doc, cfg);
+    const api = apiClient(cfg, ctx);
+    if (sub === "read") {
+        const body = await readState(api, routes);
+        if (args.json)
+            ctx.stdout(JSON.stringify(body));
+        else
+            for (const line of renderRead(body))
+                ctx.stdout(line);
+        return 0;
+    }
+    if (sub === "propose") {
+        const declaration = await readDeclaration(args, deps.readStdin ?? readStdin);
+        const expectedRevision = args.flags["expect-revision"] === undefined ? undefined : flagInt(args, "expect-revision", 0);
+        const res = await api.postJson(routes.propose, { declaration, ...(expectedRevision !== undefined ? { expectedRevision } : {}) }, { accept: [400, 404, 409] });
+        const body = res.body;
+        // A refusal is the cloud's own sentence, printed verbatim and exited 1 — never retried, and never
+        // smoothed into a success. `conflict` means someone else moved the declaration; re-read and redo.
+        if (res.status === 409 || res.status === 400 || res.status === 404) {
+            if (args.json)
+                ctx.stdout(JSON.stringify(body));
+            else {
+                ctx.stdout(`refused (${res.status}): ${body.message ?? body.error ?? "no reason given"}`);
+                if (body.reason)
+                    ctx.stdout(`  reason: ${body.reason}`);
+                if (body.currentRevision !== undefined) {
+                    ctx.stdout(`  the declaration is now at revision ${body.currentRevision} — run \`catalyst-skills environment read\` and propose again from that`);
+                }
+            }
+            return 1;
+        }
+        const approveToo = flagBool(args, "approve");
+        if (!args.json)
+            for (const line of renderState(body.state, body.status === "unchanged" ? "unchanged" : `${body.status ?? "proposed"}`))
+                ctx.stdout(line);
+        if (!approveToo) {
+            if (args.json)
+                ctx.stdout(JSON.stringify(body));
+            else if (body.status !== "unchanged")
+                ctx.stdout("not delivered until it is approved: catalyst-skills environment approve");
+            return 0;
+        }
+        // ⭐ Approve exactly what propose just returned. The whole point of the CAS is that the approver
+        // saw the revision they are approving, and nothing here has to be copied by a human or a model.
+        const state = body.state;
+        if (!state) {
+            ctx.stderr("the cloud returned no state to approve — run: catalyst-skills environment read");
+            return 1;
+        }
+        const approved = await approveExact(api, routes, state.revision, state.canonicalHash);
+        if (args.json) {
+            ctx.stdout(JSON.stringify({ propose: body, approve: approved.body }));
+            return approved.status === 200 ? 0 : 1;
+        }
+        return renderApprove(ctx, approved);
+    }
+    // approve — with no flags, read the current state and approve exactly that.
+    const revisionFlag = args.flags.revision === undefined ? undefined : flagInt(args, "revision", 0);
+    const hashFlag = flagString(args, "hash");
+    if ((revisionFlag === undefined) !== (hashFlag === undefined)) {
+        throw new UsageError("environment approve takes --revision and --hash together, or neither (it reads the current one)");
+    }
+    let revision = revisionFlag;
+    let hash = hashFlag;
+    if (revision === undefined || hash === undefined) {
+        const current = (await readState(api, routes)).current;
+        if (current === null || current === undefined) {
+            ctx.stdout("there is no declaration to approve — propose one first: catalyst-skills environment propose --file <path>");
+            return 1;
+        }
+        revision = current.revision;
+        hash = current.canonicalHash;
+    }
+    const approved = await approveExact(api, routes, revision, hash);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(approved.body));
+        return approved.status === 200 ? 0 : 1;
+    }
+    return renderApprove(ctx, approved);
+}
+function renderApprove(ctx, approved) {
+    const { body, status } = approved;
+    if (status === 200 && body.approved) {
+        for (const line of renderState(body.state, "approved"))
+            ctx.stdout(line);
+        ctx.stdout("it is now what a phase's checkout carries");
+        return 0;
+    }
+    ctx.stdout(`refused (${status}): ${body.message ?? body.error ?? "no reason given"}`);
+    if (body.currentRevision !== undefined) {
+        ctx.stdout(`  it is now at revision ${body.currentRevision}${body.currentHash ? ` (${body.currentHash})` : ""} — read it again before approving`);
+    }
+    return 1;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// 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

@@ -0,0 +1,106 @@
+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));
+}