@gurulu/cli 0.4.0 → 0.4.2

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

@@ -0,0 +1,392 @@
+// scripts/patches/auto-instrument/hono.cjs — Phase 20 W1 A4.
+//
+// Hono supports several idiomatic route registration shapes:
+//
+//   app.get('/users', (c) => { ... });
+//   app.post('/orders', async (c) => { ... });
+//   const api = new Hono(); api.get('/users', handler);
+//   app.get('/health', (c) => c.json({ ok: true })).post('/data', async (c) => { ... });
+//
+// 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-hono';
+const SUPPORTED = ['hono'];
+const MARKER = '// @gurulu-instrumented';
+const IMPORT_LINE_ESM = "import { gurulu } from '@/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',
+  'src/main.ts',
+  'src/main.js',
+];
+
+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', 'src/api', 'app', 'src/app'];
+  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;
+}
+
+// ---------------------------------------------------------------------------
+// AST path
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all `app.<method>('path', ..., handler)` or `api.<method>(...)`
+ * or `router.<method>(...)` call expressions matching the given method +
+ * urlPath. Hono apps are typically named `app`, `api`, `router`, or
+ * `server`. Returns an array of `{ fn, body }` entries.
+ */
+function findHonoHandlers(tree, method, urlPath) {
+  const t = ast.t;
+  const results = [];
+  const lowerMethod = method.toLowerCase();
+  const HONO_IDENTIFIERS = new Set(['app', 'api', 'router', 'server']);
+
+  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;
+
+      // The object can be a simple identifier (app.get) or a chained call
+      // expression (app.get('/a', h).post('/b', h) — the object of `.post`
+      // is the preceding CallExpression). We accept identifiers from the
+      // known set, and also any CallExpression (chained).
+      const obj = callee.object;
+      const isKnownIdent = t.isIdentifier(obj) && HONO_IDENTIFIERS.has(obj.name);
+      const isChained = t.isCallExpression(obj);
+      if (!isKnownIdent && !isChained) 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, opts = {}) {
+  const tree = ast.parseSource(source);
+  const handlers = findHonoHandlers(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);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
+  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|api|router|server)\\.${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);
+  // Hono response patterns: c.json(), c.text(), c.html(), c.body(),
+  // c.redirect(), c.notFound()
+  const patterns = [
+    /c\.json\s*\(/g,
+    /c\.text\s*\(/g,
+    /c\.html\s*\(/g,
+    /c\.body\s*\(/g,
+    /c\.redirect\s*\(/g,
+    /c\.notFound\s*\(/g,
+    /return\s+c\./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, opts = {}) {
+  if (source.includes(IMPORT_LINE_ESM)) return source;
+  // Sprint D / D4 — alias-aware specifier.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return source;
+  const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
+  const m = source.match(importRegex);
+  if (m) {
+    const end = m.index + m[0].length;
+    return source.slice(0, end) + importLine + '\n' + source.slice(end);
+  }
+  return importLine + '\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, opts = {}) {
+  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, opts);
+  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 = findHonoHandlers(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, 'hono');
+  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 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');
+    // Sprint D / D4 — thread repoRoot + relPath into the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
+    let res;
+    try {
+      res = astInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
+    } 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, fileOpts);
+    }
+    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;
+    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, 'hono');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    parseEventRoute,
+    resolveRouteFile,
+    astInstrumentFile,
+    regexInstrumentFile,
+    walkRoutes,
+    findHonoHandlers,
+  },
+};

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

@@ -16,6 +16,7 @@ const remix = require('./remix.cjs');
 const sveltekit = require('./sveltekit.cjs');
 const astro = require('./astro.cjs');
 const fastify = require('./fastify.cjs');
+const hono = require('./hono.cjs');
 const vue = require('./vue.cjs');
 const singleton = require('./singleton-helper.cjs');
 
@@ -29,6 +30,7 @@ const MODULES = [
   sveltekit,
   astro,
   fastify,
+  hono,
   vue,
 ];
 

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

@@ -119,7 +119,7 @@ function collectControllerMethods(tree) {
   return results;
 }
 
-function astInstrumentFile(source, targets) {
+function astInstrumentFile(source, targets, opts = {}) {
   // targets: [{ httpMethod, urlPath, events: [] }]
   const tree = ast.parseSource(source);
   const methods = collectControllerMethods(tree);
@@ -149,7 +149,9 @@ function astInstrumentFile(source, targets) {
   if (!changed) {
     return { ok: true, after: source, instrumented: [], skipped, changed: false };
   }
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return { ok: true, after, instrumented: instrumentedNames, skipped, changed: true };
 }
@@ -223,9 +225,11 @@ function instrumentEvents(ctx, events) {
     const abs = path.join(ctx.repoRoot, rel);
     const before = fs.readFileSync(abs, 'utf8');
     const targets = Array.from(perFile.values());
+    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: rel };
     let res;
     try {
-      res = astInstrumentFile(before, targets);
+      res = astInstrumentFile(before, targets, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

package/scripts/patches/auto-instrument/nextjs-app-router.cjs

@@ -70,13 +70,16 @@ function astInstrumentFile(source, method, events, opts = {}) {
     };
   }
   const trackStmts = events.map((e) =>
-    ast.buildTrackStatement(e.name, e.autoProperties || opts.autoProperties && e.extractedProperties),
+    ast.buildTrackStatement(e.name, e.extractedProperties || e.autoProperties),
   );
   const injected = ast.injectTrackBeforeLastReturn(target.fn, target.body, trackStmts);
   if (!injected) {
     return { ok: false, reason: 'inject-failed' };
   }
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — pick `@/lib/gurulu` only when tsconfig is wired,
+  // otherwise fall back to a relative import from the route file.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -92,15 +95,27 @@ function astInstrumentFile(source, method, events, opts = {}) {
 // scope for graceful degradation.
 // ---------------------------------------------------------------------------
 
-function regexEnsureImport(source) {
-  if (source.includes(IMPORT_LINE)) return { source, added: false };
+function regexEnsureImport(source, opts = {}) {
+  // Sprint D / D4 — same `@/lib/gurulu` vs relative-path detection as the
+  // AST path. Falls back to the alias form for older test fixtures that
+  // don't pass a repoRoot.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return { source, added: false };
+  // Don't double-import: if the legacy alias line exists, leave it alone.
+  if (specifier !== '@/lib/gurulu' && source.includes(IMPORT_LINE)) {
+    return { source, added: false };
+  }
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const m = source.match(importRegex);
   if (m) {
     const end = m.index + m[0].length;
-    return { source: source.slice(0, end) + IMPORT_LINE + '\n' + source.slice(end), added: true };
+    return { source: source.slice(0, end) + importLine + '\n' + source.slice(end), added: true };
   }
-  return { source: IMPORT_LINE + '\n' + source, added: true };
+  return { source: importLine + '\n' + source, added: true };
 }
 
 function regexFindMethodBody(source, method) {
@@ -147,15 +162,24 @@ function regexFindLastReturnInBody(source, start, end) {
   return { insertAt: lineStart, indent };
 }
 
-function regexBuildTrackCall(eventName, indent) {
+function regexBuildTrackCall(eventName, indent, extractedProperties) {
   const safeName = JSON.stringify(eventName);
+  let propsStr = '{}';
+  if (Array.isArray(extractedProperties) && extractedProperties.length > 0) {
+    const entries = extractedProperties
+      .filter((p) => p && p.name && p.source)
+      .map((p) => `${p.name}: ${p.source}`);
+    if (entries.length > 0) {
+      propsStr = `{ ${entries.join(', ')} }`;
+    }
+  }
   return (
     `${indent}${MARKER} ${eventName}\n` +
-    `${indent}gurulu.track(${safeName}, {});\n`
+    `${indent}gurulu.track(${safeName}, ${propsStr});\n`
   );
 }
 
-function regexInstrumentFile(before, method, events) {
+function regexInstrumentFile(before, method, events, opts = {}) {
   const body = regexFindMethodBody(before, method);
   if (!body) {
     return { ok: false, reason: `method-${method}-not-found` };
@@ -173,9 +197,9 @@ function regexInstrumentFile(before, method, events) {
   if (needed.length === 0) return { ok: true, after: before, instrumented: [], skipped, changed: false };
   const ret = regexFindLastReturnInBody(before, body.start, body.end);
   if (!ret) return { ok: false, reason: 'no-return-found' };
-  const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
+  const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent, e.extractedProperties)).join('');
   let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
-  after = regexEnsureImport(after).source;
+  after = regexEnsureImport(after, opts).source;
   return {
     ok: true,
     after,
@@ -196,15 +220,18 @@ function instrumentRouteFile(ctx, relPath, method, events) {
   }
   const before = fs.readFileSync(abs, 'utf8');
   const notes = [];
+  // Sprint D / D4 — thread repoRoot + relPath through to the import
+  // resolver so `@/*` and relative-path setups pick the right specifier.
+  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
   let res;
   try {
-    res = astInstrumentFile(before, method, events, ctx || {});
+    res = astInstrumentFile(before, method, events, { ...(ctx || {}), ...fileOpts });
   } catch (err) {
     const msg = (err && err.message) || String(err);
     // eslint-disable-next-line no-console
     console.warn(`[auto-instrument] patch.fallback ${relPath}: ${msg}`);
     notes.push(`patch.fallback:${relPath}:${msg}`);
-    res = regexInstrumentFile(before, method, events);
+    res = regexInstrumentFile(before, method, events, fileOpts);
   }
   if (!res.ok) {
     return {

package/scripts/patches/auto-instrument/nextjs-pages.cjs

@@ -89,7 +89,7 @@ function matchesMethodTest(node, method) {
   return false;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   const fns = ast.findExportedFunction(tree, 'default', { defaultExport: true });
   if (fns.length === 0) {
@@ -109,7 +109,9 @@ function astInstrumentFile(source, method, events) {
   const injectBody = branch || target.body;
   const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
   ast.injectTrackBeforeLastReturn(target.fn, injectBody, stmts);
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -124,15 +126,24 @@ function astInstrumentFile(source, method, events) {
 // Regex fallback
 // ---------------------------------------------------------------------------
 
-function regexEnsureImport(source) {
-  if (source.includes(IMPORT_LINE)) return source;
+function regexEnsureImport(source, opts = {}) {
+  // Sprint D / D4 — alias-aware specifier.
+  const specifier =
+    opts.repoRoot
+      ? ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath)
+      : '@/lib/gurulu';
+  const importLine = `import { gurulu } from '${specifier}';`;
+  if (source.includes(importLine)) return source;
+  if (specifier !== '@/lib/gurulu' && source.includes(IMPORT_LINE)) {
+    return source;
+  }
   const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
   const m = source.match(importRegex);
   if (m) {
     const end = m.index + m[0].length;
-    return source.slice(0, end) + IMPORT_LINE + '\n' + source.slice(end);
+    return source.slice(0, end) + importLine + '\n' + source.slice(end);
   }
-  return IMPORT_LINE + '\n' + source;
+  return importLine + '\n' + source;
 }
 
 function regexFindHandlerBody(source) {
@@ -191,7 +202,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, events) {
+function regexInstrumentFile(before, method, events, opts = {}) {
   const body = regexFindHandlerBody(before);
   if (!body) return { ok: false, reason: 'handler-not-found' };
   const snippet = before.slice(body.start, body.end);
@@ -209,7 +220,7 @@ function regexInstrumentFile(before, method, events) {
   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);
+  after = regexEnsureImport(after, opts);
   return {
     ok: true,
     after,
@@ -230,15 +241,17 @@ function instrumentRouteFile(ctx, relPath, method, events) {
   }
   const before = fs.readFileSync(abs, 'utf8');
   const notes = [];
+  // Sprint D / D4 — thread repoRoot + relPath through to the import resolver.
+  const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath };
   let res;
   try {
-    res = astInstrumentFile(before, method, events);
+    res = astInstrumentFile(before, method, events, fileOpts);
   } catch (err) {
     const msg = (err && err.message) || String(err);
     // eslint-disable-next-line no-console
     console.warn(`[auto-instrument] patch.fallback ${relPath}: ${msg}`);
     notes.push(`patch.fallback:${relPath}:${msg}`);
-    res = regexInstrumentFile(before, method, events);
+    res = regexInstrumentFile(before, method, events, fileOpts);
   }
   if (!res.ok) {
     return {

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

@@ -40,7 +40,7 @@ function routeToCandidates(urlPath) {
   return out;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   // Reads → `loader`, writes → `action`. Per Remix convention.
   const exportName = method === 'GET' || method === 'HEAD' ? 'loader' : 'action';
@@ -58,7 +58,9 @@ function astInstrumentFile(source, method, events) {
   }
   const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
   ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -110,9 +112,11 @@ function instrumentEvents(ctx, events) {
   for (const group of groups.values()) {
     const abs = path.join(ctx.repoRoot, group.relPath);
     const before = fs.readFileSync(abs, 'utf8');
+    // Sprint D / D4 — pass repoRoot + relPath to the import resolver.
+    const fileOpts = { repoRoot: (ctx && ctx.repoRoot) || null, relPath: group.relPath };
     let res;
     try {
-      res = astInstrumentFile(before, group.method, group.events);
+      res = astInstrumentFile(before, group.method, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console