bottleship 0.0.1 → 0.1.0-prototype.0

package/dist/src/init.d.ts

@@ -0,0 +1,12 @@
+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 interface InitFlags {
+    provider?: string;
+    host?: string;
+    name?: string;
+    agent?: string;
+    gitName?: string;
+    gitEmail?: string;
+    noIsolation?: boolean;
+}
+export declare function init(flags: InitFlags, ui?: UI): Promise<Record<string, unknown>>;

package/dist/src/init.js

@@ -0,0 +1,345 @@
+// 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.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } 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 { 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\`.
+
+- 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>\`.
+- 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
+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",
+};
+// 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)",
+};
+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();
+    }
+    catch {
+        return "";
+    }
+};
+// the value of a missing secret goes to the store, and config points at it from then on
+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
+        raw.env = { ...(raw.env ?? DEFAULTS.env), [secret.name]: source };
+    return source;
+}
+export async function init(flags, ui) {
+    const raw = readUserConfig();
+    let cfg = loadConfig(raw);
+    ui?.intro();
+    const pick = async (key, question, options) => {
+        const known = options.map((o) => o.value);
+        const value = flags[key] ?? raw[key] ?? (ui ? 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]))
+            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 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 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]))
+            ui.ok(`git ${key} ${c.bold(v)}`);
+        return v;
+    };
+    const git = { name: await gitValue("name", flags.gitName), email: await gitValue("email", flags.gitEmail) };
+    if (!git.name || !git.email)
+        throw new BsError("missing_git", "no git name or email for commits from boxes", "pass --git-name and --git-email, or set git config user.name and user.email");
+    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 secrets = [];
+    for (const s of neededSecrets(cfg, provider, agent)) {
+        let source = s.source;
+        let ok = hasSecret(source);
+        if (!ok && ui && s.name === "GH_TOKEN" && (await useGhAuthToken(ui))) {
+            source = { command: "gh auth token" };
+            raw.env = { ...(raw.env ?? DEFAULTS.env), GH_TOKEN: source };
+            writeUserConfig(raw);
+            ok = hasSecret(source);
+            if (!ok)
+                ui.warn("`gh auth token` printed nothing", "run `gh auth login`, then `bottleship init` again");
+        }
+        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 value = await ui.secret(`${s.name}`);
+            if (value) {
+                source = storeAndPoint(raw, s, value);
+                writeUserConfig(raw);
+                ok = true;
+            }
+        }
+        if (ui && ok)
+            ui.ok(s.name, describe(source));
+        secrets.push({ name: s.name, source: describe(source), ok });
+    }
+    const missing = secrets.filter((s) => !s.ok).map((s) => s.name);
+    if (missing.length)
+        throw missingSecrets(missing);
+    cfg = loadConfig(raw);
+    ui?.section(`Live check: ${provider} + ${agent}`);
+    const checks = await liveCheck(raw, 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 };
+}
+// 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) {
+    ui.say("Boxes push branches and open PRs with a GitHub token. A fine-grained token limited to the repos you pick keeps a box away from everything else in your account.");
+    const how = await ui.choose("Which GitHub token do boxes get?", [
+        { value: "fine-grained", hint: "a fine-grained token for the repos you pick (recommended)" },
+        { value: "gh", hint: "`gh auth token`: your gh login, every repo you can reach" },
+    ], "fine-grained");
+    if (how !== "gh")
+        return false;
+    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) {
+    const checks = [];
+    const step = async (name, fn) => {
+        const t0 = Date.now();
+        try {
+            const detail = ui ? await ui.step(name, fn) : await fn();
+            checks.push({ step: name, ok: true, ms: Date.now() - t0, ...(detail ? { detail } : {}) });
+            return true;
+        }
+        catch (e) {
+            checks.push({ step: name, ok: false, ms: Date.now() - t0, error: e instanceof BsError ? e.toJSON() : e.message });
+            return false;
+        }
+    };
+    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 };
+        })))
+            return;
+        if (!(await step("run a command", async () => {
+            const r = await b.provider.exec(b.box, "echo bottleship-ok");
+            if (r.stdout.trim() !== "bottleship-ok")
+                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 () => {
+            const s = await waitAgent(b, 300);
+            if (s.agent === "running")
+                throw new Error("no reply within 5 minutes");
+            if (s.agent !== "exited" || s.exitCode !== 0 || !s.log.includes("bottleship-ok"))
+                throw new Error(`agent ${s.agent}${"exitCode" in s ? ` (exit ${s.exitCode})` : ""}: ${s.log.slice(-500)}`);
+            return s.log.trim().slice(-200);
+        });
+    };
+    await check();
+    if (b)
+        await step("destroy the box", async () => void (await b.provider.destroy(b.box)));
+    return checks;
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,17 @@
+// Where things live. Local state is under ~/.bottleship (override: BOTTLESHIP_HOME).
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// runs from src/*.ts and from dist/src/*.js, so find the package root by its package.json
+function packageRoot(from) {
+    for (let dir = from;; dir = dirname(dir)) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        if (dirname(dir) === dir)
+            throw new Error(`no package.json above ${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/secrets.d.ts

@@ -0,0 +1,5 @@
+import type { SecretSource } from "./types.ts";
+export declare function describe(source: SecretSource): string;
+export declare function readSecret(source: SecretSource): string;
+export declare function storeSecret(name: string, value: string): string;
+export declare function hasSecret(source: SecretSource): boolean;

package/dist/src/secrets.js

@@ -0,0 +1,58 @@
+// Reads and stores secret values on this machine. Sources are described in types.ts (SecretSource).
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { HOME } from "./paths.js";
+const SERVICE = "bottleship";
+const FILE_DIR = join(HOME, "secrets");
+const useKeychain = () => process.platform === "darwin" && !process.env.BOTTLESHIP_NO_KEYCHAIN;
+const sh = (cmd, args, input) => execFileSync(cmd, args, { input, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+export function describe(source) {
+    if ("store" in source)
+        return useKeychain() ? `keychain:${SERVICE}/${source.store}` : `file:${join(FILE_DIR, source.store)}`;
+    if ("command" in source)
+        return `command:${source.command}`;
+    return `env:${source.env}`;
+}
+export function readSecret(source) {
+    if ("store" in source) {
+        if (useKeychain())
+            return sh("security", ["find-generic-password", "-s", SERVICE, "-a", source.store, "-w"]).trim();
+        try {
+            return readFileSync(join(FILE_DIR, source.store), "utf8").trim();
+        }
+        catch {
+            throw new Error(`no secret "${source.store}" stored`);
+        }
+    }
+    if ("command" in source)
+        return sh("sh", ["-c", source.command]).trim();
+    const v = process.env[source.env];
+    if (!v)
+        throw new Error(`env ${source.env} is not set`);
+    return v;
+}
+// returns where the value went, for the CLI to print
+export function storeSecret(name, value) {
+    if (useKeychain()) {
+        // `security -i` reads one line of at most 4096 bytes; anything past it would run as another command
+        if (/[\r\n]/.test(value) || Buffer.byteLength(value) > 4000)
+            throw new Error(`the value for "${name}" is too long or has line breaks for the keychain`);
+        // fed on stdin via `security -i` so the value never shows up in argv
+        const quoted = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        sh("security", ["-i"], `add-generic-password -U -s ${SERVICE} -a ${name} -w "${quoted}"\n`);
+    }
+    else {
+        mkdirSync(FILE_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(join(FILE_DIR, name), value + "\n", { mode: 0o600 });
+    }
+    return describe({ store: name });
+}
+export function hasSecret(source) {
+    try {
+        return Boolean(readSecret(source));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,120 @@
+import type { Readable, Writable } from "node:stream";
+export type SecretSource = {
+    store: string;
+} | {
+    command: string;
+} | {
+    env: string;
+};
+export type EnvMap = Record<string, string | SecretSource>;
+export interface AgentSpec {
+    install?: string[];
+    run: string;
+    resume: string;
+    env?: EnvMap;
+    unset?: string[];
+    login?: AgentLogin;
+}
+export type LoginRoute = "token" | "device" | "none";
+export interface AgentLogin {
+    routes: LoginRoute[];
+    use: LoginRoute;
+    token?: {
+        env: string;
+        store: string;
+        command?: string;
+        hint?: string;
+    };
+    tokens?: {
+        env: string;
+        store: string;
+        hint?: string;
+    }[];
+    device?: {
+        command: string;
+        status: string;
+        setup?: string;
+        timeout?: number;
+    };
+}
+export interface ProviderSpec {
+    module: string;
+    [option: string]: unknown;
+}
+export interface Config {
+    provider: string;
+    agent: string;
+    git: {
+        name: string;
+        email: string;
+    };
+    env: EnvMap;
+    providers: Record<string, ProviderSpec>;
+    agents: Record<string, AgentSpec>;
+    templates: Record<string, {
+        name: string;
+        ref: string;
+    }>;
+}
+export interface ExecResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface BoxStream {
+    stdin: Writable;
+    stdout: Readable;
+    stderr: Readable;
+    close(): void;
+    onClose(cb: (code?: number | null) => void): void;
+}
+export type BoxStatus = "running" | "gone";
+export interface TemplateSpec {
+    name: string;
+    dockerfile: string;
+}
+export interface Provider {
+    template?(spec: TemplateSpec): Promise<string>;
+    create(opts: {
+        id: string;
+        source?: string;
+        template?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    exec(id: string, script: string, opts?: {
+        stdin?: string | Buffer;
+    }): Promise<ExecResult>;
+    destroy(id: string): Promise<unknown>;
+    openStream?(id: string, script: string): BoxStream | Promise<BoxStream>;
+    status?(id: string): Promise<BoxStatus>;
+}
+export interface LoadedProvider extends Provider {
+    name: string;
+}
+export interface RunOptions {
+    stdin?: string | Buffer;
+    check?: boolean;
+    env?: Record<string, string>;
+}
+export interface ProviderKit {
+    run(cmd: string, args: string[], opts?: RunOptions): Promise<ExecResult>;
+    shq(s: unknown): string;
+    fill(template: string, values: Record<string, unknown>): string;
+    spawnStream(cmd: string, args: string[]): BoxStream;
+    wsStream(url: string, headers?: Record<string, string>): BoxStream;
+}
+export interface ProviderCtx {
+    name: string;
+    options: Record<string, any>;
+    secret(source: SecretSource): string;
+    log(...args: unknown[]): void;
+    kit: ProviderKit;
+}
+export type ProviderFactory = (ctx: ProviderCtx) => Provider | Promise<Provider>;
+export interface BsErrorJSON {
+    error: string;
+    message: string;
+    fix?: string;
+    [extra: string]: unknown;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/ui.d.ts

@@ -0,0 +1,31 @@
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    blue: (s: string) => string;
+    white: (s: string) => string;
+};
+export declare function header(): string;
+export interface UI {
+    intro(): void;
+    say(line?: string): void;
+    section(title: string): void;
+    ok(label: string, detail?: string): void;
+    warn(label: string, detail?: string): void;
+    note(title: string, body: string): void;
+    text(question: string, def?: string): Promise<string>;
+    choose(question: string, options: {
+        value: string;
+        hint?: string;
+    }[], def: string): Promise<string>;
+    secret(question: string): Promise<string>;
+    confirm(question: string): Promise<boolean>;
+    handOver(command: string): Promise<number | null>;
+    step<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    fail(message: string, fix?: string): void;
+    close(message?: string): void;
+}
+export declare function terminalUI(): UI;