agent-cloud-kit 1.0.0-rc.2 → 1.0.0-rc.4

package/README.md

@@ -43,6 +43,10 @@ platform does not tell you:
      commits, pushes and opens a draft PR.
    - **En la rama actual, sin commit:** does the same in your checkout and stops there; you review
      with `git diff`, commit, push, and then run `npx agent-cloud-kit verify`.
+
+   Before Claude opens, a short screen says what will happen and waits for Enter. If the repo uses
+   [claude-repo-guard](https://github.com/ramon-sg/claude-repo-guard) and has its `claude:free`
+   script, Claude opens through it, so the skill can write the files the guard blocks.
 3. **Configure the environment in claude.ai** following `docs/agent-cloud.md`, which `prepare`
    generated from your `.claude/cloud.json`. The document keeps growing: when the skill, locally
    or in the cloud, finds that a domain or an environment variable is missing, it adds it to

package/dist/cli.js

@@ -323,14 +323,24 @@ function onProcessInterrupt(handler) {
     return () => process.off("SIGINT", listener);
 }
 /**
- * Shows a text on the terminal and waits for Enter.
+ * Shows a text on the terminal and waits for Enter. Ctrl+C rejects with `InterruptedError`.
  *
- * @param text - Text to show.
+ * @param text - Text to show, printed as is.
+ * @throws InterruptedError on Ctrl+C.
  * @example
- * await waitTerminal("Presiona Enter");
+ * await waitTerminal("Presiona Enter ");
  */
 async function waitTerminal(text) {
-    await askTerminal(text, "");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        await new Promise((resolveAnswer, reject) => {
+            rl.on("SIGINT", () => reject(new InterruptedError()));
+            rl.question(text).then(resolveAnswer, reject);
+        });
+    }
+    finally {
+        rl.close();
+    }
 }
 /**
  * Runs `prepare` in the working directory.
@@ -385,6 +395,7 @@ function prepareDeps(deps) {
         packageRoot: deps.packageRoot ?? RUNNING_PACKAGE_ROOT,
         today: deps.today ?? branchDay(new Date()),
         isTty: deps.isTty ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+        color: deps.isTty === undefined && process.stdout.isTTY === true && !deps.env.NO_COLOR,
         onInterrupt: deps.onInterrupt ?? onProcessInterrupt,
     };
 }

package/dist/prepare/banner.js

@@ -0,0 +1,141 @@
+/**
+ * @file The screen `prepare` shows before opening Claude Code: a small cloud, what will happen and
+ * what the user has to do, in a few colored lines.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Script of claude-repo-guard that opens Claude without sandbox nor permission prompts. */
+export const FREE_SCRIPT = "claude:free";
+/**
+ * Wraps a text in an ANSI code when color is on.
+ *
+ * @param on - Whether color is on.
+ * @param code - SGR code, like `36` for cyan.
+ * @param text - Text.
+ * @returns The text, colored or not.
+ * @example
+ * paint(false, "36", "a"); // "a"
+ */
+function paint(on, code, text) {
+    return on ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+/**
+ * Renders the screen shown before opening Claude Code (without the Enter line, which the caller
+ * asks).
+ *
+ * @param input - Place, mode and color.
+ * @returns The lines.
+ * @example
+ * renderBanner({ place: "pr", free: false, color: false })[2]; // "     .-(    ).     Ahora se abre Claude Code"
+ */
+export function renderBanner(input) {
+    const c = (code, text) => paint(input.color, code, text);
+    const cloud = (text) => c("36", text);
+    const step = (n, text) => `   ${c("1;35", String(n))}  ${text}`;
+    const after = input.place === "pr" ? "prepare hace commit, push y PR" : "quedan los cambios sin commit";
+    const lines = [
+        "",
+        cloud("        .--."),
+        `${cloud("     .-(    ).")}     ${c("1", "Ahora se abre Claude Code")}`,
+        `${cloud("    (___.__)__)")}    ${c("2", "con la skill cloud-ready")}`,
+        "",
+        step(1, "Claude revisa el repo y te propone cómo prepararlo para la nube"),
+        step(2, "Responde sus preguntas"),
+        step(3, `Cuando diga ${c("1", "configure terminó")}, sal con ${c("1;33", "/exit")} ${c("2", `→ ${after}`)}`),
+    ];
+    if (input.free)
+        lines.push("", c("2", `   Se abre con ${FREE_SCRIPT} (sin sandbox ni preguntas de permisos): el repo usa claude-repo-guard`));
+    lines.push("");
+    return lines;
+}
+/**
+ * The line asked after the banner.
+ *
+ * @param color - Whether to use ANSI colors.
+ * @returns The text.
+ * @example
+ * enterLine(false); // "   ⏎ Enter abre Claude Code · Ctrl+C cancela "
+ */
+export function enterLine(color) {
+    return `   ${paint(color, "1;32", "⏎ Enter")} abre Claude Code ${paint(color, "2", "· Ctrl+C cancela")} `;
+}
+/**
+ * The line asked while the user configures the environment in claude.ai.
+ *
+ * @param color - Whether to use ANSI colors.
+ * @returns The text.
+ * @example
+ * continueLine(false); // "\n   ⏎ Enter cuando hayas configurado el entorno en claude.ai · abre la sesión cloud que lo verifica "
+ */
+export function continueLine(color) {
+    return `\n   ${paint(color, "1;32", "⏎ Enter")} cuando hayas configurado el entorno en claude.ai ${paint(color, "2", "· abre la sesión cloud que lo verifica")} `;
+}
+/** Config file claude-repo-guard installs; the free mode is used only when it is there. */
+const GUARD_CONFIG = ".claude/repo-guard.config.json";
+/**
+ * Tells whether the repo uses claude-repo-guard and has its `claude:free` script. Both are
+ * required: the free mode drops the sandbox and the permission prompts, so a script with that
+ * name alone is not enough.
+ *
+ * @param repo - Repo root.
+ * @returns True when the guard config exists and `package.json` has the script.
+ * @example
+ * hasFreeScript("/home/u/app"); // true
+ */
+export function hasFreeScript(repo) {
+    const file = join(repo, "package.json");
+    if (!existsSync(file) || !existsSync(join(repo, GUARD_CONFIG)))
+        return false;
+    try {
+        const scripts = JSON.parse(readFileSync(file, "utf8")).scripts;
+        return typeof scripts?.[FREE_SCRIPT] === "string";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The command that opens Claude with a prompt: the repo's `claude:free` script through its package
+ * manager, or `claude` itself.
+ *
+ * @param repo - Repo root.
+ * @param prompt - First prompt.
+ * @returns Command and arguments.
+ * @example
+ * claudeCommand("/home/u/app", "/cloud-ready configure"); // { cmd: "npm", args: ["run", "claude:free", "--", "/cloud-ready configure"] }
+ */
+export function claudeCommand(repo, prompt) {
+    if (!hasFreeScript(repo))
+        return { cmd: "claude", args: [prompt] };
+    const manager = packageManager(repo);
+    if (manager === "npm")
+        return { cmd: "npm", args: ["run", FREE_SCRIPT, "--", prompt] };
+    return { cmd: manager, args: ["run", FREE_SCRIPT, prompt] };
+}
+/** Lockfiles that tell the package manager, checked in order. */
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["yarn.lock", "yarn"],
+];
+/**
+ * The repo's package manager: `packageManager` in `package.json`, else the lockfile, else npm.
+ *
+ * @param repo - Repo root.
+ * @returns `npm`, `pnpm`, `yarn` or `bun`.
+ * @example
+ * packageManager("/home/u/app"); // "pnpm"
+ */
+function packageManager(repo) {
+    try {
+        const field = JSON.parse(readFileSync(join(repo, "package.json"), "utf8")).packageManager;
+        const name = typeof field === "string" ? field.split("@")[0] : undefined;
+        if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun")
+            return name;
+    }
+    catch {
+        // NOTE: no readable package.json; fall back to the lockfile.
+    }
+    return LOCKFILES.find(([file]) => existsSync(join(repo, file)))?.[1] ?? "npm";
+}

package/dist/prepare/index.js

@@ -6,11 +6,13 @@
 import { existsSync, lstatSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 import { readConfig } from "../config.js";
-import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "../constants.js";
+import { CONFIG_FILE, PACKAGE } from "../constants.js";
 import { defaultBranch } from "../detect.js";
 import { init } from "../init.js";
 import { MANUAL_FILE, renderEnvironmentSection, writeManual } from "../manual.js";
+import { claudeCommand, continueLine, enterLine, hasFreeScript, renderBanner } from "./banner.js";
 import { preflight } from "./detect.js";
+import { formatLine, initKind, nextSteps, styleMarkdown, unprefixed } from "./ui.js";
 import { configurePrompt, verifyPrompt } from "./prompts.js";
 /** Prefix of the branch `prepare` creates; the day follows it. */
 const BRANCH_PREFIX = "chore/cloud-ready-";
@@ -35,17 +37,12 @@ const INCLUDE_QUESTION = "¿Incluir estos cambios en el commit? [s/N]";
 /** Answers to `INCLUDE_QUESTION` that mean yes. */
 const YES_ANSWER = /^(s|si|sí|y|yes)$/i;
 /** Text shown while the user configures the environment in claude.ai. */
-const WAIT_TEXT = "Configura el entorno en claude.ai y luego presiona Enter";
 /** Matches a GitHub remote URL (https or ssh) and captures `owner/repo`. */
 const GITHUB_REMOTE = /github\.com[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/;
 /** Matches a pull request URL and captures its number. */
 const PR_URL = /\/pull\/(\d+)/;
 /** Command that continues a prepare run; `npx` because a first-time user does not have the binary on PATH. */
 const RESUME_COMMAND = `npx ${PACKAGE} prepare --resume`;
-/** Printed just before the local agent starts: `prepare` continues only when `claude` exits. */
-const EXIT_CLAUDE_HINT = `${OUTPUT_PREFIX}cuando la skill diga que configure terminó, sal de claude (/exit) y prepare hará el commit, el push y abrirá el PR`;
-/** Printed before the local agent starts in the current branch: nothing is committed. */
-const EXIT_CLAUDE_HINT_HERE = `${OUTPUT_PREFIX}cuando la skill diga que configure terminó, sal de claude (/exit)`;
 /** Question of the place menu. */
 const PLACE_QUESTION = "¿Dónde preparo el repo?";
 /** Command that launches the cloud verification of the current branch. */
@@ -78,6 +75,18 @@ export function branchDay(date) {
     const pad = (n) => String(n).padStart(2, "0");
     return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`;
 }
+/**
+ * Prints one line with the icon and color of its kind (or the plain prefix without color).
+ *
+ * @param deps - Dependencies (`print`, `color`).
+ * @param kind - Kind of line.
+ * @param text - Text, without prefix.
+ * @example
+ * say(deps, "ok", "PR en borrador: https://github.com/acme/app/pull/7");
+ */
+function say(deps, kind, text) {
+    deps.print(formatLine(kind, text, deps.color ?? false));
+}
 /**
  * Says where the worktree is and how to continue there.
  *
@@ -253,11 +262,11 @@ async function findResume(repo, deps) {
  */
 async function createAndConfigure(repo, branch, worktree, deps, progress) {
     if (existsSync(worktree)) {
-        deps.print(`${OUTPUT_PREFIX}${worktree} ya existe; bórralo (git worktree remove ${worktree}) o continúa ahí con ${RESUME_COMMAND}`);
+        say(deps, "fail", `${worktree} ya existe; bórralo (git worktree remove ${worktree}) o continúa ahí con ${RESUME_COMMAND}`);
         return false;
     }
     if ((await tryCapture(deps, "git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], repo)) !== undefined) {
-        deps.print(`${OUTPUT_PREFIX}la rama ${branch} ya existe; bórrala (git branch -D ${branch}) o corre prepare otro día`);
+        say(deps, "fail", `la rama ${branch} ya existe; bórrala (git branch -D ${branch}) o corre prepare otro día`);
         return false;
     }
     const base = `origin/${defaultBranch(repo)}`;
@@ -265,38 +274,40 @@ async function createAndConfigure(repo, branch, worktree, deps, progress) {
         await deps.run("git", ["fetch", "-q", "origin"], { cwd: repo });
         await deps.run("git", ["worktree", "add", "-b", branch, worktree, base], { cwd: repo });
         progress.worktree = worktree;
+        say(deps, "ok", `se creó el worktree ${worktree} en la rama ${branch}`);
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}no se pudo crear el worktree: ${message(err)}`);
+        say(deps, "fail", `no se pudo crear el worktree: ${message(err)}`);
         return false;
     }
     const stopped = resumeLine("el agente local se detuvo", worktree);
     try {
         const result = init(worktree, deps.packageVersion, deps.packageRoot);
         for (const line of result.lines)
-            deps.print(line);
+            say(deps, initKind(line), unprefixed(line));
         if (!result.ok) {
-            deps.print(stopped);
+            say(deps, "warn", stopped);
             return false;
         }
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}${message(err)}`);
-        deps.print(stopped);
+        say(deps, "fail", `${message(err)}`);
+        say(deps, "warn", stopped);
         return false;
     }
-    deps.print(EXIT_CLAUDE_HINT);
     try {
-        await runInteractive(deps, progress, [configurePrompt()], worktree);
+        await runConfigure(deps, progress, "pr", worktree);
     }
-    catch {
-        deps.print(stopped);
+    catch (err) {
+        if (err instanceof InterruptedError)
+            throw err;
+        say(deps, "warn", stopped);
         return false;
     }
     const problem = configureProblem(worktree);
     if (problem !== undefined) {
-        deps.print(`${OUTPUT_PREFIX}configure no terminó: ${problem}`);
-        deps.print(resumeLine("prepare se detuvo", worktree));
+        say(deps, "fail", `configure no terminó: ${problem}`);
+        say(deps, "warn", resumeLine("prepare se detuvo", worktree));
         return false;
     }
     return true;
@@ -323,44 +334,45 @@ async function commitAndPush(worktree, branch, deps) {
         const status = await deps.capture("git", ["status", "--porcelain=v1", "-z", "--untracked-files=all"], { cwd: worktree });
         const others = statusPaths(status).filter((path) => !covered(path, known));
         if (others.length) {
-            deps.print(`${OUTPUT_PREFIX}el agente local también cambió:`);
+            say(deps, "warn", `el agente local también cambió:`);
             for (const path of others)
-                deps.print(`  ${path}`);
+                deps.print(`    ${path}`);
             if (YES_ANSWER.test((await deps.ask(INCLUDE_QUESTION, "")).trim())) {
                 await deps.run("git", ["add", "--", ...others], { cwd: worktree });
             }
             else {
                 await deps.run("git", ["reset", "-q", "--", ...others], { cwd: worktree });
-                deps.print(`${OUTPUT_PREFIX}quedó sin commitear en ${worktree}`);
+                say(deps, "warn", `quedó sin commitear en ${worktree}`);
             }
         }
         const staged = await deps.capture("git", ["diff", "--cached", "--name-only"], { cwd: worktree });
         if (staged.trim())
             await deps.run("git", ["commit", "-m", COMMIT_MESSAGE], { cwd: worktree });
         else
-            deps.print(`${OUTPUT_PREFIX}no hay nada nuevo que commitear`);
+            say(deps, "same", `no hay nada nuevo que commitear`);
         await deps.run("git", ["push", "-u", "origin", branch], { cwd: worktree });
+        say(deps, "ok", `se subió la rama ${branch}`);
     }
     catch (err) {
         if (err instanceof InterruptedError)
             throw err;
-        deps.print(`${OUTPUT_PREFIX}no se pudo hacer commit y push: ${message(err)}; corrígelo en ${worktree} y corre ${RESUME_COMMAND} ahí`);
+        say(deps, "fail", `no se pudo hacer commit y push: ${message(err)}; corrígelo en ${worktree} y corre ${RESUME_COMMAND} ahí`);
         return false;
     }
     const existing = await tryCapture(deps, "gh", ["pr", "view", branch, "--json", "number", "--jq", ".number"], worktree);
     if (existing !== undefined && PR_NUMBER.test(existing)) {
-        deps.print(`${OUTPUT_PREFIX}se reutiliza el PR abierto #${existing}`);
+        say(deps, "ok", `se reutiliza el PR abierto #${existing}`);
         return { pr: existing };
     }
     try {
         const url = await deps.capture("gh", ["pr", "create", "--draft", "--fill"], { cwd: worktree });
-        deps.print(`${OUTPUT_PREFIX}PR en borrador: ${url.trim()}`);
+        say(deps, "ok", `PR en borrador: ${url.trim()}`);
         return { pr: PR_URL.exec(url)?.[1] };
     }
     catch {
         const origin = await tryCapture(deps, "git", ["remote", "get-url", "origin"], worktree);
         const link = compareLink(origin, branch);
-        deps.print(`${OUTPUT_PREFIX}no se pudo abrir el PR con gh; ábrelo a mano${link ? `: ${link}` : ` desde la rama ${branch}`}`);
+        say(deps, "warn", `no se pudo abrir el PR con gh; ábrelo a mano${link ? `: ${link}` : ` desde la rama ${branch}`}`);
         return {};
     }
 }
@@ -385,14 +397,14 @@ export async function prepare(repo, deps, options = {}) {
     const problems = preflight({ isTty: deps.isTty, gitRoot, hasOrigin, claudeHelp });
     if (problems.length || gitRoot === undefined) {
         for (const problem of problems)
-            deps.print(`${OUTPUT_PREFIX}${problem}`);
+            say(deps, "fail", `${problem}`);
         return EXIT_FAIL;
     }
     const progress = {};
     const stop = deps.onInterrupt?.(() => {
         if (progress.childOwnsTerminal)
             return false;
-        deps.print(interruptedLine(progress));
+        say(deps, "warn", interruptedLine(progress));
         return true;
     });
     try {
@@ -401,7 +413,7 @@ export async function prepare(repo, deps, options = {}) {
     catch (err) {
         if (!(err instanceof InterruptedError))
             throw err;
-        deps.print(interruptedLine(progress));
+        say(deps, "warn", interruptedLine(progress));
         return EXIT_INTERRUPTED;
     }
     finally {
@@ -414,34 +426,54 @@ export async function prepare(repo, deps, options = {}) {
  *
  * @param deps - Dependencies.
  * @param progress - Marks the child as owning the terminal.
- * @param args - Arguments of `claude`.
+ * @param command - Command and arguments that open Claude.
  * @param cwd - Worktree.
  * @returns Resolves when `claude` exits 0.
  * @throws When `claude` exits non-zero.
  * @example
- * await runInteractive(deps, progress, ["--cloud", prompt], "/home/u/app-cloud-ready");
+ * await runInteractive(deps, progress, { cmd: "claude", args: ["--cloud", prompt] }, "/home/u/app-cloud-ready");
  */
-async function runInteractive(deps, progress, args, cwd) {
+async function runInteractive(deps, progress, command, cwd) {
     progress.childOwnsTerminal = true;
     try {
-        await deps.run("claude", args, { cwd });
+        await deps.run(command.cmd, command.args, { cwd });
     }
     finally {
         progress.childOwnsTerminal = false;
     }
 }
+/**
+ * Shows the screen before Claude Code opens, waits for Enter, and runs the local agent with
+ * `cloud-ready configure` (through the repo's `claude:free` script when it has one).
+ *
+ * @param deps - Dependencies.
+ * @param progress - Marks the child as owning the terminal.
+ * @param place - Where `prepare` works.
+ * @param cwd - Folder where Claude runs.
+ * @returns Resolves when Claude exits 0.
+ * @throws InterruptedError on Ctrl+C at the Enter line; an error when Claude exits non-zero.
+ * @example
+ * await runConfigure(deps, progress, "pr", "/home/u/app-cloud-ready");
+ */
+async function runConfigure(deps, progress, place, cwd) {
+    const color = deps.color ?? false;
+    for (const line of renderBanner({ place, free: hasFreeScript(cwd), color }))
+        deps.print(line);
+    await deps.waitEnter(enterLine(color));
+    await runInteractive(deps, progress, claudeCommand(cwd, configurePrompt()), cwd);
+}
 /**
  * The line printed on Ctrl+C: where the worktree is, when it exists.
  *
  * @param progress - What exists so far.
  * @returns The line.
  * @example
- * interruptedLine({}); // "agent-cloud-kit: interrumpido; no se creó nada"
+ * interruptedLine({}); // "interrumpido; no se creó nada"
  */
 function interruptedLine(progress) {
     if (progress.here)
-        return `${OUTPUT_PREFIX}interrumpido; lo que alcanzó a cambiar quedó sin commit en tu rama`;
-    return progress.worktree === undefined ? `${OUTPUT_PREFIX}interrumpido; no se creó nada` : resumeLine("interrumpido", progress.worktree);
+        return "interrumpido; lo que alcanzó a cambiar quedó sin commit en tu rama";
+    return progress.worktree === undefined ? "interrumpido; no se creó nada" : resumeLine("interrumpido", progress.worktree);
 }
 /**
  * Everything after the preflight: resume or create the worktree, commit, wait, launch.
@@ -461,21 +493,21 @@ async function prepareSteps(gitRoot, deps, options, progress) {
     if (options.resume) {
         const found = await findResume(gitRoot, deps);
         if (!found) {
-            deps.print(`${OUTPUT_PREFIX}no hay nada que reanudar: corre prepare --resume en el worktree *${WORKTREE_SUFFIX}, sobre una rama ${BRANCH_PREFIX}*`);
+            say(deps, "fail", `no hay nada que reanudar: corre prepare --resume en el worktree *${WORKTREE_SUFFIX}, sobre una rama ${BRANCH_PREFIX}*`);
             return EXIT_FAIL;
         }
         ({ worktree, branch } = found);
         progress.worktree = worktree;
         const problem = configureProblem(worktree);
         if (problem) {
-            deps.print(`${OUTPUT_PREFIX}configure no terminó en ${worktree}: ${problem}; corre claude "/cloud-ready configure" ahí primero y luego ${RESUME_COMMAND}`);
+            say(deps, "fail", `configure no terminó en ${worktree}: ${problem}; corre claude "/cloud-ready configure" ahí primero y luego ${RESUME_COMMAND}`);
             return EXIT_FAIL;
         }
     }
     else {
         const place = options.place ?? (await askPlace(gitRoot, deps));
         if (place === null) {
-            deps.print(`${OUTPUT_PREFIX}no se cambió nada`);
+            say(deps, "same", `no se cambió nada`);
             return EXIT_FAIL;
         }
         if (place === "here")
@@ -490,16 +522,17 @@ async function prepareSteps(gitRoot, deps, options, progress) {
         return EXIT_FAIL;
     const config = readConfig(worktree).config;
     if (config)
-        deps.print(renderEnvironmentSection(config, deps.packageVersion));
-    await deps.waitEnter(WAIT_TEXT);
+        for (const line of styleMarkdown(renderEnvironmentSection(config, deps.packageVersion), deps.color ?? false))
+            deps.print(line);
+    await deps.waitEnter(continueLine(deps.color ?? false));
     try {
-        await runInteractive(deps, progress, ["--cloud", verifyPrompt({ branch, pr: pushed.pr })], worktree);
+        await runInteractive(deps, progress, { cmd: "claude", args: ["--cloud", verifyPrompt({ branch, pr: pushed.pr })] }, worktree);
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}falló claude --cloud: ${message(err)}; corre ${RESUME_COMMAND} en ${worktree} para reintentar`);
+        say(deps, "fail", `falló claude --cloud: ${message(err)}; corre ${RESUME_COMMAND} en ${worktree} para reintentar`);
         return EXIT_FAIL;
     }
-    deps.print(`${OUTPUT_PREFIX}la sesión cloud avisará con un push a ${branch} y un comentario en el PR`);
+    say(deps, "ok", `la sesión cloud avisará con un push a ${branch} y un comentario en el PR`);
     return EXIT_OK;
 }
 /**
@@ -530,45 +563,49 @@ async function askPlace(gitRoot, deps) {
  */
 async function prepareHere(gitRoot, deps, progress) {
     progress.here = true;
-    const stopped = `${OUTPUT_PREFIX}prepare se detuvo; lo que alcanzó a cambiar quedó sin commit en tu rama`;
+    const stopped = `prepare se detuvo; lo que alcanzó a cambiar quedó sin commit en tu rama`;
     try {
         const result = init(gitRoot, deps.packageVersion, deps.packageRoot);
         for (const line of result.lines)
-            deps.print(line);
+            say(deps, initKind(line), unprefixed(line));
         if (!result.ok) {
-            deps.print(stopped);
+            say(deps, "warn", stopped);
             return EXIT_FAIL;
         }
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}${message(err)}`);
-        deps.print(stopped);
+        say(deps, "fail", `${message(err)}`);
+        say(deps, "warn", stopped);
         return EXIT_FAIL;
     }
-    deps.print(EXIT_CLAUDE_HINT_HERE);
     try {
-        await runInteractive(deps, progress, [configurePrompt()], gitRoot);
+        await runConfigure(deps, progress, "here", gitRoot);
     }
-    catch {
-        deps.print(stopped);
+    catch (err) {
+        if (err instanceof InterruptedError)
+            throw err;
+        say(deps, "warn", stopped);
         return EXIT_FAIL;
     }
     const problem = configureProblem(gitRoot);
     if (problem !== undefined) {
-        deps.print(`${OUTPUT_PREFIX}configure no terminó: ${problem}; corre claude "/cloud-ready configure" y luego prepare otra vez`);
+        say(deps, "fail", `configure no terminó: ${problem}; corre claude "/cloud-ready configure" y luego prepare otra vez`);
         return EXIT_FAIL;
     }
     try {
         writeManual(gitRoot, deps.packageVersion);
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}no se pudo escribir ${MANUAL_FILE}: ${message(err)}`);
+        say(deps, "fail", `no se pudo escribir ${MANUAL_FILE}: ${message(err)}`);
         return EXIT_FAIL;
     }
     const config = readConfig(gitRoot).config;
     if (config)
-        deps.print(renderEnvironmentSection(config, deps.packageVersion));
-    deps.print(`${OUTPUT_PREFIX}listo, sin commit. Revisa los cambios con git diff, haz commit y push, configura el entorno en claude.ai (${MANUAL_FILE}) y corre ${VERIFY_COMMAND}`);
+        for (const line of styleMarkdown(renderEnvironmentSection(config, deps.packageVersion), deps.color ?? false))
+            deps.print(line);
+    const steps = ["Revisa los cambios con git diff", "Haz commit y push", `Configura el entorno en claude.ai (${MANUAL_FILE})`, `Corre ${VERIFY_COMMAND}`];
+    for (const line of nextSteps("Listo, sin commit", steps, deps.color ?? false))
+        deps.print(line);
     return EXIT_OK;
 }
 /**
@@ -589,30 +626,30 @@ export async function verifyBranch(repo, deps) {
     const problems = preflight({ isTty: deps.isTty, gitRoot, hasOrigin, claudeHelp }, "verify");
     if (problems.length || gitRoot === undefined) {
         for (const problem of problems)
-            deps.print(`${OUTPUT_PREFIX}${problem}`);
+            say(deps, "fail", `${problem}`);
         return EXIT_FAIL;
     }
     const branch = await tryCapture(deps, "git", ["rev-parse", "--abbrev-ref", "HEAD"], gitRoot);
     if (branch === undefined || branch === "HEAD") {
-        deps.print(`${OUTPUT_PREFIX}no estás en una rama; cámbiate a la rama que quieres verificar`);
+        say(deps, "fail", `no estás en una rama; cámbiate a la rama que quieres verificar`);
         return EXIT_FAIL;
     }
     const problem = configureProblem(gitRoot);
     if (problem !== undefined) {
-        deps.print(`${OUTPUT_PREFIX}el repo no está preparado (${problem}); corre npx ${PACKAGE} prepare primero`);
+        say(deps, "fail", `el repo no está preparado (${problem}); corre npx ${PACKAGE} prepare primero`);
         return EXIT_FAIL;
     }
     const notes = readConfig(gitRoot).config?.notes ?? DEFAULT_NOTES_FILE;
     const files = [CONFIG_FILE, MANUAL_FILE, notes].filter((path) => entryExists(join(gitRoot, path)));
     const dirty = await tryCapture(deps, "git", ["status", "--porcelain", "--", ...files], gitRoot);
     if (dirty) {
-        deps.print(`${OUTPUT_PREFIX}hay cambios sin commit en la preparación; haz commit y push: la nube solo ve lo que está en origin`);
+        say(deps, "fail", `hay cambios sin commit en la preparación; haz commit y push: la nube solo ve lo que está en origin`);
         return EXIT_FAIL;
     }
     const head = await tryCapture(deps, "git", ["rev-parse", "HEAD"], gitRoot);
     const remote = (await tryCapture(deps, "git", ["ls-remote", "origin", `refs/heads/${branch}`], gitRoot))?.split(/\s/)[0];
     if (!head || remote !== head) {
-        deps.print(`${OUTPUT_PREFIX}la rama ${branch} no está subida o tiene commits sin subir; haz git push y vuelve a correr verify`);
+        say(deps, "fail", `la rama ${branch} no está subida o tiene commits sin subir; haz git push y vuelve a correr verify`);
         return EXIT_FAIL;
     }
     const found = await tryCapture(deps, "gh", ["pr", "view", branch, "--json", "number", "--jq", ".number"], gitRoot);
@@ -620,15 +657,15 @@ export async function verifyBranch(repo, deps) {
     const progress = {};
     const stop = deps.onInterrupt?.(() => !progress.childOwnsTerminal);
     try {
-        await runInteractive(deps, progress, ["--cloud", verifyPrompt({ branch, pr })], gitRoot);
+        await runInteractive(deps, progress, { cmd: "claude", args: ["--cloud", verifyPrompt({ branch, pr })] }, gitRoot);
     }
     catch (err) {
-        deps.print(`${OUTPUT_PREFIX}falló claude --cloud: ${message(err)}`);
+        say(deps, "fail", `falló claude --cloud: ${message(err)}`);
         return EXIT_FAIL;
     }
     finally {
         stop?.();
     }
-    deps.print(`${OUTPUT_PREFIX}la sesión cloud avisará con un push a ${branch}${pr ? " y un comentario en el PR" : ""}`);
+    say(deps, "ok", `la sesión cloud avisará con un push a ${branch}${pr ? " y un comentario en el PR" : ""}`);
     return EXIT_OK;
 }

package/dist/prepare/ui.js

@@ -0,0 +1,128 @@
+/**
+ * @file How `prepare` and `verify` show their lines: an icon and a color per kind in a terminal,
+ * or the plain `agent-cloud-kit: ` prefix otherwise (logs, pipes, tests).
+ */
+import { OUTPUT_PREFIX } from "../constants.js";
+/** Icon and SGR color code of each kind. */
+const STYLE = {
+    ok: { icon: "✔", code: "32" },
+    same: { icon: "●", code: "2" },
+    info: { icon: "›", code: "36" },
+    warn: { icon: "▲", code: "33" },
+    fail: { icon: "✖", code: "31" },
+};
+/**
+ * Wraps a text in an SGR code when color is on.
+ *
+ * @param on - Whether color is on.
+ * @param code - SGR code.
+ * @param text - Text.
+ * @returns The text, colored or not.
+ * @example
+ * paint(true, "1", "a"); // "\x1b[1ma\x1b[0m"
+ */
+export function paint(on, code, text) {
+    return on ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+/**
+ * Formats one line.
+ *
+ * @param kind - Kind of line.
+ * @param text - Text, without prefix.
+ * @param color - Whether the output is a color terminal.
+ * @returns `  ✔ text` (icon colored; the text dimmed for `same`) or `agent-cloud-kit: text`.
+ * @example
+ * formatLine("ok", "se creó .claude/cloud.json", false); // "agent-cloud-kit: se creó .claude/cloud.json"
+ */
+export function formatLine(kind, text, color) {
+    if (!color)
+        return `${OUTPUT_PREFIX}${text}`;
+    const { icon, code } = STYLE[kind];
+    return `  ${paint(true, code, icon)} ${kind === "same" ? paint(true, "2", text) : text}`;
+}
+/**
+ * Guesses the kind of a line `init` printed, from its wording.
+ *
+ * @param text - Line, with or without the prefix.
+ * @returns `ok` for something done, `same` for something already there, `warn` otherwise.
+ * @example
+ * initKind("agent-cloud-kit: se creó .claude/cloud.json"); // "ok"
+ */
+export function initKind(text) {
+    const plain = text.startsWith(OUTPUT_PREFIX) ? text.slice(OUTPUT_PREFIX.length) : text;
+    if (/^se (creó|agregó|instaló|enlazó|actualizó|escribió)(\s|$)/.test(plain))
+        return "ok";
+    if (/\bya (existe|tiene|está)\b/.test(plain))
+        return "same";
+    return "warn";
+}
+/**
+ * Removes the `agent-cloud-kit: ` prefix of a line, if it has it.
+ *
+ * @param text - Line.
+ * @returns The line without prefix.
+ * @example
+ * unprefixed("agent-cloud-kit: hola"); // "hola"
+ */
+export function unprefixed(text) {
+    return text.startsWith(OUTPUT_PREFIX) ? text.slice(OUTPUT_PREFIX.length) : text;
+}
+/**
+ * Styles a Markdown section for the terminal: headings in bold (and cyan for `##`), code fences
+ * dropped and their lines indented, list items as bullets. Without color, the text is unchanged.
+ *
+ * @param markdown - Section text.
+ * @param color - Whether the output is a color terminal.
+ * @returns The lines.
+ * @example
+ * styleMarkdown("## A\n- b", true); // ["", "  \x1b[1;36mA\x1b[0m", "    • b"]
+ */
+export function styleMarkdown(markdown, color) {
+    if (!color)
+        return markdown.split("\n");
+    const out = [];
+    let inCode = false;
+    for (const line of markdown.split("\n")) {
+        if (line.startsWith("```")) {
+            inCode = !inCode;
+            continue;
+        }
+        if (inCode)
+            out.push(`      ${paint(true, "33", line)}`);
+        else if (line.startsWith("### "))
+            out.push(`  ${paint(true, "1", line.slice(4))}`);
+        else if (line.startsWith("## "))
+            out.push("", `  ${paint(true, "1;36", line.slice(3))}`);
+        else if (line.startsWith("- "))
+            out.push(`    ${paint(true, "36", "•")} ${inline(line.slice(2))}`);
+        else
+            out.push(line === "" ? "" : `  ${inline(line)}`);
+    }
+    return out;
+}
+/**
+ * Styles inline Markdown: `**bold**` in bold and `` `code` `` in yellow, without the marks.
+ *
+ * @param text - One line.
+ * @returns The styled line.
+ * @example
+ * inline("Elige **Custom**"); // "Elige \x1b[1mCustom\x1b[0m"
+ */
+function inline(text) {
+    return text.replace(/\*\*([^*]+)\*\*/g, (_m, bold) => paint(true, "1", bold)).replace(/`([^`]+)`/g, (_m, code) => paint(true, "33", code));
+}
+/**
+ * Renders a "what now" block: a title and numbered steps.
+ *
+ * @param title - Title.
+ * @param steps - Steps, in order.
+ * @param color - Whether the output is a color terminal.
+ * @returns The lines (without color: one prefixed line with the steps joined).
+ * @example
+ * nextSteps("Listo", ["haz commit"], false); // ["agent-cloud-kit: Listo. 1) haz commit"]
+ */
+export function nextSteps(title, steps, color) {
+    if (!color)
+        return [`${OUTPUT_PREFIX}${title}. ${steps.map((s, i) => `${i + 1}) ${s}`).join("; ")}`];
+    return ["", `  ${paint(true, "1;32", "✔")} ${paint(true, "1", title)}`, "", ...steps.map((s, i) => `   ${paint(true, "1;35", String(i + 1))}  ${s}`), ""];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-cloud-kit",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.4",
   "description": "Zero-dependency CLI that prepares Claude Code cloud sessions.",
   "type": "module",
   "license": "MIT",