@de-otio/repo-aegis-core 0.2.0

package/src/deny-set.test.ts

@@ -0,0 +1,208 @@
+// 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 { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { computeDenySet, ALWAYS_FILE_STEM } from "./deny-set.js";
+import type { RepoConfig, RepoClass } from "./repo.js";
+
+let tmp: string;
+let markersDir: string;
+
+function setupMarkers() {
+  rmSync(markersDir, { recursive: true, force: true });
+  mkdirSync(markersDir, { recursive: true });
+  writeFileSync(join(markersDir, `${ALWAYS_FILE_STEM}.txt`), "PROJECT-CODENAME-ALPHA\n");
+  writeFileSync(join(markersDir, "customer-a.txt"), "acme-corp\nacme\\.com\n");
+  writeFileSync(join(markersDir, "customer-b.txt"), "betaco\nbetaco\\.tech\n");
+}
+
+function makeRepo(cls: RepoClass, engagements: string[] = []): RepoConfig {
+  return {
+    cwd: "/tmp/fake",
+    isGitRepo: true,
+    class: cls,
+    classExplicit: true,
+    engagements,
+  };
+}
+
+before(() => {
+  tmp = mkdtempSync(join(tmpdir(), "repo-aegis-denyset-"));
+  markersDir = join(tmp, "markers");
+  setupMarkers();
+});
+
+after(() => {
+  rmSync(tmp, { recursive: true, force: true });
+});
+
+describe("computeDenySet", () => {
+  it("returns empty set when markers dir does not exist", () => {
+    const ds = computeDenySet(makeRepo("private-strict"), { markersDir: join(tmp, "no-such-dir") });
+    assert.equal(ds.patterns.length, 0);
+    assert.equal(ds.combinedRegex, "");
+  });
+
+  it("public-eligible: full union (all marker files, no scoping)", () => {
+    const ds = computeDenySet(makeRepo("public-eligible"), { markersDir });
+    assert.equal(ds.files.length, 3);
+    assert.ok(ds.patterns.includes("acme-corp"));
+    assert.ok(ds.patterns.includes("betaco"));
+    assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+  });
+
+  it("private-strict: same as public-eligible", () => {
+    const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+    assert.equal(ds.files.length, 3);
+  });
+
+  it("public-eligible warns if engagement is set", () => {
+    const ds = computeDenySet(
+      makeRepo("public-eligible", ["customer-a"]),
+      { markersDir },
+    );
+    assert.ok(ds.warnings.length > 0);
+    // engagement is ignored: full deny set
+    assert.equal(ds.files.length, 3);
+    assert.ok(ds.patterns.includes("acme-corp"));
+  });
+
+  it("customer-coupled: scopes deny set, excluding own engagement", () => {
+    const ds = computeDenySet(
+      makeRepo("customer-coupled", ["customer-a"]),
+      { markersDir },
+    );
+    const stems = ds.files.map(f => f.stem).sort();
+    assert.deepEqual(stems, [ALWAYS_FILE_STEM, "customer-b"]);
+    assert.ok(ds.patterns.includes("betaco"));
+    assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+    assert.ok(!ds.patterns.includes("acme-corp"));
+  });
+
+  it("customer-coupled: still blocks _always", () => {
+    const ds = computeDenySet(
+      makeRepo("customer-coupled", ["customer-a"]),
+      { markersDir },
+    );
+    assert.ok(ds.patterns.includes("PROJECT-CODENAME-ALPHA"));
+  });
+
+  it("customer-coupled: multi-engagement excludes both own files", () => {
+    const ds = computeDenySet(
+      makeRepo("customer-coupled", ["customer-a", "customer-b"]),
+      { markersDir },
+    );
+    const stems = ds.files.map(f => f.stem).sort();
+    assert.deepEqual(stems, [ALWAYS_FILE_STEM]);
+    assert.ok(!ds.patterns.includes("acme-corp"));
+    assert.ok(!ds.patterns.includes("betaco"));
+  });
+
+  it("customer-coupled: empty engagements still computes deny set (caller enforces error)", () => {
+    const ds = computeDenySet(makeRepo("customer-coupled", []), { markersDir });
+    // Library doesn't enforce the error; that's the CLI's job. Library returns full set.
+    assert.equal(ds.files.length, 3);
+  });
+
+  it("scratch: same scoping as customer-coupled", () => {
+    const ds = computeDenySet(
+      makeRepo("scratch", ["customer-a"]),
+      { markersDir },
+    );
+    assert.equal(ds.files.length, 2);
+  });
+
+  it("strips ; comments and blank lines from marker files", () => {
+    writeFileSync(
+      join(markersDir, "customer-c.txt"),
+      "; comment line\n\nfirst-pattern\n; another comment\nsecond-pattern\n",
+    );
+    const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+    assert.ok(ds.patterns.includes("first-pattern"));
+    assert.ok(ds.patterns.includes("second-pattern"));
+    assert.ok(!ds.patterns.some(p => p.includes("comment")));
+    // restore
+    rmSync(join(markersDir, "customer-c.txt"));
+  });
+
+  it("writes a cache file with the expected shape on miss", () => {
+    const cachePath = join(tmp, "cache-shape.json");
+    const repo = makeRepo("private-strict");
+    const ds = computeDenySet(repo, { markersDir, cachePath });
+    assert.ok(existsSync(cachePath), "cache file written");
+    const cached = JSON.parse(readFileSync(cachePath, "utf8")) as {
+      schemaVersion: number;
+      key: string;
+      files: unknown[];
+      patterns: string[];
+      combinedRegex: string;
+    };
+    assert.equal(cached.schemaVersion, 2);
+    assert.equal(typeof cached.key, "string");
+    assert.equal(cached.key.length, 64, "fingerprint is sha256 hex");
+    assert.deepEqual(cached.patterns, ds.patterns);
+    assert.equal(cached.combinedRegex, ds.combinedRegex);
+  });
+
+  it("invalidates cache when a marker file changes (mtime updated)", () => {
+    const cachePath = join(tmp, "cache-invalidate.json");
+    const repo = makeRepo("private-strict");
+    const ds1 = computeDenySet(repo, { markersDir, cachePath });
+
+    // Change a marker file with a NEW mtime + different size.
+    const acmePath = join(markersDir, "customer-a.txt");
+    writeFileSync(acmePath, "completely-different-content\n");
+
+    const ds2 = computeDenySet(repo, { markersDir, cachePath });
+    assert.notDeepEqual(ds2.patterns, ds1.patterns, "cache must invalidate on marker change");
+    assert.ok(ds2.patterns.includes("completely-different-content"));
+
+    // Restore for downstream tests.
+    setupMarkers();
+  });
+
+  it("cachePath: null disables caching", () => {
+    const repo = makeRepo("private-strict");
+    const initialFiles = readdirSync(tmp).filter(f => f.endsWith(".json")).length;
+    computeDenySet(repo, { markersDir, cachePath: null });
+    const after = readdirSync(tmp).filter(f => f.endsWith(".json")).length;
+    assert.equal(after, initialFiles, "no cache file should be written");
+  });
+
+  it("populates patternSources parallel to patterns", () => {
+    const repo = makeRepo("private-strict");
+    const ds = computeDenySet(repo, { markersDir, cachePath: null });
+    assert.equal(ds.patternSources?.length, ds.patterns.length, "lengths must match");
+    // Spot-check: alphabetical file order is _always, customer-a, customer-b
+    const alwaysIdx = ds.patterns.findIndex(p => p === "PROJECT-CODENAME-ALPHA");
+    if (alwaysIdx >= 0) {
+      assert.equal(ds.patternSources![alwaysIdx], "_always");
+    }
+    const acmeIdx = ds.patterns.findIndex(p => p === "acme-corp");
+    if (acmeIdx >= 0) {
+      assert.equal(ds.patternSources![acmeIdx], "customer-a");
+    }
+  });
+
+  it("preserves mid-line ; characters in marker patterns", () => {
+    // Regression: legitimate patterns containing `;` (e.g. `db;internal`,
+    // `key;value` form codenames) used to be silently truncated at the
+    // first `;`. Only lines whose first non-whitespace character is `;`
+    // are comments.
+    writeFileSync(
+      join(markersDir, "customer-d.txt"),
+      "db;internal\nkey;val;more\n  ; leading-space-comment\n",
+    );
+    const ds = computeDenySet(makeRepo("private-strict"), { markersDir });
+    assert.ok(ds.patterns.includes("db;internal"), "mid-line ; must not truncate");
+    assert.ok(ds.patterns.includes("key;val;more"), "multiple mid-line ; must survive");
+    assert.ok(
+      !ds.patterns.some(p => p.includes("leading-space-comment")),
+      "leading-whitespace ; lines are still comments",
+    );
+    rmSync(join(markersDir, "customer-d.txt"));
+  });
+});

