@soulguard/core 0.1.0

package/test-e2e/cases/sync-no-sudo-drift/test.sh

@@ -0,0 +1,10 @@
+# Agent can't fix drift without sudo (no init = no scoped sudoers)
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+
+# Make workspace readable by agent (no init, no sudoers)
+chmod 755 .
+chmod o+r soulguard.json SOUL.md
+
+# Agent syncs drifted workspace without sudo — chown should fail
+su - agent -c "soulguard sync $(pwd)"

package/test-e2e/cases/vault-remove-file/expected.txt

@@ -0,0 +1,26 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 3 vault file(s)
+
+Done.
+DIFF:
+Soulguard Diff — /workspace
+
+  🗑️ BOOTSTRAP.md (staged for deletion)
+  ✅ SOUL.md (no changes)
+  ✅ soulguard.json (no changes)
+
+1 file(s) changed
+Approval hash: 24d6aaec960a3d74c84690b786336bdcce7c35585e353be867f6f0606093618e
+
+Approved 1 file(s):
+  ✅ BOOTSTRAP.md
+
+Vault updated. Staging synced.
+BOOTSTRAP EXISTS:
+no
+SOUL EXISTS:
+yes

package/test-e2e/cases/vault-remove-file/test.sh

@@ -0,0 +1,31 @@
+# Vault file deletion: agent deletes a file from staging, owner approves.
+# Tests the full lifecycle when a vault-protected file is deleted through staging.
+
+# Setup: two vault files
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","BOOTSTRAP.md","soulguard.json"],"ledger":[]}
+EOF
+echo '# My Soul' > SOUL.md
+echo '# Bootstrap' > BOOTSTRAP.md
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+# Agent deletes BOOTSTRAP.md from staging (done with it)
+su - agent -c "rm $(pwd)/.soulguard/staging/BOOTSTRAP.md"
+
+# Diff should show deletion
+echo "DIFF:"
+NO_COLOR=1 soulguard diff . 2>&1
+
+# Get hash and approve the deletion
+HASH=$(NO_COLOR=1 soulguard diff . 2>&1 | grep 'Approval hash:' | awk '{print $NF}')
+soulguard approve . --hash "$HASH"
+
+# BOOTSTRAP.md should be gone from disk
+echo "BOOTSTRAP EXISTS:"
+test -f BOOTSTRAP.md && echo "yes" || echo "no"
+
+# SOUL.md should still exist
+echo "SOUL EXISTS:"
+test -f SOUL.md && echo "yes" || echo "no"

package/test-e2e/cases/vault-write-blocked/expected.txt

@@ -0,0 +1,8 @@
+Soulguard Sync — /workspace
+
+Nothing to fix — all files ok.
+-bash: line 1: /workspace/SOUL.md: Permission denied
+WRITE BLOCKED (GOOD)
+chown: changing ownership of '/workspace/SOUL.md': Operation not permitted
+CHOWN BLOCKED (GOOD)
+# My Soul

package/test-e2e/cases/vault-write-blocked/test.sh

@@ -0,0 +1,14 @@
+# Setup: create and protect a vault file (as owner/root)
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+soulguard sync .
+
+# Attack 1: Agent tries to write to the vaulted file (should fail)
+su - agent -c "(echo hacked > $(pwd)/SOUL.md) 2>&1" && echo "WRITE SUCCEEDED (BAD)" || echo "WRITE BLOCKED (GOOD)"
+
+# Attack 2: Agent tries to chown the file back (should fail without root)
+su - agent -c "chown agent:agent $(pwd)/SOUL.md 2>&1" && echo "CHOWN SUCCEEDED (BAD)" || echo "CHOWN BLOCKED (GOOD)"
+
+# Verify file is still intact
+cat SOUL.md

