@gurulu/cli 0.4.0 → 0.4.2

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