@soulguard/core 0.1.0

package/src/sync.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test } from "bun:test";
+import { sync } from "./sync.js";
+import { MockSystemOps } from "./system-ops-mock.js";
+
+const WORKSPACE = "/test/workspace";
+const VAULT_OWNERSHIP = { user: "soulguardian", group: "soulguard", mode: "444" };
+const LEDGER_OWNERSHIP = { user: "aster", group: "staff", mode: "644" };
+
+function makeMock() {
+  const ops = new MockSystemOps(WORKSPACE);
+  ops.addUser(VAULT_OWNERSHIP.user);
+  ops.addGroup(VAULT_OWNERSHIP.group);
+  return ops;
+}
+
+function opts(config: { vault: string[]; ledger: string[] }, ops: MockSystemOps) {
+  return {
+    config,
+    expectedVaultOwnership: VAULT_OWNERSHIP,
+    expectedLedgerOwnership: LEDGER_OWNERSHIP,
+    ops,
+  };
+}
+
+describe("sync", () => {
+  test("fixes unprotected vault files", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await sync(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Before had issues
+    expect(result.value.before.issues).toHaveLength(1);
+    // After is clean
+    expect(result.value.after.issues).toHaveLength(0);
+    expect(result.value.errors).toHaveLength(0);
+    expect(ops.ops).toHaveLength(2); // chown + chmod
+  });
+
+  test("no-op when already protected", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await sync(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.before.issues).toHaveLength(0);
+    expect(result.value.after.issues).toHaveLength(0);
+    expect(result.value.errors).toHaveLength(0);
+    expect(ops.ops).toHaveLength(0);
+  });
+
+  test("missing files remain in issues (can't fix)", async () => {
+    const ops = makeMock();
+
+    const result = await sync(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.before.issues).toHaveLength(1);
+    expect(result.value.after.issues).toHaveLength(1); // still missing
+    expect(result.value.errors).toHaveLength(0);
+  });
+
+  test("fixes only what needs fixing", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "644",
+    });
+
+    const result = await sync(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.after.issues).toHaveLength(0);
+    expect(ops.ops).toHaveLength(1); // only chmod
+  });
+
+  test("releases ledger files owned by soulguardian", async () => {
+    const ops = makeMock();
+    ops.addFile("notes.md", "# Notes", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await sync(opts({ vault: [], ledger: ["notes.md"] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.before.issues).toHaveLength(1);
+    expect(result.value.after.issues).toHaveLength(0);
+    expect(ops.ops).toHaveLength(2); // chown + chmod
+  });
+
+  test("handles multiple files across tiers", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", { owner: "agent", group: "staff", mode: "644" });
+    ops.addFile("AGENTS.md", "# Agents", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+    ops.addFile("notes.md", "# Notes", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await sync(opts({ vault: ["SOUL.md", "AGENTS.md"], ledger: ["notes.md"] }, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Before: SOUL.md drifted (vault), notes.md drifted (ledger)
+    expect(result.value.before.issues).toHaveLength(2);
+    // After: all clean
+    expect(result.value.after.issues).toHaveLength(0);
+    expect(result.value.errors).toHaveLength(0);
+  });
+
+  test("commits vault and ledger files to git when enabled", async () => {
+    const ops = makeMock();
+    ops.addFile(".git", "");
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+    ops.addFile("notes.md", "# Notes", {
+      owner: LEDGER_OWNERSHIP.user,
+      group: LEDGER_OWNERSHIP.group,
+      mode: LEDGER_OWNERSHIP.mode,
+    });
+
+    // Make post-add diff check fail (= files staged)
+    ops.execFailOnCall.set("git diff --cached --quiet", new Set([1]));
+
+    const result = await sync(
+      opts({ vault: ["SOUL.md"], ledger: ["notes.md"], git: true } as never, ops),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.git).toBeDefined();
+    expect(result.value.git?.committed).toBe(true);
+    if (result.value.git?.committed) {
+      expect(result.value.git.files).toEqual(["SOUL.md", "notes.md"]);
+    }
+  });
+
+  test("skips git commit when git disabled", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await sync(opts({ vault: ["SOUL.md"], ledger: [], git: false } as never, ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.git).toBeUndefined();
+  });
+});

package/src/sync.ts

@@ -0,0 +1,101 @@
+/**
+ * soulguard sync — fix all issues found by status.
+ *
+ * Runs status before and after applying fixes. The diff between
+ * before and after IS what happened. Errors are explicit.
+ */
+
+import type { DriftIssue, FileSystemError, IOError } from "./types.js";
+import { ok } from "./result.js";
+import type { Result } from "./result.js";
+import { status } from "./status.js";
+import type { StatusOptions, StatusResult } from "./status.js";
+import { isGitEnabled, gitCommit } from "./git.js";
+import type { GitCommitResult } from "./git.js";
+import { resolvePatterns } from "./glob.js";
+
+export type SyncError = {
+  path: string;
+  operation: string;
+  error: FileSystemError;
+};
+
+export type SyncResult = {
+  before: StatusResult;
+  after: StatusResult;
+  errors: SyncError[];
+  /** Git commit result (best-effort, only when git enabled) */
+  git?: GitCommitResult;
+};
+
+export type SyncOptions = StatusOptions;
+
+/**
+ * Run status, fix drifted files, run status again.
+ */
+export async function sync(options: SyncOptions): Promise<Result<SyncResult, IOError>> {
+  const { ops } = options;
+
+  const beforeResult = await status(options);
+  if (!beforeResult.ok) return beforeResult;
+  const before = beforeResult.value;
+
+  const errors: SyncError[] = [];
+
+  for (const issue of before.issues) {
+    if (issue.status !== "drifted") continue;
+
+    const expectedOwnership =
+      issue.tier === "vault" ? options.expectedVaultOwnership : options.expectedLedgerOwnership;
+
+    const path = issue.file.path;
+    const needsChown = issue.issues.some(
+      (i: DriftIssue) => i.kind === "wrong_owner" || i.kind === "wrong_group",
+    );
+    const needsChmod = issue.issues.some((i: DriftIssue) => i.kind === "wrong_mode");
+
+    if (needsChown) {
+      const { user, group } = expectedOwnership;
+      const result = await ops.chown(path, { user, group });
+      if (!result.ok) {
+        errors.push({ path, operation: "chown", error: result.error });
+        // Short-circuit: if chown fails, chmod will almost certainly fail too.
+        continue;
+      }
+    }
+
+    if (needsChmod) {
+      const result = await ops.chmod(path, expectedOwnership.mode);
+      if (!result.ok) {
+        errors.push({ path, operation: "chmod", error: result.error });
+        continue;
+      }
+    }
+  }
+
+  const afterResult = await status(options);
+  if (!afterResult.ok) return afterResult;
+  const after = afterResult.value;
+
+  // Best-effort git commit of all tracked files (vault + ledger)
+  let git: GitCommitResult | undefined;
+  if (await isGitEnabled(ops, options.config)) {
+    const [vaultResolved, ledgerResolved] = await Promise.all([
+      resolvePatterns(ops, options.config.vault),
+      resolvePatterns(ops, options.config.ledger),
+    ]);
+    const allFiles = [
+      ...(vaultResolved.ok ? vaultResolved.value : []),
+      ...(ledgerResolved.ok ? ledgerResolved.value : []),
+    ];
+    if (allFiles.length > 0) {
+      const gitResult = await gitCommit(ops, allFiles, "soulguard: sync");
+      if (gitResult.ok) {
+        git = gitResult.value;
+      }
+      // Git errors swallowed — best-effort
+    }
+  }
+
+  return ok({ before, after, errors, git });
+}

package/src/system-ops-mock.ts

@@ -0,0 +1,243 @@
+/**
+ * Mock SystemOperations for testing.
+ *
+ * Takes a workspace root; all paths are relative (resolved internally).
+ * Records all mutation operations for assertion.
+ */
+
+import { resolve } from "node:path";
+import type { FileStat, SystemOperations } from "./system-ops.js";
+import type { Result, NotFoundError, PermissionDeniedError, IOError } from "./types.js";
+import { matchGlob } from "./glob.js";
+import { ok, err } from "./result.js";
+
+/**
+ * Records what the mock *did*. Intentionally parallel to SyncAction
+ * (which records what sync *decided*) — they track different things.
+ */
+export type RecordedOp =
+  | { kind: "chown"; path: string; owner: { user: string; group: string } }
+  | { kind: "chmod"; path: string; mode: string }
+  | { kind: "exec"; command: string; args: string[] };
+
+type MockFile = {
+  content: string;
+  owner: string;
+  group: string;
+  mode: string;
+};
+
+export class MockSystemOps implements SystemOperations {
+  public readonly workspace: string;
+  private files: Map<string, MockFile> = new Map();
+  private users: Set<string> = new Set();
+  private groups: Set<string> = new Set();
+  public ops: RecordedOp[] = [];
+  /** Commands that should fail (for testing error paths). Key: "command arg1 arg2" */
+  public failingExecs: Set<string> = new Set();
+  public failingDeletes: Set<string> = new Set();
+  /** Per-command call counters for execFailAfter/execFailBefore */
+  private execCallCounts: Map<string, number> = new Map();
+  /**
+   * Commands that should fail only on the Nth call (0-indexed).
+   * Key: "command arg1 arg2", Value: set of call indices that should fail.
+   */
+  public execFailOnCall: Map<string, Set<number>> = new Map();
+
+  constructor(workspace: string) {
+    this.workspace = workspace;
+  }
+
+  private resolve(path: string): string {
+    return resolve(this.workspace, path);
+  }
+
+  /** Add a simulated file (relative path) */
+  addFile(
+    path: string,
+    content: string,
+    opts: { owner?: string; group?: string; mode?: string } = {},
+  ): void {
+    this.files.set(this.resolve(path), {
+      content,
+      owner: opts.owner ?? "unknown",
+      group: opts.group ?? "unknown",
+      mode: opts.mode ?? "644",
+    });
+  }
+
+  /** Add a simulated system user */
+  addUser(name: string): void {
+    this.users.add(name);
+  }
+
+  /** Add a simulated system group */
+  addGroup(name: string): void {
+    this.groups.add(name);
+  }
+
+  async userExists(name: string): Promise<Result<boolean, IOError>> {
+    return ok(this.users.has(name));
+  }
+
+  async groupExists(name: string): Promise<Result<boolean, IOError>> {
+    return ok(this.groups.has(name));
+  }
+
+  async stat(
+    path: string,
+  ): Promise<Result<FileStat, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    const file = this.files.get(full);
+    if (!file) return err({ kind: "not_found", path });
+    return ok({
+      path,
+      ownership: { user: file.owner, group: file.group, mode: file.mode },
+    });
+  }
+
+  async chown(
+    path: string,
+    owner: { user: string; group: string },
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    const file = this.files.get(full);
+    if (!file) return err({ kind: "not_found", path });
+    this.ops.push({ kind: "chown", path, owner });
+    file.owner = owner.user;
+    file.group = owner.group;
+    return ok(undefined);
+  }
+
+  async chmod(
+    path: string,
+    mode: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    const file = this.files.get(full);
+    if (!file) return err({ kind: "not_found", path });
+    this.ops.push({ kind: "chmod", path, mode });
+    file.mode = mode;
+    return ok(undefined);
+  }
+
+  async readFile(
+    path: string,
+  ): Promise<Result<string, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    const file = this.files.get(full);
+    if (!file) return err({ kind: "not_found", path });
+    return ok(file.content);
+  }
+
+  async createUser(name: string, _group: string): Promise<Result<void, IOError>> {
+    this.users.add(name);
+    return ok(undefined);
+  }
+
+  async createGroup(name: string): Promise<Result<void, IOError>> {
+    this.groups.add(name);
+    return ok(undefined);
+  }
+
+  async writeFile(
+    path: string,
+    content: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    this.files.set(full, { content, owner: "agent", group: "staff", mode: "644" });
+    return ok(undefined);
+  }
+
+  async mkdir(
+    path: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    // Track directory and all parent dirs as entries (mirrors recursive mkdir)
+    const full = this.resolve(path);
+    if (!this.files.has(full)) {
+      this.files.set(full, { content: "", owner: "root", group: "root", mode: "755" });
+    }
+    // Also create parent directories
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i++) {
+      const parent = parts.slice(0, i).join("/");
+      const parentFull = this.resolve(parent);
+      if (!this.files.has(parentFull)) {
+        this.files.set(parentFull, { content: "", owner: "root", group: "root", mode: "755" });
+      }
+    }
+    return ok(undefined);
+  }
+
+  async copyFile(
+    src: string,
+    dest: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const fullSrc = this.resolve(src);
+    const file = this.files.get(fullSrc);
+    if (!file) return err({ kind: "not_found", path: src });
+    const fullDest = this.resolve(dest);
+    this.files.set(fullDest, { ...file });
+    return ok(undefined);
+  }
+
+  async exists(path: string): Promise<Result<boolean, IOError>> {
+    const full = this.resolve(path);
+    return ok(this.files.has(full));
+  }
+
+  async deleteFile(
+    path: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    if (this.failingDeletes.has(path) || this.failingDeletes.has(full)) {
+      return err({ kind: "permission_denied", path, operation: "unlink" });
+    }
+    if (!this.files.has(full)) return err({ kind: "not_found", path });
+    this.files.delete(full);
+    return ok(undefined);
+  }
+
+  async hashFile(
+    path: string,
+  ): Promise<Result<string, NotFoundError | PermissionDeniedError | IOError>> {
+    const full = this.resolve(path);
+    const file = this.files.get(full);
+    if (!file) return err({ kind: "not_found", path });
+    const hash = new Bun.CryptoHasher("sha256");
+    hash.update(file.content);
+    return ok(hash.digest("hex"));
+  }
+
+  async glob(pattern: string): Promise<Result<string[], IOError>> {
+    // Simple glob matching against mock filesystem
+    const prefix = this.workspace + "/";
+    const matches: string[] = [];
+
+    for (const fullPath of this.files.keys()) {
+      if (!fullPath.startsWith(prefix)) continue;
+      const relPath = fullPath.slice(prefix.length);
+      if (matchGlob(pattern, relPath)) {
+        matches.push(relPath);
+      }
+    }
+
+    return ok(matches.sort());
+  }
+
+  async exec(command: string, args: string[]): Promise<Result<void, IOError>> {
+    this.ops.push({ kind: "exec", command, args });
+    const key = [command, ...args].join(" ");
+    if (this.failingExecs.has(key)) {
+      return err({ kind: "io_error", path: "", message: `${key} failed` });
+    }
+    // Support call-index-specific failures
+    const callIndex = this.execCallCounts.get(key) ?? 0;
+    this.execCallCounts.set(key, callIndex + 1);
+    const failIndices = this.execFailOnCall.get(key);
+    if (failIndices?.has(callIndex)) {
+      return err({ kind: "io_error", path: "", message: `${key} failed` });
+    }
+    return ok(undefined);
+  }
+}

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

@@ -0,0 +1,183 @@
+/**
+ * Tests for NodeSystemOps — local tests that don't require root.
+ *
+ * Tests stat, readFile, hashFile, chmod (on own files), userExists, groupExists.
+ * chown tests require root and live in the Docker integration suite.
+ */
+
+import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { NodeSystemOps } from "./system-ops-node.js";
+
+let workspace: string;
+let ops: NodeSystemOps;
+
+beforeEach(async () => {
+  workspace = await mkdtemp(join(tmpdir(), "soulguard-test-"));
+  ops = new NodeSystemOps(workspace);
+});
+
+afterEach(async () => {
+  await rm(workspace, { recursive: true, force: true });
+});
+
+describe("NodeSystemOps", () => {
+  // ── stat ────────────────────────────────────────────────────────────
+
+  describe("stat", () => {
+    test("returns ownership info for existing file", async () => {
+      await writeFile(join(workspace, "test.md"), "hello");
+
+      const result = await ops.stat("test.md");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      expect(result.value.path).toBe("test.md");
+      expect(result.value.ownership.user).toBeTruthy();
+      expect(result.value.ownership.group).toBeTruthy();
+      expect(result.value.ownership.mode).toMatch(/^\d{3}$/);
+    });
+
+    test("returns not_found for missing file", async () => {
+      const result = await ops.stat("nope.md");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("not_found");
+    });
+
+    test("rejects path traversal", async () => {
+      const result = await ops.stat("../../etc/passwd");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("io_error");
+    });
+
+    test("handles nested paths", async () => {
+      await mkdir(join(workspace, "sub"), { recursive: true });
+      await writeFile(join(workspace, "sub", "nested.md"), "deep");
+
+      const result = await ops.stat("sub/nested.md");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value.path).toBe("sub/nested.md");
+    });
+  });
+
+  // ── readFile ────────────────────────────────────────────────────────
+
+  describe("readFile", () => {
+    test("reads file contents", async () => {
+      await writeFile(join(workspace, "test.md"), "hello world");
+
+      const result = await ops.readFile("test.md");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe("hello world");
+    });
+
+    test("returns not_found for missing file", async () => {
+      const result = await ops.readFile("nope.md");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("not_found");
+    });
+
+    test("rejects path traversal", async () => {
+      const result = await ops.readFile("../../etc/passwd");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("io_error");
+    });
+  });
+
+  // ── hashFile ────────────────────────────────────────────────────────
+
+  describe("hashFile", () => {
+    test("returns correct SHA-256 hash", async () => {
+      const content = "hello world";
+      await writeFile(join(workspace, "test.md"), content);
+
+      const expected = createHash("sha256").update(content).digest("hex");
+
+      const result = await ops.hashFile("test.md");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(expected);
+    });
+
+    test("returns not_found for missing file", async () => {
+      const result = await ops.hashFile("nope.md");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("not_found");
+    });
+  });
+
+  // ── chmod ───────────────────────────────────────────────────────────
+
+  describe("chmod", () => {
+    test("changes file permissions", async () => {
+      await writeFile(join(workspace, "test.md"), "hello");
+
+      const result = await ops.chmod("test.md", "444");
+      expect(result.ok).toBe(true);
+
+      const stat = await ops.stat("test.md");
+      expect(stat.ok).toBe(true);
+      if (!stat.ok) return;
+      expect(stat.value.ownership.mode).toBe("444");
+
+      // Restore so cleanup works
+      await ops.chmod("test.md", "644");
+    });
+
+    test("returns not_found for missing file", async () => {
+      const result = await ops.chmod("nope.md", "444");
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.error.kind).toBe("not_found");
+    });
+  });
+
+  // ── userExists ──────────────────────────────────────────────────────
+
+  describe("userExists", () => {
+    test("returns true for current user", async () => {
+      const currentUser = process.env.USER ?? "root";
+      const result = await ops.userExists(currentUser);
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(true);
+    });
+
+    test("returns false for nonexistent user", async () => {
+      const result = await ops.userExists("soulguard_nonexistent_user_xyz");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(false);
+    });
+  });
+
+  // ── groupExists ─────────────────────────────────────────────────────
+
+  describe("groupExists", () => {
+    test("returns true for staff group", async () => {
+      // 'staff' exists on macOS, 'root' on Linux
+      const group = process.platform === "darwin" ? "staff" : "root";
+      const result = await ops.groupExists(group);
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(true);
+    });
+
+    test("returns false for nonexistent group", async () => {
+      const result = await ops.groupExists("soulguard_nonexistent_group_xyz");
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toBe(false);
+    });
+  });
+});