@soulguard/core 0.1.0

package/src/git.ts

@@ -0,0 +1,131 @@
+/**
+ * Git integration helpers for soulguard.
+ *
+ * Provides auto-commit functionality for vault and ledger changes.
+ * All operations are best-effort — git failures never block core operations.
+ */
+
+import type { SystemOperations } from "./system-ops.js";
+import type { SoulguardConfig, Result } from "./types.js";
+import { ok, err } from "./result.js";
+import { resolvePatterns } from "./glob.js";
+
+export type GitCommitResult =
+  | { committed: true; message: string; files: string[] }
+  | { committed: false; reason: "git_disabled" | "no_files" | "nothing_staged" | "dirty_staging" };
+
+export type GitError = { kind: "git_error"; message: string };
+
+/**
+ * Check if git is enabled and a repo exists.
+ */
+export async function isGitEnabled(
+  ops: SystemOperations,
+  config: SoulguardConfig,
+): Promise<boolean> {
+  if (config.git === false) return false;
+  const gitExists = await ops.exists(".git");
+  return gitExists.ok && gitExists.value;
+}
+
+/**
+ * Stage specific files and commit.
+ *
+ * Handles both modified and deleted files (git add stages deletions).
+ * Returns ok with committed=false if there's nothing to commit.
+ */
+export async function gitCommit(
+  ops: SystemOperations,
+  files: string[],
+  message: string,
+): Promise<Result<GitCommitResult, GitError>> {
+  if (files.length === 0) {
+    return ok({ committed: false, reason: "no_files" });
+  }
+
+  // Check for pre-existing staged changes — refuse to commit if the user
+  // has something staged, so we don't absorb their work into a soulguard commit.
+  const preCheck = await ops.exec("git", ["diff", "--cached", "--quiet"]);
+  if (!preCheck.ok) {
+    // exit code 1 = there are staged changes already
+    return ok({ committed: false, reason: "dirty_staging" });
+  }
+
+  // Stage each file individually
+  for (const file of files) {
+    const result = await ops.exec("git", ["add", "--", file]);
+    if (!result.ok) {
+      return err({ kind: "git_error", message: `git add ${file}: ${result.error.message}` });
+    }
+  }
+
+  // Check if there's actually anything staged
+  // exit code 0 = nothing staged, exit code 1 = changes staged
+  const diffResult = await ops.exec("git", ["diff", "--cached", "--quiet"]);
+  if (diffResult.ok) {
+    // Nothing staged — files were already committed or unchanged
+    return ok({ committed: false, reason: "nothing_staged" });
+  }
+
+  // Commit with soulguard author
+  const commitResult = await ops.exec("git", [
+    "commit",
+    "--author",
+    "SoulGuardian <soulguardian@soulguard.ai>",
+    "-m",
+    message,
+  ]);
+  if (!commitResult.ok) {
+    return err({ kind: "git_error", message: `git commit: ${commitResult.error.message}` });
+  }
+
+  return ok({ committed: true, message, files });
+}
+
+/**
+ * Build a human-readable commit message for vault changes.
+ */
+export function vaultCommitMessage(files: string[], approvalMessage?: string): string {
+  const fileList = files.join(", ");
+  const base = `soulguard: vault update — ${fileList}`;
+  if (approvalMessage) {
+    return `${base}\n\n${approvalMessage}`;
+  }
+  return base;
+}
+
+/**
+ * Build a human-readable commit message for ledger changes.
+ * Uses a generic message since we stage all ledger files and let
+ * git determine which actually changed.
+ */
+export function ledgerCommitMessage(): string {
+  return "soulguard: ledger sync";
+}
+
+/**
+ * Commit all ledger files to git (best-effort).
+ *
+ * Stages all resolved ledger files and commits if anything changed.
+ * Note: `sync` now also commits all tracked files (vault + ledger).
+ * This function is still useful for targeted ledger-only commits.
+ */
+export async function commitLedgerFiles(
+  ops: SystemOperations,
+  config: SoulguardConfig,
+): Promise<Result<GitCommitResult, GitError>> {
+  if (!(await isGitEnabled(ops, config))) {
+    return ok({ committed: false, reason: "git_disabled" });
+  }
+
+  const resolved = await resolvePatterns(ops, config.ledger);
+  if (!resolved.ok) {
+    return err({ kind: "git_error", message: `glob failed: ${resolved.error.message}` });
+  }
+  const ledgerFiles = resolved.value;
+  if (ledgerFiles.length === 0) {
+    return ok({ committed: false, reason: "no_files" });
+  }
+
+  return gitCommit(ops, ledgerFiles, ledgerCommitMessage());
+}

