@de-otio/repo-aegis-core 0.2.0

package/src/first-touch.ts

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Phase 1 onboarding: just-in-time classification of a repo from its
+// git remote against the engagement registry. Used by:
+//   - the MCP `aegis_classify_first_touch` tool (agent-facing entry).
+//   - the CLI `repo-aegis hook first-touch` subcommand (Claude Code
+//     SessionStart hook entry).
+//
+// Pure-ish: reads git config / remote URL via execFileSync, reads the
+// registry, mutates only the *per-repo* `git config` (setClass /
+// addEngagement) on the `applied` path. Never mutates the registry —
+// that's a follow-up requiring user confirmation, per the agent guide.
+
+import { execFileSync } from "node:child_process";
+import { loadRegistry, type Engagement, type Registry } from "./registry.js";
+import { RegistryNotFoundError } from "./exceptions.js";
+import { parseRemoteUrl } from "./remote-url.js";
+import { readRepoConfig, setClass, addEngagement } from "./repo.js";
+
+export type FirstTouchSkipReason =
+  | "non-git"
+  | "no-remote"
+  | "non-github-host"
+  | "registry-not-found";
+
+export interface FirstTouchAlreadyClassified {
+  status: "already-classified";
+  class: string;
+  engagements: string[];
+}
+export interface FirstTouchApplied {
+  status: "applied";
+  class: string;
+  engagement: string | null;
+  /**
+   * [SEC H-5] follow-up: when the applied path attaches an engagement
+   * with zero markers, surface a warning the agent can show the user.
+   * Closes the window where a freshly registered org has no marker yet.
+   */
+  markerWarning: { engagementId: string; count: 0 } | null;
+}
+export interface FirstTouchNeedsConfirmation {
+  status: "needs-confirmation";
+  remote: string;
+  org: string;
+  /**
+   * [SEC H-5] redacted form the agent should use in any context-bearing
+   * summary. Equal to `org` when the org is too short to redact (< 4 chars).
+   */
+  redactedOrg: string;
+  suggestion:
+    | { newEngagement: { idHint: string } }
+    | { addToExisting: { engagementId: string } }
+    | { addAsPersonal: true };
+}
+export interface FirstTouchSkipped {
+  status: "skipped";
+  reason: FirstTouchSkipReason;
+}
+
+export type FirstTouchResult =
+  | FirstTouchAlreadyClassified
+  | FirstTouchApplied
+  | FirstTouchNeedsConfirmation
+  | FirstTouchSkipped;
+
+/**
+ * [SEC H-5] Redact an org name to `xx***y` form (first 2 + ellipsis +
+ * last 1). For orgs shorter than 4 characters, returns the org as-is —
+ * redaction would be pointless and conspicuous.
+ */
+export function redactOrg(org: string): string {
+  if (org.length < 4) return org;
+  return `${org.slice(0, 2)}***${org.slice(-1)}`;
+}
+
+function readRemote(cwd: string): string | null {
+  try {
+    const out = execFileSync("git", ["remote", "get-url", "origin"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+function tryRegistryMatch(
+  parsedOrg: string,
+):
+  | { class: "public-eligible"; engagement: null }
+  | { class: "customer-coupled"; engagement: Engagement }
+  | null
+  | "registry-not-found" {
+  let reg: Registry;
+  try {
+    reg = loadRegistry();
+  } catch (err) {
+    if (err instanceof RegistryNotFoundError) return "registry-not-found";
+    return null;
+  }
+  const personalOrgs = reg.personalOrgs ?? [];
+  if (personalOrgs.includes(parsedOrg)) {
+    return { class: "public-eligible", engagement: null };
+  }
+  for (const eng of reg.engagements) {
+    if ((eng.githubOrgs ?? []).includes(parsedOrg)) {
+      return { class: "customer-coupled", engagement: eng };
+    }
+  }
+  return null;
+}
+
+export interface FirstTouchOptions {
+  cwd?: string;
+}
+
+export function firstTouchClassify(opts: FirstTouchOptions = {}): FirstTouchResult {
+  const cwd = opts.cwd ?? process.cwd();
+  const repo = readRepoConfig(cwd);
+
+  if (!repo.isGitRepo) {
+    return { status: "skipped", reason: "non-git" };
+  }
+  if (repo.classExplicit) {
+    return {
+      status: "already-classified",
+      class: repo.class,
+      engagements: repo.engagements,
+    };
+  }
+  const remote = readRemote(cwd);
+  if (remote === null) {
+    return { status: "skipped", reason: "no-remote" };
+  }
+  const parsed = parseRemoteUrl(remote);
+  if (parsed === null) {
+    return { status: "skipped", reason: "non-github-host" };
+  }
+  const match = tryRegistryMatch(parsed.org);
+  if (match === "registry-not-found") {
+    return { status: "skipped", reason: "registry-not-found" };
+  }
+  if (match === null) {
+    return {
+      status: "needs-confirmation",
+      remote,
+      org: parsed.org,
+      redactedOrg: redactOrg(parsed.org),
+      suggestion: { newEngagement: { idHint: parsed.org } },
+    };
+  }
+
+  setClass(match.class, cwd);
+  if (match.class === "customer-coupled") {
+    addEngagement(match.engagement.id, cwd);
+  }
+
+  let markerWarning: FirstTouchApplied["markerWarning"] = null;
+  if (match.class === "customer-coupled" && match.engagement.markers.length === 0) {
+    markerWarning = { engagementId: match.engagement.id, count: 0 };
+  }
+  return {
+    status: "applied",
+    class: match.class,
+    engagement: match.class === "customer-coupled" ? match.engagement.id : null,
+    markerWarning,
+  };
+}

package/src/import-graph.test.ts

@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+//
+// Hot-path determinism guard.
+//
+// The deterministic gate (PostToolUse hook, pre-commit, pre-push, render)
+// must remain offline and free of LLM dependencies. This test walks the
+// static import graph from the gate-path entry points and fails if any
+// resolved file lives under `packages/llm/`. It also greps the same set
+// of files for string literals matching `@de-otio/repo-aegis-llm` or
+// `packages/llm`, catching dynamic `import()` / `require(varName)` /
+// templated specifiers that the static walker would otherwise miss.
+//
+// Tests run from the repo root (process.cwd() at `npm test` time). The
+// walk operates on the *compiled* .js sources in each package's `dist/`,
+// not the .ts sources, because that's what actually loads at runtime —
+// any tsc-time conditional or stripped code disappears here naturally.
+
+import { describe, it, before } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+// ---- configuration --------------------------------------------------------
+
+/**
+ * Entry points whose import closure must not touch
+ * `@de-otio/repo-aegis-llm` (or its on-disk path `packages/llm/`).
+ *
+ * Express as relative paths from the repo root; the walker resolves them
+ * to compiled `.js` and then walks `import` / `require` references.
+ */
+const GATE_PATH_ENTRY_POINTS: string[] = [
+  "packages/core/dist/scan.js",
+  "packages/core/dist/render.js",
+  "packages/core/dist/deny-set.js",
+  "packages/cli/dist/commands/check.js",
+  "packages/cli/dist/commands/hook-scan-after-write.js",
+  "packages/cli/dist/commands/render.js",
+];
+
+const FORBIDDEN_PACKAGE_PATTERNS: RegExp[] = [
+  /(?:^|[\\/])packages[\\/]llm[\\/]/,
+  /(?:^|[\\/])@de-otio[\\/]repo-aegis-llm[\\/]/,
+];
+
+// String literals that must not appear in any source file reachable
+// from the gate path (catches dynamic imports the static walker misses).
+const FORBIDDEN_STRING_LITERALS: string[] = [
+  "@de-otio/repo-aegis-llm",
+  "packages/llm",
+  "repo-aegis-llm",
+];
+
+// ---- repo-root resolution -------------------------------------------------
+
+/** Locate the monorepo root by walking up from cwd until package.json's
+ *  `repo-aegis-monorepo` name marker is found. */
+function findRepoRoot(): string {
+  let cur = process.cwd();
+  for (let i = 0; i < 16; i++) {
+    const pkg = join(cur, "package.json");
+    if (existsSync(pkg)) {
+      try {
+        const json = JSON.parse(readFileSync(pkg, "utf8")) as { name?: string };
+        if (json.name === "repo-aegis-monorepo") return cur;
+      } catch {
+        // ignore parse errors at intermediate package.json files
+      }
+    }
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  throw new Error(`could not locate repo-aegis monorepo root from cwd=${process.cwd()}`);
+}
+
+// ---- import extraction ----------------------------------------------------
+
+// Match `import ... from "X"`, `import "X"`, `import("X")`, `require("X")`.
+// Strict on the quote style: only matches single or double quotes (no
+// template literals — those are caught by the string-literal grep step
+// instead, intentionally, since they suggest dynamic resolution).
+const IMPORT_RE =
+  /(?:^|[^\w$])(?:import\s+(?:[\w*${},\s]+\s+from\s+)?|import\s*\(\s*|require\s*\(\s*)["']([^"']+)["']/g;
+
+function extractStaticImportSpecifiers(source: string): string[] {
+  const results: string[] = [];
+  IMPORT_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = IMPORT_RE.exec(source)) !== null) {
+    const spec = m[1];
+    if (spec !== undefined) results.push(spec);
+  }
+  return results;
+}
+
+// ---- specifier resolution -------------------------------------------------
+
+/**
+ * Resolve an ES module specifier to an absolute file path on disk, or
+ * `null` if the specifier is external (a node_modules dependency we
+ * don't follow). Workspace links under `node_modules/@de-otio/...` are
+ * followed via `realpathSync`.
+ */
+function resolveSpecifier(
+  specifier: string,
+  fromFile: string,
+  repoRoot: string,
+): string | null {
+  // Node built-ins (`node:fs`, etc) — skip.
+  if (specifier.startsWith("node:")) return null;
+
+  // Relative — resolve against the importing file.
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    const candidate = resolve(dirname(fromFile), specifier);
+    return resolveFileWithExtensions(candidate);
+  }
+
+  // Workspace package via node_modules symlink.
+  if (specifier.startsWith("@de-otio/")) {
+    const linkPath = join(repoRoot, "node_modules", specifier);
+    if (!existsSync(linkPath)) return null;
+    const real = realpathSync(linkPath);
+    // Resolve to the package's main (typically dist/index.js).
+    const pkgJson = join(real, "package.json");
+    if (!existsSync(pkgJson)) return null;
+    const json = JSON.parse(readFileSync(pkgJson, "utf8")) as { main?: string };
+    const main = json.main ?? "dist/index.js";
+    const mainPath = join(real, main);
+    return resolveFileWithExtensions(mainPath);
+  }
+
+  // External package — skip.
+  return null;
+}
+
+function resolveFileWithExtensions(candidate: string): string | null {
+  if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  for (const ext of [".js", ".cjs", ".mjs"]) {
+    const withExt = candidate + ext;
+    if (existsSync(withExt) && statSync(withExt).isFile()) return withExt;
+  }
+  // index.js inside a directory
+  if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+    const indexJs = join(candidate, "index.js");
+    if (existsSync(indexJs)) return indexJs;
+  }
+  return null;
+}
+
+// ---- graph walk -----------------------------------------------------------
+
+function walkImportGraph(entryPoints: string[], repoRoot: string): Set<string> {
+  const visited = new Set<string>();
+  const stack: string[] = entryPoints.map(p => resolve(repoRoot, p));
+
+  while (stack.length > 0) {
+    const file = stack.pop();
+    if (file === undefined || visited.has(file)) continue;
+    if (!existsSync(file)) {
+      // Entry point not built — surface in test failure.
+      throw new Error(`gate-path entry point not built: ${file}`);
+    }
+    visited.add(file);
+
+    let source: string;
+    try {
+      source = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+
+    const specs = extractStaticImportSpecifiers(source);
+    for (const spec of specs) {
+      const resolved = resolveSpecifier(spec, file, repoRoot);
+      if (resolved !== null && !visited.has(resolved)) {
+        stack.push(resolved);
+      }
+    }
+  }
+
+  return visited;
+}
+
+// ---- the test ------------------------------------------------------------
+
+describe("hot-path determinism guard", () => {
+  let repoRoot: string;
+  let reachable: Set<string>;
+
+  before(() => {
+    repoRoot = findRepoRoot();
+    reachable = walkImportGraph(GATE_PATH_ENTRY_POINTS, repoRoot);
+  });
+
+  it("walks at least one entry point successfully", () => {
+    // Sanity — if this fails, the walker is broken (or no .js was built).
+    assert.ok(reachable.size > 0, "expected at least one reachable file");
+  });
+
+  it("no gate-path file resolves under packages/llm/", () => {
+    const offenders = [...reachable].filter(p =>
+      FORBIDDEN_PACKAGE_PATTERNS.some(re => re.test(relative(repoRoot, p))),
+    );
+    assert.equal(
+      offenders.length,
+      0,
+      `gate path imports forbidden package(s):\n` +
+        offenders.map(o => `  ${relative(repoRoot, o)}`).join("\n"),
+    );
+  });
+
+  // [SEC M-1] Catch dynamic imports / `require(variable)` / templated
+  // specifiers that the static walker would miss. Greps every reachable
+  // file's source for the forbidden literals.
+  it("[SEC M-1] no reachable file contains a literal LLM-package reference", () => {
+    const offenders: Array<{ file: string; literal: string }> = [];
+    for (const file of reachable) {
+      let source: string;
+      try {
+        source = readFileSync(file, "utf8");
+      } catch {
+        continue;
+      }
+      for (const literal of FORBIDDEN_STRING_LITERALS) {
+        if (source.includes(literal)) {
+          offenders.push({ file: relative(repoRoot, file), literal });
+        }
+      }
+    }
+    assert.equal(
+      offenders.length,
+      0,
+      `gate-path file(s) contain forbidden string literal(s):\n` +
+        offenders.map(o => `  ${o.file}  (literal: "${o.literal}")`).join("\n"),
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Richard Myers and contributors.
+// Curated public API surface for `@de-otio/repo-aegis-core`.
+//
+// Every name re-exported below is part of the package's compatibility
+// contract: renaming or removing one is a semver-major change. Items not
+// listed here are intentionally internal — they may be re-shaped at any
+// time without a major bump.
+//
+// To keep an item internal while still allowing intra-monorepo imports
+// (tests, sibling packages reaching into specific modules), tag it with
+// a `/** @internal */` JSDoc comment in its source module rather than
+// re-exporting it from this file. api-extractor / consumers honour the
+// hint; existing deep-path imports continue to resolve.
+
+// ---- paths ---------------------------------------------------------------
+export {
+  repoAegisHome,
+  registryPath,
+  markersDir,
+  statePath,
+  leakContextFlagPath,
+  lockFilePath,
+  denySetCachePath,
+  isHomeOverridden,
+  flatMarkersPath,
+  auditLogPath,
+} from "./paths.js";
+
+// ---- audit log -----------------------------------------------------------
+export {
+  appendAuditRecord,
+  isAuditLogEnabled,
+  setAuditLogEnabled,
+  activeAuditLogPath,
+} from "./audit-log.js";
+export type { AuditRecord } from "./audit-log.js";
+
+// ---- registry ------------------------------------------------------------
+export {
+  loadRegistry,
+  isActive,
+  resolveEngagement,
+  ALWAYS_BLOCK_RESERVED_ID,
+  MAX_SUPPORTED_REGISTRY_SCHEMA_VERSION,
+} from "./registry.js";
+export type { Engagement, Registry, ResolveResult } from "./registry.js";
+
+// ---- remote URL parser ---------------------------------------------------
+export { parseRemoteUrl } from "./remote-url.js";
+export type { ParsedRemote } from "./remote-url.js";
+
+// ---- working-tree resolution (path-aware hook) --------------------------
+export {
+  findEnclosingWorkingTree,
+  resolveGitDir,
+  getRemoteOrg,
+} from "./working-tree.js";
+
+// ---- trust-boundary (path-aware hook) -----------------------------------
+export {
+  computeTrustBoundary,
+  trustBoundariesOverlap,
+} from "./trust-boundary.js";
+export type { TrustBoundary } from "./trust-boundary.js";
+
+// ---- first-touch classification (Phase 1 onboarding) --------------------
+export { firstTouchClassify, redactOrg } from "./first-touch.js";
+export type {
+  FirstTouchResult,
+  FirstTouchOptions,
+  FirstTouchSkipReason,
+  FirstTouchAlreadyClassified,
+  FirstTouchApplied,
+  FirstTouchNeedsConfirmation,
+  FirstTouchSkipped,
+} from "./first-touch.js";
+
+// ---- registry mutation (Phase 2 onboarding) -----------------------------
+export {
+  addMarkerPattern,
+  addMarkerPatterns,
+} from "./registry-mutate.js";
+export type {
+  AddMarkerPatternOptions,
+  AddMarkerPatternResult,
+} from "./registry-mutate.js";
+
+// ---- repo (per-repo config + engagement membership mutators) -------------
+export {
+  readRepoConfig,
+  addEngagement,
+  addEngagements,
+  removeEngagement,
+  setClass,
+  unsetClass,
+  REPO_CLASSES,
+  RepoOverrideError,
+  OVERRIDE_FILENAME,
+} from "./repo.js";
+export type { RepoClass, RepoConfig, RepoOverride } from "./repo.js";
+
+// ---- deny set ------------------------------------------------------------
+export { computeDenySet, ALWAYS_FILE_STEM } from "./deny-set.js";
+export type { DenySet, DenySetFile, DenySetOptions } from "./deny-set.js";
+
+// ---- scan primitives -----------------------------------------------------
+export {
+  scanText,
+  scanFile,
+  scanStagedDiff,
+  scanRange,
+  scanHistory,
+  ALLOW_COMMENT,
+} from "./scan.js";
+export type { ScanHit, SkippedFile, HistoryHit, ScanOptions } from "./scan.js";
+
+// ---- secret-shaped markers (universal, not engagement-scoped) -----------
+export { scanForSecrets, summariseHits } from "./secret-markers.js";
+export type { SecretMarkerKind, SecretMarkerHit } from "./secret-markers.js";
+
+// ---- render --------------------------------------------------------------
+export { renderMarkers, MARKER_FORMAT_VERSION } from "./render.js";
+export type { RenderOptions, RenderedFile, RenderResult } from "./render.js";
+
+// ---- redaction -----------------------------------------------------------
+export { redactMatch, revealMatch } from "./redaction.js";
+export type { RedactionMode } from "./redaction.js";
+
+// ---- regex safety --------------------------------------------------------
+// `validatePattern` (the single-pattern, in-process variant) is tagged
+// `@internal` in its source. Callers should prefer `validatePatterns`
+// (which can run strict, subprocess-backed validation). It remains
+// re-exported here so existing intra-repo imports keep working without
+// a coordinated breaking change.
+export {
+  validatePattern,
+  validatePatterns,
+  validateCombinedSize,
+  getRegexBackend,
+} from "./regex-safety.js";
+export type {
+  PatternValidationResult,
+  ValidatePatternsOptions,
+  RegexBackend,
+} from "./regex-safety.js";
+
+// ---- exceptions ----------------------------------------------------------
+export {
+  RegistryNotFoundError,
+  RegistryParseError,
+  RegistryEncryptedError,
+  NotAGitRepoError,
+  AmbiguousQueryError,
+  EngagementNotFoundError,
+  PatternValidationError,
+  OutsideWorkingTreeError,
+  LockTimeoutError,
+  CustomerCoupledNoEngagementError,
+} from "./exceptions.js";
+
+// ---- exit codes ----------------------------------------------------------
+export { EXIT_OK, EXIT_HIT, EXIT_USAGE } from "./exit-codes.js";
+
+// ---- age (file-encryption helpers) --------------------------------------
+// Wrapper around the `age` CLI. Used by the scan package's
+// `encrypt-query` / `decrypt-query` commands and by the cli's
+// `registry encrypt` / `registry decrypt` commands. The `age` binary
+// is a runtime requirement; absence surfaces as `AgeNotFoundError`.
+export {
+  encryptFile,
+  decryptFile,
+  writeBufferTo,
+  AgeNotFoundError,
+  AgeError,
+} from "./age.js";
+export type { EncryptOptions, DecryptOptions } from "./age.js";
+
+// ---- locking -------------------------------------------------------------
+export { withLock, withLockSync } from "./lock.js";
+export type { LockOptions } from "./lock.js";
+
+// ---- canonical JSON shapes ----------------------------------------------
+export type { RepoJson, EngagementJson } from "./types.js";
+
+// ---- schema helpers ------------------------------------------------------
+// `formatZodError` is the canonical "render a ZodError as a one-line
+// human-readable message" helper. Sibling packages (cli, scan) own their
+// own schemas (classify rules, queries) but import this so error wording
+// is consistent across the surface.
+export { formatZodError, ORG_NAME_REGEX } from "./schemas.js";