garaje 0.1.0

package/dist/host/doctor.js

@@ -0,0 +1,119 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { driverContext, getDriver } from "../driver/index.js";
+import { baysArtifactState, discoverBays, manifestBays } from "../park/index.js";
+/** `garaje doctor` — host-side sanity checks. Exit code = failed-check count. */
+export function runDoctor(root) {
+    let fails = 0;
+    const pass = (m) => process.stdout.write(`  \x1b[32mok\x1b[0m   ${m}\n`);
+    const warn = (m) => process.stdout.write(`  \x1b[33mwarn\x1b[0m ${m}\n`);
+    const fail = (m) => {
+        process.stdout.write(`  \x1b[31mfail\x1b[0m ${m}\n`);
+        fails += 1;
+    };
+    const section = (m) => process.stdout.write(`\n== ${m} ==\n`);
+    const driver = getDriver(driverContext(root));
+    // --- host ---
+    section("host");
+    const ver = spawnSync("docker", ["--version"], { encoding: "utf8" });
+    if (ver.status === 0)
+        pass(`docker CLI: ${(ver.stdout ?? "").trim()}`);
+    else
+        fail("docker CLI not found in PATH");
+    const info = spawnSync("docker", ["info"], { stdio: "ignore" });
+    if (info.status === 0)
+        pass("docker daemon reachable");
+    else
+        fail("docker daemon not reachable (is Docker Desktop running?)");
+    // --- repo shape ---
+    section("repo");
+    for (const f of [
+        ...driver.requiredFiles(),
+        "garaje.yaml",
+        "pi/Dockerfile",
+        "pi/entrypoint.sh",
+        "packages/base/package.json",
+        ".pi/settings.json",
+    ]) {
+        if (existsSync(join(root, f)))
+            pass(`${f} present`);
+        else
+            fail(`${f} missing`);
+    }
+    if (existsSync(join(root, ".env")))
+        pass(".env present");
+    else
+        warn(".env missing — copy .env.example and add ANTHROPIC_API_KEY (or use /login)");
+    // --- runtime state ---
+    section("runtime");
+    if (driver.configOk())
+        pass("runtime config parses");
+    else
+        fail("runtime config failed to parse");
+    const running = driver.runningServices();
+    const piRunning = running.includes("pi");
+    if (piRunning)
+        pass("pi service running");
+    else
+        fail("pi service NOT running (try garaje up)");
+    // --- bays (delegate to the retained bash list) ---
+    section("bays");
+    const list = spawnSync("bash", [join(root, "bin", "garaje-sync"), "list"], { encoding: "utf8" });
+    const bayLines = (list.stdout ?? "").split(/\r?\n/).slice(1).filter((l) => l.trim());
+    if (bayLines.length)
+        bayLines.forEach((l) => pass(l));
+    else
+        warn("no bays parked (add one to garaje.yaml, then garaje sync)");
+    const unhealthy = driver.psText()
+        .split(/\r?\n/)
+        .filter((l) => /unhealthy/i.test(l));
+    if (unhealthy.length)
+        fail(`unhealthy container(s):\n${unhealthy.join("\n")}`);
+    // baysArtifactState re-parses every synced recipe; a corrupt/mid-edit
+    // recipe throws, and doctor must report that as a failed check, not crash.
+    try {
+        const artifact = baysArtifactState(root);
+        if (artifact === "fresh")
+            pass("bays artifact matches the recipes (regenerate-and-diff)");
+        else if (artifact === "no-bays")
+            warn("no synced bays — artifact staleness not checkable");
+        else if (artifact === "missing")
+            fail("bays artifact missing — run `garaje park` and commit the result");
+        else
+            fail("bays artifact STALE — recipes changed; run `garaje park` and commit the diff");
+    }
+    catch (e) {
+        fail(`bays artifact check errored — a recipe failed to parse: ${e.message}`);
+    }
+    const unsynced = manifestBays(root).filter((b) => !discoverBays(root).includes(b));
+    if (unsynced.length) {
+        warn(`manifest bay(s) not synced: ${unsynced.join(", ")} — the artifact excludes them (run garaje sync)`);
+    }
+    // --- pi container ---
+    section("pi");
+    if (piRunning) {
+        const isLink = (p) => driver.execCapture("pi", ["test", "-L", p]).status === 0;
+        // The symlink hack is gone: extensions must NOT be a symlink anymore.
+        if (isLink("/root/.pi/agent/extensions"))
+            fail("/root/.pi/agent/extensions is a symlink (Phase 3 symlink hack regressed)");
+        else
+            pass("no extensions symlink (bundle loads via @garaje/base package)");
+        if (isLink("/root/.pi/agent/sessions"))
+            pass("/root/.pi/agent/sessions symlinked to /workspace/sessions");
+        else
+            fail("/root/.pi/agent/sessions not symlinked");
+        const piver = driver.execCapture("pi", ["pi", "--version"]).stdout.trim();
+        if (/[0-9]/.test(piver))
+            pass(`pi binary works: ${piver}`);
+        else
+            fail("pi --version did not print a version");
+    }
+    // --- summary ---
+    section("summary");
+    if (fails === 0)
+        process.stdout.write("  \x1b[32mall checks passed\x1b[0m\n");
+    else
+        process.stdout.write(`  \x1b[31m${fails} check(s) failed\x1b[0m\n`);
+    return fails;
+}