package/src/glob.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import { isGlob, matchGlob, createGlobMatcher } from "./glob.js";
+
+describe("isGlob", () => {
+  test("returns true for patterns with *", () => {
+    expect(isGlob("*.md")).toBe(true);
+    expect(isGlob("memory/*.md")).toBe(true);
+    expect(isGlob("**/*.ts")).toBe(true);
+  });
+
+  test("returns false for literal paths", () => {
+    expect(isGlob("SOUL.md")).toBe(false);
+    expect(isGlob("memory/2026-01-01.md")).toBe(false);
+  });
+});
+
+describe("matchGlob", () => {
+  test("* matches single segment", () => {
+    expect(matchGlob("*.md", "SOUL.md")).toBe(true);
+    expect(matchGlob("*.md", "README.md")).toBe(true);
+    expect(matchGlob("*.md", "src/SOUL.md")).toBe(false);
+    expect(matchGlob("*.ts", "SOUL.md")).toBe(false);
+  });
+
+  test("* in directory", () => {
+    expect(matchGlob("memory/*.md", "memory/day1.md")).toBe(true);
+    expect(matchGlob("memory/*.md", "memory/deep/day1.md")).toBe(false);
+    expect(matchGlob("memory/*.md", "other/day1.md")).toBe(false);
+  });
+
+  test("** matches any depth", () => {
+    expect(matchGlob("src/**", "src/a.ts")).toBe(true);
+    expect(matchGlob("src/**", "src/deep/a.ts")).toBe(true);
+    expect(matchGlob("src/**", "other/a.ts")).toBe(false);
+  });
+
+  test("**/*.ext matches files at any depth", () => {
+    expect(matchGlob("**/*.md", "README.md")).toBe(true);
+    expect(matchGlob("**/*.md", "docs/guide.md")).toBe(true);
+    expect(matchGlob("**/*.md", "deep/nested/file.md")).toBe(true);
+    expect(matchGlob("**/*.md", "file.ts")).toBe(false);
+  });
+
+  test("/**/  matches zero or more directories", () => {
+    // src/**/*.ts should match src/main.ts (zero intermediate dirs)
+    expect(matchGlob("src/**/*.ts", "src/main.ts")).toBe(true);
+    // and also deeper paths
+    expect(matchGlob("src/**/*.ts", "src/utils/math.ts")).toBe(true);
+    expect(matchGlob("src/**/*.ts", "src/a/b/c.ts")).toBe(true);
+    // but not non-matching
+    expect(matchGlob("src/**/*.ts", "test/main.ts")).toBe(false);
+  });
+
+  test("exact match for non-glob patterns", () => {
+    expect(matchGlob("SOUL.md", "SOUL.md")).toBe(true);
+    expect(matchGlob("SOUL.md", "OTHER.md")).toBe(false);
+  });
+});
+
+describe("createGlobMatcher", () => {
+  test("returns reusable matcher function", () => {
+    const matcher = createGlobMatcher("*.md");
+    expect(matcher("SOUL.md")).toBe(true);
+    expect(matcher("README.md")).toBe(true);
+    expect(matcher("file.ts")).toBe(false);
+  });
+
+  test("compiles once for repeated use", () => {
+    const matcher = createGlobMatcher("src/**/*.ts");
+    const paths = ["src/a.ts", "src/b/c.ts", "test/d.ts", "src/e.md"];
+    const results = paths.filter(matcher);
+    expect(results).toEqual(["src/a.ts", "src/b/c.ts"]);
+  });
+});

package/src/glob.ts

