@soulguard/core 0.1.0

package/src/vault-check.test.ts

@@ -0,0 +1,41 @@
+import { describe, test, expect } from "bun:test";
+import { isVaultedFile, normalizePath } from "./vault-check.js";
+
+describe("isVaultedFile", () => {
+  test("exact match", () => {
+    expect(isVaultedFile(["SOUL.md"], "SOUL.md")).toBe(true);
+    expect(isVaultedFile(["SOUL.md"], "AGENTS.md")).toBe(false);
+  });
+
+  test("normalizes leading ./ and /", () => {
+    expect(isVaultedFile(["SOUL.md"], "./SOUL.md")).toBe(true);
+    expect(isVaultedFile(["./SOUL.md"], "SOUL.md")).toBe(true);
+  });
+
+  test("glob * matches single segment", () => {
+    expect(isVaultedFile(["memory/*.md"], "memory/day1.md")).toBe(true);
+    expect(isVaultedFile(["memory/*.md"], "memory/archive/old.md")).toBe(false);
+    expect(isVaultedFile(["*.md"], "SOUL.md")).toBe(true);
+  });
+
+  test("glob ** matches nested paths", () => {
+    expect(isVaultedFile(["memory/**"], "memory/day1.md")).toBe(true);
+    expect(isVaultedFile(["memory/**"], "memory/archive/old.md")).toBe(true);
+    expect(isVaultedFile(["skills/**"], "memory/day1.md")).toBe(false);
+  });
+});
+
+describe("normalizePath", () => {
+  test("strips leading ./", () => {
+    expect(normalizePath("./SOUL.md")).toBe("SOUL.md");
+  });
+
+  test("strips leading /", () => {
+    expect(normalizePath("/SOUL.md")).toBe("SOUL.md");
+  });
+
+  test("passes through normal paths", () => {
+    expect(normalizePath("SOUL.md")).toBe("SOUL.md");
+    expect(normalizePath("memory/day1.md")).toBe("memory/day1.md");
+  });
+});

package/src/vault-check.ts

@@ -0,0 +1,24 @@
+/**
+ * Check if a file path matches a vault entry.
+ * Supports exact matches and glob patterns (*, **).
+ */
+
+import { isGlob, matchGlob } from "./glob.js";
+
+export function isVaultedFile(vaultFiles: string[], filePath: string): boolean {
+  const norm = normalizePath(filePath);
+  return vaultFiles.some((pattern) => {
+    const normPattern = normalizePath(pattern);
+    if (isGlob(normPattern)) {
+      return matchGlob(normPattern, norm);
+    }
+    return norm === normPattern;
+  });
+}
+
+export function normalizePath(p: string): string {
+  let s = p;
+  if (s.startsWith("./")) s = s.slice(2);
+  if (s.startsWith("/")) s = s.slice(1);
+  return s;
+}

package/test-e2e/Dockerfile

