@catalyst-cloud/cli 0.13.1 → 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/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);
+    }
+}