bottleship 0.1.0-prototype.0 → 0.1.0-prototype.2

package/dist/src/init.d.ts

@@ -1,12 +1,11 @@
 import { type UI } from "./ui.ts";
-export declare const INSTRUCTIONS = "## Remote agents with bottleship\n\nYou can run other coding agents in remote sandboxes (\"boxes\") with the `bottleship` CLI, like subagents. Every command prints JSON; errors carry a `fix`.\n\n- Start remote work with `bottleship new \"<prompt>\"` from inside the repo (or `--repo owner/name`). Write a complete prompt: the task, the context it needs, and what done means, including \"work on branch <name>, commit and push as you go, and open a PR when done\". The box agent sees nothing of this conversation.\n- Treat each box as a subagent you manage. `new` returns an id; keep track of your ids yourself, bottleship keeps no list.\n- If `new` or `ask` returns a `login`, show the user its URL and code; the box agent starts once they approve it in their browser.\n- `bottleship status <id>` shows whether the agent is still running and the tail of its output; `--wait <seconds>` blocks until it finishes.\n- `bottleship ask <id> \"<follow-up>\"` continues the same conversation once the agent has finished.\n- `bottleship exec <id> -- <cmd>` inspects the box (git log, test output, files).\n- `bottleship rm <id>` when the work is merged or abandoned. If a box is gone, start a new one on the pushed branch.\n- If the user wants to watch or steer a box from their IDE, find out how their IDE attaches to an agent over a command (ACP) and give it `bottleship exec -i <id> -- <the agent's ACP command>`.\n- Secrets: never ask the user to paste a secret to you. If bottleship reports one missing, ask them to run `bottleship init` in their terminal.";
+export declare const INSTRUCTIONS = "## Remote agents with bottleship\n\nThe `bottleship` CLI runs coding agents in boxes, isolated dev environments for a repo (Docker containers by default), and builds guided reviews of PRs and of local changes, which the user opens in their browser. Your commands are under `bottleship agent`; run `bottleship agent help` before you first use them in a session, for what each does and how to use it.\n\n- Use a box for work that can run on its own while you do something else, and treat it as a subagent you manage.\n- When the user wants to review a PR, start the review for them and give them its url.\n- Reviews of your own work: after a big change you made on your own (many files, or behaviour that is hard to see in the diff), start a local review before you hand over and give the user its url, unless the user has said otherwise. Skip it for small changes.\n- If the user stops or interrupts you while you start a review, or turns one down, ask them once when they want reviews (after every big change, only when they ask, never, or something else). Then rewrite the line above in this section of your instructions file to say exactly what they chose, and follow it from then on.\n- Secrets: never ask the user to paste a secret to you. If bottleship reports one missing, ask them to run `bottleship init` in their terminal.";
 export interface InitFlags {
     provider?: string;
-    host?: string;
-    name?: string;
     agent?: string;
     gitName?: string;
     gitEmail?: string;
-    noIsolation?: boolean;
+    reset?: boolean;
 }
 export declare function init(flags: InitFlags, ui?: UI): Promise<Record<string, unknown>>;
+export declare function setUp(cwd: string, flags: InitFlags, ui: UI): Promise<void>;

package/dist/src/init.js