package/dist/host/down.js

@@ -0,0 +1,17 @@
+import { requireDocker, die } from "./docker.js";
+import { driverContext, getDriver } from "../driver/index.js";
+/** True if the args would remove volumes — which would wipe both `pi-config`
+ *  (pi's own /login auth.json) and `garaje-auth` (provisioned git/gh tokens). */
+export function hasVolumeFlag(args) {
+    return args.some((a) => a === "-v" || a === "--volumes");
+}
+/** `garaje down` — stop the stack; refuse volume removal. */
+export function runDown(root, extra) {
+    requireDocker();
+    if (hasVolumeFlag(extra)) {
+        die("refusing to remove volumes — that would wipe pi's /login auth (pi-config) " +
+            "AND your provisioned git/gh + integration tokens (garaje-auth). " +
+            "If you really mean it, run the runtime's own `down -v` directly.");
+    }
+    return getDriver(driverContext(root)).down({ extra });
+}

package/dist/host/init.js

@@ -0,0 +1,131 @@
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, chmodSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve, basename } from "node:path";
+/**
+ * Parse `garaje init <name> [dir] [--base-pin <spec>] [--no-git] [--force]`.
+ * Pure. Supports `--base-pin value` and `--base-pin=value`. Throws on a missing
+ * name, a `--base-pin` without a value, or an unrecognized argument.
+ */
+export function parseInitArgs(args) {
+    const out = { name: "", git: true, force: false };
+    let sawName = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--base-pin") {
+            const val = args[++i];
+            if (val === undefined || val === "" || val.startsWith("-")) {
+                throw new Error("garaje init: --base-pin needs a value");
+            }
+            out.basePin = val;
+        }
+        else if (a.startsWith("--base-pin=")) {
+            const val = a.slice("--base-pin=".length);
+            if (val === "")
+                throw new Error("garaje init: --base-pin needs a value");
+            out.basePin = val;
+        }
+        else if (a === "--no-git") {
+            out.git = false;
+        }
+        else if (a === "--force") {
+            out.force = true;
+        }
+        else if (!a.startsWith("-") && !sawName) {
+            out.name = a;
+            sawName = true;
+        }
+        else if (!a.startsWith("-") && out.dir === undefined) {
+            out.dir = a;
+        }
+        else {
+            throw new Error(`garaje init: unexpected argument '${a}'`);
+        }
+    }
+    if (!sawName || out.name === "") {
+        throw new Error("garaje init: a garaje name is required (garaje init <name>)");
+    }
+    return out;
+}
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(HERE, "../../templates"); // packages/cli/templates
+const RUNTIME_DIRS = ["bays", "sessions", "scratch"];
+/** This CLI's own version — the lockstep version the scaffold pins. */
+function cliVersion() {
+    const pkg = JSON.parse(readFileSync(join(HERE, "../../package.json"), "utf8"));
+    return pkg.version;
+}
+/** Recursively list files (not dirs) under dir, as absolute paths. */
+function walkFiles(dir) {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const abs = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...walkFiles(abs));
+        else
+            out.push(abs);
+    }
+    return out;
+}
+/** Apply the scaffold tokens by literal substring replace (never regex). */
+function applyTokens(text, tokens) {
+    let out = text;
+    for (const [k, v] of Object.entries(tokens))
+        out = out.split(k).join(v);
+    return out;
+}
+/** Map a template's relative path to its emitted path (npm strips a literal
+ *  `.gitignore` from a published package, so it ships de-dotted). */
+function emitPath(rel) {
+    return basename(rel) === "gitignore"
+        ? join(dirname(rel), ".gitignore")
+        : rel;
+}
+export function runInit(root, args) {
+    let a;
+    try {
+        a = parseInitArgs(args);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 1;
+    }
+    const target = a.dir ? resolve(root, a.dir) : join(root, a.name);
+    if (existsSync(join(target, "garaje.yaml"))) {
+        process.stderr.write(`garaje init: ${target} already looks like a garaje (garaje.yaml exists)\n`);
+        return 1;
+    }
+    if (existsSync(target) && readdirSync(target).length > 0 && !a.force) {
+        process.stderr.write(`garaje init: ${target} is not empty (use --force to scaffold into it anyway)\n`);
+        return 1;
+    }
+    const version = cliVersion();
+    const tokens = {
+        __GARAJE_NAME__: a.name,
+        __BASE_PIN__: a.basePin ?? `npm:@garaje/base@${version}`,
+        __GARAJE_VERSION__: version,
+    };
+    for (const abs of walkFiles(TEMPLATES)) {
+        const rel = abs.slice(TEMPLATES.length + 1);
+        const dest = join(target, emitPath(rel));
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, applyTokens(readFileSync(abs, "utf8"), tokens));
+        chmodSync(dest, statSync(abs).mode & 0o777);
+    }
+    for (const d of RUNTIME_DIRS) {
+        mkdirSync(join(target, d), { recursive: true });
+        writeFileSync(join(target, d, ".gitkeep"), "");
+    }
+    if (a.git) {
+        const r = spawnSync("git", ["init", "-q"], { cwd: target, stdio: "ignore" });
+        if (r.status !== 0) {
+            process.stderr.write("garaje init: warning — 'git init' failed (is git installed?); scaffold written anyway\n");
+        }
+    }
+    process.stdout.write(`Scaffolded garaje '${a.name}' at ${target}\n\n` +
+        `Next:\n` +
+        `  cd ${a.dir ?? a.name}\n` +
+        `  # add a codebase to garaje.yaml, then:  garaje park <repo>\n` +
+        `  git add -A && git commit -m 'init garaje'\n`);
+    return 0;
+}

