@catalyst-cloud/cli 0.14.10 → 0.15.0

package/dist/setup-prompts.js

@@ -0,0 +1,108 @@
+// setup-prompts.ts — CTC-4625: the questions and the spinner `catalyst setup` shows on a terminal,
+// drawn by @clack/prompts. Questions read the terminal itself (/dev/tty): under `curl | sh` the
+// standard input is the download, never the person.
+import { closeSync, openSync } from "node:fs";
+import { ReadStream, WriteStream } from "node:tty";
+/** What a prompt assumes when the terminal reports no width (a pty opened without a size). clack
+ *  wraps each frame at the width it reads, and at 0 it printed one character per line. */
+const FALLBACK_COLUMNS = 80;
+/** Likewise for height: with 0 rows a select shows one option and "...". */
+const FALLBACK_ROWS = 24;
+/** The controlling terminal, or null when there is none (CI, a container with no TTY, a pipe). */
+export function openSetupTerminal(stdout) {
+    // @clack/core sizes each prompt frame from process.stdout.columns, whatever output it was given.
+    if (stdout.isTTY && !stdout.columns)
+        stdout.columns = FALLBACK_COLUMNS;
+    if (stdout.isTTY && !stdout.rows)
+        stdout.rows = FALLBACK_ROWS;
+    let readFd;
+    let writeFd;
+    try {
+        readFd = openSync("/dev/tty", "r");
+        writeFd = openSync("/dev/tty", "w");
+        const input = new ReadStream(readFd);
+        const output = new WriteStream(writeFd);
+        if (!output.columns)
+            output.columns = FALLBACK_COLUMNS;
+        if (!output.rows)
+            output.rows = FALLBACK_ROWS;
+        return {
+            input,
+            output,
+            close() {
+                input.destroy();
+                output.destroy();
+            },
+        };
+    }
+    catch {
+        if (readFd !== undefined)
+            closeSync(readFd);
+        if (writeFd !== undefined)
+            closeSync(writeFd);
+        return null;
+    }
+}
+export const CONTINUE_CHOICES = [
+    { value: "y", label: "Yes, start" },
+    { value: "e", label: "Change options (folders, daily update, local sync)" },
+    { value: "n", label: "Not now" },
+];
+/** Each question as a clack prompt on the terminal. A cancelled prompt (Ctrl-C, or the engine
+ *  gone) answers null; the caller decides what that means. */
+export function clackSetupAsk(clack, terminal) {
+    return async (event, r, gone) => {
+        const io = { input: terminal.input, output: terminal.output, signal: gone };
+        r.blank();
+        const question = event.question.replace(/\s*\[[^\]]*\]:?\s*$/, "");
+        if (event.id === "continue") {
+            const choice = await clack.select({
+                ...io,
+                message: "Start setup?",
+                options: CONTINUE_CHOICES,
+                initialValue: event.fallback || "y",
+            });
+            return clack.isCancel(choice) ? null : String(choice);
+        }
+        if (/^[yn]$/i.test(event.fallback)) {
+            const yes = await clack.confirm({
+                ...io,
+                message: question,
+                initialValue: /^y$/i.test(event.fallback),
+            });
+            return clack.isCancel(yes) ? null : yes ? "y" : "n";
+        }
+        const text = await clack.text({
+            ...io,
+            message: question,
+            placeholder: event.fallback,
+            defaultValue: event.fallback,
+        });
+        return clack.isCancel(text) ? null : String(text);
+    };
+}
+/**
+ * clack's spinner reads process.stdin for Ctrl-C and, on a terminal, puts it in raw mode, which
+ * would take Ctrl-C away from the engine. install.sh starts this command with stdin from
+ * /dev/null, so the spinner is used only then; a person running `catalyst setup` from a shell
+ * gets the plain waiting lines instead.
+ */
+export function clackSetupSpinner(clack, stdinIsTty) {
+    return (r, stream) => {
+        if (!r.traits.color || stdinIsTty)
+            return null;
+        const spin = clack.spinner({ output: process[stream], withGuide: false });
+        return {
+            start: (msg) => spin.start(msg),
+            message: (msg) => spin.message(msg),
+            stop: () => spin.clear(),
+        };
+    };
+}
+/** Prompt input/output always share the controlling terminal, even when progress is redirected. */
+export function setupOnboardStreams(terminal) {
+    return {
+        input: terminal?.input ?? process.stdin,
+        output: terminal?.output ?? process.stdout,
+    };
+}

package/dist/setup-render.js