package/test-e2e/run-tests.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# E2E snapshot test runner for soulguard CLI.
+#
+# Runs each test case in a separate Docker container for full isolation.
+# No shared state between tests — each gets a fresh filesystem.
+#
+# Each test case is a directory under cases/ containing:
+#   test.sh       — shell script to run (executed as `agent` user)
+#   expected.txt  — exact expected stdout+stderr output
+#
+# Usage:
+#   ./run-tests.sh                  # run all tests, diff against snapshots
+#   ./run-tests.sh --update         # regenerate all snapshots
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CASES_DIR="$SCRIPT_DIR/cases"
+IMAGE="soulguard-e2e"
+UPDATE="${1:-}"
+PASS=0
+FAIL=0
+
+for case_dir in "$CASES_DIR"/*/; do
+  test_name="$(basename "$case_dir")"
+  test_script="$case_dir/test.sh"
+  expected_file="$case_dir/expected.txt"
+
+  if [ ! -f "$test_script" ]; then
+    echo "SKIP: $test_name (no test.sh)"
+    continue
+  fi
+
+  # Run test in a fresh container — complete isolation
+  actual=$(docker run --rm "$IMAGE" bash -c "
+    workspace=\$(mktemp -d /tmp/soulguard-e2e-XXXX)
+    chmod 755 \"\$workspace\"
+    cd \"\$workspace\"
+    NO_COLOR=1 bash /app/packages/core/test-e2e/cases/$test_name/test.sh 2>&1 | \
+      sed \"s|\$workspace|/workspace|g\" | \
+      sed 's|/app/packages/core/test-e2e/cases/$test_name/test.sh|test.sh|g'
+  ") || true
+
+  if [ "$UPDATE" = "--update" ]; then
+    echo "$actual" > "$expected_file"
+    echo "UPDATED: $test_name"
+    continue
+  fi
+
+  if [ ! -f "$expected_file" ]; then
+    echo "FAIL: $test_name (no expected.txt — run with --update)"
+    echo "--- actual output ---"
+    echo "$actual"
+    echo "---"
+    FAIL=$((FAIL + 1))
+    continue
+  fi
+
+  expected=$(cat "$expected_file")
+
+  if [ "$actual" = "$expected" ]; then
+    echo "PASS: $test_name"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $test_name"
+    diff --color=auto <(echo "$expected") <(echo "$actual") || true
+    FAIL=$((FAIL + 1))
+  fi
+done
+
+echo ""
+echo "$PASS passed, $FAIL failed"
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi

package/test-integration/Dockerfile

@@ -0,0 +1,17 @@
+FROM oven/bun:latest
+
+# Create test users that mirror the soulguard design
+RUN groupadd soulguard && \
+    useradd -r -g soulguard soulguardian && \
+    useradd -g staff agent 2>/dev/null || useradd agent
+
+WORKDIR /app
+
+# Copy full monorepo (respects .dockerignore)
+COPY . .
+
+# Install deps
+RUN bun install --frozen-lockfile
+
+# Run integration tests as root (needed for chown)
+CMD ["bun", "test", "packages/core/test-integration/"]

package/test-integration/system-ops-node.integration.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Integration tests for NodeSystemOps — requires root + test users.
+ *
+ * Run via Docker:
+ *   docker build -f packages/core/test-integration/Dockerfile -t soulguard-test .
+ *   docker run --rm soulguard-test
+ *
+ * These tests exercise chown (which requires root) and verify the full
+ * ownership pipeline: create file → chown to soulguardian → verify stat.
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { NodeSystemOps } from "../src/system-ops-node.js";
+
+let workspace: string;
+let ops: NodeSystemOps;
+
+beforeEach(async () => {
+  workspace = await mkdtemp(join(tmpdir(), "soulguard-integ-"));
+  ops = new NodeSystemOps(workspace);
+});
+
+afterEach(async () => {
+  await rm(workspace, { recursive: true, force: true });
+});
+
+describe("NodeSystemOps integration (root + test users)", () => {
+  // ── chown ───────────────────────────────────────────────────────────
+
+  describe("chown", () => {
+    test("transfers file to soulguardian:soulguard", async () => {
+      await writeFile(join(workspace, "SOUL.md"), "# Soul");
+
+      const result = await ops.chown("SOUL.md", {
+        user: "soulguardian",
+        group: "soulguard",
+      });
+      expect(result.ok).toBe(true);
+
+      const stat = await ops.stat("SOUL.md");
+      expect(stat.ok).toBe(true);
+      if (!stat.ok) return;
+      expect(stat.value.ownership.user).toBe("soulguardian");
+      expect(stat.value.ownership.group).toBe("soulguard");
+    });
+
+    test("transfers file back to agent user", async () => {
+      await writeFile(join(workspace, "notes.md"), "# Notes");
+
+      // First transfer to soulguardian
+      await ops.chown("notes.md", {
+        user: "soulguardian",
+        group: "soulguard",
+      });
+
+      // Then release back to agent
+      const result = await ops.chown("notes.md", {
+        user: "agent",
+        group: "soulguard",
+      });
+      expect(result.ok).toBe(true);
+
+      const stat = await ops.stat("notes.md");
+      expect(stat.ok).toBe(true);
+      if (!stat.ok) return;
+      expect(stat.value.ownership.user).toBe("agent");
+    });
+
+    test("returns error for nonexistent file", async () => {
+      const result = await ops.chown("nope.md", {
+        user: "soulguardian",
+        group: "soulguard",
+      });
+      expect(result.ok).toBe(false);
+    });
+
+    test("returns error for nonexistent user", async () => {
+      await writeFile(join(workspace, "test.md"), "hello");
+
+      const result = await ops.chown("test.md", {
+        user: "nonexistent_user_xyz",
+        group: "soulguard",
+      });
+      expect(result.ok).toBe(false);
+    });
+  });
+
+  // ── Full vault workflow ─────────────────────────────────────────────
+
+  describe("vault workflow", () => {
+    test("protect → verify → release cycle", async () => {
+      await writeFile(join(workspace, "SOUL.md"), "# My Soul");
+
+      // 1. Protect: chown + chmod
+      const chownResult = await ops.chown("SOUL.md", {
+        user: "soulguardian",
+        group: "soulguard",
+      });
+      expect(chownResult.ok).toBe(true);
+
+      const chmodResult = await ops.chmod("SOUL.md", "444");
+      expect(chmodResult.ok).toBe(true);
+
+      // 2. Verify: stat shows correct ownership + mode
+      const stat1 = await ops.stat("SOUL.md");
+      expect(stat1.ok).toBe(true);
+      if (!stat1.ok) return;
+      expect(stat1.value.ownership.user).toBe("soulguardian");
+      expect(stat1.value.ownership.group).toBe("soulguard");
+      expect(stat1.value.ownership.mode).toBe("444");
+
+      // 3. Content still readable
+      const content = await ops.readFile("SOUL.md");
+      expect(content.ok).toBe(true);
+      if (!content.ok) return;
+      expect(content.value).toBe("# My Soul");
+
+      // 4. Hash still works
+      const hash = await ops.hashFile("SOUL.md");
+      expect(hash.ok).toBe(true);
+      if (!hash.ok) return;
+      expect(hash.value).toMatch(/^[a-f0-9]{64}$/);
+
+      // 5. Release: chown back + chmod
+      const releaseChown = await ops.chown("SOUL.md", {
+        user: "agent",
+        group: "soulguard",
+      });
+      expect(releaseChown.ok).toBe(true);
+
+      const releaseChmod = await ops.chmod("SOUL.md", "644");
+      expect(releaseChmod.ok).toBe(true);
+
+      // 6. Verify released state
+      const stat2 = await ops.stat("SOUL.md");
+      expect(stat2.ok).toBe(true);
+      if (!stat2.ok) return;
+      expect(stat2.value.ownership.user).toBe("agent");
+      expect(stat2.value.ownership.mode).toBe("644");
+    });
+  });
+
+  // ── userExists / groupExists with real users ────────────────────────
+
+  describe("user/group checks with test users", () => {
+    test("soulguardian user exists", async () => {
+      const result = await ops.userExists("soulguardian");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(true);
+    });
+
+    test("soulguard group exists", async () => {
+      const result = await ops.groupExists("soulguard");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(true);
+    });
+
+    test("agent user exists", async () => {
+      const result = await ops.userExists("agent");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(true);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}