@gurulu/cli 0.1.0 → 0.1.2

package/scripts/patches/index.cjs

@@ -0,0 +1,294 @@
+// scripts/patches/index.cjs — Phase 16 A1 patch engine registry.
+//
+// Each patcher exports { name, detect, plan, apply, rollback }. The CLI
+// resolves them in priority order via `resolvePatcher()`. Backups and patch
+// logs are produced by shared helpers in this file.
+//
+// Pure Node, no deps. Regex-based patching (ts-morph not available).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ---------------------------------------------------------------------------
+// BEGIN: Agent A (Phase 18.7) — Framework patcher registration
+// Script-tag injection patchers. Order matters for auto-detection: more
+// specific frameworks first (Next.js before generic Vite+React, Remix
+// before Vue, NestJS/Fastify server-only last so SPA frontends in the
+// same repo win).
+// ---------------------------------------------------------------------------
+const nextAppRouter = require('./nextjs-app-router.patch.cjs');
+const nextPages = require('./nextjs-pages.patch.cjs');
+const remix = require('./remix.patch.cjs');
+const sveltekit = require('./sveltekit.patch.cjs');
+const astro = require('./astro.patch.cjs');
+const viteReact = require('./vite-react.patch.cjs');
+const vue = require('./vue.patch.cjs');
+const nestjs = require('./nestjs.patch.cjs');
+const fastify = require('./fastify.patch.cjs');
+const express = require('./express.patch.cjs');
+
+const PATCHERS = [
+  nextAppRouter,
+  nextPages,
+  remix,
+  sveltekit,
+  astro,
+  viteReact,
+  vue,
+  nestjs,
+  fastify,
+  express,
+];
+
+const PATCHER_BY_NAME = {
+  'nextjs-app': nextAppRouter,
+  'nextjs-app-router': nextAppRouter,
+  'nextjs-pages': nextPages,
+  remix,
+  sveltekit,
+  astro,
+  'vite-react': viteReact,
+  vue,
+  vue3: vue,
+  nestjs,
+  fastify,
+  express,
+};
+// ---------------------------------------------------------------------------
+// END: Agent A (Phase 18.7) — Framework patcher registration
+// NOTE for Agent B: Auto-instrument dispatcher goes in its own section below
+// (or in scripts/patches/auto-instrument/index.cjs). Do not inline it in the
+// PATCHERS array above — those are script-tag patchers only.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// BEGIN: Agent B (Phase 18.7) — Auto-instrumentation dispatcher
+// Route-handler instrumentation modules live in `./auto-instrument/*.cjs`.
+// They share a singleton-helper utility that keeps `src/lib/gurulu.ts`,
+// `package.json`, and `.env.local` / `.env` in sync. The dispatcher below
+// is a thin wrapper that `scripts/gurulu-agentic-install.mjs` calls when
+// `--auto-instrument` is set. Changes produced by auto-instrument modules
+// are stamped `type: 'auto-instrument'` so `applyAutoInstrumentPlan()` can
+// append them to the existing `.gurulu/patch-log.json` (rather than
+// overwriting the script-tag entries) — `rollback()` then restores both
+// patch generations in a single pass.
+// ---------------------------------------------------------------------------
+const autoInstrumentDispatcher = require('./auto-instrument/index.cjs');
+
+function autoInstrumentDispatch(framework, ctx, events) {
+  return autoInstrumentDispatcher.dispatch(framework, ctx, events);
+}
+// ---------------------------------------------------------------------------
+// END: Agent B (Phase 18.7) — Auto-instrumentation dispatcher
+// ---------------------------------------------------------------------------
+
+// Tracker tag context — a small object the patchers stamp into the code they inject.
+function buildInjection(opts) {
+  const siteId = opts.siteId || '';
+  const tenantId = opts.tenantId || '';
+  const publishableKey = opts.publishableKey || '';
+  const src = opts.scriptSrc || '/gurulu-tracker.js';
+  return { siteId, tenantId, publishableKey, scriptSrc: src };
+}
+
+function resolvePatcher(repoRoot, frameworkHint) {
+  if (frameworkHint && frameworkHint !== 'auto') {
+    const p = PATCHER_BY_NAME[frameworkHint];
+    if (!p) return { patcher: null, detection: null, error: `Unknown framework: ${frameworkHint}` };
+    const detection = p.detect(repoRoot);
+    return { patcher: p, detection: detection || { framework: p.name, files: [] } };
+  }
+  for (const p of PATCHERS) {
+    const detection = p.detect(repoRoot);
+    if (detection) return { patcher: p, detection };
+  }
+  return { patcher: null, detection: null };
+}
+
+// Backup one file into .gurulu-backup/<timestamp>/<relPath>.
+function backupFile(repoRoot, relPath, timestamp) {
+  const abs = path.join(repoRoot, relPath);
+  const original = fs.readFileSync(abs, 'utf8');
+  const backupDir = path.join(repoRoot, '.gurulu-backup', timestamp);
+  const backupPath = path.join(backupDir, relPath);
+  fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+  fs.writeFileSync(backupPath, original, 'utf8');
+  return { backupPath: path.relative(repoRoot, backupPath), original };
+}
+
+function hashContent(text) {
+  return crypto.createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+function ensureGitignore(repoRoot) {
+  const gi = path.join(repoRoot, '.gitignore');
+  let contents = '';
+  if (fs.existsSync(gi)) contents = fs.readFileSync(gi, 'utf8');
+  if (!/\.gurulu-backup/.test(contents)) {
+    const append = (contents.endsWith('\n') || !contents ? '' : '\n') + '.gurulu-backup/\n';
+    fs.writeFileSync(gi, contents + append, 'utf8');
+    return true;
+  }
+  return false;
+}
+
+// Utility: produce a plain unified-diff-ish output for dry-run (tiny, no deps).
+function unifiedDiff(relPath, before, after) {
+  if (before === after) return `--- a/${relPath}\n+++ b/${relPath}\n(no changes)\n`;
+  const beforeLines = before.split('\n');
+  const afterLines = after.split('\n');
+  const lines = [`--- a/${relPath}`, `+++ b/${relPath}`];
+  // Naive: show all "-" then all "+" — sufficient for alpha dry-run display.
+  for (const l of beforeLines) lines.push(`-${l}`);
+  for (const l of afterLines) lines.push(`+${l}`);
+  return lines.join('\n') + '\n';
+}
+
+// Plan → { changes: [{ relPath, before, after, reason }], notes: [] }
+// Apply consumes a plan, writes files, creates backups, writes patch-log.
+async function applyPlan(repoRoot, patcher, plan) {
+  if (!plan || !plan.changes || plan.changes.length === 0) {
+    return { applied: false, reason: 'no-changes', files: [] };
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const fileRecords = [];
+  for (const change of plan.changes) {
+    const abs = path.join(repoRoot, change.relPath);
+    // Ensure parent dir exists (for new files added by patcher if any).
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    let backupRel = null;
+    if (fs.existsSync(abs)) {
+      const { backupPath } = backupFile(repoRoot, change.relPath, timestamp);
+      backupRel = backupPath;
+    }
+    fs.writeFileSync(abs, change.after, 'utf8');
+    fileRecords.push({
+      path: change.relPath,
+      hash: hashContent(change.after),
+      backupPath: backupRel,
+      type: change.type || 'script-tag',
+    });
+  }
+  ensureGitignore(repoRoot);
+  const logDir = path.join(repoRoot, '.gurulu');
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = path.join(logDir, 'patch-log.json');
+  const log = {
+    appliedAt: new Date().toISOString(),
+    framework: patcher.name,
+    timestamp,
+    files: fileRecords,
+    rollbackAvailable: true,
+  };
+  fs.writeFileSync(logFile, JSON.stringify(log, null, 2) + '\n', 'utf8');
+  return { applied: true, log, files: fileRecords };
+}
+
+// ---------------------------------------------------------------------------
+// Phase 18.7 B6 — applyAutoInstrumentPlan
+// Applies the auto-instrument plan (helper + route handler changes) using
+// the same backup mechanism as applyPlan, but APPENDS to an existing
+// `.gurulu/patch-log.json` rather than overwriting it. This lets the
+// script-tag patch and the auto-instrument patch coexist under a single
+// rollback pass.
+// ---------------------------------------------------------------------------
+async function applyAutoInstrumentPlan(repoRoot, plan) {
+  if (!plan || !plan.changes || plan.changes.length === 0) {
+    return { applied: false, reason: 'no-changes', files: [] };
+  }
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const fileRecords = [];
+  for (const change of plan.changes) {
+    const abs = path.join(repoRoot, change.relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    let backupRel = null;
+    if (fs.existsSync(abs)) {
+      const { backupPath } = backupFile(repoRoot, change.relPath, timestamp);
+      backupRel = backupPath;
+    }
+    fs.writeFileSync(abs, change.after, 'utf8');
+    fileRecords.push({
+      path: change.relPath,
+      hash: hashContent(change.after),
+      backupPath: backupRel,
+      type: change.type || 'auto-instrument',
+    });
+  }
+  ensureGitignore(repoRoot);
+  const logDir = path.join(repoRoot, '.gurulu');
+  fs.mkdirSync(logDir, { recursive: true });
+  const logFile = path.join(logDir, 'patch-log.json');
+  let log;
+  if (fs.existsSync(logFile)) {
+    try {
+      log = JSON.parse(fs.readFileSync(logFile, 'utf8'));
+    } catch {
+      log = null;
+    }
+  }
+  if (!log) {
+    log = {
+      appliedAt: new Date().toISOString(),
+      framework: plan.framework || 'auto-instrument',
+      timestamp,
+      files: [],
+      rollbackAvailable: true,
+    };
+  }
+  log.files = [...(log.files || []), ...fileRecords];
+  log.autoInstrumentAppliedAt = new Date().toISOString();
+  log.autoInstrumentTimestamp = timestamp;
+  log.rollbackAvailable = true;
+  fs.writeFileSync(logFile, JSON.stringify(log, null, 2) + '\n', 'utf8');
+  return { applied: true, log, files: fileRecords };
+}
+
+function rollback(repoRoot) {
+  const logFile = path.join(repoRoot, '.gurulu', 'patch-log.json');
+  if (!fs.existsSync(logFile)) {
+    return { rolledBack: false, reason: 'no-patch-log' };
+  }
+  const log = JSON.parse(fs.readFileSync(logFile, 'utf8'));
+  if (!log.rollbackAvailable) return { rolledBack: false, reason: 'rollback-unavailable' };
+  const restored = [];
+  for (const f of log.files) {
+    if (!f.backupPath) {
+      // File was newly created by patcher — delete it.
+      const abs = path.join(repoRoot, f.path);
+      if (fs.existsSync(abs)) fs.unlinkSync(abs);
+      restored.push({ path: f.path, action: 'deleted' });
+      continue;
+    }
+    const backupAbs = path.join(repoRoot, f.backupPath);
+    if (!fs.existsSync(backupAbs)) {
+      restored.push({ path: f.path, action: 'missing-backup' });
+      continue;
+    }
+    const original = fs.readFileSync(backupAbs, 'utf8');
+    fs.writeFileSync(path.join(repoRoot, f.path), original, 'utf8');
+    restored.push({ path: f.path, action: 'restored' });
+  }
+  // Mark log as consumed.
+  log.rollbackAvailable = false;
+  log.rolledBackAt = new Date().toISOString();
+  fs.writeFileSync(logFile, JSON.stringify(log, null, 2) + '\n', 'utf8');
+  return { rolledBack: true, files: restored };
+}
+
+module.exports = {
+  PATCHERS,
+  PATCHER_BY_NAME,
+  resolvePatcher,
+  buildInjection,
+  backupFile,
+  hashContent,
+  ensureGitignore,
+  unifiedDiff,
+  applyPlan,
+  rollback,
+  // Phase 18.7 B — auto-instrumentation exports.
+  autoInstrumentDispatch,
+  autoInstrument: autoInstrumentDispatcher,
+  applyAutoInstrumentPlan,
+};

package/scripts/patches/nestjs.patch.cjs

@@ -0,0 +1,111 @@
+// nestjs.patch.cjs — Phase 18.7 A1
+//
+// NestJS is a server-side framework. Most real-world NestJS apps serve a
+// separate frontend (React/Vue/Angular) or bundle a static client under
+// `client/dist/` / `public/`. When we find a static `index.html` we patch
+// it with a plain <script> tag. Otherwise we emit a detection note telling
+// the operator to use --auto-instrument for server-side tracking (Phase
+// 18.7 Agent B territory).
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'nestjs';
+const HTML_CANDIDATES = [
+  'public/index.html',
+  'client/dist/index.html',
+  'client/build/index.html',
+  'dist/client/index.html',
+];
+const SERVER_CANDIDATES = [
+  'src/main.ts',
+  'src/main.js',
+];
+
+const MARKER = 'data-gurulu-install="1"';
+
+function looksLikeNest(repoRoot) {
+  // Detect either via package.json `@nestjs/core` dep or the idiomatic
+  // `NestFactory.create(...)` bootstrap call in main.ts.
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      if (deps['@nestjs/core']) return true;
+    } catch {
+      /* ignore malformed package.json */
+    }
+  }
+  for (const rel of SERVER_CANDIDATES) {
+    const abs = path.join(repoRoot, rel);
+    if (fs.existsSync(abs)) {
+      const source = fs.readFileSync(abs, 'utf8');
+      if (/NestFactory\.create\s*\(/.test(source) || /@nestjs\/core/.test(source)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function detect(repoRoot) {
+  if (!looksLikeNest(repoRoot)) return null;
+  for (const rel of HTML_CANDIDATES) {
+    if (fs.existsSync(path.join(repoRoot, rel))) {
+      return { framework: NAME, files: [rel] };
+    }
+  }
+  // Server-only — no frontend to patch. Return detection with empty file list
+  // so the caller can surface the note.
+  return { framework: NAME, files: [], serverOnly: true };
+}
+
+function buildScriptTag(injection) {
+  const pkAttr = injection.publishableKey
+    ? ` data-gurulu-publishable-key="${injection.publishableKey}"`
+    : '';
+  return (
+    `    <script\n` +
+    `      src="${injection.scriptSrc}"\n` +
+    `      data-gurulu-site-id="${injection.siteId}"\n` +
+    `      data-gurulu-tenant-id="${injection.tenantId}"${pkAttr}\n` +
+    `      ${MARKER}\n` +
+    `      async\n` +
+    `    ></script>\n`
+  );
+}
+
+function injectScriptTag(source, injection) {
+  if (source.includes(MARKER)) return source;
+  const tag = buildScriptTag(injection);
+  if (/<\/body>/.test(source)) {
+    return source.replace(/<\/body>/, `${tag}  </body>`);
+  }
+  return source + '\n' + tag;
+}
+
+function plan(ctx) {
+  const detection = detect(ctx.repoRoot);
+  if (!detection) return { changes: [], notes: ['no-nestjs'] };
+  if (detection.serverOnly) {
+    return {
+      changes: [],
+      notes: [
+        'server-only; script injection skipped, use --auto-instrument for server-side tracking',
+      ],
+    };
+  }
+  const changes = [];
+  for (const rel of detection.files) {
+    const abs = path.join(ctx.repoRoot, rel);
+    const before = fs.readFileSync(abs, 'utf8');
+    const after = injectScriptTag(before, ctx.injection);
+    if (after !== before) {
+      changes.push({ relPath: rel, before, after, reason: 'inject-script-tag' });
+    }
+  }
+  return { changes, notes: [] };
+}
+
+module.exports = { name: NAME, detect, plan };

package/scripts/patches/nextjs-app-router.patch.cjs

@@ -0,0 +1,95 @@
+// nextjs-app-router.patch.cjs — Phase 16 A1
+//
+// Detects a Next.js App Router layout (`src/app/layout.tsx` or `app/layout.tsx`)
+// and injects a <Script> tag loaded via next/script that points to the Gurulu
+// Web SDK tracker (`/gurulu-tracker.js` by default).
+//
+// Regex-based: fast alpha, good enough for most idiomatic RootLayouts.
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'nextjs-app-router';
+const CANDIDATES = [
+  'src/app/layout.tsx',
+  'src/app/layout.jsx',
+  'app/layout.tsx',
+  'app/layout.jsx',
+];
+
+const MARKER = 'data-gurulu-install="1"';
+
+function detect(repoRoot) {
+  for (const rel of CANDIDATES) {
+    if (fs.existsSync(path.join(repoRoot, rel))) {
+      return { framework: NAME, files: [rel] };
+    }
+  }
+  return null;
+}
+
+function buildScriptTag(injection) {
+  const pkAttr = injection.publishableKey
+    ? `          data-gurulu-publishable-key=${JSON.stringify(injection.publishableKey)}\n`
+    : '';
+  return (
+    `        <Script\n` +
+    `          id="gurulu-tracker"\n` +
+    `          src=${JSON.stringify(injection.scriptSrc)}\n` +
+    `          strategy="afterInteractive"\n` +
+    `          data-gurulu-site-id=${JSON.stringify(injection.siteId)}\n` +
+    `          data-gurulu-tenant-id=${JSON.stringify(injection.tenantId)}\n` +
+    pkAttr +
+    `          data-features="errors"\n` +
+    `          ${MARKER}\n` +
+    `        />\n`
+  );
+}
+
+function ensureScriptImport(source) {
+  if (/from\s+['"]next\/script['"]/.test(source)) return source;
+  // Insert after the last import statement (or at top).
+  const importRegex = /^(?:import[\s\S]*?;\s*\n)+/m;
+  const m = source.match(importRegex);
+  const inject = `import Script from 'next/script';\n`;
+  if (m) {
+    const end = m.index + m[0].length;
+    return source.slice(0, end) + inject + source.slice(end);
+  }
+  return inject + source;
+}
+
+function injectScriptTag(source, injection) {
+  if (source.includes(MARKER)) return source; // idempotent
+  const tag = buildScriptTag(injection);
+  // Prefer to insert just before </body>. Fall back to before the closing
+  // top-level fragment/element.
+  if (/<\/body>/.test(source)) {
+    return source.replace(/<\/body>/, `${tag}      </body>`);
+  }
+  // Insert before the final closing tag of children area — best-effort.
+  return source.replace(/(\n\s*<\/(?:html|main|div)>\s*\)\s*;?\s*\}\s*$)/, (m) => `\n${tag}${m}`);
+}
+
+function plan(ctx) {
+  const detection = detect(ctx.repoRoot);
+  if (!detection) return { changes: [], notes: ['no-layout-found'] };
+  const changes = [];
+  for (const rel of detection.files) {
+    const abs = path.join(ctx.repoRoot, rel);
+    const before = fs.readFileSync(abs, 'utf8');
+    let after = ensureScriptImport(before);
+    after = injectScriptTag(after, ctx.injection);
+    if (after !== before) {
+      changes.push({ relPath: rel, before, after, reason: 'inject-next-script' });
+    } else {
+      changes.push({ relPath: rel, before, after, reason: 'already-installed', skip: true });
+    }
+  }
+  return {
+    changes: changes.filter((c) => !c.skip),
+    notes: changes.filter((c) => c.skip).map((c) => `skip:${c.relPath}`),
+  };
+}
+
+module.exports = { name: NAME, detect, plan };

package/scripts/patches/nextjs-pages.patch.cjs

@@ -0,0 +1,96 @@
+// nextjs-pages.patch.cjs — Phase 16 A1
+//
+// Detects a legacy Next.js Pages Router `_app` file and injects a useEffect
+// that appends the Gurulu tracker <script> to document.head.
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'nextjs-pages';
+const CANDIDATES = [
+  'pages/_app.tsx',
+  'pages/_app.jsx',
+  'src/pages/_app.tsx',
+  'src/pages/_app.jsx',
+];
+
+const MARKER = '/* gurulu:install */';
+
+function detect(repoRoot) {
+  for (const rel of CANDIDATES) {
+    if (fs.existsSync(path.join(repoRoot, rel))) {
+      return { framework: NAME, files: [rel] };
+    }
+  }
+  return null;
+}
+
+function ensureUseEffectImport(source) {
+  if (/from\s+['"]react['"]/.test(source)) {
+    if (/useEffect/.test(source)) return source;
+    return source.replace(/import\s+([^;]*?)from\s+(['"])react\2/, (m, names, q) => {
+      if (/\{[^}]*\}/.test(names)) {
+        return m.replace(/\{([^}]*)\}/, (mm, inner) => `{${inner.trim()}, useEffect }`);
+      }
+      return `${m.trim()}\nimport { useEffect } from 'react'`;
+    });
+  }
+  return `import { useEffect } from 'react';\n` + source;
+}
+
+function buildHook(injection) {
+  const pkLine = injection.publishableKey
+    ? `    s.setAttribute('data-gurulu-publishable-key', ${JSON.stringify(injection.publishableKey)});\n`
+    : '';
+  return (
+    `  ${MARKER}\n` +
+    `  useEffect(() => {\n` +
+    `    if (typeof window === 'undefined') return;\n` +
+    `    if (document.querySelector('script[data-gurulu-install]')) return;\n` +
+    `    const s = document.createElement('script');\n` +
+    `    s.src = ${JSON.stringify(injection.scriptSrc)};\n` +
+    `    s.async = true;\n` +
+    `    s.setAttribute('data-gurulu-install', '1');\n` +
+    `    s.setAttribute('data-gurulu-site-id', ${JSON.stringify(injection.siteId)});\n` +
+    `    s.setAttribute('data-gurulu-tenant-id', ${JSON.stringify(injection.tenantId)});\n` +
+    pkLine +
+    `    document.head.appendChild(s);\n` +
+    `  }, []);\n`
+  );
+}
+
+function injectHook(source, injection) {
+  if (source.includes(MARKER)) return source;
+  const hook = buildHook(injection);
+  // Match: function MyApp({ Component, pageProps }) { ...  — insert hook after `{`.
+  const fnMatch = source.match(/function\s+\w+\s*\([^)]*\)\s*\{/);
+  if (fnMatch) {
+    const end = fnMatch.index + fnMatch[0].length;
+    return source.slice(0, end) + '\n' + hook + source.slice(end);
+  }
+  // Arrow form: `const MyApp = ({ Component, pageProps }) => {`
+  const arrowMatch = source.match(/const\s+\w+\s*=\s*\([^)]*\)\s*=>\s*\{/);
+  if (arrowMatch) {
+    const end = arrowMatch.index + arrowMatch[0].length;
+    return source.slice(0, end) + '\n' + hook + source.slice(end);
+  }
+  return source;
+}
+
+function plan(ctx) {
+  const detection = detect(ctx.repoRoot);
+  if (!detection) return { changes: [], notes: ['no-_app-found'] };
+  const changes = [];
+  for (const rel of detection.files) {
+    const abs = path.join(ctx.repoRoot, rel);
+    const before = fs.readFileSync(abs, 'utf8');
+    let after = injectHook(before, ctx.injection);
+    if (after !== before) after = ensureUseEffectImport(after);
+    if (after !== before) {
+      changes.push({ relPath: rel, before, after, reason: 'inject-useeffect' });
+    }
+  }
+  return { changes, notes: [] };
+}
+
+module.exports = { name: NAME, detect, plan };

package/scripts/patches/remix.patch.cjs

@@ -0,0 +1,74 @@
+// remix.patch.cjs — Phase 18.7 A1
+//
+// Detects a Remix app by the presence of `app/root.tsx` (or `.jsx`) and
+// injects a plain <script> tag before the `<Scripts />` component inside
+// the root layout's <body>. Remix's <Scripts /> handles hydration; we keep
+// our tracker as a vanilla async <script> so it's independent of the React
+// runtime.
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'remix';
+const CANDIDATES = [
+  'app/root.tsx',
+  'app/root.jsx',
+];
+
+const MARKER = 'data-gurulu-install="1"';
+
+function detect(repoRoot) {
+  for (const rel of CANDIDATES) {
+    if (fs.existsSync(path.join(repoRoot, rel))) {
+      return { framework: NAME, files: [rel] };
+    }
+  }
+  return null;
+}
+
+function buildScriptTag(injection) {
+  const pkAttr = injection.publishableKey
+    ? `          data-gurulu-publishable-key=${JSON.stringify(injection.publishableKey)}\n`
+    : '';
+  return (
+    `        <script\n` +
+    `          src=${JSON.stringify(injection.scriptSrc)}\n` +
+    `          data-gurulu-site-id=${JSON.stringify(injection.siteId)}\n` +
+    `          data-gurulu-tenant-id=${JSON.stringify(injection.tenantId)}\n` +
+    pkAttr +
+    `          ${MARKER}\n` +
+    `          async\n` +
+    `        />\n`
+  );
+}
+
+function injectScriptTag(source, injection) {
+  if (source.includes(MARKER)) return source;
+  const tag = buildScriptTag(injection);
+  // Prefer to insert just before <Scripts /> (self-closing or open tag).
+  if (/<Scripts\s*\/?>/.test(source)) {
+    return source.replace(/(<Scripts\s*\/?>)/, `${tag}        $1`);
+  }
+  // Fallback: before </body>.
+  if (/<\/body>/.test(source)) {
+    return source.replace(/<\/body>/, `${tag}      </body>`);
+  }
+  return source;
+}
+
+function plan(ctx) {
+  const detection = detect(ctx.repoRoot);
+  if (!detection) return { changes: [], notes: ['no-remix-root'] };
+  const changes = [];
+  for (const rel of detection.files) {
+    const abs = path.join(ctx.repoRoot, rel);
+    const before = fs.readFileSync(abs, 'utf8');
+    const after = injectScriptTag(before, ctx.injection);
+    if (after !== before) {
+      changes.push({ relPath: rel, before, after, reason: 'inject-script-tag' });
+    }
+  }
+  return { changes, notes: [] };
+}
+
+module.exports = { name: NAME, detect, plan };