@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/_lib/module_detection.ts

@@ -0,0 +1,275 @@
+/**
+ * Detect module root directories from a project tree.
+ *
+ * TypeScript twin of `src/scripts/_lib/module_detection.py` (ADR-200,
+ * Phase 2 Wave 1 batch C). Public API mirrors the Python module exactly —
+ * same exported snake_case names, same return shapes, same confidence
+ * ladder, same read-only / tolerant contract.
+ *
+ * Contract — pure, read-only, tolerant:
+ *
+ * - `detect_module_roots` walks the candidate paths once and reports every
+ *   directory that *exists*. It never creates files, never recurses past
+ *   the first level needed to score confidence, and silently skips paths
+ *   it cannot read.
+ * - The return shape is a list of `ModuleCandidate` objects ordered by
+ *   descending confidence; callers may turn that list straight into
+ *   numbered options.
+ * - Confidence is a three-step ladder:
+ *   - `high` — directory exists *and* its first level contains plausible
+ *     module subdirectories for the stack.
+ *   - `medium` — directory exists but is empty / unclear; still surfaced
+ *     so the installer can ask the user.
+ *   - Absent paths are skipped entirely; they never appear in the output.
+ *
+ * No interactive logic, no settings I/O, no logging side-effects.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Directory entry names that never count as modules. Mirrors the
+ * `modules.skip_dirs` default from
+ * `templates/agents/agent-project-settings.example.yml`.
+ */
+const _SKIP_DIRS: ReadonlySet<string> = new Set(['.module-template', '.example']);
+
+/**
+ * Path segments that exclude a file from module-like detection.
+ * Vendored dependencies, build artefacts, VCS state, IDE config —
+ * never a real module no matter what shape the parent directory has.
+ */
+const _NOISE_SEGMENTS: ReadonlySet<string> = new Set([
+    'vendor',
+    'node_modules',
+    '.git',
+    '.idea',
+    '.vscode',
+    'dist',
+    'build',
+    'tmp',
+    'var',
+    'storage',
+    'bootstrap',
+    'public',
+    '.venv',
+    'venv',
+    '__pycache__',
+]);
+
+/**
+ * Parent directory names that hint at a module layout when their
+ * immediate child is a non-noise segment (i.e. `Modules/User/...`,
+ * `packages/foo/...`). Case-sensitive — `Modules` (Laravel HMVC)
+ * differs from `modules` (Node convention) intentionally; both are
+ * accepted.
+ */
+const _MODULE_PARENTS: ReadonlySet<string> = new Set([
+    'Modules',
+    'modules',
+    'packages',
+    'apps',
+    'internal',
+]);
+
+/**
+ * Return `true` when `rel_path` sits inside a module-shaped tree.
+ *
+ * Heuristic for the `module-detect-on-the-fly` skill: triggered by
+ * repo-relative POSIX paths the agent is about to edit or reference.
+ * A path is *module-like* when:
+ *
+ * 1. None of its segments are in `_NOISE_SEGMENTS` (vendored, build,
+ *    VCS, IDE state — never a real module).
+ * 2. At least one segment matches `_MODULE_PARENTS` AND has a non-noise
+ *    sibling directly underneath (so `Modules/` alone does not trigger,
+ *    but `Modules/User/...` does).
+ *
+ * Pure, case-sensitive on parent names. Empty / dotted / Windows-style
+ * inputs return `false`. The function never touches the filesystem —
+ * callers pass in a path string they already know about.
+ */
+export function is_module_like_path(rel_path: string): boolean {
+    if (!rel_path) {
+        return false;
+    }
+    const normalised = rel_path.replaceAll('\\', '/').replace(/^\/+|\/+$/g, '');
+    if (!normalised) {
+        return false;
+    }
+    const parts = normalised.split('/');
+    for (const segment of parts) {
+        if (_NOISE_SEGMENTS.has(segment)) {
+            return false;
+        }
+    }
+    for (let idx = 0; idx < parts.length - 1; idx += 1) {
+        const segment = parts[idx] as string;
+        if (!_MODULE_PARENTS.has(segment)) {
+            continue;
+        }
+        const child = parts[idx + 1] as string;
+        if (!child || child.startsWith('.')) {
+            continue;
+        }
+        if (_SKIP_DIRS.has(child)) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+
+/**
+ * One detected module-root candidate.
+ *
+ * Fields mirror the JSON shape callers ultimately persist into
+ * `modules.root_paths` (the `path` field) plus metadata used by the
+ * installer to phrase the numbered-options prompt. Mirrors the frozen
+ * `ModuleCandidate` dataclass of the Python original.
+ */
+export interface ModuleCandidate {
+    /** Repo-relative POSIX path of the module root (e.g. `app/Modules`). */
+    readonly path: string;
+
+    /**
+     * Stack identifier — one of `laravel-hmvc`, `symfony-ddd`,
+     * `node-monorepo`, `python-src`, `go-internal`, `composer-src`.
+     */
+    readonly stack: string;
+
+    /**
+     * PHP-style namespace template with `{ModuleName}` placeholder
+     * (e.g. `App\Modules\{ModuleName}`). Empty string for stacks without
+     * a PHP-style namespace (Node, Python, Go).
+     */
+    readonly namespace_template_guess: string;
+
+    /** One of `high` or `medium` per the ladder in the module doc comment. */
+    readonly confidence: string;
+}
+
+/**
+ * Detection rules — order encodes priority when two rules match the same
+ * directory. The third tuple slot is the value emitted as
+ * `namespace_template_guess` on a hit; empty for non-PHP stacks.
+ */
+const _RULES: ReadonlyArray<readonly [string, string, string]> = [
+    ['app/Modules', 'laravel-hmvc', 'App\\Modules\\{ModuleName}'],
+    ['src/Module', 'symfony-ddd', 'App\\Module\\{ModuleName}'],
+    ['packages', 'node-monorepo', ''],
+    ['apps', 'node-monorepo', ''],
+    ['modules', 'node-monorepo', ''],
+    ['src', 'python-src', ''],
+    ['internal', 'go-internal', ''],
+    ['cmd', 'go-internal', ''],
+];
+
+/** Stat helper following symlinks; any error counts as "not there". */
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Single-character uppercase test matching Python's `str.isupper()` for
+ * one-char strings: the char must be cased AND uppercase.
+ */
+function _isUpperChar(ch: string): boolean {
+    if (!ch) {
+        return false;
+    }
+    return ch === ch.toUpperCase() && ch !== ch.toLowerCase();
+}
+
+/** Return first-level subdirectory names of `root` that look like modules. */
+function _list_module_subdirs(root: string): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(root).sort();
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const name of entries) {
+        // Mirrors Python's `entry.is_dir()` — follows symlinks, errors → skip.
+        if (!_isDir(path.join(root, name))) {
+            continue;
+        }
+        if (name.startsWith('.')) {
+            continue;
+        }
+        if (_SKIP_DIRS.has(name)) {
+            continue;
+        }
+        out.push(name);
+    }
+    return out;
+}
+
+/** Return `high` when `subdirs` looks like a populated module root. */
+function _score_confidence(stack: string, root: string, subdirs: readonly string[]): string {
+    if (subdirs.length === 0) {
+        return 'medium';
+    }
+    if (stack === 'laravel-hmvc' || stack === 'symfony-ddd') {
+        const capitalized = subdirs.filter((name) => _isUpperChar(name.slice(0, 1)));
+        return capitalized.length > 0 ? 'high' : 'medium';
+    }
+    if (stack === 'node-monorepo') {
+        const withPkgJson = subdirs.filter((name) => _isFile(path.join(root, name, 'package.json')));
+        return withPkgJson.length > 0 ? 'high' : 'medium';
+    }
+    if (stack === 'python-src') {
+        const withInit = subdirs.filter((name) => _isFile(path.join(root, name, '__init__.py')));
+        return withInit.length > 0 ? 'high' : 'medium';
+    }
+    if (stack === 'go-internal') {
+        return subdirs.length > 0 ? 'high' : 'medium';
+    }
+    return 'medium';
+}
+
+/**
+ * Return module-root candidates discovered under `project_root`.
+ *
+ * Pure read-only scan. Walks each rule in `_RULES`, reports every
+ * directory that exists, and never recurses past the first level needed
+ * to score confidence. Order: `high` first, then `medium`; rule order
+ * breaks ties. Absent paths never appear in the output.
+ */
+export function detect_module_roots(project_root: string): ModuleCandidate[] {
+    const high: ModuleCandidate[] = [];
+    const medium: ModuleCandidate[] = [];
+    for (const [rel_path, stack, namespace_template] of _RULES) {
+        const abs_path = path.join(project_root, rel_path);
+        if (!_isDir(abs_path)) {
+            continue;
+        }
+        const subdirs = _list_module_subdirs(abs_path);
+        const confidence = _score_confidence(stack, abs_path, subdirs);
+        const candidate: ModuleCandidate = {
+            path: rel_path,
+            stack,
+            namespace_template_guess: namespace_template,
+            confidence,
+        };
+        if (confidence === 'high') {
+            high.push(candidate);
+        } else {
+            medium.push(candidate);
+        }
+    }
+    return [...high, ...medium];
+}

