@soulguard/core 0.1.0

package/src/system-ops-node.ts

@@ -0,0 +1,499 @@
+/**
+ * NodeSystemOps — real OS-level file operations via Node.js APIs.
+ *
+ * Takes a workspace root; all paths are relative and validated
+ * against traversal. Maps errno codes to typed Result errors.
+ */
+
+import { resolve, relative, dirname } from "node:path";
+import {
+  stat as fsStat,
+  readFile,
+  chmod as fsChmod,
+  writeFile as fsWriteFile,
+  mkdir as fsMkdir,
+  copyFile as fsCopyFile,
+  unlink as fsUnlink,
+  chown as fsChown,
+  access,
+} from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { FileStat, SystemOperations } from "./system-ops.js";
+import type { IOError, NotFoundError, PermissionDeniedError, Result } from "./types.js";
+import { ok, err } from "./result.js";
+
+const execFileAsync = promisify(execFile);
+
+type FileError = NotFoundError | PermissionDeniedError | IOError;
+
+/** Map Node.js errno to our typed errors */
+function mapError(e: unknown, path: string, operation: string): FileError {
+  if (e instanceof Error && "code" in e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { kind: "not_found", path };
+    if (code === "EACCES" || code === "EPERM") {
+      return { kind: "permission_denied", path, operation };
+    }
+  }
+  const message = e instanceof Error ? e.message : String(e);
+  return { kind: "io_error", path, message };
+}
+
+/** Resolve username to numeric uid */
+async function nameToUid(name: string): Promise<number> {
+  const { stdout } = await execFileAsync("id", ["-u", name]);
+  return parseInt(stdout.trim(), 10);
+}
+
+/** Resolve group name to numeric gid */
+async function nameToGid(name: string): Promise<number> {
+  if (process.platform === "darwin") {
+    const { stdout } = await execFileAsync("dscl", [
+      ".",
+      "-read",
+      `/Groups/${name}`,
+      "PrimaryGroupID",
+    ]);
+    const gid = stdout.trim().split(/\s+/).pop();
+    if (!gid || !/^\d+$/.test(gid)) {
+      throw new Error(`Could not resolve GID for group '${name}'`);
+    }
+    return parseInt(gid, 10);
+  }
+  const { stdout } = await execFileAsync("getent", ["group", name]);
+  const field = stdout.split(":")[2];
+  if (!field || !/^\d+$/.test(field.trim())) {
+    throw new Error(`Could not resolve GID for group '${name}'`);
+  }
+  return parseInt(field.trim(), 10);
+}
+
+/** Look up username for a uid via `id -un` (works on macOS + Linux) */
+async function uidToName(uid: number): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync("id", ["-un", String(uid)]);
+    return stdout.trim();
+  } catch {
+    return String(uid);
+  }
+}
+
+/** Look up group name for a gid */
+async function gidToName(gid: number): Promise<string> {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      // macOS: dscl lookup
+      const { stdout } = await execFileAsync("dscl", [
+        ".",
+        "-search",
+        "/Groups",
+        "PrimaryGroupID",
+        String(gid),
+      ]);
+      const match = stdout.match(/^(\S+)/);
+      return match?.[1] ?? String(gid);
+    } else {
+      // Linux: getent
+      const { stdout } = await execFileAsync("getent", ["group", String(gid)]);
+      const name = stdout.split(":")[0];
+      return name || String(gid);
+    }
+  } catch {
+    return String(gid);
+  }
+}
+
+/** Convert octal mode to 3-digit string (e.g. 0o100444 → "444") */
+function modeToString(mode: number): string {
+  return (mode & 0o777).toString(8).padStart(3, "0");
+}
+
+export class NodeSystemOps implements SystemOperations {
+  public readonly workspace: string;
+
+  constructor(workspace: string) {
+    this.workspace = resolve(workspace);
+  }
+
+  /** Resolve a relative path, rejecting traversal outside workspace */
+  private resolvePath(path: string): Result<string, IOError> {
+    const full = resolve(this.workspace, path);
+    const rel = relative(this.workspace, full);
+    if (rel.startsWith("..")) {
+      return err({
+        kind: "io_error",
+        path,
+        message: "Path traversal outside workspace",
+      });
+    }
+    return ok(full);
+  }
+
+  async userExists(name: string): Promise<Result<boolean, IOError>> {
+    try {
+      await execFileAsync("id", ["-u", name]);
+      return ok(true);
+    } catch (e: unknown) {
+      // `id` exits non-zero for unknown users — that's expected
+      if (e instanceof Error && "code" in e && typeof (e as any).code === "number") {
+        return ok(false);
+      }
+      const message = e instanceof Error ? e.message : String(e);
+      return err({ kind: "io_error", path: "", message: `userExists(${name}): ${message}` });
+    }
+  }
+
+  async groupExists(name: string): Promise<Result<boolean, IOError>> {
+    try {
+      if (process.platform === "darwin") {
+        await execFileAsync("dscl", [".", "-read", `/Groups/${name}`, "PrimaryGroupID"]);
+      } else {
+        await execFileAsync("getent", ["group", name]);
+      }
+      return ok(true);
+    } catch (e: unknown) {
+      // Non-zero exit = group not found (expected)
+      if (e instanceof Error && "code" in e && typeof (e as any).code === "number") {
+        return ok(false);
+      }
+      const message = e instanceof Error ? e.message : String(e);
+      return err({ kind: "io_error", path: "", message: `groupExists(${name}): ${message}` });
+    }
+  }
+
+  async stat(path: string): Promise<Result<FileStat, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+
+    try {
+      const s = await fsStat(resolved.value);
+      const [user, group] = await Promise.all([uidToName(s.uid), gidToName(s.gid)]);
+
+      return ok({
+        path,
+        ownership: { user, group, mode: modeToString(s.mode) },
+      });
+    } catch (e) {
+      return err(mapError(e, path, "stat"));
+    }
+  }
+
+  async chown(
+    path: string,
+    owner: { user: string; group: string },
+  ): Promise<Result<void, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+
+    try {
+      const uid = await nameToUid(owner.user);
+      const gid = await nameToGid(owner.group);
+      await fsChown(resolved.value, uid, gid);
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, path, "chown"));
+    }
+  }
+
+  async chmod(path: string, mode: string): Promise<Result<void, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+
+    try {
+      await fsChmod(resolved.value, parseInt(mode, 8));
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, path, "chmod"));
+    }
+  }
+
+  async readFile(path: string): Promise<Result<string, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+
+    try {
+      const content = await readFile(resolved.value, "utf-8");
+      return ok(content);
+    } catch (e) {
+      return err(mapError(e, path, "readFile"));
+    }
+  }
+
+  async createUser(name: string, group: string): Promise<Result<void, IOError>> {
+    try {
+      if (process.platform === "darwin") {
+        // macOS: use dscl — PrimaryGroupID requires numeric GID
+        const { stdout: gidOutput } = await execFileAsync("dscl", [
+          ".",
+          "-read",
+          `/Groups/${group}`,
+          "PrimaryGroupID",
+        ]);
+        const gid = gidOutput.trim().split(/\s+/).pop();
+        if (!gid || !/^\d+$/.test(gid)) {
+          return err({
+            kind: "io_error",
+            path: `/Groups/${group}`,
+            message: `Could not resolve GID for group ${group}`,
+          });
+        }
+        await execFileAsync("dscl", [".", "-create", `/Users/${name}`]);
+        // macOS requires manually assigning a UID — find an unused one in system range
+        const MAX_SYSTEM_ID = 499;
+        let uid = 400;
+        while (uid <= MAX_SYSTEM_ID) {
+          const { stdout: uidSearch } = await execFileAsync("dscl", [
+            ".",
+            "-search",
+            "/Users",
+            "UniqueID",
+            String(uid),
+          ]);
+          if (!uidSearch.trim()) break;
+          uid++;
+        }
+        if (uid > MAX_SYSTEM_ID) {
+          return err({
+            kind: "io_error",
+            path: "",
+            message: `No available UID in system range (400-${MAX_SYSTEM_ID})`,
+          });
+        }
+        await execFileAsync("dscl", [".", "-create", `/Users/${name}`, "UniqueID", String(uid)]);
+        await execFileAsync("dscl", [".", "-create", `/Users/${name}`, "PrimaryGroupID", gid]);
+        await execFileAsync("dscl", [
+          ".",
+          "-create",
+          `/Users/${name}`,
+          "UserShell",
+          "/usr/bin/false",
+        ]);
+      } else {
+        await execFileAsync("useradd", ["-r", "-g", group, "-s", "/usr/bin/false", name]);
+      }
+      return ok(undefined);
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        path: "",
+        message: `createUser ${name}: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  async createGroup(name: string): Promise<Result<void, IOError>> {
+    try {
+      if (process.platform === "darwin") {
+        await execFileAsync("dscl", [".", "-create", `/Groups/${name}`]);
+        // macOS requires manually assigning a GID — find an unused one in system range
+        const MAX_SYSTEM_GID = 499;
+        let gid = 400;
+        while (gid <= MAX_SYSTEM_GID) {
+          const { stdout: searchOut } = await execFileAsync("dscl", [
+            ".",
+            "-search",
+            "/Groups",
+            "PrimaryGroupID",
+            String(gid),
+          ]);
+          if (!searchOut.trim()) break; // No match = GID is available
+          gid++;
+        }
+        if (gid > MAX_SYSTEM_GID) {
+          return err({
+            kind: "io_error",
+            path: "",
+            message: `No available GID in system range (400-${MAX_SYSTEM_GID})`,
+          });
+        }
+        await execFileAsync("dscl", [
+          ".",
+          "-create",
+          `/Groups/${name}`,
+          "PrimaryGroupID",
+          String(gid),
+        ]);
+      } else {
+        await execFileAsync("groupadd", [name]);
+      }
+      return ok(undefined);
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        path: "",
+        message: `createGroup ${name}: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  async writeFile(
+    path: string,
+    content: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+    try {
+      await fsMkdir(dirname(resolved.value), { recursive: true });
+      await fsWriteFile(resolved.value, content, "utf-8");
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, path, "writeFile"));
+    }
+  }
+
+  async mkdir(
+    path: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+    try {
+      await fsMkdir(resolved.value, { recursive: true });
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, path, "mkdir"));
+    }
+  }
+
+  async copyFile(
+    src: string,
+    dest: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>> {
+    const resolvedSrc = this.resolvePath(src);
+    if (!resolvedSrc.ok) return resolvedSrc;
+    const resolvedDest = this.resolvePath(dest);
+    if (!resolvedDest.ok) return resolvedDest;
+    try {
+      await fsMkdir(dirname(resolvedDest.value), { recursive: true });
+      await fsCopyFile(resolvedSrc.value, resolvedDest.value);
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, src, "copyFile"));
+    }
+  }
+
+  async exists(path: string): Promise<Result<boolean, IOError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return ok(false);
+    try {
+      await access(resolved.value);
+      return ok(true);
+    } catch (e) {
+      if (e instanceof Error && "code" in e && e.code === "ENOENT") {
+        return ok(false);
+      }
+      return err({
+        kind: "io_error",
+        path,
+        message: `exists: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  async deleteFile(path: string): Promise<Result<void, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+    try {
+      await fsUnlink(resolved.value);
+      return ok(undefined);
+    } catch (e) {
+      return err(mapError(e, path, "unlink"));
+    }
+  }
+
+  async hashFile(path: string): Promise<Result<string, FileError>> {
+    const resolved = this.resolvePath(path);
+    if (!resolved.ok) return resolved;
+
+    return new Promise((resolve) => {
+      const hash = createHash("sha256");
+      const stream = createReadStream(resolved.value);
+
+      stream.on("data", (chunk) => hash.update(chunk));
+      stream.on("end", () => resolve(ok(hash.digest("hex"))));
+      stream.on("error", (e) => resolve(err(mapError(e, path, "hashFile"))));
+    });
+  }
+
+  async glob(pattern: string): Promise<Result<string[], IOError>> {
+    try {
+      const fs = await import("node:fs");
+      const { promisify } = await import("node:util");
+      // fs.glob is available in Node 22+ but not yet in @types/node
+      const globFn = (fs as Record<string, unknown>).glob;
+      if (typeof globFn !== "function") {
+        return err({
+          kind: "io_error",
+          path: pattern,
+          message: "fs.glob requires Node.js 22+",
+        });
+      }
+      const globAsync = promisify(
+        globFn as (
+          pattern: string,
+          options: { cwd: string },
+          cb: (err: Error | null, matches: string[]) => void,
+        ) => void,
+      );
+      const matches = await globAsync(pattern, { cwd: this.workspace });
+      return ok([...matches].sort());
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        path: pattern,
+        message: `glob: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+
+  async exec(command: string, args: string[]): Promise<Result<void, IOError>> {
+    const execFileAsync = promisify(execFile);
+    try {
+      await execFileAsync(command, args, { cwd: this.workspace });
+      return ok(undefined);
+    } catch (e) {
+      return err({
+        kind: "io_error",
+        path: this.workspace,
+        message: `exec ${command}: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  }
+}
+
+/**
+ * Check if an absolute path exists (outside any workspace).
+ * Deliberately NOT on SystemOperations.
+ */
+export async function existsAbsolute(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write to an absolute path (outside any workspace).
+ * Deliberately NOT on SystemOperations — used only for init's sudoers writing.
+ */
+export async function writeFileAbsolute(
+  path: string,
+  content: string,
+): Promise<Result<void, IOError>> {
+  try {
+    await fsMkdir(dirname(path), { recursive: true });
+    await fsWriteFile(path, content, "utf-8");
+    return ok(undefined);
+  } catch (e) {
+    return err({
+      kind: "io_error",
+      path,
+      message: `writeFileAbsolute: ${e instanceof Error ? e.message : String(e)}`,
+    });
+  }
+}

package/src/system-ops.ts

@@ -0,0 +1,109 @@
+/**
+ * SystemOperations — abstraction over OS-level file operations.
+ *
+ * Takes a workspace root at construction time; all paths are relative.
+ * Each method declares exactly which errors it can return.
+ */
+
+import type {
+  Result,
+  FileOwnership,
+  FileInfo,
+  NotFoundError,
+  PermissionDeniedError,
+  IOError,
+} from "./types.js";
+import { ok } from "./result.js";
+
+export type FileStat = {
+  path: string;
+  ownership: FileOwnership;
+};
+
+export interface SystemOperations {
+  /** The workspace root this instance operates on */
+  readonly workspace: string;
+
+  /** Check if a system user exists */
+  userExists(name: string): Promise<Result<boolean, IOError>>;
+
+  /** Check if a system group exists */
+  groupExists(name: string): Promise<Result<boolean, IOError>>;
+
+  /** Create a system user (requires root) */
+  createUser(name: string, group: string): Promise<Result<void, IOError>>;
+
+  /** Create a system group (requires root) */
+  createGroup(name: string): Promise<Result<void, IOError>>;
+
+  /** Write content to a file (relative path). Creates parent dirs if needed. */
+  writeFile(
+    path: string,
+    content: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Create a directory (relative path). Creates parent dirs if needed. */
+  mkdir(path: string): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Copy a file (relative paths). */
+  copyFile(
+    src: string,
+    dest: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Check if a path exists (relative path) */
+  exists(path: string): Promise<Result<boolean, IOError>>;
+
+  /** Get file stat info (relative path) */
+  stat(path: string): Promise<Result<FileStat, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Change file owner and group (relative path). Does not set mode — use chmod. */
+  chown(
+    path: string,
+    owner: { user: string; group: string },
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Change file permissions (relative path) */
+  chmod(
+    path: string,
+    mode: string,
+  ): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Read file contents (relative path) */
+  readFile(path: string): Promise<Result<string, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Compute SHA-256 hash of file contents (relative path) */
+  hashFile(path: string): Promise<Result<string, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** Delete a file (relative path) */
+  deleteFile(path: string): Promise<Result<void, NotFoundError | PermissionDeniedError | IOError>>;
+
+  /** List files matching a glob pattern (relative paths, resolved within workspace) */
+  glob(pattern: string): Promise<Result<string[], IOError>>;
+
+  /** Execute a command in the workspace root */
+  exec(command: string, args: string[]): Promise<Result<void, IOError>>;
+}
+
+/** Common error type for stat/hash operations */
+type FileInfoError = NotFoundError | PermissionDeniedError | IOError;
+
+/**
+ * Get FileInfo for a relative path (stat + hash combined). DRY helper.
+ */
+export async function getFileInfo(
+  path: string,
+  ops: SystemOperations,
+): Promise<Result<FileInfo, FileInfoError>> {
+  const statResult = await ops.stat(path);
+  if (!statResult.ok) return statResult;
+
+  const hashResult = await ops.hashFile(path);
+  if (!hashResult.ok) return hashResult;
+
+  return ok({
+    path,
+    ownership: statResult.value.ownership,
+    hash: hashResult.value,
+  });
+}

package/src/types.ts

@@ -0,0 +1,91 @@
+/**
+ * Soulguard Core Types
+ */
+
+// ── Config ─────────────────────────────────────────────────────────────
+
+/** User-level configuration (soulguard.json) */
+export type SoulguardConfig = {
+  /** Files protected as vault items (require owner approval to modify) */
+  vault: string[];
+  /** File patterns tracked as ledger items (agent writes freely, changes recorded) */
+  ledger: string[];
+  /** Whether to initialize and track git (default: true) */
+  git?: boolean;
+};
+
+// ── Tiers ──────────────────────────────────────────────────────────────
+
+export type Tier = "vault" | "ledger";
+
+// ── File primitives ────────────────────────────────────────────────────
+
+/** OS-level ownership and permissions for a file */
+export type FileOwnership = {
+  user: string;
+  group: string;
+  /** e.g. "444", "644" */
+  mode: string;
+};
+
+/** Snapshot of a file's state on disk */
+export type FileInfo = {
+  /** Relative path from workspace root */
+  path: string;
+  ownership: FileOwnership;
+  /** SHA-256 hash of current contents */
+  hash: string;
+};
+
+// ── Errors ─────────────────────────────────────────────────────────────
+
+export type NotFoundError = { kind: "not_found"; path: string };
+export type PermissionDeniedError = { kind: "permission_denied"; path: string; operation: string };
+export type IOError = { kind: "io_error"; path: string; message: string };
+export type UserNotFoundError = { kind: "user_not_found"; user: string };
+export type GroupNotFoundError = { kind: "group_not_found"; group: string };
+
+/** Union of all filesystem errors */
+export type FileSystemError =
+  | NotFoundError
+  | PermissionDeniedError
+  | IOError
+  | UserNotFoundError
+  | GroupNotFoundError;
+
+// ── Drift issues (semantic, not strings) ───────────────────────────────
+
+export type WrongOwnerIssue = { kind: "wrong_owner"; expected: string; actual: string };
+export type WrongGroupIssue = { kind: "wrong_group"; expected: string; actual: string };
+export type WrongModeIssue = { kind: "wrong_mode"; expected: string; actual: string };
+export type HashFailedIssue = { kind: "hash_failed"; error: FileSystemError };
+
+export type DriftIssue = WrongOwnerIssue | WrongGroupIssue | WrongModeIssue | HashFailedIssue;
+
+/** Format a drift issue for display */
+export function formatIssue(issue: DriftIssue): string {
+  switch (issue.kind) {
+    case "wrong_owner":
+      return `owner is ${issue.actual}, expected ${issue.expected}`;
+    case "wrong_group":
+      return `group is ${issue.actual}, expected ${issue.expected}`;
+    case "wrong_mode":
+      return `mode is ${issue.actual}, expected ${issue.expected}`;
+    case "hash_failed":
+      return `hash failed: ${issue.error.kind}`;
+  }
+}
+
+// ── System identity ────────────────────────────────────────────────────
+
+/** Expected soulguard system user/group names per platform */
+export type SystemIdentity = {
+  /** System user that owns vault files (e.g. "soulguardian") */
+  user: string;
+  /** System group for vault files (e.g. "soulguard") */
+  group: string;
+};
+
+// Re-export Result from result.ts for convenience
+export type { Result } from "./result.js";
+export { ok, err } from "./result.js";