@de-otio/repo-aegis-core 0.2.0

package/src/lock.test.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import lockfile from "proper-lockfile";
+import { withLock, withLockSync } from "./lock.js";
+import { LockTimeoutError } from "./exceptions.js";
+
+let tmp: string;
+
+before(() => {
+  tmp = mkdtempSync(join(tmpdir(), "repo-aegis-lock-test-"));
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+function lockPathFor(name: string): string {
+  const p = join(tmp, name);
+  writeFileSync(p, "");
+  return p;
+}
+
+describe("withLockSync", () => {
+  it("runs fn while holding the lock and returns its result", () => {
+    const lp = lockPathFor("happy.lock");
+    const result = withLockSync(() => 42, { lockPath: lp });
+    assert.equal(result, 42);
+  });
+
+  it("releases the lock even when fn throws", () => {
+    const lp = lockPathFor("throw.lock");
+    assert.throws(() => withLockSync(() => { throw new Error("boom"); }, { lockPath: lp }), /boom/);
+    // Should be able to acquire it again immediately.
+    const r = withLockSync(() => "ok", { lockPath: lp });
+    assert.equal(r, "ok");
+  });
+
+  it("creates the lock file if missing", () => {
+    const lp = join(tmp, "auto-create.lock");
+    assert.equal(existsSync(lp), false);
+    withLockSync(() => 1, { lockPath: lp });
+    assert.ok(existsSync(lp));
+  });
+
+  it("throws LockTimeoutError when another process holds the lock", () => {
+    const lp = lockPathFor("contended.lock");
+    const release = lockfile.lockSync(lp, { stale: 30_000 });
+    try {
+      assert.throws(() => withLockSync(() => 1, { lockPath: lp }), LockTimeoutError);
+    } finally {
+      release();
+    }
+  });
+});
+
+describe("withLock (async)", () => {
+  it("runs fn and returns its result", async () => {
+    const lp = lockPathFor("async-happy.lock");
+    const result = await withLock(() => 99, { lockPath: lp });
+    assert.equal(result, 99);
+  });
+
+  it("supports async fn", async () => {
+    const lp = lockPathFor("async-fn.lock");
+    const result = await withLock(async () => {
+      await new Promise(r => setTimeout(r, 5));
+      return "done";
+    }, { lockPath: lp });
+    assert.equal(result, "done");
+  });
+
+  it("releases the lock when fn rejects", async () => {
+    const lp = lockPathFor("async-reject.lock");
+    await assert.rejects(withLock(async () => { throw new Error("x"); }, { lockPath: lp }), /x/);
+    const r = await withLock(() => "ok", { lockPath: lp });
+    assert.equal(r, "ok");
+  });
+
+  it("serializes two parallel withLock calls against the same lockPath", async () => {
+    // Two concurrent withLock calls on the same path must NOT overlap.
+    // We record entry/exit timestamps for each and assert one's interval
+    // fully precedes the other.
+    const lp = lockPathFor("async-serialize.lock");
+    const HOLD_MS = 60;
+
+    interface Span { start: number; end: number; label: string }
+    const spans: Span[] = [];
+
+    async function critical(label: string): Promise<Span> {
+      return withLock(async () => {
+        const start = Date.now();
+        await new Promise(r => setTimeout(r, HOLD_MS));
+        const end = Date.now();
+        const span: Span = { start, end, label };
+        spans.push(span);
+        return span;
+      }, { lockPath: lp, timeoutMs: 5000 });
+    }
+
+    const [a, b] = await Promise.all([critical("a"), critical("b")]);
+    // Sort by start time and assert non-overlap.
+    const sorted = [a, b].sort((x, y) => x.start - y.start);
+    assert.ok(
+      sorted[0]!.end <= sorted[1]!.start,
+      `expected serialized intervals; got a=[${a.start},${a.end}] b=[${b.start},${b.end}]`,
+    );
+    assert.equal(spans.length, 2);
+  });
+
+  it("throws LockTimeoutError when the path is held by lockfile.lockSync", async () => {
+    const lp = lockPathFor("async-contended.lock");
+    const release = lockfile.lockSync(lp, { stale: 30_000 });
+    try {
+      await assert.rejects(
+        withLock(() => 1, { lockPath: lp, timeoutMs: 100 }),
+        LockTimeoutError,
+      );
+    } finally {
+      release();
+    }
+  });
+
+  it("honours timeoutMs (rejects within the timeout window)", async () => {
+    const lp = lockPathFor("async-timeout.lock");
+    const release = lockfile.lockSync(lp, { stale: 30_000 });
+    try {
+      const t0 = Date.now();
+      await assert.rejects(
+        withLock(() => 1, { lockPath: lp, timeoutMs: 100 }),
+        LockTimeoutError,
+      );
+      const elapsed = Date.now() - t0;
+      // proper-lockfile retry math + jitter: a 100ms timeout typically
+      // settles in well under 500ms. Generous upper bound to avoid CI
+      // flake on busy runners; the lower bound asserts we waited at all
+      // (i.e. that timeoutMs wasn't ignored entirely and rejected
+      // immediately at the very first retry).
+      assert.ok(
+        elapsed < 1500,
+        `withLock should reject promptly under timeoutMs=100; elapsed=${elapsed}ms`,
+      );
+    } finally {
+      release();
+    }
+  });
+});

package/src/lock.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+import { lockFilePath } from "./paths.js";
+import { LockTimeoutError } from "./exceptions.js";
+
+export interface LockOptions {
+  /** ms to wait for the lock before throwing LockTimeoutError. Default 5000. */
+  timeoutMs?: number;
+  /** Override the lock target file. Default: lockFilePath() under the repo-aegis home. */
+  lockPath?: string;
+}
+
+/**
+ * Run `fn` while holding the registry lock. Synchronous-friendly: `fn`
+ * may be sync or async; returns the function's return value. The lock
+ * is released even if `fn` throws.
+ *
+ * Stale locks (process died) are auto-cleared by proper-lockfile after
+ * 30s.
+ */
+export async function withLock<T>(fn: () => T | Promise<T>, opts: LockOptions = {}): Promise<T> {
+  const path = opts.lockPath ?? lockFilePath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  // proper-lockfile locks the *file* — needs to exist.
+  if (!existsSync(path)) writeFileSync(path, "");
+
+  const timeout = opts.timeoutMs ?? 5000;
+  let release: () => Promise<void>;
+  try {
+    release = await lockfile.lock(path, {
+      stale: 30_000,
+      retries: { retries: 10, factor: 1.5, minTimeout: 50, maxTimeout: timeout, randomize: true },
+    });
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ELOCKED" || code === "ENOTACQUIRED") {
+      throw new LockTimeoutError(path);
+    }
+    throw err;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try {
+      await release();
+    } catch {
+      /* lock already released or compromised; nothing useful to do here */
+    }
+  }
+}
+
+/**
+ * Synchronous variant. Used by code paths that can't easily go async
+ * (e.g. existing CLI commands). proper-lockfile's lockSync exists for
+ * this case.
+ */
+export function withLockSync<T>(fn: () => T, opts: LockOptions = {}): T {
+  const path = opts.lockPath ?? lockFilePath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync(path)) writeFileSync(path, "");
+
+  let release: () => void;
+  try {
+    release = lockfile.lockSync(path, { stale: 30_000 });
+  } catch (err) {
+    const code = (err as { code?: string }).code;
+    if (code === "ELOCKED" || code === "ENOTACQUIRED") {
+      throw new LockTimeoutError(path);
+    }
+    throw err;
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      release();
+    } catch {
+      /* lock already released or compromised */
+    }
+  }
+}

