@gurulu/cli 0.4.7 → 1.0.1

package/scripts/gurulu-agentic-install.mjs

@@ -1,623 +0,0 @@
-#!/usr/bin/env node
-// gurulu-agentic-install.mjs — Phase 14 B3 CLI wrapper.
-//
-// Reads a `gurulu-scan` JSON output and produces the 10 `.gurulu/` artifacts
-// that the runtime loader (Phase 13 B1) consumes. Pairs with:
-//   scripts/gurulu-scan.mjs       (Phase 13 B2 — scanner)
-//   scripts/gurulu-agentic-install.lib.cjs  (generator logic)
-//
-// Usage:
-//   node scripts/gurulu-agentic-install.mjs <scan-output.json> \
-//     --site-id <id> --tenant-id <id> [--output .gurulu/] [--dry-run] [--quiet]
-//
-// Pass `-` as the scan path to read JSON from stdin.
-
-import { createRequire } from 'node:module';
-import { readFileSync, statSync, existsSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { posix as posixPath } from 'node:path';
-
-const require = createRequire(import.meta.url);
-const lib = require('./gurulu-agentic-install.lib.cjs');
-const patches = require('./patches/index.cjs');
-
-export const {
-  INSTALL_AGENT_VERSION,
-  generateArtifacts,
-  generateInstallPlan,
-  generateCoreConfig,
-  generateWebConfig,
-  generateAppConfig,
-  generateServerMap,
-  generateDbMap,
-  generateFlowSeeds,
-  generateMilestoneRules,
-  generateCorrelationMap,
-  generateConnectors,
-  deriveBusinessSurfaces,
-  deriveMilestones,
-  inferEventName,
-  validateArtifacts,
-  writeArtifacts,
-} = lib;
-
-// ---------------------------------------------------------------------------
-// CLI entry
-// ---------------------------------------------------------------------------
-
-function parseArgs(argv) {
-  const args = { _: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === '--help' || a === '-h') {
-      args.help = true;
-    } else if (a === '--quiet' || a === '-q') {
-      args.quiet = true;
-    } else if (a === '--dry-run') {
-      args.dryRun = true;
-    } else if (a === '--apply') {
-      args.apply = true;
-    } else if (a === '--rollback') {
-      args.rollback = true;
-    } else if (a === '--auto-instrument') {
-      args.autoInstrument = true;
-    } else if (a.startsWith('--')) {
-      const key = a.slice(2);
-      args[key] = argv[++i];
-    } else {
-      args._.push(a);
-    }
-  }
-  return args;
-}
-
-function printHelp(out = process.stdout) {
-  out.write(
-    [
-      'Usage: node scripts/gurulu-agentic-install.mjs <scan-output.json> \\',
-      '         --site-id <id> --tenant-id <id> [--output .gurulu/] [--dry-run] [--quiet]',
-      '',
-      'Reads a gurulu-scan JSON document (pass `-` for stdin) and generates the',
-      '10 .gurulu/ artifacts ingested by the Phase 13 B1 runtime loader.',
-      '',
-      'Options:',
-      '  --site-id <id>     Stable site identifier (required)',
-      '  --tenant-id <id>   Tenant identifier (required)',
-      '  --publishable-key <key>  Stripe-style gpk_live_/gpk_test_ key (optional)',
-      '  --output <path>    Output directory (default: .gurulu)',
-      '  --domains <list>   Comma-separated host list for install-plan.domains',
-      '  --dry-run          Validate + report without writing files (default for patch mode)',
-      '  --apply            (patch mode) write patches + create backup',
-      '  --rollback         (patch mode) restore most recent backup',
-      '  --framework <f>    auto|nextjs-app|nextjs-pages|vite-react|express',
-      '  --auto-instrument  (Phase 18.7) Also write gurulu.track() calls into route handlers',
-      '  --intent-result <path>  JSON file with InstallIntent output (feeds --auto-instrument)',
-      '  --token <key>      CLI auth token for LLM property extraction API',
-      '  --api-url <url>    Base URL for the Gurulu API (default: https://gurulu.io)',
-      '  --quiet            Suppress non-error output',
-      '  -h, --help         Show this help',
-      '',
-    ].join('\n'),
-  );
-}
-
-async function readScanInput(scanFile) {
-  if (scanFile === '-') {
-    // stdin
-    const chunks = [];
-    for await (const chunk of process.stdin) chunks.push(chunk);
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-  }
-  return JSON.parse(readFileSync(scanFile, 'utf8'));
-}
-
-/**
- * Return a placeholder JS expression for a property that lacks an example
- * value. The placeholder includes a TODO comment so developers know to fill
- * in the real expression from their route handler context.
- */
-function getPropertyPlaceholder(type, name) {
-  switch (type) {
-    case 'string':  return `'' /* TODO: ${name} */`;
-    case 'number':  return `0 /* TODO: ${name} */`;
-    case 'boolean': return `false /* TODO: ${name} */`;
-    default:        return `undefined /* TODO: ${name} */`;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Route resolution: map "POST /api/checkout" → actual file path on disk.
-// Reuses the candidate patterns from the auto-instrument modules.
-// ---------------------------------------------------------------------------
-
-function parseRouteString(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(/\/+$/, '').split('?')[0] };
-}
-
-function resolveRouteFile(routeStr, framework, repoRoot) {
-  const parsed = parseRouteString(routeStr);
-  if (!parsed) return null;
-  const { urlPath } = parsed;
-  const segments = urlPath.split('/').filter(Boolean);
-
-  // Build candidate file paths based on framework.
-  const candidates = [];
-
-  // Next.js App Router patterns.
-  if (!framework || /next/i.test(framework)) {
-    const exts = ['ts', 'tsx', 'js', 'jsx'];
-    for (const ext of exts) {
-      candidates.push(posixPath.join('src', 'app', ...segments, `route.${ext}`));
-      candidates.push(posixPath.join('app', ...segments, `route.${ext}`));
-    }
-  }
-
-  // Next.js Pages API patterns.
-  if (!framework || /next.*pages/i.test(framework)) {
-    const exts = ['ts', 'tsx', 'js', 'jsx'];
-    for (const ext of exts) {
-      candidates.push(posixPath.join('src', 'pages', ...segments, `index.${ext}`));
-      candidates.push(posixPath.join('pages', ...segments, `index.${ext}`));
-      candidates.push(posixPath.join('src', 'pages', ...segments.slice(0, -1), `${segments[segments.length - 1]}.${ext}`));
-      candidates.push(posixPath.join('pages', ...segments.slice(0, -1), `${segments[segments.length - 1]}.${ext}`));
-    }
-  }
-
-  // Express / Fastify / generic patterns.
-  if (!framework || /express|fastify|nest|generic/i.test(framework)) {
-    const roots = ['src/routes', 'routes', 'src/api', 'api', 'src/controllers', 'controllers', 'src', 'app'];
-    const exts = ['ts', 'js', 'mjs', 'cjs'];
-    for (const root of roots) {
-      for (const ext of exts) {
-        // e.g. src/routes/checkout.ts
-        candidates.push(posixPath.join(root, ...segments.slice(1), `index.${ext}`));
-        if (segments.length > 1) {
-          candidates.push(posixPath.join(root, ...segments.slice(1, -1), `${segments[segments.length - 1]}.${ext}`));
-        }
-      }
-    }
-  }
-
-  // SvelteKit patterns.
-  if (!framework || /svelte/i.test(framework)) {
-    const exts = ['ts', 'js'];
-    for (const ext of exts) {
-      candidates.push(posixPath.join('src', 'routes', ...segments, `+server.${ext}`));
-    }
-  }
-
-  // Remix patterns.
-  if (!framework || /remix/i.test(framework)) {
-    const exts = ['ts', 'tsx', 'js', 'jsx'];
-    for (const ext of exts) {
-      candidates.push(posixPath.join('app', 'routes', segments.join('.') + `.${ext}`));
-    }
-  }
-
-  // Find first existing candidate.
-  for (const rel of candidates) {
-    const abs = path.join(repoRoot, rel);
-    if (existsSync(abs)) return abs;
-  }
-
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// LLM property extraction via the server API endpoint.
-// ---------------------------------------------------------------------------
-
-async function tryLlmExtraction(events, { repoRoot, framework, ingestUrl, token, siteId, log }) {
-  let llmHits = 0;
-  for (const event of events) {
-    // Skip if already has extracted properties.
-    if (event.extractedProperties && event.extractedProperties.length > 0) continue;
-
-    const routeStr = event.source && event.source.route;
-    if (!routeStr) continue;
-
-    const routeFile = resolveRouteFile(routeStr, framework, repoRoot);
-    if (!routeFile) continue;
-
-    let handlerSource;
-    try {
-      handlerSource = readFileSync(routeFile, 'utf-8');
-    } catch {
-      continue;
-    }
-
-    // Cap at 4KB to keep LLM calls reasonable.
-    const clipped = handlerSource.slice(0, 4096);
-
-    try {
-      const res = await fetch(`${ingestUrl}/api/cli/install/extract-properties`, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${token}`,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          siteId,
-          eventName: event.name,
-          handlerSource: clipped,
-          framework,
-        }),
-      });
-      if (res.ok) {
-        const data = await res.json();
-        if (data.properties && data.properties.length > 0 && data.confidence >= 0.7) {
-          event.extractedProperties = data.properties;
-          llmHits++;
-          log(`  LLM extracted ${data.properties.length} property(ies) for ${event.name} (confidence: ${data.confidence.toFixed(2)})`);
-        }
-      }
-    } catch {
-      // LLM extraction failed — fall through to placeholder.
-    }
-  }
-  return llmHits;
-}
-
-async function runPatchMode(repoRoot, args) {
-  const log = args.quiet ? () => {} : (m) => process.stdout.write(m + '\n');
-  if (args.rollback) {
-    const res = patches.rollback(repoRoot);
-    if (!res.rolledBack) {
-      process.stderr.write(`Rollback failed: ${res.reason}\n`);
-      process.exit(3);
-    }
-    log(`Rolled back ${res.files.length} files`);
-    return;
-  }
-  if (!args['site-id'] || !args['tenant-id']) {
-    process.stderr.write('Error: --site-id and --tenant-id are required for patch mode\n');
-    process.exit(1);
-  }
-  const framework = args.framework || 'auto';
-  const { patcher, detection, error, unsupportedFramework } = patches.resolvePatcher(repoRoot, framework);
-  if (error) {
-    process.stderr.write(`Error: ${error}\n`);
-    // 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');
-    process.exit(4);
-  }
-  const injection = patches.buildInjection({
-    siteId: args['site-id'],
-    tenantId: args['tenant-id'],
-    publishableKey: args['publishable-key'] || '',
-    scriptSrc: args['script-src'] || 'https://gurulu.io/t.js',
-  });
-  const plan = patcher.plan({ repoRoot, injection });
-  log(`Framework: ${patcher.name}`);
-  log(`Detected files: ${(detection?.files || []).join(', ') || '(none)'}`);
-  if (plan.changes.length === 0) {
-    log('No changes to apply (already installed or nothing to patch)');
-    return;
-  }
-  // Default behavior is dry-run unless --apply is passed.
-  const shouldApply = !!args.apply;
-  if (!shouldApply) {
-    for (const change of plan.changes) {
-      process.stdout.write(patches.unifiedDiff(change.relPath, change.before, change.after));
-    }
-    // Phase 18.7 B6 — include auto-instrument diff in dry-run output so
-    // users can eyeball what will be written before --apply.
-    if (args.autoInstrument && args['intent-result']) {
-      try {
-        const intent = JSON.parse(readFileSync(args['intent-result'], 'utf8'));
-        const acceptedEvents = (intent && intent.accepted && intent.accepted.events) || [];
-        const frameworkName = (patcher && patcher.name) || framework;
-
-        // Phase 20 — Try LLM-based property extraction first.
-        const ingestUrl = args['ingest-url'] || args['api-url'] || 'https://gurulu.io';
-        const token = args['token'] || args['api-key'] || '';
-        const siteId = args['site-id'] || '';
-        if (token) {
-          try {
-            const hits = await tryLlmExtraction(acceptedEvents, {
-              repoRoot,
-              framework: frameworkName,
-              ingestUrl,
-              token,
-              siteId,
-              log,
-            });
-            if (hits > 0) log(`LLM property extraction: ${hits} event(s) enriched`);
-          } catch (err) {
-            log(`LLM property extraction failed (using placeholders): ${err.message || err}`);
-          }
-        }
-
-        // Placeholder fallback for events that LLM didn't cover.
-        for (const event of acceptedEvents) {
-          if (event.extractedProperties && event.extractedProperties.length > 0) continue;
-          if (!event.propertySchema || !event.propertySchema.length) continue;
-          event.extractedProperties = event.propertySchema
-            .filter((p) => p.required)
-            .map((p) => ({
-              name: p.name,
-              type: p.type || 'unknown',
-              source: p.example !== undefined && p.example !== null
-                ? JSON.stringify(p.example)
-                : getPropertyPlaceholder(p.type, p.name),
-            }));
-        }
-        const aiResult = patches.autoInstrumentDispatch(
-          frameworkName,
-          { repoRoot },
-          acceptedEvents,
-        );
-        for (const change of aiResult.changes || []) {
-          process.stdout.write(
-            patches.unifiedDiff(change.relPath, change.before, change.after),
-          );
-        }
-        log(
-          `Auto-instrument dry-run: ${aiResult.filesModified} file(s) would change, ` +
-            `${aiResult.eventsInstrumented} event(s), ${aiResult.eventsSkipped} skipped.`,
-        );
-      } catch (err) {
-        process.stderr.write(
-          `Auto-instrument dry-run failed: ${err.message || err}\n`,
-        );
-      }
-    }
-    log(`Dry-run: ${plan.changes.length} file(s) would change. Re-run with --apply to write.`);
-    return;
-  }
-  const result = await patches.applyPlan(repoRoot, patcher, plan);
-  log(`Applied ${result.files.length} file change(s). Patch log: .gurulu/patch-log.json`);
-
-  // -------------------------------------------------------------------
-  // Phase 18.7 B6 — Auto-instrumentation (opt-in).
-  // 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.
-  //
-  // 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) {
-      // 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;
-    try {
-      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;
-    }
-
-    const frameworkName = (patcher && patcher.name) || framework;
-
-    // Phase 20 — Try LLM-based property extraction first.
-    const ingestUrl = args['ingest-url'] || args['api-url'] || 'https://gurulu.io';
-    const token = args['token'] || args['api-key'] || '';
-    const siteId = args['site-id'] || '';
-    if (token) {
-      try {
-        const hits = await tryLlmExtraction(acceptedEvents, {
-          repoRoot,
-          framework: frameworkName,
-          ingestUrl,
-          token,
-          siteId,
-          log,
-        });
-        if (hits > 0) log(`LLM property extraction: ${hits} event(s) enriched`);
-      } catch (err) {
-        log(`LLM property extraction failed (using placeholders): ${err.message || err}`);
-      }
-    }
-
-    // Placeholder fallback: enrich events with extractedProperties from
-    // propertySchema for any events the LLM didn't cover.
-    for (const event of acceptedEvents) {
-      if (event.extractedProperties && event.extractedProperties.length > 0) continue;
-      if (!event.propertySchema || !event.propertySchema.length) continue;
-      event.extractedProperties = event.propertySchema
-        .filter((p) => p.required)
-        .map((p) => ({
-          name: p.name,
-          type: p.type || 'unknown',
-          source: p.example !== undefined && p.example !== null
-            ? JSON.stringify(p.example)
-            : getPropertyPlaceholder(p.type, p.name),
-        }));
-    }
-    const aiResult = patches.autoInstrumentDispatch(
-      frameworkName,
-      { repoRoot },
-      acceptedEvents,
-    );
-    if (aiResult.collision) {
-      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) {
-      log(`Auto-instrument: 0 file(s) changed (${aiResult.eventsSkipped} event(s) skipped)`);
-      for (const note of aiResult.notes || []) log(`  note: ${note}`);
-      return;
-    }
-    try {
-      const aiApply = await patches.applyAutoInstrumentPlan(repoRoot, {
-        framework: frameworkName,
-        changes: aiResult.changes,
-      });
-      log(
-        `Auto-instrument: ${aiResult.filesModified} file(s) instrumented, ` +
-          `${aiResult.eventsInstrumented} event(s), ${aiResult.eventsSkipped} skipped`,
-      );
-      log(`Auto-instrument: wrote ${aiApply.files.length} change(s) to patch-log`);
-      // Emit a machine-readable summary on stdout so the CLI can capture it.
-      process.stdout.write(
-        'AUTO_INSTRUMENT_RESULT ' +
-          JSON.stringify({
-            filesModified: aiResult.filesModified,
-            eventsInstrumented: aiResult.eventsInstrumented,
-            eventsSkipped: aiResult.eventsSkipped,
-            notes: aiResult.notes || [],
-          }) +
-          '\n',
-      );
-    } 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');
-    }
-  }
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    printHelp();
-    process.exit(0);
-  }
-  const input = args._[0];
-  if (!input) {
-    process.stderr.write('Error: input path is required (scan json or repo root)\n');
-    printHelp(process.stderr);
-    process.exit(1);
-  }
-
-  // Patch-mode: when input is a directory we run the code editor pipeline.
-  const isDirectory = input !== '-' && existsSync(input) && statSync(input).isDirectory();
-  if (isDirectory) {
-    await runPatchMode(input, args);
-    return;
-  }
-
-  const scanFile = input;
-  if (!args['site-id'] || !args['tenant-id']) {
-    process.stderr.write('Error: --site-id and --tenant-id are required\n');
-    process.exit(1);
-  }
-
-  const outputPath = args.output || '.gurulu';
-  const log = args.quiet ? () => {} : (m) => process.stderr.write(m + '\n');
-
-  let scanOutput;
-  try {
-    scanOutput = await readScanInput(scanFile);
-  } catch (err) {
-    process.stderr.write(`Error: failed to read scan input: ${err.message}\n`);
-    process.exit(1);
-  }
-
-  const domains = typeof args.domains === 'string'
-    ? args.domains.split(',').map((d) => d.trim()).filter(Boolean)
-    : undefined;
-
-  const result = generateArtifacts(scanOutput, {
-    siteId: args['site-id'],
-    tenantId: args['tenant-id'],
-    outputPath,
-    ...(domains ? { domains } : {}),
-  });
-
-  const validation = validateArtifacts(result.artifacts);
-  if (!validation.ok) {
-    process.stderr.write('Validation failed — not writing any files:\n');
-    for (const err of validation.errors) {
-      process.stderr.write(`  ${err.file}: ${err.message}\n`);
-    }
-    process.exit(2);
-  }
-
-  const filenames = Object.keys(result.artifacts);
-  if (args.dryRun) {
-    log(`Dry-run — would write ${filenames.length} files to ${outputPath}/:`);
-    for (const f of filenames) log(`  ${outputPath}/${f}`);
-    return;
-  }
-
-  await writeArtifacts(result.artifacts, outputPath);
-  log(`Wrote ${filenames.length} artifacts to ${outputPath}/`);
-}
-
-const invokedDirectly =
-  typeof process !== 'undefined' &&
-  process.argv[1] &&
-  (() => {
-    try {
-      return fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
-    } catch {
-      return false;
-    }
-  })();
-
-if (invokedDirectly) {
-  main().catch((err) => {
-    process.stderr.write(`[agentic-install] ERROR: ${err.stack || err.message || err}\n`);
-    process.exit(1);
-  });
-}