garaje 0.1.4 → 0.2.0

package/dist/driver/compose.js

@@ -120,6 +120,9 @@ export class ComposeDriver {
     requiredFiles() {
         return ["docker-compose.yml", "compose.framework.yaml"];
     }
+    frameworkOwnedFiles() {
+        return ["docker-compose.yml", "compose.framework.yaml"];
+    }
 }
 /** The generated bays layer's presence — driver-internal filename knowledge. */
 export function hasBaysLayer(root) {

package/dist/host/deps.js

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parseRecipe } from "../park/recipe.js";
+/** Lockfiles whose content decides whether a bay's pi-side deps are stale. */
+const LOCKFILES = ["Gemfile.lock", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
+/** A bay name is interpolated into an `sh -c` script below, and is also joined
+ *  onto `root` as a bare path component (here and in sync.ts). Anything outside
+ *  this set is refused rather than escaped — bays are directory names, and a
+ *  name that needs shell escaping is a name we do not want. The character
+ *  class alone is not enough: `.` and `..` are pure runs of an allowed
+ *  character but are not bay directories at all — they resolve to `bays/`
+ *  itself or the garaje root, so both are refused explicitly too. */
+const SAFE_BAY = /^[A-Za-z0-9._-]+$/;
+/** Whether `name` is safe to use both as a shell argument (installBayDeps) and
+ *  as a `bays/<name>` path component (installBayDeps; sync.ts's clone/fetch
+ *  destination; and sync.ts's bayStatus, which otherwise resolves '..' to the
+ *  garaje root and reports it "synced" at the root's own HEAD). Exported so
+ *  every call site shares one guard instead of each keeping its own copy of
+ *  the regex and the `.`/`..` exclusion.
+ *
+ *  Takes `unknown`, not `string`, and leads with a `typeof` check rather than
+ *  handing the value straight to `SAFE_BAY.test`. `RegExp.prototype.test`
+ *  coerces its argument to a string before matching — so `test(null)` matches
+ *  against the literal string `"null"` and PASSES. A caller with a real
+ *  compile-time `string` type never notices; the hazard is every caller that
+ *  reaches this with a value whose static type lies — e.g. a `Recipe.name`
+ *  read off an unchecked `as Recipe` cast over parsed YAML, where a `name:`
+ *  key that parses to `null` is reachable at runtime despite the field being
+ *  typed `string`. This is a security guard (path traversal, shell
+ *  injection) as well as a provenance guard, so it must fail closed for
+ *  every non-string input, not just the ones some caller's types happen to
+ *  rule out. */
+export function isSafeBayName(name) {
+    return typeof name === "string" && SAFE_BAY.test(name) && name !== "." && name !== "..";
+}
+/** Content hash of a bay's lockfiles, MIXED with its recipe's declared runtime
+ *  versions (image.ruby / image.node). The lockfile alone is not enough: bump
+ *  a bay's Ruby (recipe + .ruby-version) without touching Gemfile.lock, and a
+ *  lockfile-only hash would still match the recorded stamp — `garaje sync`
+ *  would report "up to date" while BUNDLE_PATH/ruby/<new-abi>/ is empty and
+ *  every `bundle exec` fails. Order-stable; a missing lockfile or a recipe
+ *  with no declared runtime simply contributes nothing. A corrupt recipe is
+ *  reported elsewhere (doctor / park); here it just contributes no
+ *  runtime-version bytes rather than throwing mid-sync. */
+export function lockfileHash(bayDir) {
+    const h = createHash("sha256");
+    for (const name of [...LOCKFILES].sort()) {
+        const p = join(bayDir, name);
+        if (!existsSync(p))
+            continue;
+        h.update(name);
+        h.update(readFileSync(p));
+    }
+    const recipePath = join(bayDir, "recipe.yaml");
+    if (existsSync(recipePath)) {
+        try {
+            const recipe = parseRecipe(readFileSync(recipePath, "utf8"), basename(bayDir));
+            const image = recipe.image ?? {};
+            for (const tool of ["ruby", "node"]) {
+                const raw = image[tool];
+                if (raw === undefined || raw === null)
+                    continue;
+                h.update(tool);
+                h.update(String(raw).trim());
+            }
+        }
+        catch {
+            // corrupt recipe — contribute nothing rather than crash the hash.
+        }
+    }
+    return h.digest("hex").slice(0, 16);
+}
+/** Where a bay's recorded hash lives ON THE pi-deps VOLUME (a container path). */
+export function stampPath(bay) {
+    return `/garaje/deps/.stamp/${bay}`;
+}
+/** The `setup` commands a bay's recipe declares. The recipe is the single
+ *  source of truth for "how this project installs" — we do not invent a
+ *  second one for the pi side. */
+export function setupCommands(root, bay) {
+    const p = join(root, "bays", bay, "recipe.yaml");
+    if (!existsSync(p))
+        return [];
+    return parseRecipe(readFileSync(p, "utf8"), bay).image?.setup ?? [];
+}
+/** One line of `garaje sync` output for a dep outcome. `width` should be the
+ *  longest bay name among everything being reported this run (the caller
+ *  knows that; a single outcome does not) — padEnd never truncates, so a name
+ *  longer than `width` still gets its explicit separating space rather than
+ *  running straight into "deps" (e.g. an 8-char default swallowed the space
+ *  for a 9-char name like "hello-bay"). */
+export function renderDepsOutcome(o, width = 8) {
+    const tag = `  ${o.bay.padEnd(width)} deps  `;
+    switch (o.kind) {
+        case "installed":
+            return `${tag}installed ✓\n`;
+        case "fresh":
+            return `${tag}up to date (lockfile unchanged) ✓\n`;
+        case "no-setup":
+            return `${tag}nothing to install (recipe declares no setup)\n`;
+        case "failed":
+            return `${tag}FAILED\n${o.detail.replace(/^/gm, "        ")}\n`;
+    }
+}
+/**
+ * Install one bay's dependencies inside the pi container, so pi-lens's language
+ * servers and linters see the real project. Idempotent: keyed on the bay's
+ * lockfile hash, recorded on the pi-deps volume.
+ *
+ * Gems land under the container-wide BUNDLE_PATH (/garaje/deps/bundle), which a
+ * single shared path can serve for every bay — bundler namespaces by Ruby ABI
+ * directory and activates strictly from the calling project's Gemfile.lock.
+ *
+ * `onStart`, if given, fires right before the setup script actually runs — NOT
+ * before the freshness check, and not at all for a "fresh" or "no-setup"
+ * outcome. `execCapture` buffers output, so a cold `bundle install` on a real
+ * Rails app runs 20s-to-minutes with zero output otherwise; callers use this
+ * to tell the user an install is starting and why it may be slow.
+ */
+export function installBayDeps(root, bay, driver, onStart) {
+    if (!isSafeBayName(bay)) {
+        return { kind: "failed", bay, detail: `unsafe bay name '${bay}' — refusing to run it in a shell` };
+    }
+    const setup = setupCommands(root, bay);
+    if (!setup.length)
+        return { kind: "no-setup", bay };
+    const want = lockfileHash(join(root, "bays", bay));
+    const stamp = stampPath(bay);
+    const seen = driver.execCapture("pi", ["sh", "-c", `cat ${stamp} 2>/dev/null || true`]);
+    if (seen.status === 0 && seen.stdout.trim() === want)
+        return { kind: "fresh", bay };
+    onStart?.(bay);
+    const script = [
+        "set -e",
+        `cd /workspace/bays/${bay}`,
+        ...setup,
+        "mkdir -p /garaje/deps/.stamp",
+        `printf %s ${want} > ${stamp}`,
+    ].join("\n");
+    const r = driver.execCapture("pi", ["sh", "-c", script]);
+    if (r.status !== 0) {
+        const detail = (r.stderr || r.stdout).trim().split("\n").slice(-3).join("\n");
+        return { kind: "failed", bay, detail: detail || `setup exited ${r.status}` };
+    }
+    return { kind: "installed", bay };
+}

package/dist/host/doctor.js

@@ -2,9 +2,56 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { driverContext, getDriver } from "../driver/index.js";
-import { baysArtifactState, discoverBays, manifestBays } from "../park/index.js";
+import { baysArtifactState, discoverBays, manifestBays, toolchainArtifactState, } from "../park/index.js";
+import { normalizeRubyVersion } from "../park/toolchain.js";
+import { parseRecipe } from "../park/recipe.js";
+import { readManifest } from "../manifest.js";
 import { basePinSource } from "../upgrade/pins.js";
 import { bayStatuses, statusLine } from "./sync.js";
+import { classifyModelList, defaultModelOf, hasInferenceCredential } from "./provider.js";
+/** Bays whose recipe `image.ruby` disagrees with their own `.ruby-version`.
+ *  mise installs what the RECIPE declares, but resolves per-bay from the
+ *  version FILE — so a disagreement means the bay asks for a ruby that was
+ *  never installed, and its language server dies for a reason nobody would
+ *  trace back to the recipe. */
+export function rubyVersionMismatches(root) {
+    const out = [];
+    for (const bay of discoverBays(root)) {
+        const dir = join(root, "bays", bay);
+        let declared;
+        try {
+            const recipe = parseRecipe(readFileSync(join(dir, "recipe.yaml"), "utf8"), bay);
+            const raw = recipe.image?.ruby;
+            declared = raw === undefined || raw === null ? undefined : String(raw).trim();
+        }
+        catch {
+            continue; // a corrupt recipe is reported by the artifact check, not here
+        }
+        if (!declared)
+            continue;
+        const versionFile = join(dir, ".ruby-version");
+        if (!existsSync(versionFile))
+            continue;
+        // existsSync is true for a directory too — a stray `mkdir .ruby-version`
+        // (or any other unreadable path) must not crash doctor. Treat it the same
+        // as a MISSING version file: skip this bay silently and keep checking the
+        // others, since an unreadable version file is not something doctor can
+        // report anything useful about.
+        let versionText;
+        try {
+            versionText = readFileSync(versionFile, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const wanted = normalizeRubyVersion(versionText);
+        if (wanted && wanted !== declared) {
+            out.push(`${bay}: recipe.yaml declares ruby ${declared} but .ruby-version asks for ${wanted} — ` +
+                `mise installs the recipe's, so the language server will not start`);
+        }
+    }
+    return out;
+}
 /** `garaje doctor` — host-side sanity checks. Exit code = failed-check count. */
 export function runDoctor(root) {
     let fails = 0;
@@ -59,10 +106,33 @@ export function runDoctor(root) {
         else
             fail(`@garaje/base path pin "${source}" missing — no package.json at ${dir}`);
     }
-    if (existsSync(join(root, ".env")))
-        pass(".env present");
-    else
-        warn(".env missing — copy .env.example and add ANTHROPIC_API_KEY (or use /login)");
+    // .env is the garaje's single credential surface (compose forwards it via
+    // env_file). Provider-neutral: any non-empty *_API_KEY counts, so adding a
+    // new provider needs no change here.
+    const envPath = join(root, ".env");
+    if (!existsSync(envPath)) {
+        warn(".env missing — copy .env.example and add a provider key (e.g. MIXLAYER_API_KEY)");
+    }
+    else {
+        // .env could be a directory (stray mkdir, misconfigured tool) or otherwise
+        // unreadable; report that as a failed check rather than crashing (same
+        // contract as the garaje.yaml and recipe checks below).
+        let envText;
+        try {
+            envText = readFileSync(envPath, "utf8");
+        }
+        catch (e) {
+            fail(`.env unreadable — ${e.message}`);
+        }
+        if (envText !== undefined) {
+            if (hasInferenceCredential(envText)) {
+                pass(".env carries an inference credential");
+            }
+            else {
+                warn(".env has no non-empty *_API_KEY — pi will start but cannot answer");
+            }
+        }
+    }
     // --- runtime state ---
     section("runtime");
     if (driver.configOk())
@@ -84,11 +154,28 @@ export function runDoctor(root) {
         if (!bays.length)
             warn("no bays parked (add one to garaje.yaml, then garaje sync)");
         for (const b of bays) {
-            if (b.synced)
+            if (b.unsafe)
+                fail(`${b.name}: ${statusLine(b)} (bay names must be plain directory names, not '.' or '..')`);
+            else if (b.synced)
                 pass(`${b.name}: ${statusLine(b)} (${b.ref})`);
             else
                 warn(`${b.name}: ${statusLine(b)} — run \`garaje sync ${b.name}\``);
         }
+        // bayStatuses() above (readManifest, lenient) already proved garaje.yaml
+        // itself parses as YAML — so if a STRICT re-read throws here, it can only
+        // be because a `bays:` entry is well-formed YAML but still has no usable
+        // name, which lenient mode silently drops instead of erroring. That drop
+        // is otherwise completely invisible: the bay just never appears above.
+        try {
+            readManifest(root, { strict: true });
+        }
+        catch (e) {
+            // (e as Error).message already carries a "garaje.yaml: " prefix (see
+            // parseManifest) — do not prepend a second one.
+            warn(`${e.message} — lenient parsing silently drops this bay ` +
+                "(name it to fix; `garaje upgrade` refuses to narrow a committed toolchain because of it, " +
+                "but every other bay-aware command just silently ignores it)");
+        }
     }
     catch (e) {
         fail(`bay status check errored — garaje.yaml failed to parse: ${e.message}`);
@@ -114,6 +201,22 @@ export function runDoctor(root) {
     catch (e) {
         fail(`bays artifact check errored — a recipe failed to parse: ${e.message}`);
     }
+    try {
+        const tc = toolchainArtifactState(root);
+        if (tc === "fresh")
+            pass("pi toolchain artifact matches the recipes (regenerate-and-diff)");
+        else if (tc === "no-bays")
+            warn("no parked bays — pi toolchain not checkable");
+        else if (tc === "missing")
+            fail("pi/toolchain/ missing — run `garaje park` and commit the result");
+        else
+            fail("pi toolchain artifact STALE — recipes changed; run `garaje park` and commit the diff");
+    }
+    catch (e) {
+        fail(`pi toolchain check errored — a recipe failed to parse: ${e.message}`);
+    }
+    for (const m of rubyVersionMismatches(root))
+        warn(m);
     // "Parked" (has a recipe.yaml) is a stricter state than "synced" (cloned);
     // only parked bays contribute to the artifact.
     const parked = discoverBays(root);
@@ -139,6 +242,49 @@ export function runDoctor(root) {
             pass(`pi binary works: ${piver}`);
         else
             fail("pi --version did not print a version");
+        // A key stored by `/login` outranks .env: model-registry resolves
+        // `apiKeyFromAuthStorage ?? providerConfig.apiKey`. Existence only — doctor
+        // never reads this file.
+        if (driver.execCapture("pi", ["test", "-f", "/root/.pi/agent/auth.json"]).status === 0) {
+            warn("/root/.pi/agent/auth.json exists — a stored `/login` credential OVERRIDES .env");
+        }
+        // Proves the provider extension loaded AND a credential is present. It
+        // does NOT validate the key: pi lists models for a bogus key exactly as it
+        // would for a real one — but with NO credential at all, `pi --list-models`
+        // exits 0 and prints "No models available" instead of a table. That is a
+        // separate condition from a model genuinely missing from a populated
+        // table, so it must warn, not fail (a freshly scaffolded garaje with no
+        // key yet must not report a hard failure here).
+        const model = existsSync(settings)
+            ? defaultModelOf(readFileSync(settings, "utf8"))
+            : undefined;
+        if (!model) {
+            warn("no defaultModel in .pi/settings.json — pi will prompt for a model");
+        }
+        else {
+            const listed = driver.execCapture("pi", ["pi", "--list-models"]);
+            if (listed.status !== 0) {
+                fail(`\`pi --list-models\` exited ${listed.status} — could not check defaultModel`);
+            }
+            else {
+                const verdict = classifyModelList(listed.stdout, model);
+                if (verdict === "no-models") {
+                    // A credential can exist (e.g. a key for a provider this garaje
+                    // isn't configured to use) while no *loaded* provider has a usable
+                    // one — CI's exact case: MIXLAYER_API_KEY set, but this repo's
+                    // settings select anthropic and no mixlayer extension is pinned.
+                    // Naming only "no credential" would misdirect toward the key when
+                    // the real cause may be a missing provider extension instead.
+                    warn(`pi lists no models — no loaded provider has a usable credential (key missing, or its provider extension isn't installed); defaultModel "${model}" cannot be verified`);
+                }
+                else if (verdict === "listed") {
+                    pass(`defaultModel registered: ${model} (extension loaded, credential present; key NOT validated)`);
+                }
+                else {
+                    fail(`defaultModel "${model}" absent from \`pi --list-models\` — provider extension missing or model id wrong`);
+                }
+            }
+        }
     }
     // --- summary ---
     section("summary");

package/dist/host/provider.js

@@ -0,0 +1,43 @@
+/** Pure helpers behind `garaje doctor`'s inference-provider checks. No fs, no
+ *  spawn — doctor's container probes are covered by scripts/ci-smoke instead. */
+/** True when a dotenv body sets any *_API_KEY to a non-empty value. A blank
+ *  assignment doesn't count: a scaffolded `.env.example` copied verbatim has
+ *  `MIXLAYER_API_KEY=` and therefore no credential. Lines may optionally be
+ *  prefixed with `export ` (for shell sourcing compatibility). */
+export function hasInferenceCredential(envText) {
+    for (const raw of envText.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*_API_KEY)\s*=\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        if (m[2].trim().replace(/^["']|["']$/g, "").length > 0)
+            return true;
+    }
+    return false;
+}
+/** The `defaultModel` a garaje's committed pi settings select, if any. */
+export function defaultModelOf(settingsText) {
+    try {
+        const data = JSON.parse(settingsText);
+        return typeof data.defaultModel === "string" && data.defaultModel
+            ? data.defaultModel
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `pi --list-models` output registers the given model id. */
+export function modelListed(listOutput, model) {
+    return listOutput.split(/\r?\n/).some((l) => l.includes(model));
+}
+/** Classify `pi --list-models` output. pi prints "No models available" when no
+ *  provider credential is present — a different condition from a model that is
+ *  genuinely missing from a populated table. */
+export function classifyModelList(listOutput, model) {
+    if (/no models available/i.test(listOutput))
+        return "no-models";
+    return modelListed(listOutput, model) ? "listed" : "absent";
+}

package/dist/host/sync.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { readManifest } from "../manifest.js";
+import { driverContext, getDriver } from "../driver/index.js";
+import { installBayDeps, isSafeBayName, renderDepsOutcome } from "./deps.js";
 function git(args) {
     return spawnSync("git", args, { stdio: "inherit" }).status ?? 1;
 }
@@ -21,6 +23,12 @@ function readOrReport(root) {
 }
 /** Whether one manifest bay is materialized, and at which commit. */
 function bayStatus(root, bay) {
+    // Same guard as installBayDeps and runSync's clone/fetch: an unsafe name
+    // (e.g. '..') joined onto `bays/` resolves outside bays/ entirely — for
+    // '..' that is the garaje root itself, whose own .git would otherwise be
+    // reported as this bay "synced" at the garaje's real HEAD.
+    if (!isSafeBayName(bay.name))
+        return { ...bay, synced: false, unsafe: true };
     const dest = join(root, "bays", bay.name);
     if (!existsSync(join(dest, ".git")))
         return { ...bay, synced: false };
@@ -36,6 +44,8 @@ export function bayStatuses(root) {
 }
 /** One human-readable line per bay. Pure — doctor reuses this. */
 export function statusLine(b) {
+    if (b.unsafe)
+        return "invalid bay name — fix garaje.yaml";
     return b.synced ? `synced @ ${b.head}` : "not synced";
 }
 /** The `garaje list` table. Pure. */
@@ -57,8 +67,16 @@ export function runList(root) {
     process.stdout.write(renderList(entries.map((b) => bayStatus(root, b))));
     return 0;
 }
-/** `garaje sync [name...]` — clone/update the manifest's bays into bays/. */
-export function runSync(root, names) {
+/** `garaje sync [--no-deps] [name...]` — clone/update the manifest's bays into
+ *  bays/, then install each one's dependencies inside the pi container so
+ *  pi-lens's language servers and linters see the real project.
+ *
+ *  The dep step DEGRADES, never fails: `garaje sync` is the verb you run on a
+ *  fresh clone BEFORE `garaje up`, so it must not acquire a hard dependency on
+ *  the pi container being up. */
+export function runSync(root, argv) {
+    const noDeps = argv.includes("--no-deps");
+    const names = argv.filter((a) => a !== "--no-deps");
     if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
         process.stderr.write("error: git not found in PATH\n");
         return 1;
@@ -79,6 +97,10 @@ export function runSync(root, names) {
             process.stderr.write(`skip ${bay.name}: no repo in manifest\n`);
             continue;
         }
+        if (!isSafeBayName(bay.name)) {
+            process.stderr.write(`error: garaje.yaml: unsafe bay name '${bay.name}' — fix the manifest (bay names must be plain directory names, not '.' or '..')\n`);
+            return 1;
+        }
         const dest = join(root, "bays", bay.name);
         if (existsSync(join(dest, ".git"))) {
             process.stdout.write(`==> ${bay.name}: fetching (${bay.ref})\n`);
@@ -106,5 +128,23 @@ export function runSync(root, names) {
         synced += 1;
     }
     process.stdout.write(`synced ${synced} bay(s) into bays/\n`);
-    return 0;
+    if (noDeps)
+        return 0;
+    const driver = getDriver(driverContext(root));
+    if (!driver.runningServices().includes("pi")) {
+        process.stdout.write("  deps  skipped — pi is not running (garaje up, then re-sync)\n");
+        return 0;
+    }
+    let depsFailed = 0;
+    // Width for both the "starting" line and the outcome line, so they line up:
+    // the longest bay name being reported this run, not a fixed guess (a fixed
+    // 8 silently ran a 9-char name like "hello-bay" straight into "deps").
+    const width = wanted.length ? Math.max(...wanted.map((b) => b.name.length)) : 0;
+    for (const bay of wanted) {
+        const outcome = installBayDeps(root, bay.name, driver, (name) => process.stdout.write(`  ${name.padEnd(width)} deps  installing (recipe setup — a cold cache can take a while)...\n`));
+        process.stdout.write(renderDepsOutcome(outcome, width));
+        if (outcome.kind === "failed")
+            depsFailed += 1;
+    }
+    return depsFailed > 0 ? 1 : 0;
 }

package/dist/manifest.js

@@ -1,24 +1,40 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
-/** Parse the `bays:` list out of a garaje.yaml. Entries without a name are
- *  dropped; `ref` defaults to main. Pure — throws only on malformed YAML. */
-export function parseManifest(text) {
+/** Parse the `bays:` list out of a garaje.yaml. `ref` defaults to main. Pure —
+ *  throws on malformed YAML always, and (with `{ strict: true }`) on a
+ *  well-formed-YAML entry that still can't yield a name. */
+export function parseManifest(text, opts = {}) {
     const data = parseYaml(text);
-    const bays = Array.isArray(data?.bays) ? data.bays : [];
-    return bays
-        .filter((b) => Boolean(b) && typeof b === "object")
-        .map((b) => ({
-        name: String(b.name ?? "").trim(),
-        repo: String(b.repo ?? "").trim(),
-        ref: String(b.ref ?? "main").trim() || "main",
-    }))
-        .filter((b) => b.name);
+    const rawBays = Array.isArray(data?.bays) ? data.bays : [];
+    const bays = [];
+    rawBays.forEach((b, i) => {
+        if (!b || typeof b !== "object") {
+            if (opts.strict)
+                throw new Error(`garaje.yaml: bays[${i}] is not a mapping`);
+            return;
+        }
+        const rec = b;
+        const name = String(rec.name ?? "").trim();
+        if (!name) {
+            if (opts.strict)
+                throw new Error(`garaje.yaml: bays[${i}] has no name`);
+            return;
+        }
+        bays.push({
+            name,
+            repo: String(rec.repo ?? "").trim(),
+            ref: String(rec.ref ?? "main").trim() || "main",
+        });
+    });
+    return bays;
 }
-/** Read <root>/garaje.yaml. Throws if it is missing or unparseable. */
-export function readManifest(root) {
+/** Read <root>/garaje.yaml. Throws if it is missing or unparseable (and, with
+ *  `{ strict: true }`, if a `bays:` entry can't yield a name — see
+ *  ParseManifestOptions). */
+export function readManifest(root, opts = {}) {
     const path = join(root, "garaje.yaml");
     if (!existsSync(path))
         throw new Error("no garaje.yaml at the garaje root");
-    return parseManifest(readFileSync(path, "utf8"));
+    return parseManifest(readFileSync(path, "utf8"), opts);
 }