@gurulu/cli 0.4.1 → 0.4.3

package/dist/index.js

@@ -41,6 +41,13 @@ const sourcemap_1 = require("./commands/sourcemap");
 const db_1 = require("./commands/db");
 // Sprint B Group VII B14 — live event stream
 const watch_1 = require("./commands/watch");
+// Sprint E SE-A / SE-B — analytics + observability CLI surface
+const attribution_1 = require("./commands/attribution");
+const releases_1 = require("./commands/releases");
+const skad_1 = require("./commands/skad");
+const errors_1 = require("./commands/errors");
+const replay_1 = require("./commands/replay");
+const conversion_paths_1 = require("./commands/conversion-paths");
 (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
     .scriptName('gurulu')
     .option('profile', { type: 'string', describe: 'Use a specific profile (default: personal)' })
@@ -458,18 +465,42 @@ const watch_1 = require("./commands/watch");
     json: args.json,
     profile: args.profile,
 }))
-    .command('identity <action> [sub]', 'View identity state (decay stats, transfers list, cdc-sources list)', (y) => y
-    .positional('action', { type: 'string', describe: 'decay | transfers | cdc-sources' })
+    .command('identity <action> [sub]', 'Identity state + writes (decay stats | transfers list | cdc-sources list | identify | alias | merge)', (y) => y
+    .positional('action', {
+    type: 'string',
+    describe: 'decay | transfers | cdc-sources | identify | alias | merge',
+})
     .positional('sub', { type: 'string', describe: 'Subaction (stats, list)' })
     .option('direction', { type: 'string', describe: 'outbound | inbound | all' })
     .option('status', { type: 'string', describe: 'Filter by transfer status' })
     .option('limit', { type: 'number', describe: 'Max rows' })
+    // identify / alias / merge
+    .option('site', { type: 'string', describe: 'Site ID (write actions)' })
+    .option('user-id', { type: 'string', describe: 'User ID (identify)' })
+    .option('email', { type: 'string', describe: 'Email (identify)' })
+    .option('phone', { type: 'string', describe: 'Phone (identify)' })
+    .option('traits', { type: 'string', describe: 'Traits as JSON object (identify)' })
+    .option('previous-user-id', { type: 'string', describe: 'Anonymous/old user id (alias)' })
+    .option('new-user-id', { type: 'string', describe: 'New canonical user id (alias)' })
+    .option('canonical-id', { type: 'string', describe: 'Winner canonical profile id (merge)' })
+    .option('duplicate-id', { type: 'string', describe: 'Loser canonical profile id (merge)' })
+    .option('yes', { type: 'boolean', alias: 'y', describe: 'Skip confirmation' })
     .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, identity_1.identityCommand)({
     action: args.action,
     sub: args.sub,
     direction: args.direction,
     status: args.status,
     limit: args.limit,
+    site: args.site,
+    userId: args['user-id'],
+    email: args.email,
+    phone: args.phone,
+    traits: args.traits,
+    previousUserId: args['previous-user-id'],
+    newUserId: args['new-user-id'],
+    canonicalId: args['canonical-id'],
+    duplicateId: args['duplicate-id'],
+    yes: args.yes,
     json: args.json,
     profile: args.profile,
 }))
@@ -571,6 +602,135 @@ const watch_1 = require("./commands/watch");
     tail: args.tail,
     json: args.json,
     profile: args.profile,
