@gurulu/cli 0.4.6 → 1.0.0

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

@@ -1,168 +0,0 @@
-// scripts/patches/auto-instrument/remix.cjs — Phase 20 W1 A3.
-//
-// Auto-instruments Remix route modules. Remix routes export `loader` and
-// `action` functions from files under `app/routes/**`. We map a Proposed
-// Event with `source.route = 'POST /cart/add'` onto `app/routes/cart.add.tsx`
-// (Remix flat routes) or `app/routes/cart/add.tsx`, then inject a
-// `gurulu.track(...)` call into the `action` (writes) or `loader` (reads).
-
-const fs = require('fs');
-const path = require('path');
-
-const ast = require('./ast-helper.cjs');
-const singleton = require('./singleton-helper.cjs');
-
-const NAME = 'auto-instrument-remix';
-const SUPPORTED = ['remix'];
-
-function parseEventRoute(routeStr) {
-  if (!routeStr || typeof routeStr !== 'string') return null;
-  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
-  if (!m) return null;
-  return { method: m[1].toUpperCase(), urlPath: m[2].replace(/\/+$/, '') || '/' };
-}
-
-function routeToCandidates(urlPath) {
-  const cleaned = urlPath.replace(/^\//, '').replace(/\/+$/, '');
-  const segments = cleaned.split('/').filter(Boolean);
-  if (segments.length === 0) segments.push('_index');
-  const exts = ['ts', 'tsx', 'js', 'jsx'];
-  const out = [];
-  // Nested: app/routes/cart/add.tsx
-  for (const ext of exts) {
-    out.push(path.posix.join('app', 'routes', ...segments) + `.${ext}`);
-    out.push(path.posix.join('app', 'routes', ...segments, `index.${ext}`));
-  }
-  // Flat routes: app/routes/cart.add.tsx
-  for (const ext of exts) {
-    out.push(path.posix.join('app', 'routes', segments.join('.')) + `.${ext}`);
-  }
-  return out;
-}
-
-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';
-  const fns = ast.findExportedFunction(tree, exportName);
-  if (fns.length === 0) return { ok: false, reason: `${exportName}-not-found` };
-  const target = fns[0];
-  if (ast.hasInstrumentedMarker(target.fn)) {
-    return {
-      ok: true,
-      after: source,
-      instrumented: [],
-      skipped: events.map((e) => ({ event: e.name, reason: 'already-instrumented' })),
-      changed: false,
-    };
-  }
-  const stmts = events.map((e) => ast.buildTrackStatement(e.name, e.autoProperties));
-  ast.injectTrackBeforeLastReturn(target.fn, target.body, stmts);
-  // Sprint D / D4 — alias-aware import.
-  const specifier = ast.resolveGuruluImportSpecifier(opts.repoRoot, opts.relPath);
-  ast.ensureGuruluImport(tree, specifier);
-  const after = ast.generateSource(tree, source);
-  return {
-    ok: true,
-    after,
-    instrumented: events.map((e) => e.name),
-    skipped: [],
-    changed: true,
-  };
-}
-
-function instrumentEvents(ctx, events) {
-  const helper = singleton.ensureSingletonHelper(ctx, 'remix');
-  const changes = [...helper.changes];
-  const notes = [...helper.notes];
-  let eventsInstrumented = 0;
-  let eventsSkipped = 0;
-
-  if (helper.collision) {
-    return {
-      changes: [],
-      notes,
-      filesModified: 0,
-      eventsInstrumented: 0,
-      eventsSkipped: events ? events.length : 0,
-      collision: true,
-    };
-  }
-
-  const groups = new Map();
-  for (const e of events || []) {
-    const parsed = parseEventRoute(e && e.source && e.source.route);
-    if (!parsed) {
-      notes.push(`skip:${e && e.name}:no-source-route`);
-      eventsSkipped++;
-      continue;
-    }
-    const candidates = routeToCandidates(parsed.urlPath);
-    const found = candidates.find((rel) => fs.existsSync(path.join(ctx.repoRoot, rel)));
-    if (!found) {
-      notes.push(`skip:${e.name}:route-file-not-found`);
-      eventsSkipped++;
-      continue;
-    }
-    const key = `${found}::${parsed.method}`;
-    if (!groups.has(key)) groups.set(key, { relPath: found, method: parsed.method, events: [] });
-    groups.get(key).events.push(e);
-  }
-
-  for (const group of groups.values()) {
-    const abs = path.join(ctx.repoRoot, group.relPath);
-    const before = fs.readFileSync(abs, 'utf8');
-    // Sprint D / D4 — 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, 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}`);
-      continue;
-    }
-    if (!res.ok) {
-      for (const e of group.events) {
-        notes.push(`skip:${e.name}:${res.reason}`);
-        eventsSkipped++;
-      }
-      continue;
-    }
-    for (const s of res.skipped || []) {
-      notes.push(`skip:${s.event}:${s.reason}`);
-      eventsSkipped++;
-    }
-    if (res.changed) {
-      changes.push({
-        relPath: group.relPath,
-        before,
-        after: res.after,
-        reason: `auto-instrument-remix`,
-        type: 'auto-instrument',
-      });
-      eventsInstrumented += (res.instrumented || []).length;
-    }
-  }
-
-  const filesModified = changes.filter((c) => c.type === 'auto-instrument').length;
-  return { changes, notes, filesModified, eventsInstrumented, eventsSkipped, collision: false };
-}
-
-function ensureSingletonHelper(ctx) {
-  return singleton.ensureSingletonHelper(ctx, 'remix');
-}
-
-module.exports = {
-  name: NAME,
-  supportedFrameworks: SUPPORTED,
-  ensureSingletonHelper,
-  instrumentEvents,
-  _internals: {
-    parseEventRoute,
-    routeToCandidates,
-    astInstrumentFile,
-  },
-};

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