package/src/scripts/_lib/node_sqlite.d.ts

@@ -0,0 +1,32 @@
+// Ambient declaration for the slice of `node:sqlite` used by the
+// mcp_telemetry_store / mcp_telemetry_query twins.
+//
+// `@types/node@20` (the version pinned in package.json) does not ship
+// `sqlite.d.ts` — the typings arrived with `node:sqlite`'s stabilization
+// in a later Node line. The twins import `node:sqlite` lazily and guard
+// for its absence at runtime (Node < 22.5 has no module), but `tsc` still
+// needs a type for the import or `npm run typecheck` fails on the pinned
+// types. This declares only the surface the twins touch — `DatabaseSync`,
+// `prepare`/`exec`/`close`, and the `StatementSync` methods used. It is
+// intentionally minimal and does not attempt to mirror the full module.
+declare module 'node:sqlite' {
+    export interface StatementSync {
+        run(...params: unknown[]): { changes: number; lastInsertRowid: number | bigint };
+        get(...params: unknown[]): Record<string, unknown> | undefined;
+        all(...params: unknown[]): Record<string, unknown>[];
+    }
+
+    export interface DatabaseSyncOptions {
+        readOnly?: boolean;
+        open?: boolean;
+        enableForeignKeyConstraints?: boolean;
+        enableDoubleQuotedStringLiterals?: boolean;
+    }
+
+    export class DatabaseSync {
+        constructor(location: string, options?: DatabaseSyncOptions);
+        exec(sql: string): void;
+        prepare(sql: string): StatementSync;
+        close(): void;
+    }
+}

