@soulguard/core 0.1.0

package/src/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared constants for soulguard.
+ */
+
+import type { FileOwnership, SoulguardConfig } from "./types.js";
+
+/** System user/group identity for soulguard */
+export const IDENTITY = { user: "soulguardian", group: "soulguard" } as const;
+
+/** Default vault file ownership */
+export const VAULT_OWNERSHIP: FileOwnership = {
+  user: IDENTITY.user,
+  group: IDENTITY.group,
+  mode: "444",
+} as const;
+
+/** Sensible default config — vaults soulguard's own config */
+export const DEFAULT_CONFIG: SoulguardConfig = {
+  vault: ["soulguard.json"],
+  ledger: [],
+} as const;

package/src/diff.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import { diff } from "./diff.js";
+import { MockSystemOps } from "./system-ops-mock.js";
+import type { SoulguardConfig } from "./types.js";
+
+const WORKSPACE = "/test/workspace";
+
+function makeMock() {
+  return new MockSystemOps(WORKSPACE);
+}
+
+function makeConfig(vault: string[] = ["SOUL.md"]): SoulguardConfig {
+  return { vault, ledger: [] };
+}
+
+describe("diff", () => {
+  test("no changes → all unchanged, hasChanges false", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.hasChanges).toBe(false);
+    expect(result.value.files).toHaveLength(1);
+    expect(result.value.files[0]!.status).toBe("unchanged");
+  });
+
+  test("modified file → shows diff, hasChanges true", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul\noriginal");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul\nmodified");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.hasChanges).toBe(true);
+    expect(result.value.files[0]!.status).toBe("modified");
+    expect(result.value.files[0]!.diff).toContain("-original");
+    expect(result.value.files[0]!.diff).toContain("+modified");
+  });
+
+  test("vault exists but staging deleted → deleted status", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.hasChanges).toBe(true);
+    expect(result.value.files[0]!.status).toBe("deleted");
+    expect(result.value.files[0]!.protectedHash).toBeDefined();
+    expect(result.value.approvalHash).toBeDefined();
+  });
+
+  test("neither vault nor staging exists → staging_missing status", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.files[0]!.status).toBe("staging_missing");
+  });
+
+  test("vault file missing → vault_missing status", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile(".soulguard/staging/SOUL.md", "# New Soul");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.hasChanges).toBe(true);
+    expect(result.value.files[0]!.status).toBe("vault_missing");
+  });
+
+  test("no staging dir → no_staging error", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul");
+
+    const result = await diff({ ops, config: makeConfig() });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("no_staging");
+  });
+
+  test("specific files filter works", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul");
+    ops.addFile("AGENTS.md", "# Agents");
+    ops.addFile(".soulguard/staging/AGENTS.md", "# Agents modified");
+
+    const config = makeConfig(["SOUL.md", "AGENTS.md"]);
+    const result = await diff({ ops, config, files: ["SOUL.md"] });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.files).toHaveLength(1);
+    expect(result.value.files[0]!.path).toBe("SOUL.md");
+  });
+
+  test("globs resolve to matching files", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul");
+    ops.addFile("memory/day1.md", "notes");
+    ops.addFile(".soulguard/staging/memory/day1.md", "notes");
+
+    const config = makeConfig(["SOUL.md", "memory/**"]);
+    const result = await diff({ ops, config });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.files).toHaveLength(2);
+    expect(result.value.files.map((f) => f.path)).toContain("SOUL.md");
+    expect(result.value.files.map((f) => f.path)).toContain("memory/day1.md");
+  });
+
+  test("approvalHash is present when changes exist", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "original");
+    ops.addFile(".soulguard/staging/SOUL.md", "modified");
+
+    const result = await diff({ ops, config: makeConfig() });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.approvalHash).toBeDefined();
+    expect(typeof result.value.approvalHash).toBe("string");
+    expect(result.value.approvalHash!.length).toBe(64); // SHA-256 hex
+  });
+
+  test("approvalHash is undefined when no changes", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "same");
+    ops.addFile(".soulguard/staging/SOUL.md", "same");
+
+    const result = await diff({ ops, config: makeConfig() });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.approvalHash).toBeUndefined();
+  });
+
+  test("approvalHash is deterministic", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "original");
+    ops.addFile(".soulguard/staging/SOUL.md", "modified");
+
+    const r1 = await diff({ ops, config: makeConfig() });
+    const r2 = await diff({ ops, config: makeConfig() });
+    expect(r1.ok && r2.ok).toBe(true);
+    if (r1.ok && r2.ok) {
+      expect(r1.value.approvalHash).toBe(r2.value.approvalHash);
+    }
+  });
+
+  test("approvalHash changes when staging content changes", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "original");
+    ops.addFile(".soulguard/staging/SOUL.md", "modified-v1");
+
+    const r1 = await diff({ ops, config: makeConfig() });
+
+    ops.addFile(".soulguard/staging/SOUL.md", "modified-v2");
+    const r2 = await diff({ ops, config: makeConfig() });
+
+    expect(r1.ok && r2.ok).toBe(true);
+    if (r1.ok && r2.ok) {
+      expect(r1.value.approvalHash).not.toBe(r2.value.approvalHash);
+    }
+  });
+});

