@soulguard/core 0.1.0

package/src/schema.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { parseConfig } from "./schema.js";
+
+describe("soulguardConfigSchema", () => {
+  test("parses valid config", () => {
+    const config = parseConfig({
+      vault: ["SOUL.md", "AGENTS.md"],
+      ledger: ["memory/**"],
+    });
+    expect(config.vault).toEqual(["SOUL.md", "AGENTS.md"]);
+    expect(config.ledger).toEqual(["memory/**"]);
+  });
+
+  test("rejects missing vault", () => {
+    expect(() => parseConfig({ ledger: [] })).toThrow();
+  });
+
+  test("rejects missing ledger", () => {
+    expect(() => parseConfig({ vault: [] })).toThrow();
+  });
+
+  test("accepts empty arrays", () => {
+    const config = parseConfig({ vault: [], ledger: [] });
+    expect(config.vault).toEqual([]);
+    expect(config.ledger).toEqual([]);
+  });
+});

package/src/schema.ts

@@ -0,0 +1,22 @@
+/**
+ * Soulguard config schema — runtime validation via Zod.
+ *
+ * The canonical type is SoulguardConfig in types.ts.
+ * This schema validates against it at compile time via z.ZodType<T>.
+ */
+
+import { z } from "zod";
+import type { SoulguardConfig } from "./types.js";
+
+export const soulguardConfigSchema: z.ZodType<SoulguardConfig> = z.object({
+  vault: z.array(z.string()),
+  ledger: z.array(z.string()),
+  git: z.boolean().optional(),
+});
+
+/**
+ * Parse and validate a soulguard.json config object.
+ */
+export function parseConfig(raw: unknown): SoulguardConfig {
+  return soulguardConfigSchema.parse(raw);
+}

