@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/dist/cli.js

@@ -1,268 +1,72 @@
-// cli.ts — CTC-1926: the `catalyst-skills` customer installer/joiner (npm: @catalyst-cloud/catalyst-skills).
-import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
-export const DEFAULT_BASE_URL = "https://staging.catalystcloud.dev";
-export const PROVENANCE_MARKER = "vendored-from: @catalyst-cloud/catalyst-skills";
+// cli.ts — the `catalyst-skills` dispatcher (npm: @catalyst-cloud/catalyst-skills). Verbs live in
+// their own modules; this file keeps every export the 0.1 tests and the bin import.
+import { existsSync } from "node:fs";
+import { parseArgs, positionals, verbHelp } from "./args.js";
+import { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, loadConfig, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
+import { loadContract, pickPath } from "./contract.js";
+import { CliError, MeError, UsageError } from "./errors.js";
+import { fetchMe } from "./http.js";
+import { cmdAccounts, cmdExplain, cmdQueue, cmdRunning } from "./execution.js";
+import { cmdQuery } from "./query.js";
+import { cmdReady } from "./ready.js";
+import { cmdReplica } from "./replica.js";
+import { promptSecret, stdinIsTty } from "./prompt.js";
+import { PROVENANCE_MARKER } from "./skill-shape.js";
+import { installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine } from "./skills.js";
+import { cmdWatch } from "./watch.js";
+import { cmdWrite } from "./write.js";
+import { cmdAsk } from "./ask.js";
+export { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installSkills, loadConfig, normalizeBaseUrl, parseArgs, parseChangelogEntry, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
-    "ask",
-    "concierge",
-    "join",
-    "linearis",
-    "setup",
-    "steward",
+    "catalyst-github",
+    "catalyst-linear",
+    "catalyst-setup",
+    "connect-me",
+    "how-catalyst-works",
+    "run-this-project",
+    "what-needs-me",
+    "whats-happening",
 ];
-export class UsageError extends Error {
-}
-export class CliError extends Error {
-    code;
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-    }
-}
-export class MeError extends Error {
-    kind;
-    status;
-    constructor(message, kind, status) {
-        super(message);
-        this.kind = kind;
-        this.status = status;
-    }
-}
-export function parseArgs(argv) {
-    const out = { command: null, force: false, help: false, version: false };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "-h" || a === "--help")
-            out.help = true;
-        else if (a === "-V" || a === "--version")
-            out.version = true;
-        else if (a === "--key")
-            out.key = requireValue(argv, ++i, "--key");
-        else if (a === "--base-url")
-            out.baseUrl = requireValue(argv, ++i, "--base-url");
-        else if (a === "--skills-dir")
-            out.skillsDir = requireValue(argv, ++i, "--skills-dir");
-        else if (a === "--force")
-            out.force = true;
-        else if (a.startsWith("--"))
-            throw new UsageError(`unknown option: ${a}`);
-        else if (out.command === null)
-            out.command = a;
-        else
-            throw new UsageError(`unexpected argument: ${a}`);
-    }
-    return out;
-}
-function requireValue(argv, i, flag) {
-    const v = argv[i];
-    if (v === undefined || v === "")
-        throw new UsageError(`${flag} requires a value`);
-    return v;
-}
-let manifestCache = null;
-export function readManifest() {
-    if (manifestCache)
-        return manifestCache;
-    const raw = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    manifestCache = {
-        version: raw.version,
-        tenantContractRange: raw.catalystCloud?.tenantContractRange ?? "unpinned",
-    };
-    return manifestCache;
-}
-export function configPathFor(home) {
-    return join(home, ".config", "catalyst-cloud", "customer.json");
-}
-export function defaultSkillsDirFor(home) {
-    return join(home, ".claude", "skills");
-}
-export function loadConfig(home) {
-    const path = configPathFor(home);
-    if (!existsSync(path))
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        throw new CliError(`config at ${path} is not valid JSON — re-run join to rewrite it`, "config-corrupt");
-    }
-    const cfg = parsed;
-    if (typeof cfg.account !== "string" ||
-        typeof cfg.key !== "string" ||
-        typeof cfg.baseUrl !== "string") {
-        throw new CliError(`config at ${path} is missing required fields — re-run join to rewrite it`, "config-corrupt");
-    }
-    return cfg;
-}
-export const CONFIG_MODE = 0o600;
-/**
- * Write the config and return its path plus the mode the file ACTUALLY carries afterwards.
- *
- * Codex round 1 (P1): Node honours `mode` only when it creates the file, so a rewrite of an existing
- * `customer.json` (key rotation, the corrupt-config repair, the update stamp) left a pre-existing
- * 0644 file world-readable while the CLI claimed 0600. The chmod runs on every write, and the
- * reported mode is read back from the file rather than asserted.
- */
-export function saveConfig(home, cfg) {
-    return writeConfig(home, cfg).path;
-}
-export function writeConfig(home, cfg) {
-    const path = configPathFor(home);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
-    chmodSync(path, CONFIG_MODE);
-    return { path, mode: statSync(path).mode & 0o777 };
-}
-export function formatMode(mode) {
-    return "0" + mode.toString(8);
-}
-export function normalizeBaseUrl(url) {
-    return url.replace(/\/+$/, "");
-}
-export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = 15_000) {
-    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 — ask your tenant admin for a valid account key"
-            : 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");
-    }
-    return {
-        account: body.account,
-        slug: body.slug,
-        name: body.name,
-        permissions: body.permissions,
-        principal: body.principal,
-    };
-}
-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 join)`;
-}
-export function skillsSourceDir() {
-    return fileURLToPath(new URL("../skills", import.meta.url));
-}
-export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
-    const result = { installed: [], skipped: [] };
-    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 (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;
-}
+/** `login` is the verb; `join` is the 0.1 name, kept as a deprecated alias for one minor version. */
+const VERB_ALIASES = { join: "login" };
+/** Verbs whose stdout is for a human, so the update notice may share it. Every other verb's stdout
+ *  is machine-read by a skill script and the notice goes to stderr. */
+const HUMAN_VERBS = new Set(["login", "install", "status", "notice"]);
 export function usageText() {
     return [
-        `${PACKAGE_NAME} — install the customer skill bundle and join your catalyst-cloud tenant`,
+        `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
         "",
         "Usage:",
