garaje 0.1.5 → 0.2.0

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

package/dist/upgrade/index.js

@@ -1,9 +1,16 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { classify } from "./classify.js";
 import { currentBaseVersion, rewriteBasePin, rewriteDockerfileCliPin } from "./pins.js";
+import { DEFAULT_PACKAGES, isScaffoldedGaraje, mergeSettingsPackages, missingDefaultPackages, rematerialize, scaffoldPiLensConfig, } from "./managed.js";
+import { discoverBays, readRecipes, readToolchainArtifact, writeToolchainArtifact, } from "../park/index.js";
+import { generateToolchain, isEmptyToolchain, parseToolchainBays, } from "../park/toolchain.js";
+import { readManifest } from "../manifest.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(HERE, "../../templates"); // packages/cli/templates
 /** Resolve @garaje/base@<version> into a directory tree via `npm pack`, or
  *  undefined if it can't be fetched (e.g. pre-publish / offline). */
 function fetchBaseTree(version) {
@@ -29,6 +36,200 @@ function parseTo(args) {
         return args[i + 1];
     return undefined;
 }
+/** Re-read recipes one bay at a time to name whichever one is corrupt, for a
+ *  better error message. Reuses readRecipes itself rather than re-implementing
+ *  any parsing — this only narrows down which single bay a whole-list throw
+ *  came from. */
+function describeRecipeFailure(root, bays, err) {
+    for (const bay of bays) {
+        try {
+            readRecipes(root, [bay]);
+        }
+        catch (e) {
+            return `bay '${bay}' has a corrupt recipe.yaml (${e.message}) — fix it, then re-run upgrade`;
+        }
+    }
+    return `a bay recipe.yaml failed to parse (${err.message}) — fix it, then re-run upgrade`;
+}
+/** Bays the manifest names but discoverBays() didn't find parked (no
+ *  recipe.yaml) — split into "not even cloned" (garaje sync will help) vs
+ *  "cloned but missing recipe.yaml" (sync is a no-op there; `garaje park`
+ *  only fails outright when NOTHING anywhere is parked, so it silently
+ *  excludes this bay rather than fixing it — the real remedy is authoring
+ *  bays/<name>/recipe.yaml). doctor.ts draws this same "parked is stricter
+ *  than synced/cloned" line; this mirrors it with a concrete per-bay remedy
+ *  instead of one blanket "sync then park" that is actively wrong for a
+ *  bay that is already cloned. */
+function describeUnparkedBays(root, names) {
+    const notCloned = names.filter((n) => !existsSync(join(root, "bays", n, ".git")));
+    const clonedNoRecipe = names.filter((n) => !notCloned.includes(n));
+    const parts = [];
+    if (notCloned.length) {
+        parts.push(`not synced: ${notCloned.join(", ")} (run \`garaje sync\`, then \`garaje park\`)`);
+    }
+    if (clonedNoRecipe.length) {
+        const authorHint = clonedNoRecipe.length === 1
+            ? `bays/${clonedNoRecipe[0]}/recipe.yaml`
+            : clonedNoRecipe.map((n) => `bays/${n}/recipe.yaml`).join(", ");
+        parts.push(`cloned but missing recipe.yaml: ${clonedNoRecipe.join(", ")} (author ${authorHint}, ` +
+            "then `garaje park` — `garaje sync` is a no-op here)");
+    }
+    return parts.join("; ");
+}
+/**
+ * Decide the pi/toolchain/ outcome for `garaje upgrade`, using BOTH the
+ * committed manifest (garaje.yaml, read STRICTLY via readManifest — see
+ * below) and what is actually on disk (discoverBays) — never discoverBays
+ * alone, and never manifestBays().
+ *
+ * bays/* is gitignored in every garaje: a fresh clone has the manifest but
+ * none of the bay working trees. discoverBays() then returns [], and
+ * regenerating from that would silently gut a correct, committed toolchain
+ * artifact down to empty (Finding A) — worse than the bug this replaced,
+ * because `garaje up --build` then succeeds with a Ruby-less pi container.
+ *
+ * Decision table:
+ * - garaje.yaml unreadable (missing, corrupt, OR — strict mode — a `bays:`
+ *   entry with no usable `name:`) and pi/toolchain/ IS committed -> leave it
+ *   (it is still the last-known truth) and say why.
+ * - garaje.yaml unreadable and pi/toolchain/ is NOT committed -> fail before
+ *   any write: there is nothing to derive the toolchain from and nothing to
+ *   fall back on (Finding C — manifestBays() used to collapse this into the
+ *   same `[]` as "the manifest genuinely declares no bays", and `write` then
+ *   gutted or fabricated an empty artifact instead of failing loud).
+ * - every manifest bay parked (including the vacuous case: manifest declares
+ *   none) -> regenerate from the parked recipes; readRecipes can still throw
+ *   on a corrupt recipe, which this catches and reports as "fail" rather than
+ *   letting it escape as an uncaught exception (Finding B) — UNLESS doing so
+ *   would NARROW a committed artifact (see the structural invariant below),
+ *   in which case that fires instead of "write".
+ * - some of the manifest's bays are not parked -> the committed artifact, if
+ *   present, was generated from these recipes when they WERE parked, so it
+ *   is still ground truth: leave it untouched and say why (which bay(s), and
+ *   the CORRECT remedy per bay — see describeUnparkedBays).
+ * - same, but pi/toolchain/ doesn't exist at all -> nothing to fall back on;
+ *   fail the upgrade outright rather than materialize a Dockerfile whose
+ *   `COPY toolchain/` has nothing to copy.
+ *
+ * STRUCTURAL INVARIANT: never replace a committed toolchain artifact with one
+ * derived from a SMALLER bay set than the artifact itself records. Four
+ * separate bugs have now reached "artifact silently narrowed, image builds,
+ * pi is missing a runtime" by four different routes — a gitignored bays/ on a
+ * fresh clone, a corrupt garaje.yaml, a `bays:` entry silently dropped for
+ * lacking `name:` (syntactically valid YAML — parseManifest's lenient mode
+ * does not throw on it), and a bay parked locally but never added to
+ * garaje.yaml at all. Patching each route individually kept finding a new
+ * one; the actual invariant is about the ARTIFACT, not any one cause:
+ * `generateToolchain` now records the bay set it was derived from in a
+ * `# bays: ...` comment (parseToolchainBays reads it back). If the committed
+ * artifact's recorded set is not a subset of the set we are about to
+ * regenerate from — i.e. regenerating would drop a bay the committed
+ * artifact reflects — refuse, whatever the cause, and name the dropped
+ * bay(s). Regenerating from the SAME set, or a LARGER one, is unaffected.
+ * `isEmptyToolchain` remains as a backstop for an artifact committed before
+ * this provenance line existed (no `# bays:` to compare against).
+ */
+export function planToolchain(root) {
+    const committed = readToolchainArtifact(root); // undefined = nothing committed at all
+    // Read the manifest STRICTLY — this is a WRITER, not a check. manifestBays()
+    // is lenient (missing/corrupt -> []) because every OTHER caller is a check
+    // that reports a bad manifest and moves on; see its docstring in
+    // ../park/index.ts for why a writer must not reuse that leniency. Strict
+    // mode additionally throws on a `bays:` entry with no usable name — see
+    // ParseManifestOptions in ../manifest.ts — so THAT silent-drop route is
+    // caught here directly, same as a missing/corrupt garaje.yaml, rather than
+    // relying solely on the narrowing check below to notice its effect.
+    let manifest;
+    try {
+        manifest = readManifest(root, { strict: true });
+    }
+    catch (e) {
+        const reason = e.message;
+        if (committed) {
+            return {
+                action: "leave",
+                message: `garaje.yaml is unreadable (${reason}) — pi/toolchain/ left as committed (fix garaje.yaml, then re-run upgrade)`,
+            };
+        }
+        return {
+            action: "fail",
+            message: `garaje.yaml is unreadable (${reason}) and pi/toolchain/ does not exist — the toolchain can't ` +
+                `be derived and the image won't build. Fix garaje.yaml, then re-run upgrade.`,
+        };
+    }
+    const manifestNames = manifest.map((b) => b.name);
+    const parked = discoverBays(root);
+    const unparked = manifestNames.filter((b) => !parked.includes(b));
+    if (unparked.length === 0) {
+        let recipes;
+        try {
+            recipes = readRecipes(root, parked);
+        }
+        catch (e) {
+            return { action: "fail", message: describeRecipeFailure(root, parked, e) };
+        }
+        // generateToolchain can ALSO throw (an unsafe bay name, or — the
+        // structural backstop — a provenance round-trip failure), and used to do
+        // so OUTSIDE any try/catch here, routing around the `action: "fail"` path
+        // this whole ToolchainPlan design exists to provide: the exception
+        // propagated straight out of planToolchain, then out of runUpgrade (which
+        // has no top-level catch either), and `garaje upgrade` printed a raw
+        // Node stack trace instead of a clean, actionable failure.
+        let toolchain;
+        try {
+            toolchain = generateToolchain(recipes);
+        }
+        catch (e) {
+            return {
+                action: "fail",
+                message: `pi/toolchain/ can't be generated (${e.message}) — fix the recipe, then re-run upgrade`,
+            };
+        }
+        if (committed) {
+            const committedBays = parseToolchainBays(committed.miseToml);
+            if (committedBays !== undefined) {
+                // The provenance line is present — do the precise per-bay diff.
+                const newBays = new Set(recipes.map((r) => r.name));
+                const dropped = committedBays.filter((b) => !newBays.has(b));
+                if (dropped.length > 0) {
+                    return {
+                        action: "fail",
+                        message: `regenerating pi/toolchain/ from garaje.yaml would drop bay(s) the committed artifact ` +
+                            `was derived from: ${dropped.join(", ")} — refusing to narrow it. This can happen even ` +
+                            "with syntactically valid YAML (e.g. a `bays:` entry missing `name:`), or when a bay is " +
+                            "parked locally but not (yet) declared in garaje.yaml. Sync the missing bay(s) " +
+                            "(`garaje sync`) and re-run upgrade, or fix garaje.yaml; if you really mean to drop " +
+                            "them, run `garaje park` yourself, then re-run upgrade.",
+                    };
+                }
+            }
+            else if (isEmptyToolchain(toolchain) && !isEmptyToolchain(committed)) {
+                // Backstop: the committed artifact predates the `# bays:` provenance
+                // line, so there is nothing to diff against — fall back to the
+                // coarser "would this regeneration go empty" check.
+                return {
+                    action: "fail",
+                    message: `regenerating pi/toolchain/ from garaje.yaml would produce an EMPTY artifact, but the ` +
+                        `committed one is not — refusing to overwrite it. This can happen even with syntactically ` +
+                        "valid YAML (e.g. a `bays:` entry missing `name:`). Check garaje.yaml; if you really want to " +
+                        "shrink to zero bays, run `garaje park` yourself, then re-run upgrade.",
+                };
+            }
+        }
+        return { action: "write", recipes };
+    }
+    if (!committed) {
+        return {
+            action: "fail",
+            message: `pi/toolchain/ is missing and cannot be derived — ${describeUnparkedBays(root, unparked)}. ` +
+                `Re-run upgrade once fixed.`,
+        };
+    }
+    return {
+        action: "leave",
+        message: `${describeUnparkedBays(root, unparked)} — pi/toolchain/ left as committed`,
+    };
+}
 /** `garaje upgrade [--to <version>]` — bump the base + CLI pins and classify. */
 export function runUpgrade(root, args) {
     const settingsPath = join(root, ".pi/settings.json");
@@ -67,23 +268,76 @@ export function runUpgrade(root, args) {
         if (t)
             rmSync(t.replace(/\/package$/, ""), { recursive: true, force: true });
     }
-    // Rewrite the three committed pins.
-    writeFileSync(settingsPath, rewriteBasePin(settingsText, to));
+    // Rewrite the committed pins, then re-materialize the framework-managed files
+    // and merge the framework-default packages. Without the latter two, a
+    // framework change reaches NEW garajes only. Both the rematerialize and the
+    // settings merge are declined in the framework monorepo (base pinned by
+    // relative path, not npm:) — one guard, one meaning: "this is not a
+    // scaffolded garaje, so upgrade does nothing structural to it." The
+    // version-pin rewrites above/below still run in both cases.
+    const scaffolded = isScaffoldedGaraje(root);
+    // Decide the pi/toolchain/ outcome BEFORE any write below runs. A
+    // re-materialized pi/Dockerfile's `COPY toolchain/` step must never be
+    // written on a promise the toolchain regen can't keep — a corrupt recipe or
+    // an undeliverable artifact has to fail upgrade OUTRIGHT, before pins,
+    // pi/Dockerfile, or anything else is touched, so a failed upgrade leaves the
+    // garaje exactly as it was (see planToolchain). Declined for the monorepo,
+    // same guard as rematerialize: pi/Dockerfile there is hand-maintained, not
+    // re-materialized, so upgrade has no reason to touch its sibling artifact.
+    const toolchainPlan = scaffolded ? planToolchain(root) : { action: "skip" };
+    if (toolchainPlan.action === "fail") {
+        process.stderr.write(`garaje upgrade: ${toolchainPlan.message}\n`);
+        return 1;
+    }
+    const rewritten = rewriteBasePin(settingsText, to);
+    const merged = scaffolded ? mergeSettingsPackages(rewritten, DEFAULT_PACKAGES) : rewritten;
+    writeFileSync(settingsPath, merged);
     if (existsSync(dockerfilePath)) {
         writeFileSync(dockerfilePath, rewriteDockerfileCliPin(readFileSync(dockerfilePath, "utf8"), to));
     }
     writeFileSync(versionPath, `${to}\n`);
+    const managed = rematerialize(root, TEMPLATES, to);
+    // Apply the toolchain decision made above. "write" (co-covers both "every
+    // manifest bay synced" and "manifest declares none" — an empty recipe list
+    // yields the valid empty artifact) and "leave" (bay(s) unsynced but the
+    // committed artifact still stands, untouched) are the only two live cases
+    // here; "fail" already returned above, and "skip" is the monorepo no-op.
+    if (toolchainPlan.action === "write") {
+        writeToolchainArtifact(root, toolchainPlan.recipes);
+    }
+    // Scaffold .pi-lens.json if this garaje predates it (create-only — never
+    // clobber a customized one).
+    const piLensCreated = scaffoldPiLensConfig(root, TEMPLATES);
     // Report.
     process.stdout.write(`garaje upgrade: pins bumped ${from ?? "(local)"} -> ${to}\n`);
     for (const f of findings) {
         process.stdout.write(`  ${f.kind.toUpperCase()} [${f.resource}] ${f.name}: ${f.detail}\n`);
     }
+    for (const m of managed) {
+        process.stdout.write(`  managed ${m.file.padEnd(24)}${m.changed ? "rewritten" : "unchanged"}\n`);
+    }
+    if (toolchainPlan.action === "write") {
+        process.stdout.write(`  managed pi/toolchain/           regenerated from ${toolchainPlan.recipes.length} bay recipe(s)\n`);
+    }
+    else if (toolchainPlan.action === "leave") {
+        process.stdout.write(`  managed pi/toolchain/           left as-is (${toolchainPlan.message})\n`);
+    }
+    if (piLensCreated) {
+        process.stdout.write(`  scaffold .pi-lens.json          created (was missing; template defaults)\n`);
+    }
+    const addedPkgs = scaffolded ? missingDefaultPackages(settingsText, DEFAULT_PACKAGES) : [];
+    for (const p of addedPkgs) {
+        process.stdout.write(`  merged  .pi/settings.json      + ${p}\n`);
+    }
     const nextHeader = classified
         ? `  # review the ${findings.length} override(s) above, then:\n`
         : `  # classification was skipped (base trees unavailable) — re-run this after the ` +
             `packages are published to check for shadow/orphan overrides, then:\n`;
-    process.stdout.write(`\nNext:\n${nextHeader}` +
-        `  npm i -g garaje@${to}\n  garaje up --build\n  git add -A && git commit -m 'upgrade garaje to ${to}'\n`);
+    process.stdout.write(`\nNote: this upgrade ran using the CLI you already have installed — install ` +
+        `garaje@${to} globally BEFORE running \`garaje upgrade\`, not after (the ` +
+        `version that performs the upgrade is whatever is already on PATH).\n` +
+        `\nNext:\n${nextHeader}` +
+        `  garaje up --build\n  garaje sync\n  git add -A && git commit -m 'upgrade garaje to ${to}'\n`);
     return findings.length > 0 ? 1 : 0;
 }
 /** Latest published `garaje` version, or undefined (pre-publish / offline). */

package/dist/upgrade/managed.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { basePinSource } from "./pins.js";
+import { driverContext, getDriver } from "../driver/index.js";
+/**
+ * Files the FRAMEWORK owns end-to-end. They are already write-protected from the
+ * agent, and — since the toolchain moved into the generated pi/toolchain/ —
+ * they carry no per-garaje content at all. That is what makes overwriting them
+ * safe, and what lets a framework change reach a garaje that already exists.
+ *
+ * .pi/settings.json is deliberately NOT here: it is garaje-owned (model,
+ * provider, their own packages) and is MERGED instead. See mergeSettingsPackages.
+ *
+ * The compose file(s) are NOT hardcoded here: compose filenames are
+ * driver-internal knowledge (north-star §4.1 — the runtime-driver seam is the
+ * only dialect layers above codegen may speak). We ask the driver for its own
+ * frameworkOwnedFiles() instead — NOT requiredFiles(), which only promises a
+ * file must exist (doctor), not that it is safe to overwrite — so a future
+ * k8s driver (Phase 8) gets its own framework-owned manifests re-materialized
+ * for free, without also clobbering a manifest a dev is meant to customize,
+ * and no compose literal leaks above the seam.
+ */
+export function managedFiles(root) {
+    const driver = getDriver(driverContext(root));
+    return ["pi/Dockerfile", "pi/entrypoint.sh", ...driver.frameworkOwnedFiles()];
+}
+/** pi packages every garaje should have. Merged into .pi/settings.json, never
+ *  imposed over the garaje's own choices. */
+export const DEFAULT_PACKAGES = ["npm:pi-lens"];
+/** A package spec without its version: npm:pi-lens@1.2.3 -> npm:pi-lens. The
+ *  leading @ of a scoped name (npm:@garaje/base) is not a version separator —
+ *  only an @ after the last / (i.e. after the scope) can introduce a version. */
+export function packageName(spec) {
+    const at = spec.lastIndexOf("@");
+    const boundary = Math.max(spec.indexOf(":"), spec.lastIndexOf("/"));
+    return at > boundary ? spec.slice(0, at) : spec;
+}
+/** Names already present in settingsText's package list (by packageName, not
+ *  exact spec — a default already pinned to a version still counts). */
+function presentPackageNames(settingsText) {
+    const data = JSON.parse(settingsText);
+    const packages = Array.isArray(data.packages) ? data.packages : [];
+    return new Set(packages
+        .map((p) => (typeof p === "string" ? p : p?.source))
+        .filter((s) => typeof s === "string")
+        .map(packageName));
+}
+/** Which of `defaults` are absent from settingsText, matched by package name
+ *  the same way mergeSettingsPackages decides what to add — so a stdout
+ *  report of "what got added" can never disagree with what actually did. */
+export function missingDefaultPackages(settingsText, defaults) {
+    const present = presentPackageNames(settingsText);
+    return defaults.filter((def) => !present.has(packageName(def)));
+}
+/** Add any missing framework-default packages. The garaje's model, provider,
+ *  theme and own packages are untouched, and a default it already pinned to a
+ *  version is left at that version. */
+export function mergeSettingsPackages(settingsText, defaults) {
+    const data = JSON.parse(settingsText);
+    const packages = Array.isArray(data.packages) ? [...data.packages] : [];
+    for (const def of missingDefaultPackages(settingsText, defaults)) {
+        packages.push(def);
+    }
+    data.packages = packages;
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+/** True for a scaffolded garaje (base pinned from npm), false for the framework
+ *  monorepo (base pinned by relative path), whose root pi/Dockerfile legitimately
+ *  differs from the template and must never be clobbered. Also gates the
+ *  .pi/settings.json package merge: the monorepo's own settings.json must not
+ *  be touched either. */
+export function isScaffoldedGaraje(root) {
+    const settings = join(root, ".pi", "settings.json");
+    if (!existsSync(settings))
+        return false;
+    const source = basePinSource(readFileSync(settings, "utf8"));
+    return Boolean(source?.startsWith("npm:"));
+}
+/** Scaffold `.pi-lens.json` from the template if it is missing. It is
+ *  garaje-owned once it exists (a garaje may have customized its ignore
+ *  list), so this only ever CREATES — never overwrites. Declined for the
+ *  monorepo, same guard as rematerialize/mergeSettingsPackages: this repo is
+ *  not a scaffolded garaje. Returns true iff the file was created. */
+export function scaffoldPiLensConfig(root, templatesDir) {
+    if (!isScaffoldedGaraje(root))
+        return false;
+    const dest = join(root, ".pi-lens.json");
+    if (existsSync(dest))
+        return false;
+    const template = join(templatesDir, ".pi-lens.json");
+    if (!existsSync(template))
+        return false;
+    writeFileSync(dest, readFileSync(template, "utf8"));
+    return true;
+}
+/** Rewrite every framework-managed file from the CLI's bundled templates.
+ *  Returns one outcome per file; an empty array means we declined (monorepo). */
+export function rematerialize(root, templatesDir, version) {
+    if (!isScaffoldedGaraje(root))
+        return [];
+    const out = [];
+    for (const rel of managedFiles(root)) {
+        const templatePath = join(templatesDir, rel);
+        if (!existsSync(templatePath))
+            continue;
+        const want = readFileSync(templatePath, "utf8").split("__GARAJE_VERSION__").join(version);
+        const dest = join(root, rel);
+        const have = existsSync(dest) ? readFileSync(dest, "utf8") : undefined;
+        if (have === want) {
+            out.push({ file: rel, changed: false });
+            continue;
+        }
+        writeFileSync(dest, want);
+        out.push({ file: rel, changed: true });
+    }
+    return out;
+}

package/dist/upgrade/pins.js

@@ -12,7 +12,9 @@ export function currentBaseVersion(settingsText) {
     return m ? m[1] : undefined;
 }
 /** The @garaje/base package source pinned in .pi/settings.json: an `npm:` spec
- *  in a scaffolded garaje, a relative path in the framework monorepo. */
+ *  in a scaffolded garaje, a relative path in the framework monorepo. Returns
+ *  undefined if no package matches — the caller must treat that as "not
+ *  pinned", not fall back to an unrelated package. */
 export function basePinSource(settingsText) {
     let sources;
     try {
@@ -24,5 +26,5 @@ export function basePinSource(settingsText) {
     catch {
         return undefined;
     }
-    return sources.find((s) => /@garaje\/base|packages\/base/.test(s)) ?? sources[0];
+    return sources.find((s) => /@garaje\/base|packages\/base/.test(s));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "garaje",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/.pi/settings.json

@@ -9,6 +9,7 @@
       "source": "__BASE_PIN__",
       "extensions": ["extensions/**", "!extensions/session-name.ts"]
     },
-    "npm:pi-mixlayer@0.4.0"
+    "npm:pi-mixlayer@0.4.0",
+    "npm:pi-lens"
   ]
 }

package/templates/.pi-lens.json

@@ -0,0 +1,11 @@
+{
+  "ignore": [
+    "sessions/**",
+    "scratch/**",
+    ".pi/**",
+    "bays/*/node_modules/**",
+    "bays/*/tmp/**",
+    "bays/*/log/**",
+    "bays/*/vendor/**"
+  ]
+}

package/templates/compose.framework.yaml

@@ -14,6 +14,11 @@ services:
       - ./:/workspace
       - pi-config:/root/.pi/agent
       - garaje-auth:/root/.garaje-auth
+      # pi-side project dependencies (gems, node_modules) for the parked bays,
+      # installed by `garaje sync`. Names NO bay on purpose: the framework layer
+      # stays codebase-agnostic, so the framework/bays compose split that carries
+      # containment (bays scope excludes this file entirely) is untouched.
+      - pi-deps:/garaje/deps
     # Provider credentials come from .env — a garaje's single credential surface.
     # Any pi provider extension (pi-mixlayer, pi-openai, …) resolves its key from
     # the container environment, so adding a provider needs no framework release.
@@ -72,3 +77,4 @@ services:
 volumes:
   pi-config:
   garaje-auth:
+  pi-deps: