@soulguard/core 0.1.0

package/src/approve.ts

@@ -0,0 +1,352 @@
+/**
+ * soulguard approve — apply staging changes to vault files.
+ *
+ * Implicit proposal model: staging IS the proposal. At approval time:
+ * 1. Compute diff to find modified files
+ * 2. Copy modified staging files to protected .soulguard/pending/
+ * 3. Hash the frozen pending copies and verify against reviewer's hash
+ * 4. Backup current vault files
+ * 5. Apply from pending copies, re-protect vault files
+ * 6. Sync staging, cleanup
+ *
+ * The protected copy step eliminates timing attacks — once files are in
+ * .soulguard/pending/ (owned by soulguardian), the agent cannot modify them.
+ * The hash is verified against these frozen copies, not the live staging dir.
+ */
+
+import type { SystemOperations } from "./system-ops.js";
+import type { FileOwnership, SoulguardConfig, Result } from "./types.js";
+import { diff, computeApprovalHash } from "./diff.js";
+import type { FileDiff } from "./diff.js";
+import { ok, err } from "./result.js";
+import type { GitCommitResult } from "./git.js";
+import { isGitEnabled, gitCommit, vaultCommitMessage } from "./git.js";
+import type { Policy, ApprovalContext } from "./policy.js";
+import { validatePolicies, evaluatePolicies } from "./policy.js";
+import { validateSelfProtection } from "./self-protection.js";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type ApproveOptions = {
+  ops: SystemOperations;
+  config: SoulguardConfig;
+  /** SHA-256 approval hash — must match computed hash of frozen pending copies */
+  hash: string;
+  /** Expected vault ownership to restore after writing */
+  vaultOwnership: FileOwnership;
+  /** Ownership for staging copies after sync (agent-writable) */
+  stagingOwnership?: FileOwnership;
+  /** Named policy hooks — all evaluated before applying changes.
+   *  Duplicate policy names are rejected with policy_name_collision error. */
+  policies?: Policy[];
+};
+
+/** Errors from approve. */
+export type ApprovalError =
+  | { kind: "no_changes" }
+  | { kind: "hash_mismatch"; message: string }
+  | { kind: "self_protection"; message: string }
+  | { kind: "policy_violation"; violations: Array<{ policy: string; message: string }> }
+  | { kind: "policy_name_collision"; duplicates: string[] }
+  | { kind: "apply_failed"; message: string }
+  | { kind: "diff_failed"; message: string };
+
+export type ApproveResult = {
+  /** Files that were updated */
+  appliedFiles: string[];
+  /** Git commit result (undefined if git not enabled) */
+  gitResult?: GitCommitResult;
+};
+
+/**
+ * Approve and apply staging changes to vault.
+ */
+export async function approve(
+  options: ApproveOptions,
+): Promise<Result<ApproveResult, ApprovalError>> {
+  const { ops, config, hash, vaultOwnership, policies } = options;
+
+  // ── Phase 0: Validate policy names (fail fast on collisions) ────────
+  if (policies && policies.length > 0) {
+    const validation = validatePolicies(policies);
+    if (!validation.ok) {
+      return err(validation.error);
+    }
+  }
+
+  // ── Phase 1: Compute diff to find changed files ────────────────────
+  const diffResult = await diff({ ops, config });
+  if (!diffResult.ok) {
+    return err({ kind: "diff_failed", message: diffResult.error.kind });
+  }
+
+  if (!diffResult.value.hasChanges) {
+    return err({ kind: "no_changes" });
+  }
+
+  // Files that need to be applied (modified, new, or deleted)
+  const changedFiles = diffResult.value.files.filter(
+    (f) => f.status === "modified" || f.status === "vault_missing" || f.status === "deleted",
+  );
+
+  // ── Phase 2: Copy staging to protected working dir ─────────────────
+  // Once in .soulguard/pending/ (owned by soulguardian), the agent cannot
+  // modify these files. This freezes the content before we verify the hash.
+  await ops.mkdir(".soulguard/pending");
+  for (const file of changedFiles.filter((f) => f.status !== "deleted")) {
+    const copyResult = await ops.copyFile(
+      `.soulguard/staging/${file.path}`,
+      `.soulguard/pending/${file.path}`,
+    );
+    if (!copyResult.ok) {
+      await cleanupPending(ops, changedFiles);
+      return err({ kind: "apply_failed", message: `Cannot copy staging/${file.path} to pending` });
+    }
+  }
+
+  // Protect the pending dir so agent can't tamper during approval
+  // TODO: chown recursively (needs ops interface change — tracked upstack)
+  const chownPending = await ops.chown(".soulguard/pending", vaultOwnership);
+  if (!chownPending.ok) {
+    await cleanupPending(ops, changedFiles);
+    return err({ kind: "apply_failed", message: "Cannot protect pending directory" });
+  }
+
+  // ── Phase 3: Hash the frozen pending copies and verify ─────────────
+  // Compute the approval hash from the now-protected pending files.
+  // This is the authoritative check — if the agent modified staging between
+  // the diff and the copy, the pending hash won't match the reviewer's hash.
+  const pendingHash = await computePendingHash(ops, changedFiles);
+  if (!pendingHash.ok) {
+    await cleanupPending(ops, changedFiles);
+    return err({ kind: "apply_failed", message: pendingHash.error });
+  }
+
+  if (pendingHash.value !== hash) {
+    await cleanupPending(ops, changedFiles);
+    return err({
+      kind: "hash_mismatch",
+      message: `Expected hash ${hash} but got hash ${pendingHash.value}`,
+    });
+  }
+
+  // ── Phase 3a: Read all pending file contents (used by self-protection + policies) ──
+  const pendingContents = new Map<string, string>();
+  for (const file of changedFiles.filter((f) => f.status !== "deleted")) {
+    const content = await ops.readFile(`.soulguard/pending/${file.path}`);
+    if (!content.ok) {
+      await cleanupPending(ops, changedFiles);
+      return err({
+        kind: "apply_failed",
+        message: `Cannot read pending/${file.path}`,
+      });
+    }
+    pendingContents.set(file.path, content.value);
+  }
+
+  // ── Phase 3b: Built-in self-protection (hardcoded, cannot be bypassed) ──
+  {
+    const selfCheck = validateSelfProtection(
+      pendingContents,
+      changedFiles.filter((f) => f.status === "deleted"),
+    );
+    if (!selfCheck.ok) {
+      await cleanupPending(ops, changedFiles);
+      return err(selfCheck.error);
+    }
+  }
+
+  // ── Phase 3c: Run user-provided policy hooks against frozen content ──
+  if (policies && policies.length > 0) {
+    const ctx: ApprovalContext = new Map();
+    for (const file of changedFiles) {
+      if (file.status === "deleted") {
+        const vaultContent = await ops.readFile(file.path);
+        ctx.set(file.path, {
+          final: "",
+          diff: `File deleted: ${file.path}`,
+          previous: vaultContent.ok ? vaultContent.value : "",
+        });
+      } else {
+        let previous = "";
+        if (file.status === "modified") {
+          const vaultContent = await ops.readFile(file.path);
+          if (vaultContent.ok) {
+            previous = vaultContent.value;
+          }
+        }
+        ctx.set(file.path, {
+          final: pendingContents.get(file.path)!,
+          diff: file.diff ?? "",
+          previous,
+        });
+      }
+    }
+
+    const policyResult = await evaluatePolicies(policies, ctx);
+    if (!policyResult.ok) {
+      await cleanupPending(ops, changedFiles);
+      return err(policyResult.error);
+    }
+  }
+
+  // ── Phase 4: Backup all affected vault files ───────────────────────
+  const backedUpFiles: string[] = [];
+  await ops.mkdir(".soulguard/backup");
+  for (const file of changedFiles) {
+    // Only backup files that exist in vault (skip new files)
+    if (file.status === "vault_missing") continue;
+    const backupResult = await ops.copyFile(file.path, `.soulguard/backup/${file.path}`);
+    if (!backupResult.ok) {
+      await cleanupBackup(ops, backedUpFiles);
+      await cleanupPending(ops, changedFiles);
+      return err({ kind: "apply_failed", message: `Backup of ${file.path} failed` });
+    }
+    backedUpFiles.push(file.path);
+  }
+
+  // ── Phase 5: Apply changes ─────────────────────────────────────────
+  const appliedFiles: string[] = [];
+
+  for (const file of changedFiles) {
+    if (file.status === "deleted") {
+      // Delete vault file
+      const deleteResult = await ops.deleteFile(file.path);
+      if (!deleteResult.ok) {
+        await rollback(ops, changedFiles, appliedFiles, backedUpFiles, vaultOwnership);
+        return err({
+          kind: "apply_failed",
+          message: `Cannot delete ${file.path}: ${deleteResult.error.kind}`,
+        });
+      }
+    } else {
+      // Write content from pending
+      const content = await ops.readFile(`.soulguard/pending/${file.path}`);
+      if (!content.ok) {
+        await rollback(ops, changedFiles, appliedFiles, backedUpFiles, vaultOwnership);
+        return err({ kind: "apply_failed", message: `Cannot read pending/${file.path}` });
+      }
+
+      const writeResult = await ops.writeFile(file.path, content.value);
+      if (!writeResult.ok) {
+        await rollback(ops, changedFiles, appliedFiles, backedUpFiles, vaultOwnership);
+        return err({
+          kind: "apply_failed",
+          message: `Cannot write ${file.path}: ${writeResult.error.kind}`,
+        });
+      }
+
+      // Re-protect
+      const chownResult = await ops.chown(file.path, vaultOwnership);
+      if (!chownResult.ok) {
+        await rollback(ops, changedFiles, appliedFiles, backedUpFiles, vaultOwnership);
+        return err({
+          kind: "apply_failed",
+          message: `Cannot chown ${file.path}: ${chownResult.error.kind}`,
+        });
+      }
+
+      const chmodResult = await ops.chmod(file.path, vaultOwnership.mode);
+      if (!chmodResult.ok) {
+        await rollback(ops, changedFiles, appliedFiles, backedUpFiles, vaultOwnership);
+        return err({
+          kind: "apply_failed",
+          message: `Cannot chmod ${file.path}: ${chmodResult.error.kind}`,
+        });
+      }
+    }
+    appliedFiles.push(file.path);
+  }
+
+  // ── Phase 6: Sync staging copies + cleanup ─────────────────────────
+  for (const file of changedFiles.filter((f) => f.status !== "deleted")) {
+    const stagingPath = `.soulguard/staging/${file.path}`;
+    await ops.copyFile(file.path, stagingPath);
+    if (options.stagingOwnership) {
+      await ops.chown(stagingPath, options.stagingOwnership);
+      await ops.chmod(stagingPath, options.stagingOwnership.mode);
+    }
+  }
+  // Deleted files: staging copy is already gone (that's how we detected the deletion)
+
+  // Clean up backup and pending
+  await cleanupBackup(ops, backedUpFiles);
+  await cleanupPending(ops, changedFiles);
+
+  // ── Git auto-commit (best-effort) ──────────────────────────────────
+  let gitResult: GitCommitResult | undefined;
+  if (await isGitEnabled(ops, config)) {
+    const message = vaultCommitMessage(appliedFiles);
+    const result = await gitCommit(ops, appliedFiles, message);
+    if (result.ok) {
+      gitResult = result.value;
+    }
+    // Git failures are swallowed — vault update already succeeded
+  }
+
+  return ok({ appliedFiles, gitResult });
+}
+
+/**
+ * Compute approval hash from frozen pending copies.
+ * Reuses computeApprovalHash from diff.ts for a single hash algorithm.
+ */
+async function computePendingHash(
+  ops: SystemOperations,
+  changedFiles: FileDiff[],
+): Promise<Result<string, string>> {
+  const withHashes: FileDiff[] = [];
+  for (const f of changedFiles) {
+    if (f.status === "deleted") {
+      // Deleted files pass through — they use protectedHash from the vault file
+      withHashes.push(f);
+    } else {
+      const fileHash = await ops.hashFile(`.soulguard/pending/${f.path}`);
+      if (!fileHash.ok) {
+        return err(`Cannot hash pending/${f.path}`);
+      }
+      withHashes.push({ ...f, stagedHash: fileHash.value });
+    }
+  }
+  return ok(computeApprovalHash(withHashes));
+}
+
+/**
+ * Clean up pending directory on early exit.
+ */
+async function cleanupPending(ops: SystemOperations, files: FileDiff[]): Promise<void> {
+  for (const file of files) {
+    await ops.deleteFile(`.soulguard/pending/${file.path}`);
+  }
+}
+
+/**
+ * Clean up backup files.
+ */
+async function cleanupBackup(ops: SystemOperations, backedUpFiles: string[]): Promise<void> {
+  for (const filePath of backedUpFiles) {
+    await ops.deleteFile(`.soulguard/backup/${filePath}`);
+  }
+}
+
+/**
+ * Rollback: restore vault files from backups after a partial apply failure.
+ */
+async function rollback(
+  ops: SystemOperations,
+  changedFiles: FileDiff[],
+  appliedFiles: string[],
+  backedUpFiles: string[],
+  vaultOwnership: FileOwnership,
+): Promise<void> {
+  for (const filePath of appliedFiles) {
+    const backupContent = await ops.readFile(`.soulguard/backup/${filePath}`);
+    if (backupContent.ok) {
+      await ops.writeFile(filePath, backupContent.value);
+      await ops.chown(filePath, vaultOwnership);
+      await ops.chmod(filePath, vaultOwnership.mode);
+    }
+  }
+  await cleanupBackup(ops, backedUpFiles);
+  await cleanupPending(ops, changedFiles);
+}