package/src/paths.test.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  repoAegisHome,
+  registryPath,
+  markersDir,
+  flatMarkersPath,
+  statePath,
+  leakContextFlagPath,
+  lockFilePath,
+  isHomeOverridden,
+} from "./paths.js";
+
+let originalHome: string | undefined;
+let originalRegistry: string | undefined;
+let originalMarkersDir: string | undefined;
+
+beforeEach(() => {
+  originalHome = process.env["REPO_AEGIS_HOME"];
+  originalRegistry = process.env["REPO_AEGIS_REGISTRY"];
+  originalMarkersDir = process.env["REPO_AEGIS_MARKERS_DIR"];
+  delete process.env["REPO_AEGIS_HOME"];
+  delete process.env["REPO_AEGIS_REGISTRY"];
+  delete process.env["REPO_AEGIS_MARKERS_DIR"];
+});
+
+afterEach(() => {
+  if (originalHome !== undefined) process.env["REPO_AEGIS_HOME"] = originalHome;
+  else delete process.env["REPO_AEGIS_HOME"];
+  if (originalRegistry !== undefined) process.env["REPO_AEGIS_REGISTRY"] = originalRegistry;
+  else delete process.env["REPO_AEGIS_REGISTRY"];
+  if (originalMarkersDir !== undefined) process.env["REPO_AEGIS_MARKERS_DIR"] = originalMarkersDir;
+  else delete process.env["REPO_AEGIS_MARKERS_DIR"];
+});
+
+describe("paths", () => {
+  it("default home is ~/.config/repo-aegis", () => {
+    const h = repoAegisHome();
+    assert.match(h, /\.config\/repo-aegis$/);
+  });
+
+  it("REPO_AEGIS_HOME env overrides home", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/custom";
+    assert.equal(repoAegisHome(), "/tmp/custom");
+  });
+
+  it("REPO_AEGIS_REGISTRY overrides registry path", () => {
+    process.env["REPO_AEGIS_REGISTRY"] = "/tmp/custom-registry.yaml";
+    assert.equal(registryPath(), "/tmp/custom-registry.yaml");
+  });
+
+  it("registryPath defaults to home/engagements.yaml", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(registryPath(), "/tmp/x/engagements.yaml");
+  });
+
+  it("REPO_AEGIS_MARKERS_DIR overrides markers path", () => {
+    process.env["REPO_AEGIS_MARKERS_DIR"] = "/tmp/custom-markers";
+    assert.equal(markersDir(), "/tmp/custom-markers");
+  });
+
+  it("markersDir defaults to home/markers", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(markersDir(), "/tmp/x/markers");
+  });
+
+  it("flatMarkersPath is home/markers.txt", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(flatMarkersPath(), "/tmp/x/markers.txt");
+  });
+
+  it("statePath is home/state", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(statePath(), "/tmp/x/state");
+  });
+
+  it("leakContextFlagPath is home/state/leak-context-mode", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(leakContextFlagPath(), "/tmp/x/state/leak-context-mode");
+  });
+
+  it("lockFilePath is home/state/.lock", () => {
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(lockFilePath(), "/tmp/x/state/.lock");
+  });
+
+  it("isHomeOverridden reflects env var presence", () => {
+    assert.equal(isHomeOverridden(), false);
+    process.env["REPO_AEGIS_HOME"] = "/tmp/x";
+    assert.equal(isHomeOverridden(), true);
+  });
+});

