@event4u/agent-config 9.8.0 → 9.10.0

package/src/scripts/_lib/duplicate_scope_census.ts

@@ -0,0 +1,77 @@
+/**
+ * Duplicate-scope rule census — the shared byte-comparison primitive behind
+ * both C-2 (`cache_realization_report.ts`'s `computeDuplicateScope`, which
+ * turns this into a share of subagent write volume) and the `doctor`
+ * `duplicate-scope-rules` health check (`_cli/cmd_doctor.ts`), so the two
+ * surfaces can never drift on what counts as "shared" or how a redundant
+ * copy's size is estimated.
+ *
+ * `road-to-cache-economy.md` Phase 3: the same 110 rule
+ * filenames observed at both `~/.claude/rules` (user scope) and
+ * `dist/agent-src/rules` (project scope) on this maintainer's own checkout —
+ * C-2 confirmed at 38.5% of subagent write volume. This module answers only
+ * "which filenames are shared, and how many redundant bytes do they cost" —
+ * the write-volume share and the doctor warning are each computed by their
+ * own caller from this raw census.
+ *
+ * Detection only. Never deletes, never rewrites a user's file — see
+ * `non-destructive-by-default`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface DuplicateScopeCensus {
+    evaluable: boolean;
+    reason?: string | undefined;
+    /** `.md` basenames present in BOTH directories, sorted. */
+    shared_filenames: string[];
+    /** Σ min(userBytes, projectBytes) over shared filenames — the conservative
+     *  estimate of the redundant copy (the roadmap's byte census found the two
+     *  scopes near-identical in size, so the min/max choice rarely matters). */
+    duplicate_chars: number;
+}
+
+/**
+ * For every `.md` filename present in BOTH `userRulesDir` and
+ * `projectRulesDir`, the redundant copy is estimated as the SMALLER of the
+ * two files' byte sizes, summed across all shared filenames.
+ */
+export function censusDuplicateScope(userRulesDir: string, projectRulesDir: string): DuplicateScopeCensus {
+    if (!fs.existsSync(userRulesDir) || !fs.existsSync(projectRulesDir)) {
+        return {
+            evaluable: false,
+            reason: `one or both rule directories are missing (user: ${userRulesDir}, project: ${projectRulesDir})`,
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    const userFiles = new Set(fs.readdirSync(userRulesDir).filter((f) => f.endsWith('.md')));
+    const projectFiles = fs.readdirSync(projectRulesDir).filter((f) => f.endsWith('.md'));
+
+    const shared: string[] = [];
+    let duplicateChars = 0;
+    for (const f of projectFiles) {
+        if (!userFiles.has(f)) continue;
+        shared.push(f);
+        const a = fs.statSync(path.join(userRulesDir, f)).size;
+        const b = fs.statSync(path.join(projectRulesDir, f)).size;
+        duplicateChars += Math.min(a, b);
+    }
+    shared.sort();
+
+    if (shared.length === 0) {
+        return {
+            evaluable: false,
+            reason: 'no shared .md filenames between the two rule scopes — this checkout has no duplicate-scope install',
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    return {
+        evaluable: true,
+        shared_filenames: shared,
+        duplicate_chars: duplicateChars,
+    };
+}

package/src/scripts/_lib/fixtures/secret-detector/negatives.txt

@@ -8,3 +8,8 @@ bundle integrity 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1
 data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAElFTkSuQmCC
 API_KEY=your-key-here
 aws_key = "AKIAZ4Q7WXYT2H9RVBKL"  # secret-allow
+aws docs example AKIAIOSFODNN7EXAMPLE
+stripe_key = "sk_test_placeholder"
+token = "[REDACTED]"
+password = "********"
+checksum sha512-VGhpcyBpcyBub3QgYSBzZWNyZXQgYXQgYWxsIGp1c3QgYSBkaWdlc3Q=

package/src/scripts/_lib/fixtures/secret-detector/positives.txt

@@ -9,3 +9,7 @@ pem|-----BEGIN RSA PRIVATE KEY-----
 jwt|eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
 dburl|postgres://dbuser:s3cr3tpass@db.internal:5432/app
 assignment|api_key = "s3cr3tV4lu3Abc123"
+github-fine-grained|github_pat_11ABCDEFG0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
+env-db-password|DB_PASSWORD=q7Xp2Vr9kLm4Nt8wYz3BdF6h
+env-api-key|API_KEY=Zr4tK9pQx2Wm7Vn3Jb8LcD5f
+dburl-mysql|mysql://svc:P4ssw0rdXyz789@10.0.0.12:3306/prod

package/src/scripts/_lib/install_drift.ts

@@ -0,0 +1,194 @@
+/**
+ * Installer drift report (measurement only, never a gate).
+ *
+ * Compares the sha256 hashes recorded in a project's
+ * `agents/installed-tools.lock` manifest (`kind: 'deployed'` file entries —
+ * written by the installer at deploy time, see `install.ts`'s `_file_entry`)
+ * against the current on-disk content of those same files. A mismatch means
+ * a framework-authoritative file was locally modified since the last
+ * install/upgrade; a missing file means it was deleted. This measures the
+ * "consumers edit framework-authoritative files" premise — it never repairs,
+ * never blocks, and has no opinion on whether drift is good or bad. See
+ * `report_install_drift.ts` (the standalone CLI, always exits 0) and
+ * `install.ts`'s global-install upgrade path (prints the report and
+ * proceeds with the redeploy regardless of what it finds).
+ *
+ * Deliberately does NOT reuse `installed_tools.read_manifest()`: that
+ * module's manual v1/v2 parser silently drops nested `tools[].files[]`
+ * entries on read (documented divergence in that module's header) — exactly
+ * the data this report needs. This module parses the manifest YAML directly
+ * with the `yaml` package (a real dependency of this package, already used
+ * by dozens of sibling scripts) so `sha256` values are read faithfully. It
+ * still reuses `installed_tools.manifest_path()` for path resolution + the
+ * `AGENT_CONFIG_INSTALLED_TOOLS` env override, so there is exactly one place
+ * that decides "where is the manifest".
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+import { manifest_path, type EnvMap } from "./installed_tools.js";
+
+export type DriftStatus = "modified" | "missing";
+
+export interface DriftEntry {
+  /** Tool id the entry is recorded under (`tools[].name` in the manifest). */
+  tool_id: string;
+  /** Resolved on-disk path (absolute when the recorded path was absolute). */
+  path: string;
+  status: DriftStatus;
+  recorded_sha256: string;
+  /** `null` when the file is missing entirely (status === 'missing'). */
+  current_sha256: string | null;
+}
+
+/** Expand a leading `~`, mirroring the sibling helper in `installed_tools.ts`. */
+function expanduser(p: string): string {
+  if (p === "~") {
+    return os.homedir();
+  }
+  if (p.startsWith("~/") || (process.platform === "win32" && p.startsWith("~\\"))) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/** Resolve a manifest-recorded path against the project root (mirrors `cmd_doctor.ts`'s `_resolve_path`). */
+function resolve_entry_path(project_root: string, raw: string): string {
+  const p = expanduser(raw);
+  return path.isAbsolute(p) ? p : path.join(project_root, p);
+}
+
+function sha256_of_file(p: string): string | null {
+  try {
+    return crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the project manifest and return one entry per `kind: 'deployed'` file
+ * whose current on-disk sha256 differs from the recorded value, or which no
+ * longer exists.
+ *
+ * Returns `null` when there is no manifest at all (or it fails to parse) —
+ * distinct from `[]`, which means the manifest was read fine and nothing has
+ * drifted. Never throws.
+ */
+export function collect_drift(project_root: string, env?: EnvMap | null): DriftEntry[] | null {
+  const target = manifest_path(project_root, env);
+
+  let text: string;
+  try {
+    text = fs.readFileSync(target, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let data: unknown;
+  try {
+    data = parseYaml(text, { version: "1.1" });
+  } catch {
+    return null;
+  }
+  if (typeof data !== "object" || data === null) {
+    return null;
+  }
+  const tools = (data as Record<string, unknown>)["tools"];
+  if (!Array.isArray(tools)) {
+    // Manifest parsed fine, just carries no tools — that is "clean", not
+    // "no manifest".
+    return [];
+  }
+
+  const out: DriftEntry[] = [];
+  for (const tool of tools) {
+    if (typeof tool !== "object" || tool === null) {
+      continue;
+    }
+    const t = tool as Record<string, unknown>;
+    const tool_id = t["name"] === undefined ? "" : String(t["name"]);
+    const files = t["files"];
+    if (!Array.isArray(files)) {
+      continue;
+    }
+    for (const entry of files) {
+      if (typeof entry !== "object" || entry === null) {
+        continue;
+      }
+      const e = entry as Record<string, unknown>;
+      if (e["kind"] !== "deployed") {
+        continue;
+      }
+      const recorded_sha256 = e["sha256"];
+      if (typeof recorded_sha256 !== "string" || recorded_sha256 === "") {
+        continue;
+      }
+      const raw_path = e["path"];
+      if (typeof raw_path !== "string" || raw_path === "") {
+        continue;
+      }
+
+      const resolved = resolve_entry_path(project_root, raw_path);
+      if (!fs.existsSync(resolved)) {
+        out.push({
+          tool_id,
+          path: resolved,
+          status: "missing",
+          recorded_sha256,
+          current_sha256: null,
+        });
+        continue;
+      }
+      const current = sha256_of_file(resolved);
+      if (current === recorded_sha256) {
+        continue;
+      }
+      out.push({
+        tool_id,
+        path: resolved,
+        status: "modified",
+        recorded_sha256,
+        current_sha256: current,
+      });
+    }
+  }
+
+  out.sort((a, b) => {
+    if (a.tool_id !== b.tool_id) {
+      return a.tool_id < b.tool_id ? -1 : 1;
+    }
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+  });
+  return out;
+}
+
+/**
+ * Human-readable report body — one line per drifted file plus a summary
+ * line, or an explicit "clean"/"no manifest" line. Never throws.
+ */
+export function format_drift_report(entries: DriftEntry[] | null): string {
+  if (entries === null) {
+    return "Installer drift: no installed-tools manifest found — nothing to report.\n";
+  }
+  if (entries.length === 0) {
+    return "Installer drift: no local modifications detected in framework-authoritative files.\n";
+  }
+
+  const lines: string[] = [];
+  for (const e of entries) {
+    const label = e.status === "missing" ? "missing " : "modified";
+    lines.push(`  ${label}  [${e.tool_id}]  ${e.path}`);
+  }
+  const modified = entries.filter((e) => e.status === "modified").length;
+  const missing = entries.filter((e) => e.status === "missing").length;
+  lines.push("");
+  lines.push(
+    `Installer drift: ${entries.length} framework-authoritative file(s) locally modified ` +
+      `since the last install (${modified} modified, ${missing} missing).`,
+  );
+  return lines.join("\n") + "\n";
+}

package/src/scripts/_lib/managed_agents_folder.ts

@@ -0,0 +1,181 @@
+/**
+ * Detect whether a directory is a project whose `agents/` folder is managed
+ * by this package.
+ *
+ * `.agent-settings.yml` resolution and settings-cascade routing already have
+ * a project-root walker (`find_project_root_with_anchor` in
+ * `_lib/agent_settings.ts`), but that walker answers a different question —
+ * "where does the settings cascade start reading from" — and its `agents/`
+ * check exists only to pick a boundary anchor for that walk (its marker list
+ * mixes package-source-repo-only paths, e.g. `settings/.ai-council.yml`, with
+ * consumer-only paths). It also treats a bare `.git` anywhere in the ancestor
+ * chain as "a project was found", which is the right answer for "where do
+ * settings live" but the wrong answer for "is this THIS package's managed
+ * `agents/` folder" — a third-party repo with an unrelated `agents/`
+ * directory and its own `.git` would resolve to a root there too. No
+ * existing helper answers the narrower managed/unmanaged/not-a-project
+ * question this module exists for.
+ *
+ * Contract — pure, read-only, tolerant:
+ *
+ * - Never writes, never mutates, never touches the network.
+ * - Operates on the given `start` directory directly — it does not walk
+ *   ancestors looking for a project root (that is the caller's job, e.g.
+ *   via `find_project_root` when the caller only has a subdirectory).
+ *   Keeping this helper non-walking keeps it a distinct primitive from the
+ *   settings-root walker above rather than a second, subtly different copy
+ *   of the same walk.
+ * - Silently tolerant of a missing/unreadable `start` — every check falls
+ *   through to `false`, which resolves to `'not-a-project'`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { SECTION_HEADER as _MANAGED_GITIGNORE_HEADER } from '../sync_gitignore.js';
+
+/**
+ * Three-state answer — never a boolean, because "no `agents/` folder" and
+ * "no project at all" route differently downstream (an unmanaged repo is a
+ * candidate for adoption; a bare directory outside any repo is not a
+ * project the P-routing question even applies to).
+ */
+export type ManagedAgentsFolderStatus = 'managed' | 'unmanaged' | 'not-a-project';
+
+/**
+ * Detection predicate — chosen after inspecting what the installer actually
+ * writes into a consumer project (verified against source, not invented):
+ *
+ *   is_project   := <start>/.git exists (file or directory — worktrees and
+ *                    submodules use a `.git` file, not a directory).
+ *   has_agents   := <start>/agents is a directory.
+ *   has_marker   := ANY of —
+ *     (a) <start>/.gitignore contains the managed-block header line
+ *         `# event4u/agent-config` (`SECTION_HEADER` in
+ *         `sync_gitignore.ts`) — installed by `refresh --project` /
+ *         `sync:gitignore`. Strongest signal: the literal package name, so
+ *         a third-party repo carries it only if it also runs this package.
+ *     (b) <start>/agents/overrides/ is a directory — scaffolded by
+ *         `install.ts` for every consumer project (the "guaranteed
+ *         minimal-consumer surface", ADR-020).
+ *     (c) a resolvable `.agent-settings.yml` exists — canonical
+ *         `<start>/agents/settings/.agent-settings.yml`, or the legacy
+ *         `<start>/.agent-settings.yml` fallback (see
+ *         `project_settings_path` in `_lib/agent_settings.ts`).
+ *
+ *   status := has_agents && has_marker  → 'managed'
+ *             is_project (else)         → 'unmanaged'
+ *             otherwise                 → 'not-a-project'
+ *
+ * Rejected alternatives:
+ *
+ *   - `agents/` existence alone (no marker). Rejected: this is exactly the
+ *     false positive the roadmap phase calls out — an unrelated multi-agent
+ *     framework repo, or any project that happens to name a directory
+ *     `agents/`, would read as managed with zero package-specific evidence.
+ *   - Reusing `find_project_root_with_anchor`'s `_AGENTS_DIR_MARKERS` list
+ *     verbatim (`roadmaps`, `settings/.ai-council.yml`,
+ *     `roadmaps-progress.md`, `overrides`). Rejected: two of those four
+ *     (`settings/.ai-council.yml`, `roadmaps-progress.md`) are `pkg`-scope
+ *     only per `docs/contracts/agents-layout.md`'s consumer-slim-profile
+ *     table — they never appear in an installed consumer project, so
+ *     requiring "any one" would under-detect nothing (they're just dead
+ *     weight for the consumer case) but reusing the *function* would also
+ *     inherit its `.git`-anchor and `.agent-settings.yml`-layer-fallback
+ *     semantics, which answer "where is the settings root" rather than
+ *     "is `agents/` managed" (see module docblock).
+ *   - `agents/roadmaps/` as a marker. Rejected: it is listed as "Optional"
+ *     even in the consumer-slim profile — a managed project with zero
+ *     roadmaps yet (the common case right after install) would false-
+ *     negative.
+ */
+function _existsAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        fs.statSync(path.join(dir, ...segments));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _isDirAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFileAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** `true` when `start` sits at the root of a git repository (or worktree). */
+function _isGitProject(start: string): boolean {
+    // `.git` is a directory in a normal clone, a file in a worktree or
+    // submodule checkout — `statSync` (not `lstatSync`) is deliberate so a
+    // broken symlink named `.git` does not count as present.
+    return _existsAt(start, '.git');
+}
+
+/** `true` when `<start>/.gitignore` carries the managed-block header line. */
+function _hasManagedGitignoreBlock(start: string): boolean {
+    if (!_isFileAt(start, '.gitignore')) {
+        return false;
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(start, '.gitignore'), 'utf-8');
+    } catch {
+        return false;
+    }
+    return text
+        .split(/\r\n|\r|\n/)
+        .some((line) => line.trim() === _MANAGED_GITIGNORE_HEADER);
+}
+
+/** `true` when `<start>/agents/overrides` exists as a directory. */
+function _hasOverridesDir(start: string): boolean {
+    return _isDirAt(start, 'agents', 'overrides');
+}
+
+/**
+ * `true` when a resolvable `.agent-settings.yml` exists — canonical
+ * `agents/settings/.agent-settings.yml`, or the legacy repo-root
+ * `.agent-settings.yml`.
+ */
+function _hasResolvableAgentSettings(start: string): boolean {
+    return (
+        _isFileAt(start, 'agents', 'settings', '.agent-settings.yml') ||
+        _isFileAt(start, '.agent-settings.yml')
+    );
+}
+
+/**
+ * Classify `start` as `'managed'` (an `agents/` folder this package
+ * installed and can safely write project facts into), `'unmanaged'` (a real
+ * project — has a `.git` — with no such folder, or an `agents/` folder this
+ * package did not install), or `'not-a-project'` (no `.git` at `start` at
+ * all — e.g. a bare directory outside any repo).
+ *
+ * Read-only. Does not walk ancestors — `start` is checked directly; pass a
+ * project root (e.g. from `find_project_root`) when the caller only has a
+ * subdirectory.
+ */
+export function detect_managed_agents_folder(start: string): ManagedAgentsFolderStatus {
+    if (!_isGitProject(start)) {
+        return 'not-a-project';
+    }
+    const hasAgentsDir = _isDirAt(start, 'agents');
+    const hasMarker =
+        _hasManagedGitignoreBlock(start) ||
+        _hasOverridesDir(start) ||
+        _hasResolvableAgentSettings(start);
+    if (hasAgentsDir && hasMarker) {
+        return 'managed';
+    }
+    return 'unmanaged';
+}