@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/bench_hook_latency.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env tsx
+/**
+ * bench_hook_latency — standing, published hook-dispatch latency harness.
+ *
+ * road-to-credible-install Phase 1: the 9.8.0 external review measured
+ * ~1.6 s p50 per PreToolUse dispatch (CLI → bash → tsx → per-concern tsx
+ * re-spawn). The precompiled single-process dispatcher (dist/hooks/
+ * dispatch.js) replaces that chain; THIS harness is the re-runnable proof
+ * and the regression net. An external reviewer runs it from a fresh clone:
+ *
+ *     npm ci && npm run build:cli && npm run build:hooks
+ *     ./scripts-run src/scripts/bench_hook_latency            # measure + print
+ *     ./scripts-run src/scripts/bench_hook_latency --gate     # enforce budget
+ *     ./scripts-run src/scripts/bench_hook_latency --update   # record numbers
+ *
+ * Method (pinned so numbers reproduce):
+ *   - N invocations per hook event (default 50, --runs N) of
+ *     `node dist/hooks/dispatch.js --platform claude --event <e>` with a
+ *     synthetic payload on stdin and a throwaway temp workspace as
+ *     --project-dir (concern state lands there, never in the repo).
+ *   - AGENT_CONFIG_REPLAY=1 (feedback-dir writes off — measures dispatch,
+ *     not audit-trail I/O).
+ *   - Wall-clock per invocation around spawnSync; p50/p95 per event.
+ *
+ * Gate semantics (--gate):
+ *   - pre_tool_use p95 must be ≤ budgets_ms.pre_tool_use.p95_ci
+ *   - every event p95 must be ≤ budgets_ms.any_hook_event.p95_ci
+ *   - when docs/hook-latency.json exists, a p95 regression beyond
+ *     regression_gate.max_regression_pct fails.
+ *   Budgets: src/config/hook-latency-budget.json (pre-registered, owner +
+ *   review date — see the Phase-6 budget-ownership lint).
+ *
+ * Exit codes: 0 green · 1 budget/regression exceeded · 2 internal error.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const BUNDLE = path.join(REPO_ROOT, 'dist', 'hooks', 'dispatch.js');
+const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'hook-latency-budget.json');
+const RESULTS_PATH = path.join(REPO_ROOT, 'docs', 'hook-latency.json');
+
+const EVENTS: readonly string[] = [
+    'pre_tool_use',
+    'post_tool_use',
+    'user_prompt_submit',
+    'stop',
+    'session_start',
+    'session_end',
+];
+
+interface EventResult {
+    event: string;
+    runs: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+}
+
+function percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) return 0;
+    const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[Math.max(0, idx)] as number;
+}
+
+function syntheticPayload(event: string, workspace: string): string {
+    // Claude-shaped payload; concerns read tool_name/tool_input for
+    // pre/post_tool_use. A plain Read is the common non-matching case —
+    // the fast path consumers pay on every tool call.
+    return JSON.stringify({
+        session_id: 'bench-hook-latency',
+        cwd: workspace,
+        hook_event_name: event,
+        tool_name: 'Read',
+        tool_input: { file_path: path.join(workspace, 'README.md') },
+    });
+}
+
+export function benchEvent(event: string, runs: number, workspace: string): EventResult {
+    const durations: number[] = [];
+    const payload = syntheticPayload(event, workspace);
+    for (let i = 0; i < runs; i += 1) {
+        const started = performance.now();
+        const proc = spawnSync(
+            process.execPath,
+            [
+                BUNDLE,
+                '--platform',
+                'claude',
+                '--event',
+                event,
+                '--project-dir',
+                workspace,
+            ],
+            {
+                input: payload,
+                encoding: 'utf-8',
+                env: { ...process.env, AGENT_CONFIG_REPLAY: '1' },
+                timeout: 60000,
+            },
+        );
+        const elapsed = performance.now() - started;
+        if (proc.error) {
+            throw new Error(`dispatch failed on ${event}: ${proc.error.message}`);
+        }
+        durations.push(elapsed);
+    }
+    durations.sort((a, b) => a - b);
+    return {
+        event,
+        runs,
+        p50_ms: Math.round(percentile(durations, 50)),
+        p95_ms: Math.round(percentile(durations, 95)),
+        max_ms: Math.round(durations[durations.length - 1] as number),
+    };
+}
+
+function loadJson<T>(p: string): T | null {
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8')) as T;
+    } catch {
+        return null;
+    }
+}
+
+interface Budget {
+    budgets_ms: {
+        pre_tool_use: { p95_ci: number };
+        any_hook_event: { p95_ci: number };
+    };
+    regression_gate: { max_regression_pct: number };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const gate = argv.includes('--gate');
+    const update = argv.includes('--update');
+    const runsIdx = argv.indexOf('--runs');
+    const runs = runsIdx >= 0 ? Number.parseInt(argv[runsIdx + 1] ?? '50', 10) : 50;
+
+    if (!fs.existsSync(BUNDLE)) {
+        process.stderr.write(
+            `bench_hook_latency: bundle missing at ${BUNDLE} — run \`npm run build:hooks\` first\n`,
+        );
+        return 2;
+    }
+    const budget = loadJson<Budget>(BUDGET_PATH);
+    if (budget === null) {
+        process.stderr.write(`bench_hook_latency: budget file missing/invalid at ${BUDGET_PATH}\n`);
+        return 2;
+    }
+
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-hook-bench-'));
+    const results: EventResult[] = [];
+    try {
+        for (const event of EVENTS) {
+            const r = benchEvent(event, runs, workspace);
+            results.push(r);
+            process.stdout.write(
+                `${event.padEnd(20)} p50 ${String(r.p50_ms).padStart(5)} ms · p95 ${String(r.p95_ms).padStart(5)} ms · max ${String(r.max_ms).padStart(5)} ms (n=${r.runs})\n`,
+            );
+        }
+    } finally {
+        fs.rmSync(workspace, { recursive: true, force: true });
+    }
+
+    let failed = false;
+    const prior = loadJson<{ results: EventResult[] }>(RESULTS_PATH);
+    for (const r of results) {
+        const anyCap = budget.budgets_ms.any_hook_event.p95_ci;
+        const cap = r.event === 'pre_tool_use' ? budget.budgets_ms.pre_tool_use.p95_ci : anyCap;
+        if (gate && r.p95_ms > cap) {
+            process.stderr.write(
+                `❌  ${r.event}: p95 ${r.p95_ms} ms exceeds the pre-registered budget (${cap} ms)\n`,
+            );
+            failed = true;
+        }
+        if (gate && prior !== null) {
+            const prev = prior.results.find((x) => x.event === r.event);
+            if (prev !== undefined && prev.p95_ms > 0) {
+                const regressionPct = ((r.p95_ms - prev.p95_ms) / prev.p95_ms) * 100;
+                if (regressionPct > budget.regression_gate.max_regression_pct) {
+                    process.stderr.write(
+                        `❌  ${r.event}: p95 regressed ${Math.round(regressionPct)}% vs recorded ` +
+                            `${prev.p95_ms} ms (allowed: ${budget.regression_gate.max_regression_pct}%)\n`,
+                    );
+                    failed = true;
+                }
+            }
+        }
+    }
+
+    if (update) {
+        const doc = {
+            _comment:
+                'Recorded hook-dispatch latency (bench_hook_latency --update). Method pinned in src/scripts/bench_hook_latency.ts; budgets in src/config/hook-latency-budget.json. Re-run from a fresh clone to reproduce.',
+            recorded_at: new Date().toISOString(),
+            node: process.version,
+            platform: `${os.platform()}-${os.arch()}`,
+            hardware_note: 'see hook-latency-budget.json hardware_reference — CI numbers are the gated ones',
+            runs_per_event: runs,
+            results,
+        };
+        fs.writeFileSync(RESULTS_PATH, `${JSON.stringify(doc, null, 4)}\n`);
+        process.stdout.write(`recorded → ${path.relative(REPO_ROOT, RESULTS_PATH)}\n`);
+    }
+
+    if (failed) return 1;
+    process.stdout.write(gate ? '✅  hook-latency budget met\n' : 'ℹ️  measurement only (no gate)\n');
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/build_mcp_catalog.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env tsx
+/**
+ * `consumer_tool_catalog.json` generator — Phase 3 of road-to-credible-install
+ * (MCP hygiene: generated truth, honest stubs).
+ *
+ * The catalog used to be hand-maintained: every tool's name / description /
+ * input_schema had to be kept in sync BY HAND across the JSON file AND its
+ * real handler registration in `mcp_server/tools.ts`. This script derives
+ * the JSON from the actual registries instead of a third hand-edited copy:
+ *
+ *   - implemented tools — `ALLOWLIST` in `mcp_server/tools.ts`. Name,
+ *     description, input_schema, and side_effect all come straight off the
+ *     handler registration.
+ *   - stub-only tools    — `STUB_TOOLS` in `mcp_server/tool_catalog_source.ts`.
+ *     Catalog-listed discovery placeholders with no wired handler.
+ *
+ * Every stub entry's description is prefixed with the literal marker
+ * `[stub — implemented on demand] ` so a client can tell a discovery
+ * placeholder from a real tool without cross-checking `implemented_on`.
+ * Every implemented entry additionally carries an `annotations.readOnlyHint`
+ * derived from its `side_effect`.
+ *
+ * CLI contract (same `--write` / `--strict` shape as
+ * `build_discovery_manifest.ts`):
+ *   --write   regenerate and persist the catalog deterministically (tools
+ *             sorted by name, stable key order, 2-space indent).
+ *   --strict  quality gate on the freshly-built content (no duplicate name
+ *             across the two registries, non-empty tool list); when NOT
+ *             combined with --write, ALSO diffs the fresh content against
+ *             the committed file and fails on any drift — the CI gate that
+ *             catches a hand-edit or a registry change nobody regenerated
+ *             the catalog for.
+ *   --quiet   suppress the stdout summary line.
+ * Bare invocation (no flags) prints the freshly-built JSON to stdout,
+ * mirroring `build_discovery_manifest.ts`'s non-write default.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { ALLOWLIST, type ToolSideEffect } from './mcp_server/tools.js';
+import { CATALOG_DESCRIPTION, STUB_TOOLS } from './mcp_server/tool_catalog_source.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'build_mcp_catalog';
+
+// src/scripts/build_mcp_catalog.ts → repo root is two dirs up.
+const _DEFAULT_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+interface ModuleConfig {
+    ROOT: string;
+    CATALOG_PATH: string;
+    PACKAGE_JSON: string;
+}
+
+function _deriveConfig(root: string): ModuleConfig {
+    return {
+        ROOT: root,
+        CATALOG_PATH: path.join(root, 'src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json'),
+        PACKAGE_JSON: path.join(root, 'package.json'),
+    };
+}
+
+const _config: ModuleConfig = _deriveConfig(_DEFAULT_ROOT);
+
+/** Test seam — mirrors `build_discovery_manifest.ts`'s `_setConfigForTest`. */
+export function _setConfigForTest(overrides: Partial<ModuleConfig>): void {
+    Object.assign(_config, overrides);
+}
+
+export function _getConfigForTest(): ModuleConfig {
+    return { ..._config };
+}
+
+export const ROOT = (): string => _config.ROOT;
+export const CATALOG_PATH = (): string => _config.CATALOG_PATH;
+
+/** Literal marker every stub-only description starts with. */
+export const STUB_MARKER = '[stub — implemented on demand] ';
+
+interface CatalogEntryOut {
+    name: string;
+    description: string;
+    side_effect: ToolSideEffect;
+    implemented_on: string[];
+    input_schema: Record<string, unknown>;
+    annotations?: { readOnlyHint: boolean };
+}
+
+function _packageName(): string {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(_config.PACKAGE_JSON, 'utf-8')) as { name?: unknown };
+        return typeof pkg.name === 'string' && pkg.name !== '' ? pkg.name : '@event4u/agent-config';
+    } catch {
+        return '@event4u/agent-config';
+    }
+}
+
+/** Mirror Python `str.__lt__` (code-point ordering — matches ASCII tool names). */
+function _cmpStr(a: string, b: string): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Build the deterministic, name-sorted tool-entry list. Throws on a name collision. */
+export function _buildEntries(): CatalogEntryOut[] {
+    const seen = new Set<string>();
+    const entries: CatalogEntryOut[] = [];
+
+    for (const tool of Object.values(ALLOWLIST)) {
+        if (seen.has(tool.name)) {
+            throw new Error(`build_mcp_catalog: duplicate tool name in ALLOWLIST: ${tool.name}`);
+        }
+        seen.add(tool.name);
+        entries.push({
+            name: tool.name,
+            description: tool.description,
+            side_effect: tool.side_effect,
+            implemented_on: ['stdio'],
+            input_schema: tool.input_schema,
+            annotations: { readOnlyHint: tool.side_effect === 'ro' },
+        });
+    }
+
+    for (const stub of STUB_TOOLS) {
+        if (seen.has(stub.name)) {
+            throw new Error(
+                `build_mcp_catalog: '${stub.name}' is registered both in ALLOWLIST ` +
+                    'and STUB_TOOLS — a tool is implemented or a stub, never both.',
+            );
+        }
+        seen.add(stub.name);
+        entries.push({
+            name: stub.name,
+            description: STUB_MARKER + stub.description,
+            side_effect: stub.side_effect,
+            implemented_on: [],
+            input_schema: stub.input_schema,
+        });
+    }
+
+    entries.sort((a, b) => _cmpStr(a.name, b.name));
+    return entries;
+}
+
+/** Build the full catalog document (unserialized). */
+export function _buildCatalog(): Record<string, unknown> {
+    const entries = _buildEntries();
+    if (entries.length === 0) {
+        throw new Error('build_mcp_catalog: computed zero tool entries — refusing an empty catalog');
+    }
+    return {
+        schema_version: 1,
+        description: CATALOG_DESCRIPTION,
+        install_hint_stdio: `npx -y ${_packageName()} mcp-server`,
+        tools: entries,
+    };
+}
+
+/** Deterministic JSON: 2-space indent, trailing newline. Key order = insertion order above. */
+export function _serialize(catalog: Record<string, unknown>): string {
+    return JSON.stringify(catalog, null, 2) + '\n';
+}
+
+/** Freshly-computed catalog file content — the single function both --write and --strict trust. */
+export function _computeFreshContent(): string {
+    return _serialize(_buildCatalog());
+}
+
+function _relativeToRoot(p: string): string {
+    return path.relative(_config.ROOT, p).split(path.sep).join('/');
+}
+
+interface ParsedArgs {
+    write: boolean;
+    strict: boolean;
+    quiet: boolean;
+}
+
+function _argError(msg: string): never {
+    process.stderr.write(`usage: ${_PROG} [-h] [--write] [--strict] [--quiet]\n`);
+    process.stderr.write(`${_PROG}: error: ${msg}\n`);
+    process.exit(2);
+}
+
+export function parse_args(argv: readonly string[]): ParsedArgs {
+    const out: ParsedArgs = { write: false, strict: false, quiet: false };
+    for (const a of argv) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(`usage: ${_PROG} [-h] [--write] [--strict] [--quiet]\n`);
+            process.exit(0);
+        } else if (a === '--write') {
+            out.write = true;
+        } else if (a === '--strict') {
+            out.strict = true;
+        } else if (a === '--quiet') {
+            out.quiet = true;
+        } else {
+            _argError(`unrecognized arguments: ${a}`);
+        }
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] | null = null): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+
+    let fresh: string;
+    try {
+        fresh = _computeFreshContent();
+    } catch (exc) {
+        process.stderr.write(`${_PROG}: ${(exc as Error).message}\n`);
+        return 1;
+    }
+
+    if (args.write) {
+        fs.mkdirSync(path.dirname(_config.CATALOG_PATH), { recursive: true });
+        fs.writeFileSync(_config.CATALOG_PATH, fresh, 'utf-8');
+        if (!args.quiet) {
+            const toolCount = (JSON.parse(fresh) as { tools: unknown[] }).tools.length;
+            process.stdout.write(
+                `wrote ${_relativeToRoot(_config.CATALOG_PATH)} (${toolCount} tool(s))\n`,
+            );
+        }
+        return 0;
+    }
+
+    if (args.strict) {
+        let onDisk: string | null;
+        try {
+            onDisk = fs.readFileSync(_config.CATALOG_PATH, 'utf-8');
+        } catch {
+            onDisk = null;
+        }
+        if (onDisk !== fresh) {
+            process.stderr.write(
+                `❌ ${_relativeToRoot(_config.CATALOG_PATH)} has drifted from the tool registry ` +
+                    '(ALLOWLIST in mcp_server/tools.ts + STUB_TOOLS in ' +
+                    'mcp_server/tool_catalog_source.ts).\n',
+            );
+            process.stderr.write(`   Run: ./scripts-run src/scripts/${_PROG} --write\n`);
+            return 1;
+        }
+        if (!args.quiet) {
+            process.stdout.write(`${_relativeToRoot(_config.CATALOG_PATH)} is in sync with the tool registry\n`);
+        }
+        return 0;
+    }
+
+    // Bare invocation: print the freshly-built JSON to stdout (dry compute,
+    // no write) — mirrors build_discovery_manifest.ts's non-write default.
+    process.stdout.write(fresh);
+    return 0;
+}
+
+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.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/build_mcp_registry_manifest.ts