@@ -0,0 +1,339 @@
+// setup-render.ts — CTC-4625: how `catalyst setup` looks. The terminal's traits come
+// from the stream and the environment, and every line goes through here: a pipe, a log or a dumb
+// terminal gets the same words in plain ASCII, never an escape sequence.
+//
+// ⛔ EVERY LINE IS WRITTEN WHEN IT IS PRINTED. Nothing here collects lines to wrap or align them
+// later: the sign-in code must reach the screen before the wait for approval starts (the 0.13.9
+// installer piped its login through fold, which held the code until the deadline discarded it).
+import { styleText } from "node:util";
+import { wrapAnsi } from "fast-wrap-ansi";
+import stringWidth from "fast-string-width";
+const DEFAULT_COLUMNS = 80;
+const MIN_COLUMNS = 40;
+function utf8Locale(env) {
+    return /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || "");
+}
+/**
+ * OSC 8 is shown only where a terminal is known to render it: an unknown one may print the escape
+ * as text. FORCE_HYPERLINK=1 or 0 overrides the list, as in the supports-hyperlinks convention.
+ */
+function hyperlinkTerminal(env) {
+    if (env.FORCE_HYPERLINK === "0")
+        return false;
+    if (env.FORCE_HYPERLINK === "1")
+        return true;
+    const program = env.TERM_PROGRAM ?? "";
+    if (["iTerm.app", "WezTerm", "vscode", "ghostty", "Hyper"].includes(program))
+        return true;
+    if ((env.TERM ?? "").includes("kitty") || env.TERM === "alacritty")
+        return true;
+    if (env.WT_SESSION)
+        return true;
+    const vte = Number.parseInt(env.VTE_VERSION ?? "", 10);
+    return Number.isFinite(vte) && vte >= 5000;
+}
+export function terminalTraits(stream, env) {
+    const fancy = stream.isTTY === true &&
+        env.NO_COLOR === undefined &&
+        Boolean(env.TERM) &&
+        env.TERM !== "dumb" &&
+        utf8Locale(env);
+    let columns = DEFAULT_COLUMNS;
+    if (stream.isTTY === true &&
+        typeof stream.columns === "number" &&
+        stream.columns > 0)
+        columns = stream.columns;
+    else if (/^[1-9][0-9]{0,3}$/.test(env.COLUMNS ?? ""))
+        columns = Number(env.COLUMNS);
+    return {
+        color: fancy,
+        unicode: fancy,
+        links: fancy && hyperlinkTerminal(env),
+        columns: Math.max(MIN_COLUMNS, columns),
+    };
+}
+const ASCII_MARKS = {
+    done: "[done]",
+    fail: "[fail]",
+    act: "[!]",
+    skip: "[skip]",
+    later: "[later]",
+    run: "[..]",
+    ask: "[?]",
+};
+const UNICODE_MARKS = {
+    done: ["✓", "green"],
+    fail: ["✗", "red"],
+    act: ["▲", "yellow"],
+    skip: ["–", "gray"],
+    later: ["·", "gray"],
+    run: ["◐", "cyan"],
+    ask: ["◆", "cyan"],
+};
+export function createSetupRenderer(stream, env) {
+    let traits = terminalTraits(stream, env);
+    const style = (format, text) => traits.color ? styleText(format, text, { validateStream: false }) : text;
+    let width = Math.min(traits.columns, 100);
+    const refresh = () => {
+        const next = terminalTraits(stream, env);
+        if (live && next.columns !== traits.columns)
+            live.resized = true;
+        traits = next;
+        width = Math.min(traits.columns, 100);
+    };
+    let frame = 1;
+    const visible = (text) => text
+        .replace(/\u001b\]8;;[^\u001b]*\u001b\\/g, "")
+        .replace(/\u001b\[[0-9;]*m/g, "");
+    const rail = traits.unicode ? "│" : "";
+    const titleCol = traits.unicode ? 6 : 11;
+    const outcomeCol = traits.unicode ? 38 : 43;
+    const prefix = (col) => rail + " ".repeat(col - rail.length);
+    const mark = (kind) => {
+        if (!traits.unicode)
+            return ASCII_MARKS[kind];
+        const [glyph, colour] = UNICODE_MARKS[kind];
+        return style(colour, kind === "run" ? ["◒", "◐", "◓", "◑"][frame % 4] : glyph);
+    };
+    const rows = (text, col) => {
+        refresh();
+        const indent = /^ */.exec(text)?.[0].length ?? 0;
+        col += indent;
+        text = text.slice(indent);
+        return wrapAnsi(text, Math.max(1, width - col), {
+            hard: false,
+            wordWrap: true,
+            trim: true,
+        })
+            .split("\n")
+            .map((line) => {
+            const plain = visible(line);
+            const indent = /^https?:\/\/\S+$/.test(plain) && stringWidth(plain) > width - col
+                ? traits.unicode
+                    ? 3
+                    : 0
+                : col;
+            return prefix(indent) + line;
+        });
+    };
+    const stepRows = (kind, number, title, outcome, plan = false) => {
+        refresh();
+        const lead = plan
+            ? traits.unicode
+                ? "│"
+                : "       "
+            : traits.unicode
+                ? mark(kind)
+                : mark(kind).padEnd(7);
+        const titleWidth = stringWidth(visible(title));
+        const label = `${lead}${traits.unicode ? "  " : " "}${String(number || "").padStart(2)} ${title}`;
+        if (!outcome)
+            return [label];
+        if (width < 80 || titleWidth > 30)
+            return [label, ...rows(outcome, titleCol)];
+        const padding = " ".repeat(Math.max(2, 32 - titleWidth));
+        const wrapped = wrapAnsi(outcome, width - outcomeCol, {
+            hard: false,
+            wordWrap: true,
+            trim: true,
+        }).split("\n");
+        return [
+            `${label}${padding}${wrapped[0]}`,
+            ...wrapped.slice(1).map((l) => prefix(outcomeCol) + l),
+        ];
+    };
+    const write = (lines) => stream.write(lines.join("\n") + "\n");
+    let live;
+    const clear = () => {
+        if (live && traits.unicode && !live.resized && live.height)
+            stream.write(`\u001b[${live.height}A\r\u001b[J`);
+    };
+    let workingTimer;
+    const flushWorking = () => {
+        if (workingTimer) {
+            clearTimeout(workingTimer);
+            workingTimer = undefined;
+            paint();
+        }
+    };
+    let listening = false;
+    const releaseListener = () => {
+        if (listening) {
+            process.off("SIGWINCH", resize);
+            listening = false;
+        }
+    };
+    const abandon = () => {
+        if (workingTimer)
+            clearTimeout(workingTimer);
+        workingTimer = undefined;
+        live = undefined;
+        releaseListener();
+    };
+    const paint = () => {
+        if (!live || live.resized)
+            return;
+        const lines = [
+            ...stepRows(live.mark, live.number, style("bold", live.title), live.status),
+            ...live.details.flatMap((t) => rows(t, titleCol)),
+        ];
+        const physicalWidth = stream.columns && stream.columns > 0 ? stream.columns : traits.columns;
+        const physicalRows = lines.reduce((n, line) => n + Math.max(1, Math.ceil(stringWidth(visible(line)) / physicalWidth)), 0);
+        if (traits.unicode) {
+            clear();
+            write(lines);
+            live.height = physicalRows;
+            // A taller block cannot be safely erased in a short terminal. Keep its scrollback instead.
+            if (physicalRows > 8)
+                live.resized = true;
+        }
+        else if (!live.height) {
+            write(lines);
+            live.height = physicalRows;
+        }
+    };
+    const resize = () => {
+        if (live)
+            live.resized = true;
+        refresh();
+    };
+    const ordinary = (lines) => {
+        if (live && traits.unicode && !live.resized) {
+            clear();
+            live.height = 0;
+            write(lines);
+            if (!workingTimer)
+                paint();
+        }
+        else
+            write(lines);
+    };
+    const suspendLive = () => {
+        clear();
+        abandon();
+    };
+    const r = {
+        get traits() {
+            refresh();
+            return traits;
+        },
+        intro(title) {
+            refresh();
+            ordinary([traits.unicode ? `┌  ${style("bold", title)}` : title]);
+        },
+        outro(text) {
+            abandon();
+            write(traits.unicode ? [`│`, `└  ${text}`] : ["", text]);
+        },
+        plan(number, title, text) {
+            ordinary(stepRows("run", number, title, text, true));
+            if (width < 80)
+                r.blank();
+        },
+        begin(number, title, status = "checking…", kind = "run") {
+            if (live?.number === number)
+                suspendLive();
+            else
+                abandon();
+            if (traits.unicode && !listening) {
+                process.on("SIGWINCH", resize);
+                listening = true;
+            }
+            live = {
+                number,
+                title,
+                status,
+                mark: kind,
+                details: [],
+                height: 0,
+                resized: false,
+            };
+            if (status === "checking…" && kind === "run") {
+                workingTimer = setTimeout(() => {
+                    workingTimer = undefined;
+                    paint();
+                }, 300);
+                workingTimer.unref();
+            }
+            else
+                paint();
+        },
+        update(status) {
+            if (live) {
+                live.status = status;
+                frame++;
+                if (workingTimer && /waiting|new code/.test(status))
+                    flushWorking();
+                else if (!workingTimer)
+                    paint();
+            }
+        },
+        resolve(kind, outcome) {
+            if (!live)
+                return;
+            const { number, title } = live;
+            clear();
+            abandon();
+            write(stepRows(kind, number, title, outcome));
+        },
+        suspendLive,
+        promptRows(rows) {
+            if (live) {
+                if (rows === null)
+                    live.resized = true;
+                else
+                    live.height += rows;
+            }
+        },
+        dispose() {
+            abandon();
+        },
+        step(kind, number, title, outcome) {
+            if (live && live.number === number)
+                r.resolve(kind, outcome);
+            else
+                ordinary(stepRows(kind, number, title, outcome));
+        },
+        detail(text) {
+            flushWorking();
+            if (live && traits.unicode && !live.resized) {
+                live.details.push(text);
+                paint();
+            }
+            else
+                write(rows(text, titleCol));
+        },
+        replaceLastDetail(text) {
+            if (live && traits.unicode && !live.resized && live.details.length) {
+                live.details[live.details.length - 1] = text;
+                paint();
+            }
+            else
+                r.detail(text);
+        },
+        action(text) {
+            r.detail(style("bold", text));
+        },
+        heading(text) {
+            abandon();
+            write(traits.unicode ? ["│", `├─ ${style("bold", text)}`] : ["", text]);
+        },
+        line(text) {
+            ordinary(rows(text, traits.unicode ? 3 : 0));
+        },
+        blank() {
+            refresh();
+            ordinary([rail]);
+        },
+        link(url) {
+            return traits.links
+                ? `\u001b]8;;${url}\u001b\\${url}\u001b]8;;\u001b\\`
+                : url;
+        },
+        bold: (text) => style("bold", text),
+        dim: (text) => style("dim", text),
+        verdict: (ok, text) => style(["bold", ok ? "green" : "red"], text),
+        mark,
+    };
+    return r;
+}