package/src/deny-set.ts

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  denySetCachePath as defaultDenySetCachePath,
+  markersDir as defaultMarkersDir,
+} from "./paths.js";
+import type { RepoConfig } from "./repo.js";
+
+export const ALWAYS_FILE_STEM = "_always";
+
+export interface DenySetFile {
+  stem: string;
+  path: string;
+}
+
+export interface DenySet {
+  files: DenySetFile[];
+  patterns: string[];
+  /**
+   * Parallel to `patterns`: `patternSources[i]` is the file stem (engagement
+   * id or `_always`) that pattern i was loaded from. Used by scanText to
+   * attribute each hit to its source engagement, surfaced as
+   * {@link ScanHit.engagement}.
+   *
+   * Optional for backward compatibility with fixtures and ad-hoc DenySet
+   * literals; runtime callers (computeDenySet) always populate it. When
+   * absent or length-mismatched, scanText falls back to no-attribution.
+   */
+  patternSources?: string[];
+  combinedRegex: string;
+  warnings: string[];
+}
+
+export interface DenySetOptions {
+  markersDir?: string;
+  /**
+   * Path to the cache file. Default: `<home>/state/deny-set.cache.json`.
+   * Pass `null` to disable caching entirely (useful for tests).
+   */
+  cachePath?: string | null;
+}
+
+// Bumped to 2 when patternSources was added; v1 caches are invalidated
+// (the read path's schemaVersion check returns null, falling through to
+// recompute).
+const DENY_SET_CACHE_VERSION = 2;
+
+interface CacheEntry {
+  schemaVersion: number;
+  key: string;
+  files: DenySetFile[];
+  patterns: string[];
+  patternSources: string[];
+  combinedRegex: string;
+  warnings: string[];
+}
+
+/**
+ * Build a fingerprint of the inputs to computeDenySet. Two calls with the
+ * same fingerprint produce the same deny set. Includes:
+ *   - repo class + sorted engagements (these change the per-engagement
+ *     filtering applied to the marker file set)
+ *   - the marker dir's file list, mtimes, and sizes (any edit to a marker
+ *     file or addition/removal invalidates the cache)
+ */
+function computeFingerprint(repo: RepoConfig, dir: string): string {
+  const fileSummaries: string[] = [];
+  if (existsSync(dir)) {
+    const files = readdirSync(dir).filter(f => f.endsWith(".txt")).sort();
+    for (const f of files) {
+      const st = statSync(join(dir, f));
+      fileSummaries.push(`${f}:${st.mtimeMs}:${st.size}`);
+    }
+  }
+  const sortedEng = [...repo.engagements].sort().join(",");
+  const input = `v${DENY_SET_CACHE_VERSION}|${repo.class}|${sortedEng}|${fileSummaries.join(";")}`;
+  return createHash("sha256").update(input).digest("hex");
+}
+
+function readCache(cachePath: string): CacheEntry | null {
+  if (!existsSync(cachePath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8")) as Partial<CacheEntry>;
+    if (
+      parsed.schemaVersion !== DENY_SET_CACHE_VERSION ||
+      typeof parsed.key !== "string" ||
+      !Array.isArray(parsed.files) ||
+      !Array.isArray(parsed.patterns) ||
+      !Array.isArray(parsed.patternSources) ||
+      parsed.patternSources.length !== parsed.patterns.length ||
+      typeof parsed.combinedRegex !== "string" ||
+      !Array.isArray(parsed.warnings)
+    ) {
+      return null;
+    }
+    return parsed as CacheEntry;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cachePath: string, entry: CacheEntry): void {
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify(entry, null, 2), { mode: 0o600 });
+  } catch {
+    /* cache is best-effort; failure to write is not fatal */
+  }
+}
+
+/**
+ * Compute the per-repo deny set. Class-aware:
+ *
+ * - `public-eligible` / `private-strict`: full union (every marker file).
+ *   Engagement field on the repo is ignored; if set, a warning is emitted.
+ * - `customer-coupled`: union of `_always.txt` + every per-engagement file
+ *   whose stem is NOT in this repo's `engagements` list.
+ * - `scratch`: same set as `customer-coupled`, but the caller (the CLI's
+ *   `check`) treats hits as advisory and exits 0.
+ */
+export function computeDenySet(repo: RepoConfig, opts: DenySetOptions = {}): DenySet {
+  const dir = opts.markersDir ?? defaultMarkersDir();
+  const warnings: string[] = [];
+
+  if ((repo.class === "public-eligible" || repo.class === "private-strict") &&
+      repo.engagements.length > 0) {
+    warnings.push(
+      `repo class is ${repo.class} but ${repo.engagements.length} engagement(s) are set; ` +
+        `engagement field is ignored for non-customer-coupled classes`,
+    );
+  }
+
+  // Cache fast-path. Cache is keyed on (class, engagements, marker-file
+  // mtimes+sizes). An exact key match returns the cached deny set without
+  // re-reading any marker file. Caller can disable with cachePath: null
+  // (tests) or override the path. The base warnings (repo-class engagement
+  // mismatch, computed above) are always recomputed so they reflect the
+  // current call rather than what the cache wrote at fingerprint time.
+  const cachePath =
+    opts.cachePath === null ? null : opts.cachePath ?? defaultDenySetCachePath();
+  const fingerprint = computeFingerprint(repo, dir);
+
+  if (cachePath !== null) {
+    const cached = readCache(cachePath);
+    if (cached !== null && cached.key === fingerprint) {
+      return {
+        files: cached.files,
+        patterns: cached.patterns,
+        patternSources: cached.patternSources,
+        combinedRegex: cached.combinedRegex,
+        warnings: [...warnings, ...cached.warnings.filter(w => !warnings.includes(w))],
+      };
+    }
+  }
+
+  if (!existsSync(dir)) {
+    const empty: DenySet = { files: [], patterns: [], patternSources: [], combinedRegex: "", warnings };
+    if (cachePath !== null) {
+      writeCache(cachePath, {
+        schemaVersion: DENY_SET_CACHE_VERSION,
+        key: fingerprint,
+        files: [],
+        patterns: [],
+        patternSources: [],
+        combinedRegex: "",
+        warnings: [],
+      });
+    }
+    return empty;
+  }
+
+  const own = new Set(repo.engagements);
+  const useScoping = repo.class === "customer-coupled" || repo.class === "scratch";
+
+  const files: DenySetFile[] = readdirSync(dir)
+    .filter(f => f.endsWith(".txt"))
+    .map(f => ({ stem: f.replace(/\.txt$/, ""), path: join(dir, f) }))
+    .filter(({ stem }) => {
+      if (stem === ALWAYS_FILE_STEM) return true;
+      if (!useScoping) return true;
+      return !own.has(stem);
+    });
+
+  const patterns: string[] = [];
+  const patternSources: string[] = [];
+  for (const f of files) {
+    const lines = readFileSync(f.path, "utf8").split("\n");
+    for (const raw of lines) {
+      const trimmed = raw.trim();
+      // A line is a comment only if its first non-whitespace character is `;`.
+      // Mid-line `;` is part of the pattern (e.g. `db;internal` is a literal
+      // marker, not "db" with a comment).
+      if (trimmed.length === 0 || trimmed.startsWith(";")) continue;
+      patterns.push(trimmed);
+      patternSources.push(f.stem);
+    }
+  }
+  const result: DenySet = {
+    files,
+    patterns,
+    patternSources,
+    combinedRegex: patterns.join("|"),
+    warnings,
+  };
+
+  if (cachePath !== null) {
+    writeCache(cachePath, {
+      schemaVersion: DENY_SET_CACHE_VERSION,
+      key: fingerprint,
+      files,
+      patterns,
+      patternSources,
+      combinedRegex: result.combinedRegex,
+      // Cache only the input-derived warnings; the call-time class mismatch
+      // warning is recomputed above per call.
+      warnings: [],
+    });
+  }
+
+  return result;
+}