package/src/diff.ts

@@ -0,0 +1,212 @@
+/**
+ * soulguard diff — compare vault files against their staging copies.
+ */
+
+import { createHash } from "node:crypto";
+import { createTwoFilesPatch } from "diff";
+import type { Result } from "./result.js";
+import { ok, err } from "./result.js";
+import type { SoulguardConfig } from "./types.js";
+import type { SystemOperations } from "./system-ops.js";
+import { resolvePatterns } from "./glob.js";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type FileDiff = {
+  path: string;
+  status: "modified" | "unchanged" | "vault_missing" | "staging_missing" | "deleted";
+  /** Unified diff string (only for modified) */
+  diff?: string;
+  protectedHash?: string;
+  stagedHash?: string;
+};
+
+export type DiffResult = {
+  files: FileDiff[];
+  hasChanges: boolean;
+  /**
+   * Approval hash — SHA-256 of all modified file paths + staged content hashes,
+   * sorted deterministically. Used for hash-based approve integrity check.
+   * Only present when there are changes.
+   */
+  approvalHash?: string;
+};
+
+export type DiffError =
+  | { kind: "no_staging" }
+  | { kind: "no_config" }
+  | { kind: "read_failed"; path: string; message: string };
+
+export type DiffOptions = {
+  ops: SystemOperations;
+  config: SoulguardConfig;
+  /** Specific files to diff (default: all vault files) */
+  files?: string[];
+};
+
+// ── Implementation ─────────────────────────────────────────────────────
+
+const STAGING_DIR = ".soulguard/staging";
+
+/**
+ * Compare vault files against their staging copies.
+ */
+export async function diff(options: DiffOptions): Promise<Result<DiffResult, DiffError>> {
+  const { ops, config, files: filterFiles } = options;
+
+  // Check staging directory exists
+  const stagingExists = await ops.exists(STAGING_DIR);
+  if (!stagingExists.ok) {
+    return err({ kind: "read_failed", path: STAGING_DIR, message: stagingExists.error.message });
+  }
+  if (!stagingExists.value) {
+    return err({ kind: "no_staging" });
+  }
+
+  // Resolve glob patterns to concrete file paths
+  const resolved = await resolvePatterns(ops, config.vault);
+  if (!resolved.ok) {
+    return err({ kind: "read_failed", path: "glob", message: resolved.error.message });
+  }
+  let vaultFiles = resolved.value;
+  if (filterFiles && filterFiles.length > 0) {
+    const filterSet = new Set(filterFiles);
+    vaultFiles = vaultFiles.filter((p) => filterSet.has(p));
+  }
+
+  const fileDiffs: FileDiff[] = [];
+
+  for (const path of vaultFiles) {
+    const stagingPath = `${STAGING_DIR}/${path}`;
+
+    const [vaultExists, stagingFileExists] = await Promise.all([
+      ops.exists(path),
+      ops.exists(stagingPath),
+    ]);
+
+    if (!vaultExists.ok) {
+      return err({ kind: "read_failed", path, message: vaultExists.error.message });
+    }
+    if (!stagingFileExists.ok) {
+      return err({
+        kind: "read_failed",
+        path: stagingPath,
+        message: stagingFileExists.error.message,
+      });
+    }
+
+    // Missing cases
+    if (vaultExists.value && !stagingFileExists.value) {
+      // Vault file exists but staging copy deleted → agent wants to delete this file
+      const vaultHash = await ops.hashFile(path);
+      fileDiffs.push({
+        path,
+        status: "deleted",
+        protectedHash: vaultHash.ok ? vaultHash.value : undefined,
+      });
+      continue;
+    }
+    if (!vaultExists.value && stagingFileExists.value) {
+      // New file — hash staging so it's covered by the approval hash
+      const newHash = await ops.hashFile(stagingPath);
+      fileDiffs.push({
+        path,
+        status: "vault_missing",
+        stagedHash: newHash.ok ? newHash.value : undefined,
+      });
+      continue;
+    }
+    if (!vaultExists.value && !stagingFileExists.value) {
+      fileDiffs.push({ path, status: "staging_missing" });
+      continue;
+    }
+
+    // Both exist — compare hashes
+    const [vaultHash, stagingHash] = await Promise.all([
+      ops.hashFile(path),
+      ops.hashFile(stagingPath),
+    ]);
+
+    if (!vaultHash.ok) {
+      return err({ kind: "read_failed", path, message: "hash failed" });
+    }
+    if (!stagingHash.ok) {
+      return err({ kind: "read_failed", path: stagingPath, message: "hash failed" });
+    }
+
+    if (vaultHash.value === stagingHash.value) {
+      fileDiffs.push({
+        path,
+        status: "unchanged",
+        protectedHash: vaultHash.value,
+        stagedHash: stagingHash.value,
+      });
+      continue;
+    }
+
+    // Modified — generate unified diff
+    const [vaultContent, stagingContent] = await Promise.all([
+      ops.readFile(path),
+      ops.readFile(stagingPath),
+    ]);
+
+    if (!vaultContent.ok) {
+      return err({ kind: "read_failed", path, message: "read failed" });
+    }
+    if (!stagingContent.ok) {
+      return err({ kind: "read_failed", path: stagingPath, message: "read failed" });
+    }
+
+    const unifiedDiff = createTwoFilesPatch(
+      `a/${path}`,
+      `b/${path}`,
+      vaultContent.value,
+      stagingContent.value,
+    );
+
+    fileDiffs.push({
+      path,
+      status: "modified",
+      diff: unifiedDiff,
+      protectedHash: vaultHash.value,
+      stagedHash: stagingHash.value,
+    });
+  }
+
+  const hasChanges = fileDiffs.some((f) => f.status !== "unchanged");
+
+  // Compute approval hash from modified files (deterministic)
+  let approvalHash: string | undefined;
+  if (hasChanges) {
+    approvalHash = computeApprovalHash(fileDiffs);
+  }
+
+  return ok({ files: fileDiffs, hasChanges, approvalHash });
+}
+
+/**
+ * Compute a deterministic approval hash from file diffs.
+ * Covers all modified files — sorted by path, hashing path + stagedHash pairs.
+ * This is the integrity token for hash-based approve.
+ */
+export function computeApprovalHash(files: FileDiff[]): string {
+  // Include modified, new (vault_missing), and deleted files in the hash
+  const actionable = files
+    .filter(
+      (f) =>
+        ((f.status === "modified" || f.status === "vault_missing") && f.stagedHash) ||
+        f.status === "deleted",
+    )
+    .sort((a, b) => a.path.localeCompare(b.path));
+
+  const hash = createHash("sha256");
+  for (const f of actionable) {
+    if (f.status === "deleted") {
+      // Use a sentinel for deletions — hash includes the vault hash to prevent replay
+      hash.update(`${f.path}\0DELETED\0${f.protectedHash ?? ""}\0`);
+    } else {
+      hash.update(`${f.path}\0${f.stagedHash}\0`);
+    }
+  }
+  return hash.digest("hex");
+}