package/dist/setup-signin.js

@@ -0,0 +1,187 @@
+// setup-signin.ts — CTC-4625: step 4 of `catalyst setup`, the browser sign-in, drawn in this process.
+//
+// ⛔ THE CODE IS WRITTEN THE MOMENT THE SERVER SENDS IT. The device flow hands each code to
+// `present`, which writes straight to the output stream before the wait for approval begins; no
+// filter, wrap buffer or relay process sits between them (the 0.13.9 installer piped the login
+// through fold, which held the code until the deadline discarded it).
+import { realpathSync } from "node:fs";
+import { join, relative } from "node:path";
+import { loadConfig, saveConfig } from "./config.js";
+import { CliError } from "./errors.js";
+const PLAIN_REMINDER_MS = 60_000;
+function clock(ms) {
+    const total = Math.max(0, Math.ceil(ms / 1000));
+    const minutes = Math.floor(total / 60);
+    return `${minutes}:${String(total % 60).padStart(2, "0")}`;
+}
+function limitWords(seconds) {
+    if (seconds <= 0)
+        return "";
+    if (seconds < 60)
+        return ` (up to ${seconds} seconds)`;
+    const minutes = Math.ceil(seconds / 60);
+    return ` (up to ${minutes} minute${minutes === 1 ? "" : "s"})`;
+}
+/** The host a link opens, named when it is not Catalyst Cloud's own, so the page is not a surprise. */
+function vendorNote(code) {
+    let host;
+    try {
+        host = new URL(code.completeUri ?? code.verificationUri).host;
+    }
+    catch {
+        return null;
+    }
+    if (host === "catalystcloud.dev" || host.endsWith(".catalystcloud.dev"))
+        return null;
+    return `That page is Catalyst's sign-in page, hosted by WorkOS.`;
+}
+export async function runSetupSignin(ctx, r, seconds, deps) {
+    const now = deps.now ?? Date.now;
+    const reason = "This connects this computer to your Catalyst account, so catalyst and your coding agent can act for you.";
+    r.detail(reason);
+    const deadline = new AbortController();
+    const timer = seconds > 0
+        ? setTimeout(() => deadline.abort(), seconds * 1000)
+        : undefined;
+    const signal = deps.interrupted
+        ? AbortSignal.any([deadline.signal, deps.interrupted])
+        : deadline.signal;
+    const started = now();
+    const progress = () => seconds > 0
+        ? `${clock(started + seconds * 1000 - now())} left`
+        : `${clock(now() - started)} so far`;
+    let hintInFrame = false;
+    let round = 1, rounds = 1;
+    const waitingWords = () => `${round > 1 ? `new code ${round} of ${rounds}` : "waiting for you"} · ${progress()}`;
+    const present = (code) => {
+        round = code.round;
+        rounds = code.rounds;
+        if (code.round > 1) {
+            r.begin(4, "Sign in to Catalyst", `new code ${code.round} of ${code.rounds} · ${progress()}`);
+            r.detail(reason);
+            hintInFrame = false;
+        }
+        r.action("Open this link and approve this computer:");
+        if (code.completeUri)
+            r.detail(r.link(code.completeUri));
+        r.detail(`Or open ${r.link(code.verificationUri)} and enter ${code.userCode}.`);
+        const note = vendorNote(code);
+        if (note)
+            r.detail(note);
+        if (code.round > 1) {
+            r.detail("Ctrl-C stops setup.");
+            hintInFrame = true;
+        }
+    };
+    const presentBrowser = (opened) => {
+        if (opened)
+            r.detail("Your browser opened that page.");
+    };
+    const waitForApproval = async (run) => {
+        let tick;
+        if (r.traits.unicode) {
+            r.update(waitingWords());
+            if (!hintInFrame)
+                r.detail("Ctrl-C stops setup.");
+            hintInFrame = true;
+            tick = setInterval(() => r.update(waitingWords()), 1000);
+        }
+        else {
+            r.detail(`waiting for you${limitWords(seconds > 0 ? Math.max(0, Math.ceil((started + seconds * 1000 - now()) / 1000)) : seconds)}.${hintInFrame ? "" : " Ctrl-C stops setup."}`);
+            hintInFrame = true;
+            tick = setInterval(() => {
+                const minutes = Math.max(0, Math.ceil((started + seconds * 1000 - now()) / 60000));
+                if (minutes > 0)
+                    r.detail(`Still waiting, ${minutes} minute${minutes === 1 ? "" : "s"} left.`);
+            }, PLAIN_REMINDER_MS);
+        }
+        try {
+            return await run();
+        }
+        finally {
+            clearInterval(tick);
+        }
+    };
+    // The login's own lines repeat what this step already shows, so they are kept, not printed; the
+    // last one is the reason when the login ends without signing in.
+    const logged = [];
+    const log = (line) => {
+        if (line.trim())
+            logged.push(line.trim());
+        deps.log?.(line);
+    };
+    const quiet = { ...ctx, stdout: log, stderr: log };
+    try {
+        const code = await deps.login(quiet, {
+            signal,
+            present,
+            presentBrowser,
+            waitForApproval,
+        });
+        if (code === 0)
+            return "done";
+        r.detail(`The sign-in did not finish: ${logged.at(-1) ?? `catalyst login exited ${code}`}`);
+        return "failed";
+    }
+    catch (error) {
+        if (deps.interrupted?.aborted)
+            return "cancelled";
+        if (deadline.signal.aborted)
+            return "timeout";
+        if (error instanceof CliError && error.code === "login-expired")
+            return "timeout";
+        deps.log?.(error instanceof Error ? error.message : String(error));
+        r.detail(`The sign-in did not finish: ${error instanceof Error ? error.message : String(error)}`);
+        return "failed";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * install.sh may run `catalyst setup` from a temporary install (CATALYST_INSTALL_TEMP_CLI) that is
+ * removed when setup ends. The sign-in records the running command's path for skill scripts to
+ * spawn, so once it is saved, point it at the installed `catalyst` on PATH (step 1 installed it).
+ * An installed command running setup keeps its own path.
+ */
+export function keepInstalledCliPath(ctx, running) {
+    const given = ctx.env.CATALYST_INSTALL_TEMP_CLI;
+    if (!given)
+        return;
+    let temporary;
+    try {
+        temporary = realpathSync(given);
+        running = realpathSync(running);
+    }
+    catch {
+        return;
+    }
+    if (relative(temporary, running).startsWith(".."))
+        return;
+    const cfg = loadConfig(ctx.home);
+    if (!cfg?.cliPath)
+        return;
+    try {
+        if (realpathSync(cfg.cliPath) !== running)
+            return;
+    }
+    catch {
+        return;
+    }
+    for (const dir of (ctx.env.PATH ?? "").split(":")) {
+        if (!dir)
+            continue;
+        let installed;
+        try {
+            installed = realpathSync(join(dir, "catalyst"));
+        }
+        catch {
+            continue;
+        }
+        if (!relative(temporary, installed).startsWith(".."))
+            continue;
+        cfg.cliPath = installed;
+        saveConfig(ctx.home, cfg);
+        return;
+    }
+}