Broader rework

.dockerignore

@@ -0,0 +1,3 @@
+.git
+.DS_Store
+**/*.log

.github/workflows/docker-ci.yml

@@ -0,0 +1,113 @@
+name: docker-ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      kernel_release:
+        description: "v9fs/test release tag providing the kernel Image (default: kernel-main)"
+        required: true
+        default: "kernel-main"
+        type: string
+
+env:
+  # Pin the kernel version so BuildKit layer caching remains stable across commits.
+  # Bump this intentionally when you want to test a newer kernel.
+  KERNEL9P_LINUX_VERSION: "7.0"
+
+jobs:
+  docker-test:
+    name: docker (${{ matrix.target }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [test, race]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build ${{ matrix.target }} image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          target: ${{ matrix.target }}
+          load: true
+          tags: go9p:${{ matrix.target }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run ${{ matrix.target }}
+        run: docker run --rm go9p:${{ matrix.target }}
+
+  examplefs-unit:
+    name: example fs unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Run unit tests for example filesystems
+        run: go test ./p/srv/examples/...
+
+  tlsramfs-e2e:
+    name: tlsramfs userspace e2e
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+      - name: Run tlsramfs TLS client CRUD
+        run: go test -count=1 ./p/srv/examples/tlsramfs -run TestTLSRamfs_TLSClientCRUD
+
+  kernel9p-qemu:
+    # arm64-only kernel-client testing using v9fs/docker methodology.
+    name: kernel9p-qemu (arm64, v9fs/docker, ${{ matrix.fs }})
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: arm64
+            runs_on: ubuntu-24.04-arm
+            fs: ufs
+          - arch: arm64
+            runs_on: ubuntu-24.04-arm
+            fs: ramfs
+          - arch: arm64
+            runs_on: ubuntu-24.04-arm
+            fs: clonefs
+          - arch: arm64
+            runs_on: ubuntu-24.04-arm
+            fs: timefs
+          - arch: arm64
+            runs_on: ubuntu-24.04-arm
+            fs: netfs
+    runs-on: ${{ matrix.runs_on }}
+    timeout-minutes: 90
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run v9fs/docker kernel-client e2e (${{ matrix.fs }})
+        run: |
+          docker run --rm --privileged --platform linux/arm64 \
+            -v "${{ github.workspace }}:/opt/v9fs/go9p" \
+            -w /opt/v9fs/go9p \
+            -e V9FS_TEST_KERNEL_TAG="${{ inputs.kernel_release || 'kernel-main' }}" \
+            ghcr.io/v9fs/docker:v2.0.0 \
+            bash /opt/v9fs/go9p/scripts/v9fs/ci-e2e-fs.sh "${{ matrix.fs }}"
+

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+This file captures the working preferences for AI agents contributing to this repo.
+Tweak freely.
+
+## Branching and change hygiene
+
+- Do active work on `rework` unless told otherwise.
+- Keep `README.md`, `CHANGES.md`, and `TODO.md` updated as changes land.
+- Keep `HERZOG.md` in sync with `README.md` headings (AI-generated stylistic mirror).
+- Do not commit generated outputs (`logs/`, `kernel/`, `tmp/`, `initrd.cpio`, pid files).
+
+## Test philosophy
+- Prefer **guest-direct execution** (Option A): run tests **inside the QEMU guest**.
+- Avoid SSH/port-forwarding flows unless explicitly requested.
+- use u-root based minimal initrd as root filesystem
+- use u-root/cpu with NFS option to expose tools, benchmarks, tests, and results directories to the guest running in qemu
+- be able to run as github actions or using act locally
+- provide easy mechanism for running local tests (make or script based)
+- verify workflow locally before pushing to github
+- CI should surface failures (red dashboards) while still running the full suite:
+ - Run the whole matrix
+ - Record failures
+ - Exit non-zero at the end
+
+## Local/dev environment assumptions
+
+- Primary local dev is **macOS via Docker + QEMU**.
+- Prefer solutions that work on Docker Desktop (no reliance on KVM).
+- After any manual experiment that uses `docker run`, ensure containers are not left running:
+ - Prefer `docker run --rm` plus a project label `v9fs.harness=v9fs-test`.
+ - If you suspect a hung run left containers behind, clean up with `make docker-clean` or `./scripts/v9fs-docker-clean`.
+
+## CI architecture preferences
+- Use http://github.com/v9fs/docker published base image instead of building custom docker for kernel build and/or test frameworks
+- Default to **ARM64** (`ubuntu-24.04-arm`) for builds/tests unless asked otherwise.
+- Build and/or test will be triggered by external triggers (such as v9fs/linux changes) or user request in addition to any changes to this repo
+- Separate concerns:
+ - **Kernel publishing** workflow: builds `v9fs/linux` arm64 `Image` and publishes it.
+ - **Harness CI** workflows: download a published kernel `Image` and run tests.
+- Publishing:
+ - Prefer a stable, `wget`-able GitHub Release asset `Image` tagged `kernel-main`, `kernel-nightly`, or `kernel- `.
+ - GHCR is optional/secondary; keep it consistent if used.
+
+## Logging and debuggability
+
+- Always preserve logs for failures (artifact upload `if: always()`).
+- When tests fail, also dump the relevant tails into the CI console output:
+ - `logs/*/qemu.log`
+ - per-test `*.log`
+ - `guest.exitcode` markers (or equivalent)
+
+## Style
+
+- Prefer small, explicit scripts over complex magic.
+- Keep paths stable and explicit (`/workspaces/share`, `kernel/.build/...`).
+- Avoid large refactors unless requested; preserve working behavior first.
+

CHANGES.md

@@ -0,0 +1,32 @@
+# Changes
+
+This file tracks notable changes on the `ericvh/go9p` fork branches (not upstream release notes).
+
+## Unreleased
+
+### Go / tooling
+
+- Add `go.mod` and enable module-based builds (`module github.com/lionkov/go9p`)
+- Target modern Go (`go 1.26.0`) and set `toolchain go1.26.0`
+
+### Tests / CI hygiene
+
+- Fix `go test ./...` failures on modern Go:
+  - Resolve `go vet` “non-constant format string” warnings
+  - Make Unix socket-based tests portable by using a temp socket path instead of `net.Listen("unix", "")`
+  - Avoid flaky failures when shutting down the listener (ignore expected “use of closed network connection” on close)
+- Add Docker-based Linux test runner (`Dockerfile`) with `test` and `race` targets.
+- Add GitHub Actions CI that runs Docker-based tests on every push/PR.
+- Add end-to-end client/server integration tests:
+  - UFS-backed e2e test in `p/clnt`
+  - Fsrv synthetic-tree e2e test in `p/srv`
+- Add QEMU-based Linux kernel 9p client smoke test (`Dockerfile.kernel9p-qemu`) and run it in CI (arm64 only for now).
+- Switch the kernel-client CI harness to run inside the prebuilt `ghcr.io/v9fs/docker:v2.0.0` image, using a u-root initrd + chroot flow (modeled after `github.com/v9fs/test`), instead of building a bespoke v9fs Docker image.
+- Add per-example filesystem tests:
+  - Unit tests for each 9P server in `p/srv/examples/*`.
+  - Kernel-client QEMU e2e matrix for `ufs`, `ramfs`, `clonefs`, and `timefs`.
+  - Userspace TLS e2e stage for `tlsramfs`.
+- CI: pin kernel9p Docker build and `docker run` to `linux/${{ matrix.arch }}` so Buildx does not load the wrong CPU architecture on split amd64/arm64 runners.
+- CI: build the kernel9p Docker image **once per architecture** per workflow run, then run `qemu` / `diod` / `u9fs` smoke tests against that image (still uses BuildKit GHA cache across commits).
+- Add `HERZOG.md` as an AI-generated stylistic mirror of `README.md`, with CI enforcement to keep headings in sync.
+

Dockerfile

@@ -0,0 +1,30 @@
+## Dockerfile for running Linux builds/tests from macOS.
+##
+## Usage:
+##   docker build -t go9p:test --target test .
+##   docker run --rm go9p:test
+##
+## Optional:
+##   docker build -t go9p:race --target race .
+##   docker run --rm go9p:race
+
+ARG GO_VERSION=1.26.0
+
+FROM golang:${GO_VERSION}-bookworm AS base
+WORKDIR /src
+
+# Keep the module download layer stable.
+COPY go.mod ./
+RUN go mod download
+
+COPY . .
+
+FROM base AS test
+RUN go test ./...
+CMD ["go", "test", "./..."]
+
+FROM base AS race
+# Race detector requires CGO; Debian-based images support this out of the box.
+RUN go test -race ./...
+CMD ["go", "test", "-race", "./..."]
+