garaje 0.1.0 → 0.1.2

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/package.json

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

package/dist/host/compose.js

@@ -1,65 +0,0 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-/**
- * The argv to pass after `docker compose`. Mirrors bin/_lib.sh `compose`:
- * always `-f docker-compose.yml`, layer `-f compose.bays.yaml` when present,
- * and prepend `-p <name>` when the garaje declares one.
- */
-export function composeArgs(ctx, extra) {
-    const files = ["-f", "docker-compose.yml"];
-    if (ctx.hasBaysCompose)
-        files.push("-f", "compose.bays.yaml");
-    const project = ctx.name ? ["-p", ctx.name] : [];
-    return [...project, ...files, ...extra];
-}
-/** The committed compose project name — the first top-level `name:` line. */
-export function readProjectName(root) {
-    const path = join(root, "garaje.yaml");
-    if (!existsSync(path))
-        return undefined;
-    for (const line of readFileSync(path, "utf8").split(/\r?\n/)) {
-        const m = /^name:\s*(.+?)\s*$/.exec(line);
-        if (m)
-            return m[1].replace(/^["']|["']$/g, "");
-    }
-    return undefined;
-}
-export function composeContext(root) {
-    return {
-        name: readProjectName(root),
-        hasBaysCompose: existsSync(join(root, "compose.bays.yaml")),
-    };
-}
-/** Run `docker compose` from the repo root, inheriting stdio; returns exit code. */
-export function compose(root, extra) {
-    const args = composeArgs(composeContext(root), extra);
-    return spawnSync("docker", ["compose", ...args], { cwd: root, stdio: "inherit" }).status ?? 1;
-}
-/** Run `docker compose` and capture stdout/stderr instead of inheriting. */
-export function composeCapture(root, extra) {
-    const args = composeArgs(composeContext(root), extra);
-    const r = spawnSync("docker", ["compose", ...args], { cwd: root, encoding: "utf8" });
-    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
-}
-/** Like composeCapture, but feeds `input` to the process's stdin. */
-export function composeCaptureInput(root, extra, input) {
-    const args = composeArgs(composeContext(root), extra);
-    const r = spawnSync("docker", ["compose", ...args], { cwd: root, encoding: "utf8", input });
-    return { status: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
-}
-/**
- * Start the stack if the `pi` service isn't already running. Returns 0 when pi
- * is (or becomes) running, else the non-zero `up -d` exit code so callers can
- * bail cleanly instead of exec-ing against a stack that failed to start. The
- * running-check is inlined (rather than importing pi.ts's parseRunningServices)
- * to avoid a compose ↔ pi import cycle — pi.ts already imports from compose.ts.
- */
-export function ensurePiRunning(root) {
-    const ps = composeCapture(root, ["ps", "--status", "running", "--services"]);
-    const running = ps.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-    if (running.includes("pi"))
-        return 0;
-    process.stderr.write("(pi container not running; starting the stack)\n");
-    return compose(root, ["up", "-d"]);
-}