@@ -0,0 +1,84 @@
+/**
+ * Glob resolution for soulguard config patterns.
+ *
+ * Expands glob patterns (e.g. "memory/*.md", "skills/**") into concrete
+ * file paths by querying the filesystem. Literal paths pass through as-is.
+ */
+
+import type { SystemOperations } from "./system-ops.js";
+import type { Result, IOError } from "./types.js";
+import { ok, err } from "./result.js";
+
+/** Check if a path contains glob characters */
+export function isGlob(path: string): boolean {
+  return path.includes("*");
+}
+
+/**
+ * Create a compiled glob matcher supporting * (single segment) and ** (any depth).
+ * Handles /**\/ matching zero or more directories (e.g. src/**\/*.ts matches src/main.ts).
+ */
+export function createGlobMatcher(pattern: string): (path: string) => boolean {
+  const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+  // Step 1: normalize /**/ to a placeholder, handling edge cases
+  let normalized = pattern;
+  // /**/ → match zero or more directory segments (including none, consume both slashes)
+  normalized = normalized.replace(/\/\*\*\//g, "<GLOBSTAR>");
+  // **/ at start → match zero or more directory prefixes
+  normalized = normalized.replace(/^\*\*\//, "<GLOBSTAR_PREFIX>");
+  // /** at end → match everything remaining (consume the leading /)
+  normalized = normalized.replace(/\/\*\*$/, "<GLOBSTAR_SUFFIX>");
+  // standalone ** → match everything
+  normalized = normalized.replace(/^\*\*$/, "<GLOBSTAR_ALL>");
+
+  // Step 2: escape literals and convert single * to [^/]*
+  const regexStr = normalized
+    .split(/(<GLOBSTAR(?:_PREFIX|_SUFFIX|_ALL)?>)/)
+    .map((part) => {
+      if (part === "<GLOBSTAR>") return "/(?:.+/)?";
+      if (part === "<GLOBSTAR_PREFIX>") return "(?:.+/)?";
+      if (part === "<GLOBSTAR_SUFFIX>") return "(?:/.*)?";
+
+      if (part === "<GLOBSTAR_ALL>") return ".*";
+      return part.split("*").map(escape).join("[^/]*");
+    })
+    .join("");
+
+  const regex = new RegExp(`^${regexStr}$`);
+  return (path: string) => regex.test(path);
+}
+
+/** Simple glob matcher supporting * (single segment) and ** (any depth) */
+export function matchGlob(pattern: string, path: string): boolean {
+  return createGlobMatcher(pattern)(path);
+}
+
+/**
+ * Resolve a list of paths/patterns into concrete file paths.
+ * Literal paths are included as-is (even if they don't exist on disk).
+ * Glob patterns are expanded against the filesystem.
+ * Returns deduplicated, sorted results.
+ */
+export async function resolvePatterns(
+  ops: SystemOperations,
+  patterns: string[],
+): Promise<Result<string[], IOError>> {
+  const files = new Set<string>();
+
+  for (const pattern of patterns) {
+    if (isGlob(pattern)) {
+      const result = await ops.glob(pattern);
+      if (!result.ok) {
+        return err(result.error);
+      }
+      for (const match of result.value) {
+        files.add(match);
+      }
+    } else {
+      files.add(pattern);
+    }
+  }
+
+  return ok([...files].sort());
+}

package/src/index.ts

@@ -0,0 +1,100 @@
+// Shared primitives
+export type {
+  SoulguardConfig,
+  Tier,
+  FileOwnership,
+  FileInfo,
+  // Errors
+  FileSystemError,
+  NotFoundError,
+  PermissionDeniedError,
+  IOError,
+  UserNotFoundError,
+  GroupNotFoundError,
+  // Drift issues
+  DriftIssue,
+  WrongOwnerIssue,
+  WrongGroupIssue,
+  WrongModeIssue,
+  HashFailedIssue,
+  // System identity
+  SystemIdentity,
+} from "./types.js";
+export { formatIssue } from "./types.js";
+
+// Result (generic pattern)
+export type { Result } from "./result.js";
+export { ok, err } from "./result.js";
+
+// Config
+export { soulguardConfigSchema, parseConfig } from "./schema.js";
+
+// System operations
+export type { SystemOperations, FileStat } from "./system-ops.js";
+export { getFileInfo } from "./system-ops.js";
+export { MockSystemOps } from "./system-ops-mock.js";
+export type { RecordedOp } from "./system-ops-mock.js";
+export { NodeSystemOps } from "./system-ops-node.js";
+
+// Status
+export { status } from "./status.js";
+export type { FileStatus, StatusResult, StatusOptions } from "./status.js";
+
+// Diff
+export { diff } from "./diff.js";
+export type { FileDiff, DiffResult, DiffError, DiffOptions } from "./diff.js";
+
+// Sync
+export { sync } from "./sync.js";
+export type { SyncError, SyncResult, SyncOptions } from "./sync.js";
+
+// Init
+export type { InitResult, InitError } from "./init.js";
+export { DEFAULT_CONFIG } from "./constants.js";
+
+// Console output
+export type { ConsoleOutput } from "./console.js";
+export { LiveConsoleOutput } from "./console-live.js";
+
+// Policy
+export { validatePolicies, evaluatePolicies } from "./policy.js";
+export type {
+  Policy,
+  PolicyViolation,
+  PolicyError,
+  PolicyCollisionError,
+  ApprovalContext,
+} from "./policy.js";
+
+// Self-protection (hardcoded, cannot be bypassed)
+export { validateSelfProtection } from "./self-protection.js";
+
+// Approve
+export { approve } from "./approve.js";
+export type { ApproveOptions, ApproveResult, ApprovalError } from "./approve.js";
+
+// Reset
+export { reset } from "./reset.js";
+export type { ResetOptions, ResetResult, ResetError } from "./reset.js";
+
+// Git integration
+export {
+  isGitEnabled,
+  gitCommit,
+  vaultCommitMessage,
+  ledgerCommitMessage,
+  commitLedgerFiles,
+} from "./git.js";
+export type { GitCommitResult, GitError } from "./git.js";
+
+// Vault check + glob
+export { isVaultedFile, normalizePath } from "./vault-check.js";
+export { isGlob, matchGlob, createGlobMatcher, resolvePatterns } from "./glob.js";
+
+// CLI commands
+export { StatusCommand } from "./cli/status-command.js";
+export { SyncCommand } from "./cli/sync-command.js";
+export { DiffCommand } from "./cli/diff-command.js";
+export { ApproveCommand } from "./cli/approve-command.js";
+export type { ApproveCommandOptions } from "./cli/approve-command.js";
+export { ResetCommand } from "./cli/reset-command.js";

package/src/init.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, test } from "bun:test";
+import { MockSystemOps } from "./system-ops-mock.js";
+import { init, generateSudoers } from "./init.js";
+import type { InitOptions } from "./init.js";
+import { DEFAULT_CONFIG } from "./constants.js";
+
+/** Mock absolute writer/exists that tracks what was written */
+function mockAbsolute(): {
+  writer: InitOptions["writeAbsolute"];
+  exists: InitOptions["existsAbsolute"];
+  written: Map<string, string>;
+} {
+  const written = new Map<string, string>();
+  return {
+    writer: async (path, content) => {
+      written.set(path, content);
+      return { ok: true as const, value: undefined };
+    },
+    exists: async (path) => written.has(path),
+    written,
+  };
+}
+
+function makeOptions(ops: MockSystemOps, overrides?: Partial<InitOptions>): InitOptions {
+  const { writer, exists } = mockAbsolute();
+  return {
+    ops,
+    identity: { user: "soulguardian", group: "soulguard" },
+    config: { vault: ["SOUL.md"], ledger: [] },
+    agentUser: "agent",
+    writeAbsolute: writer,
+    existsAbsolute: exists,
+    sudoersPath: "/tmp/test-sudoers",
+    _skipRootCheck: true,
+    ...overrides,
+  };
+}
+
+describe("init", () => {
+  test("creates user, group, config, staging, and sudoers", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.groupCreated).toBe(true);
+    expect(result.value.userCreated).toBe(true);
+    expect(result.value.configCreated).toBe(true);
+    expect(result.value.stagingCreated).toBe(true);
+    expect(result.value.sudoersCreated).toBe(true);
+  });
+
+  test("skips existing user and group", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addUser("soulguardian");
+    ops.addGroup("soulguard");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.groupCreated).toBe(false);
+    expect(result.value.userCreated).toBe(false);
+    // Config and staging should still be created
+    expect(result.value.configCreated).toBe(true);
+    expect(result.value.stagingCreated).toBe(true);
+  });
+
+  test("skips existing config", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("soulguard.json", '{"vault":["SOUL.md"],"ledger":[]}');
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.configCreated).toBe(false);
+  });
+
+  test("idempotent — second run recreates staging but not system resources", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    // Share absolute state between runs
+    const abs = mockAbsolute();
+    const opts = makeOptions(ops, { writeAbsolute: abs.writer, existsAbsolute: abs.exists });
+
+    // First run
+    const first = await init(opts);
+    expect(first.ok).toBe(true);
+
+    // Second run — system resources already exist, staging is recreated
+    const second = await init(opts);
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+
+    expect(second.value.groupCreated).toBe(false);
+    expect(second.value.userCreated).toBe(false);
+    expect(second.value.configCreated).toBe(false);
+    expect(second.value.sudoersCreated).toBe(false);
+    // Staging is always recreated (idempotent, self-healing)
+    expect(second.value.stagingCreated).toBe(true);
+  });
+
+  test("syncs vault files after setup", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Sync should have fixed the vault file ownership
+    const afterIssues = result.value.syncResult.after.issues;
+    expect(afterIssues.length).toBe(0);
+  });
+
+  test("uses DEFAULT_CONFIG when no config provided", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("openclaw.json", "{}", { owner: "agent", group: "staff", mode: "644" });
+    ops.addFile("soulguard.json", '{"vault":[],"ledger":[]}', {
+      owner: "agent",
+      group: "staff",
+      mode: "644",
+    });
+
+    const { writer, exists } = mockAbsolute();
+    const result = await init({
+      ops,
+      identity: { user: "soulguardian", group: "soulguard" },
+      agentUser: "agent",
+      writeAbsolute: writer,
+      existsAbsolute: exists,
+      sudoersPath: "/tmp/test-sudoers",
+      _skipRootCheck: true,
+      // no config — should use DEFAULT_CONFIG
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    // Config file already existed so configCreated is false, but sync should
+    // have processed the default vault file (soulguard.json)
+    expect(result.value.stagingCreated).toBe(true);
+
+    // Verify staging copy was created for the default vault file
+    const stagingSoulguard = await ops.exists(".soulguard/staging/soulguard.json");
+    expect(stagingSoulguard.ok && stagingSoulguard.value).toBe(true);
+  });
+});
+
+describe("DEFAULT_CONFIG", () => {
+  test("has expected default vault files", () => {
+    expect(DEFAULT_CONFIG.vault).toEqual(["soulguard.json"]);
+    expect(DEFAULT_CONFIG.ledger).toEqual([]);
+  });
+
+  test("git=true (default), no existing repo — git init called, .gitignore updated", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.gitInitialized).toBe(true);
+    expect(result.value.gitignoreUpdated).toBe(true);
+    // Verify git init was called
+    const execOps = ops.ops.filter((o) => o.kind === "exec");
+    expect(execOps).toContainEqual({ kind: "exec", command: "git", args: ["init"] });
+  });
+
+  test("git=true, existing repo — git init skipped, .gitignore still updated", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+    ops.addFile(".git", ""); // simulate existing git repo
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.gitInitialized).toBe(false);
+    expect(result.value.gitignoreUpdated).toBe(true);
+    const execOps = ops.ops.filter((o) => o.kind === "exec");
+    expect(execOps).not.toContainEqual({ kind: "exec", command: "git", args: ["init"] });
+  });
+
+  test("git=false — no git operations", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+
+    const result = await init(
+      makeOptions(ops, { config: { vault: ["SOUL.md"], ledger: [], git: false } }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.gitInitialized).toBe(false);
+    expect(result.value.gitignoreUpdated).toBe(false);
+    const execOps = ops.ops.filter((o) => o.kind === "exec");
+    expect(execOps).toHaveLength(0);
+  });
+
+  test(".gitignore already has staging entry — not duplicated", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "# My Soul", { owner: "agent", group: "staff", mode: "644" });
+    ops.addFile(".gitignore", "node_modules/\n.soulguard/\n");
+
+    const result = await init(makeOptions(ops));
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect(result.value.gitignoreUpdated).toBe(false);
+  });
+});
+
+describe("generateSudoers", () => {
+  test("generates scoped sudoers for agent", () => {
+    const content = generateSudoers("agent", "/usr/local/bin/soulguard");
+    expect(content).toContain("agent ALL=(root) NOPASSWD:");
+    expect(content).toContain("soulguard sync *");
+    expect(content).toContain("soulguard stage *");
+    expect(content).toContain("soulguard status *");
+    expect(content).toContain("soulguard diff *");
+    // Should NOT contain approve, init, or propose
+    expect(content).not.toContain("approve");
+    expect(content).not.toContain("init");
+    expect(content).not.toContain("propose");
+  });
+});