@catalyst-cloud/cli 0.13.1 → 0.14.1

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/legacy.js

@@ -6,8 +6,8 @@
 //
 // 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";
+// read at the source commit below, and nothing else. Shared data folders are always kept. The historical --data flag cannot remove them.
+import { existsSync, lstatSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join } from "node:path";
 import { flagBool, positionals } from "./args.js";
@@ -47,8 +47,8 @@ const OLD_ROLE_PREFIX = "com.catalyst.role.";
 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_BINS = [".local/bin/catalyst-events", ".local/bin/catalyst-filter", ".local/bin/catalyst-hud", ".local/bin/catalyst-monitor", ".local/bin/catalyst-myown"];
+/** Shared roots also hold current skills, logs, hosts and seats. Never remove these directories. */
 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) {
@@ -138,11 +138,10 @@ function remove(item, run, platform, uid) {
             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);
+        // CTC-4496: even explicit --data cannot delete shared roots. Unknown directories stay too.
+        if (item.data || lstatSync(item.path).isDirectory())
+            return "directory kept; shared data is protected";
+        unlinkSync(item.path);
         return null;
     }
     catch (err) {
@@ -171,10 +170,10 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     }
     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)" : ""}`),
+        ...found.map((f) => `  ${f.kind}: ${f.name}${f.kind === "job" ? ` — ${f.path}` : f.data ? " (kept: shared current state)" : ""}`),
     ];
     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)"]);
+        emit({ sourceCommit: LEGACY_SOURCE_COMMIT, found, removed: [], remaining: found }, [...listLines, RECOMMEND, "Run: catalyst legacy --remove (all data folders are kept)"]);
         return 1;
     }
     // the one question, only on a terminal; --yes answers it without asking
@@ -182,13 +181,13 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     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)"]);
+            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 (all data folders are kept)"]);
             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();
+        const answer = (await (deps.prompt ?? ((q) => promptSecret(q)))(`Remove ${found.length} item${found.length === 1 ? "" : "s"}, keeping all 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"]);
@@ -200,9 +199,9 @@ export async function cmdLegacy(args, ctx, deps = {}) {
     const kept = [];
     const lines = [];
     for (const item of found) {
-        if (item.data && !withData) {
+        if (item.data) {
             kept.push(item);
-            lines.push(`kept: ${item.kind} ${item.name} (run with --data to delete it)`);
+            lines.push(`kept: ${item.kind} ${item.name} (shared current state; always kept)`);
             continue;
         }
         const why = remove(item, run, platform, uid);
@@ -216,8 +215,8 @@ export async function cmdLegacy(args, ctx, deps = {}) {
         }
     }
     // 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" : "";
+    const remaining = findLegacy(ctx.home, platform).filter((f) => !f.data);
+    const keptNote = kept.length > 0 ? "; all shared data folders were 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);
+    }
+}