@soulguard/core 0.1.0

package/src/cli/reset-command.ts

@@ -0,0 +1,36 @@
+/**
+ * ResetCommand — reset staging to match vault (discard changes).
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { ResetOptions } from "../reset.js";
+import { reset } from "../reset.js";
+
+export class ResetCommand {
+  constructor(
+    private opts: ResetOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    const result = await reset(this.opts);
+
+    if (!result.ok) {
+      this.out.error(`Reset failed: ${result.error.message}`);
+      return 1;
+    }
+
+    if (result.value.resetFiles.length === 0) {
+      this.out.info("No changes to reset — staging already matches vault.");
+      return 0;
+    }
+
+    this.out.heading(`Soulguard Reset — ${this.opts.ops.workspace}`);
+    this.out.write("");
+    this.out.success(`Reset ${result.value.resetFiles.length} staging file(s):`);
+    for (const file of result.value.resetFiles) {
+      this.out.info(`  ↩️  ${file}`);
+    }
+    return 0;
+  }
+}

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "bun:test";
+import { MockSystemOps } from "../system-ops-mock.js";
+import { MockConsoleOutput } from "../console-mock.js";
+import { StatusCommand } from "./status-command.js";
+import type { StatusOptions } from "../status.js";
+
+const VAULT_OWNERSHIP = { user: "soulguardian", group: "soulguard", mode: "444" };
+const LEDGER_OWNERSHIP = { user: "agent", group: "soulguard", mode: "644" };
+const VAULT_MOCK = { owner: "soulguardian", group: "soulguard", mode: "444" };
+const LEDGER_MOCK = { owner: "agent", group: "soulguard", mode: "644" };
+
+function setup(configureMock: (ops: MockSystemOps) => void): {
+  cmd: StatusCommand;
+  out: MockConsoleOutput;
+} {
+  const ops = new MockSystemOps("/workspace");
+  configureMock(ops);
+  const out = new MockConsoleOutput();
+  const opts: StatusOptions = {
+    config: { vault: ["SOUL.md"], ledger: ["memory/today.md"] },
+    expectedVaultOwnership: VAULT_OWNERSHIP,
+    expectedLedgerOwnership: LEDGER_OWNERSHIP,
+    ops,
+  };
+  return { cmd: new StatusCommand(opts, out), out };
+}
+
+describe("StatusCommand", () => {
+  it("returns 0 and shows ✅ when all files ok", async () => {
+    const { cmd, out } = setup((ops) => {
+      ops.addFile("SOUL.md", "soul content", VAULT_MOCK);
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(0);
+    expect(out.hasText("✅")).toBe(true);
+    expect(out.hasText("2 files ok, 0 drifted, 0 missing")).toBe(true);
+  });
+
+  it("returns 1 and shows ⚠️ when files are drifted", async () => {
+    const { cmd, out } = setup((ops) => {
+      ops.addFile("SOUL.md", "soul content", { owner: "wrong", group: "soulguard", mode: "444" });
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(1);
+    expect(out.hasText("⚠️")).toBe(true);
+    expect(out.hasText("1 drifted")).toBe(true);
+  });
+
+  it("returns 1 and shows ❌ when files are missing", async () => {
+    const { cmd, out } = setup((ops) => {
+      // SOUL.md not added — missing
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(1);
+    expect(out.hasText("❌")).toBe(true);
+    expect(out.hasText("1 missing")).toBe(true);
+  });
+
+  it("resolves glob patterns and shows matched files", async () => {
+    const ops = new MockSystemOps("/workspace");
+    ops.addFile("SOUL.md", "soul content", VAULT_MOCK);
+    ops.addFile("memory/day1.md", "notes", {
+      owner: LEDGER_OWNERSHIP.user,
+      group: LEDGER_OWNERSHIP.group,
+      mode: LEDGER_OWNERSHIP.mode,
+    });
+    const out = new MockConsoleOutput();
+    const opts: StatusOptions = {
+      config: { vault: ["SOUL.md"], ledger: ["memory/*.md"] },
+      expectedVaultOwnership: VAULT_OWNERSHIP,
+      expectedLedgerOwnership: LEDGER_OWNERSHIP,
+      ops,
+    };
+    const cmd = new StatusCommand(opts, out);
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(0);
+    expect(out.hasText("memory/day1.md")).toBe(true);
+  });
+});

package/src/cli/status-command.ts

@@ -0,0 +1,78 @@
+/**
+ * StatusCommand — pretty-prints the result of `status()`.
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { StatusOptions, FileStatus } from "../status.js";
+import { status } from "../status.js";
+import { formatIssue } from "../types.js";
+
+export class StatusCommand {
+  constructor(
+    private opts: StatusOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    const result = await status(this.opts);
+    if (!result.ok) return 1;
+
+    const { vault, ledger, issues } = result.value;
+
+    this.out.heading(`Soulguard Status — ${this.opts.ops.workspace}`);
+    this.out.write("");
+
+    if (vault.length > 0) {
+      this.out.heading("Vault");
+      for (const f of vault) {
+        this.printFile(f);
+      }
+      this.out.write("");
+    }
+
+    if (ledger.length > 0) {
+      this.out.heading("Ledger");
+      for (const f of ledger) {
+        this.printFile(f);
+      }
+      this.out.write("");
+    }
+
+    const counts = this.summarize([...vault, ...ledger]);
+    this.out.info(`${counts.ok} files ok, ${counts.drifted} drifted, ${counts.missing} missing`);
+
+    return issues.length > 0 ? 1 : 0;
+  }
+
+  private printFile(f: FileStatus): void {
+    switch (f.status) {
+      case "ok":
+        this.out.success(`  ✅ ${f.file.path}`);
+        break;
+      case "drifted":
+        this.out.warn(`  ⚠️  ${f.file.path}`);
+        for (const issue of f.issues) {
+          this.out.warn(`      ${formatIssue(issue)}`);
+        }
+        break;
+      case "missing":
+        this.out.error(`  ❌ ${f.path}`);
+        break;
+      case "error":
+        this.out.error(`  ❌ ${f.path} (${f.error.kind})`);
+        break;
+    }
+  }
+
+  private summarize(files: FileStatus[]): { ok: number; drifted: number; missing: number } {
+    let okCount = 0;
+    let drifted = 0;
+    let missing = 0;
+    for (const f of files) {
+      if (f.status === "ok") okCount++;
+      else if (f.status === "drifted") drifted++;
+      else if (f.status === "missing") missing++;
+    }
+    return { ok: okCount, drifted, missing };
+  }
+}

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

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "bun:test";
+import { MockSystemOps } from "../system-ops-mock.js";
+import { MockConsoleOutput } from "../console-mock.js";
+import { SyncCommand } from "./sync-command.js";
+import type { SyncOptions } from "../sync.js";
+
+const VAULT_OWNERSHIP = { user: "soulguardian", group: "soulguard", mode: "444" };
+const LEDGER_OWNERSHIP = { user: "agent", group: "soulguard", mode: "644" };
+const VAULT_MOCK = { owner: "soulguardian", group: "soulguard", mode: "444" };
+const LEDGER_MOCK = { owner: "agent", group: "soulguard", mode: "644" };
+
+function setup(configureMock: (ops: MockSystemOps) => void): {
+  cmd: SyncCommand;
+  out: MockConsoleOutput;
+  ops: MockSystemOps;
+} {
+  const ops = new MockSystemOps("/workspace");
+  configureMock(ops);
+  const out = new MockConsoleOutput();
+  const opts: SyncOptions = {
+    config: { vault: ["SOUL.md"], ledger: ["memory/today.md"] },
+    expectedVaultOwnership: VAULT_OWNERSHIP,
+    expectedLedgerOwnership: LEDGER_OWNERSHIP,
+    ops,
+  };
+  return { cmd: new SyncCommand(opts, out), out, ops };
+}
+
+describe("SyncCommand", () => {
+  it("returns 0 and shows fix when drift is corrected", async () => {
+    const { cmd, out, ops } = setup((ops) => {
+      ops.addFile("SOUL.md", "soul content", { owner: "wrong", group: "soulguard", mode: "444" });
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(0);
+    expect(out.hasText("🔧")).toBe(true);
+    expect(out.hasText("All files now ok.")).toBe(true);
+    expect(ops.ops.length).toBeGreaterThan(0);
+  });
+
+  it("returns 0 with nothing-to-fix message when all ok", async () => {
+    const { cmd, out } = setup((ops) => {
+      ops.addFile("SOUL.md", "soul content", VAULT_MOCK);
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(0);
+    expect(out.hasText("Nothing to fix")).toBe(true);
+  });
+
+  it("returns 1 when missing files remain after sync", async () => {
+    const { cmd, out } = setup((ops) => {
+      // SOUL.md missing — sync can't fix missing files
+      ops.addFile("memory/today.md", "memory content", LEDGER_MOCK);
+    });
+
+    const code = await cmd.execute();
+
+    expect(code).toBe(1);
+    expect(out.hasText("remaining after sync")).toBe(true);
+  });
+});

package/src/cli/sync-command.ts

@@ -0,0 +1,105 @@
+/**
+ * SyncCommand — runs sync and pretty-prints results.
+ */
+
+import type { ConsoleOutput } from "../console.js";
+import type { SyncOptions } from "../sync.js";
+import { sync } from "../sync.js";
+import { formatIssue } from "../types.js";
+import type { FileStatus } from "../status.js";
+import type { GitCommitResult } from "../git.js";
+
+export class SyncCommand {
+  constructor(
+    private opts: SyncOptions,
+    private out: ConsoleOutput,
+  ) {}
+
+  async execute(): Promise<number> {
+    const result = await sync(this.opts);
+    if (!result.ok) return 1;
+
+    const { before, after, errors, git } = result.value;
+
+    this.out.heading(`Soulguard Sync — ${this.opts.ops.workspace}`);
+    this.out.write("");
+
+    if (before.issues.length === 0 && errors.length === 0) {
+      this.out.success("Nothing to fix — all files ok.");
+      this.reportGit(git);
+      return 0;
+    }
+
+    // Show what was actually fixed (in before.issues but not in after.issues)
+    const afterPaths = new Set(after.issues.map((f) => this.issuePath(f)));
+    const fixed = before.issues.filter((f) => !afterPaths.has(this.issuePath(f)));
+
+    if (fixed.length > 0) {
+      this.out.heading("Fixed:");
+      for (const f of fixed) {
+        this.out.success(`  🔧 ${this.issuePath(f)}`);
+        if (f.status === "drifted") {
+          for (const issue of f.issues) {
+            this.out.info(`      ${formatIssue(issue)}`);
+          }
+        }
+      }
+      this.out.write("");
+    }
+
+    // Show errors
+    if (errors.length > 0) {
+      this.out.heading("Errors:");
+      for (const e of errors) {
+        this.out.error(`  ❌ ${e.path}: ${e.operation} failed (${e.error.kind})`);
+      }
+      this.out.write("");
+    }
+
+    // Show remaining issues
+    if (after.issues.length === 0) {
+      this.out.success("All files now ok.");
+      this.reportGit(git);
+      return 0;
+    }
+
+    this.out.warn(`${after.issues.length} issue(s) remaining after sync:`);
+    for (const f of after.issues) {
+      this.printFile(f);
+    }
+
+    return 1;
+  }
+
+  private reportGit(git?: GitCommitResult): void {
+    if (git?.committed) {
+      this.out.success(`  📝 Committed ${git.files.length} file(s) to git`);
+    }
+  }
+
+  private issuePath(f: FileStatus): string {
+    switch (f.status) {
+      case "ok":
+        return f.file.path;
+      case "drifted":
+        return f.file.path;
+      case "missing":
+      case "error":
+        return f.path;
+    }
+  }
+
+  private printFile(f: FileStatus): void {
+    switch (f.status) {
+      case "drifted":
+        this.out.warn(`  ⚠️  ${f.file.path}`);
+        break;
+      case "missing":
+        this.out.error(`  ❌ ${f.path}`);
+        break;
+      case "error":
+        this.out.error(`  ❌ ${f.path} (${f.error.kind})`);
+        break;
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * soulguard CLI entry point.
+ */
+
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { LiveConsoleOutput } from "./console-live.js";
+import { StatusCommand } from "./cli/status-command.js";
+import { SyncCommand } from "./cli/sync-command.js";
+import { DiffCommand } from "./cli/diff-command.js";
+import { ApproveCommand } from "./cli/approve-command.js";
+import { ResetCommand } from "./cli/reset-command.js";
+import { InitCommand } from "./cli/init-command.js";
+import { NodeSystemOps, writeFileAbsolute, existsAbsolute } from "./system-ops-node.js";
+import { parseConfig } from "./schema.js";
+import type { StatusOptions } from "./status.js";
+import type { SoulguardConfig } from "./types.js";
+
+import { IDENTITY, VAULT_OWNERSHIP } from "./constants.js";
+function ledgerOwnership(): { user: string; group: string; mode: string } {
+  const agentUser = process.env.SUDO_USER ?? "agent";
+  return { user: agentUser, group: IDENTITY.group, mode: "644" };
+}
+
+const DEFAULT_CONFIG: SoulguardConfig = {
+  vault: [
+    "SOUL.md",
+    "AGENTS.md",
+    "IDENTITY.md",
+    "USER.md",
+    "TOOLS.md",
+    "HEARTBEAT.md",
+    "BOOTSTRAP.md",
+    "soulguard.json",
+  ],
+  ledger: ["memory/**", "skills/**"],
+};
+
+async function makeOptions(workspace: string): Promise<StatusOptions> {
+  const ops = new NodeSystemOps(resolve(workspace));
+  const configPath = resolve(workspace, "soulguard.json");
+
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf-8");
+  } catch {
+    throw new Error(`No soulguard.json found in ${workspace}`);
+  }
+
+  const config = parseConfig(JSON.parse(raw));
+
+  return {
+    config,
+    expectedVaultOwnership: VAULT_OWNERSHIP,
+    expectedLedgerOwnership: ledgerOwnership(),
+    ops,
+  };
+}
+
+const program = new Command()
+  .name("soulguard")
+  .description("Identity protection for AI agents")
+  .version("0.0.0");
+
+program
+  .command("status")
+  .description("Report the status of a soulguard workspace")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .action(async (workspace: string) => {
+    const out = new LiveConsoleOutput();
+    try {
+      const opts = await makeOptions(workspace);
+      const cmd = new StatusCommand(opts, out);
+      process.exitCode = await cmd.execute();
+    } catch (e) {
+      out.error(e instanceof Error ? e.message : String(e));
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("sync")
+  .description("Fix all issues in a soulguard workspace")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .action(async (workspace: string) => {
+    const out = new LiveConsoleOutput();
+    try {
+      const opts = await makeOptions(workspace);
+      const cmd = new SyncCommand(opts, out);
+      process.exitCode = await cmd.execute();
+    } catch (e) {
+      out.error(e instanceof Error ? e.message : String(e));
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("init")
+  .description("Initialize soulguard for a workspace")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .option("--agent-user <user>", "agent OS username (default: $SUDO_USER or 'agent')")
+  .option("--template <name>", "protection template")
+  .action(async (workspace: string, opts: { agentUser?: string; template?: string }) => {
+    const out = new LiveConsoleOutput();
+    const absWorkspace = resolve(workspace);
+    const nodeOps = new NodeSystemOps(absWorkspace);
+
+    // Infer agent user: explicit flag > $SUDO_USER > "agent"
+    const agentUser = opts.agentUser ?? process.env.SUDO_USER ?? "agent";
+
+    // Use existing config if present, otherwise default
+    let config: SoulguardConfig = DEFAULT_CONFIG;
+    try {
+      const raw = await readFile(resolve(absWorkspace, "soulguard.json"), "utf-8");
+      config = parseConfig(JSON.parse(raw));
+    } catch {
+      // No existing config — will be created by init
+    }
+
+    const cmd = new InitCommand(
+      {
+        ops: nodeOps,
+        identity: IDENTITY,
+        config,
+        agentUser,
+        writeAbsolute: writeFileAbsolute,
+        existsAbsolute,
+      },
+      out,
+    );
+    process.exitCode = await cmd.execute();
+  });
+
+program
+  .command("diff")
+  .description("Compare vault files against staging copies")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .argument("[files...]", "specific files to diff")
+  .action(async (workspace: string, files: string[]) => {
+    const out = new LiveConsoleOutput();
+    try {
+      const opts = await makeOptions(workspace);
+      const cmd = new DiffCommand(
+        {
+          ops: opts.ops,
+          config: opts.config,
+          files: files.length > 0 ? files : undefined,
+        },
+        out,
+      );
+      process.exitCode = await cmd.execute();
+    } catch (e) {
+      out.error(e instanceof Error ? e.message : String(e));
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("approve")
+  .description("Approve and apply staging changes to vault")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .option("--hash <hash>", "approval hash for non-interactive mode")
+  .action(async (workspace: string, opts: { hash?: string }) => {
+    const out = new LiveConsoleOutput();
+    try {
+      const statusOpts = await makeOptions(workspace);
+      const agentUser = process.env.SUDO_USER ?? "agent";
+      const cmd = new ApproveCommand(
+        {
+          ops: statusOpts.ops,
+          config: statusOpts.config,
+          vaultOwnership: VAULT_OWNERSHIP,
+          stagingOwnership: { user: agentUser, group: IDENTITY.group, mode: "644" },
+          hash: opts.hash,
+          prompt: opts.hash
+            ? undefined
+            : async () => {
+                // Interactive prompt via stdin
+                const rl = await import("node:readline");
+                const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+                return new Promise<boolean>((resolve) => {
+                  iface.question("Apply these changes? [y/N] ", (answer) => {
+                    iface.close();
+                    resolve(answer.toLowerCase() === "y");
+                  });
+                });
+              },
+        },
+        out,
+      );
+      process.exitCode = await cmd.execute();
+    } catch (e) {
+      out.error(e instanceof Error ? e.message : String(e));
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("reset")
+  .description("Reset staging to match vault (discard changes)")
+  .argument("[workspace]", "workspace path", process.cwd())
+  .action(async (workspace: string) => {
+    const out = new LiveConsoleOutput();
+    try {
+      const statusOpts = await makeOptions(workspace);
+      const agentUser = process.env.SUDO_USER ?? "agent";
+      const cmd = new ResetCommand(
+        {
+          ops: statusOpts.ops,
+          config: statusOpts.config,
+          stagingOwnership: { user: agentUser, group: IDENTITY.group, mode: "644" },
+        },
+        out,
+      );
+      process.exitCode = await cmd.execute();
+    } catch (e) {
+      out.error(e instanceof Error ? e.message : String(e));
+      process.exitCode = 1;
+    }
+  });
+
+program.parse();

package/src/console-live.ts

@@ -0,0 +1,32 @@
+/**
+ * LiveConsoleOutput — real terminal output with colors via picocolors.
+ */
+
+import pc from "picocolors";
+import type { ConsoleOutput } from "./console.js";
+
+export class LiveConsoleOutput implements ConsoleOutput {
+  write(text: string): void {
+    console.log(text);
+  }
+
+  error(text: string): void {
+    console.log(pc.red(text));
+  }
+
+  success(text: string): void {
+    console.log(pc.green(text));
+  }
+
+  warn(text: string): void {
+    console.log(pc.yellow(text));
+  }
+
+  info(text: string): void {
+    console.log(pc.dim(text));
+  }
+
+  heading(text: string): void {
+    console.log(pc.bold(text));
+  }
+}

package/src/console-mock.ts

@@ -0,0 +1,48 @@
+/**
+ * MockConsoleOutput — captures output for test assertions.
+ */
+
+import type { ConsoleOutput } from "./console.js";
+
+export type CapturedLine = {
+  level: "write" | "error" | "success" | "warn" | "info" | "heading";
+  text: string;
+};
+
+export class MockConsoleOutput implements ConsoleOutput {
+  public lines: CapturedLine[] = [];
+
+  write(text: string): void {
+    this.lines.push({ level: "write", text });
+  }
+
+  error(text: string): void {
+    this.lines.push({ level: "error", text });
+  }
+
+  success(text: string): void {
+    this.lines.push({ level: "success", text });
+  }
+
+  warn(text: string): void {
+    this.lines.push({ level: "warn", text });
+  }
+
+  info(text: string): void {
+    this.lines.push({ level: "info", text });
+  }
+
+  heading(text: string): void {
+    this.lines.push({ level: "heading", text });
+  }
+
+  /** Get all text from lines matching a level */
+  textsAt(level: CapturedLine["level"]): string[] {
+    return this.lines.filter((l) => l.level === level).map((l) => l.text);
+  }
+
+  /** Check if any line contains a substring */
+  hasText(substring: string): boolean {
+    return this.lines.some((l) => l.text.includes(substring));
+  }
+}

package/src/console.ts

@@ -0,0 +1,12 @@
+/**
+ * ConsoleOutput — abstraction over terminal output for testability.
+ */
+
+export interface ConsoleOutput {
+  write(text: string): void;
+  error(text: string): void;
+  success(text: string): void;
+  warn(text: string): void;
+  info(text: string): void;
+  heading(text: string): void;
+}