@@ -45,6 +45,7 @@ interface PathConfig {
     OUT_MANIFEST: string;
     OUT_ROW_MD: string;
     OUT_CF_JSON: string;
+    OUT_SERVER_JSON: string;
 }
 
 function _deriveConfig(root: string): PathConfig {
@@ -58,6 +59,7 @@ function _deriveConfig(root: string): PathConfig {
         OUT_MANIFEST: path.join(outDir, 'registry-manifest.json'),
         OUT_ROW_MD: path.join(outDir, 'awesome-mcp-servers.row.md'),
         OUT_CF_JSON: path.join(outDir, 'mcp-cloudflare-catalogue.json'),
+        OUT_SERVER_JSON: path.join(outDir, 'server.json'),
     };
 }
 
@@ -86,6 +88,17 @@ const REGISTRIES_SEED: ReadonlyArray<JsonObject> = [
         submission_url: 'https://github.com/cloudflare/mcp-server-cloudflare',
         rendered_payload: 'dist/mcp/mcp-cloudflare-catalogue.json',
     },
+    // Official MCP Registry (schema-bump #3 per docs/distribution/
+    // mcp-submission-checklist.md § Submitting to a new registry;
+    // road-to-credible-install Phase 3). Payload is the registry's
+    // server.json; submission itself runs via `mcp-publisher` (human-gated).
+    {
+        id: 'mcp-official-registry',
+        label: 'Official MCP Registry (registry.modelcontextprotocol.io)',
+        listing_format: 'server-json',
+        submission_url: 'https://registry.modelcontextprotocol.io',
+        rendered_payload: 'dist/mcp/server.json',
+    },
 ];
 
 /** Raised to mirror `sys.exit("ERROR: …")` — message to stderr, exit 1. */
