Implement OCI/Dockerfile converters with Gondolin runtime integration

Author: vmg-dev

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+out/

Dockerfile.alpine-curl

@@ -0,0 +1,4 @@
+   FROM alpine:3.20
+   RUN apk add --no-cache curl ca-certificates
+   CMD ["/bin/sh"]
+   

Dockerfile.busybox

@@ -0,0 +1,2 @@
+FROM busybox:latest
+CMD ["/bin/busybox", "echo", "hello-from-dockerfile"]

README.md

@@ -1,28 +1,164 @@
-# Gondolin Image Tooling Plan
+# Gondolin Image Tools
 
-## Goal
-Create external tooling that converts container artifacts into images Gondolin can boot **without modifying Gondolin core code**.
+External OCI-first tooling that converts container artifacts into Gondolin-bootable images **without modifying Gondolin core**.
 
-## Recommendation
-Build in this order:
+## Status
 
-1. **`oci2gondolin` first** (core converter)
-2. **`dockerfile2gondolin` second** (thin wrapper around BuildKit + `oci2gondolin`)
+Implemented and working:
 
-This keeps complexity low and allows multiple input paths (registry, CI-produced OCI tar, local OCI layout).
+- ✅ `oci2gondolin` core converter
+  - input sources: `--image`, `--oci-layout`, `--oci-tar` (exactly one)
+  - platform selection (`linux/amd64`, `linux/arm64`, plus short forms)
+  - output modes: `rootfs`, `assets`
+  - structured dry-run plans
+  - actionable validation + runtime errors
+- ✅ OCI resolver/puller for public registries (Bearer token flow)
+- ✅ digest verification + local blob cache
+- ✅ layer apply engine (tar+gzip, whiteouts, secure extraction checks)
+- ✅ materialization
+  - ext4 image creation (`rootfs.ext4`)
+  - metadata emission (`meta.json`)
+  - assets output (`vmlinuz-virt`, `initramfs.cpio.lz4`, `rootfs.ext4`, `manifest.json`)
+- ✅ `dockerfile2gondolin` thin wrapper
+  - BuildKit via `docker buildx` (temp docker-container builder)
+  - BuildKit via `buildctl`
+  - delegates conversion to `oci2gondolin`
+- ✅ unit tests for argument parsing/validation
 
-## Why OCI-first
-- Dockerfile support is effectively a full build system
-- OCI image/manifest/layers are a stable output contract
-- Reusable converter for any upstream build stack
+## Requirements
 
-## Deliverables
-- `oci2gondolin` CLI
-- `dockerfile2gondolin` CLI (wrapper)
-- Test fixtures + conformance tests
-- Basic docs and examples
+- Bun 1.2+
+- Docker (for `dockerfile2gondolin`)
+- `e2fsprogs` (`mke2fs`, `debugfs`) for rootfs creation/injection
+- (optional runtime verification) `@earendil-works/gondolin` CLI + QEMU
+
+macOS helpers:
+
+```bash
+brew install e2fsprogs qemu
+```
+
+## Install
+
+```bash
+bun install
+```
+
+## Quickstart
+
+### 1) Validate build + tests
+
+```bash
+bun test
+bun run typecheck
+bun run build
+```
+
+### 2) Convert BusyBox image to Gondolin assets
+
+```bash
+bun run oci2gondolin -- \
+  --image busybox:latest \
+  --platform linux/arm64 \
+  --mode assets \
+  --out ./out/busybox-assets
+```
+
+### 3) Run with Gondolin package
+
+```bash
+GONDOLIN_GUEST_DIR=./out/busybox-assets bunx gondolin exec -- /bin/busybox echo hello
+```
+
+### 4) Dockerfile -> Gondolin (wrapper)
+
+```bash
+bun run dockerfile2gondolin -- \
+  --file ./Dockerfile.busybox \
+  --context . \
+  --platform linux/arm64 \
+  --mode assets \
+  --out ./out/busybox-from-dockerfile
+```
+
+Then:
+
+```bash
+GONDOLIN_GUEST_DIR=./out/busybox-from-dockerfile bunx gondolin exec -- /bin/busybox echo wrapper-ok
+```
+
+## Distro smoke matrix (arm64)
+
+Validated with `gondolin exec`:
+
+- Alpine (`alpine:3.20`)
+- Debian (`debian:bookworm-slim`)
+- Ubuntu (`ubuntu:24.04`)
+- Fedora (`fedora:latest`)
+- Arch Linux ARM (`menci/archlinuxarm:latest`)
+
+### macOS note (case-sensitive temp workspace)
+
+Some images (notably Arch/Fedora) include case-sensitive filesystem paths that conflict on default case-insensitive macOS volumes. Use a case-sensitive temp mount and point `TMPDIR` at it when converting:
+
+```bash
+CASE_ROOT=$(mktemp -d)
+IMG="$CASE_ROOT/oci2gondolin-casefs.sparseimage"
+MP="$CASE_ROOT/mount"
+mkdir -p "$MP"
+
+hdiutil create -size 8g -type SPARSE -fs 'Case-sensitive APFS' -volname Oci2GondolinCase "$IMG"
+hdiutil attach "$IMG" -mountpoint "$MP" -nobrowse
+
+TMPDIR="$MP" bun run oci2gondolin -- --image menci/archlinuxarm:latest --platform linux/arm64 --mode assets --out ./out/arch-assets
+GONDOLIN_GUEST_DIR=./out/arch-assets bunx gondolin exec -- /bin/sh -lc 'cat /etc/os-release | head -n 2'
+
+hdiutil detach "$MP"
+rm -rf "$CASE_ROOT"
+```
+
+## Dry-run examples
+
+```bash
+bun run oci2gondolin -- --image busybox:latest --out ./out/plan --dry-run
+bun run dockerfile2gondolin -- --file ./Dockerfile --context . --out ./out/plan --dry-run
+```
+
+## Commands
+
+### `oci2gondolin`
+
+- Input source (exactly one):
+  - `--image <ref>`
+  - `--oci-layout <path>`
+  - `--oci-tar <path>`
+- `--platform linux/amd64|linux/arm64` (or `amd64|arm64`)
+- `--mode rootfs|assets` (default: `rootfs`)
+- `--out <path>` (required)
+- `--dry-run`
+
+### `dockerfile2gondolin`
+
+- `--file <path>` (required)
+- `--context <path>` (required)
+- `--out <path>` (required)
+- `--platform linux/amd64|linux/arm64`
+- `--mode rootfs|assets`
+- `--builder docker-buildx|buildctl`
+- `--target <stage>`
+- `--build-arg KEY=VALUE` (repeatable)
+- `--secret ...` (repeatable)
+- `--dry-run`
+
+## Architecture
+
+- `oci2gondolin` contains the converter pipeline (resolver/puller/layer-apply/materialize)
+- converter applies OCI layers on top of an extracted Gondolin base rootfs to preserve runtime compatibility (`sandboxd`, `sandboxfs`, init flow)
+- `dockerfile2gondolin` is a wrapper layer around BuildKit + `oci2gondolin`
+- gondolin core remains external/unmodified
+
+## Planning docs
 
