garaje 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 teammates.work
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { runPark } from "./park/index.js";
+import { runInit } from "./host/init.js";
+import { runUp } from "./host/up.js";
+import { runDown } from "./host/down.js";
+import { runLogs } from "./host/logs.js";
+import { runPi } from "./host/pi.js";
+import { runAttach } from "./host/attach.js";
+import { runDoctor } from "./host/doctor.js";
+import { runSyncList } from "./host/sync.js";
+import { runAuth } from "./host/auth.js";
+import { runSessionsIndex } from "./sessions/run.js";
+import { inContainer } from "./driver/index.js";
+import { runBay } from "./host/bay.js";
+import { runUpgrade } from "./upgrade/index.js";
+/** Verbs the in-container agent may not run: it cannot rebirth or reset the
+ *  container it lives in (north-star §5.4 — self-lifecycle is host-only). */
+const HOST_ONLY = new Set(["up", "down", "attach", "upgrade"]);
+export function hostOnlyRefusal(cmd, env) {
+    if (HOST_ONLY.has(cmd) && inContainer(env)) {
+        return (`garaje ${cmd}: host-only (self-lifecycle) — the agent cannot manage its own ` +
+            `container. Stage + commit the change, then ask the developer to run it on the host.`);
+    }
+    return undefined;
+}
+export function main(argv) {
+    const [cmd, ...rest] = argv;
+    const root = process.cwd();
+    const refusal = hostOnlyRefusal(cmd ?? "", process.env);
+    if (refusal) {
+        process.stderr.write(refusal + "\n");
+        return 1;
+    }
+    switch (cmd) {
+        case "up":
+            return runUp(root, rest);
+        case "down":
+            return runDown(root, rest);
+        case "logs":
+            return runLogs(root, rest);
+        case "pi":
+            return runPi(root, rest);
+        case "attach":
+            return runAttach(root, rest);
+        case "doctor":
+            return runDoctor(root);
+        case "sync":
+            return runSyncList(root, "sync", rest);
+        case "list":
+            return runSyncList(root, "list", rest);
+        case "park":
+            return runPark(root, rest).code;
+        case "sessions-index":
+            return runSessionsIndex(root).code;
+        case "auth":
+            return runAuth(root, rest);
+        case "bay":
+            return runBay(root, rest);
+        case "init":
+            return runInit(root, rest);
+        case "upgrade":
+            return runUpgrade(root, rest);
+        default:
+            process.stderr.write(`garaje: unknown subcommand: ${cmd ?? ""} ` +
+                `(try: init, up, down, logs, pi, attach, doctor, sync, list, park, bay, sessions-index, auth, upgrade)\n`);
+            return 1;
+    }
+}
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/dist/driver/compose.js