@@ -195,6 +208,37 @@ function _render_cf_json(m: JsonObject): string {
     return pyJsonDumps(payload, { indent: 2, sortKeys: true }) + '\n';
 }
 
+/**
+ * Official MCP Registry server.json (registry.modelcontextprotocol.io).
+ * Minimal valid shape per the registry's server.schema.json: reverse-DNS
+ * name (matches package.json `mcpName` + the README `mcp-name:` marker),
+ * the npm package pointer, and the stdio transport. The version is asserted
+ * equal to package.json.version by lint_mcp_registry_manifest (CI).
+ */
+function _render_server_json(m: JsonObject): string {
+    const pkg = m['package'] as JsonObject;
+    const version = pkg['version'] as string;
+    const payload: JsonObject = {
+        $schema: 'https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json',
+        name: 'io.github.event4u-app/agent-config',
+        description: pkg['description'],
+        repository: {
+            url: pkg['repository'],
+            source: 'github',
+        },
+        version,
+        packages: [
+            {
+                registryType: 'npm',
+                identifier: '@event4u/agent-config',
+                version,
+                transport: { type: 'stdio' },
+            },
+        ],
+    };
+    return pyJsonDumps(payload, { indent: 2, sortKeys: true }) + '\n';
+}
+
 interface ParsedArgs {
     write: boolean;
     strict: boolean;
@@ -236,11 +280,13 @@ export function main(argv: readonly string[]): number {
     const manifest_text = pyJsonDumps(manifest, { indent: 2, sortKeys: true }) + '\n';
     const row_md = _render_row_md(manifest);
     const cf_json = _render_cf_json(manifest);
+    const server_json = _render_server_json(manifest);
 
     const outputs: Array<[string, string]> = [
         [_config.OUT_MANIFEST, manifest_text],
         [_config.OUT_ROW_MD, row_md],
         [_config.OUT_CF_JSON, cf_json],
+        [_config.OUT_SERVER_JSON, server_json],
     ];
     const changed = outputs.filter(
         ([p, t]) => !_isFile(p) || fs.readFileSync(p, 'utf-8') !== t,