garaje 0.1.5 → 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,10 +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;
@@ -108,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}`);
@@ -138,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);

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);
 }

package/dist/park/index.js

@@ -1,8 +1,9 @@
-import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { readManifest } from "../manifest.js";
 import { parseRecipe } from "./recipe.js";
 import { generate } from "./compose.js";
+import { generateToolchain, parseToolchainBays } from "./toolchain.js";
 /** Bay folder names under <root>/bays that contain a recipe.yaml, sorted. */
 export function discoverBays(root) {
     const baysDir = join(root, "bays");
@@ -14,8 +15,21 @@ export function discoverBays(root) {
         .sort();
 }
 /** Bay names declared in the committed manifest (garaje.yaml). Lenient: a
- *  missing or corrupt manifest yields no bays rather than throwing, because
- *  every caller here is a check that reports on it separately. */
+ *  missing or corrupt manifest yields no bays rather than throwing — safe for
+ *  every CURRENT caller, because each is a CHECK that reports a bad manifest
+ *  separately (doctor; `garaje park`'s unsynced-bay warning) and a `[]` here
+ *  changes nothing about what gets reported.
+ *
+ *  DO NOT reach for this in a WRITER. `garaje upgrade`'s planToolchain used to
+ *  call this and treated the `[]` it got back as "the manifest genuinely
+ *  declares no bays" — indistinguishable from "the manifest is missing or
+ *  corrupt", so a bad garaje.yaml silently regenerated pi/toolchain/ down to
+ *  an empty artifact instead of failing loud (fixed: planToolchain now calls
+ *  readManifest directly and gives "can't read the manifest" its own outcome,
+ *  distinct from "reads fine and says zero"). A future writer has to make
+ *  that same distinction for itself — call readManifest and handle the
+ *  throw — rather than reusing this function's leniency and re-collapsing
+ *  the two states. */
 export function manifestBays(root) {
     try {
         return readManifest(root).map((b) => b.name);
@@ -24,6 +38,52 @@ export function manifestBays(root) {
         return [];
     }
 }
+/** Parse the recipe of every named bay. Throws on a corrupt recipe; callers
+ *  that are checks (doctor) report that rather than crashing. Exported so
+ *  `garaje upgrade` can read whatever is currently parked without inventing a
+ *  second recipe-loading path. */
+export function readRecipes(root, names) {
+    return names.map((bay) => parseRecipe(readFileSync(join(root, "bays", bay, "recipe.yaml"), "utf8"), bay));
+}
+/** Where the committed pi/toolchain/ artifact lives. Exported so every caller
+ *  that needs the paths (to check existence) or the content (to compare)
+ *  shares one definition instead of re-deriving these two join() calls. */
+export function toolchainArtifactPaths(root) {
+    return {
+        misePath: join(root, "pi", "toolchain", "mise.toml"),
+        aptPath: join(root, "pi", "toolchain", "apt-packages.txt"),
+    };
+}
+/** The committed pi/toolchain/ artifact's content, or undefined if either
+ *  file is missing (a partial artifact counts as absent — same convention
+ *  toolchainArtifactState and planToolchain already used before this was
+ *  extracted). */
+export function readToolchainArtifact(root) {
+    const { misePath, aptPath } = toolchainArtifactPaths(root);
+    if (!existsSync(misePath) || !existsSync(aptPath))
+        return undefined;
+    return { miseToml: readFileSync(misePath, "utf8"), aptPackages: readFileSync(aptPath, "utf8") };
+}
+/** Write pi/toolchain/{mise.toml,apt-packages.txt} generated from `recipes`.
+ *  The ONE place that produces this artifact — `runPark` (synced bays) and
+ *  `garaje upgrade` (whatever is parked at upgrade time) both call this
+ *  instead of each re-deriving it. Passing an empty recipe list yields the
+ *  valid empty artifact, so a garaje with no bays needs no special branch. */
+export function writeToolchainArtifact(root, recipes) {
+    writeToolchain(root, generateToolchain(recipes));
+}
+/** Write an ALREADY-generated Toolchain to pi/toolchain/. Split out from
+ *  writeToolchainArtifact so a caller that must generate (and validate) the
+ *  artifact BEFORE deciding whether to write anything else — `runPark`,
+ *  which must fail before touching compose.bays.yaml if the recipe set
+ *  generateToolchain rejects — can write the exact bytes it already
+ *  generated instead of generating (and risking throwing) a second time. */
+export function writeToolchain(root, toolchain) {
+    const { misePath, aptPath } = toolchainArtifactPaths(root);
+    mkdirSync(join(root, "pi", "toolchain"), { recursive: true });
+    writeFileSync(misePath, toolchain.miseToml);
+    writeFileSync(aptPath, toolchain.aptPackages);
+}
 /** 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
@@ -44,18 +104,82 @@ export function runPark(root, bays) {
     }
     // 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));
+    // Read STRICT here, not manifestBays()'s lenient default: a `bays:` entry
+    // with no usable `name:` is syntactically valid YAML that lenient mode
+    // silently drops, which made this exact warning go silent too (the bay
+    // just vanished from the list being checked, so it never showed up as
+    // "unsynced" either). This warning is advisory, not a hard gate — park is
+    // a writer and must not crash on a bad manifest — so a strict-read failure
+    // is itself reported as a warning (naming the manifest problem) rather
+    // than thrown or silently swallowed. A garaje.yaml that is simply ABSENT
+    // is not this warning's concern (there is nothing to diff against, and
+    // other checks — e.g. doctor's repo-shape section — already report a
+    // missing manifest); only a PRESENT-but-malformed one gets the warning.
+    let manifestNames;
+    if (!existsSync(join(root, "garaje.yaml"))) {
+        manifestNames = [];
+    }
+    else {
+        try {
+            manifestNames = readManifest(root, { strict: true }).map((b) => b.name);
+        }
+        catch (e) {
+            process.stderr.write(`garaje park: WARNING — ${e.message} — cannot check for unsynced manifest bay(s)\n`);
+            manifestNames = [];
+        }
+    }
+    const unsynced = manifestNames.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 recipes = readRecipes(root, synced);
     const text = generate(recipes);
     if (dump) {
         process.stdout.write(text);
         return { code: 0, wrote: synced.join(", ") };
     }
+    // Generate (and validate — see generateToolchain's provenance round-trip
+    // assertion) the pi/toolchain/ artifact BEFORE writing anything. A recipe
+    // generateToolchain rejects (an unsafe bay name, or a provenance encoding
+    // failure) must fail park CLEANLY here — no stack trace, and neither
+    // compose.bays.yaml nor pi/toolchain/ touched — rather than writing
+    // compose.bays.yaml below and THEN throwing out of what used to be a
+    // second, later generateToolchain call. That order also used to print the
+    // narrowing WARNING below as a lie: it describes what pi/toolchain/ is
+    // about to lose, but if generation then failed, nothing was written at
+    // all.
+    let toolchain;
+    try {
+        toolchain = generateToolchain(recipes);
+    }
+    catch (e) {
+        process.stderr.write(`garaje park: ${e.message}\n`);
+        return { code: 1 };
+    }
+    // `garaje park` is the deliberate escape hatch for narrowing the committed
+    // pi/toolchain/ artifact (unlike `garaje upgrade`, which refuses outright)
+    // — but narrowing must never happen SILENTLY. The committed artifact
+    // records the exact bay set it was derived from (generateToolchain's
+    // `# bays: ...` line, read back by parseToolchainBays); if what we are
+    // about to write would drop any of those bays, warn loudly and name them
+    // before writing anyway. This is what closes the laundering route: doctor
+    // tells a user to run `garaje park` to fix a STALE artifact, and this is
+    // the only place left that can catch a park which "fixes" staleness by
+    // quietly dropping a bay instead.
+    const committedArtifact = readToolchainArtifact(root);
+    if (committedArtifact) {
+        const committedBays = parseToolchainBays(committedArtifact.miseToml);
+        if (committedBays !== undefined) {
+            const newBays = new Set(recipes.map((r) => r.name));
+            const dropped = committedBays.filter((b) => !newBays.has(b));
+            if (dropped.length > 0) {
+                process.stderr.write(`garaje park: WARNING — narrowing pi/toolchain/: dropping bay(s) the committed artifact was derived from: ${dropped.join(", ")} (if unintended, sync/author the missing bay(s) and re-park)\n`);
+            }
+        }
+    }
     writeFileSync(join(root, "compose.bays.yaml"), text);
