@flout/paf-flout 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @flout/paf-flout
+
+> **Fork-only.** Not part of upstream `bgrgicak/flout`. This package ships a batteries-included Docker image specific to the PaF (phone-a-friend) integration.
+
+A monorepo package that holds the Dockerfile for the `paf-flout:<hash>` image and a small build helper. The Dockerfile is embedded as a TypeScript string constant — same shape as `@flout/sandbox`'s `EMBEDDED_DOCKERFILE` — so the image tag is content-addressed (sha256 of the Dockerfile text). Any edit to the embedded Dockerfile produces a new tag automatically.
+
+## What's inside the image
+
+| Layer | Contents |
+|---|---|
+| Base | `node:22-slim` |
+| System | bash, curl, git, sudo, tmux |
+| User | `dev` at UID 1000 (replaces node:22-slim's `node` user) |
+| Backend CLIs (stable layer) | `@openai/codex`, `@google/gemini-cli`, `opencode-ai` |
+| Claude | `claude.ai/install.sh` + `/usr/local/bin/claude` symlink |
+| PaF (volatile layer, last) | `@freibergergarcia/phone-a-friend@2.3.1` |
+| PaF plugin shim | `phone-a-friend plugin install --opencode` |
+| Auth dirs | pre-created at `~/.claude`, `~/.codex`, `~/.gemini`, `~/.local/share/opencode`, `~/.config/{opencode,phone-a-friend}` |
+| Shell entry | `phone-a-friend doctor` runs on shell entry via `.bashrc` |
+
+Layer ordering: PaF sits last so PaF version bumps don't invalidate the heavier backend install layers (codex/gemini/opencode/claude all stay cached).
+
+## Build
+
+```bash
+npm run build           # tsc compile of this package
+npm run build-image     # docker build -t paf-flout:<sha256-prefix>
+
+# also tag the build with convenience aliases:
+npm run build-image -- paf-flout:r3 paf-flout:latest
+```
+
+Override the engine:
+
+```bash
+PAF_FLOUT_ENGINE_BINARY=podman npm run build-image
+```
+
+## Use with flout
+
+```bash
+# get the content-addressed tag programmatically
+PAF_FLOUT_IMAGE=$(node -e "import('./packages/paf-flout/dist/src/index.js').then(m => console.log(m.IMAGE_NAME))")
+
+flout sandbox start --image $PAF_FLOUT_IMAGE --clean --name devbox -- \
+  -p 127.0.0.1:4096:4096 \
+  -e OPENCODE_SERVER_PASSWORD=$(openssl rand -hex 16)
+
+flout sandbox shell devbox
+# inside: opencode serve --hostname 0.0.0.0 --port 4096
+# host browser → http://localhost:4096
+```
+
+## Why this is a separate package (and fork-only)
+
+- **Right layer.** `@flout/sandbox` is the generic container lifecycle (knows nothing about specific tools). This package owns the image-specific knowledge (which CLIs to bundle, which versions, layer order).
+- **Doesn't go upstream.** Bero's flout is a generic agent-session tool. The PaF integration is one specific use case — it lives in the fork.
+- **Content-addressed tagging.** Edit the Dockerfile string → automatic new tag on next build, mirroring how `@flout/sandbox` invalidates its `flout-sandbox:<hash>` image.
+
+## Related
+
+- Eventual home: dedicated `paf-flout` repo with CI multi-arch builds and GHCR publishing — see the portability plan.
+- Predecessor: loose Dockerfile at `~/sandbox-experiments/paf-flout-track-a/Dockerfile` (now superseded by this package).

package/dist/src/build-cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build-cli.d.ts.map

package/dist/src/build-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-cli.d.ts","sourceRoot":"","sources":["../../src/build-cli.ts"],"names":[],"mappings":""}

package/dist/src/build-cli.js

@@ -0,0 +1,23 @@
+// Thin CLI wrapper around buildImage(). Invoked via `npm run build-image`.
+//
+//   npm run build-image                                       # tags paf-flout:<sha256-prefix>
+//   npm run build-image -- paf-flout:r3 paf-flout:latest      # also applies those extra tags
+//   PAF_FLOUT_ENGINE_BINARY=podman npm run build-image        # build with a different engine
+import { buildImage, IMAGE_NAME } from './index.js';
+const engineBinary = process.env.PAF_FLOUT_ENGINE_BINARY || 'docker';
+const extraTags = process.argv.slice(2);
+// Extra tags become `-t <tag>` args prepended BEFORE the build-context path in
+// the spawned `docker build` invocation. Reject anything that could be parsed
+// by docker as a flag (any arg starting with '-') — legitimate image tags
+// never start with '-', so this blocks injection like '--push' or '-f /etc/...'.
+for (const tag of extraTags) {
+    if (tag.startsWith('-')) {
+        console.error(`Refusing tag '${tag}': image tags cannot start with '-'. ` +
+            `Allowed shape: registry/repo:tag, e.g. paf-flout:r3 or ghcr.io/user/img:latest.`);
+        process.exit(1);
+    }
+}
+buildImage({ engineBinary, extraTags });
+const tagsApplied = [IMAGE_NAME, ...extraTags];
+console.log(`Built ${tagsApplied.join(', ')}`);
+//# sourceMappingURL=build-cli.js.map

package/dist/src/build-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-cli.js","sourceRoot":"","sources":["../../src/build-cli.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,+FAA+F;AAC/F,8FAA8F;AAC9F,8FAA8F;AAC9F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,QAAQ,CAAC;AACrE,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAExC,+EAA+E;AAC/E,8EAA8E;AAC9E,0EAA0E;AAC1E,iFAAiF;AACjF,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;IAC5B,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CACX,iBAAiB,GAAG,uCAAuC;YAC3D,iFAAiF,CAClF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,UAAU,CAAC,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC;AAExC,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,GAAG,SAAS,CAAC,CAAC;AAC/C,OAAO,CAAC,GAAG,CAAC,SAAS,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export declare const EMBEDDED_DOCKERFILE = "FROM node:22-slim\n\nRUN apt-get update && apt-get install -y \\\n    bash curl git sudo tmux \\\n    && rm -rf /var/lib/apt/lists/*\n\n# node:22-slim ships a 'node' user at UID 1000. Remove it so 'dev' can\n# take UID 1000 \u2014 bind-mounted credential files (~/.claude, ~/.local/share/opencode,\n# ~/.codex, ~/.gemini) are then readable/writable by dev without permission issues.\nRUN userdel -r node 2>/dev/null || true \\\n    && useradd -m -s /bin/bash -u 1000 dev \\\n    && adduser dev sudo \\\n    && echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers\n\n# Backend CLIs (stable layer). Bumped less often than PaF, so they sit in their\n# own RUN to keep their cache hit when PaF version changes.\nRUN npm install -g \\\n      @openai/codex \\\n      @google/gemini-cli \\\n      opencode-ai\n\nUSER dev\nWORKDIR /home/dev\nENV PATH=\"/home/dev/.local/bin:${PATH}\"\n\n# Claude \u2014 native installer writes ~/.local/bin/claude. Symlink into\n# /usr/local/bin so bash -lc (login shells used in docker exec) finds it.\nRUN curl -fsSL https://claude.ai/install.sh | bash \\\n    && sudo ln -sf /home/dev/.local/bin/claude /usr/local/bin/claude\n\n# PaF installed LAST (volatile layer). When PaF version bumps, only this layer\n# and the plugin-install layer below rebuild \u2014 the backend CLIs above stay cached.\nUSER root\nRUN npm install -g @freibergergarcia/phone-a-friend@2.3.1\nUSER dev\n\n# PaF OpenCode shim install at build time (host shims are nvm-symlinks, can't mount).\nRUN phone-a-friend plugin install --opencode\n\n# Pre-create auth dirs as dev so bind mounts don't break writes to adjacent paths.\nRUN mkdir -p \\\n      /home/dev/.claude \\\n      /home/dev/.codex \\\n      /home/dev/.gemini \\\n      /home/dev/.local/share/opencode \\\n      /home/dev/.config/opencode \\\n      /home/dev/.config/phone-a-friend\n\nRUN echo 'echo \"\"; phone-a-friend doctor 2>&1 | head -30 || true; echo \"\"' >> /home/dev/.bashrc\n\nCMD [\"sleep\", \"infinity\"]\n";
+export declare const IMAGE_BASE = "paf-flout";
+export declare const DOCKERFILE_TAG: string;
+export declare const IMAGE_NAME: string;
+export interface BuildOptions {
+    engineBinary?: string;
+    extraTags?: string[];
+}
+export declare function buildImage(options?: BuildOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,mBAAmB,i8DAmD/B,CAAC;AAEF,eAAO,MAAM,UAAU,cAAc,CAAC;AAItC,eAAO,MAAM,cAAc,QAIZ,CAAC;AAEhB,eAAO,MAAM,UAAU,QAAoC,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,UAAU,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI,CAY3D"}

package/dist/src/index.js

@@ -0,0 +1,89 @@
+import { execFileSync } from 'child_process';
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+// Dockerfile embedded as a string constant. Mirrors the pattern from
+// @flout/sandbox so the image tag is content-addressed (sha256 of the
+// Dockerfile text) — any edit here automatically invalidates the cached image
+// on next build, no manual version bumping needed.
+//
+// Layer ordering note: backend CLIs (codex/gemini/opencode/claude) sit BEFORE
+// phone-a-friend so PaF version bumps don't invalidate the (larger) backend
+// install layers. `phone-a-friend plugin install --opencode` must come after
+// both PaF and opencode are installed.
+export const EMBEDDED_DOCKERFILE = `FROM node:22-slim
+
+RUN apt-get update && apt-get install -y \\
+    bash curl git sudo tmux \\
+    && rm -rf /var/lib/apt/lists/*
+
+# node:22-slim ships a 'node' user at UID 1000. Remove it so 'dev' can
+# take UID 1000 — bind-mounted credential files (~/.claude, ~/.local/share/opencode,
+# ~/.codex, ~/.gemini) are then readable/writable by dev without permission issues.
+RUN userdel -r node 2>/dev/null || true \\
+    && useradd -m -s /bin/bash -u 1000 dev \\
+    && adduser dev sudo \\
+    && echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers
+
+# Backend CLIs (stable layer). Bumped less often than PaF, so they sit in their
+# own RUN to keep their cache hit when PaF version changes.
+RUN npm install -g \\
+      @openai/codex \\
+      @google/gemini-cli \\
+      opencode-ai
+
+USER dev
+WORKDIR /home/dev
+ENV PATH="/home/dev/.local/bin:\${PATH}"
+
+# Claude — native installer writes ~/.local/bin/claude. Symlink into
+# /usr/local/bin so bash -lc (login shells used in docker exec) finds it.
+RUN curl -fsSL https://claude.ai/install.sh | bash \\
+    && sudo ln -sf /home/dev/.local/bin/claude /usr/local/bin/claude
+
+# PaF installed LAST (volatile layer). When PaF version bumps, only this layer
+# and the plugin-install layer below rebuild — the backend CLIs above stay cached.
+USER root
+RUN npm install -g @freibergergarcia/phone-a-friend@2.3.1
+USER dev
+
+# PaF OpenCode shim install at build time (host shims are nvm-symlinks, can't mount).
+RUN phone-a-friend plugin install --opencode
+
+# Pre-create auth dirs as dev so bind mounts don't break writes to adjacent paths.
+RUN mkdir -p \\
+      /home/dev/.claude \\
+      /home/dev/.codex \\
+      /home/dev/.gemini \\
+      /home/dev/.local/share/opencode \\
+      /home/dev/.config/opencode \\
+      /home/dev/.config/phone-a-friend
+
+RUN echo 'echo ""; phone-a-friend doctor 2>&1 | head -30 || true; echo ""' >> /home/dev/.bashrc
+
+CMD ["sleep", "infinity"]
+`;
+export const IMAGE_BASE = 'paf-flout';
+// 12-char prefix of sha256(EMBEDDED_DOCKERFILE) — matches @flout/sandbox's tag
+// shape so the look-and-feel is consistent across flout-built images.
+export const DOCKERFILE_TAG = crypto
+    .createHash('sha256')
+    .update(EMBEDDED_DOCKERFILE)
+    .digest('hex')
+    .slice(0, 12);
+export const IMAGE_NAME = `${IMAGE_BASE}:${DOCKERFILE_TAG}`;
+export function buildImage(options = {}) {
+    const engineBinary = options.engineBinary ?? 'docker';
+    const extraTags = options.extraTags ?? [];
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'paf-flout-build-'));
+    try {
+        fs.writeFileSync(path.join(tmpDir, 'Dockerfile'), EMBEDDED_DOCKERFILE);
+        const tagArgs = [IMAGE_NAME, ...extraTags].flatMap(t => ['-t', t]);
+        execFileSync(engineBinary, ['build', ...tagArgs, tmpDir], { stdio: 'inherit' });
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,qEAAqE;AACrE,sEAAsE;AACtE,8EAA8E;AAC9E,mDAAmD;AACnD,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDlC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,WAAW,CAAC;AAEtC,+EAA+E;AAC/E,sEAAsE;AACtE,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM;KACjC,UAAU,CAAC,QAAQ,CAAC;KACpB,MAAM,CAAC,mBAAmB,CAAC;KAC3B,MAAM,CAAC,KAAK,CAAC;KACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAEhB,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,UAAU,IAAI,cAAc,EAAE,CAAC;AAO5D,MAAM,UAAU,UAAU,CAAC,UAAwB,EAAE;IACnD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,QAAQ,CAAC;IACtD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAE1C,MAAM,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC1E,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,mBAAmB,CAAC,CAAC;QACvE,MAAM,OAAO,GAAG,CAAC,UAAU,EAAE,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACnE,YAAY,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,GAAG,OAAO,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAClF,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@flout/paf-flout",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "description": "Batteries-included image for flout sandboxes (PaF + codex + gemini + opencode + claude pre-installed). Fork-only — not part of upstream flout.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "build-image": "node dist/src/build-cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "GPL-2.0-only"
+}