@@ -0,0 +1,29 @@
+FROM oven/bun:latest
+
+# Create agent user only — soulguardian/soulguard are created by `soulguard init`
+RUN useradd -m -s /bin/bash agent
+
+# Install sudo + git (git needed for e2e tests with git integration)
+RUN apt-get update && apt-get install -y sudo git && rm -rf /var/lib/apt/lists/*
+
+# No broad sudoers for agent — init generates scoped rules.
+# Agent gets sudo only after `soulguard init` writes /etc/sudoers.d/soulguard.
+
+WORKDIR /app
+
+# Copy full monorepo
+COPY . .
+
+# Install deps
+RUN bun install --frozen-lockfile
+
+# Make CLI executable
+RUN chmod +x packages/core/src/cli.ts
+
+# Create soulguard command
+RUN printf '#!/bin/bash\nexec bun /app/packages/core/src/cli.ts "$@"\n' > /usr/local/bin/soulguard && \
+    chmod +x /usr/local/bin/soulguard
+
+# Default to root (simulates human/owner running setup)
+# Tests switch to agent via `su - agent -c "..."` for agent actions
+USER root

package/test-e2e/cases/approve-with-hash/expected.txt

@@ -0,0 +1,16 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+HASH: 0e94615ddc559fbd6541b0b002014ab8ee99df58d6ad360ba45e8510623a8990
+
+Approved 1 file(s):
+  ✅ SOUL.md
+
+Vault updated. Staging synced.
+VAULT:
+# My Updated Soul

package/test-e2e/cases/approve-with-hash/test.sh

@@ -0,0 +1,23 @@
+# Approve with --hash (non-interactive, implicit proposal)
+
+echo '# My Soul' > SOUL.md
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+# Agent modifies staging
+su - agent -c "echo '# My Updated Soul' > $(pwd)/.soulguard/staging/SOUL.md"
+
+# Get approval hash from diff output
+HASH=$(NO_COLOR=1 soulguard diff . 2>&1 | grep 'Approval hash:' | awk '{print $NF}')
+echo "HASH: $HASH"
+
+# Owner approves with hash
+soulguard approve . --hash "$HASH"
+
+# Verify vault has new content
+echo "VAULT:"
+cat SOUL.md

package/test-e2e/cases/diff-no-changes/expected.txt

@@ -0,0 +1,5 @@
+Soulguard Diff — /workspace
+
+  ✅ SOUL.md (no changes)
+
+No changes

package/test-e2e/cases/diff-no-changes/test.sh

@@ -0,0 +1,7 @@
+# Setup: create config, vault file, init — but don't modify staging
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+
+# Run diff — should show no changes
+soulguard diff .

package/test-e2e/cases/diff-no-staging/expected.txt

@@ -0,0 +1 @@
+No staging directory found. Run `soulguard init` first.

package/test-e2e/cases/diff-no-staging/test.sh

@@ -0,0 +1,6 @@
+# Setup: create config but do NOT init (no .soulguard/staging/)
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+
+# Run diff — should error about missing staging
+soulguard diff .

package/test-e2e/cases/diff-shows-changes/expected.txt

@@ -0,0 +1,13 @@
+Soulguard Diff — /workspace
+
+  📝 SOUL.md
+      ===================================================================
+      --- a/SOUL.md
+      +++ b/SOUL.md
+      @@ -1,1 +1,1 @@
+      -# My Soul
+      +# My Modified Soul
+      
+
+1 file(s) changed
+Approval hash: 3ef797046758a06b4f4cae5b20fdca383f4baff6ec653abe6b42597618a0b577

package/test-e2e/cases/diff-shows-changes/test.sh

@@ -0,0 +1,12 @@
+# Setup: create config, vault file, init + create staging with modification
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+
+# Create staging with modified copy
+mkdir -p .soulguard/staging
+cp SOUL.md .soulguard/staging/SOUL.md
+echo '# My Modified Soul' > .soulguard/staging/SOUL.md
+
+# Run diff
+soulguard diff .

package/test-e2e/cases/diff-vault-missing/expected.txt

@@ -0,0 +1,6 @@
+Soulguard Diff — /workspace
+
+  ⚠️ SOUL.md (vault file missing — new file)
+
+1 file(s) changed
+Approval hash: ddc1ac8615d0e23d031c518f50b17bacc02fd15e5e5cd1a6e2993978f50221a0

package/test-e2e/cases/diff-vault-missing/test.sh

@@ -0,0 +1,10 @@
+# Setup: create config, vault file, init — then delete the vault file
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+
+# Delete the vault file so staging exists but vault doesn't
+rm SOUL.md
+
+# Run diff — should show vault_missing status
+soulguard diff .

package/test-e2e/cases/glob-ledger-files/expected.txt

@@ -0,0 +1,52 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 3 vault file(s)
+
+Done.
+STATUS:
+Soulguard Status — /workspace
+
+Vault
+  ✅ soulguard.json
+
+Ledger
+  ✅ memory/2026-01-01.md
+  ✅ memory/2026-01-02.md
+
+3 files ok, 0 drifted, 0 missing
+STATUS AFTER DRIFT:
+Soulguard Status — /workspace
+
+Vault
+  ✅ soulguard.json
+
+Ledger
+  ⚠️  memory/2026-01-01.md
+      owner is root, expected agent
+      group is root, expected soulguard
+  ✅ memory/2026-01-02.md
+
+2 files ok, 1 drifted, 0 missing
+SYNC:
+Soulguard Sync — /workspace
+
+Fixed:
+  🔧 memory/2026-01-01.md
+      owner is root, expected agent
+      group is root, expected soulguard
+
+All files now ok.
+STATUS AFTER SYNC:
+Soulguard Status — /workspace
+
+Vault
+  ✅ soulguard.json
+
+Ledger
+  ✅ memory/2026-01-01.md
+  ✅ memory/2026-01-02.md
+
+3 files ok, 0 drifted, 0 missing

package/test-e2e/cases/glob-ledger-files/test.sh

@@ -0,0 +1,28 @@
+# Glob ledger files: ledger protects "memory/*.md" pattern.
+# Tests that glob patterns resolve to actual files in status and sync.
+
+# Setup: config with glob ledger pattern
+cat > soulguard.json <<'EOF'
+{"vault":["soulguard.json"],"ledger":["memory/*.md"]}
+EOF
+mkdir -p memory
+echo '# Day 1' > memory/2026-01-01.md
+echo '# Day 2' > memory/2026-01-02.md
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+echo "STATUS:"
+NO_COLOR=1 soulguard status . 2>&1
+
+# Simulate drift: wrong ownership on a ledger file
+chown root:root memory/2026-01-01.md
+
+echo "STATUS AFTER DRIFT:"
+NO_COLOR=1 soulguard status . 2>&1
+
+echo "SYNC:"
+soulguard sync . 2>&1
+
+echo "STATUS AFTER SYNC:"
+NO_COLOR=1 soulguard status . 2>&1

package/test-e2e/cases/glob-vault-files/expected.txt

@@ -0,0 +1,41 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 3 vault file(s)
+
+Done.
+STATUS:
+Soulguard Status — /workspace
+
+Vault
+  ✅ skills/python.md
+  ✅ skills/typescript.md
+  ✅ soulguard.json
+
+3 files ok, 0 drifted, 0 missing
+DIFF:
+Soulguard Diff — /workspace
+
+  📝 skills/python.md
+      ===================================================================
+      --- a/skills/python.md
+      +++ b/skills/python.md
+      @@ -1,1 +1,1 @@
+      -# Python
+      +# Python v2
+      
+  ✅ skills/typescript.md (no changes)
+  ✅ soulguard.json (no changes)
+
+1 file(s) changed
+Approval hash: dddd99b50cc6db47e3ab9cdcd8730fc93bb3eb4850bd5f2e01ad9c8a5b4a4dbb
+APPROVE:
+
+Approved 1 file(s):
+  ✅ skills/python.md
+
+Vault updated. Staging synced.
+VAULT CONTENT:
+# Python v2

package/test-e2e/cases/glob-vault-files/test.sh

@@ -0,0 +1,30 @@
+# Glob vault files: vault protects "skills/*.md" pattern.
+# Tests that glob patterns resolve to actual files in status, diff, and approve.
+
+# Setup: vault with glob + a couple matching files
+cat > soulguard.json <<'EOF'
+{"vault":["soulguard.json","skills/*.md"],"ledger":[]}
+EOF
+mkdir -p skills
+echo '# Python' > skills/python.md
+echo '# TypeScript' > skills/typescript.md
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+echo "STATUS:"
+NO_COLOR=1 soulguard status . 2>&1
+
+# Agent modifies a skill
+su - agent -c "echo '# Python v2' > $(pwd)/.soulguard/staging/skills/python.md"
+
+echo "DIFF:"
+NO_COLOR=1 soulguard diff . 2>&1
+
+# Approve the change
+HASH=$(NO_COLOR=1 soulguard diff . 2>&1 | grep 'Approval hash:' | awk '{print $NF}')
+echo "APPROVE:"
+soulguard approve . --hash "$HASH"
+
+echo "VAULT CONTENT:"
+cat skills/python.md

package/test-e2e/cases/init-blocked-by-agent/expected.txt

@@ -0,0 +1,11 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+--- AGENT TRIES INIT ---
+sudo: a terminal is required to read the password; either use the -S option to read from standard input or configure an askpass helper
+sudo: a password is required

package/test-e2e/cases/init-blocked-by-agent/test.sh

@@ -0,0 +1,15 @@
+# After owner runs init, agent can't run init again.
+# Init writes scoped sudoers that excludes init and approve.
+
+echo '# My Soul' > SOUL.md
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+
+# Owner runs init (as root)
+soulguard init . --agent-user agent
+
+echo "--- AGENT TRIES INIT ---"
+
+# Agent tries init — should be denied by scoped sudoers
+su - agent -c "sudo soulguard init $(pwd) --agent-user agent" 2>&1

package/test-e2e/cases/init-happy/expected.txt

@@ -0,0 +1,18 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+Soulguard Status — /workspace
+
+Vault
+  ✅ SOUL.md
+  ✅ soulguard.json
+
+2 files ok, 0 drifted, 0 missing
+.soulguard/staging/SOUL.md
+STAGING: OK
+-bash: line 1: /workspace/SOUL.md: Permission denied

package/test-e2e/cases/init-happy/test.sh

@@ -0,0 +1,20 @@
+# Init test: owner sets up workspace, verify protection works for agent
+# Runs as root (owner), switches to agent for verification
+
+# Create a minimal config and soul file
+echo '# My Soul' > SOUL.md
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+# Owner verifies status is clean
+soulguard status .
+
+# Verify staging copy exists
+ls .soulguard/staging/SOUL.md && echo "STAGING: OK" || echo "STAGING: MISSING"
+
+# Agent can't write to vault file
+su - agent -c "(echo hacked > $(pwd)/SOUL.md) 2>&1"

package/test-e2e/cases/init-idempotent/expected.txt

@@ -0,0 +1,13 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+--- SECOND RUN ---
+Soulguard Init — /workspace
+  Created .soulguard/staging/
+
+Done.

package/test-e2e/cases/init-idempotent/test.sh

@@ -0,0 +1,14 @@
+# Init twice: second run should report nothing to do
+
+echo '# My Soul' > SOUL.md
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+
+# First init (as owner/root)
+soulguard init . --agent-user agent
+
+echo "--- SECOND RUN ---"
+
+# Second init — should be idempotent
+soulguard init . --agent-user agent

package/test-e2e/cases/reset-staging/expected.txt

@@ -0,0 +1,16 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+Soulguard Reset — /workspace
+
+Reset 1 staging file(s):
+  ↩️  SOUL.md
+VAULT:
+# My Soul
+STAGING:
+# My Soul

package/test-e2e/cases/reset-staging/test.sh

@@ -0,0 +1,23 @@
+# Reset staging (implicit proposal)
+
+echo '# My Soul' > SOUL.md
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+# Agent modifies staging
+su - agent -c "echo '# Hacked Soul' > $(pwd)/.soulguard/staging/SOUL.md"
+
+# Owner resets staging
+soulguard reset .
+
+# Verify vault unchanged
+echo "VAULT:"
+cat SOUL.md
+
+# Verify staging reset
+echo "STAGING:"
+cat .soulguard/staging/SOUL.md

package/test-e2e/cases/self-protection-blocks-invalid/expected.txt

@@ -0,0 +1,12 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 2 vault file(s)
+
+Done.
+APPROVE:
+Self-protection: soulguard.json would be invalid after this change: ledger: Required
+CONFIG:
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}

package/test-e2e/cases/self-protection-blocks-invalid/test.sh

@@ -0,0 +1,25 @@
+# Self-protection: approve blocks invalid soulguard.json changes.
+# Even if the owner provides the correct hash, soulguard refuses to
+# brick itself by writing an invalid config.
+
+cat > soulguard.json <<'EOF'
+{"vault":["SOUL.md","soulguard.json"],"ledger":[]}
+EOF
+echo '# My Soul' > SOUL.md
+
+# Owner runs init
+soulguard init . --agent-user agent
+
+# Agent writes invalid config to staging (missing "ledger" field)
+su - agent -c "echo '{\"vault\":[\"SOUL.md\"]}' > $(pwd)/.soulguard/staging/soulguard.json"
+
+# Get hash — diff will show the change
+HASH=$(NO_COLOR=1 soulguard diff . 2>&1 | grep 'Approval hash:' | awk '{print $NF}')
+
+# Try to approve — should be blocked by self-protection
+echo "APPROVE:"
+soulguard approve . --hash "$HASH" 2>&1 || true
+
+# Verify soulguard.json is unchanged
+echo "CONFIG:"
+cat soulguard.json

package/test-e2e/cases/status-clean/expected.txt

@@ -0,0 +1,9 @@
+Soulguard Sync — /workspace
+
+Nothing to fix — all files ok.
+Soulguard Status — /workspace
+
+Vault
+  ✅ SOUL.md
+
+1 files ok, 0 drifted, 0 missing

package/test-e2e/cases/status-clean/test.sh

@@ -0,0 +1,8 @@
+# Setup: create config and vault file, init + sync (as owner)
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+soulguard sync .
+
+# Status check
+soulguard status .

package/test-e2e/cases/status-drifted/expected.txt

@@ -0,0 +1,9 @@
+Soulguard Status — /workspace
+
+Vault
+  ⚠️  SOUL.md
+      owner is root, expected soulguardian
+      group is root, expected soulguard
+      mode is 644, expected 444
+
+0 files ok, 1 drifted, 0 missing

package/test-e2e/cases/status-drifted/test.sh

@@ -0,0 +1,11 @@
+# Setup: create config and vault file, init for user/group but don't sync
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+
+# Simulate drift: reset ownership to root
+chown root:root SOUL.md
+chmod 644 SOUL.md
+
+# Status doesn't need sudo — it's read-only
+soulguard status .

package/test-e2e/cases/status-no-config/expected.txt

@@ -0,0 +1 @@
+No soulguard.json found in .

package/test-e2e/cases/status-no-config/test.sh

@@ -0,0 +1,2 @@
+# No soulguard.json → error
+soulguard status .

package/test-e2e/cases/sync-fix-drift/expected.txt

@@ -0,0 +1,15 @@
+Soulguard Sync — /workspace
+
+Fixed:
+  🔧 SOUL.md
+      owner is root, expected soulguardian
+      group is root, expected soulguard
+      mode is 644, expected 444
+
+All files now ok.
+Soulguard Status — /workspace
+
+Vault
+  ✅ SOUL.md
+
+1 files ok, 0 drifted, 0 missing

package/test-e2e/cases/sync-fix-drift/test.sh

@@ -0,0 +1,14 @@
+# Setup: create config and vault file, init for user/group
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+soulguard init . --agent-user agent > /dev/null 2>&1
+
+# Simulate drift: reset ownership to root
+chown root:root SOUL.md
+chmod 644 SOUL.md
+
+# Owner syncs to fix drift
+soulguard sync .
+
+# Verify status is clean after sync
+soulguard status .

package/test-e2e/cases/sync-no-sudo-clean/expected.txt

@@ -0,0 +1,11 @@
+Soulguard Init — /workspace
+  Created group: soulguard
+  Created user: soulguardian
+  Wrote /etc/sudoers.d/soulguard
+  Created .soulguard/staging/
+  Synced 1 vault file(s)
+
+Done.
+Soulguard Sync — /workspace
+
+Nothing to fix — all files ok.

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

@@ -0,0 +1,9 @@
+# After init, agent can sudo soulguard sync on a clean workspace
+echo '{"vault": ["SOUL.md"], "ledger": []}' > soulguard.json
+echo '# My Soul' > SOUL.md
+
+# Owner runs init (creates sudoers for agent)
+soulguard init . --agent-user agent
+
+# Agent syncs via scoped sudoers — workspace is already clean
+su - agent -c "sudo soulguard sync $(pwd)"

package/test-e2e/cases/sync-no-sudo-drift/expected.txt

@@ -0,0 +1,7 @@
+Soulguard Sync — /workspace
+
+Errors:
+  ❌ SOUL.md: chown failed (io_error)
+
+1 issue(s) remaining after sync:
+  ⚠️  SOUL.md