package/src/paths.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function repoAegisHome(): string {
+  return process.env["REPO_AEGIS_HOME"] ?? join(homedir(), ".config", "repo-aegis");
+}
+
+export function registryPath(home: string = repoAegisHome()): string {
+  return process.env["REPO_AEGIS_REGISTRY"] ?? join(home, "engagements.yaml");
+}
+
+export function markersDir(home: string = repoAegisHome()): string {
+  return process.env["REPO_AEGIS_MARKERS_DIR"] ?? join(home, "markers");
+}
+
+export function flatMarkersPath(home: string = repoAegisHome()): string {
+  return join(home, "markers.txt");
+}
+
+export function statePath(home: string = repoAegisHome()): string {
+  return join(home, "state");
+}
+
+export function leakContextFlagPath(home: string = repoAegisHome()): string {
+  return join(statePath(home), "leak-context-mode");
+}
+
+export function lockFilePath(home: string = repoAegisHome()): string {
+  return join(statePath(home), ".lock");
+}
+
+export function denySetCachePath(home: string = repoAegisHome()): string {
+  return join(statePath(home), "deny-set.cache.json");
+}
+
+/**
+ * Path of the operator audit log. JSON Lines, append-only, chmod 600.
+ * Off by default; opted into via `~/.config/repo-aegis/state/audit-log.json`
+ * (`{ "enabled": true }`). See `audit-log.ts` for the writer and
+ * `cli/commands/audit-log.ts` for the on/off/show/path subcommands.
+ */
+export function auditLogPath(home: string = repoAegisHome()): string {
+  return join(statePath(home), "audit.log");
+}
+
+/**
+ * True if `REPO_AEGIS_HOME` is set in the environment, indicating the user
+ * (or a parent process) has overridden the default home. CLI uses this to
+ * print a stderr warning that the override is in effect.
+ */
+export function isHomeOverridden(): boolean {
+  return process.env["REPO_AEGIS_HOME"] !== undefined;
+}