package/src/cli/approve-command.ts

@@ -0,0 +1,107 @@
+/**
+ * ApproveCommand — approve and apply staging changes to vault.
+ *
+ * Two modes:
+ * - `--hash <hash>`: Non-interactive, verifies hash and applies.
+ * - No args: Interactive — shows diff, prompts for confirmation, then applies.
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { ApproveOptions } from "../approve.js";
+import { approve } from "../approve.js";
+import { diff } from "../diff.js";
+
+export type ApproveCommandOptions = Omit<ApproveOptions, "hash"> & {
+  /** Pre-computed hash for non-interactive mode */
+  hash?: string;
+  /** Prompt function for interactive mode (returns true if user confirms) */
+  prompt?: () => Promise<boolean>;
+};
+
+export class ApproveCommand {
+  constructor(
+    private opts: ApproveCommandOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    let hash = this.opts.hash;
+
+    // Interactive mode: show diff, compute hash, prompt
+    if (!hash) {
+      const diffResult = await diff({ ops: this.opts.ops, config: this.opts.config });
+      if (!diffResult.ok) {
+        this.out.error(`Diff failed: ${diffResult.error.kind}`);
+        return 1;
+      }
+      if (!diffResult.value.hasChanges) {
+        this.out.info("No changes to approve — staging matches vault.");
+        return 0;
+      }
+
+      // Show diff
+      this.out.heading(`Soulguard Approve — ${this.opts.ops.workspace}`);
+      this.out.write("");
+      for (const file of diffResult.value.files) {
+        if (file.status === "modified" && file.diff) {
+          this.out.write(file.diff);
+        }
+      }
+      this.out.write("");
+      this.out.info(`Approval hash: ${diffResult.value.approvalHash}`);
+      this.out.write("");
+
+      // Prompt
+      if (this.opts.prompt) {
+        const confirmed = await this.opts.prompt();
+        if (!confirmed) {
+          this.out.info("Cancelled.");
+          return 0;
+        }
+      }
+
+      hash = diffResult.value.approvalHash!;
+    }
+
+    const result = await approve({ ...this.opts, hash });
+
+    if (!result.ok) {
+      switch (result.error.kind) {
+        case "no_changes":
+          this.out.info("No changes to approve — staging matches vault.");
+          return 0;
+        case "hash_mismatch":
+          this.out.error(result.error.message);
+          this.out.info("Please run `soulguard diff` again and re-review.");
+          return 1;
+        case "self_protection":
+          this.out.error(`Self-protection: ${result.error.message}`);
+          return 1;
+        case "policy_violation":
+          this.out.error("Blocked by policy:");
+          for (const v of result.error.violations) {
+            this.out.error(`  ✗ ${v.policy}: ${v.message}`);
+          }
+          return 1;
+        case "policy_name_collision":
+          this.out.error(`Duplicate policy names: ${result.error.duplicates.join(", ")}`);
+          return 1;
+        case "apply_failed":
+          this.out.error(`Apply failed: ${result.error.message}`);
+          return 1;
+        case "diff_failed":
+          this.out.error(`Diff failed: ${result.error.message}`);
+          return 1;
+      }
+    }
+
+    this.out.write("");
+    this.out.success(`Approved ${result.value.appliedFiles.length} file(s):`);
+    for (const file of result.value.appliedFiles) {
+      this.out.success(`  ✅ ${file}`);
+    }
+    this.out.write("");
+    this.out.info("Vault updated. Staging synced.");
+    return 0;
+  }
+}