-        "  catalyst-skills join --key <account-key> [--base-url <url>] [--skills-dir <dir>]",
-        "  catalyst-skills install [--skills-dir <dir>] [--force]",
-        "  catalyst-skills notice",
-        "  catalyst-skills status",
+        "  catalyst-skills login [--key <account-key>] [--base-url <url>] [--start-replica]",
+        "  catalyst-skills join ...   (deprecated alias of login; removed in the next minor version)",
+        "  catalyst-skills install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
+        "  catalyst-skills status | notice | me | ready | accounts",
+        "  catalyst-skills contract [--refresh] [--path <a.b.c>]",
+        "  catalyst-skills query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <n>>",
+        "  catalyst-skills replica <start [--detach]|stop|status [--probe]|sql \"<select>\"|schema [table]>",
+        "  catalyst-skills explain <ticket> | running | queue [--team K]",
+        "  catalyst-skills watch [--team K] [--ticket T]... [--project P] [--exec CMD]",
+        "  catalyst-skills write <comment|state|label|create|reaction|attachment|session> ...",
+        "  catalyst-skills ask <raise|accept|list> ...",
+        "",
+        "Every verb takes --help. --json makes the output machine-readable.",
         "",
         "The key may also come from CATALYST_CLOUD_TOKEN; the base URL defaults to",
         `CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
         "",
-        "join installs the skills (default ~/.claude/skills), calls GET /api/v1/me to discover",
-        "your tenant from the key alone, and writes ~/.config/catalyst-cloud/customer.json (0600).",
+        "login calls GET /api/v1/me to discover your tenant from the key alone, writes",
+        "~/.config/catalyst-cloud/customer.json (0600) with the key and this CLI's path, and caches the",
+        "tenant contract beside it. With no key in the environment and a terminal attached it prompts",
+        "for the key without echoing it. It does not install skills: your agent's own install command",
+        "does that, and `install` is only here to repair a copy this package made.",
     ].join("\n");
 }
-export function defaultCtx() {
-    return {
-        env: process.env,
-        home: process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/",
-        stdout: (line) => console.log(line),
-        stderr: (line) => console.error(line),
-        fetch: fetch,
-        now: () => new Date(),
-    };
-}
-export function resolveSkillsDir(args, ctx, cfg) {
-    return (args.skillsDir ??
-        ctx.env.CATALYST_SKILLS_CLAUDE_DIR ??
-        cfg?.skillsDir ??
-        defaultSkillsDirFor(ctx.home));
-}
 /**
- * The Tier-2 update path. When the bundle on disk is newer than the version the config last
- * recorded, the copies under the skills dir are still the OLD bundle's — `npm update -g` and a newer
- * `npx` replace the package, not the copies join made (Codex round 1, P2). So the copies are
- * refreshed FIRST and the new version is recorded only once that succeeded; a failed refresh leaves
- * the old stamp in place so the next command tries again instead of silencing the notice forever.
+ * The Tier-2 update path: when the bundle on disk is newer than the version the config last
+ * recorded, refresh the copied skills FIRST and record the new version only once that succeeded.
  */
 function maybePrintUpdateNotice(args, ctx) {
+    const say = HUMAN_VERBS.has(args.command ?? "") ? ctx.stdout : ctx.stderr;
     let cfg;
     try {
         cfg = loadConfig(ctx.home);
@@ -278,31 +82,32 @@ function maybePrintUpdateNotice(args, ctx) {
     const previous = cfg.lastSkillBundleVersion;
     if (previous) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
-        ctx.stdout(updateNoticeLine(previous, manifest.version, entry));
+        say(updateNoticeLine(previous, manifest.version, entry));
     }
     const skillsDir = resolveSkillsDir(args, ctx, cfg);
     let refreshed;
     try {
-        refreshed = installSkills(skillsDir, { force: false });
+        refreshed = installSkills(skillsDir, { force: false, onlyExisting: true });
     }
     catch (err) {
         ctx.stderr(`[catalyst-skills] could not refresh the skills at ${skillsDir} (${err instanceof Error ? err.message : String(err)}) — the ${manifest.version} skills are not installed yet; run: catalyst-skills install`);
         return;
     }
-    if (refreshed.installed.length > 0) {
-        ctx.stdout(`[catalyst-skills] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
-    }
+    if (refreshed.installed.length > 0)
+        say(`[catalyst-skills] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
     for (const s of refreshed.skipped) {
-        ctx.stdout(`[catalyst-skills] left "${s.name}" alone: ${skillsDir}/${s.name} was not installed by this package (catalyst-skills install --force to replace)`);
+        say(`[catalyst-skills] left "${s.name}" alone: ${skillsDir}/${s.name} was not installed by this package (catalyst-skills install --force to replace)`);
     }
     cfg.lastSkillBundleVersion = manifest.version;
     cfg.skillsDir = skillsDir;
     saveConfig(ctx.home, cfg);
 }
-export async function main(argv, ctx = defaultCtx()) {
+export async function main(argv, ctx = defaultCtx(), deps = {}) {
     let args;
     try {
-        args = parseArgs(argv);
+        args = parseArgs(argv.map((a, i) => (i === 0 && VERB_ALIASES[a] ? VERB_ALIASES[a] : a)));
+        if (args.command && VERB_ALIASES[args.command])
+            args.command = VERB_ALIASES[args.command];
     }
     catch (err) {
         ctx.stderr(err instanceof Error ? err.message : String(err));
@@ -314,21 +119,49 @@ export async function main(argv, ctx = defaultCtx()) {
         ctx.stdout(`${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
         return 0;
     }
-    if (args.help || args.command === null) {
+    if (args.command === null) {
         ctx.stdout(usageText());
         return 0;
     }
+    if (args.help) {
+        ctx.stdout(verbHelp(args.command));
+        return 0;
+    }
     try {
         maybePrintUpdateNotice(args, ctx);
         switch (args.command) {
-            case "join":
-                return await cmdJoin(args, ctx, manifest);
+            case "login":
+                return await cmdLogin(args, ctx, deps);
             case "install":
                 return cmdInstall(args, ctx);
             case "notice":
                 return 0;
             case "status":
-                return cmdStatus(ctx, manifest);
+                return cmdStatus(ctx);
+            case "me":
+                return await cmdMe(args, ctx);
+            case "contract":
+                return await cmdContract(args, ctx);
+            case "query":
+                return await cmdQuery(args, ctx, { engineDeps: deps.replica?.engineDeps });
+            case "replica":
+                return await cmdReplica(args, ctx, deps.replica);
+            case "explain":
+                return await cmdExplain(args, ctx);
+            case "running":
+                return await cmdRunning(args, ctx);
+            case "queue":
+                return await cmdQueue(args, ctx);
+            case "watch":
+                return await cmdWatch(args, ctx, deps.watch);
+            case "write":
+                return await cmdWrite(args, ctx, deps.write);
+            case "ask":
+                return await cmdAsk(args, ctx);
+            case "ready":
+                return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk });
+            case "accounts":
+                return cmdAccounts(ctx);
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());
@@ -338,21 +171,29 @@ export async function main(argv, ctx = defaultCtx()) {
     catch (err) {
         if (err instanceof UsageError) {
             ctx.stderr(err.message);
-            ctx.stderr(usageText());
+            ctx.stderr(args.command && args.command in VERB_HELP_KNOWN ? verbHelp(args.command) : usageText());
             return 1;
         }
-        if (err instanceof MeError || err instanceof CliError) {
+        if (err instanceof CliError) {
+            ctx.stderr(`catalyst-skills: ${err.message}`);
+            return err.exitCode;
+        }
+        if (err instanceof MeError) {
             ctx.stderr(`catalyst-skills: ${err.message}`);
             return 2;
         }
         throw err;
     }
 }
-async function cmdJoin(args, ctx, manifest) {
-    const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
-    if (!key) {
-        throw new UsageError("join needs an account key: pass --key <account-key> or set CATALYST_CLOUD_TOKEN");
+const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts"].map((v) => [v, true]));
+async function cmdLogin(args, ctx, deps) {
+    const manifest = readManifest();
+    let key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
+    if (!key && (deps.isTty ?? stdinIsTty)()) {
+        key = (await (deps.promptSecret ?? promptSecret)("Account key (not echoed): ")).trim();
     }
+    if (!key)
+        throw new UsageError("login needs an account key: pass --key <account-key> or set CATALYST_CLOUD_TOKEN");
     const baseUrl = normalizeBaseUrl(args.baseUrl ?? ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL);
     const me = await fetchMe(baseUrl, key, ctx.fetch);
     let existing;
@@ -364,7 +205,6 @@ async function cmdJoin(args, ctx, manifest) {
     }
     const previous = existing?.lastSkillBundleVersion ?? null;
     const skillsDir = resolveSkillsDir(args, ctx, existing);
-    const result = installSkills(skillsDir, { force: args.force });
     const config = {
         baseUrl,
         key,
@@ -376,21 +216,37 @@ async function cmdJoin(args, ctx, manifest) {
         joinedAt: ctx.now().toISOString(),
         lastSkillBundleVersion: manifest.version,
         skillsDir,
+        cliPath: cliPath(),
+        replicaDb: existing?.replicaDb ?? defaultReplicaDbFor(ctx.home),
     };
     const written = writeConfig(ctx.home, config);
-    ctx.stdout(`Joined ${me.name} (${me.slug}) — account ${me.account}`);
-    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your key)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
-    ctx.stdout(result.installed.length > 0
-        ? `Skills installed to ${skillsDir}: ${result.installed.join(", ")}`
-        : `No skills installed — ${skillsDir} already had them`);
-    for (const s of result.skipped) {
-        ctx.stdout(`Skipped "${s.name}": ${skillsDir}/${s.name} exists and was not installed by this package (use --force to replace)`);
-    }
+    ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
+    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your key and the CLI path)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
+    try {
+        const loaded = await loadContract(ctx, config, { refresh: true });
+        ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
+    }
+    catch (err) {
+        if (err instanceof CliError && (err.code === "contract-forbidden" || err.code === "contract-version")) {
+            ctx.stderr(`[catalyst-skills] ${err.message}`);
+        }
+        else {
+            throw err;
+        }
+    }
     if (previous && previous !== manifest.version) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
         ctx.stdout(updateNoticeLine(previous, manifest.version, entry));
     }
+    if (args.flags["start-replica"] === true) {
+        const code = await cmdReplica(parseArgs(["replica", "start", "--detach"]), ctx, {
+            ...deps.replica,
+            argv: deps.replica?.argv ?? [cliPath(), "replica", "start"],
+        });
+        if (code !== 0)
+            return code;
+    }
     return 0;
 }
 function cmdInstall(args, ctx) {
@@ -411,14 +267,44 @@ function cmdInstall(args, ctx) {
     }
     return 0;
 }
-function cmdStatus(ctx, manifest) {
+function cmdStatus(ctx) {
+    const manifest = readManifest();
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
-        ctx.stdout(`Not joined yet — run: npx ${PACKAGE_NAME} join --key <your account key>`);
+        ctx.stdout(`Not connected yet — run: CATALYST_CLOUD_TOKEN=<your account key> npx ${PACKAGE_NAME} login`);
         return 0;
     }
     ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
     ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
     ctx.stdout(`Bundle: ${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+    if (cfg.cliPath)
+        ctx.stdout(`CLI: ${cfg.cliPath}${existsSync(cfg.cliPath) ? "" : " (missing — re-run login)"}`);
+    ctx.stdout(`Contract: ${existsSync(contractPathFor(ctx.home)) ? contractPathFor(ctx.home) : "not cached (run: catalyst-skills contract --refresh)"}`);
+    return 0;
+}
+async function cmdMe(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const me = await fetchMe(cfg.baseUrl, cfg.key, ctx.fetch);
+    if (args.json)
+        ctx.stdout(JSON.stringify(me));
+    else {
+        ctx.stdout(`${me.name} (${me.slug}) — account ${me.account}`);
+        ctx.stdout(`principal: ${me.principal}; permissions: ${me.permissions ? me.permissions.join(", ") : "unrestricted"}`);
+    }
+    return 0;
+}
+async function cmdContract(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const [sub] = positionals(args);
+    if (sub)
+        throw new UsageError(`contract takes no positional argument (got "${sub}"); use --path <a.b.c>`);
+    const refresh = args.flags.refresh === true;
+    const loaded = await loadContract(ctx, cfg, { refresh });
+    ctx.stderr(`contract: ${loaded.doc.contractVersion} from ${loaded.source}${loaded.source === "cache" ? ` (${loaded.ageSeconds}s old)` : ""}`);
+    const path = typeof args.flags.path === "string" ? args.flags.path : undefined;
+    const value = path ? pickPath(loaded.doc, path) : loaded.doc;
+    if (path && value === undefined)
+        throw new CliError(`the contract has nothing at "${path}"`, "contract-path");
+    ctx.stdout(typeof value === "string" ? value : JSON.stringify(value, null, args.json ? 0 : 2));
     return 0;
 }

package/dist/config.js

@@ -0,0 +1,106 @@
+// config.ts — ~/.config/catalyst-cloud/customer.json and its siblings. The ONLY place the base URL
+// and the `/api/v1` prefix are joined: the SDK wants the base with the prefix, GET /me without.
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
+export const DEFAULT_BASE_URL = "https://staging.catalystcloud.dev";
+export const CONFIG_MODE = 0o600;
+export function defaultCtx() {
+    return {
+        env: process.env,
+        home: process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/",
+        stdout: (line) => console.log(line),
+        stderr: (line) => console.error(line),
+        fetch: fetch,
+        now: () => new Date(),
+    };
+}
+export function configDirFor(home) {
+    return join(home, ".config", "catalyst-cloud");
+}
+export function configPathFor(home) {
+    return join(configDirFor(home), "customer.json");
+}
+export function contractPathFor(home) {
+    return join(configDirFor(home), "contract.json");
+}
+export function watchCursorPathFor(home) {
+    return join(configDirFor(home), "watch-cursor.json");
+}
+export function defaultReplicaDbFor(home) {
+    return join(configDirFor(home), "replica.db");
+}
+export function defaultSkillsDirFor(home) {
+    return join(home, ".claude", "skills");
+}
+/** The CLI launcher this very package ships — recorded by login so skill scripts can spawn it. */
+export function cliPath() {
+    return fileURLToPath(new URL("../bin/catalyst-skills.js", import.meta.url));
+}
+export function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+/** The origin WITH the versioned prefix — what the SDK and every API read/write take. */
+export function apiBase(cfg) {
+    return `${normalizeBaseUrl(cfg.baseUrl)}/api/v1`;
+}
+export function replicaDbPath(cfg, home) {
+    return cfg.replicaDb ?? defaultReplicaDbFor(home);
+}
+export function loadConfig(home) {
+    const path = configPathFor(home);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new CliError(`config at ${path} is not valid JSON — re-run login to rewrite it`, "config-corrupt");
+    }
+    const cfg = parsed;
+    if (typeof cfg.account !== "string" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+        throw new CliError(`config at ${path} is missing required fields — re-run login to rewrite it`, "config-corrupt");
+    }
+    return cfg;
+}
+/** Load the config or refuse with the one line every verb prints when the machine is not connected. */
+export function requireConfig(ctx) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg) {
+        throw new CliError(`not connected yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE_NAME} login`, "not-configured");
+    }
+    return cfg;
+}
+export function saveConfig(home, cfg) {
+    return writeConfig(home, cfg).path;
+}
+/** Write the config and return the mode the file ACTUALLY carries afterwards (chmod runs on every
+ *  write: Node honours `mode` only when it creates the file). */
+export function writeConfig(home, cfg) {
+    const path = configPathFor(home);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
+    chmodSync(path, CONFIG_MODE);
+    return { path, mode: statSync(path).mode & 0o777 };
+}
+export function formatMode(mode) {
+    return "0" + mode.toString(8);
+}
+let manifestCache = null;
+export function readManifest() {
+    if (manifestCache)
+        return manifestCache;
+    const raw = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    manifestCache = {
+        version: raw.version,
+        tenantContractRange: raw.catalystCloud?.tenantContractRange ?? "unpinned",
+    };
+    return manifestCache;
+}
+/** Test seam: forget the cached manifest. */
+export function resetManifestCache() {
+    manifestCache = null;
+}

package/dist/contract-types.js

@@ -0,0 +1,4 @@
+// contract-types.ts — the SHAPE of GET /api/v1/agent/contract as this bundle reads it. Typed here
+// (the cloud's own declaration lives in another repository) and filled only from the wire. No field
+// below carries a default: a tenant value the contract does not serve is refused, never guessed.
+export {};