package/src/git.test.ts

@@ -0,0 +1,180 @@
+import { describe, test, expect } from "bun:test";
+import { MockSystemOps } from "./system-ops-mock.js";
+import {
+  isGitEnabled,
+  gitCommit,
+  vaultCommitMessage,
+  ledgerCommitMessage,
+  commitLedgerFiles,
+} from "./git.js";
+
+describe("isGitEnabled", () => {
+  test("returns true when git not false and .git exists", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    expect(await isGitEnabled(ops, { vault: [], ledger: [] })).toBe(true);
+  });
+
+  test("returns true when git explicitly true", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    expect(await isGitEnabled(ops, { vault: [], ledger: [], git: true })).toBe(true);
+  });
+
+  test("returns false when git is false", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    expect(await isGitEnabled(ops, { vault: [], ledger: [], git: false })).toBe(false);
+  });
+
+  test("returns false when no .git directory", async () => {
+    const ops = new MockSystemOps("/workspace");
+    expect(await isGitEnabled(ops, { vault: [], ledger: [] })).toBe(false);
+  });
+});
+
+describe("gitCommit", () => {
+  test("stages files and commits when changes exist", async () => {
+    const ops = new MockSystemOps("/workspace");
+    // First diff --cached --quiet (pre-check) succeeds (no pre-existing staged changes)
+    // Second diff --cached --quiet (post-add) fails (= our files are staged)
+    ops.execFailOnCall.set("git diff --cached --quiet", new Set([1]));
+    const result = await gitCommit(ops, ["SOUL.md", "AGENTS.md"], "test commit");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.committed).toBe(true);
+    if (result.value.committed) {
+      expect(result.value.files).toEqual(["SOUL.md", "AGENTS.md"]);
+      expect(result.value.message).toBe("test commit");
+    }
+    const execOps = ops.ops.filter((op) => op.kind === "exec");
+    expect(execOps).toEqual([
+      { kind: "exec", command: "git", args: ["diff", "--cached", "--quiet"] },
+      { kind: "exec", command: "git", args: ["add", "--", "SOUL.md"] },
+      { kind: "exec", command: "git", args: ["add", "--", "AGENTS.md"] },
+      { kind: "exec", command: "git", args: ["diff", "--cached", "--quiet"] },
+      {
+        kind: "exec",
+        command: "git",
+        args: [
+          "commit",
+          "--author",
+          "SoulGuardian <soulguardian@soulguard.ai>",
+          "-m",
+          "test commit",
+        ],
+      },
+    ]);
+  });
+
+  test("returns nothing_staged when nothing to commit", async () => {
+    const ops = new MockSystemOps("/workspace");
+    const result = await gitCommit(ops, ["SOUL.md"], "test commit");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.committed).toBe(false);
+    if (!result.value.committed) {
+      expect(result.value.reason).toBe("nothing_staged");
+    }
+  });
+
+  test("returns dirty_staging when user has pre-existing staged changes", async () => {
+    const ops = new MockSystemOps("/workspace");
+    // Make the pre-check diff --cached --quiet fail (= there are staged changes)
+    ops.failingExecs.add("git diff --cached --quiet");
+    const result = await gitCommit(ops, ["SOUL.md"], "test commit");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.committed).toBe(false);
+    if (!result.value.committed) {
+      expect(result.value.reason).toBe("dirty_staging");
+    }
+    // Should NOT have called git add or git commit
+    const gitOps = ops.ops.filter((o) => o.kind === "exec" && o.command === "git");
+    expect(gitOps).toHaveLength(1); // only the diff check
+  });
+
+  test("returns no_files with empty files array", async () => {
+    const ops = new MockSystemOps("/workspace");
+    const result = await gitCommit(ops, [], "empty");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.committed).toBe(false);
+    if (!result.value.committed) {
+      expect(result.value.reason).toBe("no_files");
+    }
+  });
+});
+
+describe("commit messages", () => {
+  test("vaultCommitMessage with files only", () => {
+    expect(vaultCommitMessage(["SOUL.md"])).toBe("soulguard: vault update — SOUL.md");
+  });
+
+  test("vaultCommitMessage with approval message", () => {
+    expect(vaultCommitMessage(["SOUL.md", "AGENTS.md"], "identity refresh")).toBe(
+      "soulguard: vault update — SOUL.md, AGENTS.md\n\nidentity refresh",
+    );
+  });
+
+  test("ledgerCommitMessage", () => {
+    expect(ledgerCommitMessage()).toBe("soulguard: ledger sync");
+  });
+});
+
+describe("commitLedgerFiles", () => {
+  test("commits ledger files when git enabled and changes exist", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    // Pre-check succeeds (no pre-existing staged), post-add fails (= our files staged)
+    ops.execFailOnCall.set("git diff --cached --quiet", new Set([1]));
+
+    const result = await commitLedgerFiles(ops, {
+      vault: [],
+      ledger: ["MEMORY.md", "memory/*.md"],
+      git: true,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.committed).toBe(true);
+    if (result.value.committed) {
+      expect(result.value.message).toBe("soulguard: ledger sync");
+      // Globs are filtered out — only MEMORY.md staged
+      expect(result.value.files).toEqual(["MEMORY.md"]);
+    }
+  });
+
+  test("returns git_disabled when git not enabled", async () => {
+    const ops = new MockSystemOps("/workspace");
+    const result = await commitLedgerFiles(ops, { vault: [], ledger: ["MEMORY.md"], git: false });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toEqual({ committed: false, reason: "git_disabled" });
+  });
+
+  test("returns no_files when no ledger files", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    const result = await commitLedgerFiles(ops, { vault: [], ledger: [], git: true });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toEqual({ committed: false, reason: "no_files" });
+  });
+
+  test("returns no_files when only glob patterns", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile(".git", "");
+    const result = await commitLedgerFiles(ops, {
+      vault: [],
+      ledger: ["memory/*.md"],
+      git: true,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toEqual({ committed: false, reason: "no_files" });
+  });
+});