@catalyst-cloud/cli 0.13.0 → 0.14.0

package/dist/env.js

@@ -2,17 +2,103 @@
 // validator. Unlike every other verb in this file's siblings, `cmdEnv` never calls `requireConfig` or
 // `apiClient` — it needs neither a login nor a network call, which is the whole point of the feature:
 // a person reviews what a repository declares without connecting anything first.
-import { readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
-import { positionals } from "./args.js";
-import { validateDeclaration } from "./env/declaration-rules.js";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { flagBool, flagString, positionals } from "./args.js";
+import { validateSettingsToml } from "./env/settings-toml.js";
+import { convertLegacyEnvironmentJson } from "./env/legacy.js";
+import { draftEnvironment } from "./env/draft.js";
 import { inventoryRepo } from "./env/inventory.js";
-import { inventoryToJson, renderCheck, renderInventory } from "./env/render.js";
+import { inventoryToJson, renderInventory } from "./env/render.js";
 import { UsageError } from "./errors.js";
 export async function cmdEnv(args, ctx, deps = {}) {
     const [sub, ...rest] = positionals(args);
     if (sub === undefined)
-        throw new UsageError("env needs a subcommand: inventory | check");
+        throw new UsageError("env needs a subcommand: inventory | check | migrate | draft");
+    if (sub === "draft") {
+        if (rest.length > 0)
+            throw new UsageError("env draft takes no positional arguments; use --root DIR");
+        const root = resolve(flagString(args, "root") ?? ".");
+        const target = join(root, ".catalyst/catalyst.toml");
+        const draft = draftEnvironment(root, deps);
+        if (draft.state === "invalid") {
+            if (args.json)
+                ctx.stdout(JSON.stringify(draft));
+            else
+                for (const error of draft.errors)
+                    ctx.stderr(error);
+            return 1;
+        }
+        const summary = {
+            state: "valid",
+            names: draft.names,
+            secretNames: draft.secretNames,
+            setupCount: draft.setup.length,
+            verifyCount: draft.verify.length,
+            sources: draft.sources,
+            destination: ".catalyst/catalyst.toml",
+            toml: draft.toml,
+        };
+        const write = flagBool(args, "write");
+        if (write && existsSync(target)) {
+            ctx.stderr(`${summary.destination} already exists; no file was written. Review the draft with --diff and merge it by hand.`);
+            return 1;
+        }
+        if (write) {
+            const checked = validateSettingsToml(draft.toml);
+            if (checked.state !== "valid") {
+                ctx.stderr(`draft failed local validation: ${checked.state === "invalid" ? checked.errors.join("; ") : "no environment table"}`);
+                return 1;
+            }
+            if (deps.writeFile)
+                deps.writeFile(target, draft.toml);
+            else {
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, draft.toml, { encoding: "utf8", flag: "wx" });
+            }
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify({ ...summary, written: write }));
+        else if (flagBool(args, "diff")) {
+            ctx.stdout(`--- /dev/null\n+++ b/${summary.destination} (draft)\n@@\n${draft.toml.split("\n").filter(Boolean).map((line) => `+${line}`).join("\n")}`);
+        }
+        else {
+            ctx.stdout(`Drafted ${summary.destination} from ${draft.sources.length ? draft.sources.join(", ") : "no environment sources"}.`);
+            ctx.stdout(`Names: ${draft.names.length} (${draft.secretNames.length} secret; all optional)`);
+            ctx.stdout(`Setup: ${draft.setup.length}; verify: ${draft.verify.length}`);
+            ctx.stdout(draft.toml);
+        }
+        if (write && !args.json)
+            ctx.stdout(`Wrote ${summary.destination}; review and commit it through your repository's pull request.`);
+        return 0;
+    }
+    if (sub === "migrate") {
+        if (rest.length > 1)
+            throw new UsageError(`env migrate takes at most one file (got an extra "${rest[1]}")`);
+        const file = rest[0] ?? "catalyst.env.json";
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            ctx.stderr(`could not read legacy declaration ${file}`);
+            return 1;
+        }
+        const result = convertLegacyEnvironmentJson(text);
+        if (result.state === "invalid") {
+            if (args.json)
+                ctx.stdout(JSON.stringify(result));
+            else
+                for (const error of result.errors)
+                    ctx.stderr(error);
+            return 1;
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify(result));
+        else
+            ctx.stdout(result.toml);
+        return 0;
+    }
     if (sub === "inventory") {
         if (rest.length > 1)
             throw new UsageError(`env inventory takes at most one path (got an extra "${rest[1]}")`);
@@ -40,37 +126,51 @@ export async function cmdEnv(args, ctx, deps = {}) {
         return 0;
     }
     if (sub === "check") {
-        const file = rest[0];
-        if (!file)
-            throw new UsageError("env check needs a file: catalyst env check <path to catalyst.env.json>");
+        const file = rest[0] ?? ".catalyst/catalyst.toml";
         if (rest.length > 1)
             throw new UsageError(`env check takes exactly one file (got an extra "${rest[1]}")`);
+        if (file.endsWith("catalyst.env.json")) {
+            const message = "catalyst.env.json is a legacy declaration and is no longer read; validate .catalyst/catalyst.toml instead";
+            if (args.json)
+                ctx.stdout(JSON.stringify({ state: "invalid", errors: [message] }));
+            else
+                ctx.stderr(message);
+            return 1;
+        }
         let text;
         try {
             text = readFileSync(file, "utf8");
         }
         catch (err) {
+            if (rest[0] === undefined && !existsSync("catalyst.env.json")) {
+                if (args.json)
+                    ctx.stdout(JSON.stringify({ state: "no-source", errors: [] }));
+                else
+                    ctx.stdout("no .catalyst/catalyst.toml found in this repository");
+                return 0;
+            }
+            if (rest[0] === undefined && existsSync("catalyst.env.json")) {
+                const message = "No .catalyst/catalyst.toml found; this repository has a legacy catalyst.env.json, which is no longer read. Convert it to the [environment] table in .catalyst/catalyst.toml.";
+                if (args.json)
+                    ctx.stdout(JSON.stringify({ state: "invalid", errors: [message] }));
+                else
+                    ctx.stderr(message);
+                return 1;
+            }
             ctx.stderr(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
             return 1;
         }
-        let doc;
-        try {
-            doc = JSON.parse(text);
-        }
-        catch {
-            // C-4/S-2: JSON.parse's own message embeds the first ten characters of the input, so
-            // forwarding it prints content from the file — on a verb documented as never printing a value.
-            ctx.stderr(`${file} is not valid JSON`);
-            return 1;
-        }
-        const errors = validateDeclaration(doc);
-        const state = errors.length === 0 ? "valid" : "invalid";
+        const result = validateSettingsToml(text);
         if (args.json)
-            ctx.stdout(JSON.stringify({ state, errors }));
+            ctx.stdout(JSON.stringify(result));
+        else if (result.state === "valid")
+            ctx.stdout(`valid — ${file} contains ${result.variableNames.length} environment variable names`);
+        else if (result.state === "no-source")
+            ctx.stdout(`no [environment] table in ${file}`);
         else
-            for (const line of renderCheck({ state, errors }, file))
-                ctx.stdout(line);
-        return state === "valid" ? 0 : 1;
+            for (const error of result.errors)
+                ctx.stderr(`${file}: ${error}`);
+        return result.state === "invalid" ? 1 : 0;
     }
-    throw new UsageError(`unknown env subcommand "${sub}": inventory | check`);
+    throw new UsageError(`unknown env subcommand "${sub}": inventory | check | migrate | draft`);
 }

package/dist/environment.js

@@ -1,4 +1,4 @@
-// environment.ts — `catalyst-skills environment`: the tenant-scope environment declaration, through
+// environment.ts — `catalyst environment`: the tenant-scope environment declaration, through
 // the contract's account-environment routes. This is the ONE setup write a person's own key can
 // perform: the cloud has admitted it since the routes shipped, and until this verb existed nothing
 // could call it, so every setup action was a settings page.

package/dist/legacy.js

@@ -0,0 +1,224 @@
+// legacy.ts — `catalyst legacy`: leftovers of the old LOCAL Catalyst runtime (the archived repository
+// whose plugin, daemons, scheduled jobs and state folders a machine may still carry), found from a
+// FIXED list and removed only on a yes, through the tools that own each piece. The cloud runtime
+// replaced all of it; what is left can start old jobs or shadow current commands, so removal is
+// recommended, and never automatic: a run with no terminal and no --yes only reports.
+//
+// The list is fixed on purpose. A prefix match would one day catch a current job (the housekeeping
+// job, the sandbox credit guard, jobs a person made); this matches names the old runtime installed,
+// read at the source commit below, and nothing else. Data folders are a separate yes (--data).
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { flagBool, positionals } from "./args.js";
+import { UsageError } from "./errors.js";
+import { promptSecret, stdinIsTty } from "./prompt.js";
+/** The archived repository's commit the list below was read at. */
+export const LEGACY_SOURCE_COMMIT = "73bc0645252ce8be38f8c87be6b67b950b3f0b56";
+/** The old runtime's marketplace source, as Claude Code records it in known_marketplaces.json. */
+export const OLD_MARKETPLACE_REPO = "coalesce-labs/catalyst";
+/** launchd labels the old runtime installed under ~/Library/LaunchAgents (macOS). `com.catalyst.role.<name>`
+ *  is the old role supervisor's per-role instance, matched by that exact prefix. Never `dev.catalystcloud.*`
+ *  (the current housekeeping job and runner jobs) and never `dev.catalyst.*` (the sandbox credit guard). */
+export const OLD_LAUNCHD_LABELS = [
+    "com.catalyst.agent",
+    "com.catalyst.reaper-watch",
+    "com.catalyst.quiet-fleet",
+    "com.catalyst.dead-man",
+    "com.catalyst.holding-sentinel",
+    "com.catalyst.orch-monitor",
+    "com.catalyst.role",
+    "ai.coalesce.catalyst-stack",
+    "ai.coalesce.catalyst-thoughts-sync",
+    "ai.coalesce.catalyst-orphan-sweep",
+    "ai.coalesce.catalyst-log-shipper",
+    "ai.coalesce.catalyst-cloud-sync",
+    "ai.coalesce.catalyst-usage-page",
+    "ai.coalesce.catalyst-claude-update",
+    "ai.coalesce.catalyst-updater",
+    "ai.coalesce.catalyst-replica-sync",
+    "ai.coalesce.catalyst-channel-watcher",
+    "ai.coalesce.catalyst-event-mirror",
+    "ai.coalesce.catalyst-monitor",
+];
+const OLD_ROLE_PREFIX = "com.catalyst.role.";
+/** systemd user units (~/.config/systemd/user) the old runtime's workstation pieces used on Linux. System
+ *  units under /etc/systemd/system are a host's, current, and never looked at. */
+export const OLD_USER_UNITS = ["catalyst.service", "catalyst-monitor.service"];
+/** Command files the old runtime put on the person's PATH. `~/.local/bin/catalyst` is NOT one: that
+ *  name belongs to the current CLI wherever npm put it. */
+export const OLD_BINS = [".catalyst/bin", ".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
+/** State the old runtime kept. `~/.config/catalyst-cloud` is the current CLI's and never touched. */
+export const OLD_DATA_DIRS = [".catalyst", ".config/catalyst", ".local/state/catalyst", ".local/state/catalyst-fleet-runner", ".local/state/catalyst-ledger"];
+const RECOMMEND = "Remove them: the cloud runtime replaced them, and left in place they can start old jobs or shadow current commands.";
+function readJson(path) {
+    try {
+        const v = JSON.parse(readFileSync(path, "utf8"));
+        return v !== null && typeof v === "object" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Marketplaces whose recorded source is the old repository, and the plugins installed from them. */
+function findPlugins(home) {
+    const dir = join(home, ".claude", "plugins");
+    const marketplaces = readJson(join(dir, "known_marketplaces.json")) ?? {};
+    const old = Object.entries(marketplaces)
+        .filter(([, v]) => {
+        const src = v?.source;
+        return typeof src?.repo === "string" && src.repo.toLowerCase() === OLD_MARKETPLACE_REPO;
+    })
+        .map(([name]) => name);
+    if (old.length === 0)
+        return [];
+    const installed = (readJson(join(dir, "installed_plugins.json")) ?? {}).plugins ?? {};
+    const items = [];
+    for (const key of Object.keys(installed)) {
+        const at = key.lastIndexOf("@");
+        if (at > 0 && old.includes(key.slice(at + 1)))
+            items.push({ kind: "plugin", name: key, path: join(dir, "installed_plugins.json") });
+    }
+    for (const name of old)
+        items.push({ kind: "marketplace", name, path: join(dir, "known_marketplaces.json") });
+    return items;
+}
+function findJobs(home, platform) {
+    if (platform === "darwin") {
+        const dir = join(home, "Library", "LaunchAgents");
+        let files = [];
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        return files
+            .filter((f) => f.endsWith(".plist"))
+            .map((f) => f.slice(0, -".plist".length))
+            .filter((label) => OLD_LAUNCHD_LABELS.includes(label) || label.startsWith(OLD_ROLE_PREFIX))
+            .sort()
+            .map((label) => ({ kind: "job", name: label, path: join(dir, `${label}.plist`) }));
+    }
+    if (platform === "linux") {
+        const dir = join(home, ".config", "systemd", "user");
+        return OLD_USER_UNITS.filter((u) => existsSync(join(dir, u))).map((u) => ({ kind: "job", name: u, path: join(dir, u) }));
+    }
+    return [];
+}
+const tilde = (rel) => `~/${rel}`;
+function findFiles(home) {
+    const bins = OLD_BINS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "bin", name: tilde(rel), path: join(home, rel) }));
+    const data = OLD_DATA_DIRS.filter((rel) => existsSync(join(home, rel))).map((rel) => ({ kind: "data", name: tilde(rel), path: join(home, rel), data: true }));
+    return [...bins, ...data];
+}
+/** Every old piece on this machine, in removal order: plugins, their marketplace, jobs, bins, data. Never writes. */
+export function findLegacy(home, platform) {
+    return [...findPlugins(home), ...findJobs(home, platform), ...findFiles(home)];
+}
+const defaultRun = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 60_000 });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.error ? r.error.message : (r.stderr ?? "") };
+};
+/** Remove one item through the tool that owns it. Returns null on success, else the reason it is still there. */
+function remove(item, run, platform, uid) {
+    const tool = (cmd, args, what) => {
+        const r = run(cmd, args);
+        return r.status === 0 ? null : `${what} failed: ${(r.stderr || r.stdout).trim().split("\n")[0] || `exit ${r.status}`}`;
+    };
+    try {
+        if (item.kind === "plugin")
+            return tool("claude", ["plugin", "uninstall", item.name], "claude plugin uninstall");
+        if (item.kind === "marketplace")
+            return tool("claude", ["plugin", "marketplace", "remove", item.name], "claude plugin marketplace remove");
+        if (item.kind === "job") {
+            const why = platform === "darwin" ? tool("launchctl", ["bootout", `gui/${uid}/${item.name}`], "launchctl bootout") : tool("systemctl", ["--user", "disable", "--now", item.name], "systemctl --user disable --now");
+            if (why !== null)
+                return why;
+            unlinkSync(item.path);
+            return null;
+        }
+        // a bin or a data folder: a file goes with unlink, a directory (~/.catalyst/bin, the data) with rm -rf
+        if (lstatSync(item.path).isDirectory())
+            rmSync(item.path, { recursive: true, force: true });
+        else
+            unlinkSync(item.path);
+        return null;
+    }
+    catch (err) {
+        return `could not remove: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+export async function cmdLegacy(args, ctx, deps = {}) {
+    if (positionals(args).length > 0)
+        throw new UsageError("legacy takes no positional argument; flags are --remove, --data, --yes, --json");
+    const wantRemove = flagBool(args, "remove");
+    const withData = flagBool(args, "data");
+    if (withData && !wantRemove)
+        throw new UsageError("--data belongs with --remove");
+    const platform = deps.platform ?? process.platform;
+    const uid = deps.uid ?? (typeof process.getuid === "function" ? process.getuid() : 0);
+    const run = deps.run ?? defaultRun;
+    const found = findLegacy(ctx.home, platform);
+    const emit = (body, lines) => { if (args.json)
+        ctx.stdout(JSON.stringify(body));
+    else
+        for (const l of lines)
+            ctx.stdout(l); };
+    if (found.length === 0) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found: [], removed: [], remaining: [] }, ["no leftovers of the old local Catalyst runtime on this machine"]);
+        return 0;
+    }
+    const listLines = [
+        `Leftovers of the old local Catalyst runtime on this machine (${found.length}):`,
+        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept unless --data)" : ""}`),
+    ];
+    if (!wantRemove) {
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (add --data to delete its data folders too)"]);
+        return 1;
+    }
+    // the one question, only on a terminal; --yes answers it without asking
+    let go = flagBool(args, "yes");
+    if (!go) {
+        const tty = (deps.isTty ?? stdinIsTty)();
+        if (!tty) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: false }, [...listLines, RECOMMEND, "nothing removed: no terminal to ask on; run catalyst legacy --remove --yes to remove these without a question (add --data for the data folders)"]);
+            return 1;
+        }
+        for (const l of listLines)
+            ctx.stdout(l);
+        ctx.stdout(RECOMMEND);
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}${withData ? ", data folders included" : ", keeping the data folders"}? [y/N] `)).trim().toLowerCase();
+        go = answer === "y" || answer === "yes";
+        if (!go) {
+            emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found, asked: true }, ["nothing removed; run catalyst legacy --remove again when ready"]);
+            return 1;
+        }
+    }
+    const removed = [];
+    const failed = [];
+    const kept = [];
+    const lines = [];
+    for (const item of found) {
+        if (item.data && !withData) {
+            kept.push(item);
+            lines.push(`kept: ${item.kind} ${item.name} (run with --data to delete it)`);
+            continue;
+        }
+        const why = remove(item, run, platform, uid);
+        if (why === null) {
+            removed.push(item);
+            lines.push(`removed: ${item.kind} ${item.name}`);
+        }
+        else {
+            failed.push({ item, why });
+            lines.push(`still present: ${item.kind} ${item.name} (${why})`);
+        }
+    }
+    // re-check from the same list, so the report says what the machine holds now, not what was attempted
+    const remaining = findLegacy(ctx.home, platform).filter((f) => !(f.data && !withData));
+    const keptNote = kept.length > 0 ? " except the data folders you kept" : "";
+    lines.push(remaining.length === 0 ? `re-checked: nothing of the old runtime remains${keptNote}` : `re-checked: ${remaining.length} item${remaining.length === 1 ? "" : "s"} of the old runtime remain${remaining.length === 1 ? "s" : ""}${keptNote}: ${remaining.map((r) => `${r.kind} ${r.name}`).join(", ")}`);
+    emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed, remaining: [...remaining, ...kept], kept, failed }, lines);
+    return remaining.length === 0 ? 0 : 1;
+}

package/dist/onboard-consent.js

@@ -0,0 +1,65 @@
+import { performance } from "node:perf_hooks";
+import { CliError, UsageError } from "./errors.js";
+/** Bound callbacks too: a transport that forgets to honor abort cannot hold setup forever. */
+function bounded(work, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(new Error("consent_deadline"));
+        if (signal.aborted) {
+            reject(new Error("consent_deadline"));
+            return;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+function safeReason(reason, fallback) {
+    return reason && /^[a-z][a-z0-9_]{1,63}$/.test(reason) ? reason : fallback;
+}
+/** Poll live consent every two seconds for at most ten minutes, using actual elapsed time. */
+export async function pollConsent(options) {
+    const timeoutMs = options.timeoutMs ?? 600_000;
+    const intervalMs = options.intervalMs ?? 2_000;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 600_000 ||
+        !Number.isSafeInteger(intervalMs) || intervalMs <= 0)
+        throw new UsageError("consent timeout must be 1 to 600000 milliseconds, with a positive poll interval");
+    const now = options.now ?? (() => performance.now());
+    const started = now();
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const signal = options.signal ? AbortSignal.any([options.signal, deadline.signal]) : deadline.signal;
+    const elapsedMs = () => Math.max(0, Math.round(now() - started));
+    const waiting = () => ({ state: "waiting", reason: options.signal?.aborted ? "interrupted" : "consent_timeout", elapsedMs: elapsedMs() });
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    try {
+        while (!signal.aborted && elapsedMs() < timeoutMs) {
+            let status;
+            try {
+                status = await bounded(options.readStatus(signal), signal);
+            }
+            catch (error) {
+                if (signal.aborted)
+                    return waiting();
+                if (error instanceof CliError && (error.status === 401 || error.status === 403))
+                    return { state: "refused", reason: "consent_identity_refused", elapsedMs: elapsedMs() };
+                return { state: "failed", reason: "consent_status_failed", elapsedMs: elapsedMs() };
+            }
+            if (elapsedMs() >= timeoutMs || signal.aborted)
+                return waiting();
+            if (status.outcome === "connected")
+                return { state: "done", elapsedMs: elapsedMs() };
+            if (status.outcome === "refused" || status.outcome === "failed")
+                return { state: status.outcome, reason: safeReason(status.reason, `consent_${status.outcome}`), elapsedMs: elapsedMs() };
+            const remaining = timeoutMs - elapsedMs();
+            try {
+                await bounded(sleep(Math.min(intervalMs, remaining)), signal);
+            }
+            catch {
+                return waiting();
+            }
+        }
+        return waiting();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}