package/src/self-protection.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from "bun:test";
+import { MockSystemOps } from "./system-ops-mock.js";
+import { diff } from "./diff.js";
+import { approve } from "./approve.js";
+import type { SoulguardConfig, FileOwnership } from "./types.js";
+
+const vaultOwnership: FileOwnership = { user: "soulguardian", group: "soulguard", mode: "444" };
+
+async function getApprovalHash(ops: MockSystemOps, config: SoulguardConfig): Promise<string> {
+  const result = await diff({ ops, config });
+  if (!result.ok) throw new Error("diff failed");
+  return result.value.approvalHash!;
+}
+
+describe("self-protection", () => {
+  test("blocks invalid JSON in soulguard.json", async () => {
+    const config: SoulguardConfig = { vault: ["soulguard.json"], ledger: [] };
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("soulguard.json", '{"vault":["soulguard.json"],"ledger":[]}', {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile(".soulguard/staging", "", { owner: "root", group: "root", mode: "755" });
+    ops.addFile(".soulguard/staging/soulguard.json", "not valid json {{{", {
+      owner: "agent",
+      group: "soulguard",
+      mode: "644",
+    });
+
+    const hash = await getApprovalHash(ops, config);
+    const result = await approve({ ops, config, hash, vaultOwnership });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("self_protection");
+    if (result.error.kind === "self_protection") {
+      expect(result.error.message).toContain("not be valid JSON");
+    }
+  });
+
+  test("blocks invalid schema in soulguard.json", async () => {
+    const config: SoulguardConfig = { vault: ["soulguard.json"], ledger: [] };
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("soulguard.json", '{"vault":["soulguard.json"],"ledger":[]}', {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile(".soulguard/staging", "", { owner: "root", group: "root", mode: "755" });
+    // Missing ledger field
+    ops.addFile(".soulguard/staging/soulguard.json", '{"vault":["soulguard.json"]}', {
+      owner: "agent",
+      group: "soulguard",
+      mode: "644",
+    });
+
+    const hash = await getApprovalHash(ops, config);
+    const result = await approve({ ops, config, hash, vaultOwnership });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("self_protection");
+    if (result.error.kind === "self_protection") {
+      expect(result.error.message).toContain("invalid after this change");
+    }
+  });
+
+  test("allows valid soulguard.json changes", async () => {
+    const config: SoulguardConfig = { vault: ["soulguard.json"], ledger: [] };
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("soulguard.json", '{"vault":["soulguard.json"],"ledger":[]}', {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile(".soulguard/staging", "", { owner: "root", group: "root", mode: "755" });
+    ops.addFile(
+      ".soulguard/staging/soulguard.json",
+      '{"vault":["soulguard.json","SOUL.md"],"ledger":["memory/**"]}',
+      { owner: "agent", group: "soulguard", mode: "644" },
+    );
+
+    const hash = await getApprovalHash(ops, config);
+    const result = await approve({ ops, config, hash, vaultOwnership });
+    expect(result.ok).toBe(true);
+  });
+
+  test("does not run when soulguard.json is not being changed", async () => {
+    const config: SoulguardConfig = { vault: ["SOUL.md", "soulguard.json"], ledger: [] };
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "original", {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile("soulguard.json", '{"vault":["SOUL.md","soulguard.json"],"ledger":[]}', {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile(".soulguard/staging", "", { owner: "root", group: "root", mode: "755" });
+    ops.addFile(".soulguard/staging/SOUL.md", "modified", {
+      owner: "agent",
+      group: "soulguard",
+      mode: "644",
+    });
+    ops.addFile(
+      ".soulguard/staging/soulguard.json",
+      '{"vault":["SOUL.md","soulguard.json"],"ledger":[]}',
+      { owner: "agent", group: "soulguard", mode: "644" },
+    );
+
+    const hash = await getApprovalHash(ops, config);
+    const result = await approve({ ops, config, hash, vaultOwnership });
+    expect(result.ok).toBe(true);
+  });
+
+  test("self-protection cannot be bypassed with empty policies", async () => {
+    const config: SoulguardConfig = { vault: ["soulguard.json"], ledger: [] };
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("soulguard.json", '{"vault":["soulguard.json"],"ledger":[]}', {
+      owner: "soulguardian",
+      group: "soulguard",
+      mode: "444",
+    });
+    ops.addFile(".soulguard/staging", "", { owner: "root", group: "root", mode: "755" });
+    ops.addFile(".soulguard/staging/soulguard.json", "not json", {
+      owner: "agent",
+      group: "soulguard",
+      mode: "644",
+    });
+
+    const hash = await getApprovalHash(ops, config);
+    // Explicitly pass empty policies — self-protection still runs
+    const result = await approve({ ops, config, hash, vaultOwnership, policies: [] });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.kind).toBe("self_protection");
+  });
+});

package/src/self-protection.ts

@@ -0,0 +1,63 @@
+/**
+ * Built-in self-protection for soulguard approve.
+ *
+ * These checks are HARDCODED and run on every approval — they cannot be
+ * bypassed by passing an empty policies array. This prevents soulguard
+ * from being bricked through its own approval flow.
+ *
+ * Current checks:
+ * - soulguard.json cannot be deleted
+ * - If soulguard.json is being changed, the new content must be valid config
+ */
+
+import type { Result } from "./types.js";
+import type { ApprovalError } from "./approve.js";
+import type { FileDiff } from "./diff.js";
+import { soulguardConfigSchema } from "./schema.js";
+import { ok, err } from "./result.js";
+
+/**
+ * Validate built-in self-protection rules against pending changes.
+ * Takes a map of path → content for content files, and a list of deleted files.
+ * Returns an ApprovalError if any check fails.
+ */
+export function validateSelfProtection(
+  pendingContents: Map<string, string>,
+  deletedFiles: FileDiff[] = [],
+): Result<void, ApprovalError> {
+  // Block deletion of soulguard.json — config must always exist
+  if (deletedFiles.some((f) => f.path === "soulguard.json")) {
+    return err({
+      kind: "self_protection",
+      message: "Cannot delete soulguard.json — it is required for soulguard to function",
+    });
+  }
+
+  const sgContent = pendingContents.get("soulguard.json");
+  if (sgContent === undefined) {
+    return ok(undefined);
+  }
+
+  // Parse as JSON
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(sgContent);
+  } catch {
+    return err({
+      kind: "self_protection",
+      message: "soulguard.json would not be valid JSON after this change",
+    });
+  }
+
+  // Validate against config schema
+  const result = soulguardConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+    return err({
+      kind: "self_protection",
+      message: `soulguard.json would be invalid after this change: ${issues}`,
+    });
+  }
+
+  return ok(undefined);
+}

package/src/status.test.ts

@@ -0,0 +1,241 @@
+import { describe, expect, test } from "bun:test";
+import { status } from "./status.js";
+import { MockSystemOps } from "./system-ops-mock.js";
+import type { FileStatus } from "./status.js";
+import { formatIssue } from "./types.js";
+import type { DriftIssue } from "./types.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("status", () => {
+  test("reports ok when vault file is correct", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.vault).toHaveLength(1);
+    expect(result.value.vault[0]!.status).toBe("ok");
+    expect(result.value.issues).toHaveLength(0);
+  });
+
+  test("reports drifted with semantic issues when vault file has wrong owner", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: "agent",
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.vault[0]! as FileStatus & { status: "drifted" };
+    expect(file.status).toBe("drifted");
+    expect(file.issues).toContainEqual({
+      kind: "wrong_owner",
+      expected: VAULT_OWNERSHIP.user,
+      actual: "agent",
+    });
+    expect(result.value.issues).toHaveLength(1);
+  });
+
+  test("reports drifted when vault file has wrong mode", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "644",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.vault[0]! as FileStatus & { status: "drifted" };
+    expect(file.status).toBe("drifted");
+    expect(file.issues).toContainEqual({
+      kind: "wrong_mode",
+      expected: "444",
+      actual: "644",
+    });
+  });
+
+  test("reports missing vault files", async () => {
+    const ops = makeMock();
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.vault[0]!.status).toBe("missing");
+    expect(result.value.issues).toHaveLength(1);
+  });
+
+  test("includes hashes in FileInfo for ok files", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.vault[0]! as FileStatus & { status: "ok" };
+    expect(file.file.hash).toMatch(/^[a-f0-9]{64}$/);
+  });
+
+  test("resolves glob patterns to matching files", async () => {
+    const ops = makeMock();
+    ops.addFile("memory/day1.md", "notes", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: VAULT_OWNERSHIP.mode,
+    });
+    ops.addFile("skills/python.md", "skill", {
+      owner: LEDGER_OWNERSHIP.user,
+      group: LEDGER_OWNERSHIP.group,
+      mode: LEDGER_OWNERSHIP.mode,
+    });
+
+    const result = await status(opts({ vault: ["memory/**"], ledger: ["skills/**"] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.vault).toHaveLength(1);
+    expect(result.value.vault[0]!.status).toBe("ok");
+    expect(result.value.ledger).toHaveLength(1);
+    expect(result.value.ledger[0]!.status).toBe("ok");
+    expect(result.value.issues).toHaveLength(0);
+  });
+
+  test("glob with no matches returns empty", async () => {
+    const ops = makeMock();
+
+    const result = await status(opts({ vault: ["memory/**"], ledger: ["skills/**"] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.vault).toHaveLength(0);
+    expect(result.value.ledger).toHaveLength(0);
+  });
+
+  test("reports multiple semantic issues on same file", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: "agent",
+      group: "staff",
+      mode: "777",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: [] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.vault[0]! as FileStatus & { status: "drifted" };
+    expect(file.issues).toHaveLength(3);
+    expect(file.issues.map((i) => i.kind)).toEqual(["wrong_owner", "wrong_group", "wrong_mode"]);
+  });
+
+  test("issues array contains all problems from both tiers", async () => {
+    const ops = makeMock();
+    ops.addFile("SOUL.md", "# Soul", {
+      owner: "agent",
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await status(opts({ vault: ["SOUL.md"], ledger: ["notes.md"] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.issues).toHaveLength(2);
+  });
+
+  test("ledger ok files include FileInfo", async () => {
+    const ops = makeMock();
+    ops.addFile("notes.md", "# Notes", {
+      owner: LEDGER_OWNERSHIP.user,
+      group: LEDGER_OWNERSHIP.group,
+      mode: "644",
+    });
+
+    const result = await status(opts({ vault: [], ledger: ["notes.md"] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.ledger[0]! as FileStatus & { status: "ok" };
+    expect(file.status).toBe("ok");
+    expect(file.file.hash).toMatch(/^[a-f0-9]{64}$/);
+    expect(file.file.ownership.user).toBe(LEDGER_OWNERSHIP.user);
+  });
+
+  test("ledger file owned by guardian reports drift", async () => {
+    const ops = makeMock();
+    ops.addFile("notes.md", "# Notes", {
+      owner: VAULT_OWNERSHIP.user,
+      group: VAULT_OWNERSHIP.group,
+      mode: "444",
+    });
+
+    const result = await status(opts({ vault: [], ledger: ["notes.md"] }, ops));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const file = result.value.ledger[0]! as FileStatus & { status: "drifted" };
+    expect(file.status).toBe("drifted");
+    expect(file.issues).toContainEqual({
+      kind: "wrong_owner",
+      expected: LEDGER_OWNERSHIP.user,
+      actual: VAULT_OWNERSHIP.user,
+    });
+  });
+
+  test("formatIssue produces readable strings", () => {
+    const issues: DriftIssue[] = [
+      { kind: "wrong_owner", expected: "soulguardian", actual: "agent" },
+      { kind: "wrong_mode", expected: "444", actual: "644" },
+    ];
+    expect(formatIssue(issues[0]!)).toBe("owner is agent, expected soulguardian");
+    expect(formatIssue(issues[1]!)).toBe("mode is 644, expected 444");
+  });
+});

package/src/status.ts

@@ -0,0 +1,114 @@
+/**
+ * soulguard status — report the current protection state of a workspace.
+ */
+
+import type {
+  SoulguardConfig,
+  FileInfo,
+  FileOwnership,
+  Tier,
+  DriftIssue,
+  FileSystemError,
+  IOError,
+  Result,
+} from "./types.js";
+import { ok } from "./result.js";
+import type { SystemOperations } from "./system-ops.js";
+import { getFileInfo } from "./system-ops.js";
+import { resolvePatterns } from "./glob.js";
+
+// ── File status ────────────────────────────────────────────────────────
+
+export type FileStatus =
+  | { tier: Tier; status: "ok"; file: FileInfo }
+  | { tier: Tier; status: "drifted"; file: FileInfo; issues: DriftIssue[] }
+  | { tier: Tier; status: "missing"; path: string }
+  | { tier: Tier; status: "error"; path: string; error: FileSystemError };
+
+export type StatusResult = {
+  vault: FileStatus[];
+  ledger: FileStatus[];
+  /** All non-ok statuses from both tiers, for convenience */
+  issues: FileStatus[];
+};
+
+export type StatusOptions = {
+  config: SoulguardConfig;
+  /** Expected ownership for vault files (e.g. soulguardian:soulguard 444) */
+  expectedVaultOwnership: FileOwnership;
+  /** Expected ownership for ledger files (e.g. agent:staff 644) */
+  expectedLedgerOwnership: FileOwnership;
+  ops: SystemOperations;
+};
+
+/**
+ * Check the protection status of all configured files.
+ */
+export async function status(options: StatusOptions): Promise<Result<StatusResult, IOError>> {
+  const { config, expectedVaultOwnership, expectedLedgerOwnership, ops } = options;
+
+  // Resolve glob patterns to concrete file paths
+  const [vaultResult, ledgerResult] = await Promise.all([
+    resolvePatterns(ops, config.vault),
+    resolvePatterns(ops, config.ledger),
+  ]);
+  if (!vaultResult.ok) return vaultResult;
+  if (!ledgerResult.ok) return ledgerResult;
+  const vaultPaths = vaultResult.value;
+  const ledgerPaths = ledgerResult.value;
+
+  const [vault, ledger] = await Promise.all([
+    Promise.all(vaultPaths.map((path) => checkPath(path, "vault", expectedVaultOwnership, ops))),
+    Promise.all(ledgerPaths.map((path) => checkPath(path, "ledger", expectedLedgerOwnership, ops))),
+  ]);
+
+  const issues = [...vault, ...ledger].filter((f) => f.status !== "ok");
+
+  return ok({ vault, ledger, issues });
+}
+
+async function checkPath(
+  filePath: string,
+  tier: Tier,
+  expectedOwnership: FileOwnership,
+  ops: SystemOperations,
+): Promise<FileStatus> {
+  const infoResult = await getFileInfo(filePath, ops);
+
+  if (!infoResult.ok) {
+    if (infoResult.error.kind === "not_found") {
+      return { tier, status: "missing", path: filePath };
+    }
+    return { tier, status: "error", path: filePath, error: infoResult.error };
+  }
+
+  const file = infoResult.value;
+  const issues: DriftIssue[] = [];
+
+  if (file.ownership.user !== expectedOwnership.user) {
+    issues.push({
+      kind: "wrong_owner",
+      expected: expectedOwnership.user,
+      actual: file.ownership.user,
+    });
+  }
+  if (file.ownership.group !== expectedOwnership.group) {
+    issues.push({
+      kind: "wrong_group",
+      expected: expectedOwnership.group,
+      actual: file.ownership.group,
+    });
+  }
+  if (file.ownership.mode !== expectedOwnership.mode) {
+    issues.push({
+      kind: "wrong_mode",
+      expected: expectedOwnership.mode,
+      actual: file.ownership.mode,
+    });
+  }
+
+  if (issues.length === 0) {
+    return { tier, status: "ok", file };
+  }
+  return { tier, status: "drifted", file, issues };
+}