package/dist/host/logs.js

@@ -0,0 +1,12 @@
+import { requireDocker } from "./docker.js";
+import { driverContext, getDriver } from "../driver/index.js";
+/** Default to follow + recent context unless the caller passed any flag. */
+export function logsOpts(extra) {
+    const hasFlag = extra.some((a) => a.startsWith("-"));
+    return hasFlag ? { extra } : { follow: true, tail: 100, services: extra };
+}
+/** `garaje logs` — tail logs for one or all services. */
+export function runLogs(root, extra) {
+    requireDocker();
+    return getDriver(driverContext(root)).logs(logsOpts(extra));
+}

package/dist/host/pi.js

@@ -0,0 +1,15 @@
+import { requireDocker } from "./docker.js";
+import { driverContext, ensureRunning, getDriver } from "../driver/index.js";
+/**
+ * `garaje pi` — launch the pi TUI in the running pi container, auto-starting
+ * the stack first if needed. All extra args pass through to `pi` (so `-c`,
+ * `-r`, `--session <id>`, `--name "x"`, `-p "..."` all work here).
+ */
+export function runPi(root, extra) {
+    requireDocker();
+    const driver = getDriver(driverContext(root));
+    const upStatus = ensureRunning(driver, "pi");
+    if (upStatus !== 0)
+        return upStatus;
+    return driver.exec("pi", ["pi", ...extra]);
+}