@@ -0,0 +1,127 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+/** The compose files a scope layers, in order. Bays scope excludes the
+ *  framework layer entirely — that exclusion IS the structural containment. */
+export function composeFiles(scope, baysActive) {
+    if (scope === "bays")
+        return ["compose.bays.yaml"];
+    return baysActive
+        ? ["docker-compose.yml", "compose.bays.yaml"]
+        : ["docker-compose.yml"];
+}
+/** The argv to pass after `docker compose`. Mirrors the retired
+ *  host/compose.ts (and before it bin/_lib.sh `compose`). */
+export function composeArgs(ctx, extra) {
+    const files = composeFiles(ctx.scope, ctx.baysActive).flatMap((f) => ["-f", f]);
+    const project = ctx.project ? ["-p", ctx.project] : [];
+    return [...project, ...files, ...extra];
+}
+/** The committed compose project name — the first top-level `name:` line. */
+export function readProjectName(root) {
+    const path = join(root, "garaje.yaml");
+    if (!existsSync(path))
+        return undefined;
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        const m = /^name:\s*(.+?)\s*$/.exec(line);
+        if (m)
+            return m[1].replace(/^["']|["']$/g, "");
+    }
+    return undefined;
+}
+/** Service names from `ps --status running --services` output. */
+export function parseServicesOutput(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+}
+export class ComposeDriver {
+    ctx;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    args(extra) {
+        return composeArgs(this.ctx, extra);
+    }
+    /** PWD is pinned to the root so `${PWD:-}` interpolation in the framework
+     *  compose sees the garaje root even when the CLI is invoked from elsewhere. */
+    env() {
+        const env = { ...process.env, PWD: this.ctx.root };
+        if (this.ctx.scope === "bays") {
+            // The framework services (pi, docker-proxy) are intentional "orphans" of
+            // the bays-only file set — compose's suggestion to remove them must
+            // never reach the agent (that removal would take down its own container).
+            env.COMPOSE_IGNORE_ORPHANS = "1";
+        }
+        return env;
+    }
+    run(extra) {
+        return (spawnSync("docker", ["compose", ...this.args(extra)], {
+            cwd: this.ctx.root,
+            stdio: "inherit",
+            env: this.env(),
+        }).status ?? 1);
+    }
+    capture(extra, input) {
+        const r = spawnSync("docker", ["compose", ...this.args(extra)], {
+            cwd: this.ctx.root,
+            encoding: "utf8",
+            input,
+            env: this.env(),
+        });
+        return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+    }
+    up(opts = {}) {
+        return this.run([
+            "up",
+            "-d",
+            ...(opts.build ? ["--build"] : []),
+            ...(opts.extra ?? []),
+            ...(opts.services ?? []),
+        ]);
+    }
+    down(opts = {}) {
+        return this.run(["down", ...(opts.extra ?? []), ...(opts.services ?? [])]);
+    }
+    logs(opts = {}) {
+        return this.run([
+            "logs",
+            ...(opts.follow ? ["-f"] : []),
+            ...(opts.tail !== undefined ? [`--tail=${opts.tail}`] : []),
+            ...(opts.extra ?? []),
+            ...(opts.services ?? []),
+        ]);
+    }
+    psText() {
+        return this.capture(["ps"]).stdout;
+    }
+    runningServices() {
+        return parseServicesOutput(this.capture(["ps", "--status", "running", "--services"]).stdout);
+    }
+    configOk() {
+        return this.capture(["config", "-q"]).status === 0;
+    }
+    exec(service, argv) {
+        return this.run(["exec", "-it", service, ...argv]);
+    }
+    execCapture(service, argv, opts = {}) {
+        return this.capture(["exec", "-T", service, ...argv], opts.input);
+    }
+    port(service, containerPort) {
+        const r = this.capture(["port", service, String(containerPort)]);
+        const line = (r.stdout.trim().split(/\r?\n/)[0] ?? "").trim();
+        return r.status === 0 && line ? line : undefined;
+    }
+    volumeName(volume) {
+        const project = this.ctx.project ?? basename(this.ctx.root).toLowerCase();
+        return `${project}_${volume}`;
+    }
+    requiredFiles() {
+        return ["docker-compose.yml", "compose.framework.yaml"];
+    }
+}
+/** The generated bays layer's presence — driver-internal filename knowledge. */
+export function hasBaysLayer(root) {
+    return existsSync(join(root, "compose.bays.yaml"));
+}

package/dist/driver/index.js

@@ -0,0 +1,33 @@
+import { ComposeDriver, hasBaysLayer, readProjectName } from "./compose.js";
+import { discoverBays } from "../park/index.js";
+export { hasBaysLayer } from "./compose.js";
+/** Build a DriverContext for a garaje root. Default scope: the full stack. */
+export function driverContext(root, scope = "garaje") {
+    return {
+        root,
+        project: readProjectName(root),
+        scope,
+        baysActive: hasBaysLayer(root) && discoverBays(root).length > 0,
+    };
+}
+/** Compose is the only driver until Phase 8 adds k8s — no registry yet (YAGNI). */
+export function getDriver(ctx) {
+    return new ComposeDriver(ctx);
+}
+/** True inside the pi container (env marker set in the framework compose). */
+export function inContainer(env = process.env) {
+    return env.GARAJE_IN_CONTAINER === "1";
+}
+/** Start the stack if `service` isn't running. 0 when running (or started).
+ *  In-container this refuses to fall back to a full-stack `up` — that would
+ *  try to recreate the stack the agent itself lives in. */
+export function ensureRunning(driver, service, env = process.env) {
+    if (driver.runningServices().includes(service))
+        return 0;
+    if (inContainer(env)) {
+        process.stderr.write(`(${service} not running — cannot start the stack from inside the container; run garaje up on the host)\n`);
+        return 1;
+    }
+    process.stderr.write(`(${service} container not running; starting the stack)\n`);
+    return driver.up();
+}

package/dist/driver/types.js

@@ -0,0 +1,7 @@
+/**
+ * The runtime-driver seam (north-star design §4.1): up/down/exec/logs/ports/
+ * volumes is the only dialect layers above codegen may speak. Compose
+ * knowledge lives exclusively in driver/compose.ts; the k8s driver (Phase 8)
+ * implements this same interface.
+ */
+export {};

package/dist/host/attach.js

@@ -0,0 +1,12 @@
+import { requireDocker } from "./docker.js";
+import { driverContext, getDriver } from "../driver/index.js";
+/**
+ * `garaje attach` — interactive shell in the pi container (the former
+ * `jack-in`), or a one-shot command with `garaje attach <cmd...>`.
+ */
+export function runAttach(root, extra) {
+    requireDocker();
+    const driver = getDriver(driverContext(root));
+    const argv = extra.length ? ["/bin/bash", "-c", extra.join(" ")] : ["/bin/bash"];
+    return driver.exec("pi", argv);
+}

package/dist/host/auth-presets.js

@@ -0,0 +1,13 @@
+/** Framework-shipped preset catalog. git/gh only for Plan 1. */
+export const AUTH_PRESETS = {
+    github: {
+        name: "github",
+        hint: "GitHub for git-over-https + gh, from your host `gh auth token` " +
+            "(override with --token <t> or --resolver env:NAME|cmd:<sh> for a scoped PAT)",
+        defaultResolver: "gh",
+        install: "gh-login",
+    },
+};
+export function getPreset(name) {
+    return AUTH_PRESETS[name];
+}

package/dist/host/auth-resolvers.js

@@ -0,0 +1,46 @@
+import { spawnSync } from "node:child_process";
+/**
+ * Resolve a secret VALUE host-side from a resolver spec, at `garaje auth add`
+ * time (not per launch). Supported forms:
+ *   - `gh`         → `gh auth token` (the host gh CLI's current token)
+ *   - `env:NAME`   → the host environment variable NAME
+ *   - `cmd:<shell>`→ trimmed stdout of the shell command
+ * Throws on an unknown scheme, a missing/empty value, or multi-line output.
+ * (Single-line is enforced because `gh auth login --with-token` reads ALL of
+ * stdin, so an embedded newline — e.g. a tool that prints a notice before the
+ * token — would corrupt the credential.)
+ */
+export function resolveSecret(spec) {
+    const value = resolveRaw(spec);
+    if (/[\r\n]/.test(value)) {
+        throw new Error(`resolver ${spec}: output must be a single line (got multiple lines) — ` +
+            "make the command emit only the secret (e.g. pipe through `tail -1`)");
+    }
+    return value;
+}
+function resolveRaw(spec) {
+    if (spec === "gh") {
+        const r = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
+        const out = (r.stdout ?? "").trim();
+        if (r.status !== 0 || !out) {
+            throw new Error("resolver gh: `gh auth token` failed (is gh installed + logged in?)");
+        }
+        return out;
+    }
+    if (spec.startsWith("env:")) {
+        const name = spec.slice(4);
+        const val = (process.env[name] ?? "").trim();
+        if (!val)
+            throw new Error(`resolver env:${name}: environment variable ${name} is unset or empty`);
+        return val;
+    }
+    if (spec.startsWith("cmd:")) {
+        const r = spawnSync("sh", ["-c", spec.slice(4)], { encoding: "utf8" });
+        const out = (r.stdout ?? "").trim();
+        if (r.status !== 0 || !out) {
+            throw new Error(`resolver cmd: command failed or produced no output: ${spec.slice(4)}`);
+        }
+        return out;
+    }
+    throw new Error(`unknown resolver: ${spec} (use gh, env:NAME, or cmd:<shell>)`);
+}

package/dist/host/auth.js

@@ -0,0 +1,140 @@
+import { requireDocker, die } from "./docker.js";
+import { driverContext, ensureRunning, getDriver } from "../driver/index.js";
+import { resolveSecret } from "./auth-resolvers.js";
+import { getPreset } from "./auth-presets.js";
+/**
+ * Parse `garaje auth <sub> [name] [--token t] [--resolver spec]`. Pure.
+ * Supports `--flag value` and `--flag=value`. Throws on a missing/empty flag
+ * value or an unrecognized argument — so a forgotten value can't silently fall
+ * back to provisioning the full host `gh` token, and a stray flag can't be piped
+ * to gh as the secret.
+ */
+export function parseAuthArgs(args) {
+    const [sub, ...rest] = args;
+    const out = { sub: sub ?? "" };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--token" || a === "--resolver") {
+            const val = rest[++i];
+            if (val === undefined || val === "" || val.startsWith("-")) {
+                throw new Error(`garaje auth: ${a} needs a value`);
+            }
+            if (a === "--token")
+                out.token = val;
+            else
+                out.resolver = val;
+        }
+        else if (a.startsWith("--token=") || a.startsWith("--resolver=")) {
+            const eq = a.indexOf("=");
+            const val = a.slice(eq + 1);
+            if (val === "")
+                throw new Error(`garaje auth: ${a.slice(0, eq)} needs a value`);
+            if (a.startsWith("--token="))
+                out.token = val;
+            else
+                out.resolver = val;
+        }
+        else if (!a.startsWith("-") && out.name === undefined) {
+            out.name = a;
+        }
+        else {
+            throw new Error(`garaje auth: unexpected argument '${a}'`);
+        }
+    }
+    return out;
+}
+/** `garaje auth` — provision integration auth into the garaje-auth store. */
+export function runAuth(root, args) {
+    let parsed;
+    try {
+        parsed = parseAuthArgs(args);
+    }
+    catch (e) {
+        die(`${e.message}`);
+    }
+    const { sub, name, token, resolver } = parsed;
+    if (sub !== "add" && sub !== "list" && sub !== "remove") {
+        process.stderr.write("garaje auth: usage: garaje auth {add <tool> [--token t|--resolver spec] | list | remove <tool>}\n");
+        return 1;
+    }
+    requireDocker();
+    const driver = getDriver(driverContext(root));
+    switch (sub) {
+        case "add":
+            return authAdd(driver, name, token, resolver);
+        case "list":
+            return authList(driver);
+        case "remove":
+            return authRemove(driver, name);
+    }
+    return 1;
+}
+/** The exec argv (NO secret) + the stdin payload (the token) for
+ *  `gh auth login --with-token`. Kept pure so a test can lock the security
+ *  property: the token travels on stdin, never in argv. */
+export function ghLoginExec(secret) {
+    return {
+        argv: ["gh", "auth", "login", "--hostname", "github.com", "--with-token"],
+        input: secret + "\n",
+    };
+}
+/** Start the stack; die with a clear message if it fails to come up. */
+function requirePiRunning(driver, verb) {
+    if (ensureRunning(driver, "pi") !== 0) {
+        die(`garaje auth ${verb}: could not start the pi stack — see the error above`);
+    }
+}
+function authAdd(driver, name, token, resolver) {
+    if (!name)
+        die("garaje auth add: which integration? (e.g. garaje auth add github)");
+    const preset = getPreset(name);
+    if (!preset)
+        die(`garaje auth add: unknown integration '${name}' (known: github)`);
+    // The preset drives which provisioning flow runs; refuse one this verb can't
+    // install so a future (non-GitHub) preset's secret is never piped to gh.
+    if (preset.install !== "gh-login") {
+        die(`garaje auth add: '${name}' uses an unsupported auth method (Plan 1 provisions github via gh)`);
+    }
+    let secret;
+    try {
+        secret = token ?? resolveSecret(resolver ?? preset.defaultResolver);
+    }
+    catch (e) {
+        die(`garaje auth add ${name}: ${e.message}`);
+    }
+    requirePiRunning(driver, "add");
+    // The token only persists if THIS image carries the auth wiring
+    // (GH_CONFIG_DIR → the garaje-auth volume). A stale container from before that
+    // landed would "succeed" but write off-volume and lose the token on recreate.
+    const cfg = driver.execCapture("pi", ["printenv", "GH_CONFIG_DIR"]);
+    if (cfg.status !== 0 || !cfg.stdout.trim()) {
+        die("garaje auth add: the pi image is missing the auth wiring (GH_CONFIG_DIR). Run `garaje up --build` first.");
+    }
+    const { argv, input } = ghLoginExec(secret);
+    const r = driver.execCapture("pi", argv, { input });
+    if (r.status !== 0) {
+        process.stderr.write(r.stderr || r.stdout);
+        process.stderr.write("garaje auth add github: gh auth login failed (see gh's output above — token invalid/expired or wrong scopes, or a container error)\n");
+        return r.status;
+    }
+    process.stderr.write("garaje auth: github added — gh + git (https) authenticated for the agent\n");
+    return 0;
+}
+function authList(driver) {
+    requirePiRunning(driver, "list");
+    // `gh auth status` exits non-zero when no account is configured; passing that
+    // through lets callers script "is the agent authed?" off the exit code.
+    const r = driver.execCapture("pi", ["gh", "auth", "status"]);
+    process.stdout.write(r.stdout);
+    process.stderr.write(r.stderr);
+    return r.status;
+}
+function authRemove(driver, name) {
+    if (name !== "github")
+        die("garaje auth remove: only 'github' is supported (Plan 1)");
+    requirePiRunning(driver, "remove");
+    const r = driver.execCapture("pi", ["gh", "auth", "logout", "--hostname", "github.com"]);
+    process.stdout.write(r.stdout);
+    process.stderr.write(r.stderr);
+    return r.status;
+}

package/dist/host/bay.js

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { requireDocker, die } from "./docker.js";
+import { driverContext, getDriver, hasBaysLayer } from "../driver/index.js";
+import { parseRecipe } from "../park/recipe.js";
+import { bayServiceNames } from "../park/compose.js";
+const USAGE = "garaje bay {up|down|logs|ps} <name> [args...] — bay-scoped lifecycle " +
+    "(runs against the parked-services layer only; safe in-container)\n";
+/** Extra args the bay verbs must refuse: in the bays-only scope the framework
+ *  services (pi, docker-proxy) are "orphans" of the file set, so orphan
+ *  removal would take down the agent's own container. */
+export function bayExtraRejection(extra) {
+    if (extra.includes("--remove-orphans")) {
+        return ("garaje bay: --remove-orphans is refused — in the bays-only scope the framework " +
+            "services (pi, docker-proxy) count as orphans, so this would remove the agent's own container");
+    }
+    return undefined;
+}
+/**
+ * `garaje bay <verb> <name>` — lifecycle for ONE parked bay, in the bays-only
+ * driver scope. The framework layer (the pi service) is not in that scope's
+ * file set, so these verbs structurally cannot touch the agent's own
+ * container (north-star §5.1 layer 2 / spec §3.2).
+ */
+export function runBay(root, args) {
+    const [sub, name, ...extra] = args;
+    if (!sub || !name || !["up", "down", "logs", "ps"].includes(sub)) {
+        process.stderr.write(USAGE);
+        return 1;
+    }
+    const rejection = bayExtraRejection(extra);
+    if (rejection)
+        die(rejection);
+    const recipePath = join(root, "bays", name, "recipe.yaml");
+    if (!existsSync(recipePath)) {
+        die(`garaje bay: no recipe at bays/${name}/recipe.yaml (sync first?)`);
+    }
+    if (!hasBaysLayer(root)) {
+        die("garaje bay: no generated bays layer — run `garaje park` first");
+    }
+    const services = bayServiceNames(parseRecipe(readFileSync(recipePath, "utf8"), name));
+    requireDocker();
+    const driver = getDriver(driverContext(root, "bays"));
+    switch (sub) {
+        case "up":
+            // build:true so recipe edits take effect every prove-loop iteration.
+            return driver.up({ build: true, services, extra });
+        case "down":
+            return driver.down({ services, extra });
+        case "logs":
+            // Bounded tail, no follow: agents must get their prompt back.
+            return driver.logs({ tail: 200, services, extra });
+        case "ps": {
+            const lines = driver.psText().split(/\r?\n/);
+            const out = [lines[0], ...lines.slice(1).filter((l) => l.includes(`${name}-`))];
+            process.stdout.write(out.filter(Boolean).join("\n") + "\n");
+            return 0;
+        }
+    }
+    return 1;
+}

