@catalyst-cloud/cli 0.8.0

package/dist/skill-shape.js

@@ -0,0 +1,189 @@
+// skill-shape.ts — `validateSkillDir(dir)`: every problem with one skill directory, one string each.
+// The rules are the packaging pipeline's, the plugin shape gate's, the cloud validator's, and this
+// bundle's own content prohibitions, so a skill that passes here installs and publishes everywhere.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+export const PROVENANCE_MARKER = "vendored-from: @catalyst-cloud/catalyst-skills";
+export const MAX_SKILL_LINES = 80;
+export const MAX_REFERENCE_LINES = 150;
+export const MAX_DESCRIPTION_CHARS = 1024;
+/** The first release whose SKILL.md files carry a version on the provenance line. An installed
+ *  skill with the marker and no version predates this release — but that only PROVES staleness
+ *  once a release at or above it has actually been published (CTC-2160 D4). */
+export const FIRST_STAMPED_VERSION = "0.7.0";
+const PROVENANCE_VERSION_RE = new RegExp(`${PROVENANCE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}@(\\S+)`);
+/** The version stamped on a provenance comment line, or null when the line carries none. */
+export function parseProvenanceVersion(line) {
+    const m = PROVENANCE_VERSION_RE.exec(line);
+    return m ? m[1] : null;
+}
+/** Strings no customer-facing skill file may contain. */
+export const FORBIDDEN_CONTENT = [
+    { name: "the maintainer tenant (tenant-0)", re: /tenant-0/ },
+    // The public bundle repository is `coalesce-labs/catalyst-cloud-skills`, whose name CONTAINS the
+    // private repository's, so this one has to end at a word boundary or it bans its own README.
+    { name: "the private catalyst repository (coalesce-labs/catalyst)", re: /coalesce-labs\/catalyst(?![-\w])/ },
+    { name: "the fleet thoughts repository (thoughts/)", re: /thoughts\// },
+    { name: "an internal ticket id", re: /\bC[TL]C-\d+\b/ },
+    { name: "a Linear CLI name (linearis)", re: /linearis/i },
+    { name: "the internal replica tool name (catalyst-replica)", re: /catalyst-replica/ },
+];
+function walk(dir) {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...walk(p));
+        else
+            out.push(p);
+    }
+    return out;
+}
+/** A flat `key: value` parser with block-scalar support for one key spanning indented lines. */
+export function parseFrontmatter(lines) {
+    if (lines[0] !== "---")
+        return null;
+    const fields = {};
+    let closeIndex = -1;
+    let current = null;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === "---") {
+            closeIndex = i;
+            break;
+        }
+        const m = /^([A-Za-z][A-Za-z0-9_-]*):\s?(.*)$/.exec(line);
+        if (m && !/^\s/.test(line)) {
+            current = m[1];
+            const v = m[2].trim();
+            fields[current] = v === "|" || v === ">" || v === "|-" || v === ">-" ? "" : v.replace(/^"(.*)"$/, "$1");
+            continue;
+        }
+        if (current && /^\s+\S/.test(line)) {
+            fields[current] = `${fields[current]}${fields[current] ? " " : ""}${line.trim()}`;
+        }
+    }
+    return closeIndex === -1 ? { fields, closeIndex } : { fields, closeIndex };
+}
+const IMPORT_RE = /(?:from\s+|import\s*\(\s*|require\s*\(\s*)["']([^"']+)["']/g;
+export function validateSkillDir(dir) {
+    const problems = [];
+    const name = basename(dir);
+    if (!existsSync(dir) || !statSync(dir).isDirectory())
+        return [`${dir} is not a directory`];
+    const skillMd = join(dir, "SKILL.md");
+    if (!existsSync(skillMd))
+        return [`${name}: SKILL.md is missing`];
+    const md = readFileSync(skillMd, "utf8");
+    const lines = md.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (lines.length > MAX_SKILL_LINES)
+        problems.push(`${name}: SKILL.md is ${lines.length} lines (max ${MAX_SKILL_LINES})`);
+    const fm = parseFrontmatter(lines);
+    let mutatingFrontmatter = false;
+    if (!fm)
+        problems.push(`${name}: SKILL.md must start with YAML frontmatter (---)`);
+    else {
+        if (fm.closeIndex === -1)
+            problems.push(`${name}: SKILL.md is missing a closing frontmatter fence`);
+        if (!fm.fields.name)
+            problems.push(`${name}: frontmatter is missing "name"`);
+        else if (fm.fields.name !== name)
+            problems.push(`${name}: frontmatter name "${fm.fields.name}" must match the directory`);
+        if (fm.fields.description === undefined || fm.fields.description.trim() === "")
+            problems.push(`${name}: frontmatter is missing "description"`);
+        else if (fm.fields.description.length > MAX_DESCRIPTION_CHARS)
+            problems.push(`${name}: description is ${fm.fields.description.length} characters (max ${MAX_DESCRIPTION_CHARS})`);
+        mutatingFrontmatter = fm.fields["disable-model-invocation"] === "true";
+        if (fm.closeIndex !== -1) {
+            const after = lines[fm.closeIndex + 1] ?? "";
+            if (!(after.startsWith("<!--") && after.includes(PROVENANCE_MARKER))) {
+                problems.push(`${name}: the line after the frontmatter must be the HTML provenance comment containing "${PROVENANCE_MARKER}"`);
+            }
+        }
+    }
+    const refsDir = join(dir, "references");
+    if (existsSync(refsDir)) {
+        const refs = readdirSync(refsDir).filter((f) => f.endsWith(".md")).sort();
+        if (refs.length === 0)
+            problems.push(`${name}: references/ is empty`);
+        const table = /^## Load on demand\s*$/m.test(md);
+        if (refs.length > 0 && !table)
+            problems.push(`${name}: SKILL.md has no "## Load on demand" table`);
+        for (const f of refs) {
+            const body = readFileSync(join(refsDir, f), "utf8").split("\n");
+            if (body.at(-1) === "")
+                body.pop();
+            if (body.length > MAX_REFERENCE_LINES)
+                problems.push(`${name}: references/${f} is ${body.length} lines (max ${MAX_REFERENCE_LINES})`);
+            if (!md.includes(`references/${f}`))
+                problems.push(`${name}: references/${f} is not linked from SKILL.md by its literal path`);
+        }
+    }
+    const scriptsDir = join(dir, "scripts");
+    if (existsSync(scriptsDir)) {
+        for (const p of walk(scriptsDir).filter((f) => f.endsWith(".mjs"))) {
+            const rel = relative(dir, p);
+            const src = readFileSync(p, "utf8");
+            if (!src.startsWith("#!/usr/bin/env node"))
+                problems.push(`${name}: ${rel} must start with #!/usr/bin/env node`);
+            if (!src.includes("--help"))
+                problems.push(`${name}: ${rel} has no --help`);
+            for (const m of src.matchAll(IMPORT_RE)) {
+                const spec = m[1];
+                if (!(spec.startsWith("node:") || spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/"))) {
+                    problems.push(`${name}: ${rel} imports "${spec}"; scripts may import only node: modules and relative files`);
+                }
+            }
+        }
+    }
+    const portability = join(dir, "agents", "portability.yaml");
+    const openai = join(dir, "agents", "openai.yaml");
+    let mutating = false;
+    let implicitFalse = false;
+    if (!existsSync(portability))
+        problems.push(`${name}: agents/portability.yaml is missing`);
+    else {
+        const y = readFileSync(portability, "utf8");
+        if (!/^effects:\s*.*$/m.test(y))
+            problems.push(`${name}: agents/portability.yaml does not declare "effects"`);
+        if (!/^exposure:\s*\[\s*"?catalog"?\s*\]\s*$/m.test(y))
+            problems.push(`${name}: agents/portability.yaml must declare exposure: [catalog]`);
+        mutating = /^mutating:\s*true\s*$/m.test(y);
+    }
+    if (!existsSync(openai))
+        problems.push(`${name}: agents/openai.yaml is missing`);
+    else {
+        const y = readFileSync(openai, "utf8");
+        if (!/^policy:\s*$/m.test(y))
+            problems.push(`${name}: agents/openai.yaml has no "policy:" block`);
+        if (!/allow_implicit_invocation:\s*(true|false)/.test(y))
+            problems.push(`${name}: agents/openai.yaml does not set policy.allow_implicit_invocation`);
+        implicitFalse = /allow_implicit_invocation:\s*false/.test(y);
+    }
+    if (mutating || mutatingFrontmatter || implicitFalse) {
+        if (!mutating)
+            problems.push(`${name}: disable-model-invocation / allow_implicit_invocation: false are set but agents/portability.yaml lacks mutating: true`);
+        if (!mutatingFrontmatter)
+            problems.push(`${name}: is mutating but SKILL.md does not set disable-model-invocation: true`);
+        if (!implicitFalse)
+            problems.push(`${name}: is mutating but agents/openai.yaml does not set policy.allow_implicit_invocation: false`);
+    }
+    for (const p of walk(dir)) {
+        const rel = relative(dir, p);
+        if (/\.log$/i.test(rel))
+            problems.push(`${name}: ${rel} is a log file; no *.log may ship in a skill`);
+        let text;
+        try {
+            text = readFileSync(p, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const f of FORBIDDEN_CONTENT)
+            if (f.re.test(text))
+                problems.push(`${name}: ${rel} mentions ${f.name}`);
+    }
+    return problems;
+}

package/dist/skills.js

@@ -0,0 +1,129 @@
+// skills.ts — copying the bundled skills into the user's skills directory, and the one-line update
+// notice a new version prints on its next session.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defaultSkillsDirFor, upgradeCommand } from "./config.js";
+import { semverOlder } from "./semver.js";
+import { PROVENANCE_MARKER, parseFrontmatter, parseProvenanceVersion } from "./skill-shape.js";
+export function skillsSourceDir() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+/**
+ * Copy every `skills/<name>/` that has a SKILL.md. A target directory whose SKILL.md lacks the
+ * provenance marker was not installed by this package and is skipped unless `force`.
+ *
+ * `onlyExisting` is the update path: it refreshes copies this package already made and creates
+ * none. That is what keeps the update notice from planting a second copy of every skill beside a
+ * set the customer's agent installed as a plugin.
+ */
+export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
+    const result = { installed: [], skipped: [] };
+    if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
+        throw new Error(`${targetDir} is not a directory`);
+    }
+    const names = readdirSync(sourceDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    for (const name of names) {
+        const src = join(sourceDir, name);
+        if (!existsSync(join(src, "SKILL.md")))
+            continue;
+        const dst = join(targetDir, name);
+        const existingMd = join(dst, "SKILL.md");
+        if (opts.onlyExisting && !existsSync(existingMd))
+            continue;
+        if (existsSync(existingMd) && !opts.force) {
+            const existing = readFileSync(existingMd, "utf8");
+            if (!existing.includes(PROVENANCE_MARKER)) {
+                result.skipped.push({ name, reason: "foreign-skill-dir" });
+                continue;
+            }
+        }
+        mkdirSync(dst, { recursive: true });
+        cpSync(src, dst, { recursive: true });
+        result.installed.push(name);
+    }
+    return result;
+}
+export function resolveSkillsDir(args, ctx, cfg) {
+    return args.skillsDir ?? ctx.env.CATALYST_SKILLS_CLAUDE_DIR ?? cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
+}
+/** The provenance comment in a SKILL.md, wherever that file's frontmatter actually ends.
+ *
+ *  `validateSkillDir` requires the comment on the line right after the closing fence and caps the
+ *  FILE's length, never the frontmatter's — so a fixed head window was an unpinned assumption, and a
+ *  skill with a long wrapped `description` fell past it and became invisible: no version and not even
+ *  counted as unstamped, silently dropping out of the staleness check. A file whose shape is off
+ *  falls back to the whole-file scan `installSkills` already uses to recognise our own copies. */
+function provenanceLine(text) {
+    const lines = text.split("\n");
+    const fm = parseFrontmatter(lines);
+    if (fm && fm.closeIndex !== -1) {
+        const after = lines[fm.closeIndex + 1];
+        if (after?.includes(PROVENANCE_MARKER))
+            return after;
+    }
+    return lines.find((l) => l.includes(PROVENANCE_MARKER));
+}
+/** What skill-bundle version is actually sitting in `dir`. Reads only the provenance comment; a
+ *  directory this package did not write (no marker) is ignored, not counted as stale, and a name
+ *  that is not installed at all is skipped. */
+export function installedBundleVersion(dir, names) {
+    let version = null;
+    let skill = null;
+    const unstamped = [];
+    for (const name of names) {
+        const skillMd = join(dir, name, "SKILL.md");
+        if (!existsSync(skillMd))
+            continue;
+        let text;
+        try {
+            text = readFileSync(skillMd, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const line = provenanceLine(text);
+        if (line === undefined)
+            continue;
+        const stamp = parseProvenanceVersion(line);
+        if (stamp === null) {
+            unstamped.push(name);
+            continue;
+        }
+        if (version === null || semverOlder(stamp, version)) {
+            version = stamp;
+            skill = name;
+        }
+    }
+    return { version, skill, unstamped };
+}
+export function parseChangelogEntry(changelog, version) {
+    const lines = changelog.split("\n");
+    const heading = `## ${version}`;
+    const start = lines.findIndex((l) => l.trim() === heading);
+    if (start === -1)
+        return null;
+    for (const line of lines.slice(start + 1)) {
+        const t = line.trim();
+        if (t === "")
+            continue;
+        if (t.startsWith("#"))
+            break;
+        return t;
+    }
+    return null;
+}
+export function readChangelog() {
+    return readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");
+}
+export function updateNoticeLine(previous, current, entry) {
+    const summary = entry ?? "see CHANGELOG.md";
+    // `npm update -g` treats a global install as a caret range, and a caret below 1.0.0 never moves a
+    // minor — so it never crosses 0.2.x → 0.3.0. Pin @latest via `npm install`, THEN re-run login: the
+    // install alone does not rewrite customer.json.cliPath, so the skill helpers would keep spawning the
+    // stale recorded bundle and repeat this notice forever; the new global bin records its own path.
+    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: ${upgradeCommand()}`;
+}

package/dist/transport.js

@@ -0,0 +1,205 @@
+import { normalizeBaseUrl } from "./config.js";
+import { CliError, MeError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+export const REQUEST_TIMEOUT_MS = 15_000;
+export class ApiClient {
+    baseUrl;
+    credential;
+    fetchImpl;
+    constructor(baseUrl, 
+    /** Resolves the current bearer FRESH per request — a personal key verbatim, or the OAuth access
+     *  token refreshed within 60s of expiry (CTC-2112). Never captured once. */
+    credential, fetchImpl) {
+        this.baseUrl = baseUrl;
+        this.credential = credential;
+        this.fetchImpl = fetchImpl;
+    }
+    /** `path` is absolute under the origin (e.g. `/api/v1/issues`). */
+    url(path, query) {
+        const u = new URL(`${normalizeBaseUrl(this.baseUrl)}${path}`);
+        for (const [k, v] of Object.entries(query ?? {}))
+            if (v !== undefined)
+                u.searchParams.set(k, String(v));
+        return u.toString();
+    }
+    async getJson(path, opts = {}) {
+        const headers = {
+            authorization: `Bearer ${await this.credential()}`,
+            accept: "application/json",
+        };
+        if (opts.etag)
+            headers["if-none-match"] = opts.etag;
+        const url = this.url(path, opts.query);
+        const res = await this.send(url, { method: "GET", headers });
+        if (opts.accept?.includes(res.status)) {
+            return { status: res.status, body: undefined, headers: res.headers };
+        }
+        await this.refuseIfNotOk(res, `GET ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
+    }
+    /**
+     * A GET whose success body is NDJSON — one JSON object per line, the shape `streamNdjson` sends.
+     *
+     * ⛔ `/changes` and `/snapshot` ANSWER NDJSON ON 200 AND JSON ON A REFUSAL, so a caller that only
+     * has `getJson` reads every real success as "returned a non-JSON body" while its refusals parse
+     * perfectly. That asymmetry is why `query changes` looked like it worked: nothing reached a 200.
+     * `accept` behaves as it does on `getJson` — those statuses come back with `rows: []` for the
+     * caller to branch on, and their (JSON) body is deliberately not parsed here.
+     */
+    async getNdjson(path, opts = {}) {
+        const url = this.url(path, opts.query);
+        const res = await this.send(url, {
+            method: "GET",
+            headers: { authorization: `Bearer ${await this.credential()}`, accept: "application/x-ndjson, application/json" },
+        });
+        if (opts.accept?.includes(res.status))
+            return { status: res.status, body: [], headers: res.headers };
+        await this.refuseIfNotOk(res, `GET ${path}`);
+        const text = await res.text();
+        const rows = [];
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            try {
+                rows.push(JSON.parse(trimmed));
+            }
+            catch {
+                throw new MeError(`GET ${path} returned a line that is not JSON: ${trimmed.slice(0, 120)}`, "shape");
+            }
+        }
+        return { status: res.status, body: rows, headers: res.headers };
+    }
+    /** `opts.accept` lists non-2xx statuses returned to the caller with their JSON body instead of thrown
+     *  — the release route answers a refusal as 409 with the refusals the caller has to print. */
+    async postJson(path, body, opts = {}) {
+        const url = this.url(path);
+        const res = await this.send(url, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${await this.credential()}`,
+                accept: "application/json",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `POST ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
+    }
+    async send(url, init) {
+        try {
+            return await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        }
+        catch (err) {
+            throw new MeError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+        }
+    }
+    async parseBody(res, what) {
+        try {
+            return (await res.json());
+        }
+        catch {
+            throw new MeError(`${what} returned a non-JSON body`, "shape");
+        }
+    }
+    async refuseIfNotOk(res, what) {
+        if (res.ok)
+            return;
+        let reason = "";
+        let raw = "";
+        try {
+            raw = await res.text();
+            const body = JSON.parse(raw);
+            reason = body.reason ?? body.error ?? body.message ?? "";
+        }
+        catch {
+            reason = raw.slice(0, 200);
+        }
+        if (res.status === 401) {
+            throw new CliError(`${what} failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again`, "unauthorized", 2, 401);
+        }
+        if (res.status === 403) {
+            throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a route that acts as a host (claiming work, publishing artifacts) needs the tenant's account key; every read and write a person makes takes your personal key`, "forbidden", 2, 403);
+        }
+        if (res.status === 429) {
+            const retryAfter = res.headers.get("retry-after");
+            const budget = /budget/i.test(raw) || /budget/i.test(reason);
+            throw new CliError(`${what} refused (429)${budget ? ": the per-host daily write budget is spent" : ": rate limited"}${reason ? ` — ${reason}` : ""}${retryAfter ? ` — retry after ${retryAfter}s` : ""}`, budget ? "budget" : "rate-limited", 2, 429);
+        }
+        throw new CliError(`${what} failed (${res.status})${reason ? `: ${reason}` : ""}`, "http", 2, res.status);
+    }
+}
+/** Build the authenticated client for a config: the bearer resolves through {@link bearerFor}, so a
+ *  key config sends the key and an OAuth config sends a freshly-refreshed access token per request. */
+export function apiClient(cfg, ctx) {
+    return new ApiClient(cfg.baseUrl, () => bearerFor(ctx, cfg), ctx.fetch);
+}
+/** GET /api/v1/me — how a key learns its own tenant. Unchanged contract from 0.1. */
+export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const url = `${normalizeBaseUrl(baseUrl)}/api/v1/me`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${key}`, accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        throw new MeError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+    if (!res.ok) {
+        let reason;
+        try {
+            const body = (await res.json());
+            reason = body.reason ?? body.error ?? "";
+        }
+        catch {
+            reason = "";
+        }
+        const detail = res.status === 401
+            ? "credential not accepted — mint a personal key at Settings → API keys and log in again"
+            : reason || `HTTP ${res.status}`;
+        throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new MeError("GET /me returned a non-JSON body", "shape");
+    }
+    if (typeof body.account !== "string" ||
+        typeof body.slug !== "string" ||
+        typeof body.name !== "string" ||
+        (body.permissions !== null && !Array.isArray(body.permissions)) ||
+        (body.principal !== "service" && body.principal !== "session")) {
+        throw new MeError("GET /me returned an unexpected shape", "shape");
+    }
+    const user = parseMeUser(body.user);
+    return {
+        account: body.account,
+        slug: body.slug,
+        name: body.name,
+        permissions: body.permissions,
+        principal: body.principal,
+        ...(user ? { user } : {}),
+    };
+}
+/** The `user` block a personal key gets from /me. Absent (undefined) is "a host key, no person";
+ *  present-but-malformed is a shape error like any other field, never silently dropped. */
+function parseMeUser(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "object" || raw === null)
+        throw new MeError("GET /me returned an unexpected user shape", "shape");
+    const u = raw;
+    if (typeof u.id !== "string" ||
+        typeof u.label !== "string" ||
+        (u.email !== null && typeof u.email !== "string") ||
+        (u.role !== "owner" && u.role !== "admin" && u.role !== "member") ||
+        (u.linearUserId !== null && typeof u.linearUserId !== "string")) {
+        throw new MeError("GET /me returned an unexpected user shape", "shape");
+    }
+    return { id: u.id, label: u.label, email: u.email, role: u.role, linearUserId: u.linearUserId };
+}

package/dist/ts-deps-loader.js

@@ -0,0 +1,113 @@
+// ts-deps-loader.ts — lets plain Node load the Catalyst Cloud SDK.
+//
+// `@catalyst-cloud/sdk` depends on `@catalyst-cloud/schema` and `@catalyst-cloud/replicate`, both of
+// which are published as TypeScript source (`exports: "./src/index.ts"`). Node refuses to strip types
+// for files under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so a bare
+// `import("@catalyst-cloud/sdk/node")` fails on every Node version. Bun and vitest transpile anywhere,
+// which is why the SDK's other consumers never see this.
+//
+// This module installs two synchronous module hooks (Node 22.15+): a `load` hook that strips types
+// from any `.ts` file under node_modules with Node's own `stripTypeScriptTypes`, and a `resolve` hook
+// that maps a failed `./x.js` relative import onto `./x.ts` (the TS-ESM suffix convention those
+// packages use). Nothing outside node_modules is touched, and the hooks are installed once.
+import * as nodeModule from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+let installed = false;
+function inDeps(url) {
+    return typeof url === "string" && url.startsWith("file:") && url.includes("/node_modules/");
+}
+/** Both modes this runtime offers refused the source. Naming the file and both refusals beats
+ *  surfacing Node's raw `options.mode` message, which names the mode Node rejected rather than the
+ *  syntax in the SOURCE that made both modes fail. */
+export class StripModeError extends Error {
+    sourceUrl;
+    refusals;
+    constructor(sourceUrl, refusals) {
+        super(`${sourceUrl}: could not be type-stripped by any mode this runtime offers. This usually means ` +
+            `the source uses TypeScript syntax with runtime semantics (an enum, a runtime namespace, a ` +
+            `parameter property, or \`export =\`) that Node's type-stripping can never erase, on a ` +
+            `runtime that also refuses \`transform\`. ` +
+            `strip refused: ${refusals.strip} | transform refused: ${refusals.transform}`);
+        this.name = "StripModeError";
+        this.sourceUrl = sourceUrl;
+        this.refusals = refusals;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** CTC-2483 — strip types preferring the one mode EVERY supported Node accepts.
+ *
+ *  ⭐ `strip` is always tried first, and that ordering is the whole fix. Node 26's
+ *  `stripTypeScriptTypes` accepts only `{ mode: "strip" }` and throws ERR_INVALID_ARG_VALUE for
+ *  `"transform"`, so a loader that reaches for `transform` first dies there before it ever learns
+ *  whether `strip` would have worked. But `strip` is not a weaker `transform`: it REFUSES
+ *  TypeScript syntax with runtime semantics (enums, runtime namespaces, parameter properties,
+ *  `export =`) that `transform` erases, so `transform` stays reachable as a fallback on Node 22-25
+ *  for sources that need it. */
+export function stripPreferringStrip(strip, source, sourceUrl) {
+    try {
+        return strip(source, { mode: "strip", sourceUrl });
+    }
+    catch (stripError) {
+        try {
+            return strip(source, { mode: "transform", sourceUrl });
+        }
+        catch (transformError) {
+            throw new StripModeError(sourceUrl, {
+                strip: messageOf(stripError),
+                transform: messageOf(transformError),
+            });
+        }
+    }
+}
+/** Build the hook pair over a strip function. Pure, so a test can drive it with fake `next`s. */
+export function makeHooks(strip, fileExists = existsSync, readFile = (p) => readFileSync(p, "utf8")) {
+    return {
+        resolve(specifier, context, next) {
+            try {
+                return next(specifier, context);
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === "ERR_MODULE_NOT_FOUND" && specifier.startsWith(".") && inDeps(context.parentURL)) {
+                    const base = specifier.endsWith(".js") ? specifier.slice(0, -3) : specifier;
+                    const alt = new URL(`${base}.ts`, context.parentURL);
+                    if (fileExists(fileURLToPath(alt)))
+                        return { url: alt.href, format: "module", shortCircuit: true };
+                }
+                throw err;
+            }
+        },
+        load(url, context, next) {
+            if (inDeps(url) && url.endsWith(".ts")) {
+                return { format: "module", shortCircuit: true, source: stripPreferringStrip(strip, readFile(fileURLToPath(url)), url) };
+            }
+            return next(url, context);
+        },
+    };
+}
+/** Install the hooks once. Returns whether they are installed and, if not, why. */
+export function installTsDepsLoader(mod = nodeModule) {
+    if (installed)
+        return { installed: true };
+    if (typeof mod.registerHooks !== "function") {
+        return { installed: false, reason: `node:module has no registerHooks on Node ${process.version}; Node 22.15 or newer is required` };
+    }
+    if (typeof mod.stripTypeScriptTypes !== "function") {
+        return { installed: false, reason: `node:module has no stripTypeScriptTypes on Node ${process.version}; Node 22.13 or newer is required` };
+    }
+    // Node prints "stripTypeScriptTypes is an experimental feature" once on first use; that line would
+    // land on stderr of every SDK-loading verb, so the one warning this loader provokes is dropped.
+    const emit = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...rest) => {
+        const text = typeof warning === "string" ? warning : warning instanceof Error ? warning.message : "";
+        if (text.includes("stripTypeScriptTypes"))
+            return;
+        emit(warning, ...rest);
+    });
+    mod.registerHooks(makeHooks(mod.stripTypeScriptTypes));
+    installed = true;
+    return { installed: true };
+}