Merge pull request #4 from git-stunts/feature/docker-guard-package

Feature/docker-guard-package

Author: flyingrobots

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] - 2026-01-08
+
+### Added
+- **Shared Docker Guard**: Added `@git-stunts/docker-guard` with `isDockerEnvironment`/`ensureDocker`, exported banner text, and injectable logger/exit hooks so every repo can reuse the same safety net.
+### Changed
+- **Plumbing Guard Wiring**: `@git-stunts/plumbing` now imports the shared guard via `test/support/ensure-docker.js`, `vitest.config.js`, and `test/deno_entry.js`, removing the in-repo Minecraft `src/infrastructure/DockerGuard.js`.
+
+## [2.8.0] - 2026-01-07
+
+### Added
+- **DockerGuard**: Introduced a critical safety service (`src/infrastructure/DockerGuard.js`) that prevents execution on the host machine to protect against unintended system modifications.
+- **Dockerized Workflow**: Added `Dockerfile.node`, `Dockerfile.bun`, `Dockerfile.deno`, and `docker-compose.yml` to standardize isolated testing environments.
+
+### Changed
+- **Command Whitelist Expansion**: Added `log` to the `CommandSanitizer` allowed list to support high-performance graph traversals.
+- **Strict Host Enforcement**: Updated `package.json` with a `pretest` script that enforces the `GIT_STUNTS_DOCKER` environment variable.
+
 ## [2.7.0] - 2026-01-07
 
 ### Added

README.md

@@ -20,6 +20,26 @@ A low-level, robust, and environment-agnostic Git plumbing library for the moder
 - **OOM Protection**: Integrated safety buffering (`GitStream.collect`) with configurable byte limits.
 - **Dockerized CI**: Parallel test execution across all runtimes using isolated containers.
 
+## 🛡️ Safety First: Docker Execution
+
+This library performs low-level Git manipulations. To protect your host system and ensure a reproducible environment, **execution on the host is strictly prohibited.**
+
+All tests and commands should be run inside the provided Docker containers:
+
+```bash
+docker-compose run --rm node-test
+```
+
+The system will automatically fail if `GIT_STUNTS_DOCKER=1` is not set.
+
+We load `@git-stunts/docker-guard` (v0.1.0+) before every suite (`test/support/ensure-docker.js`), so invoking `ensureDocker()` happens automatically for Vitest/Bun/Deno. You can copy the same pattern in other packages:
+
+```javascript
+import { ensureDocker } from '@git-stunts/docker-guard';
+
+ensureDocker();
+```
+
 ## 🏗️ Design Principles
 
 1.  **Git as a Subsystem**: Git is treated as an external, untrusted dependency. Every command and environment variable is sanitized.

docker-compose.yml

@@ -5,13 +5,18 @@ services:
       dockerfile: Dockerfile.node
     environment:
       - NODE_ENV=test
+      - GIT_STUNTS_DOCKER=1
 
   bun-test:
     build:
       context: .
       dockerfile: Dockerfile.bun
+    environment:
+      - GIT_STUNTS_DOCKER=1
 
   deno-test:
     build:
       context: .
       dockerfile: Dockerfile.deno
+    environment:
+      - GIT_STUNTS_DOCKER=1

package-lock.json

@@ -35,7 +35,8 @@
     "@eslint/js": "^9.17.0",
     "eslint": "^9.17.0",
     "prettier": "^3.4.2",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@git-stunts/docker-guard": "^0.1.0"
   },
   "files": [
     "src",
@@ -51,8 +52,22 @@
     "NOTICE",
     "SECURITY.md"
   ],
-  "repository": { "type": "git", "url": "git+https://github.com/git-stunts/plumbing.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/git-stunts/plumbing.git"
+  },
   "homepage": "https://github.com/git-stunts/plumbing#readme",
-  "bugs": { "url": "https://github.com/git-stunts/plumbing/issues" },
-  "keywords": ["git", "plumbing", "content-addressable", "dag", "merkle", "node", "deno", "bun"]
-}
+  "bugs": {
+    "url": "https://github.com/git-stunts/plumbing/issues"
+  },
+  "keywords": [
+    "git",
+    "plumbing",
+    "content-addressable",
+    "dag",
+    "merkle",
+    "node",
+    "deno",
+    "bun"
+  ]
+}

package.json

@@ -42,7 +42,8 @@ export default class CommandSanitizer {
     'check-ignore',
     'check-attr',
     'init',
-    'config'
+    'config',
+    'log'
   ]);
 
   /**

src/domain/services/CommandSanitizer.js

@@ -2,6 +2,11 @@
  * @fileoverview Integration tests for GitPlumbing
  */
 
+import { ensureDocker } from '@git-stunts/docker-guard';
+
+ensureDocker();
+
+import './test/deno_shim.js';
 import { mkdtempSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';

test.js

@@ -1,3 +1,4 @@
+import "./support/ensure-docker.js";
 import "./deno_shim.js";
 
 // Import all tests to run them in one Deno process with the shim
@@ -21,4 +22,4 @@ import "./domain/services/GitCommandBuilder.test.js";
 import "./domain/services/GitErrorClassifier.test.js";
 import "./domain/services/GitPersistenceService.test.js";
 import "./domain/value-objects/GitFileMode.test.js";
-import "./domain/value-objects/GitObjectType.test.js";
+import "./domain/value-objects/GitObjectType.test.js";

test/deno_entry.js

@@ -0,0 +1,3 @@
+import { ensureDocker } from '@git-stunts/docker-guard';
+
+ensureDocker();

test/support/ensure-docker.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    setupFiles: ['test/support/ensure-docker.js']
+  }
+});