package/src/redaction.test.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { redactMatch, revealMatch } from "./redaction.js";
+
+describe("redactMatch", () => {
+  it("preview mode: shows first 3 chars + length for long strings", () => {
+    assert.equal(redactMatch("acme-corp", "preview"), "acm***9");
+    assert.equal(redactMatch("betaco", "preview"), "bet***6");
+  });
+
+  it("preview mode: redacts short strings entirely", () => {
+    assert.equal(redactMatch("abc", "preview"), "[redacted]");
+    assert.equal(redactMatch("ab", "preview"), "[redacted]");
+    assert.equal(redactMatch("", "preview"), "[redacted]");
+  });
+
+  it("preview mode is the default", () => {
+    assert.equal(redactMatch("acme-corp"), "acm***9");
+  });
+
+  it("hash mode: returns hex hash + length, deterministic", () => {
+    const a = redactMatch("acme-corp", "hash");
+    const b = redactMatch("acme-corp", "hash");
+    assert.equal(a, b);
+    assert.match(a, /^\[hash:[a-f0-9]{8}:9\]$/);
+  });
+
+  it("hash mode: distinct inputs produce distinct outputs", () => {
+    assert.notEqual(
+      redactMatch("acme-corp", "hash"),
+      redactMatch("betaco", "hash"),
+    );
+  });
+
+  it("position-only mode: always [redacted]", () => {
+    assert.equal(redactMatch("acme-corp", "position-only"), "[redacted]");
+    assert.equal(redactMatch("anything", "position-only"), "[redacted]");
+  });
+
+  it("never includes the literal in any redaction mode", () => {
+    const literal = "veryspecificcustomername";
+    const modes = ["preview", "hash", "position-only"] as const;
+    for (const m of modes) {
+      const out = redactMatch(literal, m);
+      assert.ok(!out.includes(literal), `mode ${m} leaked literal`);
+    }
+  });
+
+  it("handles unicode without crashing", () => {
+    assert.ok(redactMatch("éâô-corp", "preview").length > 0);
+    assert.ok(redactMatch("中文corp", "hash").length > 0);
+  });
+
+  it("preview mode does not split surrogate pairs", () => {
+    // 🔒 is U+1F512, a surrogate pair in UTF-16. .slice(0,3) on the raw
+    // string would split the surrogate; code-point iteration must not.
+    const s = "🔒🔑🔓abcd";
+    const out = redactMatch(s, "preview");
+    // Length is 7 code points; preview returns the first 3 code points + ***N
+    assert.match(out, /^🔒🔑🔓\*\*\*7$/);
+  });
+
+  it("preview mode counts length in code points, not UTF-16 units", () => {
+    const s = "🔒🔑🔓"; // 3 code points, 6 UTF-16 units
+    assert.equal(redactMatch(s, "preview"), "[redacted]"); // length 3 < 4
+  });
+});
+
+describe("revealMatch", () => {
+  it("returns the literal", () => {
+    assert.equal(revealMatch("acme-corp"), "acme-corp");
+  });
+
+  it("is the only function that returns the literal", () => {
+    // Documentary test: enforces by convention that revealMatch is the
+    // single point of literal exposure in the redaction module.
+    assert.equal(typeof revealMatch, "function");
+  });
+});

package/src/redaction.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { createHash } from "node:crypto";
+
+export type RedactionMode = "preview" | "hash" | "position-only";
+
+/**
+ * Redact a matched marker string for safe display.
+ *
+ * Default mode `preview` returns `<first-3-chars>***<length-N>` for matches
+ * of length >= 4, else `[redacted]`. The literal match value never appears
+ * in output that flows to AI agent context (PostToolUse hook output, error
+ * messages, JSON payloads), because the literal match in recent context is
+ * exactly the recency-pressure failure mode the tool exists to prevent.
+ *
+ * `hash` mode returns the first 8 hex chars of SHA-256 + length, useful
+ * when distinct hits should be distinguishable from each other but the
+ * value itself remains opaque.
+ *
+ * `position-only` returns the constant `[redacted]`.
+ */
+export function redactMatch(match: string, mode: RedactionMode = "preview"): string {
+  // Use code-point iteration to avoid splitting surrogate pairs in the
+  // first 3 characters of multi-byte unicode markers.
+  const codePoints = Array.from(match);
+  if (mode === "position-only") return "[redacted]";
+  if (mode === "hash") {
+    const h = createHash("sha256").update(match).digest("hex").slice(0, 8);
+    return `[hash:${h}:${codePoints.length}]`;
+  }
+  // preview
+  if (codePoints.length < 4) return "[redacted]";
+  const head = codePoints.slice(0, 3).join("");
+  return `${head}***${codePoints.length}`;
+}
+
+/**
+ * Pass-through; explicit "this is the literal".
+ *
+ * Should ONLY be called when the user has explicitly opted in via the
+ * `--verbose` CLI flag. Hooks must never pass through this function.
+ *
+ * The previous `REPO_AEGIS_REVEAL_MATCHES` env-var was removed: env
+ * vars propagate to subprocess hooks unintentionally and could cause
+ * literal markers to flow into AI tool-result context.
+ */
+export function revealMatch(match: string): string {
+  return match;
+}