garaje 0.1.4 → 0.2.0

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

package/dist/park/toolchain.js

@@ -0,0 +1,170 @@
+import { isSafeBayName } from "../host/deps.js";
+/** The mise tool ids a recipe's `image:` block can declare. */
+const TOOLS = ["node", "ruby"];
+/**
+ * What ruby-build needs to compile Ruby from source under mise. Injected into
+ * the apt list ONLY when some bay declares a ruby — a garaje with no Ruby bay
+ * should not carry ~200MB of build deps it will never use.
+ */
+export const RUBY_BUILD_DEPS = [
+    "autoconf",
+    "build-essential",
+    "libffi-dev",
+    "libreadline-dev",
+    "libssl-dev",
+    "libyaml-dev",
+    "patch",
+    "zlib1g-dev",
+];
+/** Numeric-aware compare, so "3.10.1" sorts AFTER "3.9.1" (a plain lexical
+ *  sort gets this backwards, and the artifact would churn). */
+function byVersion(a, b) {
+    return a.localeCompare(b, undefined, { numeric: true });
+}
+/** Normalize a `.ruby-version` body ("ruby-3.4.1\n") to a bare version. */
+export function normalizeRubyVersion(text) {
+    return text.trim().replace(/^ruby-/, "");
+}
+/** A TOML array of double-quoted strings: ["3.2.2", "3.4.1"]. */
+function tomlArray(items) {
+    return `[${items.map((i) => JSON.stringify(i)).join(", ")}]`;
+}
+export function generateToolchain(recipes) {
+    const versions = new Map(TOOLS.map((t) => [t, new Set()]));
+    const packages = new Set();
+    for (const r of recipes) {
+        // The recipe's `name:` (or its bay-folder fallback) is embedded VERBATIM
+        // into the `# bays: ...` provenance line below — a comma-joined list with
+        // a `(none)` sentinel for "zero bays". An unvalidated name can defeat
+        // that encoding two ways: a name containing a comma (e.g. "web,api")
+        // parses back as MULTIPLE bays, permanently blocking `garaje upgrade`
+        // with no way to clear it; a name literally equal to "(none)" collides
+        // with the empty sentinel, parsing back to `[]` and neutering BOTH the
+        // provenance check and the isEmptyToolchain backstop at once. Neither
+        // name is reachable in a working garaje today (isSafeBayName already
+        // gates every OTHER bay-name path — sync's clone destination, doctor's
+        // bay-status check — and Docker rejects the resulting compose service
+        // key), but this is the one place that ENCODES the name into a
+        // string other code parses back apart, so it gets its own guard rather
+        // than trusting every caller upstream to have already checked.
+        if (!isSafeBayName(r.name)) {
+            throw new Error(`recipe name "${r.name}" is not a safe bay name (must match [A-Za-z0-9._-]+, and not be '.' or '..') — ` +
+                "refusing to embed it in pi/toolchain/'s `# bays:` provenance line");
+        }
+        const image = r.image ?? {};
+        for (const tool of TOOLS) {
+            const raw = image[tool];
+            if (raw === undefined || raw === null)
+                continue;
+            const v = String(raw).trim();
+            if (v !== "")
+                versions.get(tool)?.add(v);
+        }
+        for (const p of image.system_packages ?? [])
+            packages.add(p);
+    }
+    if ((versions.get("ruby")?.size ?? 0) > 0) {
+        for (const dep of RUBY_BUILD_DEPS)
+            packages.add(dep);
+    }
+    const toolLines = [];
+    for (const tool of TOOLS) {
+        const set = versions.get(tool);
+        if (!set || set.size === 0)
+            continue;
+        toolLines.push(`${tool} = ${tomlArray([...set].sort(byVersion))}`);
+    }
+    // The set of bays this artifact was derived from, recorded IN the artifact
+    // itself so a later regeneration (garaje upgrade's planToolchain) can tell
+    // a genuine "the manifest now declares fewer bays" from "disk happens to
+    // have fewer bays than what this was committed from" — see
+    // parseToolchainBays. Sorted + deduped so the line (and the whole file) is
+    // deterministic regardless of recipe order or a name declared twice.
+    const bayNames = [...new Set(recipes.map((r) => r.name))].sort();
+    const baysLine = bayNames.length ? bayNames.join(", ") : "(none)";
+    const miseToml = [
+        "# GENERATED by `garaje park` from bays/*/recipe.yaml. Do not edit by hand.",
+        "#",
+        "# The union of every parked bay's declared runtimes. mise installs all of",
+        "# them; each bay's own .ruby-version / .node-version then selects which one",
+        "# applies inside that bay. pi-lens spawns language servers with cwd = the bay",
+        "# root, so the mise shim on PATH resolves the right version with no glue.",
+        "#",
+        `# bays: ${baysLine}`,
+        "",
+        "[tools]",
+        ...toolLines,
+        "",
+        "[settings]",
+        "# Honor each bay's .ruby-version / .node-version (they already ship them).",
+        `idiomatic_version_file_enable_tools = ${tomlArray([...TOOLS])}`,
+        "",
+    ].join("\n");
+    const sorted = [...packages].sort();
+    const aptPackages = sorted.length ? `${sorted.join("\n")}\n` : "";
+    // Self-verifying provenance: don't just trust that the `# bays: ...` line
+    // above encodes bayNames correctly — prove it, using the SAME parser every
+    // downstream narrowing guard (runPark's, planToolchain's) relies on to read
+    // it back. isSafeBayName above already blocks the two encoding hazards this
+    // file's comments enumerate by hand (a comma in a name; a name literally
+    // equal to the "(none)" sentinel) — but enumerating hazards by hand is
+    // exactly how six review passes each found a new route into the same bug.
+    // This assertion does not depend on the hazard being anticipated: if
+    // ANYTHING about a name, this join, or the sentinel ever lets the header
+    // lie about the bays it was derived from, generation fails LOUD, right
+    // here, instead of shipping a provenance line that a later reader trusts.
+    const roundTrip = parseToolchainBays(miseToml);
+    const roundTripsClean = roundTrip !== undefined &&
+        roundTrip.length === bayNames.length &&
+        roundTrip.every((b, i) => b === bayNames[i]);
+    if (!roundTripsClean) {
+        throw new Error(`generateToolchain: internal error — the "# bays: ${baysLine}" provenance line does not round-trip. ` +
+            `Generated from bay(s) ${JSON.stringify(bayNames)}, but parseToolchainBays reads it back as ` +
+            `${JSON.stringify(roundTrip)}. A recipe name is defeating the provenance encoding — check the ` +
+            "recipe(s) named above for anything unusual in `name:`.");
+    }
+    return { miseToml, aptPackages };
+}
+/** True when a Toolchain carries no runtimes and no packages — the artifact
+ *  produced by zero (or all-vacuous) recipes. Compared against the canonical
+ *  empty generation rather than re-deriving "empty" from recipe internals, so
+ *  this can never drift from generateToolchain's own aggregation logic.
+ *
+ *  Exists so a WRITER (garaje upgrade's planToolchain) can refuse to replace
+ *  an existing, non-empty committed toolchain artifact with an empty one —
+ *  the structural invariant behind three separate bugs found in that seam. */
+export function isEmptyToolchain(t) {
+    const empty = generateToolchain([]);
+    return t.miseToml === empty.miseToml && t.aptPackages === empty.aptPackages;
+}
+/** Read the `# bays: <names>` provenance line `generateToolchain` embeds in
+ *  mise.toml back out again — the other half of that round-trip.
+ *
+ *  Returns:
+ *  - `string[]` (possibly empty, for the recorded `(none)`) when the line is
+ *    present — the bay set the committed artifact was actually derived from.
+ *  - `undefined` when no such line exists at all (a hand-written artifact, or
+ *    one committed before this provenance line existed). Callers MUST NOT
+ *    treat `undefined` the same as `[]`: one means "we don't know", the other
+ *    means "derived from zero bays, and we know it".
+ *
+ *  This is what lets planToolchain refuse to regenerate a NARROWER artifact
+ *  than what is actually committed, closing the bug class where the on-disk
+ *  bay set is smaller than the set the committed artifact came from (a
+ *  gitignored bays/ on a fresh clone, a `bays:` entry silently dropped for
+ *  lacking `name:`, a bay parked locally but never added to garaje.yaml, ...)
+ *  — every one of those makes discoverBays()/readRecipes() return less than
+ *  the committed truth, and no comparison of "would this regen be empty"
+ *  alone can catch a narrowing that stops short of empty. */
+export function parseToolchainBays(miseToml) {
+    const m = miseToml.match(/^# bays: (.*)$/m);
+    if (!m)
+        return undefined;
+    const body = m[1].trim();
+    if (body === "(none)")
+        return [];
+    return body
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}