Decouple gondolin runtime assets and refresh setup docs

Author: vmg-dev

.github/workflows/ci.yml

@@ -82,6 +82,9 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y qemu-system-x86 e2fsprogs
 
+      - name: Prime Gondolin guest assets
+        run: bunx gondolin exec -- /bin/true
+
       - name: Run integration tests
         env:
           INTEGRATION_PLATFORM: linux/amd64
@@ -113,6 +116,9 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y qemu-system-x86 e2fsprogs
 
+      - name: Prime Gondolin guest assets
+        run: bunx gondolin exec -- /bin/true
+
       - name: Run end-to-end smoke test
         env:
           PLATFORM: linux/amd64

README.md

@@ -2,7 +2,7 @@
 
 `docker2vm` converts OCI container images (or Dockerfiles via BuildKit) into VM-compatible outputs. Today, the runtime materialization target is [Gondolin](https://github.com/earendil-works/gondolin).
 
-It follows an OCI-first flow inspired by "Docker without Docker":
+It follows an OCI-first flow inspired by ["Docker without Docker"](https://fly.io/blog/docker-without-docker/):
 
 - resolve/pull an OCI image
 - apply layers to a root filesystem
@@ -16,6 +16,7 @@ Docker containers share the host kernel. Gondolin runs workloads inside a VM, so
 
 ## Current features
 
+- zero runtime npm dependencies (`dependencies: {}`)
 - `oci2gondolin` core converter
   - input: `--image`, `--oci-layout`, `--oci-tar` (exactly one)
   - platform: `linux/amd64`, `linux/arm64`
@@ -39,6 +40,7 @@ Docker containers share the host kernel. Gondolin runs workloads inside a VM, so
 - Bun >= 1.2
 - `e2fsprogs` (`mke2fs`, `debugfs`)
 - QEMU (for runtime smoke checks via `gondolin exec`)
+- Gondolin CLI installed separately (tested with `@earendil-works/gondolin@0.2.1`)
 - Docker (only required for `dockerfile2gondolin`)
 
 macOS helpers:
@@ -53,17 +55,25 @@ Ubuntu helpers:
 sudo apt-get install -y e2fsprogs qemu-system-x86
 ```
 
-## Platform setup guides
+Install Gondolin CLI (tested version):
 
-- [macOS guide](./docs/macos.md)
-- [Linux guide](./docs/linux.md)
+```bash
+bun add -g @earendil-works/gondolin@0.2.1
+```
 
-## Install
+Prime guest assets once:
 
 ```bash
-bun install
+gondolin exec -- /bin/true
 ```
 
+> On macOS, `docker2vm` checks common Homebrew `e2fsprogs` locations automatically; updating `PATH` is usually optional.
+
+## Platform setup guides
+
+- [macOS guide](./docs/macos.md)
+- [Linux guide](./docs/linux.md)
+
 ## Quickstart
 
 ### 1) Validate
@@ -92,11 +102,12 @@ For each distro row, tests run a distro-specific probe command (for example `/et
 
 ### Choosing the build platform (`--platform`)
 
-`--platform` selects which OCI image variant to convert, and should match the architecture you plan to run in Gondolin.
+`--platform` selects which OCI image variant to convert, and should match the architecture you plan to run in Gondolin. This applies to both `oci2gondolin` and `dockerfile2gondolin`.
 
 - Apple Silicon / arm64 Linux hosts: `linux/arm64`
 - Intel / amd64 hosts: `linux/amd64`
-- If omitted, `oci2gondolin` defaults from host arch (`x64 -> linux/amd64`, `arm64 -> linux/arm64`).
+- If omitted, both commands default from host arch (`x64 -> linux/amd64`, `arm64 -> linux/arm64`).
+- You can always override manually with `--platform linux/amd64` or `--platform linux/arm64`.
 
 For helper scripts:
 
@@ -118,7 +129,7 @@ bun run oci2gondolin -- \
 ### 3) Run with Gondolin
 
 ```bash
-GONDOLIN_GUEST_DIR=./out/busybox-assets bunx gondolin exec -- /bin/busybox echo hello
+GONDOLIN_GUEST_DIR=./out/busybox-assets gondolin exec -- /bin/busybox echo hello
 ```
 
 ## Dockerfile flow
@@ -143,7 +154,7 @@ bun run dockerfile2gondolin -- \
 Then run:
 
 ```bash
-GONDOLIN_GUEST_DIR=./out/demo-assets bunx gondolin exec -- /usr/games/cowsay "hello"
+GONDOLIN_GUEST_DIR=./out/demo-assets gondolin exec -- /usr/games/cowsay "hello"
 ```
 
 ## End-to-end smoke test

bun.lock

@@ -2,6 +2,8 @@
 
 This guide is for running `docker2vm` on Linux hosts.
 
+`docker2vm` itself has **0 runtime npm dependencies**; system/runtime tools are installed separately.
+
 ## 1) Install required tools
 
 ### Ubuntu / Debian
@@ -15,30 +17,49 @@ Install Bun:
 
 ```bash
 curl -fsSL https://bun.sh/install | bash
-source ~/.bashrc
+export BUN_INSTALL="$HOME/.bun"
+export PATH="$BUN_INSTALL/bin:$PATH"
 ```
 
 If you want Dockerfile conversion (`dockerfile2gondolin`), install Docker and Buildx.
 
-## 2) Verify toolchain
+## 2) Install Gondolin CLI separately (tested version)
+
+`docker2vm` is tested with:
+
+- `@earendil-works/gondolin@0.2.1`
+
+Install (global):
+
+```bash
+bun add -g @earendil-works/gondolin@0.2.1
+```
+
+Prime guest assets once:
+
+```bash
+gondolin exec -- /bin/true
+```
+
+## 3) Verify toolchain
 
 ```bash
 bun --version
 qemu-system-x86_64 --version
 mke2fs -V
 debugfs -V
+gondolin --help >/dev/null
 ```
 
-## 3) Install dependencies and validate
+## 4) Validate from source checkout
 
 ```bash
-bun install
 bun run test
 bun run typecheck
 bun run build
 ```
 
-## 4) Choose the build platform
+## 5) Choose the build platform
 
 Use a platform that matches the architecture you will run in Gondolin.
 
@@ -57,7 +78,7 @@ bun run oci2gondolin -- \
   --out ./out/busybox-assets
 ```
 
-## 5) Run integration + smoke checks
+## 6) Run integration + smoke checks
 
 amd64 host:
 

docs/linux.md

@@ -2,6 +2,8 @@
 
 This guide is for running `docker2vm` on macOS (Apple Silicon or Intel).
 
+`docker2vm` itself has **0 runtime npm dependencies**; system/runtime tools are installed separately.
+
 ## 1) Install required tools
 
 ```bash
@@ -10,43 +12,55 @@ brew install bun qemu e2fsprogs
 
 If you want Dockerfile conversion (`dockerfile2gondolin`), also install Docker Desktop.
 
-## 2) Ensure `mke2fs` and `debugfs` are on `PATH`
+## 2) Optional: add `e2fsprogs` binaries to `PATH`
+
+With Homebrew, `e2fsprogs` is often keg-only. `docker2vm` checks common Homebrew locations automatically, so a PATH change is usually **not required** for normal usage.
+
+If you want to run `mke2fs` / `debugfs` manually in your shell:
+
+```bash
+export PATH="$(brew --prefix e2fsprogs)/sbin:$PATH"
+```
+
+To persist it, add that `export PATH=...` line to your shell profile (`~/.zshrc`, `~/.bashrc`, `~/.profile`, etc.).
+
+## 3) Install Gondolin CLI separately (tested version)
+
+`docker2vm` is tested with:
 
-`e2fsprogs` is often keg-only on macOS.
+- `@earendil-works/gondolin@0.2.1`
 
-### Apple Silicon (`/opt/homebrew`)
+Install (global):
 
 ```bash
-echo 'export PATH="/opt/homebrew/opt/e2fsprogs/sbin:$PATH"' >> ~/.zshrc
-source ~/.zshrc
+bun add -g @earendil-works/gondolin@0.2.1
 ```
 
-### Intel (`/usr/local`)
+Prime guest assets once:
 
 ```bash
-echo 'export PATH="/usr/local/opt/e2fsprogs/sbin:$PATH"' >> ~/.zshrc
-source ~/.zshrc
+gondolin exec -- /bin/true
 ```
 
-## 3) Verify toolchain
+## 4) Verify toolchain
 
 ```bash
 bun --version
 qemu-system-aarch64 --version || qemu-system-x86_64 --version
-mke2fs -V
-debugfs -V
+"$(brew --prefix e2fsprogs)/sbin/mke2fs" -V
+"$(brew --prefix e2fsprogs)/sbin/debugfs" -V
+gondolin --help >/dev/null
 ```
 
-## 4) Install dependencies and validate
+## 5) Validate from source checkout
 
 ```bash
-bun install
 bun run test
 bun run typecheck
 bun run build
 ```
 
-## 5) Choose the build platform
+## 6) Choose the build platform
 
 Use a platform that matches the architecture you will run in Gondolin.
 
@@ -65,7 +79,7 @@ bun run oci2gondolin -- \
   --out ./out/busybox-assets
 ```
 
-## 6) Run integration + smoke checks
+## 7) Run integration + smoke checks
 
 Apple Silicon:
 
@@ -85,7 +99,7 @@ PLATFORM=linux/amd64 bun run e2e:smoke
 
 ### `mke2fs` / `debugfs` not found
 
-Confirm PATH includes the `e2fsprogs` `sbin` directory shown above.
+`docker2vm` should find common Homebrew locations automatically. If your install uses a custom prefix, either add it to `PATH` or point `GONDOLIN_GUEST_DIR` to prepared assets and verify `e2fsprogs` binaries are installed.
 
 ### Case-sensitive filename conflicts during conversion
 

docs/macos.md

@@ -19,14 +19,13 @@
     "dockerfile2gondolin": "bun run src/bin/dockerfile2gondolin.ts"
   },
   "devDependencies": {
+    "@earendil-works/gondolin": "0.2.1",
     "@types/node": "^22.13.10",
     "typescript": "^5.7.3"
   },
   "engines": {
     "bun": ">=1.2.0"
   },
   "packageManager": "bun@1.3.6",
-  "dependencies": {
-    "@earendil-works/gondolin": "^0.2.1"
-  }
+  "dependencies": {}
 }

package.json

@@ -1,10 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { ensureGuestAssets } from "@earendil-works/gondolin";
-
 import type { AppliedRootfs, MaterializedOutput, Oci2GondolinOptions } from "../types";
 import { sha256File } from "../utils/digest";
+import { resolveGondolinGuestAssets } from "../../shared/gondolin-assets";
 import { ensureDirectory } from "../utils/fs";
 import { createExt4FromDirectory } from "./ext4";
 import { injectGondolinRuntime } from "./runtime-injection";
@@ -51,7 +50,7 @@ export async function materializeOutput(
   let assetManifestPath: string | undefined;
 
   if (options.mode === "assets") {
-    const baseAssets = await ensureGuestAssets();
+    const baseAssets = resolveGondolinGuestAssets();
     const kernelPath = path.join(outDir, KERNEL_FILENAME);
     const initramfsPath = path.join(outDir, INITRAMFS_FILENAME);
 

src/oci2gondolin/materialize/index.ts

@@ -2,9 +2,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-import { ensureGuestAssets } from "@earendil-works/gondolin";
-
 import { CliUsageError } from "../../shared/cli-errors";
+import { resolveGondolinGuestAssets } from "../../shared/gondolin-assets";
 
 type RuntimeFileSpec = {
   sourcePathInRootfs: string;
@@ -89,7 +88,7 @@ export interface RuntimeInjectionResult {
 }
 
 export async function extractBaseRootfsTree(destinationDir: string): Promise<string> {
-  const guestAssets = await ensureGuestAssets();
+  const guestAssets = resolveGondolinGuestAssets();
   const baseRootfsPath = guestAssets.rootfsPath;
 
   if (!fs.existsSync(baseRootfsPath)) {
@@ -119,7 +118,7 @@ export async function extractBaseRootfsTree(destinationDir: string): Promise<str
 }
 
 export async function injectGondolinRuntime(rootfsDir: string): Promise<RuntimeInjectionResult> {
-  const guestAssets = await ensureGuestAssets();
+  const guestAssets = resolveGondolinGuestAssets();
   const baseRootfsPath = guestAssets.rootfsPath;
 
   if (!fs.existsSync(baseRootfsPath)) {