@gurulu/cli 0.1.0 → 0.1.2

package/scripts/patches/auto-instrument/express.cjs

@@ -0,0 +1,368 @@
+// scripts/patches/auto-instrument/express.cjs — Phase 20 W1 A1.
+//
+// AST-based auto-instrumentation for Express route files. We walk common
+// entry files + `routes/**` and search for `app.<method>('/path', handler)`
+// or `router.<method>('/path', handler)` call expressions. Once we locate
+// the matching call we inject `gurulu.track(...)` inside the handler body
+// (last argument, arrow or function expression).
+//
+// Regex fallback is retained for graceful degradation on parse failure.
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-express';
+const SUPPORTED = ['express'];
+const MARKER = '// @gurulu-instrumented';
+const IMPORT_LINE_ESM = "import { gurulu } from '@/lib/gurulu';";
+const IMPORT_LINE_CJS = "const { gurulu } = require('./lib/gurulu');";
+
+const CANDIDATE_ENTRIES = [
+  'app.js',
+  'server.js',
+  'index.js',
+  'src/app.js',
+  'src/server.js',
+  'src/index.js',
+  'src/app.ts',
+  'src/server.ts',
+  'src/index.ts',
+];
+
+function walkRoutes(repoRoot) {
+  const results = [];
+  const dirs = ['routes', 'src/routes', 'api', 'src/api'];
+  for (const d of dirs) {
+    const abs = path.join(repoRoot, d);
+    if (!fs.existsSync(abs)) continue;
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (entry.isFile() && /\.(js|ts|mjs|cjs)$/.test(entry.name)) {
+        results.push(path.posix.join(d, entry.name));
+      }
+    }
+  }
+  return results;
+}
+
+function parseRoute(routeStr) {
+  if (!routeStr || typeof routeStr !== 'string') return null;
+  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
+  if (!m) return null;
+  return { method: m[1].toUpperCase(), urlPath: m[2].replace(/\/+$/, '') || '/' };
+}
+
+// ---------------------------------------------------------------------------
+// AST path
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all `app.<method>('path', ..., handler)` or `router.<method>(...)`
+ * call expressions matching the given method + urlPath. Returns an array of
+ * `{ fn, body }` entries (the handler arrow/function bodies).
+ */
+function findRouteHandlers(tree, method, urlPath) {
+  const t = ast.t;
+  const results = [];
+  const lowerMethod = method.toLowerCase();
+  ast.traverse(tree, {
+    CallExpression(p) {
+      const callee = p.node.callee;
+      if (!t.isMemberExpression(callee)) return;
+      if (!t.isIdentifier(callee.property) || callee.property.name !== lowerMethod) return;
+      if (!t.isIdentifier(callee.object)) return;
+      const obj = callee.object.name;
+      if (obj !== 'app' && obj !== 'router') return;
+      const args = p.node.arguments;
+      if (args.length < 2) return;
+      if (!t.isStringLiteral(args[0]) || args[0].value !== urlPath) return;
+      // The final argument should be the handler function.
+      const handler = args[args.length - 1];
+      if (
+        (t.isArrowFunctionExpression(handler) || t.isFunctionExpression(handler)) &&
+        t.isBlockStatement(handler.body)
+      ) {
+        results.push({ fn: handler, body: handler.body });
+      }
+    },
+  });
+  return results;
+}
+
+function astInstrumentFile(source, method, urlPath, events) {
+  const tree = ast.parseSource(source);
+  const handlers = findRouteHandlers(tree, method, urlPath);
+  if (handlers.length === 0) {
+    return { ok: false, reason: 'handler-not-found' };
+  }
+  const target = handlers[0];
+  if (ast.hasInstrumentedMarker(target.fn)) {
+    return {
+      ok: true,
+      after: source,
+      instrumented: [],
+      skipped: events.map((e) => ({ event: e.name, reason: 'already-instrumented' })),
+      changed: false,
+    };
+  }
+  const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
+  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
+  ast.ensureGuruluImport(tree);
+  const after = ast.generateSource(tree, source);
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Regex fallback
+// ---------------------------------------------------------------------------
+
+function regexFindHandlerStart(source, method, urlPath) {
+  const lower = method.toLowerCase();
+  const escapedPath = urlPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(
+    `(?:app|router)\\.${lower}\\s*\\(\\s*['"\`]${escapedPath}['"\`]\\s*,`,
+  );
+  const m = re.exec(source);
+  if (!m) return null;
+  let i = m.index + m[0].length;
+  const tail = source.slice(i);
+  const arrowIdx = tail.search(/=>\s*\{/);
+  const funcIdx = tail.search(/function\s*[^(]*\([^)]*\)\s*\{/);
+  let bodyOpen = -1;
+  if (arrowIdx !== -1 && (funcIdx === -1 || arrowIdx < funcIdx)) {
+    bodyOpen = i + tail.indexOf('{', arrowIdx);
+  } else if (funcIdx !== -1) {
+    bodyOpen = i + tail.indexOf('{', funcIdx);
+  }
+  if (bodyOpen === -1) return null;
+  let depth = 0;
+  for (let j = bodyOpen; j < source.length; j++) {
+    const c = source[j];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) return { start: bodyOpen, end: j };
+    }
+  }
+  return null;
+}
+
+function regexFindLastResponseCall(source, start, end) {
+  const snippet = source.slice(start, end);
+  const patterns = [
+    /res\.status\s*\([^)]*\)\s*\.json\s*\(/g,
+    /res\.status\s*\([^)]*\)\s*\.send\s*\(/g,
+    /res\.json\s*\(/g,
+    /res\.send\s*\(/g,
+    /res\.sendStatus\s*\(/g,
+    /res\.end\s*\(/g,
+  ];
+  let lastIdx = -1;
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(snippet)) !== null) {
+      if (m.index > lastIdx) lastIdx = m.index;
+    }
+  }
+  if (lastIdx === -1) return null;
+  const absoluteIdx = start + lastIdx;
+  let lineStart = absoluteIdx;
+  while (lineStart > 0 && source[lineStart - 1] !== '\n') lineStart--;
+  const indentMatch = source.slice(lineStart, absoluteIdx).match(/^(\s*)/);
+  const indent = (indentMatch && indentMatch[1]) || '  ';
+  return { insertAt: lineStart, indent };
+}
+
+function regexEnsureImport(source) {
+  if (source.includes(IMPORT_LINE_ESM) || source.includes(IMPORT_LINE_CJS)) return source;
+  const isCjs = /\brequire\s*\(/.test(source) && !/^import\s/m.test(source);
+  const line = isCjs ? IMPORT_LINE_CJS : IMPORT_LINE_ESM;
+  const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
+  const requireRegex = /^(?:const\s[\s\S]*?require\([\s\S]*?\);\s*\n)+/m;
+  const m = source.match(importRegex) || source.match(requireRegex);
+  if (m) {
+    const end = m.index + m[0].length;
+    return source.slice(0, end) + line + '\n' + source.slice(end);
+  }
+  return line + '\n' + source;
+}
+
+function regexBuildTrackCall(eventName, indent) {
+  const safeName = JSON.stringify(eventName);
+  return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
+}
+
+function regexInstrumentFile(before, method, urlPath, events) {
+  const body = regexFindHandlerStart(before, method, urlPath);
+  if (!body) return { ok: false, reason: 'handler-not-found' };
+  const snippet = before.slice(body.start, body.end);
+  const needed = [];
+  const skipped = [];
+  for (const e of events) {
+    if (snippet.includes(`${MARKER} ${e.name}`)) {
+      skipped.push({ event: e.name, reason: 'already-instrumented' });
+    } else {
+      needed.push(e);
+    }
+  }
+  if (needed.length === 0) return { ok: true, after: before, instrumented: [], skipped, changed: false };
+  const ret = regexFindLastResponseCall(before, body.start, body.end);
+  if (!ret) return { ok: false, reason: 'no-response-found' };
+  const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
+  let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
+  after = regexEnsureImport(after);
+  return {
+    ok: true,
+    after,
+    instrumented: needed.map((e) => e.name),
+    skipped,
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Glue
+// ---------------------------------------------------------------------------
+
+function resolveRouteFile(ctx, method, urlPath) {
+  const seen = new Set();
+  const candidates = [
+    ...CANDIDATE_ENTRIES,
+    ...walkRoutes(ctx.repoRoot),
+  ].filter((rel) => {
+    if (seen.has(rel)) return false;
+    seen.add(rel);
+    return fs.existsSync(path.join(ctx.repoRoot, rel));
+  });
+  for (const rel of candidates) {
+    const src = fs.readFileSync(path.join(ctx.repoRoot, rel), 'utf8');
+    // Cheap pre-filter: must contain `.${method.toLowerCase()}(`.
+    if (!src.includes(`.${method.toLowerCase()}(`)) continue;
+    try {
+      const tree = ast.parseSource(src);
+      const handlers = findRouteHandlers(tree, method, urlPath);
+      if (handlers.length > 0) return { relPath: rel };
+    } catch (_) {
+      // Regex check as last-ditch.
+      if (regexFindHandlerStart(src, method, urlPath)) return { relPath: rel };
+    }
+  }
+  return null;
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'express');
+  const changes = [...helper.changes];
+  const notes = [...helper.notes];
+  let eventsInstrumented = 0;
+  let eventsSkipped = 0;
+
+  if (helper.collision) {
+    return {
+      changes: [],
+      notes,
+      filesModified: 0,
+      eventsInstrumented: 0,
+      eventsSkipped: events ? events.length : 0,
+      collision: true,
+    };
+  }
+
+  const groups = new Map();
+  for (const e of events || []) {
+    const parsed = parseRoute(e && e.source && e.source.route);
+    if (!parsed) {
+      notes.push(`skip:${e && e.name}:no-source-route`);
+      eventsSkipped++;
+      continue;
+    }
+    const resolved = resolveRouteFile(ctx, parsed.method, parsed.urlPath);
+    if (!resolved) {
+      notes.push(`skip:${e.name}:route-not-found`);
+      eventsSkipped++;
+      continue;
+    }
+    const key = `${resolved.relPath}::${parsed.method}::${parsed.urlPath}`;
+    if (!groups.has(key)) {
+      groups.set(key, {
+        relPath: resolved.relPath,
+        method: parsed.method,
+        urlPath: parsed.urlPath,
+        events: [],
+      });
+    }
+    groups.get(key).events.push(e);
+  }
+
+  for (const group of groups.values()) {
+    const abs = path.join(ctx.repoRoot, group.relPath);
+    const before = fs.readFileSync(abs, 'utf8');
+    let res;
+    try {
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events);
+    } catch (err) {
+      const msg = (err && err.message) || String(err);
+      // eslint-disable-next-line no-console
+      console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
+      notes.push(`patch.fallback:${group.relPath}:${msg}`);
+      res = regexInstrumentFile(before, group.method, group.urlPath, group.events);
+    }
+    if (!res.ok) {
+      for (const e of group.events) {
+        notes.push(`skip:${e.name}:${res.reason || 'instrument-failed'}`);
+        eventsSkipped++;
+      }
+      continue;
+    }
+    for (const s of res.skipped || []) {
+      notes.push(`skip:${s.event}:${s.reason}`);
+      eventsSkipped++;
+    }
+    if (!res.changed) continue;
+    // Merge with earlier staged change to the same file (AST already takes
+    // care of dedup-by-marker within a single call, so we just overwrite).
+    const existing = changes.find((c) => c.relPath === group.relPath && c.type === 'auto-instrument');
+    if (existing) {
+      existing.after = res.after;
+    } else {
+      changes.push({
+        relPath: group.relPath,
+        before,
+        after: res.after,
+        reason: `auto-instrument-${group.method}`,
+        type: 'auto-instrument',
+      });
+    }
+    eventsInstrumented += (res.instrumented || []).length;
+  }
+
+  const filesModified = changes.filter((c) => c.type === 'auto-instrument').length;
+  return { changes, notes, filesModified, eventsInstrumented, eventsSkipped, collision: false };
+}
+
+function ensureSingletonHelper(ctx) {
+  return singleton.ensureSingletonHelper(ctx, 'express');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    parseRoute,
+    resolveRouteFile,
+    astInstrumentFile,
+    regexInstrumentFile,
+    walkRoutes,
+    findRouteHandlers,
+  },
+};

package/scripts/patches/auto-instrument/fastify.cjs

@@ -0,0 +1,258 @@
+// scripts/patches/auto-instrument/fastify.cjs — Phase 20 W1 A3.
+//
+// Fastify supports two idiomatic route registration shapes:
+//
+//   fastify.get('/users', async (req, reply) => { ... });
+//   fastify.route({ method: 'GET', url: '/users', handler: async (req, reply) => { ... } });
+//
+// We search the usual server entry files plus `routes/**` for a matching
+// registration, parse the AST, and inject `gurulu.track(...)` into the
+// handler body before the last return.
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-fastify';
+const SUPPORTED = ['fastify'];
+
+const CANDIDATE_ENTRIES = [
+  'app.js',
+  'server.js',
+  'index.js',
+  'src/app.js',
+  'src/server.js',
+  'src/index.js',
+  'src/app.ts',
+  'src/server.ts',
+  'src/index.ts',
+];
+
+function parseEventRoute(routeStr) {
+  if (!routeStr || typeof routeStr !== 'string') return null;
+  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
+  if (!m) return null;
+  return { method: m[1].toUpperCase(), urlPath: m[2].replace(/\/+$/, '') || '/' };
+}
+
+function walkRoutes(repoRoot) {
+  const results = [];
+  const dirs = ['routes', 'src/routes', 'plugins', 'src/plugins'];
+  for (const d of dirs) {
+    const abs = path.join(repoRoot, d);
+    if (!fs.existsSync(abs)) continue;
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (entry.isFile() && /\.(js|ts|mjs|cjs)$/.test(entry.name)) {
+        results.push(path.posix.join(d, entry.name));
+      }
+    }
+  }
+  return results;
+}
+
+function findFastifyHandlers(tree, method, urlPath) {
+  const t = ast.t;
+  const results = [];
+  const lowerMethod = method.toLowerCase();
+
+  ast.traverse(tree, {
+    CallExpression(p) {
+      const callee = p.node.callee;
+      // Shape 1: fastify.get('/users', handler) / app.get(...) — identifier may
+      // be any local name bound to the fastify instance.
+      if (t.isMemberExpression(callee) && t.isIdentifier(callee.property)) {
+        if (callee.property.name === lowerMethod) {
+          const args = p.node.arguments;
+          if (args.length >= 2 && t.isStringLiteral(args[0]) && args[0].value === urlPath) {
+            const handler = args[args.length - 1];
+            if (
+              (t.isArrowFunctionExpression(handler) || t.isFunctionExpression(handler)) &&
+              t.isBlockStatement(handler.body)
+            ) {
+              results.push({ fn: handler, body: handler.body });
+            }
+          }
+        }
+        // Shape 2: fastify.route({ method, url, handler })
+        if (callee.property.name === 'route') {
+          const arg0 = p.node.arguments[0];
+          if (t.isObjectExpression(arg0)) {
+            let m, u, handlerNode;
+            for (const prop of arg0.properties) {
+              if (!t.isObjectProperty(prop)) continue;
+              const key = t.isIdentifier(prop.key) ? prop.key.name : (t.isStringLiteral(prop.key) ? prop.key.value : null);
+              if (!key) continue;
+              if (key === 'method' && t.isStringLiteral(prop.value)) m = prop.value.value.toUpperCase();
+              else if (key === 'url' && t.isStringLiteral(prop.value)) u = prop.value.value;
+              else if (key === 'handler') handlerNode = prop.value;
+            }
+            if (m === method && u === urlPath && handlerNode) {
+              if (
+                (t.isArrowFunctionExpression(handlerNode) || t.isFunctionExpression(handlerNode)) &&
+                t.isBlockStatement(handlerNode.body)
+              ) {
+                results.push({ fn: handlerNode, body: handlerNode.body });
+              }
+            }
+          }
+        }
+      }
+    },
+  });
+  return results;
+}
+
+function astInstrumentFile(source, method, urlPath, events) {
+  const tree = ast.parseSource(source);
+  const handlers = findFastifyHandlers(tree, method, urlPath);
+  if (handlers.length === 0) return { ok: false, reason: 'handler-not-found' };
+  const target = handlers[0];
+  if (ast.hasInstrumentedMarker(target.fn)) {
+    return {
+      ok: true,
+      after: source,
+      instrumented: [],
+      skipped: events.map((e) => ({ event: e.name, reason: 'already-instrumented' })),
+      changed: false,
+    };
+  }
+  const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
+  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
+  ast.ensureGuruluImport(tree);
+  const after = ast.generateSource(tree, source);
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+function resolveRouteFile(ctx, method, urlPath) {
+  const seen = new Set();
+  const candidates = [
+    ...CANDIDATE_ENTRIES,
+    ...walkRoutes(ctx.repoRoot),
+  ].filter((rel) => {
+    if (seen.has(rel)) return false;
+    seen.add(rel);
+    return fs.existsSync(path.join(ctx.repoRoot, rel));
+  });
+  for (const rel of candidates) {
+    const src = fs.readFileSync(path.join(ctx.repoRoot, rel), 'utf8');
+    if (!src.includes(urlPath)) continue;
+    try {
+      const tree = ast.parseSource(src);
+      const h = findFastifyHandlers(tree, method, urlPath);
+      if (h.length > 0) return rel;
+    } catch (_) {
+      // ignore
+    }
+  }
+  return null;
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'fastify');
+  const changes = [...helper.changes];
+  const notes = [...helper.notes];
+  let eventsInstrumented = 0;
+  let eventsSkipped = 0;
+
+  if (helper.collision) {
+    return {
+      changes: [],
+      notes,
+      filesModified: 0,
+      eventsInstrumented: 0,
+      eventsSkipped: events ? events.length : 0,
+      collision: true,
+    };
+  }
+
+  const groups = new Map();
+  for (const e of events || []) {
+    const parsed = parseEventRoute(e && e.source && e.source.route);
+    if (!parsed) {
+      notes.push(`skip:${e && e.name}:no-source-route`);
+      eventsSkipped++;
+      continue;
+    }
+    const rel = resolveRouteFile(ctx, parsed.method, parsed.urlPath);
+    if (!rel) {
+      notes.push(`skip:${e.name}:route-not-found`);
+      eventsSkipped++;
+      continue;
+    }
+    const key = `${rel}::${parsed.method}::${parsed.urlPath}`;
+    if (!groups.has(key)) {
+      groups.set(key, { relPath: rel, method: parsed.method, urlPath: parsed.urlPath, events: [] });
+    }
+    groups.get(key).events.push(e);
+  }
+
+  for (const group of groups.values()) {
+    const abs = path.join(ctx.repoRoot, group.relPath);
+    const before = fs.readFileSync(abs, 'utf8');
+    let res;
+    try {
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events);
+    } catch (err) {
+      const msg = (err && err.message) || String(err);
+      // eslint-disable-next-line no-console
+      console.warn(`[auto-instrument] patch.fallback ${group.relPath}: ${msg}`);
+      notes.push(`patch.fallback:${group.relPath}:${msg}`);
+      continue;
+    }
+    if (!res.ok) {
+      for (const e of group.events) {
+        notes.push(`skip:${e.name}:${res.reason}`);
+        eventsSkipped++;
+      }
+      continue;
+    }
+    for (const s of res.skipped || []) {
+      notes.push(`skip:${s.event}:${s.reason}`);
+      eventsSkipped++;
+    }
+    if (res.changed) {
+      const existing = changes.find((c) => c.relPath === group.relPath && c.type === 'auto-instrument');
+      if (existing) {
+        existing.after = res.after;
+      } else {
+        changes.push({
+          relPath: group.relPath,
+          before,
+          after: res.after,
+          reason: `auto-instrument-fastify`,
+          type: 'auto-instrument',
+        });
+      }
+      eventsInstrumented += (res.instrumented || []).length;
+    }
+  }
+
+  const filesModified = changes.filter((c) => c.type === 'auto-instrument').length;
+  return { changes, notes, filesModified, eventsInstrumented, eventsSkipped, collision: false };
+}
+
+function ensureSingletonHelper(ctx) {
+  return singleton.ensureSingletonHelper(ctx, 'fastify');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    parseEventRoute,
+    walkRoutes,
+    findFastifyHandlers,
+    astInstrumentFile,
+    resolveRouteFile,
+  },
+};