@@ -1,241 +0,0 @@
-// 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/singleton-helper.cjs

@@ -1,193 +0,0 @@
-// scripts/patches/auto-instrument/singleton-helper.cjs — Phase 18.7 B5.
-//
-// Shared utility for the per-framework auto-instrument modules. Responsible
-// for:
-//
-//   1. Creating a `src/lib/gurulu.ts` singleton that constructs the
-//      `@gurulu/node` Gurulu client from env vars.
-//   2. Adding `@gurulu/node` to the target repo's `package.json` dependencies
-//      if missing.
-//   3. Appending `GURULU_SITE_ID` / `GURULU_SECRET_KEY` / `GURULU_INGEST_URL`
-//      env vars to `.env.local` (Next.js) or `.env` (Express/other).
-//
-// None of these helpers shell out — they produce in-memory `change` records
-// that the caller can thread through the existing `applyPlan()` backup +
-// patch-log infrastructure. That way auto-instrument patches participate in
-// the same `--rollback` flow as the script-tag patches.
-//
-// Pure Node, zero deps. Idempotency is achieved via the
-// `// @gurulu-instrumented` marker + JSON dep deduplication.
-
-const fs = require('fs');
-const path = require('path');
-
-const HELPER_MARKER = '// @gurulu-instrumented';
-const HELPER_REL_PATH = 'src/lib/gurulu.ts';
-const NODE_DEP = '@gurulu/node';
-const NODE_DEP_VERSION = '^0.1.0';
-
-function buildHelperContent() {
-  return (
-    `${HELPER_MARKER}\n` +
-    `// Auto-generated by Gurulu agentic install (phase 18.7).\n` +
-    `// Edit to customize the singleton, but keep the @gurulu-instrumented\n` +
-    `// marker so \`gurulu install --rollback\` can find this file.\n` +
-    `import { Gurulu } from '@gurulu/node';\n\n` +
-    `export const gurulu = new Gurulu({\n` +
-    `  siteId: process.env.GURULU_SITE_ID ?? '',\n` +
-    `  apiKey: process.env.GURULU_SECRET_KEY ?? '',\n` +
-    `  endpoint: process.env.GURULU_INGEST_URL ?? 'https://gurulu.io',\n` +
-    `});\n`
-  );
-}
-
-/**
- * Plan a singleton helper file change. Returns a `change` record compatible
- * with `patches.applyPlan()` or `null` if the helper already exists with our
- * marker (idempotent). Throws when the file exists but does not carry the
- * marker — that indicates a collision with user code and refuses to
- * overwrite.
- */
-function planSingletonHelper(ctx) {
-  const repoRoot = ctx.repoRoot;
-  const abs = path.join(repoRoot, HELPER_REL_PATH);
-  if (fs.existsSync(abs)) {
-    const existing = fs.readFileSync(abs, 'utf8');
-    if (existing.includes(HELPER_MARKER)) {
-      return { change: null, reason: 'helper-exists' };
-    }
-    const err = new Error(
-      `auto-instrument: refusing to overwrite existing ${HELPER_REL_PATH} ` +
-        `(no @gurulu-instrumented marker). Delete or rename the file to proceed.`,
-    );
-    err.code = 'GURULU_HELPER_COLLISION';
-    throw err;
-  }
-  return {
-    change: {
-      relPath: HELPER_REL_PATH,
-      before: '',
-      after: buildHelperContent(),
-      reason: 'create-singleton-helper',
-    },
-    reason: 'helper-created',
-  };
-}
-
-/**
- * Plan the `package.json` edit that adds `@gurulu/node` to dependencies if
- * missing. Returns a change record or null when already present.
- */
-function planPackageJsonDependency(ctx) {
-  const abs = path.join(ctx.repoRoot, 'package.json');
-  if (!fs.existsSync(abs)) {
-    return { change: null, reason: 'package-json-missing' };
-  }
-  const before = fs.readFileSync(abs, 'utf8');
-  let pkg;
-  try {
-    pkg = JSON.parse(before);
-  } catch {
-    return { change: null, reason: 'package-json-invalid' };
-  }
-  const deps = pkg.dependencies || {};
-  if (deps[NODE_DEP]) {
-    return { change: null, reason: 'node-dep-present' };
-  }
-  pkg.dependencies = { ...deps, [NODE_DEP]: NODE_DEP_VERSION };
-  // Preserve the trailing newline convention.
-  const trailing = before.endsWith('\n') ? '\n' : '';
-  const after = JSON.stringify(pkg, null, 2) + trailing;
-  return {
-    change: {
-      relPath: 'package.json',
-      before,
-      after,
-      reason: 'add-gurulu-node-dep',
-    },
-    reason: 'node-dep-added',
-  };
-}
-
-/**
- * Plan the `.env.local` / `.env` edit that appends the GURULU_* keys. Never
- * overwrites existing values. Returns a change record or null when all keys
- * are already present.
- */
-function planEnvFile(ctx, framework) {
-  const isNext = !!(framework && /^nextjs/.test(framework));
-  const filename = isNext ? '.env.local' : '.env';
-  const abs = path.join(ctx.repoRoot, filename);
-  const before = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
-  const presentKeys = new Set(
-    before
-      .split('\n')
-      .map((l) => l.trim())
-      .filter((l) => l && !l.startsWith('#'))
-      .map((l) => l.split('=')[0].trim()),
-  );
-  const want = {
-    GURULU_SITE_ID: '',
-    GURULU_SECRET_KEY: '',
-    GURULU_INGEST_URL: 'https://gurulu.io',
-  };
-  const missing = Object.entries(want).filter(([k]) => !presentKeys.has(k));
-  if (missing.length === 0) {
-    return { change: null, reason: 'env-already-present' };
-  }
-  const separator = before && !before.endsWith('\n') ? '\n' : '';
-  const header = before ? '' : '# Gurulu agentic install (phase 18.7)\n';
-  const newLines = missing.map(([k, v]) => `${k}=${v}`).join('\n');
-  const after = before + separator + header + newLines + '\n';
-  return {
-    change: {
-      relPath: filename,
-      before,
-      after,
-      reason: 'append-gurulu-env',
-    },
-    reason: 'env-added',
-    addedKeys: missing.map(([k]) => k),
-  };
-}
-
-/**
- * Convenience: plan all three prerequisite changes at once. Returns
- * `{ changes: [...], notes: [...] }` following the same shape the
- * per-framework instrument modules return, so it can be merged directly by
- * callers.
- */
-function ensureSingletonHelper(ctx, framework) {
-  const changes = [];
-  const notes = [];
-  try {
-    const helper = planSingletonHelper(ctx);
-    if (helper.change) changes.push(helper.change);
-    else notes.push(`singleton:${helper.reason}`);
-  } catch (err) {
-    if (err.code === 'GURULU_HELPER_COLLISION') {
-      notes.push(`singleton-collision:${err.message}`);
-      return { changes: [], notes, collision: true };
-    }
-    throw err;
-  }
-  const dep = planPackageJsonDependency(ctx);
-  if (dep.change) changes.push(dep.change);
-  else notes.push(`package-json:${dep.reason}`);
-  const env = planEnvFile(ctx, framework);
-  if (env.change) changes.push(env.change);
-  else notes.push(`env:${env.reason}`);
-  return { changes, notes, collision: false };
-}
-
-module.exports = {
-  HELPER_MARKER,
-  HELPER_REL_PATH,
-  NODE_DEP,
-  NODE_DEP_VERSION,
-  buildHelperContent,
-  planSingletonHelper,
-  planPackageJsonDependency,
-  planEnvFile,
-  ensureSingletonHelper,
-};