package/src/scripts/_lib/pin_resolver.ts

@@ -0,0 +1,264 @@
+/**
+ * Pin-aware version resolver for the `agent-config` dispatcher.
+ *
+ * TypeScript twin of `src/scripts/_lib/pin_resolver.py` (ADR-200,
+ * Phase 2 / Wave 1 batch B). The dispatcher consults this module
+ * **before** doing any work. If `.agent-settings.yml` carries a
+ * non-empty `agent_config_version` pin and the currently running
+ * package version does not match, the process re-execs via
+ * `npx @event4u/agent-config@<pin> <argv>`.
+ *
+ * Determinism is the goal: a consumer's `npx` cache may resolve to a
+ * different version than the project pinned to, and the resolver
+ * guarantees the pinned version is the one that actually runs.
+ *
+ * Escape hatch: `AGENT_CONFIG_NO_PIN_REEXEC=1` disables the re-exec
+ * entirely (used for local development of the package itself and for
+ * the recursion guard described below).
+ *
+ * Recursion guard: the parent sets `AGENT_CONFIG_PIN_REEXEC_DEPTH=1`
+ * on the child env so the re-exec'd child does not loop if the freshly
+ * spawned `npx` resolves to a still-mismatched version. One re-exec
+ * per process, full stop.
+ *
+ * Port notes (intentional TS adaptations, semantics preserved):
+ * - `read_pin` / `maybe_reexec` are async because the default settings
+ *   loader is loaded via dynamic `import()` (Python uses a deferred
+ *   local import of `scripts._lib.agent_settings`).
+ * - `maybe_reexec` accepts injectable `pin_reader` / `which` seams —
+ *   the test points the pytest suite reaches via `monkeypatch`.
+ * - Node has no `os.execvpe` (true process replacement). The default
+ *   runner spawns the child synchronously with inherited stdio and
+ *   exits with its status — flagged as a divergence candidate.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { EnvMap } from './user_global_paths';
+
+export const PACKAGE_NAME = '@event4u/agent-config';
+export const PIN_KEY = 'agent_config_version';
+export const NO_REEXEC_ENV = 'AGENT_CONFIG_NO_PIN_REEXEC';
+export const REEXEC_DEPTH_ENV = 'AGENT_CONFIG_PIN_REEXEC_DEPTH';
+
+/** Settings-loader shape — mirrors `agent_settings.load_agent_settings(cwd=...)`. */
+export type SettingsLoader = (options: {
+    cwd: string;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;
+
+/** Injectable re-exec runner — mirrors the pytest `runner=` seam. */
+export type ReexecRunner = (npx: string, argv: string[], env: EnvMap) => number;
+
+function _normalize(version: string): string {
+    return version.trim().replace(/^v+/, '');
+}
+
+/**
+ * Return the pinned version from the cascaded settings, or `null`.
+ *
+ * Empty string and missing key both yield `null`. Any loader failure
+ * (including a missing `agent_settings` TS twin while the migration is
+ * in flight) yields `null` — mirroring the Python `except Exception`.
+ */
+export async function read_pin(
+    cwd: string,
+    options: { settings_loader?: SettingsLoader } = {},
+): Promise<string | null> {
+    let settings: Record<string, unknown>;
+    try {
+        let loader = options.settings_loader;
+        if (loader === undefined) {
+            // Deferred local import, mirroring the Python test-override
+            // pattern. Specifier kept dynamic so tsc does not resolve it
+            // eagerly while the agent_settings twin is still being ported.
+            const specifier = './agent_settings';
+            const mod = (await import(specifier)) as {
+                load_agent_settings?: SettingsLoader;
+            };
+            if (typeof mod.load_agent_settings !== 'function') {
+                return null;
+            }
+            loader = mod.load_agent_settings;
+        }
+        settings = await loader({ cwd });
+    } catch {
+        return null;
+    }
+    const raw = settings[PIN_KEY];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const pin = raw.trim();
+    return pin || null;
+}
+
+/** Pure predicate: do we need to re-exec under the pinned version? */
+export function should_reexec(
+    pin: string | null | undefined,
+    installed: string,
+    options: { env?: EnvMap | null } = {},
+): boolean {
+    const env = options.env ?? process.env;
+    if (env[NO_REEXEC_ENV] === '1') {
+        return false;
+    }
+    if (env[REEXEC_DEPTH_ENV] === '1') {
+        return false;
+    }
+    if (!pin) {
+        return false;
+    }
+    if (!installed) {
+        return false;
+    }
+    return _normalize(pin) !== _normalize(installed);
+}
+
+/** Build the `npx` argv that re-execs at the pinned version. */
+export function build_reexec_argv(pin: string, argv: string[]): string[] {
+    return ['npx', '--yes', `${PACKAGE_NAME}@${_normalize(pin)}`, ...argv];
+}
+
+/**
+ * Minimal `shutil.which` equivalent for locating `npx` on PATH.
+ *
+ * Like Python's `shutil.which`, the lookup uses the *real* process
+ * environment's PATH (not the injected env map). On Windows, PATHEXT
+ * extensions are tried (`.cmd`, `.exe`, ...).
+ */
+function _which(cmd: string): string | null {
+    const path_var = process.env.PATH ?? '';
+    const exts =
+        process.platform === 'win32'
+            ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';')
+            : [''];
+    for (const dir of path_var.split(path.delimiter)) {
+        if (!dir) {
+            continue;
+        }
+        for (const ext of exts) {
+            const candidate = path.join(dir, cmd + ext.toLowerCase());
+            try {
+                const st = fs.statSync(candidate);
+                if (st.isFile()) {
+                    if (process.platform !== 'win32') {
+                        fs.accessSync(candidate, fs.constants.X_OK);
+                    }
+                    return candidate;
+                }
+            } catch {
+                // Not here — keep scanning.
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Default runner — closest Node equivalent of `os.execvpe`.
+ *
+ * Divergence candidate (flagged): Node cannot replace the current
+ * process image, so the child runs as a synchronous subprocess with
+ * inherited stdio and the parent exits with the child's status.
+ */
+function _exec_runner(npx: string, argv: string[], env: EnvMap): number {
+    const result = spawnSync(npx, argv.slice(1), {
+        env: env as NodeJS.ProcessEnv,
+        stdio: 'inherit',
+    });
+    // Mirror "never returns on success": terminate with the child status.
+    process.exit(result.status ?? 1);
+}
+
+/**
+ * Re-exec at the pinned version if needed; return the child exit code.
+ *
+ * Returns `null` when no re-exec is performed (caller continues).
+ * The injected `runner` covers the test path — the default runner
+ * replaces the process (see `_exec_runner`).
+ */
+export async function maybe_reexec(
+    installed: string,
+    options: {
+        cwd?: string | null;
+        argv?: string[] | null;
+        env?: EnvMap | null;
+        runner?: ReexecRunner | null;
+        /** Test seam mirroring `monkeypatch.setattr(pr, "read_pin", ...)`. */
+        pin_reader?: (cwd: string) => string | null | Promise<string | null>;
+        /** Test seam mirroring `monkeypatch.setattr(pr.shutil, "which", ...)`. */
+        which?: (cmd: string) => string | null;
+    } = {},
+): Promise<number | null> {
+    const cwd = options.cwd ?? process.cwd();
+    const argv = options.argv ?? process.argv.slice(1);
+    const env = options.env ?? process.env;
+    const pin_reader = options.pin_reader ?? ((c: string) => read_pin(c));
+    const which = options.which ?? _which;
+
+    const pin = await pin_reader(cwd);
+    if (!should_reexec(pin, installed, { env })) {
+        return null;
+    }
+
+    if (pin == null) {
+        // Unreachable — should_reexec only fires with a non-empty pin
+        // (mirrors the Python `assert pin is not None`).
+        throw new Error('maybe_reexec: pin narrowed to null after should_reexec');
+    }
+    const npx = which('npx');
+    if (!npx) {
+        // Cannot re-exec without npx — silently fall back to running
+        // the locally-installed version. Better to do something than
+        // to die because of a missing CLI.
+        return null;
+    }
+
+    const new_argv = build_reexec_argv(pin, argv.length > 0 ? argv.slice(1) : []);
+    const child_env: EnvMap = { ...env };
+    child_env[REEXEC_DEPTH_ENV] = '1';
+
+    const runner = options.runner ?? null;
+    if (runner === null) {
+        // Replaces the current process (exits); never returns on success.
+        return _exec_runner(npx, new_argv, child_env);
+    }
+    return runner(npx, new_argv, child_env);
+}
+
+/** Parse the dispatcher-facing argv: `--cwd X --installed Y -- ARGS`. */
+function _parse_cli(argv: string[]): { cwd: string; installed: string; forward: string[] } {
+    let cwd = process.cwd();
+    let installed = '';
+    let forward: string[] = [];
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === '--cwd' && i + 1 < argv.length) {
+            cwd = argv[i + 1] as string;
+            i += 2;
+        } else if (token === '--installed' && i + 1 < argv.length) {
+            installed = argv[i + 1] as string;
+            i += 2;
+        } else if (token === '--') {
+            forward = argv.slice(i + 1);
+            break;
+        } else {
+            i += 1;
+        }
+    }
+    return { cwd, installed, forward };
+}
+
+// Script entry — mirrors the Python `if __name__ == "__main__"` block.
+if (
+    typeof process.argv[1] === 'string' &&
+    import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+    const { cwd, installed, forward } = _parse_cli(process.argv.slice(2));
+    // Build the argv the child should see: `agent-config <forward...>`.
+    const child_argv = ['agent-config', ...forward];
+    await maybe_reexec(installed, { cwd, argv: child_argv });
+}