@@ -1,69 +1,41 @@
-// One-time onboarding: provider, agent, git identity, secrets, then a live check.
-// Re-running it only asks for what is missing. Without a UI it never prompts.
+// Setup: this machine (provider, agent, git identity, secrets, a live check), then on a terminal the repo it runs in.
+// Re-running it only asks for what is missing. Without a UI it never prompts and does only the machine.
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { CONFIG_FILE, HOME, ROOT } from "./paths.js";
-import { BsError, DEFAULTS, getAgent, getProvider, isSource, loadConfig, neededSecrets, noIsolationAccepted, noIsolationError, readUserConfig, unisolated, writeUserConfig } from "./config.js";
-import { describe, hasSecret, storeSecret } from "./secrets.js";
-import { agentState, loginState, missingSecrets, newBoxId, setupAndStart, templateSpec, waitAgent } from "./boxes.js";
+import { BsError, DEFAULTS, getAgent, loadConfig, missingSecrets, neededSecrets, readUserConfig, writeUserConfig } from "./config.js";
+import { describe, forgetSecret, hasSecret, storeSecret } from "./secrets.js";
+import { createBox, startAgent, waitAgent } from "./boxes.js";
+import { providerNames } from "./provider.js";
+import { openLocalAgent } from "./local.js";
+import { ONBOARD_PROMPT } from "./onboard.js";
+import { checkout, readRepoEnv } from "./repo.js";
 import { c } from "./ui.js";
 export const INSTRUCTIONS = `## Remote agents with bottleship
 
-You can run other coding agents in remote sandboxes ("boxes") with the \`bottleship\` CLI, like subagents. Every command prints JSON; errors carry a \`fix\`.
+The \`bottleship\` CLI runs coding agents in boxes, isolated dev environments for a repo (Docker containers by default), and builds guided reviews of PRs and of local changes, which the user opens in their browser. Your commands are under \`bottleship agent\`; run \`bottleship agent help\` before you first use them in a session, for what each does and how to use it.
 
-- Start remote work with \`bottleship new "<prompt>"\` from inside the repo (or \`--repo owner/name\`). Write a complete prompt: the task, the context it needs, and what done means, including "work on branch <name>, commit and push as you go, and open a PR when done". The box agent sees nothing of this conversation.
-- Treat each box as a subagent you manage. \`new\` returns an id; keep track of your ids yourself, bottleship keeps no list.
-- If \`new\` or \`ask\` returns a \`login\`, show the user its URL and code; the box agent starts once they approve it in their browser.
-- \`bottleship status <id>\` shows whether the agent is still running and the tail of its output; \`--wait <seconds>\` blocks until it finishes.
-- \`bottleship ask <id> "<follow-up>"\` continues the same conversation once the agent has finished.
-- \`bottleship exec <id> -- <cmd>\` inspects the box (git log, test output, files).
-- \`bottleship rm <id>\` when the work is merged or abandoned. If a box is gone, start a new one on the pushed branch.
-- If the user wants to watch or steer a box from their IDE, find out how their IDE attaches to an agent over a command (ACP) and give it \`bottleship exec -i <id> -- <the agent's ACP command>\`.
+- Use a box for work that can run on its own while you do something else, and treat it as a subagent you manage.
+- When the user wants to review a PR, start the review for them and give them its url.
+- Reviews of your own work: after a big change you made on your own (many files, or behaviour that is hard to see in the diff), start a local review before you hand over and give the user its url, unless the user has said otherwise. Skip it for small changes.
+- If the user stops or interrupts you while you start a review, or turns one down, ask them once when they want reviews (after every big change, only when they ask, never, or something else). Then rewrite the line above in this section of your instructions file to say exactly what they chose, and follow it from then on.
 - Secrets: never ask the user to paste a secret to you. If bottleship reports one missing, ask them to run \`bottleship init\` in their terminal.`;
 const CHECK_PROMPT = "This is a connection check. Reply with exactly: bottleship-ok";
-// by secret name, else by store name; agent tokens carry their own hint in the preset
+// by secret name; agent tokens carry their own hint in the preset
 const HINTS = {
     GH_TOKEN: "create a fine-grained token at https://github.com/settings/personal-access-tokens/new: Repository access \"Only select repositories\" (the repos boxes work on), " +
         "Repository permissions Contents and Pull requests \"Read and write\" (Metadata read-only comes with them). Boxes get only what it allows, so a runaway agent cannot touch your other repos. Paste it below",
-    e2b: "create an API key at https://e2b.dev/dashboard and paste it",
-    daytona: "create an API key at https://app.daytona.io/dashboard/keys and paste it",
-    "modal-token-id": "run `modal token new` or create a token at https://modal.com/settings/tokens, and paste its id",
-    "modal-token-secret": "paste the secret of the same Modal token (from `modal token new` or https://modal.com/settings/tokens)",
-};
-const PROVIDER_HINTS = {
-    docker: "containers on this machine",
-    exe: "exe.dev VMs",
-    e2b: "e2b.dev cloud sandboxes",
-    daytona: "daytona.io cloud sandboxes",
-    modal: "modal.com cloud sandboxes",
-    ssh: "a machine you can ssh into, no isolation",
-    local: "git worktrees on this machine, no isolation, stops when the laptop sleeps",
-    custom: "your company's sandboxes, via their API or CLI",
 };
+const PROVIDER_HINTS = { docker: "containers on this machine" };
 // also the order of the agent menu; agents from config.json come after these
 const AGENT_HINTS = {
-    claude: "Claude Code",
-    codex: "OpenAI Codex CLI",
-    opencode: "opencode, runs its free models without a login",
-    cursor: "Cursor CLI (cursor-agent)",
+    claude: "Claude Code, with your subscription's setup token",
+    codex: "OpenAI Codex CLI, with an API key",
+    opencode: "opencode, with an OpenCode Zen API key",
+    cursor: "Cursor CLI (cursor-agent), with an API key",
 };
 const README = join(ROOT, "README.md");
