garaje 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,110 @@
+# garaje
+
+**Park your codebases. Let the agent drive.**
+
+`garaje` is a command-line tool for running the [pi](https://pi.dev) coding
+agent against the codebases you actually work on — each one containerized with
+its own datastores, alongside the agent, in a single Docker Compose project
+called a **garaje**. You scaffold a garaje, hand it your repos, and the
+in-container agent wires each one up for agentic development.
+
+The design goal is **portability**: your dev environment is declared as data
+(a manifest + per-codebase recipes), the agent harness is a swappable package,
+and the same garaje runs locally on Docker today (Kubernetes is on the roadmap).
+
+```bash
+npm install -g garaje
+```
+
+> Requires **Docker** (Desktop or Engine) on the host. The agent and its tools
+> run in containers; `garaje` itself is a thin, dependency-light wrapper over
+> `docker compose`.
+
+---
+
+## Quick start
+
+```bash
+# 1. Scaffold a new garaje (a git repo that hosts your parked codebases)
+garaje init my-workspace
+cd my-workspace
+
+# 2. Start it — builds the agent container and brings the project up
+garaje up --build
+
+# 3. Drop into the agent
+garaje pi
+```
+
+Then, from inside the agent, point it at a codebase and ask it to **park** it —
+the agent introspects the repo, writes a `recipe.yaml` describing how it runs
+(toolchain, processes, datastores, env), generates the container config, and
+commits it. From then on that codebase is a first-class, live-reloading,
+agent-assisted dev target in your garaje.
+
+Stop without losing your work or your credentials:
+
+```bash
+garaje down        # refuses -v, so the agent's auth + provisioned tokens survive
+garaje up
+garaje pi -c       # continue your most recent session
+```
+
+## Concepts
+
+| Term | What it is |
+|------|-----------|
+| **garaje** | A git repo + Docker Compose project that runs the pi agent next to the codebases it works on. One per developer, or one shared per team. |
+| **bay** | A parked codebase inside a garaje (`bays/<name>`), materialized from the manifest. The garaje commits the *manifest*, not the code. |
+| **`recipe.yaml`** | A platform-neutral description of how one codebase runs — its toolchain, app processes, backing services, env, and secrets. Lives in the codebase; the agent authors it by introspection. |
+| **[`@garaje/base`](https://www.npmjs.com/package/@garaje/base)** | The agent-side substrate — the persona, rules, roles, and skills the in-container agent loads. Pinned declaratively in `.pi/settings.json`; installed automatically in-container. |
+
+## Commands
+
+```
+garaje init <name> [dir]    scaffold a new garaje
+garaje up [--build]         build + start the garaje (host-only)
+garaje down                 stop it (refuses -v; auth/tokens persist)
+garaje pi [-c]              open the pi agent TUI (-c continues the last session)
+garaje attach               attach to the running agent
+garaje logs                 tail container logs
+garaje doctor               health-check the garaje
+garaje sync [name]          clone the manifest's codebases into bays/
+garaje list                 list parked bays
+garaje park [name]          regenerate the compose from the bays' recipes
+garaje bay <up|down|logs|ps>  operate a parked bay's services
+garaje auth <add|list|remove> provision git / gh / integration credentials
+garaje upgrade [--to <v>]   bump the framework + base pins, flag override drift
+garaje sessions-index       index the agent's session transcripts
+```
+
+## How it works
+
+- **Compose split by ownership.** A thin top-level `docker-compose.yml` includes
+  the framework layer (the agent container); parked codebases live in a
+  generated `compose.bays.yaml`. The agent shapes services by editing recipes,
+  never the compose files it can't reconfigure itself.
+- **Bind-mounted, live-reloading.** The repo is mounted into the containers, so
+  edits the agent makes take effect immediately — no image rebuilds for code
+  changes.
+- **Least-privilege Docker.** The agent reaches Docker only through a
+  default-deny socket proxy, never the raw socket.
+- **Layered, declarative config.** The shared `@garaje/base` package is pinned
+  and consumed read-only; a garaje customizes by layering local overrides on
+  top — so upgrading the framework is a pin bump, not a merge.
+
+## Framework & harness portability
+
+garaje separates the *dev environment* (yours, committed as data) from the
+*agent harness* (a package). Today the harness is pi via `@garaje/base`; the
+seam is deliberately thin so a different harness is a different base package,
+not a rewrite. The runtime is Docker Compose locally, with a Kubernetes driver
+planned for the cloud — the same recipe, two runtimes.
+
+`garaje` and `@garaje/base` are released in lockstep. Upgrade a garaje with
+`garaje upgrade`, which bumps the pins and flags any local override that now
+shadows or orphans a changed base resource.
+
+## License
+
+MIT

package/dist/cli.js

@@ -9,7 +9,7 @@ import { runLogs } from "./host/logs.js";
 import { runPi } from "./host/pi.js";
 import { runAttach } from "./host/attach.js";
 import { runDoctor } from "./host/doctor.js";
-import { runSyncList } from "./host/sync.js";
+import { runList, runSync } from "./host/sync.js";
 import { runAuth } from "./host/auth.js";
 import { runSessionsIndex } from "./sessions/run.js";
 import { inContainer } from "./driver/index.js";
@@ -47,9 +47,9 @@ export function main(argv) {
         case "doctor":
             return runDoctor(root);
         case "sync":
-            return runSyncList(root, "sync", rest);
+            return runSync(root, rest);
         case "list":
-            return runSyncList(root, "list", rest);
+            return runList(root);
         case "park":
             return runPark(root, rest).code;
         case "sessions-index":

package/dist/host/doctor.js

@@ -1,8 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
+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 { basePinSource } from "../upgrade/pins.js";
+import { bayStatuses, statusLine } from "./sync.js";
 /** `garaje doctor` — host-side sanity checks. Exit code = failed-check count. */
 export function runDoctor(root) {
     let fails = 0;
@@ -33,7 +35,6 @@ export function runDoctor(root) {
         "garaje.yaml",
         "pi/Dockerfile",
         "pi/entrypoint.sh",
-        "packages/base/package.json",
         ".pi/settings.json",
     ]) {
         if (existsSync(join(root, f)))
@@ -41,6 +42,23 @@ export function runDoctor(root) {
         else
             fail(`${f} missing`);
     }
+    // The base package is an npm pin in a scaffolded garaje and a relative path
+    // in the framework monorepo. Only the path form has anything on disk to check.
+    const settings = join(root, ".pi", "settings.json");
+    const source = existsSync(settings)
+        ? basePinSource(readFileSync(settings, "utf8"))
+        : undefined;
+    if (!source)
+        fail("@garaje/base is not pinned in .pi/settings.json");
+    else if (source.startsWith("npm:"))
+        pass(`@garaje/base pinned: ${source}`);
+    else {
+        const dir = resolve(join(root, ".pi"), source);
+        if (existsSync(join(dir, "package.json")))
+            pass(`@garaje/base pinned: ${source}`);
+        else
+            fail(`@garaje/base path pin "${source}" missing — no package.json at ${dir}`);
+    }
     if (existsSync(join(root, ".env")))
         pass(".env present");
     else
@@ -57,14 +75,24 @@ export function runDoctor(root) {
         pass("pi service running");
     else
         fail("pi service NOT running (try garaje up)");
-    // --- bays (delegate to the retained bash list) ---
+    // --- bays ---
     section("bays");
-    const list = spawnSync("bash", [join(root, "bin", "garaje-sync"), "list"], { encoding: "utf8" });
-    const bayLines = (list.stdout ?? "").split(/\r?\n/).slice(1).filter((l) => l.trim());
-    if (bayLines.length)
-        bayLines.forEach((l) => pass(l));
-    else
-        warn("no bays parked (add one to garaje.yaml, then garaje sync)");
+    // readManifest throws on a missing/corrupt garaje.yaml; doctor reports that
+    // as a failed check rather than crashing (same contract as the artifact check).
+    try {
+        const bays = bayStatuses(root);
+        if (!bays.length)
+            warn("no bays parked (add one to garaje.yaml, then garaje sync)");
+        for (const b of bays) {
+            if (b.synced)
+                pass(`${b.name}: ${statusLine(b)} (${b.ref})`);
+            else
+                warn(`${b.name}: ${statusLine(b)} — run \`garaje sync ${b.name}\``);
+        }
+    }
+    catch (e) {
+        fail(`bay status check errored — garaje.yaml failed to parse: ${e.message}`);
+    }
     const unhealthy = driver.psText()
         .split(/\r?\n/)
         .filter((l) => /unhealthy/i.test(l));
@@ -77,7 +105,7 @@ export function runDoctor(root) {
         if (artifact === "fresh")
             pass("bays artifact matches the recipes (regenerate-and-diff)");
         else if (artifact === "no-bays")
-            warn("no synced bays — artifact staleness not checkable");
+            warn("no parked bays (no recipe.yaml) — artifact staleness not checkable");
         else if (artifact === "missing")
             fail("bays artifact missing — run `garaje park` and commit the result");
         else
@@ -86,9 +114,12 @@ export function runDoctor(root) {
     catch (e) {
         fail(`bays artifact check errored — a recipe failed to parse: ${e.message}`);
     }
-    const unsynced = manifestBays(root).filter((b) => !discoverBays(root).includes(b));
-    if (unsynced.length) {
-        warn(`manifest bay(s) not synced: ${unsynced.join(", ")} — the artifact excludes them (run garaje sync)`);
+    // "Parked" (has a recipe.yaml) is a stricter state than "synced" (cloned);
+    // only parked bays contribute to the artifact.
+    const parked = discoverBays(root);
+    const unparked = manifestBays(root).filter((b) => !parked.includes(b));
+    if (unparked.length) {
+        warn(`manifest bay(s) with no recipe.yaml: ${unparked.join(", ")} — the artifact excludes them`);
     }
     // --- pi container ---
     section("pi");

package/dist/host/sync.js

@@ -1,7 +1,88 @@
 import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-/** `garaje sync` / `garaje list` — delegate to the retained bash helper. */
-export function runSyncList(root, sub, extra) {
-    const helper = join(root, "bin", "garaje-sync");
-    return spawnSync("bash", [helper, sub, ...extra], { cwd: root, stdio: "inherit" }).status ?? 1;
+import { readManifest } from "../manifest.js";
+function git(args) {
+    return spawnSync("git", args, { stdio: "inherit" }).status ?? 1;
+}
+/** Cross the manifest with what is actually checked out under bays/. */
+export function bayStatuses(root) {
+    return readManifest(root).map((bay) => {
+        const dest = join(root, "bays", bay.name);
+        if (!existsSync(join(dest, ".git")))
+            return { ...bay, synced: false };
+        const rev = spawnSync("git", ["-C", dest, "rev-parse", "--short", "HEAD"], {
+            encoding: "utf8",
+        });
+        return { ...bay, synced: true, head: rev.status === 0 ? rev.stdout.trim() : "?" };
+    });
+}
+/** One human-readable line per bay. Pure — doctor reuses this. */
+export function statusLine(b) {
+    return b.synced ? `synced @ ${b.head}` : "not synced";
+}
+/** The `garaje list` table. Pure. */
+export function renderList(rows) {
+    const w = (header, pick) => Math.max(header.length, ...rows.map((b) => pick(b).length || 1));
+    const repo = (b) => b.repo || "-";
+    const wName = w("BAY", (b) => b.name);
+    const wRepo = w("REPO", repo);
+    const wRef = w("REF", (b) => b.ref);
+    const line = (a, b, c, d) => `${a.padEnd(wName)}  ${b.padEnd(wRepo)}  ${c.padEnd(wRef)}  ${d}\n`;
+    return (line("BAY", "REPO", "REF", "STATUS") +
+        rows.map((b) => line(b.name, repo(b), b.ref, statusLine(b))).join(""));
+}
+/** `garaje list` — show the manifest and which bays are materialized. */
+export function runList(root) {
+    process.stdout.write(renderList(bayStatuses(root)));
+    return 0;
+}
+/** `garaje sync [name...]` — clone/update the manifest's bays into bays/. */
+export function runSync(root, names) {
+    if (spawnSync("git", ["--version"], { stdio: "ignore" }).status !== 0) {
+        process.stderr.write("error: git not found in PATH\n");
+        return 1;
+    }
+    const entries = readManifest(root);
+    const unknown = names.filter((n) => !entries.some((b) => b.name === n));
+    if (unknown.length) {
+        process.stderr.write(`error: not in garaje.yaml: ${unknown.join(", ")} (declare the bay in the manifest first)\n`);
+        return 1;
+    }
+    const wanted = names.length ? entries.filter((b) => names.includes(b.name)) : entries;
+    mkdirSync(join(root, "bays"), { recursive: true });
+    let synced = 0;
+    for (const bay of wanted) {
+        if (!bay.repo) {
+            process.stderr.write(`skip ${bay.name}: no repo in manifest\n`);
+            continue;
+        }
+        const dest = join(root, "bays", bay.name);
+        if (existsSync(join(dest, ".git"))) {
+            process.stdout.write(`==> ${bay.name}: fetching (${bay.ref})\n`);
+            if (git(["-C", dest, "fetch", "--quiet", "origin", bay.ref]) !== 0 ||
+                git(["-C", dest, "checkout", "--quiet", bay.ref]) !== 0) {
+                process.stderr.write(`error: ${bay.name}: fetch/checkout of ${bay.ref} failed\n`);
+                return 1;
+            }
+            // Fast-forward only when ref names a branch. A tag or sha leaves HEAD
+            // detached, and there is nothing to advance — that is not a failure.
+            const onBranch = spawnSync("git", ["-C", dest, "symbolic-ref", "-q", "HEAD"], { stdio: "ignore" })
+                .status === 0;
+            if (onBranch && git(["-C", dest, "merge", "--quiet", "--ff-only", "FETCH_HEAD"]) !== 0) {
+                process.stderr.write(`error: ${bay.name}: ${bay.ref} is not fast-forwardable\n`);
+                return 1;
+            }
+        }
+        else {
+            process.stdout.write(`==> ${bay.name}: cloning ${bay.repo} (${bay.ref})\n`);
+            if (git(["clone", "--quiet", "--branch", bay.ref, bay.repo, dest]) !== 0) {
+                process.stderr.write(`error: ${bay.name}: clone failed\n`);
+                return 1;
+            }
+        }
+        synced += 1;
+    }
+    process.stdout.write(`synced ${synced} bay(s) into bays/\n`);
+    return 0;
 }

package/dist/manifest.js

@@ -0,0 +1,24 @@
+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) {
+    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);
+}
+/** Read <root>/garaje.yaml. Throws if it is missing or unparseable. */
+export function readManifest(root) {
+    const path = join(root, "garaje.yaml");
+    if (!existsSync(path))
+        throw new Error("no garaje.yaml at the garaje root");
+    return parseManifest(readFileSync(path, "utf8"));
+}

package/dist/park/index.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { parse as parseYaml } from "yaml";
+import { readManifest } from "../manifest.js";
 import { parseRecipe } from "./recipe.js";
 import { generate } from "./compose.js";
 /** Bay folder names under <root>/bays that contain a recipe.yaml, sorted. */
@@ -13,16 +13,12 @@ export function discoverBays(root) {
         .map((e) => e.name)
         .sort();
 }
-/** Bay names declared in the committed manifest (garaje.yaml). */
+/** 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. */
 export function manifestBays(root) {
-    const path = join(root, "garaje.yaml");
-    if (!existsSync(path))
-        return [];
     try {
-        const data = parseYaml(readFileSync(path, "utf8"));
-        return (data?.bays ?? [])
-            .map((b) => b?.name)
-            .filter((n) => Boolean(n));
+        return readManifest(root).map((b) => b.name);
     }
     catch {
         return [];

package/dist/upgrade/pins.js

@@ -11,3 +11,18 @@ export function currentBaseVersion(settingsText) {
     const m = settingsText.match(/npm:@garaje\/base@([0-9A-Za-z.\-]+)/);
     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. */
+export function basePinSource(settingsText) {
+    let sources;
+    try {
+        const data = JSON.parse(settingsText);
+        sources = (data.packages ?? [])
+            .map((p) => p?.source)
+            .filter((s) => Boolean(s));
+    }
+    catch {
+        return undefined;
+    }
+    return sources.find((s) => /@garaje\/base|packages\/base/.test(s)) ?? sources[0];
+}

package/package.json

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