package/dist/host/sync.js

@@ -0,0 +1,7 @@
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+/** `garaje sync` / `garaje list` — delegate to the retained bash helper. */
+export function runSyncList(root, sub, extra) {
+    const helper = join(root, "bin", "garaje-sync");
+    return spawnSync("bash", [helper, sub, ...extra], { cwd: root, stdio: "inherit" }).status ?? 1;
+}

package/dist/host/up.js

@@ -0,0 +1,34 @@
+import { requireDocker } from "./docker.js";
+import { driverContext, getDriver } from "../driver/index.js";
+import { discoverBays, runPark } from "../park/index.js";
+import { runSessionsIndex } from "../sessions/run.js";
+/**
+ * `garaje up` — regenerate the parked-bays layer (best-effort), bring the
+ * stack up, refresh the sessions index (best-effort), then print the service
+ * table. Forwards extra args to the runtime's `up` (e.g. `--build`).
+ */
+export function runUp(root, extra) {
+    requireDocker();
+    // Regenerate the bays layer from synced recipes so `up` reflects what's
+    // parked. Best-effort: a bay without a recipe yet just means no output.
+    if (discoverBays(root).length > 0) {
+        try {
+            runPark(root, []);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    const driver = getDriver(driverContext(root));
+    const status = driver.up({ extra });
+    if (status !== 0)
+        return status;
+    try {
+        runSessionsIndex(root);
+    }
+    catch {
+        /* best-effort */
+    }
+    process.stdout.write(driver.psText());
+    return 0;
+}

package/dist/park/compose.js

@@ -0,0 +1,190 @@
+import { PortAllocator } from "./ports.js";
+import { devDockerfile } from "./dockerfile.js";
+/** Match the old Python tool's scalar formatting for env values. */
+function envValue(v) {
+    if (v === true)
+        return "True";
+    if (v === false)
+        return "False";
+    if (v === null)
+        return "None";
+    return String(v);
+}
+/** A flow-style list of double-quoted strings, e.g. ["CMD", "curl"]. */
+function flowList(items) {
+    const esc = (s) => s.replace(/[\x80-￿]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+    return "[" + items.map((i) => esc(JSON.stringify(String(i)))).join(", ") + "]";
+}
+/** The 4-line compose healthcheck block for a given test argv + retries. */
+function healthcheckLines(test, retries) {
+    return [
+        "    healthcheck:",
+        `      test: ${test}`,
+        "      interval: 5s",
+        "      timeout: 3s",
+        `      retries: ${retries}`,
+    ];
+}
+/** The `build:` block for the shared dev image, indented for a service body. */
+function buildLines(name, image) {
+    const out = [
+        "    build:",
+        `      context: ./bays/${name}`,
+        "      dockerfile_inline: |",
+    ];
+    for (const line of devDockerfile(image))
+        out.push(`        ${line}`);
+    return out;
+}
+function emitBay(recipe, ports) {
+    const name = recipe.name;
+    const image = recipe.image ?? {};
+    const workdir = image.workdir ?? "/app";
+    const target = recipe.mount?.target ?? workdir;
+    const devImage = `garaje-${name}-dev`;
+    const net = name;
+    const L = [];
+    const vols = [];
+    const bundleVol = `${name}-bundle`;
+    const nodeVol = `${name}-node-modules`;
+    vols.push(bundleVol, nodeVol);
+    // Shared app config emitted inline per service (no YAML anchors).
+    const appCommon = (indent = "    ") => {
+        const out = [
+            `${indent}working_dir: ${target}`,
+            `${indent}volumes:`,
+            // Bind sources resolve on the DAEMON side; build contexts stream from
+            // the CLIENT side. In-container invocations (cwd /workspace) therefore
+            // need the HOST path for mounts: GARAJE_HOST_ROOT is baked into the pi
+            // service env at `garaje up`. On the host it's unset/empty and "."
+            // preserves the old relative behavior.
+            `${indent}  - \${GARAJE_HOST_ROOT:-.}/bays/${name}:${target}`,
+            `${indent}  - ${bundleVol}:/usr/local/bundle`,
+            `${indent}  - ${nodeVol}:${target}/node_modules`,
+        ];
+        const envEntries = [];
+        for (const [k, v] of Object.entries(recipe.env ?? {})) {
+            envEntries.push(`${indent}  ${k}: "${envValue(v)}"`);
+        }
+        for (const sec of recipe.required_secrets ?? []) {
+            // File-delivered secrets arrive via the bind mount — no env guard.
+            if (sec.file)
+                continue;
+            const sn = sec.env ?? sec.name;
+            envEntries.push(`${indent}  ${sn}: "\${${sn}:?set ${sn} in .env}"`);
+        }
+        // A dangling `environment:` key is invalid for a bay with no env/secrets.
+        if (envEntries.length)
+            out.push(`${indent}environment:`, ...envEntries);
+        out.push(`${indent}networks: [${net}]`);
+        return out;
+    };
+    // --- backing services ---
+    for (const [sname, svc] of Object.entries(recipe.services ?? {})) {
+        L.push(`  ${name}-${sname}:`);
+        L.push(`    image: ${svc.image}`);
+        if (svc.env) {
+            L.push("    environment:");
+            for (const [k, v] of Object.entries(svc.env)) {
+                L.push(`      ${k}: "${envValue(v)}"`);
+            }
+        }
+        if (svc.volume) {
+            const volname = svc.volume.split(":")[0];
+            vols.push(volname);
+            L.push("    volumes:");
+            L.push(`      - ${svc.volume}`);
+        }
+        const health = svc.health?.cmd;
+        if (health) {
+            L.push(...healthcheckLines(flowList(["CMD", ...health]), 10));
+        }
+        L.push("    networks:");
+        L.push(`      ${net}:`);
+        L.push(`        aliases: [${sname}]`);
+    }
+    // --- oneshot init: builds the dev image, runs setup + bootstrap ---
+    const setup = image.setup ?? [];
+    const bootstrap = recipe.bootstrap ?? [];
+    const initCmd = [...setup, ...bootstrap].join(" && ") || "true";
+    L.push(`  ${name}-init:`);
+    L.push(`    image: ${devImage}`);
+    L.push(...buildLines(name, image));
+    L.push(`    command: ["bash", "-lc", ${JSON.stringify(initCmd)}]`);
+    L.push('    restart: "no"');
+    // A dangling `depends_on:` key is invalid for a bay with no backing services.
+    const backing = Object.keys(recipe.services ?? {});
+    if (backing.length) {
+        L.push("    depends_on:");
+        for (const sname of backing) {
+            L.push(`      ${name}-${sname}:`);
+            L.push("        condition: service_healthy");
+        }
+    }
+    L.push(...appCommon());
+    // --- app processes ---
+    for (const [pname, proc] of Object.entries(recipe.processes ?? {})) {
+        L.push(`  ${name}-${pname}:`);
+        L.push(`    image: ${devImage}`);
+        L.push("    pull_policy: never");
+        L.push(`    command: ${JSON.stringify(proc.command)}`);
+        const port = proc.port;
+        if (port) {
+            const host = ports.take(Number(port));
+            L.push("    ports:");
+            L.push(`      - "${host}:${port}"`);
+        }
+        L.push("    depends_on:");
+        L.push(`      ${name}-init:`);
+        L.push("        condition: service_completed_successfully");
+        const hpath = proc.health?.http;
+        if (hpath && port) {
+            const url = `http://localhost:${port}${hpath}`;
+            L.push(...healthcheckLines(flowList(["CMD", "curl", "-f", url]), 20));
+        }
+        L.push(...appCommon());
+    }
+    return { services: L.join("\n"), networks: [net], volumes: vols };
+}
+/** Render the full compose.bays.yaml text for the given recipes. */
+export function generate(recipes) {
+    const ports = new PortAllocator();
+    const serviceBlocks = [];
+    let nets = [];
+    let vols = [];
+    for (const r of recipes) {
+        const { services, networks, volumes } = emitBay(r, ports);
+        serviceBlocks.push(services);
+        nets = nets.concat(networks);
+        vols = vols.concat(volumes);
+    }
+    const out = [
+        "# compose.bays.yaml — GENERATED by `garaje park`. Do not edit by hand.",
+        "# Derived from garaje.yaml + each bay's recipe.yaml. COMMITTED as the",
+        "# provisioning artifact; `garaje doctor` flags drift from the recipes.",
+        "",
+        "services:",
+    ];
+    out.push(serviceBlocks.join("\n"));
+    out.push("");
+    out.push("networks:");
+    for (const n of [...new Set(nets)])
+        out.push(`  ${n}: {}`);
+    out.push("");
+    out.push("volumes:");
+    for (const v of [...new Set(vols)])
+        out.push(`  ${v}: {}`);
+    out.push("");
+    return out.join("\n");
+}
+/** The compose service names a bay's recipe generates, in emit order. The
+ *  driver-facing bay→services map — derived from the recipe (the IR), so
+ *  callers never parse generated compose. */
+export function bayServiceNames(recipe) {
+    const name = recipe.name;
+    return [
+        ...Object.keys(recipe.services ?? {}).map((s) => `${name}-${s}`),
+        `${name}-init`,
+        ...Object.keys(recipe.processes ?? {}).map((p) => `${name}-${p}`),
+    ];
+}

package/dist/park/dockerfile.js

@@ -0,0 +1,23 @@
+/** The inline dev-image Dockerfile lines (unindented). Mirrors garaje-park. */
+export function devDockerfile(image) {
+    const ruby = image.ruby ?? "3";
+    const workdir = image.workdir ?? "/app";
+    const pkgs = [...(image.system_packages ?? [])];
+    for (const required of ["curl", "ca-certificates"]) {
+        if (!pkgs.includes(required))
+            pkgs.push(required);
+    }
+    const df = [`FROM ruby:${ruby}-slim`];
+    df.push("RUN apt-get update && apt-get install -y --no-install-recommends " +
+        pkgs.join(" ") +
+        " && rm -rf /var/lib/apt/lists/*");
+    const node = image.node;
+    if (node) {
+        const major = String(node).split(".")[0];
+        df.push(`RUN curl -fsSL https://deb.nodesource.com/setup_${major}.x | bash - ` +
+            "&& apt-get install -y --no-install-recommends nodejs " +
+            "&& rm -rf /var/lib/apt/lists/*");
+    }
+    df.push(`WORKDIR ${workdir}`);
+    return df;
+}

package/dist/park/index.js

@@ -0,0 +1,77 @@
+import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseRecipe } from "./recipe.js";
+import { generate } from "./compose.js";
+/** Bay folder names under <root>/bays that contain a recipe.yaml, sorted. */
+export function discoverBays(root) {
+    const baysDir = join(root, "bays");
+    if (!existsSync(baysDir))
+        return [];
+    return readdirSync(baysDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && existsSync(join(baysDir, e.name, "recipe.yaml")))
+        .map((e) => e.name)
+        .sort();
+}
+/** Bay names declared in the committed manifest (garaje.yaml). */
+export function manifestBays(root) {
+    const path = join(root, "garaje.yaml");
+    if (!existsSync(path))
+        return [];
+    try {
+        const data = parseYaml(readFileSync(path, "utf8"));
+        return (data?.bays ?? [])
+            .map((b) => b?.name)
+            .filter((n) => Boolean(n));
+    }
+    catch {
+        return [];
+    }
+}
+/** Regenerate <root>/compose.bays.yaml from ALL synced bays' recipes. Named
+ *  args validate ("these bays must be synced with a recipe") rather than
+ *  select: the artifact is a committed whole-set derivation, so parking one
+ *  bay must never drop siblings from it. */
+export function runPark(root, bays) {
+    const dump = bays[0] === "--dump";
+    const named = dump ? bays.slice(1) : bays;
+    const synced = discoverBays(root);
+    for (const bay of named) {
+        if (!synced.includes(bay)) {
+            process.stderr.write(`garaje park: no recipe at bays/${bay}/recipe.yaml\n`);
+            return { code: 1 };
+        }
+    }
+    if (!synced.length) {
+        process.stderr.write("garaje park: no bays with a recipe.yaml (sync first?)\n");
+        return { code: 1 };
+    }
+    // The artifact derives from the SYNCED set; warn when the manifest lists
+    // more, so a partial sync can't silently narrow the committed artifact.
+    const unsynced = manifestBays(root).filter((b) => !synced.includes(b));
+    if (unsynced.length) {
+        process.stderr.write(`garaje park: WARNING — writing the artifact without unsynced manifest bay(s): ${unsynced.join(", ")} (garaje sync them and re-park)\n`);
+    }
+    const recipes = synced.map((bay) => parseRecipe(readFileSync(join(root, "bays", bay, "recipe.yaml"), "utf8"), bay));
+    const text = generate(recipes);
+    if (dump) {
+        process.stdout.write(text);
+        return { code: 0, wrote: synced.join(", ") };
+    }
+    writeFileSync(join(root, "compose.bays.yaml"), text);
+    process.stderr.write(`garaje park: wrote compose.bays.yaml for ${synced.join(", ")}\n`);
+    return { code: 0, wrote: synced.join(", ") };
+}
+/** Compare the COMMITTED bays artifact against a regeneration from the
+ *  synced recipes. The artifact is committed output (Phase 4 Plan 2); this
+ *  is the guard that keeps it from drifting silently from its inputs. */
+export function baysArtifactState(root) {
+    const names = discoverBays(root);
+    if (!names.length)
+        return "no-bays";
+    const path = join(root, "compose.bays.yaml");
+    if (!existsSync(path))
+        return "missing";
+    const recipes = names.map((bay) => parseRecipe(readFileSync(join(root, "bays", bay, "recipe.yaml"), "utf8"), bay));
+    return generate(recipes) === readFileSync(path, "utf8") ? "fresh" : "stale";
+}

package/dist/park/ports.js

@@ -0,0 +1,11 @@
+/** Assigns host ports, bumping past ones already taken (matches garaje-park). */
+export class PortAllocator {
+    used = new Set();
+    take(containerPort) {
+        let host = containerPort;
+        while (this.used.has(host))
+            host += 1;
+        this.used.add(host);
+        return host;
+    }
+}

package/dist/park/recipe.js

@@ -0,0 +1,12 @@
+import { parse as parseYaml } from "yaml";
+/** Parse recipe YAML into a Recipe, defaulting name to the bay folder name. */
+export function parseRecipe(text, fallbackName) {
+    const data = parseYaml(text);
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error("recipe did not parse to a mapping");
+    }
+    const recipe = data;
+    if (recipe.name === undefined)
+        recipe.name = fallbackName;
+    return recipe;
+}