-// copies the HTTP template to ~/.bottleship/providers/<name>.ts, never over an existing file
-function scaffoldProvider(raw, name) {
-    if (!/^[a-z][a-z0-9-]*$/.test(name))
-        throw new BsError("bad_name", `"${name}" is not a provider name`, "use lowercase letters, digits and dashes, e.g. --name corp");
-    if (name === "custom" || name in DEFAULTS.providers)
-        throw new BsError("bad_name", `"${name}" is a builtin provider`, "pick another --name, e.g. your company's name");
-    const file = join(HOME, "providers", `${name}.ts`);
-    if (!existsSync(file)) {
-        const template = readFileSync(join(ROOT, "presets/providers/http.example.ts"), "utf8");
-        mkdirSync(join(HOME, "providers"), { recursive: true });
-        writeFileSync(file, template.replace(/^import type \{ ProviderFactory \} from .*$/m, 'import type { ProviderFactory } from "bottleship";'));
-    }
-    raw.providers = { ...raw.providers, [name]: { ...raw.providers?.[name], module: `providers/${name}.ts` } };
-    return file;
-}
 const localGit = (key) => {
     try {
         return execFileSync("git", ["config", key], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
@@ -76,60 +48,57 @@ const localGit = (key) => {
 function storeAndPoint(raw, secret, value) {
     const source = "store" in secret.source ? secret.source : { store: secret.name.toLowerCase().replace(/[^a-z0-9-]+/g, "-") };
     storeSecret(source.store, value);
-    if ("store" in secret.source)
-        return source;
-    const m = secret.name.match(/^providers\.([^.]+)\.(.+)$/);
-    if (m) {
-        const spec = { ...loadConfig(raw).providers[m[1]], ...raw.providers?.[m[1]], [m[2]]: source };
-        raw.providers = { ...raw.providers, [m[1]]: spec };
-    }
-    else
+    if (!("store" in secret.source))
         raw.env = { ...(raw.env ?? DEFAULTS.env), [secret.name]: source };
     return source;
 }
+// local agents that keep a global instructions file get a prompt to add the section to it
+const teachPrompt = (a) => a.name === "cursor-agent"
+    ? `Write the text below as the Cursor user rule file ${a.file}, so you can use bottleship in every project. Give it this frontmatter, then the text: "---" / "description: How to run coding agents in remote boxes with bottleship" / "alwaysApply: true" / "---". Replace the file if it exists. Show me the file before you write it.\n\n${INSTRUCTIONS}`
+    : `Add the section below to your global instructions file ${a.file}, so you can use bottleship in every project. If the file already has a "## Remote agents with bottleship" section, replace it; keep everything else as it is, and create the file if it does not exist. Show me the change before you write it.\n\n${INSTRUCTIONS}`;
+const TEACH_YOURSELF = 'Add `instructions` to your own global instructions file (e.g. ~/.claude/CLAUDE.md for Claude Code, ~/.codex/AGENTS.md for Codex, a rule file ~/.cursor/rules/bottleship.mdc with `alwaysApply: true` for Cursor), replacing an older "## Remote agents with bottleship" section, and show the user the change.';
+// the store names of saved logins the config refers to, for reset to offer forgetting
+function savedLogins(cfg) {
+    const names = new Set();
+    const walk = (v) => {
+        if (!v || typeof v !== "object")
+            return;
+        if ("store" in v && typeof v.store === "string" && hasSecret({ store: v.store }))
+            names.add(v.store);
+        Object.values(v).forEach(walk);
+    };
+    walk(cfg);
+    return [...names].sort();
+}
+async function reset(ui) {
+    if (!existsSync(CONFIG_FILE))
+        return;
+    if (ui && !(await ui.confirm("Start over? Your current setup is set aside and every question comes back.")))
+        throw new BsError("reset_cancelled", "nothing changed", "bottleship init");
+    const saved = savedLogins(loadConfig(readUserConfig()));
+    renameSync(CONFIG_FILE, `${CONFIG_FILE}.bak`);
+    // only a human on the terminal can forget saved logins
+    if (ui && saved.length && (await ui.confirm(`Also forget the saved logins (${saved.join(", ")})?`)))
+        saved.forEach(forgetSecret);
+}
 export async function init(flags, ui) {
+    if (flags.reset)
+        await reset(ui);
     const raw = readUserConfig();
     let cfg = loadConfig(raw);
-    ui?.intro();
-    const pick = async (key, question, options) => {
+    const pick = async (key, question, options, fix) => {
         const known = options.map((o) => o.value);
-        const value = flags[key] ?? raw[key] ?? (ui ? await ui.choose(question, options, cfg[key]) : cfg[key]);
+        const value = flags[key] ?? raw[key] ?? (ui && known.length > 1 ? await ui.choose(question, options, cfg[key]) : cfg[key]);
         if (!known.includes(value))
-            throw new BsError(`unknown_${key}`, `no ${key} "${value}"`, `known: ${known.join(", ")}`);
-        if (ui && (flags[key] || raw[key]))
+            throw new BsError(`unknown_${key}`, `no ${key} "${value}"`, `known: ${known.join(", ")}. ${fix}`);
+        if (ui)
             ui.ok(`${key} ${c.bold(value)}`);
         return value;
     };
-    const choices = [...Object.entries(cfg.providers).map(([value, s]) => ({ value, hint: PROVIDER_HINTS[value] ?? s.module })), { value: "custom", hint: PROVIDER_HINTS.custom }];
-    let provider = await pick("provider", "Where should boxes run?", choices);
-    let module;
-    if (provider === "custom") {
-        const name = flags.name ?? (ui ? await ui.text("A short name for your sandbox provider", "corp") : "");
-        if (!name)
-            throw new BsError("missing_name", "a custom provider needs a name", "pass --name <name>, e.g. --name corp");
-        module = scaffoldProvider(raw, name);
-        provider = name;
-    }
-    if (cfg.providers[provider]?.module === "builtin:ssh") {
-        const host = flags.host ?? cfg.providers[provider].host ?? (ui ? await ui.text("SSH host for boxes (anything ssh accepts, e.g. a ~/.ssh/config alias)") : "");
-        if (!host)
-            throw new BsError("missing_host", "the ssh provider needs a host", "pass --host <host>, anything `ssh <host>` accepts");
-        raw.providers = { ...raw.providers, [provider]: { ...cfg.providers[provider], host } };
-    }
-    if (unisolated(cfg, provider) && !noIsolationAccepted(cfg, provider)) {
-        const warning = `${provider} runs box agents as you, on ${provider === "local" ? "this machine" : "that host"}, with no sandbox and with their permission prompts off. An agent misled by a prompt, a repo or a web page can read, change or send anything you can reach there, including your files, keys and logins.`;
-        if (ui)
-            ui.warn("No isolation", warning);
-        const ok = flags.noIsolation || (ui ? await ui.confirm(`Run agents on ${provider} with no isolation anyway?`) : false);
-        if (!ok)
-            throw noIsolationError(provider);
-        raw.providers = { ...raw.providers, [provider]: { ...cfg.providers[provider], ...raw.providers?.[provider], acceptNoIsolation: true } };
-    }
+    const provider = await pick("provider", "Where should boxes run?", providerNames().map((value) => ({ value, hint: PROVIDER_HINTS[value] ?? join(HOME, "providers", value) })), `For another sandbox, an agent writes its scripts into ${join(HOME, "providers", "<name>")}, see "Providers" in ${README}`);
     const rank = (a) => (a in AGENT_HINTS ? Object.keys(AGENT_HINTS).indexOf(a) : Infinity);
     const agents = Object.keys(cfg.agents).sort((a, b) => rank(a) - rank(b));
-    // a first choice from the menu, as opposed to a flag or an earlier run
-    const picked = Boolean(ui && !flags.agent && !raw.agent);
-    const agent = await pick("agent", "Which agent runs in a box?", agents.map((value) => ({ value, hint: AGENT_HINTS[value] })));
+    const agent = await pick("agent", "Which agent runs in a box?", agents.map((value) => ({ value, hint: AGENT_HINTS[value] })), `Add one under "agents" in ${CONFIG_FILE}`);
     const gitValue = async (key, flag) => {
         const v = flag ?? raw.git?.[key] ?? (ui ? await ui.text(`Git ${key} for commits from boxes`, localGit(`user.${key}`)) : localGit(`user.${key}`));
         if (ui && (flag || raw.git?.[key]))
@@ -142,23 +111,10 @@ export async function init(flags, ui) {
     Object.assign(raw, { provider, agent, git });
     writeUserConfig(raw);
     cfg = loadConfig(raw);
-    // a new custom provider has only TODOs, so secrets and the live check wait for the next run
-    if (module) {
-        const next = `fill in the TODOs in ${module} following "Custom providers" in ${README}, then run \`bottleship init\` again to check it`;
-        if (ui) {
-            ui.note("Next", `Ask your agent to fill in the TODOs in ${module}, following the "Custom providers" section of ${README}. Then run \`bottleship init\` again to check it.`);
-            ui.close(c.green(`Provider ${provider} is set up as a template.`));
-        }
-        return { ok: true, config: CONFIG_FILE, provider, agent, git, module, next };
-    }
     ui?.section("Secrets");
-    if (await agentLogin(raw, cfg, agent, picked, ui)) {
-        writeUserConfig(raw);
-        cfg = loadConfig(raw);
-    }
-    const token = getAgent(cfg, agent).login?.token;
+    const login = getAgent(cfg, agent).login;
     const secrets = [];
-    for (const s of neededSecrets(cfg, provider, agent)) {
+    for (const s of neededSecrets(cfg, agent)) {
         let source = s.source;
         let ok = hasSecret(source);
         if (!ok && ui && s.name === "GH_TOKEN" && (await useGhAuthToken(ui))) {
@@ -171,10 +127,10 @@ export async function init(flags, ui) {
         }
         else if (!ok && ui) {
             ui.warn(`${s.name} is missing`, `looked in ${describe(source)}`);
-            const hint = s.name === token?.env ? token.hint : undefined;
-            ui.say(`    ${hint ?? HINTS[s.name] ?? HINTS["store" in s.source ? s.source.store : ""] ?? "paste the value"}`);
-            if (token?.command && s.name === token.env && (await ui.confirm(`Run \`${token.command}\` now? Paste the token it prints below.`)))
-                await ui.handOver(token.command);
+            const isLogin = s.name === login?.env;
+            ui.say(`    ${(isLogin ? login?.hint : undefined) ?? HINTS[s.name] ?? "paste the value"}`);
+            if (isLogin && login?.command && (await ui.confirm(`Run \`${login.command}\` now? Paste the token it prints below.`)))
+                await ui.handOver(login.command);
             const value = await ui.secret(`${s.name}`);
             if (value) {
                 source = storeAndPoint(raw, s, value);
@@ -191,19 +147,62 @@ export async function init(flags, ui) {
         throw missingSecrets(missing);
     cfg = loadConfig(raw);
     ui?.section(`Live check: ${provider} + ${agent}`);
-    const checks = await liveCheck(raw, cfg, provider, agent, ui);
+    const checks = await liveCheck(cfg, provider, agent, ui);
     const ok = checks.every((ch) => ch.ok);
     if (ui) {
         const failed = checks.find((ch) => !ch.ok);
         if (failed)
             ui.fail(`${failed.step} failed`, JSON.stringify(failed.error));
-        else {
-            ui.note("Add this to your agent's global instructions (e.g. ~/.claude/CLAUDE.md)", INSTRUCTIONS);
-            ui.say(`config  ${c.dim(CONFIG_FILE)}\nboxes   ${provider} running ${agent}, committing as ${git.name} <${git.email}>`);
-            ui.close(c.green("All set. Tell your agent to start something in a box."));
+    }
+    return { ok, config: CONFIG_FILE, provider, agent, git, secrets, checks, instructions: INSTRUCTIONS, ...(ok && { next: TEACH_YOURSELF }) };
+}
+// a machine is set up once its config names a provider, an agent and a git identity, and every secret they need is there
+function machineReady() {
+    if (!existsSync(CONFIG_FILE))
+        return undefined;
+    const raw = readUserConfig();
+    if (!raw.provider || !raw.agent || !raw.git?.name || !raw.git?.email)
+        return undefined;
+    const cfg = loadConfig(raw);
+    try {
+        return neededSecrets(cfg, cfg.agent).every((s) => hasSecret(s.source)) ? cfg : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// a person's setup: this machine unless it is set up, then the repo at cwd if they want it set up for boxes.
+// One session of their local agent adds bottleship to its instructions and writes .bottleship/, whichever is needed.
+export async function setUp(cwd, flags, ui) {
+    ui.intro();
+    const ready = flags.reset ? undefined : machineReady();
+    if (ready)
+        ui.ok(`this machine is set up: ${ready.provider} running ${ready.agent}`, "bottleship init --reset starts over");
+    else if (!(await init(flags, ui)).ok)
+        return;
+    const learn = !ready;
+    const repo = checkout(cwd);
+    const onboard = !!repo && (readRepoEnv(repo.root)
+        ? await ui.confirm(`${repo.root} already has a box environment. Have your agent go over it again?`)
+        : await ui.confirm(`Set up ${repo.root} for boxes?`));
+    if (onboard) {
+        ui.say(`Your agent works out how ${repo.root} runs in a box and writes .bottleship/. It checks its work in real boxes and asks you before changing anything else in the repo.`);
+        // the agent starts where it is handed the terminal
+        process.chdir(repo.root);
+    }
+    if (learn || onboard) {
+        const hint = (a) => [learn && `adds bottleship to ${a.file}`, onboard && "sets up the repo with you"].filter(Boolean).join(", then ");
+        const prompt = (a) => [learn && teachPrompt(a), onboard && ONBOARD_PROMPT].filter(Boolean).join("\n\nWhen that is done, set up this repository:\n\n");
+        if (!(await openLocalAgent(ui, "Which agent on this machine should do this?", hint, prompt))) {
+            if (learn)
+                ui.note("Add this to your agent's global instructions (e.g. ~/.claude/CLAUDE.md)", INSTRUCTIONS);
+            if (onboard)
+                ui.note("Give this to your coding agent, from the repo root", ONBOARD_PROMPT);
         }
     }
-    return { ok, config: CONFIG_FILE, provider, agent, git, secrets, checks, instructions: INSTRUCTIONS };
+    if (!repo)
+        ui.say(`Run ${c.bold("bottleship init")} in a repo to set it up for boxes, then ${c.bold("bottleship review")} there.`);
+    ui.close(c.green("All set."));
 }
 // boxes push and open PRs with GH_TOKEN: a fine-grained token by default, the gh CLI's token only after a warning
 async function useGhAuthToken(ui) {
@@ -217,50 +216,8 @@ async function useGhAuthToken(ui) {
     ui.warn("`gh auth token` is your full gh login", "every box can push to, and open PRs or delete branches in, every repo your account can reach, including other organizations'");
     return ui.confirm("Give boxes your gh login anyway?");
 }
-// a user entry for a builtin agent only needs the fields it overrides, see loadConfig
-const patchAgent = (raw, name, patch) => {
-    const before = raw.agents?.[name];
-    const login = patch.login && { ...before?.login, ...patch.login };
-    raw.agents = { ...raw.agents, [name]: { ...before, ...patch, ...(login && { login }) } };
-};
-const tokenNames = (login) => (login.tokens ?? [login.token]).map((t) => t.env).join(", ");
-const routeHint = (login, route) => route === "token" ? `${login.tokens ? `an API key (${tokenNames(login)})` : login.token.env}${login.token.command ? ` from \`${login.token.command}\`` : ""}, kept in bottleship's store`
-    : route === "device" ? "log in inside each box: bottleship shows you a URL and code to approve for every new box"
-        : "no login, e.g. free models";
-// asks for the login route on a first choice or a missing token, and which key on the token route; returns whether raw changed
-async function agentLogin(raw, cfg, agentName, picked, ui) {
-    const login = getAgent(cfg, agentName).login;
-    if (!login || !ui)
-        return false;
-    const ready = (route) => {
-        if (route !== "token" || !login.token)
-            return true;
-        const source = cfg.env[login.token.env] ?? { store: login.token.store };
-        return !isSource(source) || hasSecret(source);
-    };
-    let use = login.use;
-    const ask = picked || !ready(use);
-    const patch = {};
-    if (login.routes.length > 1 && ask) {
-        use = (await ui.choose(`How does ${agentName} log in inside boxes?`, login.routes.map((r) => ({ value: r, hint: routeHint(login, r) })), use));
-        if (use !== login.use)
-            patch.use = use;
-    }
-    if (use === "token" && login.tokens && ask) {
-        const env = await ui.choose(`Which key does ${agentName} use?`, login.tokens.map((t) => ({ value: t.env, hint: t.hint })), login.token?.env ?? login.tokens[0].env);
-        const token = login.tokens.find((t) => t.env === env);
-        if (token.env !== login.token?.env)
-            patch.token = token;
-    }
-    if (use === "device" && login.device?.setup)
-        ui.note(`Once, before boxes can log ${agentName} in`, login.device.setup);
-    if (!Object.keys(patch).length)
-        return false;
-    patchAgent(raw, agentName, { login: patch });
-    return true;
-}
-// the template (recorded in raw), create, exec, the agent's setup, its device login, one reply, destroy; stops at the first failure but always destroys
-async function liveCheck(raw, cfg, providerName, agent, ui) {
+// create (which builds the base image the first time), exec, one reply from the agent, destroy; stops at the first failure but always destroys
+async function liveCheck(cfg, providerName, agent, ui) {
     const checks = [];
     const step = async (name, fn) => {
         const t0 = Date.now();
@@ -275,23 +232,9 @@ async function liveCheck(raw, cfg, providerName, agent, ui) {
         }
     };
     let b;
-    let template;
-    const provider = await getProvider(cfg, providerName);
-    const login = getAgent(cfg, agent).login;
-    const device = login?.use === "device" ? login.device : undefined;
     const check = async () => {
-        // the provider finds a template it already built, so a rerun with the same spec is quick
-        if (provider.template && !(await step("build the box template", async () => {
-            const spec = templateSpec(cfg, agent);
-            template = await provider.template(spec);
-            raw.templates = { ...raw.templates, [providerName]: { name: spec.name, ref: template } };
-            writeUserConfig(raw);
-            return template;
-        })))
-            return;
-        if (!(await step("create a box", async () => {
-            const { id } = await provider.create({ id: newBoxId("check"), ...(template && { template }) });
-            b = { id: `${providerName}:${id}`, provider, box: id };
+        if (!(await step("create a box (builds the image the first time, minutes)", async () => {
+            b = await createBox(cfg, { provider: providerName, label: "check", agent });
         })))
             return;
         if (!(await step("run a command", async () => {
@@ -300,36 +243,8 @@ async function liveCheck(raw, cfg, providerName, agent, ui) {
                 throw new Error(`expected bottleship-ok, got exit ${r.code}: ${r.stdout}${r.stderr}`);
         })))
             return;
-        if (!(await step(`set up ${agent}`, () => setupAndStart(cfg, b, { agent, prompt: CHECK_PROMPT }))))
-            return;
-        if (device) {
-            let pending;
-            if (!(await step(`${agent} logs in`, async () => {
-                const s = await loginState(b, device.setup);
-                if (s.agent !== "waiting_for_login")
-                    return;
-                if (!ui)
-                    throw new BsError("login_needs_human", `${agent} logs in inside each box with a device login, which a human has to approve`, "ask the user to run `bottleship init` in their terminal and approve the login it shows. Boxes from `bottleship new` return the same kind of login for you to show the user", { login: s.login });
-                pending = s.login;
-                return s.login.url;
-            })))
-                return;
-            if (pending) {
-                ui.note(`Approve the ${agent} login`, `Open ${pending.url}${pending.code ? `\nand enter the code ${pending.code}` : ""}\n\nEvery new box asks for this.`);
-                if (!(await step("waiting for you to approve the login", async () => {
-                    const until = Date.now() + ((device.timeout ?? 900) + 10) * 1000;
-                    let s = await agentState(b);
-                    while (s.agent === "waiting_for_login" && Date.now() < until) {
-                        await new Promise((r) => setTimeout(r, 1000));
-                        s = await agentState(b);
-                    }
-                    if (s.agent === "waiting_for_login" || s.agent === "login_failed")
-                        throw new Error(`the login was not approved: ${s.log.slice(-500)}`);
-                })))
-                    return;
-            }
-        }
         await step(`${agent} replies`, async () => {
+            await startAgent(b, CHECK_PROMPT);
             const s = await waitAgent(b, 300);
             if (s.agent === "running")
                 throw new Error("no reply within 5 minutes");
@@ -340,6 +255,6 @@ async function liveCheck(raw, cfg, providerName, agent, ui) {
     };
     await check();
     if (b)
-        await step("destroy the box", async () => void (await b.provider.destroy(b.box)));
+        await step("destroy the box", () => b.provider.destroy(b.box));
     return checks;
 }

package/dist/src/local.d.ts

@@ -0,0 +1,8 @@
+import type { UI } from "./ui.ts";
+export interface LocalAgent {
+    name: string;
+    file: string;
+    open(prompt: string): string;
+}
+export declare const LOCAL_AGENTS: LocalAgent[];
+export declare function openLocalAgent(ui: UI, question: string, hint: (a: LocalAgent) => string, prompt: (a: LocalAgent) => string): Promise<boolean>;

package/dist/src/local.js

@@ -0,0 +1,24 @@
+// The coding agents on this machine, and opening one with a prompt in the terminal.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { shq } from "./util.js";
+export const LOCAL_AGENTS = [
+    { name: "claude", file: "~/.claude/CLAUDE.md", open: (prompt) => `claude ${shq(prompt)}` },
+    { name: "codex", file: "~/.codex/AGENTS.md", open: (prompt) => `codex ${shq(prompt)}` },
+    { name: "opencode", file: "~/.config/opencode/AGENTS.md", open: (prompt) => `opencode --prompt ${shq(prompt)}` },
+    // Cursor reads user rule files from ~/.cursor/rules (https://cursor.com/help/customization/rules)
+    { name: "cursor-agent", file: "~/.cursor/rules/bottleship.mdc", open: (prompt) => `cursor-agent ${shq(prompt)}` },
+];
+const onPath = (bin) => (process.env.PATH ?? "").split(":").some((d) => d && existsSync(join(d, bin)));
+// asks which installed agent to open and hands it the terminal with its prompt; false when there is none or the user skips
+export async function openLocalAgent(ui, question, hint, prompt) {
+    const found = LOCAL_AGENTS.filter((a) => onPath(a.name));
+    if (!found.length)
+        return false;
+    const pick = await ui.choose(question, [...found.map((a) => ({ value: a.name, hint: hint(a) })), { value: "skip", hint: "show the text to copy instead" }], found[0].name);
+    const agent = found.find((a) => a.name === pick);
+    if (!agent)
+        return false;
+    await ui.handOver(agent.open(prompt(agent)));
+    return true;
+}

package/dist/src/onboard.d.ts

@@ -0,0 +1,5 @@
+export declare const ONBOARD_PROMPT = "Set up this repository to run in bottleship boxes, so agents and reviewers can run the app in a fresh, isolated box.\n\nA box is a Docker container from a Debian bookworm image with Node 22, git, gh, curl and ripgrep. It runs as a non-root user `box` without sudo. The repo's files are in ~/workspace. Describe this repo's box in three files under .bottleship/, committed with the repo:\n\n- .bottleship/Dockerfile (optional): lines appended to bottleship's base image, run as root. No FROM, and no COPY or ADD of local files, since the build has no context. Use it for system packages, language runtimes and services, e.g. `RUN apt-get update && apt-get install -y --no-install-recommends postgresql && rm -rf /var/lib/apt/lists/*`. Add `EXPOSE <port>` for each port a person should open, such as the web app; bottleship publishes those and waits for them.\n- .bottleship/setup.sh: runs once as `box` in ~/workspace, after the code is there: install dependencies, create and migrate databases, load seed data, build. It must not prompt, and running it twice must be fine.\n- .bottleship/start.sh: starts the services the app needs, then the app in the foreground, as `box`. Bottleship runs it in the background, logs it to ~/.bottleship/app.log, and waits until every EXPOSEd port accepts connections. The app must listen on 0.0.0.0, not only on localhost, or the published port cannot reach it.\n\nHow to go about it:\n\n1. Learn how the project runs today: README, CONTRIBUTING, package manifests and lockfiles, Makefile or justfile, docker-compose files, devcontainer config, CI workflows, .env.example. Prefer the commands CI uses; they already run on a fresh machine.\n2. Run services (databases, caches, queues) inside the box, not shared remote ones. For third-party APIs, use test credentials or the project's mock or offline mode.\n3. Secrets: never write secret values into .bottleship/. Boxes get the .env files at the root of this checkout (.env, .env.local and so on, not .env.example). If the app needs values that are not there, ask me which ones to use, and prefer dev or test credentials.\n4. Check your work with `bottleship agent onboard --check` from the repo root. It builds the box from this working tree (uncommitted changes included), runs setup.sh and start.sh, waits for the EXPOSEd ports, and prints JSON: the stage it reached (ready or failed), the log of what failed, and a URL on this machine for each port. Look inside a box with `bottleship agent exec <id> -- <command>` (logs are in ~/.bottleship/ there) and remove it with `bottleship agent rm <id>`. Repeat until check reports ready, then confirm the app really serves, e.g. `curl` its URL and look at the response. Remove every box you created.\n5. Then look for changes to the repo itself that would make it easier to run in a box or for a reviewer to try: one command for setup, a seed script with useful demo data, config read from env instead of hardcoded hosts, a mock mode for external services, a complete .env.example, faster installs. List each with why it helps and how much work it is, and only make the ones I agree to, separately from the .bottleship/ files.\n6. Finish with a short summary: what the box runs, what check reported, what does not work in a box yet and why. Suggest committing .bottleship/.";
+export declare function onboardPrompt(cwd: string): {
+    root: string;
+    prompt: string;
+};

package/dist/src/onboard.js

@@ -0,0 +1,25 @@
+// Onboarding a repo: the instructions for the agent that works out how it runs in a box and writes .bottleship/.
+import { BsError } from "./config.js";
+import { checkout } from "./repo.js";
+export const ONBOARD_PROMPT = `Set up this repository to run in bottleship boxes, so agents and reviewers can run the app in a fresh, isolated box.
+
+A box is a Docker container from a Debian bookworm image with Node 22, git, gh, curl and ripgrep. It runs as a non-root user \`box\` without sudo. The repo's files are in ~/workspace. Describe this repo's box in three files under .bottleship/, committed with the repo:
+
+- .bottleship/Dockerfile (optional): lines appended to bottleship's base image, run as root. No FROM, and no COPY or ADD of local files, since the build has no context. Use it for system packages, language runtimes and services, e.g. \`RUN apt-get update && apt-get install -y --no-install-recommends postgresql && rm -rf /var/lib/apt/lists/*\`. Add \`EXPOSE <port>\` for each port a person should open, such as the web app; bottleship publishes those and waits for them.
+- .bottleship/setup.sh: runs once as \`box\` in ~/workspace, after the code is there: install dependencies, create and migrate databases, load seed data, build. It must not prompt, and running it twice must be fine.
+- .bottleship/start.sh: starts the services the app needs, then the app in the foreground, as \`box\`. Bottleship runs it in the background, logs it to ~/.bottleship/app.log, and waits until every EXPOSEd port accepts connections. The app must listen on 0.0.0.0, not only on localhost, or the published port cannot reach it.
+
+How to go about it:
+
+1. Learn how the project runs today: README, CONTRIBUTING, package manifests and lockfiles, Makefile or justfile, docker-compose files, devcontainer config, CI workflows, .env.example. Prefer the commands CI uses; they already run on a fresh machine.
+2. Run services (databases, caches, queues) inside the box, not shared remote ones. For third-party APIs, use test credentials or the project's mock or offline mode.
+3. Secrets: never write secret values into .bottleship/. Boxes get the .env files at the root of this checkout (.env, .env.local and so on, not .env.example). If the app needs values that are not there, ask me which ones to use, and prefer dev or test credentials.
+4. Check your work with \`bottleship agent onboard --check\` from the repo root. It builds the box from this working tree (uncommitted changes included), runs setup.sh and start.sh, waits for the EXPOSEd ports, and prints JSON: the stage it reached (ready or failed), the log of what failed, and a URL on this machine for each port. Look inside a box with \`bottleship agent exec <id> -- <command>\` (logs are in ~/.bottleship/ there) and remove it with \`bottleship agent rm <id>\`. Repeat until check reports ready, then confirm the app really serves, e.g. \`curl\` its URL and look at the response. Remove every box you created.
+5. Then look for changes to the repo itself that would make it easier to run in a box or for a reviewer to try: one command for setup, a seed script with useful demo data, config read from env instead of hardcoded hosts, a mock mode for external services, a complete .env.example, faster installs. List each with why it helps and how much work it is, and only make the ones I agree to, separately from the .bottleship/ files.
+6. Finish with a short summary: what the box runs, what check reported, what does not work in a box yet and why. Suggest committing .bottleship/.`;
+export function onboardPrompt(cwd) {
+    const repo = checkout(cwd);
+    if (!repo)
+        throw new BsError("no_repo", "this directory is not in a git repository", "run it from inside the repo");
+    return { root: repo.root, prompt: ONBOARD_PROMPT };
+}

package/dist/src/paths.d.ts

@@ -1,4 +1,3 @@
 export declare const ROOT: string;
-export declare const DIST: string;
 export declare const HOME: string;
 export declare const CONFIG_FILE: string;

package/dist/src/paths.js

@@ -12,6 +12,5 @@ function packageRoot(from) {
     }
 }
 export const ROOT = packageRoot(import.meta.dirname);
-export const DIST = join(ROOT, "dist");
 export const HOME = process.env.BOTTLESHIP_HOME ?? join(homedir(), ".bottleship");
 export const CONFIG_FILE = join(HOME, "config.json");

package/dist/src/provider.d.ts

@@ -0,0 +1,16 @@
+import type { BoxStream, ExecResult } from "./types.ts";
+export interface Provider {
+    name: string;
+    create(id: string, dockerfile: string, image: string): Promise<void>;
+    exec(id: string, script: string, stdin?: string | Buffer): Promise<ExecResult>;
+    stream(id: string, script: string): BoxStream;
+    status(id: string): Promise<"running" | "gone">;
+    destroy(id: string): Promise<void>;
+    url?(id: string, port: number): Promise<string>;
+    list?(): Promise<{
+        box: string;
+        created?: string;
+    }[]>;
+}
+export declare function providerNames(): string[];
+export declare function getProvider(name: string): Provider;