@catalyst-cloud/catalyst-skills 0.1.0 → 0.2.0

package/dist/query.js

@@ -0,0 +1,187 @@
+// query.ts — `query issues|issue|pulls|pull|projects|cycles|search|changes`: the replica when it is
+// fresh, else the API, with the source named on stderr every time. Output shape is the read-model
+// view either way. `pull`, `cycles`, `search` and `changes` are API-only (the SDK wraps no view for
+// them and the read-model package is not a declared dependency of this bundle).
+import { flagInt, flagString, positionals } from "./args.js";
+import { requireConfig, replicaDbPath } from "./config.js";
+import { UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+import { engineFor, replicaStatus } from "./replica.js";
+import { loadSdk } from "./sdk.js";
+const REPLICA_CAPABLE = new Set(["issues", "issue", "pulls", "projects"]);
+export async function cmdQuery(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (!sub)
+        throw new UsageError("query needs a subcommand: issues | issue <id> | pulls | pull <id> | projects | cycles | search <terms> | changes --since <n>");
+    const cfg = requireConfig(ctx);
+    const filters = {
+        team: flagString(args, "team"),
+        project: flagString(args, "project"),
+        state: flagString(args, "state"),
+        limit: flagInt(args, "limit", 50),
+    };
+    const forced = flagString(args, "source");
+    if (forced && forced !== "replica" && forced !== "api")
+        throw new UsageError("--source must be replica or api");
+    const status = replicaStatus(ctx, cfg);
+    let source;
+    let why;
+    if (!REPLICA_CAPABLE.has(sub)) {
+        source = "api";
+        why = `${sub} is api-only`;
+    }
+    else if (forced) {
+        source = forced;
+        why = `--source ${forced}`;
+    }
+    else if (status.verdict === "fresh") {
+        source = "replica";
+        why = `cursor ${status.cursor}`;
+    }
+    else {
+        source = "api";
+        why = `replica ${status.verdict}`;
+    }
+    ctx.stderr(source === "replica" ? `source: replica (${why})` : `source: api (${why})`);
+    let result;
+    if (source === "replica") {
+        if (status.verdict === "absent" || status.verdict === "not-configured") {
+            throw new UsageError(`--source replica but the replica is ${status.verdict}`);
+        }
+        result = await fromReplica(ctx, cfg, sub, rest, filters, deps);
+    }
+    else {
+        result = await fromApi(ctx, cfg, sub, rest, filters, args);
+    }
+    if (result === null) {
+        ctx.stderr(`${sub} ${rest[0] ?? ""}: not found`);
+        return 1;
+    }
+    printResult(ctx, args, sub, result);
+    return 0;
+}
+async function fromReplica(ctx, cfg, sub, rest, f, deps) {
+    const sdk = await loadSdk();
+    const dbPath = replicaDbPath(cfg, ctx.home);
+    const engine = await engineFor(sdk, dbPath, ctx, { ...deps.engineDeps, readonly: true });
+    const replica = await sdk.CatalystReplica.openReadOnly({ dbPath, engine, log: () => { } });
+    try {
+        switch (sub) {
+            case "issues": {
+                const rows = replica.issues({ limit: Math.max(f.limit, 200) });
+                return applyFilters(rows, f).slice(0, f.limit);
+            }
+            case "issue":
+                return replica.issue(needArg(rest, "issue <identifier>"));
+            case "pulls":
+                return replica.pulls({ limit: f.limit });
+            case "projects":
+                return applyFilters(replica.projects({ limit: Math.max(f.limit, 200) }), { limit: f.limit, state: f.state }).slice(0, f.limit);
+            default:
+                throw new UsageError(`${sub} is not readable from the replica`);
+        }
+    }
+    finally {
+        await replica.close();
+    }
+}
+async function fromApi(ctx, cfg, sub, rest, f, args) {
+    const api = apiClient(cfg, ctx);
+    const common = { team: f.team, project: f.project, state: f.state, limit: f.limit };
+    switch (sub) {
+        case "issues": {
+            const res = await api.getJson("/api/v1/issues", { query: common });
+            return applyFilters(rowsOf(res.body), f).slice(0, f.limit);
+        }
+        case "issue": {
+            const id = needArg(rest, "issue <identifier>");
+            const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(id)}`, { accept: [404] });
+            return res.status === 404 ? null : res.body;
+        }
+        case "pulls": {
+            const res = await api.getJson("/api/v1/pulls", { query: { limit: f.limit, ticket: flagString(args, "ticket") } });
+            return rowsOf(res.body).slice(0, f.limit);
+        }
+        case "pull": {
+            const id = needArg(rest, "pull <node id>");
+            const res = await api.getJson(`/api/v1/pulls/${encodeURIComponent(id)}`, { accept: [404] });
+            return res.status === 404 ? null : res.body;
+        }
+        case "projects": {
+            const res = await api.getJson("/api/v1/projects", { query: { limit: f.limit } });
+            return rowsOf(res.body).slice(0, f.limit);
+        }
+        case "cycles": {
+            const res = await api.getJson("/api/v1/cycles", { query: { team: f.team, limit: f.limit } });
+            return rowsOf(res.body);
+        }
+        case "search": {
+            const q = rest.join(" ").trim();
+            if (!q)
+                throw new UsageError("search needs terms: query search <terms>");
+            const res = await api.getJson("/api/v1/search", { query: { q, limit: f.limit } });
+            return rowsOf(res.body);
+        }
+        case "changes": {
+            const since = flagString(args, "since");
+            if (since === undefined)
+                throw new UsageError("changes needs --since <cursor>");
+            const res = await api.getJson("/api/v1/changes", { query: { since, limit: f.limit } });
+            return res.body;
+        }
+        default:
+            throw new UsageError(`unknown query subcommand: ${sub}`);
+    }
+}
+function needArg(rest, usage) {
+    const v = rest[0];
+    if (!v)
+        throw new UsageError(`query ${usage}`);
+    return v;
+}
+/** The API answers a list route with either a bare array or `{rows|items|issues|...: []}`. */
+export function rowsOf(body) {
+    if (Array.isArray(body))
+        return body;
+    if (body && typeof body === "object") {
+        for (const key of ["rows", "items", "issues", "pulls", "projects", "cycles", "results", "changes", "data"]) {
+            const v = body[key];
+            if (Array.isArray(v))
+                return v;
+        }
+    }
+    return [];
+}
+export function applyFilters(rows, f) {
+    return rows.filter((r) => {
+        if (f.team && !(String(r.identifier ?? "").toUpperCase().startsWith(`${f.team.toUpperCase()}-`) || r.team_id === f.team || r.team_key === f.team))
+            return false;
+        if (f.project && r.project_id !== f.project)
+            return false;
+        if (f.state && String(r.state ?? "").toLowerCase() !== f.state.toLowerCase())
+            return false;
+        return true;
+    });
+}
+function printResult(ctx, args, sub, result) {
+    if (args.json || !Array.isArray(result)) {
+        ctx.stdout(JSON.stringify(result, null, args.json ? 0 : 2));
+        return;
+    }
+    for (const row of result)
+        ctx.stdout(summaryLine(sub, row));
+}
+export function summaryLine(sub, r) {
+    switch (sub) {
+        case "issues":
+            return `${r.identifier ?? r.id}  ${r.state ?? "?"}  ${r.title ?? ""}${r.assignee_name || r.assignee ? `  (${r.assignee_name ?? r.assignee})` : ""}`;
+        case "pulls":
+            return `#${r.number ?? "?"}  ${r.state ?? "?"}${r.merged ? " merged" : ""}  ${r.title ?? ""}  [${r.node_id ?? ""}]`;
+        case "projects":
+            return `${r.id}  ${r.state ?? "?"}  ${r.name ?? ""}`;
+        case "cycles":
+            return `cycle ${r.number ?? r.id}  ${r.name ?? ""}  ${r.starts_at ?? ""} → ${r.ends_at ?? ""}`;
+        default:
+            return JSON.stringify(r);
+    }
+}

package/dist/ready.js

@@ -0,0 +1,123 @@
+// ready.ts — `ready`: the machine checks plus the tenant's own readiness vector from the contract,
+// one verdict, and per failure the fix and who can apply it. The replica is optional, so its absence
+// is a note, never a failure; the SDK loading IS a check, because the replica and watch need it.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defaultSkillsDirFor, loadConfig, readManifest } from "./config.js";
+import { contractVersionInRange, readContractCache } from "./contract.js";
+import { CliError } from "./errors.js";
+import { replicaStatus, statusLine } from "./replica.js";
+import { loadSdk } from "./sdk.js";
+function whoCanAnswer(doc) {
+    const roles = doc.humans.map((h) => `${h.role} ${h.linearUserId}`);
+    return roles.length ? roles.join(", ") : "a tenant owner or admin (none resolved on the contract)";
+}
+export async function readyReport(ctx, deps) {
+    const checks = [];
+    const nodeMajor = deps.nodeMajor ?? Number(process.versions.node.split(".")[0]);
+    checks.push(nodeMajor >= 22
+        ? { id: "node", ok: true, line: `node: ${nodeMajor} (22 or newer required)` }
+        : { id: "node", ok: false, line: `node: ${nodeMajor} is too old`, fix: "install Node 22 or newer (the SDK's built-in SQLite engine needs it)", who: "you" });
+    let cfg = null;
+    try {
+        cfg = loadConfig(ctx.home);
+        checks.push(cfg
+            ? { id: "config", ok: true, line: `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}` }
+            : { id: "config", ok: false, line: "config: not connected", fix: "CATALYST_CLOUD_TOKEN=<account key> npx @catalyst-cloud/catalyst-skills login", who: "you (the key comes from your tenant admin)" });
+    }
+    catch (err) {
+        checks.push({ id: "config", ok: false, line: `config: ${err instanceof CliError ? err.message : String(err)}`, fix: "re-run login to rewrite it", who: "you" });
+    }
+    const cache = readContractCache(ctx.home);
+    const range = readManifest().tenantContractRange;
+    if (!cache) {
+        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst-skills contract --refresh (needs an account key, not a workstation key)", who: "you" });
+    }
+    else if (contractVersionInRange(cache.contractVersion, range) !== true) {
+        checks.push({ id: "contract", ok: false, line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`, fix: "npm update -g @catalyst-cloud/catalyst-skills", who: "you" });
+    }
+    else {
+        checks.push({ id: "contract", ok: true, line: `contract: ${cache.contractVersion} cached ${cache.fetchedAt} (range ${range})` });
+    }
+    if (cfg) {
+        checks.push(cfg.cliPath && existsSync(cfg.cliPath)
+            ? { id: "cliPath", ok: true, line: `cliPath: ${cfg.cliPath}` }
+            : { id: "cliPath", ok: false, line: `cliPath: ${cfg.cliPath ? `${cfg.cliPath} does not exist` : "not recorded"}`, fix: "re-run login so the skill scripts can find this CLI", who: "you" });
+    }
+    // The skills are installed by the customer's own agent (a plugin, or `npx skills add`), so an
+    // empty copy directory is the normal case and must not read as NOT READY. A PARTIAL copy is the
+    // one broken state this check can see: half a set this package put there and never finished.
+    const skillsDir = cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
+    const present = deps.skillNames.filter((n) => existsSync(join(skillsDir, n, "SKILL.md")));
+    const missing = deps.skillNames.filter((n) => !present.includes(n));
+    if (present.length === 0) {
+        checks.push({ id: "skills", ok: true, note: true, line: `skills: none copied to ${skillsDir} — you are reading one, so your agent installed them its own way` });
+    }
+    else if (missing.length === 0) {
+        checks.push({ id: "skills", ok: true, line: `skills: all ${deps.skillNames.length} present in ${skillsDir}` });
+    }
+    else {
+        checks.push({ id: "skills", ok: false, line: `skills: ${present.length} of ${deps.skillNames.length} in ${skillsDir}, missing ${missing.join(", ")}`, fix: "catalyst-skills install", who: "you" });
+    }
+    try {
+        await (deps.loadSdk ?? loadSdk)();
+        checks.push({ id: "sdk", ok: true, line: "sdk: loads (replica and watch are available)" });
+    }
+    catch (err) {
+        checks.push({ id: "sdk", ok: false, line: `sdk: ${err instanceof Error ? err.message : String(err)}`, fix: "run under Node 22.15 or newer (or bun); every read still works through the API meanwhile", who: "you" });
+    }
+    const replica = replicaStatus(ctx, cfg);
+    checks.push({ id: "replica", ok: replica.verdict === "fresh", note: true, line: statusLine(replica) });
+    if (cache) {
+        const doc = cache.doc;
+        const who = whoCanAnswer(doc);
+        for (const team of doc.teams) {
+            const label = team.key ?? team.id;
+            if (team.readiness.status === "unchecked") {
+                checks.push({ id: `team:${label}`, ok: true, note: true, line: `team ${label}: readiness not checked yet` });
+                continue;
+            }
+            const bad = team.readiness.checks.filter((c) => c.state !== "pass");
+            if (bad.length === 0 && team.readiness.status === "ready") {
+                checks.push({ id: `team:${label}`, ok: true, line: `team ${label}: ready` });
+                continue;
+            }
+            for (const c of bad) {
+                const meta = doc.readinessChecks.find((r) => r.id === c.id);
+                const needsAnswer = meta?.needsAnswer ?? true;
+                checks.push({
+                    id: `team:${label}:${c.id}`,
+                    ok: !needsAnswer && c.state !== "fail",
+                    note: !needsAnswer,
+                    line: `team ${label}: ${c.id} is ${c.state}${c.reason ? ` (${c.reason}${c.count !== undefined ? ` ×${c.count}` : ""})` : ""}${meta ? `, ${meta.severity}` : ""}`,
+                    fix: `open settings for team ${label} and resolve ${c.id}`,
+                    who: needsAnswer ? who : "nobody yet; it is informational",
+                });
+            }
+            if (bad.length === 0 && team.readiness.status !== "ready") {
+                checks.push({ id: `team:${label}`, ok: team.readiness.status !== "blocked", note: team.readiness.status === "degraded", line: `team ${label}: ${team.readiness.status}`, fix: `open settings for team ${label}`, who });
+            }
+        }
+    }
+    const ready = checks.every((c) => c.ok || c.note);
+    return { ready, checks };
+}
+export async function cmdReady(args, ctx, deps) {
+    const report = await readyReport(ctx, deps);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(report));
+    }
+    else {
+        for (const c of report.checks) {
+            ctx.stdout(`${c.note ? "note" : c.ok ? "ok " : "FAIL"}  ${c.line}`);
+            if (!c.ok && !c.note) {
+                if (c.fix)
+                    ctx.stdout(`      fix: ${c.fix}`);
+                if (c.who)
+                    ctx.stdout(`      who: ${c.who}`);
+            }
+        }
+        ctx.stdout(report.ready ? "READY" : "NOT READY");
+    }
+    return report.ready ? 0 : 1;
+}

package/dist/replica.js

@@ -0,0 +1,318 @@
+// replica.ts — the optional local replica: `replica start|stop|status|sql|schema`.
+//
+// `status` is the check every skill runs first and it needs no network and no SDK: the pidfile, the
+// writer-lock heartbeat, and the `sync_meta.cursor` row (read through node:sqlite read-only). Exit
+// 0 fresh, 1 present but stale, 2 not configured, 3 absent. `--probe` adds the one network call.
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { createRequire } from "node:module";
+import { flagBool, flagInt, flagString, positionals } from "./args.js";
+import { apiBase, loadConfig, replicaDbPath } from "./config.js";
+import { detachSelf } from "./detach.js";
+import { CliError, UsageError } from "./errors.js";
+import { apiClient } from "./http.js";
+import { loadSdk } from "./sdk.js";
+export const DEFAULT_STALE_MS = 15_000;
+export function pidfilePath(dbPath) {
+    return `${dbPath}.pid`;
+}
+export function lockPath(dbPath) {
+    return `${dbPath}.writer.lock`;
+}
+export function pidAlive(pid) {
+    if (pid === null || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+export function readPidfile(dbPath) {
+    const p = pidfilePath(dbPath);
+    if (!existsSync(p))
+        return null;
+    const n = Number(readFileSync(p, "utf8").trim());
+    return Number.isInteger(n) ? n : null;
+}
+function readLock(dbPath) {
+    try {
+        const rec = JSON.parse(readFileSync(lockPath(dbPath), "utf8"));
+        if (typeof rec.pid === "number" && typeof rec.heartbeat === "number")
+            return { pid: rec.pid, heartbeat: rec.heartbeat };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read `sync_meta.cursor` read-only through node:sqlite; null when the table or row is absent. */
+export function readCursor(dbPath) {
+    let db = null;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+        const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'sync_meta'").get();
+        if (!table)
+            return null;
+        const row = db.prepare("SELECT value FROM sync_meta WHERE key = 'cursor'").get();
+        if (!row || row.value === null || row.value === undefined || row.value === "")
+            return null;
+        const n = Number(row.value);
+        return Number.isInteger(n) ? n : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db?.close();
+    }
+}
+/** The in-process status logic `query` and `ready` reuse. */
+export function replicaStatus(ctx, cfg, opts = {}) {
+    const base = {
+        verdict: "not-configured",
+        exitCode: 2,
+        dbPath: null,
+        cursor: null,
+        heartbeatAgeMs: null,
+        lockPid: null,
+        pidfilePid: null,
+        writerAlive: false,
+        reasons: [],
+    };
+    if (!cfg)
+        return { ...base, reasons: ["not connected"] };
+    const dbPath = opts.dbPath ?? replicaDbPath(cfg, ctx.home);
+    if (!existsSync(dbPath))
+        return { ...base, verdict: "absent", exitCode: 3, dbPath, reasons: ["no replica file"] };
+    const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+    const nowMs = opts.nowMs ?? ctx.now().getTime();
+    const lock = readLock(dbPath);
+    const pidfilePid = readPidfile(dbPath);
+    const heartbeatAgeMs = lock ? Math.max(0, nowMs - lock.heartbeat) : null;
+    const writerAlive = pidAlive(lock?.pid ?? null) || pidAlive(pidfilePid);
+    const cursor = readCursor(dbPath);
+    const reasons = [];
+    if (!lock)
+        reasons.push("no writer lock");
+    else if (heartbeatAgeMs !== null && heartbeatAgeMs >= staleMs)
+        reasons.push(`heartbeat ${heartbeatAgeMs}ms old (stale after ${staleMs}ms)`);
+    if (cursor === null)
+        reasons.push("no cursor");
+    if (!writerAlive)
+        reasons.push("no live writer process");
+    const fresh = reasons.length === 0;
+    return {
+        verdict: fresh ? "fresh" : "stale",
+        exitCode: fresh ? 0 : 1,
+        dbPath,
+        cursor,
+        heartbeatAgeMs,
+        lockPid: lock?.pid ?? null,
+        pidfilePid,
+        writerAlive,
+        reasons,
+    };
+}
+export function statusLine(s) {
+    switch (s.verdict) {
+        case "not-configured":
+            return "replica: not configured — run login first";
+        case "absent":
+            return `replica: absent at ${s.dbPath} — start it with: catalyst-skills replica start --detach`;
+        case "fresh":
+            return `replica: fresh at ${s.dbPath} (cursor ${s.cursor}, heartbeat ${s.heartbeatAgeMs}ms ago${s.lag !== undefined ? `, ${s.lag} behind head ${s.head}` : ""})`;
+        case "stale":
+            return `replica: stale at ${s.dbPath} (${s.reasons.join("; ")}${s.cursor !== null ? `; cursor ${s.cursor}` : ""}) — reads fall back to the API`;
+    }
+}
+/** better-sqlite3 when it resolves and constructs, else node:sqlite — with exactly one stderr line
+ *  on the fallback so the choice is visible. */
+export async function engineFor(sdk, dbPath, ctx, deps = {}) {
+    const requireDriver = deps.requireDriver ?? (() => createRequire(import.meta.url)("better-sqlite3"));
+    try {
+        const mod = requireDriver();
+        const driver = (mod && typeof mod === "object" && "default" in mod ? mod.default : mod);
+        if (typeof driver !== "function")
+            throw new Error("better-sqlite3 resolved to a non-constructor");
+        return deps.readonly ? sdk.betterSqlite3ReadonlyEngine(driver, dbPath) : sdk.betterSqlite3Engine(driver, dbPath);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        ctx.stderr(`[catalyst-skills] better-sqlite3 unavailable (${why}); using node:sqlite`);
+        return deps.readonly ? sdk.nodeSqliteReadonlyEngine(dbPath) : sdk.nodeSqliteEngine(dbPath);
+    }
+}
+export async function cmdReplica(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (!sub)
+        throw new UsageError("replica needs a subcommand: start | stop | status | sql | schema");
+    if (sub === "status")
+        return cmdStatus(args, ctx);
+    const cfg = loadConfig(ctx.home);
+    if (!cfg)
+        throw new CliError("not connected yet — run login first", "not-configured");
+    const dbPath = flagString(args, "db") ?? replicaDbPath(cfg, ctx.home);
+    switch (sub) {
+        case "start":
+            return cmdStart(args, ctx, cfg, dbPath, deps);
+        case "stop":
+            return cmdStop(ctx, dbPath);
+        case "sql":
+            return cmdSql(args, ctx, dbPath, rest.join(" "), deps);
+        case "schema":
+            return cmdSchema(args, ctx, dbPath, rest[0]);
+        default:
+            throw new UsageError(`unknown replica subcommand: ${sub}`);
+    }
+}
+async function cmdStatus(args, ctx) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        cfg = null;
+    }
+    const status = replicaStatus(ctx, cfg, {
+        staleMs: flagInt(args, "stale-ms", DEFAULT_STALE_MS),
+        dbPath: flagString(args, "db"),
+    });
+    if (flagBool(args, "probe") && cfg && status.verdict !== "not-configured") {
+        const head = await apiClient(cfg, ctx).getJson("/api/v1/snapshot", { query: { head: 1 } });
+        if (typeof head.body.cursor === "number") {
+            status.head = head.body.cursor;
+            status.lag = status.cursor === null ? head.body.cursor : head.body.cursor - status.cursor;
+        }
+    }
+    ctx.stdout(args.json ? JSON.stringify(status) : statusLine(status));
+    return status.exitCode;
+}
+async function cmdStart(args, ctx, cfg, dbPath, deps) {
+    if (flagBool(args, "detach")) {
+        const argv = (deps.argv ?? process.argv.slice(1)).filter((a) => a !== "--detach");
+        const { pid } = (deps.detach ?? detachSelf)(argv, ctx.env);
+        writeFileSync(pidfilePath(dbPath), `${pid}\n`);
+        ctx.stdout(`replica writer started in the background (pid ${pid}, db ${dbPath}); check with: catalyst-skills replica status`);
+        return 0;
+    }
+    const sdk = await loadSdk();
+    const engine = await engineFor(sdk, dbPath, ctx, deps.engineDeps);
+    const replica = new sdk.CatalystReplica({
+        baseUrl: apiBase(cfg),
+        account: cfg.account,
+        accountSource: "declared",
+        auth: { kind: "token", token: cfg.key },
+        dbPath,
+        engine,
+        fetchImpl: ctx.fetch,
+        wsFactory: deps.wsFactory,
+        log: (level, msg, extra) => ctx.stderr(`[replica ${level}] ${msg}${extra ? ` ${safeJson(extra)}` : ""}`),
+        onStatus: (s) => ctx.stderr(`[replica] status=${s}`),
+    });
+    await replica.start();
+    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}) — Ctrl-C to stop`);
+    const wait = deps.waitForStop ??
+        (() => new Promise((resolve) => {
+            const done = () => resolve();
+            process.once("SIGINT", done);
+            process.once("SIGTERM", done);
+        }));
+    await wait();
+    await replica.close();
+    try {
+        if (readPidfile(dbPath) === process.pid)
+            unlinkSync(pidfilePath(dbPath));
+    }
+    catch {
+        // pidfile already gone
+    }
+    ctx.stdout("replica stopped");
+    return 0;
+}
+function cmdStop(ctx, dbPath) {
+    const pid = readPidfile(dbPath);
+    if (pid === null) {
+        ctx.stdout(`no pidfile at ${pidfilePath(dbPath)} — nothing to stop (a foreground writer is stopped with Ctrl-C)`);
+        return 1;
+    }
+    if (!pidAlive(pid)) {
+        unlinkSync(pidfilePath(dbPath));
+        ctx.stdout(`pid ${pid} is not running; removed the stale pidfile`);
+        return 1;
+    }
+    process.kill(pid, "SIGTERM");
+    try {
+        unlinkSync(pidfilePath(dbPath));
+    }
+    catch {
+        // already removed by the writer
+    }
+    ctx.stdout(`sent SIGTERM to replica writer pid ${pid}`);
+    return 0;
+}
+const SELECT_ONLY = /^\s*(select|with)\b/i;
+export function assertSingleSelect(sql) {
+    const trimmed = sql.trim().replace(/;\s*$/, "");
+    if (!trimmed)
+        throw new UsageError('replica sql needs a query: replica sql "select ..."');
+    if (!SELECT_ONLY.test(trimmed) || trimmed.includes(";")) {
+        throw new UsageError("replica sql runs exactly one SELECT (or WITH ... SELECT); nothing else is accepted on a read-only handle");
+    }
+    return trimmed;
+}
+async function cmdSql(args, ctx, dbPath, sql, deps) {
+    const query = assertSingleSelect(sql);
+    if (!existsSync(dbPath))
+        throw new CliError(`no replica at ${dbPath} — start it with: catalyst-skills replica start --detach`, "replica-absent", 3);
+    const sdk = await loadSdk();
+    const engine = await engineFor(sdk, dbPath, ctx, { ...deps.engineDeps, readonly: true });
+    const replica = await sdk.CatalystReplica.openReadOnly({ dbPath, engine, log: () => { } });
+    try {
+        const rows = replica.sql.exec(query).toArray();
+        ctx.stdout(JSON.stringify(rows, null, args.json ? 0 : 2));
+        return 0;
+    }
+    finally {
+        await replica.close();
+    }
+}
+async function cmdSchema(args, ctx, dbPath, table) {
+    if (!existsSync(dbPath))
+        throw new CliError(`no replica at ${dbPath} — the schema is what the file holds; start it with: catalyst-skills replica start --detach`, "replica-absent", 3);
+    const db = new DatabaseSync(dbPath, { readOnly: true });
+    try {
+        const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map((r) => r.name);
+        const wanted = table ? tables.filter((t) => t === table) : tables;
+        if (table && wanted.length === 0)
+            throw new CliError(`no table "${table}" in the replica (tables: ${tables.join(", ")})`, "table-unknown");
+        const out = {};
+        for (const t of wanted) {
+            out[t] = db.prepare(`PRAGMA table_info("${t.replace(/"/g, '""')}")`).all().map((c) => ({
+                name: c.name,
+                type: c.type,
+                notnull: c.notnull,
+                pk: c.pk,
+            }));
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify(out));
+        else
+            for (const [t, cols] of Object.entries(out))
+                ctx.stdout(`${t}: ${cols.map((c) => `${c.name} ${c.type || "ANY"}${c.pk ? " PK" : ""}`).join(", ")}`);
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}

package/dist/sdk.js

@@ -0,0 +1,26 @@
+import { CliError } from "./errors.js";
+import { installTsDepsLoader } from "./ts-deps-loader.js";
+let cached = null;
+const realImport = () => import("@catalyst-cloud/sdk/node");
+/** Import the SDK's node entry, installing the type-stripping loader first. Cached per process. */
+export function loadSdk(importer = realImport) {
+    if (!cached) {
+        cached = (async () => {
+            const verdict = installTsDepsLoader();
+            try {
+                return await importer();
+            }
+            catch (err) {
+                cached = null;
+                const detail = err instanceof Error ? err.message.split("\n")[0] : String(err);
+                const why = verdict.installed ? "" : ` (${verdict.reason})`;
+                throw new CliError(`the Catalyst Cloud SDK could not be loaded on Node ${process.version}${why}: ${detail} — this verb needs the SDK; run under Node 22.15 or newer, or under bun`, "sdk-unavailable");
+            }
+        })();
+    }
+    return cached;
+}
+/** Test seam: forget the cached import. */
+export function resetSdkCache() {
+    cached = null;
+}