package/dist/host/compose.js

@@ -0,0 +1,65 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The argv to pass after `docker compose`. Mirrors bin/_lib.sh `compose`:
+ * always `-f docker-compose.yml`, layer `-f compose.bays.yaml` when present,
+ * and prepend `-p <name>` when the garaje declares one.
+ */
+export function composeArgs(ctx, extra) {
+    const files = ["-f", "docker-compose.yml"];
+    if (ctx.hasBaysCompose)
+        files.push("-f", "compose.bays.yaml");
+    const project = ctx.name ? ["-p", ctx.name] : [];
+    return [...project, ...files, ...extra];
+}
+/** The committed compose project name — the first top-level `name:` line. */
+export function readProjectName(root) {
+    const path = join(root, "garaje.yaml");
+    if (!existsSync(path))
+        return undefined;
+    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
+        const m = /^name:\s*(.+?)\s*$/.exec(line);
+        if (m)
+            return m[1].replace(/^["']|["']$/g, "");
+    }
+    return undefined;
+}
+export function composeContext(root) {
+    return {
+        name: readProjectName(root),
+        hasBaysCompose: existsSync(join(root, "compose.bays.yaml")),
+    };
+}
+/** Run `docker compose` from the repo root, inheriting stdio; returns exit code. */
+export function compose(root, extra) {
+    const args = composeArgs(composeContext(root), extra);
+    return spawnSync("docker", ["compose", ...args], { cwd: root, stdio: "inherit" }).status ?? 1;
+}
+/** Run `docker compose` and capture stdout/stderr instead of inheriting. */
+export function composeCapture(root, extra) {
+    const args = composeArgs(composeContext(root), extra);
+    const r = spawnSync("docker", ["compose", ...args], { cwd: root, encoding: "utf8" });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+/** Like composeCapture, but feeds `input` to the process's stdin. */
+export function composeCaptureInput(root, extra, input) {
+    const args = composeArgs(composeContext(root), extra);
+    const r = spawnSync("docker", ["compose", ...args], { cwd: root, encoding: "utf8", input });
+    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+/**
+ * Start the stack if the `pi` service isn't already running. Returns 0 when pi
+ * is (or becomes) running, else the non-zero `up -d` exit code so callers can
+ * bail cleanly instead of exec-ing against a stack that failed to start. The
+ * running-check is inlined (rather than importing pi.ts's parseRunningServices)
+ * to avoid a compose ↔ pi import cycle — pi.ts already imports from compose.ts.
+ */
+export function ensurePiRunning(root) {
+    const ps = composeCapture(root, ["ps", "--status", "running", "--services"]);
+    const running = ps.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    if (running.includes("pi"))
+        return 0;
+    process.stderr.write("(pi container not running; starting the stack)\n");
+    return compose(root, ["up", "-d"]);
+}

package/dist/host/docker.js

@@ -0,0 +1,15 @@
+import { spawnSync } from "node:child_process";
+/** Print an error and exit non-zero. Mirrors bin/_lib.sh `die`. */
+export function die(msg) {
+    process.stderr.write(`error: ${msg}\n`);
+    process.exit(1);
+}
+/** Ensure the docker CLI is on PATH and the daemon is reachable. */
+export function requireDocker() {
+    if (spawnSync("docker", ["--version"], { stdio: "ignore" }).status !== 0) {
+        die("docker not found in PATH");
+    }
+    if (spawnSync("docker", ["info"], { stdio: "ignore" }).status !== 0) {
+        die("docker daemon not reachable (is Docker Desktop running?)");
+    }
+}