-    process.stderr.write(`garaje park: wrote compose.bays.yaml for ${synced.join(", ")}\n`);
+    writeToolchain(root, toolchain);
+    process.stderr.write(`garaje park: wrote compose.bays.yaml + pi/toolchain/ for ${synced.join(", ")}\n`);
     return { code: 0, wrote: synced.join(", ") };
 }
 /** Compare the COMMITTED bays artifact against a regeneration from the
@@ -68,6 +192,20 @@ export function baysArtifactState(root) {
     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";
+    return generate(readRecipes(root, names)) === readFileSync(path, "utf8") ? "fresh" : "stale";
+}
+/** Same regenerate-and-diff guard as baysArtifactState, for the pi toolchain.
+ *  The pi image is a second consumer of the recipes; its artifact must not
+ *  drift from them silently either. */
+export function toolchainArtifactState(root) {
+    const names = discoverBays(root);
+    if (!names.length)
+        return "no-bays";
+    const artifact = readToolchainArtifact(root);
+    if (!artifact)
+        return "missing";
+    const want = generateToolchain(readRecipes(root, names));
+    return want.miseToml === artifact.miseToml && want.aptPackages === artifact.aptPackages
+        ? "fresh"
+        : "stale";
 }

package/dist/park/recipe.js

@@ -1,12 +1,26 @@
 import { parse as parseYaml } from "yaml";
-/** Parse recipe YAML into a Recipe, defaulting name to the bay folder name. */
+/** Parse recipe YAML into a Recipe, defaulting name to the bay folder name.
+ *
+ *  A `name:` key that parses to `null` (a bare `name:` with nothing after
+ *  it, or an explicit `~` / `null`) or to the empty string is, for every
+ *  purpose downstream, "no name was given" — it must fall back to the bay
+ *  folder name exactly like an absent `name:` (`undefined`) does. This is
+ *  read off the raw parsed `data`, not the `recipe as Recipe` cast below:
+ *  that cast is unchecked (`data as Recipe`), so TypeScript's `name: string`
+ *  cannot be trusted to reflect what untrusted YAML actually produced. Left
+ *  unhandled, a recipe with an empty `name:` used to survive as a
+ *  non-`undefined`, non-string `name` all the way into generateToolchain,
+ *  where it could defeat the `# bays: ...` provenance encoding instead of
+ *  cleanly taking the folder-name fallback. */
 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)
+    const rawName = data.name;
+    if (rawName === undefined || rawName === null || rawName === "") {
         recipe.name = fallbackName;
+    }
     return recipe;
 }