@gurulu/cli 0.1.0 → 0.1.2

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

@@ -0,0 +1,348 @@
+// scripts/patches/auto-instrument/nextjs-pages.cjs — Phase 20 W1 A1.
+//
+// AST-based auto-instrumentation for Next.js Pages Router handlers. The
+// default export is the handler. We parse with Babel, find the exported
+// handler (default export function or arrow), locate a method branch if the
+// handler switches on `req.method`, and inject `gurulu.track(...)` before
+// the final `return` inside that branch (or the handler body when no branch
+// exists).
+//
+// Regex fallback is preserved for malformed sources.
+
+const fs = require('fs');
+const path = require('path');
+
+const ast = require('./ast-helper.cjs');
+const singleton = require('./singleton-helper.cjs');
+
+const NAME = 'auto-instrument-nextjs-pages';
+const SUPPORTED = ['nextjs-pages'];
+const MARKER = '// @gurulu-instrumented';
+const IMPORT_LINE = "import { gurulu } from '@/lib/gurulu';";
+
+function resolveRouteFileCandidates(routeStr) {
+  if (!routeStr || typeof routeStr !== 'string') return null;
+  const m = routeStr.trim().match(/^([A-Z]+)\s+(\/.*)$/);
+  if (!m) return null;
+  const method = m[1].toUpperCase();
+  const urlPath = m[2].replace(/^\//, '').replace(/\/+$/, '');
+  const exts = ['ts', 'tsx', 'js', 'jsx'];
+  const prefixes = ['pages', 'src/pages'];
+  const candidates = [];
+  for (const p of prefixes) {
+    for (const ext of exts) {
+      candidates.push(path.posix.join(p, `${urlPath}.${ext}`));
+      candidates.push(path.posix.join(p, urlPath, `index.${ext}`));
+    }
+  }
+  return { method, candidates };
+}
+
+// ---------------------------------------------------------------------------
+// AST path
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a handler body and a method string, return the BlockStatement of
+ * `if (req.method === 'POST') { ... }` or null if no method branch is found.
+ */
+function findMethodBranchBody(handlerBody, method) {
+  if (!handlerBody || !Array.isArray(handlerBody.body)) return null;
+  const t = ast.t;
+  for (const stmt of handlerBody.body) {
+    if (!t.isIfStatement(stmt)) continue;
+    if (!matchesMethodTest(stmt.test, method)) continue;
+    if (t.isBlockStatement(stmt.consequent)) return stmt.consequent;
+  }
+  // Recurse into else-if chains.
+  for (const stmt of handlerBody.body) {
+    if (!t.isIfStatement(stmt)) continue;
+    let cursor = stmt.alternate;
+    while (cursor) {
+      if (t.isIfStatement(cursor)) {
+        if (matchesMethodTest(cursor.test, method) && t.isBlockStatement(cursor.consequent)) {
+          return cursor.consequent;
+        }
+        cursor = cursor.alternate;
+      } else {
+        break;
+      }
+    }
+  }
+  return null;
+}
+
+function matchesMethodTest(node, method) {
+  const t = ast.t;
+  if (!node) return false;
+  if (t.isBinaryExpression(node) && (node.operator === '===' || node.operator === '==')) {
+    const isMethod = (n) =>
+      t.isMemberExpression(n) &&
+      t.isIdentifier(n.object) &&
+      n.object.name === 'req' &&
+      t.isIdentifier(n.property) &&
+      n.property.name === 'method';
+    const isMethodLiteral = (n) => t.isStringLiteral(n) && n.value.toUpperCase() === method;
+    if (isMethod(node.left) && isMethodLiteral(node.right)) return true;
+    if (isMethod(node.right) && isMethodLiteral(node.left)) return true;
+  }
+  return false;
+}
+
+function astInstrumentFile(source, method, events) {
+  const tree = ast.parseSource(source);
+  const fns = ast.findExportedFunction(tree, 'default', { defaultExport: true });
+  if (fns.length === 0) {
+    return { ok: false, reason: 'handler-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 branch = findMethodBranchBody(target.body, method);
+  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);
+  const after = ast.generateSource(tree, source);
+  return {
+    ok: true,
+    after,
+    instrumented: events.map((e) => e.name),
+    skipped: [],
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Regex fallback
+// ---------------------------------------------------------------------------
+
+function regexEnsureImport(source) {
+  if (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 IMPORT_LINE + '\n' + source;
+}
+
+function regexFindHandlerBody(source) {
+  const patterns = [
+    /export\s+default\s+async\s+function\s+\w+\s*\([^)]*\)\s*\{/,
+    /export\s+default\s+function\s+\w+\s*\([^)]*\)\s*\{/,
+    /export\s+default\s+async\s*\([^)]*\)\s*=>\s*\{/,
+    /export\s+default\s*\([^)]*\)\s*=>\s*\{/,
+  ];
+  for (const re of patterns) {
+    const m = re.exec(source);
+    if (m) {
+      const openIdx = m.index + m[0].length - 1;
+      let depth = 0;
+      for (let i = openIdx; i < source.length; i++) {
+        const c = source[i];
+        if (c === '{') depth++;
+        else if (c === '}') {
+          depth--;
+          if (depth === 0) return { start: openIdx, end: i };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function regexFindLastResponseCall(source, start, end) {
+  const snippet = source.slice(start, end);
+  const patterns = [
+    /res\.status\s*\([^)]*\)\s*\.json\s*\(/g,
+    /res\.status\s*\([^)]*\)\s*\.send\s*\(/g,
+    /res\.json\s*\(/g,
+    /res\.send\s*\(/g,
+    /res\.sendStatus\s*\(/g,
+    /res\.end\s*\(/g,
+  ];
+  let lastIdx = -1;
+  for (const re of patterns) {
+    let m;
+    while ((m = re.exec(snippet)) !== null) {
+      if (m.index > lastIdx) lastIdx = m.index;
+    }
+  }
+  if (lastIdx === -1) return null;
+  const absoluteIdx = start + lastIdx;
+  let lineStart = absoluteIdx;
+  while (lineStart > 0 && source[lineStart - 1] !== '\n') lineStart--;
+  const indentMatch = source.slice(lineStart, absoluteIdx).match(/^(\s*)/);
+  const indent = (indentMatch && indentMatch[1]) || '  ';
+  return { insertAt: lineStart, indent };
+}
+
+function regexBuildTrackCall(eventName, indent) {
+  const safeName = JSON.stringify(eventName);
+  return `${indent}${MARKER} ${eventName}\n${indent}gurulu.track(${safeName}, {});\n`;
+}
+
+function regexInstrumentFile(before, method, events) {
+  const body = regexFindHandlerBody(before);
+  if (!body) return { ok: false, reason: 'handler-not-found' };
+  const snippet = before.slice(body.start, body.end);
+  const needed = [];
+  const skipped = [];
+  for (const e of events) {
+    if (snippet.includes(`${MARKER} ${e.name}`)) {
+      skipped.push({ event: e.name, reason: 'already-instrumented' });
+    } else {
+      needed.push(e);
+    }
+  }
+  if (needed.length === 0) return { ok: true, after: before, instrumented: [], skipped, changed: false };
+  const ret = regexFindLastResponseCall(before, body.start, body.end);
+  if (!ret) return { ok: false, reason: 'no-response-found' };
+  const block = needed.map((e) => regexBuildTrackCall(e.name, ret.indent)).join('');
+  let after = before.slice(0, ret.insertAt) + block + before.slice(ret.insertAt);
+  after = regexEnsureImport(after);
+  return {
+    ok: true,
+    after,
+    instrumented: needed.map((e) => e.name),
+    skipped,
+    changed: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Glue
+// ---------------------------------------------------------------------------
+
+function instrumentRouteFile(ctx, relPath, method, events) {
+  const abs = path.join(ctx.repoRoot, relPath);
+  if (!fs.existsSync(abs)) {
+    return { change: null, skipped: events.map((e) => ({ event: e.name, reason: 'route-file-missing' })), notes: [] };
+  }
+  const before = fs.readFileSync(abs, 'utf8');
+  const notes = [];
+  let res;
+  try {
+    res = astInstrumentFile(before, method, events);
+  } 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);
+  }
+  if (!res.ok) {
+    return {
+      change: null,
+      skipped: events.map((e) => ({ event: e.name, reason: res.reason || 'instrument-failed' })),
+      notes,
+    };
+  }
+  if (!res.changed) return { change: null, skipped: res.skipped, notes };
+  return {
+    change: {
+      relPath,
+      before,
+      after: res.after,
+      reason: `auto-instrument-${method}`,
+      type: 'auto-instrument',
+    },
+    skipped: res.skipped,
+    instrumented: res.instrumented,
+    notes,
+  };
+}
+
+function groupEventsByRoute(ctx, events) {
+  const groups = new Map();
+  const unresolved = [];
+  for (const e of events || []) {
+    const routeStr = e && e.source && e.source.route;
+    if (!routeStr) {
+      unresolved.push({ event: e && e.name, reason: 'no-source-route' });
+      continue;
+    }
+    const parsed = resolveRouteFileCandidates(routeStr);
+    if (!parsed) {
+      unresolved.push({ event: e.name, reason: `unparseable-route:${routeStr}` });
+      continue;
+    }
+    const found = parsed.candidates.find((rel) =>
+      fs.existsSync(path.join(ctx.repoRoot, rel)),
+    );
+    if (!found) {
+      unresolved.push({ event: e.name, reason: 'route-file-not-found' });
+      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);
+  }
+  return { groups: Array.from(groups.values()), unresolved };
+}
+
+function instrumentEvents(ctx, events) {
+  const helper = singleton.ensureSingletonHelper(ctx, 'nextjs-pages');
+  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, unresolved } = groupEventsByRoute(ctx, events || []);
+  for (const u of unresolved) {
+    notes.push(`skip:${u.event || '(unknown)'}:${u.reason}`);
+    eventsSkipped++;
+  }
+  for (const group of groups) {
+    const res = instrumentRouteFile(ctx, group.relPath, group.method, group.events);
+    if (res.notes && res.notes.length) notes.push(...res.notes);
+    if (res.change) {
+      changes.push(res.change);
+      eventsInstrumented += (res.instrumented || []).length;
+    }
+    for (const s of res.skipped || []) {
+      notes.push(`skip:${s.event}:${s.reason}`);
+      eventsSkipped++;
+    }
+  }
+  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, 'nextjs-pages');
+}
+
+module.exports = {
+  name: NAME,
+  supportedFrameworks: SUPPORTED,
+  ensureSingletonHelper,
+  instrumentEvents,
+  _internals: {
+    resolveRouteFileCandidates,
+    astInstrumentFile,
+    regexInstrumentFile,
+    groupEventsByRoute,
+    instrumentRouteFile,
+  },
+};

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

@@ -0,0 +1,164 @@
+// 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) {
+  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);
+  ast.ensureGuruluImport(tree);
+  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');
+    let res;
+    try {
+      res = astInstrumentFile(before, group.method, group.events);
+    } 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/singleton-helper.cjs

@@ -0,0 +1,193 @@
+// 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,
+};