@catalyst-cloud/cli 0.8.0

package/dist/cli.js

@@ -0,0 +1,397 @@
+// 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, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
+import { loadContract, pickPath } from "./contract.js";
+import { CliError, MeError, UsageError } from "./errors.js";
+import { fetchMe } from "./transport.js";
+import { bearerFor, deviceFlowLogin } from "./oauth.js";
+import { openBrowser as defaultOpenBrowser } from "./browser.js";
+import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning } from "./execution.js";
+import { cmdQuery } from "./query.js";
+import { cmdReady } from "./ready.js";
+import { cmdReplica } from "./replica.js";
+import { cmdRuntime } from "./runtime-verb.js";
+import { cmdEvents } from "./events.js";
+import { stdinIsTty } from "./prompt.js";
+import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion } from "./skill-shape.js";
+import { installedBundleVersion, installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine, } from "./skills.js";
+import { cmdWatch } from "./watch.js";
+import { cmdWrite } from "./write.js";
+import { cmdAsk } from "./ask.js";
+import { cmdRelease } from "./release.js";
+import { cmdEnvironment } from "./environment.js";
+import { cmdSecret } from "./secret.js";
+export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, LEGACY_PACKAGE_NAME, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, modernCliPath, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
+export const CUSTOMER_SKILLS = [
+    "catalyst-github",
+    "catalyst-linear",
+    "catalyst-onboard",
+    "catalyst-setup",
+    "connect-me",
+    "how-catalyst-works",
+    "run-this-project",
+    "unstick",
+    "what-needs-me",
+    "whats-happening",
+];
+/** `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} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
+        "",
+        "Usage:",
+        "  catalyst-skills login [--base-url <url>] [--start-replica]   (keyless: logs you in as yourself)",
+        "  catalyst-skills login --key <personal-key> [--base-url <url>]   (or CATALYST_CLOUD_TOKEN, for a key)",
+        "  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 <cursor|head>>",
+        "  catalyst-skills replica <start [--detach]|stop|status [--probe]|sql \"<select>\"|schema [table]>",
+        "  catalyst-skills runtime <status [--json]|install|path|uninstall>   (a pinned Node this CLI manages itself)",
+        "  catalyst-skills events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE]",
+        "  catalyst-skills explain <ticket> | history <ticket> | running [--ticket T --phase P] | 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> ...",
+        "  catalyst-skills release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
+        "  catalyst-skills environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve",
+        "  catalyst-skills secret set <NAME> --repo <owner/name> [--command '<cmd>'] | secret import <file> --repo <owner/name>",
+        "",
+        "Every verb takes --help. --json makes the output machine-readable.",
+        "",
+        "With no key, login is keyless: it opens a WorkOS device-code flow, prints a short code and a URL,",
+        "and connects you as yourself once you approve in the browser — nothing to mint or paste. Pass",
+        "--key (or set CATALYST_CLOUD_TOKEN) to use a personal or account key instead. The base URL defaults",
+        `to CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
+        "",
+        "login discovers your tenant from GET /api/v1/me, writes ~/.config/catalyst-cloud/customer.json",
+        "(0600) holding your login session (or key) and this CLI's path, and caches the tenant contract",
+        "beside it. A keyless session's short-lived token refreshes silently on every request. login 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");
+}
+/**
+ * CTC-3479 — a login before the rename recorded bin/catalyst-skills.js as cliPath. Skill scripts
+ * spawn that path, and it now prints the deprecated-name notice on every call. Move the record onto
+ * the `catalyst` launcher beside it, once, on the next run of either name. Read and write back to
+ * back, so the window for racing a concurrent OAuth refresh is as small as the update notice's.
+ */
+function migrateLegacyCliPath(ctx) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        return;
+    }
+    if (!cfg)
+        return;
+    const next = modernCliPath(cfg.cliPath);
+    if (next === null)
+        return;
+    cfg.cliPath = next;
+    try {
+        saveConfig(ctx.home, cfg);
+    }
+    catch {
+        // Best effort: the old launcher still works, it only prints the notice.
+    }
+}
+/**
+ * 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);
+    }
+    catch {
+        return;
+    }
+    if (!cfg)
+        return;
+    const manifest = readManifest();
+    if (cfg.lastSkillBundleVersion === manifest.version)
+        return;
+    const previous = cfg.lastSkillBundleVersion;
+    if (previous) {
+        const entry = parseChangelogEntry(readChangelog(), manifest.version);
+        say(updateNoticeLine(previous, manifest.version, entry));
+    }
+    const skillsDir = resolveSkillsDir(args, ctx, cfg);
+    let refreshed;
+    try {
+        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)
+        say(`[catalyst-skills] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
+    for (const s of refreshed.skipped) {
+        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(), deps = {}) {
+    let args;
+    try {
+        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));
+        ctx.stderr(usageText());
+        return 1;
+    }
+    const manifest = readManifest();
+    if (args.version) {
+        ctx.stdout(`${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+        return 0;
+    }
+    if (args.command === null) {
+        ctx.stdout(usageText());
+        return 0;
+    }
+    if (args.help) {
+        ctx.stdout(verbHelp(args.command));
+        return 0;
+    }
+    try {
+        migrateLegacyCliPath(ctx);
+        maybePrintUpdateNotice(args, ctx);
+        switch (args.command) {
+            case "login":
+                return await cmdLogin(args, ctx, deps);
+            case "install":
+                return cmdInstall(args, ctx);
+            case "notice":
+                return 0;
+            case "status":
+                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 "runtime":
+                return await cmdRuntime(args, ctx, deps.runtime);
+            case "events":
+                return await cmdEvents(args, ctx, deps.events);
+            case "explain":
+                return await cmdExplain(args, ctx);
+            case "history":
+                return await cmdHistory(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, offline: args.flags.offline === true });
+            case "accounts":
+                return await cmdAccounts(args, ctx);
+            case "release":
+                return await cmdRelease(args, ctx);
+            case "environment":
+                return await cmdEnvironment(args, ctx, deps.environment ?? {});
+            case "secret":
+                return await cmdSecret(args, ctx, deps.secret ?? {});
+            default:
+                ctx.stderr(`unknown command: ${args.command}`);
+                ctx.stderr(usageText());
+                return 1;
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            ctx.stderr(err.message);
+            ctx.stderr(args.command && args.command in VERB_HELP_KNOWN ? verbHelp(args.command) : usageText());
+            return 1;
+        }
+        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;
+    }
+}
+const VERB_HELP_KNOWN = Object.fromEntries(["login", "join", "install", "status", "notice", "me", "contract", "query", "replica", "runtime", "events", "explain", "running", "queue", "watch", "write", "ask", "ready", "accounts", "release", "secret"].map((v) => [v, true]));
+async function cmdLogin(args, ctx, deps) {
+    const manifest = readManifest();
+    const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
+    const baseUrl = normalizeBaseUrl(args.baseUrl ?? ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL);
+    // Keyless is the preferred rail: with no key in flag or env, run the WorkOS device flow and log in
+    // as the person. A key (flag or CATALYST_CLOUD_TOKEN) still takes the token rail unchanged.
+    let auth;
+    const bearer = key
+        ? key
+        : (auth = await deviceFlowLogin(ctx, baseUrl, {
+            isTty: deps.isTty ?? stdinIsTty,
+            openBrowser: deps.openBrowser ?? defaultOpenBrowser,
+            sleep: deps.sleep,
+        })).accessToken;
+    const me = await fetchMe(baseUrl, bearer, ctx.fetch);
+    let existing;
+    try {
+        existing = loadConfig(ctx.home);
+    }
+    catch {
+        existing = null;
+    }
+    const previous = existing?.lastSkillBundleVersion ?? null;
+    const skillsDir = resolveSkillsDir(args, ctx, existing);
+    const config = {
+        baseUrl,
+        ...(key ? { key } : {}),
+        ...(auth ? { auth } : {}),
+        account: me.account,
+        slug: me.slug,
+        name: me.name,
+        permissions: me.permissions,
+        principal: me.principal,
+        ...(me.user ? { user: me.user } : {}),
+        joinedAt: ctx.now().toISOString(),
+        lastSkillBundleVersion: manifest.version,
+        skillsDir,
+        cliPath: cliPath(),
+        replicaDb: existing?.replicaDb ?? defaultReplicaDbFor(ctx.home),
+    };
+    const written = writeConfig(ctx.home, config);
+    ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
+    if (me.user) {
+        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId ? "" : " — your Linear identity is not matched yet, so \"what needs me\" will show everyone's asks until an admin matches it in Settings"}`);
+    }
+    else {
+        ctx.stderr(`[catalyst-skills] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
+    }
+    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "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) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        cfg = null;
+    }
+    const skillsDir = resolveSkillsDir(args, ctx, cfg);
+    const result = installSkills(skillsDir, { force: args.force });
+    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)`);
+    }
+    return 0;
+}
+function cmdStatus(ctx) {
+    const manifest = readManifest();
+    const cfg = loadConfig(ctx.home);
+    if (!cfg) {
+        ctx.stdout(`Not connected yet — run: npx ${LEGACY_PACKAGE_NAME} login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)`);
+        return 0;
+    }
+    ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
+    ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
+    ctx.stdout(cfg.user ? `As: ${cfg.user.label} (${cfg.user.role})` : "As: the tenant's account key (a host credential — no person)");
+    ctx.stdout(cfg.auth ? `Credential: your login (expires ${relativeExpiry(cfg.auth.expiresAt, ctx.now())})` : "Credential: personal key");
+    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;
+}
+/** A short human relative time for an ISO expiry, e.g. "in 14m", "in 2h", "in 6d", or "now" once past. */
+function relativeExpiry(iso, now) {
+    const ms = Date.parse(iso) - now.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return "now";
+    const mins = Math.round(ms / 60_000);
+    if (mins < 60)
+        return `in ${mins}m`;
+    const hours = Math.round(mins / 60);
+    if (hours < 48)
+        return `in ${hours}h`;
+    return `in ${Math.round(hours / 24)}d`;
+}
+async function cmdMe(args, ctx) {
+    const cfg = requireConfig(ctx);
+    const me = await fetchMe(cfg.baseUrl, await bearerFor(ctx, cfg), 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"}`);
+        if (me.user)
+            ctx.stdout(`user: ${me.user.label} (${me.user.role}); linear: ${me.user.linearUserId ?? "unmatched"}`);
+    }
+    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,241 @@
+// 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, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+import { parseMachinePaths, resolveCatalystPath } from "../vendor/paths/index.js";
+import { machinePathsFile } from "../vendor/paths/node.js";
+/** CTC-3479 — the package this CLI publishes as. Its command is `catalyst`. */
+export const PACKAGE_NAME = "@catalyst-cloud/cli";
+/** The old package name, now a thin forwarder that depends on PACKAGE_NAME at the same version. The
+ *  npx login hints keep naming it until CTC-3480/3481 move them; upgrade hints name whichever package
+ *  is installed (updatePackageName). `npx @catalyst-cloud/cli`
+ *  cannot run a verb: that package has two bins and neither is named `cli`, so npx cannot pick one.
+ *  The forwarder has a bin named after itself, so `npx @catalyst-cloud/catalyst-skills` still works. */
+export const LEGACY_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");
+}
+/** CTC-2160 — the cached answer to "what is the newest published release" (src/published.ts). */
+export function publishedCachePathFor(home) {
+    return join(configDirFor(home), "published.json");
+}
+export function watchCursorPathFor(home) {
+    return join(configDirFor(home), "watch-cursor.json");
+}
+/** CTC-2112 — where the cached CLI-auth discovery document lives (the `/api/v1/auth/cli` answer). */
+export function discoveryCachePathFor(home) {
+    return join(configDirFor(home), "auth-discovery.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. It is
+ *  the `catalyst` launcher, so a skill script's call does not print the deprecated-name line. */
+export function cliPath() {
+    return fileURLToPath(new URL("../bin/catalyst.js", import.meta.url));
+}
+/** This package's root directory (the one holding package.json, bin/ and dist/). */
+export function packageRoot() {
+    return fileURLToPath(new URL("..", import.meta.url));
+}
+function packageNameAt(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        return typeof raw.name === "string" ? raw.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * CTC-3479 — the package whose `npm install -g <name>@latest` updates this install. Both packages
+ * ship the `catalyst` and `catalyst-skills` bins, so npm refuses to install one over the other
+ * (EEXIST). An upgrade hint must therefore name the package this machine already has.
+ *
+ * The forwarder carries this package as its dependency, in one of two layouts:
+ * - nested, as `npm install -g` lays it out: `<forwarder>/node_modules/@catalyst-cloud/cli`;
+ * - flat, as npx and a project install lay it out: `node_modules/@catalyst-cloud/catalyst-skills`
+ *   sits beside `node_modules/@catalyst-cloud/cli`.
+ * Anything else is a direct install of this package (or a checkout of this repository).
+ */
+export function updatePackageName(root = packageRoot()) {
+    const scopeDir = dirname(root);
+    const nested = dirname(dirname(scopeDir));
+    if (packageNameAt(nested) === LEGACY_PACKAGE_NAME)
+        return LEGACY_PACKAGE_NAME;
+    if (packageNameAt(join(scopeDir, "catalyst-skills")) === LEGACY_PACKAGE_NAME)
+        return LEGACY_PACKAGE_NAME;
+    return PACKAGE_NAME;
+}
+/** The one upgrade command every hint prints: update the installed package, then log in again so
+ *  customer.json records the new launcher path. */
+export function upgradeCommand(root) {
+    return `npm install -g ${updatePackageName(root)}@latest && catalyst-skills login`;
+}
+/**
+ * CTC-3479 — logins before this release recorded bin/catalyst-skills.js as cliPath. That launcher is
+ * now the deprecated name and prints a notice, so every skill script call through it would carry
+ * the notice. When the recorded launcher has a `catalyst.js` beside it (any 0.8.0-or-later install of
+ * either package), point cliPath at that instead. Returns the new path, or null when nothing changes.
+ */
+export function modernCliPath(recorded) {
+    if (typeof recorded !== "string" || !recorded.endsWith("catalyst-skills.js"))
+        return null;
+    const sibling = join(dirname(recorded), "catalyst.js");
+    return existsSync(sibling) ? sibling : null;
+}
+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`;
+}
+function machineFilePresent(file) {
+    try {
+        lstatSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function replicaDbPath(cfg, home, env = {}) {
+    if (env.CATALYST_REPLICA_DB !== undefined)
+        return resolveCatalystPath("replicaDb", { env });
+    const file = machinePathsFile({ env: { ...env, HOME: home } });
+    if (file && (env.CATALYST_PATHS_FILE !== undefined || machineFilePresent(file))) {
+        const machine = parseMachinePaths(JSON.parse(readFileSync(file, "utf8")));
+        if (machine.paths.replicaDb === undefined)
+            throw new CliError("optional replica is not configured; set CATALYST_REPLICA_DB or declare replicaDb in the machine paths file", "replica-not-configured");
+        return resolveCatalystPath("replicaDb", { env, machine });
+    }
+    // Compatibility for machines that have not run paths setup. Keep the existing DB in place.
+    return resolveCatalystPath("replicaDb", { overrides: { replicaDb: 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.baseUrl !== "string") {
+        throw new CliError(`config at ${path} is missing required fields — re-run login to rewrite it`, "config-corrupt");
+    }
+    const hasKey = typeof cfg.key === "string" && cfg.key !== "";
+    const hasOauth = isOauthAuth(cfg.auth);
+    if (hasKey === hasOauth) {
+        throw new CliError(`config at ${path} must hold exactly one of a personal key or an OAuth session — 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: npx ${LEGACY_PACKAGE_NAME} login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN for a key)`, "not-configured");
+    }
+    return cfg;
+}
+export function saveConfig(home, cfg) {
+    return writeConfig(home, cfg).path;
+}
+/** True when `v` is a well-formed OAuth session block. */
+export function isOauthAuth(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const a = v;
+    return (a.kind === "oauth" &&
+        typeof a.accessToken === "string" &&
+        typeof a.refreshToken === "string" &&
+        typeof a.expiresAt === "string" &&
+        typeof a.sessionId === "string");
+}
+/**
+ * Write the config atomically (a rotated token must never be half-written under a crash) and return
+ * the mode the file ACTUALLY carries afterwards. Write to a sibling `.tmp` at 0600, then rename over
+ * the target — rename is atomic within a directory — and chmod once more (a pre-existing target keeps
+ * its own mode through the rename on some platforms).
+ */
+export function writeConfig(home, cfg) {
+    const path = configPathFor(home);
+    mkdirSync(dirname(path), { recursive: true });
+    // A UNIQUE sibling temp per write (pid + randomness): two concurrent CLI processes reaching the
+    // OAuth refresh window must not share `customer.json.tmp`, or one renames/removes it out from under
+    // the other and the second write fails with ENOENT or lands the wrong contents (Codex P2).
+    const tmp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
+        chmodSync(tmp, CONFIG_MODE);
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch {
+            // best-effort cleanup of the temp file
+        }
+        throw err;
+    }
+    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"));
+    if (!raw.engines?.node) {
+        throw new CliError("package.json is missing engines.node — the supported Node range is not optional", "manifest-corrupt");
+    }
+    if (!raw.catalystCloud?.pinnedNode) {
+        throw new CliError("package.json is missing catalystCloud.pinnedNode — the pinned runtime version is not optional", "manifest-corrupt");
+    }
+    manifestCache = {
+        version: raw.version,
+        tenantContractRange: raw.catalystCloud?.tenantContractRange ?? "unpinned",
+        enginesNode: raw.engines.node,
+        pinnedNode: raw.catalystCloud.pinnedNode,
+    };
+    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 {};