package/src/cli/diff-command.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import { DiffCommand } from "./diff-command.js";
+import { MockSystemOps } from "../system-ops-mock.js";
+import { MockConsoleOutput } from "../console-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("DiffCommand", () => {
+  test("no changes → exit 0, output contains 'No changes'", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul");
+
+    const out = new MockConsoleOutput();
+    const cmd = new DiffCommand({ ops, config: makeConfig() }, out);
+    const exitCode = await cmd.execute();
+
+    expect(exitCode).toBe(0);
+    expect(out.hasText("No changes")).toBe(true);
+  });
+
+  test("modified file → exit 1, output contains diff", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul\noriginal");
+    ops.addFile(".soulguard/staging/SOUL.md", "# Soul\nmodified");
+
+    const out = new MockConsoleOutput();
+    const cmd = new DiffCommand({ ops, config: makeConfig() }, out);
+    const exitCode = await cmd.execute();
+
+    expect(exitCode).toBe(1);
+    expect(out.hasText("📝 SOUL.md")).toBe(true);
+    expect(out.hasText("-original")).toBe(true);
+    expect(out.hasText("+modified")).toBe(true);
+    expect(out.hasText("1 file(s) changed")).toBe(true);
+  });
+
+  test("deleted file → exit 1, output contains deletion marker", async () => {
+    const ops = makeMock();
+    ops.addFile(".soulguard/staging", "");
+    ops.addFile("SOUL.md", "# Soul");
+
+    const out = new MockConsoleOutput();
+    const cmd = new DiffCommand({ ops, config: makeConfig() }, out);
+    const exitCode = await cmd.execute();
+
+    expect(exitCode).toBe(1);
+    expect(out.hasText("staged for deletion")).toBe(true);
+  });
+});