package/src/exceptions.ts

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+import { redactMatch } from "./redaction.js";
+
+export class RegistryNotFoundError extends Error {
+  readonly code = "REGISTRY_NOT_FOUND" as const;
+  constructor(public path: string) {
+    super(`engagement registry not found at ${path}`);
+    this.name = "RegistryNotFoundError";
+  }
+}
+
+export class RegistryParseError extends Error {
+  readonly code = "REGISTRY_PARSE" as const;
+  constructor(public path: string, public override cause: unknown) {
+    super(`failed to parse registry at ${path}: ${(cause as Error).message ?? cause}`);
+    this.name = "RegistryParseError";
+  }
+}
+
+/**
+ * Raised by `loadRegistry` when the plaintext registry path is absent
+ * but a sibling `<path>.age` ciphertext exists. The user (or the agent
+ * on their behalf) must run `repo-aegis registry decrypt --identity
+ * <path>` before any registry-reading command will work.
+ *
+ * Why this is its own error: encrypted-at-rest is the *intended* state
+ * during periods of non-use. Auto-decrypt would defeat the purpose
+ * (any process could read the registry). Surfacing a distinct code
+ * lets the agent guide the user to the right command without trying
+ * to recover blindly.
+ */
+export class RegistryEncryptedError extends Error {
+  readonly code = "REGISTRY_ENCRYPTED" as const;
+  constructor(public path: string, public ciphertextPath: string) {
+    super(
+      `engagement registry at ${path} is encrypted at rest ` +
+        `(ciphertext present at ${ciphertextPath}); ` +
+        `run \`repo-aegis registry decrypt --identity <path>\` first`,
+    );
+    this.name = "RegistryEncryptedError";
+  }
+}
+
+export class NotAGitRepoError extends Error {
+  readonly code = "NOT_GIT_REPO" as const;
+  constructor() {
+    super("not inside a git repository");
+    this.name = "NotAGitRepoError";
+  }
+}
+
+export class AmbiguousQueryError extends Error {
+  readonly code = "AMBIGUOUS_QUERY" as const;
+  constructor(public query: string, public candidateCount: number) {
+    super(`ambiguous engagement query "${query}" (${candidateCount} candidates)`);
+    this.name = "AmbiguousQueryError";
+  }
+}
+
+export class EngagementNotFoundError extends Error {
+  readonly code = "ENGAGEMENT_NOT_FOUND" as const;
+  constructor(public query: string) {
+    super(`no engagement matches "${query}"`);
+    this.name = "EngagementNotFoundError";
+  }
+}
+
+export class PatternValidationError extends Error {
+  readonly code = "PATTERN_VALIDATION" as const;
+  constructor(
+    public invalid: { pattern: string; reason: string; engagementId?: string }[],
+  ) {
+    super(`${invalid.length} marker pattern${invalid.length === 1 ? "" : "s"} failed validation`);
+    this.name = "PatternValidationError";
+  }
+
+  /**
+   * Same shape as {@link invalid} but with each `pattern` field passed
+   * through {@link redactMatch} so the literal customer-derived substring
+   * never leaves the process.
+   *
+   * Marker patterns are user-authored regexes that typically embed
+   * customer-derived strings (e.g. `acmeengineering\.com`). They fall
+   * under the same redaction policy as match values whenever they are
+   * surfaced to JSON, log files, or anything an AI agent might
+   * subsequently read.
+   *
+   * Callers serialising this error to JSON, stderr, or any persisted
+   * artifact should prefer `redactedPatterns`. The raw `invalid` field
+   * remains for the in-process renderer (it needs the literal pattern to
+   * point the user at the offending entry in their own marker file) —
+   * that is an internal contract; do not leak it across a process
+   * boundary.
+   */
+  get redactedPatterns(): { pattern: string; reason: string; engagementId?: string }[] {
+    return this.invalid.map(entry => {
+      const out: { pattern: string; reason: string; engagementId?: string } = {
+        pattern: redactMatch(entry.pattern),
+        reason: entry.reason,
+      };
+      if (entry.engagementId !== undefined) out.engagementId = entry.engagementId;
+      return out;
+    });
+  }
+}
+
+export class OutsideWorkingTreeError extends Error {
+  readonly code = "OUTSIDE_WORKING_TREE" as const;
+  constructor(public path: string, public workingTree: string) {
+    super(`path ${path} is outside the working tree ${workingTree}`);
+    this.name = "OutsideWorkingTreeError";
+  }
+}
+
+export class LockTimeoutError extends Error {
+  readonly code = "LOCK_TIMEOUT" as const;
+  constructor(public lockPath: string) {
+    super(`could not acquire registry lock at ${lockPath} (another repo-aegis process is running?)`);
+    this.name = "LockTimeoutError";
+  }
+}
+
+export class CustomerCoupledNoEngagementError extends Error {
+  readonly code = "CUSTOMER_COUPLED_NO_ENGAGEMENT" as const;
+  constructor() {
+    super(
+      "repo-aegis.class=customer-coupled but no repo-aegis.engagement is set; " +
+        "run `repo-aegis allow <engagement-id>` to declare which engagement(s) " +
+        "this repo legitimately references",
+    );
+    this.name = "CustomerCoupledNoEngagementError";
+  }
+}

package/src/exit-codes.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+export const EXIT_OK = 0;
+export const EXIT_HIT = 1;
+export const EXIT_USAGE = 2;