@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/dist/skill-shape.js

@@ -0,0 +1,179 @@
+// 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;
+/** 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,74 @@
+// 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 { PACKAGE_NAME, defaultSkillsDirFor } from "./config.js";
+import { PROVENANCE_MARKER } 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);
+}
+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";
+    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm update -g ${PACKAGE_NAME} (or: npx ${PACKAGE_NAME}@latest login)`;
+}

package/dist/ts-deps-loader.js

@@ -0,0 +1,68 @@
+// 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/");
+}
+/** 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: strip(readFile(fileURLToPath(url)), { mode: "transform", sourceUrl: 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 };
+}

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 ${opts.token}` }, 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: { kind: "token", token: opts.token },
+        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);
+}