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

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,130 @@
+/**
+ * @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")} `;
+}
+/** 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

@@ -10,6 +10,7 @@ import { CONFIG_FILE, OUTPUT_PREFIX, PACKAGE } from "../constants.js";
 import { defaultBranch } from "../detect.js";
 import { init } from "../init.js";
 import { MANUAL_FILE, renderEnvironmentSection, writeManual } from "../manual.js";
+import { claudeCommand, enterLine, hasFreeScript, renderBanner } from "./banner.js";
 import { preflight } from "./detect.js";
 import { configurePrompt, verifyPrompt } from "./prompts.js";
 /** Prefix of the branch `prepare` creates; the day follows it. */
@@ -35,17 +36,13 @@ 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";
+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. */
@@ -285,11 +282,12 @@ async function createAndConfigure(repo, branch, worktree, deps, progress) {
         deps.print(stopped);
         return false;
     }
-    deps.print(EXIT_CLAUDE_HINT);
     try {
-        await runInteractive(deps, progress, [configurePrompt()], worktree);
+        await runConfigure(deps, progress, "pr", worktree);
     }
-    catch {
+    catch (err) {
+        if (err instanceof InterruptedError)
+            throw err;
         deps.print(stopped);
         return false;
     }
@@ -414,22 +412,42 @@ 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.
  *
@@ -493,7 +511,7 @@ async function prepareSteps(gitRoot, deps, options, progress) {
         deps.print(renderEnvironmentSection(config, deps.packageVersion));
     await deps.waitEnter(WAIT_TEXT);
     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`);
@@ -545,11 +563,12 @@ async function prepareHere(gitRoot, deps, progress) {
         deps.print(stopped);
         return EXIT_FAIL;
     }
-    deps.print(EXIT_CLAUDE_HINT_HERE);
     try {
-        await runInteractive(deps, progress, [configurePrompt()], gitRoot);
+        await runConfigure(deps, progress, "here", gitRoot);
     }
-    catch {
+    catch (err) {
+        if (err instanceof InterruptedError)
+            throw err;
         deps.print(stopped);
         return EXIT_FAIL;
     }
@@ -620,7 +639,7 @@ 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)}`);

package/package.json

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