+}))
+    // ── Sprint E SE-A/B — analytics + observability CLI surface ──────────
+    .command('attribution <action>', 'Attribution analytics (report, compare, channels)', (y) => y
+    .positional('action', { type: 'string', describe: 'report | compare | channels' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('from', { type: 'string', describe: 'ISO date (inclusive)' })
+    .option('to', { type: 'string', describe: 'ISO date (inclusive)' })
+    .option('range', { type: 'string', describe: '7d | 30d | 90d shorthand' })
+    .option('model', { type: 'string', describe: 'last-touch | first-touch | linear | time-decay | position-based | data-driven' })
+    .option('baseline-model', { type: 'string', describe: 'Baseline model id (compare)' })
+    .option('variant-model', { type: 'string', describe: 'Variant model id (compare)' })
+    .option('conversion-event', { type: 'string', describe: 'Conversion event (default $purchase)' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('json', { type: 'boolean', describe: 'JSON output (default)' }), (args) => (0, attribution_1.attributionCommand)({
+    action: args.action,
+    site: args.site,
+    from: args.from,
+    to: args.to,
+    range: args.range,
+    model: args.model,
+    baselineModel: args['baseline-model'],
+    variantModel: args['variant-model'],
+    conversionEvent: args['conversion-event'],
+    format: args.format,
+    json: args.json,
+    profile: args.profile,
+}))
+    .command('releases <action>', 'Release health (list)', (y) => y
+    .positional('action', { type: 'string', describe: 'list' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('range', { type: 'string', describe: '24h | 7d | 30d (default 7d)' })
+    .option('environment', { type: 'string', describe: 'Optional environment filter' })
+    .option('limit', { type: 'number', describe: 'Max rows (default 20)' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, releases_1.releasesCommand)({
+    action: args.action,
+    site: args.site,
+    range: args.range,
+    environment: args.environment,
+    limit: args.limit,
+    format: args.format,
+    json: args.json,
+    profile: args.profile,
+}))
+    .command('skad <action>', 'Apple SKAdNetwork postbacks (postbacks)', (y) => y
+    .positional('action', { type: 'string', describe: 'postbacks' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('from', { type: 'string', describe: 'ISO ts or 7d/24h' })
+    .option('to', { type: 'string', describe: 'ISO ts (default now)' })
+    .option('goal', { type: 'string', describe: 'Filter by resolved goal' })
+    .option('limit', { type: 'number', describe: 'Max rows (1..500)' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, skad_1.skadCommand)({
+    action: args.action,
+    site: args.site,
+    from: args.from,
+    to: args.to,
+    goal: args.goal,
+    limit: args.limit,
+    format: args.format,
+    json: args.json,
+    profile: args.profile,
+}))
+    .command('errors <action>', 'Error tracking (list, detail, resolve, mute)', (y) => y
+    .positional('action', { type: 'string', describe: 'list | detail | resolve | mute | upload-sourcemap | upload-native-symbols' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('fingerprint', { type: 'string', describe: 'Error group fingerprint' })
+    .option('level', { type: 'string', describe: 'error | warning | info' })
+    .option('resolved', { type: 'string', describe: 'true | false' })
+    .option('environment', { type: 'string', describe: 'Environment filter' })
+    .option('release-id', { type: 'string', describe: 'Filter to a release' })
+    .option('limit', { type: 'number', describe: 'Max rows' })
+    .option('duration', { type: 'string', describe: 'Mute duration (e.g. 24h, 7d)' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('yes', { type: 'boolean', alias: 'y', describe: 'Skip confirmation' })
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, errors_1.errorsCommand)({
+    action: args.action,
+    site: args.site,
+    fingerprint: args.fingerprint,
+    level: args.level,
+    resolved: args.resolved,
+    environment: args.environment,
+    releaseId: args['release-id'],
+    limit: args.limit,
+    duration: args.duration,
+    format: args.format,
+    yes: args.yes,
+    json: args.json,
+    profile: args.profile,
+}))
+    .command('replay <action>', 'Session replay (list, get)', (y) => y
+    .positional('action', { type: 'string', describe: 'list | get' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('session-id', { type: 'string', describe: 'Session id (for get)' })
+    .option('range', { type: 'string', describe: '7d | 30d (default 7d)' })
+    .option('has-error', { type: 'boolean', describe: 'Filter to sessions with errors' })
+    .option('limit', { type: 'number', describe: 'Max rows' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, replay_1.replayCommand)({
+    action: args.action,
+    site: args.site,
+    sessionId: args['session-id'],
+    range: args.range,
+    hasError: args['has-error'],
+    limit: args.limit,
+    format: args.format,
+    json: args.json,
+    profile: args.profile,
+}))
+    .command('conversion-paths <action>', 'Conversion path analytics (list)', (y) => y
+    .positional('action', { type: 'string', describe: 'list' })
+    .option('site', { type: 'string', describe: 'Site ID' })
+    .option('from', { type: 'string', describe: 'ISO date' })
+    .option('to', { type: 'string', describe: 'ISO date' })
+    .option('range', { type: 'string', describe: '7d | 30d | 90d' })
+    .option('conversion-event', { type: 'string', describe: 'Conversion event' })
+    .option('limit', { type: 'number', describe: 'Max rows' })
+    .option('format', { type: 'string', describe: 'json | table' })
+    .option('json', { type: 'boolean', describe: 'JSON output' }), (args) => (0, conversion_paths_1.conversionPathsCommand)({
+    action: args.action,
+    site: args.site,
+    from: args.from,
+    to: args.to,
+    range: args.range,
+    conversionEvent: args['conversion-event'],
+    limit: args.limit,
+    format: args.format,
+    json: args.json,
+    profile: args.profile,
 }))
     .demandCommand(1, 'Run gurulu --help for available commands')
     .strict()

package/package.json

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

package/scripts/gurulu-agentic-install.lib.cjs

@@ -380,16 +380,44 @@ function generateServerMap(scan /*, opts*/) {
   };
 }
 
+/**
+ * Sprint E1.3b — singularize plural table/model names to canonical singular.
+ * The scan layer normalises mutations as `{ op: '<model>.<operation>' }` so we
+ * derive the operation from `m.op` when `m.operation` isn't present, and
+ * collapse common irregular plurals to their singular form so e.g. raw-SQL
+ * `INSERT INTO orders` and a Drizzle `pgTable('orders', ...)` both fold into
+ * the same `order` row in db-map.
+ */
+const SINGULARIZE_IRREGULARS = {
+  users: 'user',
+  orders: 'order',
+  items: 'item',
+};
+function singularizeModelName(raw) {
+  const lower = String(raw || '').toLowerCase();
+  if (!lower) return lower;
+  if (Object.prototype.hasOwnProperty.call(SINGULARIZE_IRREGULARS, lower)) {
+    return SINGULARIZE_IRREGULARS[lower];
+  }
+  return lower;
+}
+
 /** db-map.json — table → event emitter mapping from detected mutations. */
 function generateDbMap(scan, opts) {
   const byModel = new Map();
   for (const m of scan.mutations || []) {
-    const name = String(m.model || '').trim();
-    if (!name) continue;
-    const op = cdcOp(m.operation);
+    const rawName = String(m.model || '').trim();
+    if (!rawName) continue;
+    const name = singularizeModelName(rawName);
+    // Sprint E1.3b — `scan.mutations` from gurulu-scan.lib.cjs normalises the
+    // operation as `m.op = "<model>.<operation>"` and drops `m.operation`.
+    // Derive the operation verb from whichever field is populated.
+    const operation =
+      m.operation || (typeof m.op === 'string' ? m.op.split('.').pop() : null);
+    const op = cdcOp(operation);
     if (!op) continue;
     if (!byModel.has(name)) byModel.set(name, new Set());
-    const key = `${op}::${inferEventName(name, m.operation)}`;
+    const key = `${op}::${inferEventName(name, operation)}`;
     byModel.get(name).add(key);
   }
 

package/scripts/gurulu-agentic-install.mjs

@@ -278,10 +278,13 @@ async function runPatchMode(repoRoot, args) {
     process.exit(1);
   }
   const framework = args.framework || 'auto';
-  const { patcher, detection, error } = patches.resolvePatcher(repoRoot, framework);
+  const { patcher, detection, error, unsupportedFramework } = patches.resolvePatcher(repoRoot, framework);
   if (error) {
     process.stderr.write(`Error: ${error}\n`);
-    process.exit(1);
+    // Sprint E1.6 — exit 6 specifically for mobile / not-yet-supported
+    // frameworks so the wrapping CLI can surface docs links instead of a
+    // generic install failure.
+    process.exit(unsupportedFramework ? 6 : 1);
   }
   if (!patcher) {
     process.stderr.write('No supported framework detected in ' + repoRoot + '\n');
@@ -379,13 +382,53 @@ 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`,
+      );
+    }
+    // Sprint E1.1 — exit code 5 signals "patches rolled back" so install.ts
+    // can skip the npm-install / .env-merge / ingest-ping steps and surface
+    // the rollback to the user. The wrapping CLI converts this into a
+    // partially-installed state with `summary.rolledBack=true`.
+    process.exit(5);
+  }
   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 +436,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 +493,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 +527,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