package/src/cli/diff-command.ts

@@ -0,0 +1,81 @@
+/**
+ * DiffCommand — pretty-prints the result of `diff()`.
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { DiffOptions } from "../diff.js";
+import { diff } from "../diff.js";
+
+export class DiffCommand {
+  constructor(
+    private options: DiffOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    const result = await diff(this.options);
+
+    if (!result.ok) {
+      switch (result.error.kind) {
+        case "no_staging":
+          this.out.error("No staging directory found. Run `soulguard init` first.");
+          return 1;
+        case "no_config":
+          this.out.error("No soulguard.json found.");
+          return 1;
+        case "read_failed":
+          this.out.error(`Failed to read ${result.error.path}: ${result.error.message}`);
+          return 1;
+      }
+    }
+
+    const { files, hasChanges } = result.value;
+
+    this.out.heading(`Soulguard Diff — ${this.options.ops.workspace}`);
+    this.out.write("");
+
+    let changeCount = 0;
+
+    for (const file of files) {
+      switch (file.status) {
+        case "unchanged":
+          this.out.info(`  ✅ ${file.path} (no changes)`);
+          break;
+        case "modified":
+          changeCount++;
+          this.out.warn(`  📝 ${file.path}`);
+          if (file.diff) {
+            for (const line of file.diff.split("\n")) {
+              this.out.write(`      ${line}`);
+            }
+          }
+          break;
+        case "staging_missing":
+          changeCount++;
+          this.out.warn(`  ⚠️ ${file.path} (no staging copy)`);
+          break;
+        case "vault_missing":
+          changeCount++;
+          this.out.warn(`  ⚠️ ${file.path} (vault file missing — new file)`);
+          break;
+        case "deleted":
+          changeCount++;
+          this.out.warn(`  🗑️ ${file.path} (staged for deletion)`);
+          break;
+      }
+    }
+
+    this.out.write("");
+    if (hasChanges) {
+      this.out.info(`${changeCount} file(s) changed`);
+      if (result.value.approvalHash) {
+        this.out.info(`Approval hash: ${result.value.approvalHash}`);
+      }
+    } else {
+      this.out.info("No changes");
+    }
+
+    // Exit 1 = differences found (matching `git diff` convention), not an error.
+    return hasChanges ? 1 : 0;
+  }
+}

package/src/cli/init-command.ts

@@ -0,0 +1,83 @@
+/**
+ * CLI command: soulguard init
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { InitOptions, InitResult, InitError } from "../init.js";
+import type { Result } from "../types.js";
+import { init } from "../init.js";
+
+export type InitCommandOptions = {
+  initOptions: InitOptions;
+  out: ConsoleOutput;
+};
+
+export class InitCommand {
+  constructor(
+    private options: InitOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    const result: Result<InitResult, InitError> = await init(this.options);
+
+    if (!result.ok) {
+      const e = result.error;
+      switch (e.kind) {
+        case "not_root":
+          this.out.error("soulguard init requires root. Run with sudo.");
+          break;
+        case "group_creation_failed":
+          this.out.error(`Failed to create group: ${e.message}`);
+          break;
+        case "user_creation_failed":
+          this.out.error(`Failed to create user: ${e.message}`);
+          break;
+        case "config_write_failed":
+          this.out.error(`Failed to write config: ${e.message}`);
+          break;
+        case "sudoers_write_failed":
+          this.out.error(`Failed to write sudoers: ${e.message}`);
+          break;
+        case "staging_failed":
+          this.out.error(`Failed to create staging: ${e.message}`);
+          break;
+      }
+      return 1;
+    }
+
+    const r = result.value;
+    this.out.heading(`Soulguard Init — ${this.options.ops.workspace}`);
+
+    const steps: string[] = [];
+    if (r.groupCreated) steps.push("Created group: soulguard");
+    if (r.userCreated) steps.push("Created user: soulguardian");
+    if (r.configCreated) steps.push("Wrote soulguard.json");
+    if (r.sudoersCreated) steps.push("Wrote /etc/sudoers.d/soulguard");
+    if (r.stagingCreated) steps.push("Created .soulguard/staging/");
+    if (steps.length > 0) {
+      for (const step of steps) {
+        this.out.success(`  ${step}`);
+      }
+    }
+
+    // Report sync results
+    const fixed = r.syncResult.before.issues.length - r.syncResult.after.issues.length;
+    if (fixed > 0) {
+      this.out.success(`  Synced ${fixed} vault file(s)`);
+    }
+
+    const remaining = r.syncResult.after.issues.length;
+    if (remaining > 0) {
+      this.out.warn(`  ${remaining} issue(s) remaining after sync`);
+    }
+
+    if (steps.length === 0 && fixed === 0) {
+      this.out.info("Already initialized — nothing to do.");
+    } else {
+      this.out.success("\nDone.");
+    }
+
+    return remaining > 0 ? 1 : 0;
+  }
+}