@event4u/agent-config 8.3.0 → 8.4.1

package/src/scripts/prepack-check.mjs

@@ -2,11 +2,16 @@
 /**
  * prepack-check.mjs — guard the published artifact.
  *
- * Runs during `npm pack` and `npm publish`. Asserts the compiled TS
- * CLI binary exists, is executable, and carries the Node shebang
- * before the tarball is built. Otherwise a silently-broken `dist/`
- * ships and every `npx @event4u/agent-config` greets the consumer
- * with a cryptic `Cannot find module` panic.
+ * Runs during `npm pack` / `npm publish` AND as a dry-run on every PR
+ * (Static Checks workflow). Two gates:
+ *
+ *   1. Compiled-bin shape — the TS CLI binary exists, is executable, and
+ *      carries the Node shebang before the tarball is built. Otherwise a
+ *      silently-broken `dist/` ships and every `npx @event4u/agent-config`
+ *      greets the consumer with a cryptic `Cannot find module` panic.
+ *   2. Shipped-import completeness — every relative import reachable from
+ *      the shipped `src/` trees resolves to a file the `files` whitelist
+ *      actually ships (the 8.3.0 ERR_MODULE_NOT_FOUND class).
  *
  * Folded from external council pass 2026-05-18 (Phase 1.3 acceptance).
  *
@@ -56,6 +61,104 @@ if (head !== SHEBANG) {
 
 process.stderr.write(`prepack-check: ${BIN} OK\n`);
 
+// ---------------------------------------------------------------------------
+// Import-completeness guard: every relative import reachable from the
+// SHIPPED src/ trees must itself resolve to a shipped file. Catches the
+// 8.3.0 class of bug where src/scripts/_lib/claude_settings_hooks.ts
+// imported src/install/atomic.js while the `files` whitelist did not ship
+// src/install/ — the global install then crashed doctor/conformance with
+// ERR_MODULE_NOT_FOUND. Deterministic, no network, no npm pack invocation:
+// the shipped set is derived from the package.json `files` whitelist.
+// ---------------------------------------------------------------------------
+import { readdirSync } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+
+const pkg = JSON.parse(readFileSync(resolve('package.json'), 'utf8'));
+const shippedPrefixes = (pkg.files ?? [])
+    .filter((f) => f.endsWith('/'))
+    .map((f) => f.replace(/\/+$/, '') + '/');
+const shippedFiles = new Set((pkg.files ?? []).filter((f) => !f.endsWith('/')));
+
+function isShipped(relPath) {
+    const posix = relPath.split(sep).join('/');
+    if (shippedFiles.has(posix)) return true;
+    return shippedPrefixes.some((p) => posix.startsWith(p));
+}
+
+function* walk(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = join(dir, e.name);
+        if (e.isDirectory()) {
+            yield* walk(full);
+        } else if (/\.(ts|mts|mjs|js)$/.test(e.name) && !e.name.endsWith('.d.ts')) {
+            yield full;
+        }
+    }
+}
+
+const IMPORT_RE = /(?:from\s+|import\s*\(\s*|require\s*\(\s*)['"](\.\.?\/[^'"]+)['"]/g;
+
+function resolveCandidates(fromDir, spec) {
+    const base = join(fromDir, spec);
+    return [
+        base,
+        base.replace(/\.js$/, '.ts'),
+        base.replace(/\.mjs$/, '.mts'),
+        `${base}.ts`,
+        `${base}.js`,
+        join(base, 'index.ts'),
+        join(base, 'index.js'),
+    ];
+}
+
+const importErrors = [];
+const scanRoots = shippedPrefixes.filter((p) => p.startsWith('src/'));
+for (const root of scanRoots) {
+    for (const file of walk(resolve(root))) {
+        const text = readFileSync(file, 'utf8');
+        for (const m of text.matchAll(IMPORT_RE)) {
+            const spec = m[1];
+            const candidates = resolveCandidates(dirname(file), spec);
+            const hit = candidates.find((c) => {
+                try {
+                    return statSync(c).isFile();
+                } catch {
+                    return false;
+                }
+            });
+            const fileRel = relative(resolve('.'), file);
+            if (hit === undefined) {
+                importErrors.push(`${fileRel}: unresolvable relative import '${spec}'`);
+                continue;
+            }
+            const hitRel = relative(resolve('.'), hit);
+            if (!isShipped(hitRel)) {
+                importErrors.push(
+                    `${fileRel}: imports '${spec}' → ${hitRel}, which is NOT in the ` +
+                        'package.json `files` whitelist (would crash the global install ' +
+                        'with ERR_MODULE_NOT_FOUND)',
+                );
+            }
+        }
+    }
+}
+
+if (importErrors.length > 0) {
+    for (const e of importErrors) {
+        process.stderr.write(`prepack-check: ${e}\n`);
+    }
+    die(`${importErrors.length} shipped import(s) escape the files whitelist.`);
+}
+process.stderr.write(
+    `prepack-check: import-completeness OK (${scanRoots.length} shipped src tree(s) scanned)\n`,
+);
+
 // Optional: invoked with --verbose dumps the size for tarball-budget bookkeeping.
 if (argv.includes('--verbose')) {
     process.stderr.write(`prepack-check: size=${st.size} bytes\n`);

package/src/scripts/surface_probe_hook.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * Duplicate-surface probe — `session_start` hook
+ * (road-to-install-path-convergence Phase 4).
+ *
+ * Cheap runtime self-detection on every install path, even for users who
+ * never run `agent-config doctor`: reads src/config/surface-matrix.yml from
+ * the package root, existence-checks each declared duplicate class, and — at
+ * most once per day — emits ONE stderr nudge naming the duplicate plus the
+ * converge command.
+ *
+ * Contract:
+ *   - fail-open, never blocking — returns 0 on every path, including
+ *     unreadable matrix, corrupted state file, and unwritable state dir.
+ *   - rate-limited via agents/runtime/state/surface-probe.json in the
+ *     CONSUMER project (last_check_utc, 24h window — same precedent as
+ *     _lib/update_check.ts). A corrupted state file counts as "due" and is
+ *     rewritten.
+ *   - suppressed entirely when the surface is clean or when
+ *     install.auto_converge is already true in the global settings (the
+ *     user has standing consent — converge handles it, no nagging).
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { is_replay_mode } from './hooks/state_io.js';
+
+const CHECK_WINDOW_MS = 24 * 60 * 60 * 1000;
+const STATE_REL = ['agents', 'runtime', 'state', 'surface-probe.json'] as const;
+
+function _project_root(): string {
+    const env = process.env['CLAUDE_PROJECT_DIR'] || process.env['AGENT_CONFIG_PROJECT_DIR'];
+    if (env) {
+        return env;
+    }
+    return process.cwd();
+}
+
+function _package_root(): string {
+    const env = process.env['AGENT_CONFIG_PACKAGE_ROOT'];
+    if (env) {
+        return env;
+    }
+    // surface_probe_hook.ts lives at src/scripts/; parents[2] = package root.
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+}
+
+function _readStdinIfNotTty(): void {
+    try {
+        if (!process.stdin.isTTY) {
+            fs.readFileSync(0, 'utf-8');
+        }
+    } catch {
+        /* ignore */
+    }
+}
+
+function _exists(p: string): boolean {
+    try {
+        fs.statSync(p);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+interface ProbeOptions {
+    project_root?: string;
+    package_root?: string;
+    home?: string;
+    global_settings_path?: string;
+    now_ms?: number;
+}
+
+/** Fail-open read of install.auto_converge from the global settings file. */
+function _auto_converge(global_settings_path: string): boolean {
+    try {
+        const raw = parseYaml(fs.readFileSync(global_settings_path, 'utf-8'), { version: '1.1' }) as
+            | Record<string, unknown>
+            | null;
+        const install = raw?.['install'];
+        if (install && typeof install === 'object' && !Array.isArray(install)) {
+            return (install as Record<string, unknown>)['auto_converge'] === true;
+        }
+    } catch {
+        /* absent / unreadable → false */
+    }
+    return false;
+}
+
+function _default_global_settings(home: string): string {
+    return path.join(home, '.event4u', 'agent-config', 'agent-settings.yml');
+}
+
+/** Rate limit: true when the probe already ran inside the window. */
+function _rate_limited(state_path: string, now_ms: number): boolean {
+    try {
+        const raw = JSON.parse(fs.readFileSync(state_path, 'utf-8')) as Record<string, unknown>;
+        const last = raw['last_check_utc'];
+        if (typeof last === 'number' && now_ms - last < CHECK_WINDOW_MS && last <= now_ms) {
+            return true;
+        }
+    } catch {
+        /* missing / corrupted → due */
+    }
+    return false;
+}
+
+function _stamp(state_path: string, now_ms: number): void {
+    try {
+        fs.mkdirSync(path.dirname(state_path), { recursive: true });
+        fs.writeFileSync(state_path, `${JSON.stringify({ last_check_utc: now_ms })}\n`, 'utf-8');
+    } catch {
+        /* unwritable state dir → fail open, probe just runs again next time */
+    }
+}
+
+interface Finding {
+    tool: string;
+    command: string;
+}
+
+function _detect(pkg_root: string, home: string): Finding[] {
+    const matrix_path = path.join(pkg_root, 'src', 'config', 'surface-matrix.yml');
+    let tools: Record<string, unknown> = {};
+    try {
+        const raw = parseYaml(fs.readFileSync(matrix_path, 'utf-8'), { version: '1.1' }) as Record<
+            string,
+            unknown
+        >;
+        const t = raw?.['tools'];
+        if (t && typeof t === 'object' && !Array.isArray(t)) {
+            tools = t as Record<string, unknown>;
+        }
+    } catch {
+        return []; // unreadable matrix → fail open, no nudge
+    }
+
+    const expand = (p: string): string =>
+        p.startsWith('~/') ? path.join(home, p.slice(2)) : path.join(pkg_root, p);
+
+    const findings: Finding[] = [];
+    for (const [tool_id, entry] of Object.entries(tools)) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            continue;
+        }
+        const e = entry as Record<string, unknown>;
+        const dup = e['duplicate'] as Record<string, unknown> | undefined;
+        const detect = dup?.['detect'] as Record<string, unknown> | undefined;
+        const all_of = detect?.['all_of'];
+        if (!Array.isArray(all_of) || all_of.length === 0) {
+            continue;
+        }
+        const present = all_of.every((p) => typeof p === 'string' && _exists(expand(p)));
+        if (!present) {
+            continue;
+        }
+        const conv = e['converge'] as Record<string, unknown> | undefined;
+        findings.push({ tool: tool_id, command: String(conv?.['command'] ?? '') });
+    }
+    return findings;
+}
+
+export function main(argv?: string[], opts: ProbeOptions = {}): number {
+    void argv;
+    _readStdinIfNotTty();
+
+    // Replay contract (state_io): fixture re-execution must not mutate
+    // state or emit nudges — the probe is a live-session UX concern only.
+    if (is_replay_mode()) {
+        return 0;
+    }
+
+    try {
+        const project_root = opts.project_root ?? _project_root();
+        const pkg_root = opts.package_root ?? _package_root();
+        const home = opts.home ?? os.homedir();
+        const global_settings = opts.global_settings_path ?? _default_global_settings(home);
+        const now_ms = opts.now_ms ?? Date.now();
+
+        const state_path = path.join(project_root, ...STATE_REL);
+        if (_rate_limited(state_path, now_ms)) {
+            return 0;
+        }
+        _stamp(state_path, now_ms);
+
+        if (_auto_converge(global_settings)) {
+            return 0; // standing consent — converge owns the cleanup, no nag
+        }
+
+        const findings = _detect(pkg_root, home);
+        if (findings.length === 0) {
+            return 0; // clean surface — fully silent
+        }
+
+        const tools = findings.map((f) => f.tool).join(', ');
+        const fix = findings.find((f) => f.command !== '')?.command ?? '';
+        process.stderr.write(
+            `[surface] duplicate install surface: ${tools} — run: agent-config converge` +
+                `${fix ? ` (or: ${fix})` : ''}\n`,
+        );
+        return 0;
+    } catch {
+        return 0; // fail-open — a probe must never block a session
+    }
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main(process.argv.slice(2)));
+}