@gurulu/cli 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gurulu/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Gurulu.io CLI — setup analytics in seconds",
   "bin": {
     "gurulu": "bin/gurulu.js"

package/scripts/gurulu-agentic-install.mjs

@@ -379,13 +379,48 @@ async function runPatchMode(repoRoot, args) {
   // When --auto-instrument is set AND --intent-result is provided, load
   // the accepted events from the Phase 18.6 intent proposal, dispatch
   // to the matching auto-instrument module, and append the resulting
-  // route-handler changes to the existing patch-log. Failures here are
-  // reported but do NOT unwind the script-tag patch (separate concerns).
+  // route-handler changes to the existing patch-log.
+  //
+  // Sprint D / D2 — auto-instrument failures (collision, apply-throw, or a
+  // missing intent-result file) now roll back the script-tag patch we just
+  // applied. Otherwise the user is left half-installed: a tracker tag in
+  // their HTML/layout but no route-handler instrumentation, and no signal
+  // that the partial state needs cleanup. We invoke `patches.rollback()` and
+  // emit `INSTALL_ROLLED_BACK` on stdout so install.ts (and any wrapping
+  // agent) can surface the rollback to the user.
   // -------------------------------------------------------------------
+  let autoInstrumentFailureReason = null;
+  function rollbackOnFailure(reason) {
+    if (autoInstrumentFailureReason) return; // only roll back once
+    autoInstrumentFailureReason = reason;
+    try {
+      const rb = patches.rollback(repoRoot);
+      if (rb && rb.rolledBack) {
+        log(`Auto-instrument failed (${reason}); rolled back ${rb.files.length} script-tag change(s).`);
+        process.stdout.write(
+          'INSTALL_ROLLED_BACK ' +
+            JSON.stringify({ stage: 'auto-instrument', reason, files: rb.files }) +
+            '\n',
+        );
+      } else {
+        process.stderr.write(
+          `Auto-instrument failed (${reason}); rollback unavailable: ${rb && rb.reason}\n`,
+        );
+      }
+    } catch (err) {
+      process.stderr.write(
+        `Auto-instrument failed (${reason}); rollback threw: ${err.stack || err.message || err}\n`,
+      );
+    }
+  }
   if (args.autoInstrument) {
     const intentPath = args['intent-result'];
     if (!intentPath) {
-      log('Auto-instrument: skipped (no --intent-result provided)');
+      // Sprint D / D2 — explicit `--auto-instrument` without `--intent-result`
+      // is a user error, not "skip silently". The script-tag patch we just
+      // applied promised the agent that route handlers would be wired, so
+      // unwind that partial state.
+      rollbackOnFailure('missing-intent-result');
       return;
     }
     let intent;
@@ -393,11 +428,14 @@ async function runPatchMode(repoRoot, args) {
       intent = JSON.parse(readFileSync(intentPath, 'utf8'));
     } catch (err) {
       process.stderr.write(`Auto-instrument: failed to read ${intentPath}: ${err.message}\n`);
+      rollbackOnFailure('intent-result-unreadable');
       return;
     }
     const acceptedEvents = (intent && intent.accepted && intent.accepted.events) || [];
     if (acceptedEvents.length === 0) {
       log('Auto-instrument: no accepted events to instrument');
+      // Empty intent file is NOT a failure — the agent legitimately had
+      // nothing to instrument. Leave the script-tag patch on disk.
       return;
     }
 
@@ -447,6 +485,10 @@ async function runPatchMode(repoRoot, args) {
       process.stderr.write(
         `Auto-instrument: singleton helper collision; aborting without changes.\n`,
       );
+      // Sprint D / D2 — collision mid-flow leaves the user with a script tag
+      // injected and no helper file. Roll back the script-tag patch so the
+      // agent can decide whether to retry after resolving the collision.
+      rollbackOnFailure('singleton-helper-collision');
       return;
     }
     if (!aiResult.changes || aiResult.changes.length === 0) {
@@ -477,6 +519,11 @@ async function runPatchMode(repoRoot, args) {
       );
     } catch (err) {
       process.stderr.write(`Auto-instrument: apply failed: ${err.stack || err.message || err}\n`);
+      // Sprint D / D2 — applyAutoInstrumentPlan threw mid-write. The patch
+      // log is partially written; let the rollback restore both script-tag
+      // and any auto-instrument files we already touched (rollback walks the
+      // full file list in patch-log.json).
+      rollbackOnFailure('apply-auto-instrument-threw');
     }
   }
 }

package/scripts/patches/auto-instrument/ast-helper.cjs

@@ -16,6 +16,9 @@
 // apply transforms, then run `@babel/generator` to serialize the result.
 // Parse errors are NOT swallowed — callers catch and fall back to regex.
 
+const fs = require('fs');
+const path = require('path');
+
 const parser = require('@babel/parser');
 // `@babel/traverse` exposes its default export under `.default` in CJS.
 const traverseMod = require('@babel/traverse');
@@ -25,9 +28,93 @@ const generate = generatorMod.default || generatorMod;
 const t = require('@babel/types');
 
 const IMPORT_LINE = "import { gurulu } from '@/lib/gurulu';";
+const HELPER_REL_PATH = 'src/lib/gurulu';
 const MARKER = '@gurulu-instrumented';
 const MARKER_COMMENT = `// @gurulu-instrumented`;
 
+// ---------------------------------------------------------------------------
+// Sprint D / D4 — tsconfig `@/*` path detection + relative-path fallback.
+//
+// Many auto-instrumented files want to write `import { gurulu } from
+// '@/lib/gurulu'`. That works for the typical Next.js scaffold, but breaks
+// in vanilla TS / Vite / Express setups whose `tsconfig.json` does not
+// configure `compilerOptions.paths['@/*']`. Without the alias the inserted
+// import resolves to a missing module and the patched file fails to
+// compile.
+//
+// `resolveGuruluImportSpecifier(repoRoot, relativeRouteFile)` returns the
+// import specifier the patcher should embed. When the alias is configured
+// it returns `'@/lib/gurulu'`; otherwise it computes the POSIX-style
+// relative path from the route file to `src/lib/gurulu` (e.g.
+// `'../../lib/gurulu'`).
+// ---------------------------------------------------------------------------
+
+function stripJsonComments(text) {
+  // Tolerate `// ...` and `/* ... */` comments as found in tsconfig files.
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:\\])\/\/.*$/gm, '$1');
+}
+
+function readTsconfigPaths(repoRoot) {
+  const candidates = ['tsconfig.json', 'tsconfig.base.json', 'jsconfig.json'];
+  for (const rel of candidates) {
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) continue;
+    try {
+      const raw = fs.readFileSync(abs, 'utf8');
+      const parsed = JSON.parse(stripJsonComments(raw));
+      const co = parsed && parsed.compilerOptions;
+      if (co && co.paths && typeof co.paths === 'object') {
+        return { paths: co.paths, baseUrl: co.baseUrl || '.' };
+      }
+    } catch {
+      // Ignore malformed tsconfig — fall through to the next candidate.
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns true when tsconfig.json (or jsconfig.json) declares
+ * `compilerOptions.paths['@/*']`. We accept any value — most projects map it
+ * to `['./src/*']` but custom roots like `['./*']` also count as wired.
+ */
+function hasAtAlias(repoRoot) {
+  const cfg = readTsconfigPaths(repoRoot);
+  if (!cfg) return false;
+  return Object.prototype.hasOwnProperty.call(cfg.paths, '@/*');
+}
+
+/**
+ * Compute a POSIX-style relative import path from `fromFileRel` (a repo
+ * relative path like `src/app/api/checkout/route.ts`) to the singleton
+ * helper at `src/lib/gurulu`. The returned path is suitable for use as an
+ * ES module import specifier: it always starts with `./` or `../` and never
+ * carries a file extension.
+ */
+function relativeHelperSpecifier(fromFileRel) {
+  const fromDir = path.posix.dirname(fromFileRel.split(path.sep).join('/'));
+  let rel = path.posix.relative(fromDir, HELPER_REL_PATH);
+  if (!rel) rel = '.';
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  return rel;
+}
+
+/**
+ * Pick the right import specifier for `import { gurulu } from <here>`
+ * given the repo root and the file the import will be written into.
+ *
+ * - When `@/*` is configured in tsconfig, prefer the alias for clean diffs
+ *   that match the singleton helper documentation.
+ * - Otherwise fall back to a relative import computed from the route file.
+ */
+function resolveGuruluImportSpecifier(repoRoot, fromFileRel) {
+  if (repoRoot && hasAtAlias(repoRoot)) return '@/lib/gurulu';
+  if (fromFileRel) return relativeHelperSpecifier(fromFileRel);
+  return '@/lib/gurulu';
+}
+
 const DEFAULT_PARSE_PLUGINS = [
   'typescript',
   'jsx',
@@ -96,12 +183,62 @@ function tagInstrumented(node) {
   t.addComment(node, 'leading', ` @gurulu-instrumented`, true);
 }
 
+// Sprint D / D1 — typed-helper selector. Lives in its own CJS module so the
+// auto-instrumenter can swap `gurulu.track('$purchase', {...})` for the
+// canonical `gurulu.purchase({...})` whenever the LLM-extracted properties
+// satisfy the helper's required fields. When `selectHelper` returns null we
+// fall through to the legacy generic-track shape — no behaviour change for
+// custom (non-canonical) events.
+const sdkHelperMap = require('./sdk-helper-map.cjs');
+
+function safeParseExpression(text) {
+  return parser.parseExpression(text, { plugins: DEFAULT_PARSE_PLUGINS });
+}
+
+function buildTypedHelperCall(eventName, autoProperties) {
+  const helper = sdkHelperMap.selectHelper(eventName, autoProperties);
+  if (!helper) return null;
+  const argNodes = [];
+  for (const expr of helper.argExpressions) {
+    try {
+      argNodes.push(safeParseExpression(expr));
+    } catch (_) {
+      // Defensive: if any arg expression is malformed, abort the typed
+      // upgrade and let the caller emit `gurulu.track(...)` instead.
+      return null;
+    }
+  }
+  return t.expressionStatement(
+    t.callExpression(
+      t.memberExpression(t.identifier('gurulu'), t.identifier(helper.method)),
+      argNodes,
+    ),
+  );
+}
+
 /**
  * Build the `gurulu.track('eventName', { ...properties })` statement. Empty
  * object when no auto-properties; otherwise an ObjectExpression with the
  * property AST nodes inlined.
+ *
+ * Sprint D / D1: when `eventName` is a canonical event ($purchase, $signup,
+ * etc.) AND the extracted properties supply every required field, we emit
+ * the typed helper instead — `gurulu.purchase({ value, currency })` rather
+ * than `gurulu.track('$purchase', { ... })`. The marker comment is identical
+ * in either form so idempotency checks still work.
  */
-function buildTrackStatement(eventName, autoProperties) {
+function buildTrackStatement(eventName, autoProperties, opts = {}) {
+  // Try the typed helper first. Tests and patcher modules pass `opts.preferTyped =
+  // false` to opt out (e.g. when verifying the legacy shape). Default is true.
+  const preferTyped = opts.preferTyped !== false;
+  if (preferTyped) {
+    const typed = buildTypedHelperCall(eventName, autoProperties);
+    if (typed) {
+      t.addComment(typed, 'leading', ` @gurulu-instrumented ${eventName}`, true);
+      return typed;
+    }
+  }
+
   const args = [t.stringLiteral(eventName)];
   if (Array.isArray(autoProperties) && autoProperties.length > 0) {
     const props = [];
@@ -111,10 +248,7 @@ function buildTrackStatement(eventName, autoProperties) {
       let valueNode;
       if (p.source && typeof p.source === 'string') {
         try {
-          const parsedExpr = parser.parseExpression(p.source, {
-            plugins: DEFAULT_PARSE_PLUGINS,
-          });
-          valueNode = parsedExpr;
+          valueNode = safeParseExpression(p.source);
         } catch (_) {
           valueNode = t.stringLiteral(String(p.source));
         }
@@ -193,10 +327,13 @@ function injectTrackBeforeLastReturn(fn, body, trackStatements) {
 }
 
 /**
- * Ensure `import { gurulu } from '@/lib/gurulu'` is present. No-op when the
- * import already exists.
+ * Ensure `import { gurulu } from <specifier>` is present. No-op when an
+ * existing import already binds the `gurulu` named export from a path
+ * pointing at our singleton helper (alias OR relative). Sprint D / D4: the
+ * specifier is derived from tsconfig — callers may pass an explicit one.
  */
-function ensureGuruluImport(ast) {
+function ensureGuruluImport(ast, specifierOpt) {
+  const specifier = specifierOpt || '@/lib/gurulu';
   let present = false;
   let lastImportIdx = -1;
   const body = ast.program.body;
@@ -204,7 +341,12 @@ function ensureGuruluImport(ast) {
     const node = body[i];
     if (t.isImportDeclaration(node)) {
       lastImportIdx = i;
-      if (node.source && node.source.value === '@/lib/gurulu') {
+      const src = node.source && node.source.value;
+      if (
+        src === specifier ||
+        src === '@/lib/gurulu' ||
+        (typeof src === 'string' && /(^|\/)lib\/gurulu$/.test(src))
+      ) {
         const hasNamed = (node.specifiers || []).some(
           (s) => t.isImportSpecifier(s) && t.isIdentifier(s.imported) && s.imported.name === 'gurulu',
         );
@@ -215,7 +357,7 @@ function ensureGuruluImport(ast) {
   if (present) return;
   const imp = t.importDeclaration(
     [t.importSpecifier(t.identifier('gurulu'), t.identifier('gurulu'))],
-    t.stringLiteral('@/lib/gurulu'),
+    t.stringLiteral(specifier),
   );
   body.splice(lastImportIdx + 1, 0, imp);
 }
@@ -323,10 +465,16 @@ module.exports = {
   hasInstrumentedMarker,
   tagInstrumented,
   buildTrackStatement,
+  buildTypedHelperCall,
   injectTrackBeforeLastReturn,
   ensureGuruluImport,
   findExportedFunction,
+  hasAtAlias,
+  relativeHelperSpecifier,
+  resolveGuruluImportSpecifier,
+  sdkHelperMap,
   IMPORT_LINE,
+  HELPER_REL_PATH,
   MARKER,
   MARKER_COMMENT,
 };

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

@@ -69,7 +69,7 @@ function hasDataLoadingPattern(frontmatterSource) {
  * `---` fences via the shared AST helper, injects gurulu.track() calls, and
  * reconstructs the full .astro file.
  */
-function astInstrumentFrontmatter(source, events) {
+function astInstrumentFrontmatter(source, events, opts = {}) {
   const fmMatch = source.match(FRONTMATTER_RE);
   if (!fmMatch) return { ok: false, reason: 'no-frontmatter' };
 
@@ -123,7 +123,9 @@ function astInstrumentFrontmatter(source, events) {
     body.body.push(...stmts);
   }
 
-  ast.ensureGuruluImport(tree);
+  // Sprint D / D4 — alias-aware import.
+  const fmSpecifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, fmSpecifier);
   const newFrontmatter = ast.generateSource(tree, frontmatter);
 
   // Reconstruct the full .astro file
@@ -140,7 +142,7 @@ function astInstrumentFrontmatter(source, events) {
   };
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   const fns = ast.findExportedFunction(tree, method);
   if (fns.length === 0) return { ok: false, reason: `${method}-not-found` };
@@ -156,7 +158,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,
@@ -208,12 +212,14 @@ 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 {
       const isAstroComponent = group.relPath.endsWith('.astro');
       res = isAstroComponent
-        ? astInstrumentFrontmatter(before, group.events)
-        : astInstrumentFile(before, group.method, group.events);
+        ? astInstrumentFrontmatter(before, group.events, fileOpts)
+        : astInstrumentFile(before, group.method, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

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

@@ -91,7 +91,7 @@ function findRouteHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findRouteHandlers(tree, method, urlPath);
   if (handlers.length === 0) {
@@ -109,7 +109,9 @@ function astInstrumentFile(source, method, urlPath, 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 (Express usually has no `@/*` alias).
+  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+  ast.ensureGuruluImport(tree, specifier);
   const after = ast.generateSource(tree, source);
   return {
     ok: true,
@@ -181,10 +183,21 @@ function regexFindLastResponseCall(source, start, end) {
   return { insertAt: lineStart, indent };
 }
 
-function regexEnsureImport(source) {
+function regexEnsureImport(source, opts = {}) {
   if (source.includes(IMPORT_LINE_ESM) || source.includes(IMPORT_LINE_CJS)) return source;
+  // Sprint D / D4 — alias-aware specifier. ESM-only branch picks `@/lib/gurulu`
+  // when tsconfig declares it, otherwise a relative import. The CJS branch
+  // continues to use `./lib/gurulu` since CommonJS does not honor TS paths.
   const isCjs = /\brequire\s*\(/.test(source) && !/^import\s/m.test(source);
-  const line = isCjs ? IMPORT_LINE_CJS : IMPORT_LINE_ESM;
+  let line;
+  if (isCjs) {
+    line = IMPORT_LINE_CJS;
+  } else if (opts.repoRoot) {
+    const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
+    line = `import { gurulu } from '${specifier}';`;
+  } else {
+    line = 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);
@@ -200,7 +213,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, urlPath, events) {
+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);
@@ -218,7 +231,7 @@ function regexInstrumentFile(before, method, urlPath, 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,
@@ -305,15 +318,17 @@ 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 — 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);
+      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);
+      res = regexInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     }
     if (!res.ok) {
       for (const e of group.events) {

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

@@ -104,7 +104,7 @@ function findFastifyHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findFastifyHandlers(tree, method, urlPath);
   if (handlers.length === 0) return { ok: false, reason: 'handler-not-found' };
@@ -120,7 +120,9 @@ function astInstrumentFile(source, method, urlPath, 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,
@@ -197,9 +199,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.urlPath, group.events);
+      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

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

@@ -106,7 +106,7 @@ function findHonoHandlers(tree, method, urlPath) {
   return results;
 }
 
-function astInstrumentFile(source, method, urlPath, events) {
+function astInstrumentFile(source, method, urlPath, events, opts = {}) {
   const tree = ast.parseSource(source);
   const handlers = findHonoHandlers(tree, method, urlPath);
   if (handlers.length === 0) {
@@ -124,7 +124,9 @@ function astInstrumentFile(source, method, urlPath, 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,
@@ -199,15 +201,22 @@ function regexFindLastResponseCall(source, start, end) {
   return { insertAt: lineStart, indent };
 }
 
-function regexEnsureImport(source) {
+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) + IMPORT_LINE_ESM + '\n' + source.slice(end);
+    return source.slice(0, end) + importLine + '\n' + source.slice(end);
   }
-  return IMPORT_LINE_ESM + '\n' + source;
+  return importLine + '\n' + source;
 }
 
 function regexBuildTrackCall(eventName, indent) {
@@ -215,7 +224,7 @@ function regexBuildTrackCall(eventName, indent) {
   return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
 }
 
-function regexInstrumentFile(before, method, urlPath, events) {
+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);
@@ -233,7 +242,7 @@ function regexInstrumentFile(before, method, urlPath, 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,
@@ -320,15 +329,17 @@ 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 — 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);
+      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);
+      res = regexInstrumentFile(before, group.method, group.urlPath, group.events, fileOpts);
     }
     if (!res.ok) {
       for (const e of group.events) {

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

@@ -76,7 +76,10 @@ function astInstrumentFile(source, method, events, opts = {}) {
   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) {
@@ -164,7 +179,7 @@ function regexBuildTrackCall(eventName, indent, extractedProperties) {
   );
 }
 
-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` };
@@ -184,7 +199,7 @@ function regexInstrumentFile(before, method, events) {
   if (!ret) return { ok: false, reason: 'no-return-found' };
   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,
@@ -205,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

package/scripts/patches/auto-instrument/sdk-helper-map.cjs

@@ -0,0 +1,241 @@
+// scripts/patches/auto-instrument/sdk-helper-map.cjs — Sprint D / D1.
+//
+// CommonJS port of the canonical event → typed SDK helper map. Mirrors a
+// subset of `src/lib/intelligence/sdk-helper-mapping.ts` so the auto-
+// instrumenter (a pure-Node CJS pipeline) can pick a typed helper like
+// `gurulu.purchase({...})` instead of the generic `gurulu.track('$purchase',
+// {...})` when an event matches a known canonical name.
+//
+// We intentionally only encode the *server* mapping here — the auto-
+// instrumenter writes Node/server-side route handlers, never web/iOS/Android
+// code. The TS file remains the source of truth for the multi-platform
+// onboarding UI.
+//
+// Schema:
+//   eventName → {
+//     method: 'purchase'         // bare method on `gurulu` singleton
+//     args:   [arg-spec, ...]    // ordered positional arg specs
+//   }
+//
+// Each arg-spec is either:
+//   { kind: 'object', props: [{ name, propName, required, default? }] }
+//     → emits `{ propName: <expr from ctx[name]>, ... }`
+//   { kind: 'value', name }
+//     → emits the JS expression bound to property `name` (or undefined)
+//
+// `selectHelper(eventName, propMap)` returns null when no typed helper
+// applies to the given event/properties. Callers fall back to the generic
+// `gurulu.track(name, {...})` form. This function is pure — it does not
+// require any AST/Babel APIs.
+
+// Common property aliases. The `propMap` callers feed us is keyed by the
+// extracted property `name`, but typed helpers expect canonical fields like
+// `value`, `currency`, `transactionId`. We accept any of the listed aliases.
+const PROP_ALIASES = {
+  value: ['value', 'amount', 'total', 'price', 'revenue'],
+  currency: ['currency', 'currency_code', 'currencyCode'],
+  transactionId: ['transactionId', 'transaction_id', 'orderId', 'order_id', 'id'],
+  orderId: ['orderId', 'order_id'],
+  userId: ['userId', 'user_id', 'uid'],
+  email: ['email', 'user_email'],
+  method: ['method', 'auth_method', 'provider'],
+  plan: ['plan', 'plan_id', 'planId', 'subscription_plan'],
+  query: ['query', 'q', 'search_term', 'searchTerm'],
+};
+
+// Server-side typed helpers. Each entry's `method` is the bare method name
+// on the `gurulu` singleton (`gurulu.<method>(...)`). When `args` is a single
+// object spec we emit `gurulu.<method>({ ... })`. Multiple arg-specs would
+// emit positional args, but no current helper needs that shape.
+const HELPER_MAP = {
+  $purchase: {
+    method: 'purchase',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'value', propName: 'value', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+          { name: 'transactionId', propName: 'transaction_id', required: false },
+        ],
+      },
+    ],
+  },
+  $payment_succeeded: {
+    method: 'paymentSucceeded',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'value', propName: 'amount', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+          { name: 'orderId', propName: 'orderId', required: false },
+        ],
+      },
+    ],
+  },
+  $order_placed: {
+    method: 'orderPlaced',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'orderId', propName: 'orderId', required: true },
+          { name: 'value', propName: 'total', required: true },
+          { name: 'currency', propName: 'currency', required: true },
+        ],
+      },
+    ],
+  },
+  $subscription_started: {
+    method: 'subscriptionStarted',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'plan', propName: 'plan', required: true },
+          { name: 'value', propName: 'amount', required: false },
+          { name: 'currency', propName: 'currency', required: false },
+        ],
+      },
+    ],
+  },
+  $subscription_created: {
+    method: 'subscriptionStarted',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: false },
+          { name: 'plan', propName: 'plan', required: true },
+          { name: 'value', propName: 'amount', required: false },
+          { name: 'currency', propName: 'currency', required: false },
+        ],
+      },
+    ],
+  },
+  $signup: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+  $signup_completed: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+  $account_created: {
+    method: 'userCreated',
+    args: [
+      {
+        kind: 'object',
+        props: [
+          { name: 'userId', propName: 'userId', required: true },
+          { name: 'email', propName: 'email', required: false },
+        ],
+      },
+    ],
+  },
+};
+
+/**
+ * Given an extractedProperties array (each `{ name, source }` where `source`
+ * is a JS expression string), build a lookup of `canonicalName → expression`
+ * resolving the alias table. Unknown names pass through under their raw key.
+ */
+function buildPropertyLookup(extractedProperties) {
+  const raw = {};
+  const resolved = {};
+  if (!Array.isArray(extractedProperties)) {
+    return { raw, resolved };
+  }
+  for (const prop of extractedProperties) {
+    if (!prop || !prop.name || !prop.source) continue;
+    raw[prop.name] = prop.source;
+  }
+  // Resolve aliases — for each canonical key, the first alias hit wins.
+  for (const [canonical, aliases] of Object.entries(PROP_ALIASES)) {
+    for (const alias of aliases) {
+      if (Object.prototype.hasOwnProperty.call(raw, alias)) {
+        resolved[canonical] = raw[alias];
+        break;
+      }
+    }
+  }
+  return { raw, resolved };
+}
+
+/**
+ * Pick a typed helper for the given event + properties. Returns:
+ *   { method, argExpressions: ['<expr>', ...] }   — when the helper applies
+ *   null                                           — when no helper applies
+ *
+ * The caller is responsible for parsing each argExpression string into an AST
+ * node (e.g. via `parser.parseExpression`) and emitting the corresponding
+ * `gurulu.<method>(...)` call. We deliberately stay AST-free here so this
+ * module can be unit-tested without Babel.
+ */
+function selectHelper(eventName, extractedProperties) {
+  const helper = HELPER_MAP[eventName];
+  if (!helper) return null;
+
+  const lookup = buildPropertyLookup(extractedProperties);
+  const argExpressions = [];
+
+  for (const argSpec of helper.args) {
+    if (argSpec.kind === 'object') {
+      const objectEntries = [];
+      let missingRequired = false;
+      for (const prop of argSpec.props) {
+        const expr = lookup.resolved[prop.name] || lookup.raw[prop.name];
+        if (expr) {
+          objectEntries.push(`${prop.propName}: ${expr}`);
+        } else if (prop.required) {
+          missingRequired = true;
+          break;
+        }
+      }
+      if (missingRequired) return null;
+      argExpressions.push(`{ ${objectEntries.join(', ')} }`);
+    } else if (argSpec.kind === 'value') {
+      const expr = lookup.resolved[argSpec.name] || lookup.raw[argSpec.name];
+      if (!expr) return null;
+      argExpressions.push(expr);
+    }
+  }
+
+  return { method: helper.method, argExpressions };
+}
+
+/**
+ * Returns the list of canonical event names that have typed helpers wired.
+ * Useful for tests and observability.
+ */
+function getMappedEventNames() {
+  return Object.keys(HELPER_MAP);
+}
+
+module.exports = {
+  PROP_ALIASES,
+  HELPER_MAP,
+  buildPropertyLookup,
+  selectHelper,
+  getMappedEventNames,
+};

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

@@ -35,7 +35,7 @@ function routeToCandidates(urlPath) {
   return out;
 }
 
-function astInstrumentFile(source, method, events) {
+function astInstrumentFile(source, method, events, opts = {}) {
   const tree = ast.parseSource(source);
   const fns = ast.findExportedFunction(tree, method);
   if (fns.length === 0) return { ok: false, reason: `${method}-not-found` };
@@ -51,7 +51,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,
@@ -103,9 +105,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

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

@@ -70,7 +70,7 @@ function findEventHandler(tree) {
   return found;
 }
 
-function astInstrumentFile(source, events) {
+function astInstrumentFile(source, events, opts = {}) {
   const tree = ast.parseSource(source);
   const target = findEventHandler(tree);
   if (!target) return { ok: false, reason: 'event-handler-not-found' };
@@ -85,7 +85,9 @@ function astInstrumentFile(source, 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,
@@ -137,9 +139,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.events);
+      res = astInstrumentFile(before, group.events, fileOpts);
     } catch (err) {
       const msg = (err && err.message) || String(err);
       // eslint-disable-next-line no-console

package/scripts/patches/index.cjs

@@ -42,6 +42,12 @@ const PATCHERS = [
 ];
 
 const PATCHER_BY_NAME = {
+  // Sprint D / D3 — `nextjs` (bare) is the alias most agents emit. Resolve it
+  // to the App Router patcher (the modern default). The Pages Router can
+  // still be selected explicitly via `nextjs-pages`. Auto-detection (in the
+  // PATCHERS array above) handles the case where a project actually uses
+  // Pages Router and the agent passed `auto`.
+  nextjs: nextAppRouter,
   'nextjs-app': nextAppRouter,
   'nextjs-app-router': nextAppRouter,
   'nextjs-pages': nextPages,