package/scripts/patches/auto-instrument/index.cjs

@@ -0,0 +1,78 @@
+// scripts/patches/auto-instrument/index.cjs — Phase 18.7 B auto-instrument
+// dispatcher.
+//
+// Maps a resolved framework name to the matching auto-instrument module and
+// exposes a single `dispatch(framework, ctx, events)` entry point used by
+// `scripts/gurulu-agentic-install.mjs` and `packages/cli/src/commands/
+// install.ts`. Modules themselves own singleton-helper planning and regex
+// instrumentation; this index is just the registry.
+
+const nextAppRouter = require('./nextjs-app-router.cjs');
+const nextPages = require('./nextjs-pages.cjs');
+const express = require('./express.cjs');
+const viteReact = require('./vite-react.cjs');
+const nestjs = require('./nestjs.cjs');
+const remix = require('./remix.cjs');
+const sveltekit = require('./sveltekit.cjs');
+const astro = require('./astro.cjs');
+const fastify = require('./fastify.cjs');
+const vue = require('./vue.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const MODULES = [
+  nextAppRouter,
+  nextPages,
+  express,
+  viteReact,
+  nestjs,
+  remix,
+  sveltekit,
+  astro,
+  fastify,
+  vue,
+];
+
+const MODULE_BY_FRAMEWORK = {};
+for (const mod of MODULES) {
+  for (const fw of mod.supportedFrameworks) {
+    MODULE_BY_FRAMEWORK[fw] = mod;
+  }
+}
+// Aliases.
+MODULE_BY_FRAMEWORK['nextjs'] = nextAppRouter;
+MODULE_BY_FRAMEWORK['nextjs-app'] = nextAppRouter;
+
+function resolveModule(framework) {
+  if (!framework) return null;
+  return MODULE_BY_FRAMEWORK[framework] || null;
+}
+
+/**
+ * Dispatch: given a framework, context, and a list of ProposedEvents, invoke
+ * the matching module's `instrumentEvents()` and return its plan result. If
+ * no module matches, returns a no-op plan with a note describing why.
+ */
+function dispatch(framework, ctx, events) {
+  const mod = resolveModule(framework);
+  if (!mod) {
+    return {
+      changes: [],
+      notes: [`auto-instrument:no-module-for-${framework || 'auto'}`],
+      filesModified: 0,
+      eventsInstrumented: 0,
+      eventsSkipped: events ? events.length : 0,
+      collision: false,
+      module: null,
+    };
+  }
+  const result = mod.instrumentEvents(ctx, events);
+  return { ...result, module: mod.name };
+}
+
+module.exports = {
+  MODULES,
+  MODULE_BY_FRAMEWORK,
+  resolveModule,
+  dispatch,
+  singleton,
+};