-## Directory contents
 - [`01-oci2gondolin-spec.md`](./01-oci2gondolin-spec.md)
 - [`02-dockerfile2gondolin-wrapper.md`](./02-dockerfile2gondolin-wrapper.md)
 - [`03-implementation-phases.md`](./03-implementation-phases.md)

bun.lock

@@ -0,0 +1,30 @@
+{
+  "name": "gondolin-image-tools",
+  "version": "0.1.0",
+  "private": true,
+  "description": "OCI-first external image tooling for Gondolin",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "bin": {
+    "oci2gondolin": "./dist/bin/oci2gondolin.js",
+    "dockerfile2gondolin": "./dist/bin/dockerfile2gondolin.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "oci2gondolin": "bun run src/bin/oci2gondolin.ts",
+    "dockerfile2gondolin": "bun run src/bin/dockerfile2gondolin.ts"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}

package.json

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import { runDockerfile2Gondolin } from "../commands/dockerfile2gondolin";
+
+async function main(): Promise<void> {
+  const exitCode = await runDockerfile2Gondolin(process.argv.slice(2));
+  process.exit(exitCode);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

src/bin/dockerfile2gondolin.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+import { runOci2Gondolin } from "../commands/oci2gondolin";
+
+async function main(): Promise<void> {
+  const exitCode = await runOci2Gondolin(process.argv.slice(2));
+  process.exit(exitCode);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

src/bin/oci2gondolin.ts

@@ -0,0 +1,35 @@
+import { parseDockerfile2GondolinArgs } from "../dockerfile2gondolin/cli/args";
+import { dockerfile2GondolinUsage } from "../dockerfile2gondolin/cli/usage";
+import { buildDockerfileWrapperPlan } from "../dockerfile2gondolin/pipeline/plan";
+import { executeDockerfileWrapper } from "../dockerfile2gondolin/pipeline/execute";
+import { CliHelpRequested, CliUsageError } from "../shared/cli-errors";
+import { renderCliError } from "../shared/render-cli-error";
+
+export async function runDockerfile2Gondolin(argv: string[]): Promise<number> {
+  try {
+    const options = parseDockerfile2GondolinArgs(argv);
+
+    if (options.dryRun) {
+      const plan = buildDockerfileWrapperPlan(options);
+      console.log(JSON.stringify(plan, null, 2));
+      return 0;
+    }
+
+    const result = await executeDockerfileWrapper(options);
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof CliHelpRequested) {
+      console.log(dockerfile2GondolinUsage());
+      return 0;
+    }
+
+    console.error(renderCliError(error));
+
+    if (error instanceof CliUsageError) {
+      console.error("\n" + dockerfile2GondolinUsage());
+    }
+
+    return 1;
+  }
+}

src/commands/dockerfile2gondolin.ts

@@ -0,0 +1,35 @@
+import { CliHelpRequested, CliUsageError } from "../shared/cli-errors";
+import { renderCliError } from "../shared/render-cli-error";
+import { parseOci2GondolinArgs } from "../oci2gondolin/cli/args";
+import { oci2GondolinUsage } from "../oci2gondolin/cli/usage";
+import { executeConversion } from "../oci2gondolin/pipeline/execute";
+import { buildDryRunPlan } from "../oci2gondolin/pipeline/plan";
+
+export async function runOci2Gondolin(argv: string[]): Promise<number> {
+  try {
+    const options = parseOci2GondolinArgs(argv);
+
+    if (options.dryRun) {
+      const plan = buildDryRunPlan(options);
+      console.log(JSON.stringify(plan, null, 2));
+      return 0;
+    }
+
+    const result = await executeConversion(options);
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  } catch (error) {
+    if (error instanceof CliHelpRequested) {
+      console.log(oci2GondolinUsage());
+      return 0;
+    }
+
+    console.error(renderCliError(error));
+
+    if (error instanceof CliUsageError) {
+      console.error("\n" + oci2GondolinUsage());
+    }
+
+    return 1;
+  }
+}