@gurulu/cli 0.4.2 → 0.4.4

package/dist/commands/install.js

@@ -48,18 +48,24 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkspaceRoot = resolveWorkspaceRoot;
 exports.resolveScriptsDir = resolveScriptsDir;
 exports.detectPackageManager = detectPackageManager;
 exports.packageInstallArgs = packageInstallArgs;
+exports.parseEnvFile = parseEnvFile;
 exports.mergeEnvFile = mergeEnvFile;
 exports.createDefaultDeps = createDefaultDeps;
 exports.runInstallFlow = runInstallFlow;
+exports.isTelemetryDisabled = isTelemetryDisabled;
+exports.maybePromptTelemetryConsent = maybePromptTelemetryConsent;
 exports.repoHashOf = repoHashOf;
 exports.pickSite = pickSite;
 exports.emitInstallTelemetry = emitInstallTelemetry;
+exports.detectCiEnv = detectCiEnv;
 exports.runAuthenticatedInstallFlow = runAuthenticatedInstallFlow;
 exports.installCommand = installCommand;
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const crypto = __importStar(require("crypto"));
 const child_process_1 = require("child_process");
@@ -68,6 +74,159 @@ const config_1 = require("../config");
 const api_client_1 = require("../api-client");
 const install_intent_proposal_1 = require("../install-intent-proposal");
 // ---------------------------------------------------------------------------
+// Sprint E1.5 — Workspace resolution.
+//
+// Many fresh repos are npm/pnpm/yarn workspaces (Turborepo, Nx, Bun, etc).
+// Running `gurulu install` from the repo root is ambiguous: should we patch
+// the `apps/web/` Next.js app, the `apps/admin/` dashboard, or one of the
+// `packages/*` libraries? When package.json declares >=2 workspace globs we
+// either (a) honour `--workspace=<path>` if set, or (b) prompt the user
+// interactively. The resolved path becomes `repoRoot` for the rest of the
+// install flow.
+// ---------------------------------------------------------------------------
+function walkForPackageJson(root, depth, out) {
+    // FA-1 P1-7 — recursive walker for `**/*` and `apps/**` style globs used by
+    // Turborepo and Yarn berry monorepos. We cap depth to avoid descending into
+    // node_modules / .git / huge build trees, and we only collect directories
+    // that actually contain a package.json.
+    if (depth < 0)
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        if (e.name === 'node_modules' || e.name === '.git' || e.name.startsWith('.'))
+            continue;
+        const abs = path.join(root, e.name);
+        if (fs.existsSync(path.join(abs, 'package.json')))
+            out.push(abs);
+        walkForPackageJson(abs, depth - 1, out);
+    }
+}
+function expandWorkspaceGlobs(repoRoot, globs) {
+    // FA-1 P1-7 — workspace glob support now covers:
+    //   - bare `dir`               (single workspace)
+    //   - `dir/*`                  (immediate children — npm/pnpm/yarn classic)
+    //   - `dir/**`, `dir/**/*`     (Turborepo / Yarn berry recursive)
+    //   - `!packages/excluded`     (negation filter, applied after expansion)
+    //   - `workspace:*` protocol   (Yarn berry — skipped, not a glob)
+    const positives = [];
+    const negatives = [];
+    for (const raw of globs) {
+        if (!raw || typeof raw !== 'string')
+            continue;
+        // Yarn berry sometimes lists `workspace:*` protocol entries — skip; they
+        // are dependency declarations, not workspace path globs.
+        if (raw.startsWith('workspace:'))
+            continue;
+        if (raw.startsWith('!')) {
+            negatives.push(raw.slice(1));
+        }
+        else {
+            positives.push(raw);
+        }
+    }
+    const collected = new Set();
+    for (const g of positives) {
+        // `dir/**`, `dir/**/*` — recursive walk up to 4 levels deep.
+        if (g.endsWith('/**') || g.endsWith('/**/*') || g === '**' || g === '**/*') {
+            const root = g === '**' || g === '**/*'
+                ? repoRoot
+                : path.join(repoRoot, g.replace(/\/\*\*(\/\*)?$/, ''));
+            if (!fs.existsSync(root))
+                continue;
+            const acc = [];
+            walkForPackageJson(root, 4, acc);
+            for (const a of acc)
+                collected.add(a);
+            continue;
+        }
+        if (g.endsWith('/*')) {
+            const parent = path.join(repoRoot, g.slice(0, -2));
+            if (!fs.existsSync(parent))
+                continue;
+            try {
+                for (const entry of fs.readdirSync(parent)) {
+                    const abs = path.join(parent, entry);
+                    if (fs.statSync(abs).isDirectory() &&
+                        fs.existsSync(path.join(abs, 'package.json'))) {
+                        collected.add(abs);
+                    }
+                }
+            }
+            catch {
+                /* ignore */
+            }
+            continue;
+        }
+        // Bare directory.
+        const abs = path.join(repoRoot, g);
+        if (fs.existsSync(abs) && fs.existsSync(path.join(abs, 'package.json'))) {
+            collected.add(abs);
+        }
+    }
+    // Apply negations as simple suffix-match against the relative path.
+    if (negatives.length > 0) {
+        for (const dir of Array.from(collected)) {
+            const rel = path.relative(repoRoot, dir);
+            for (const n of negatives) {
+                const negResolved = n.replace(/\/\*+$/, '');
+                if (rel === negResolved || rel.startsWith(negResolved + path.sep)) {
+                    collected.delete(dir);
+                    break;
+                }
+            }
+        }
+    }
+    return Array.from(collected);
+}
+async function resolveWorkspaceRoot(repoRoot, args, deps) {
+    const pkgPath = path.join(repoRoot, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return repoRoot;
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    }
+    catch {
+        return repoRoot;
+    }
+    let globs = null;
+    if (Array.isArray(pkg.workspaces))
+        globs = pkg.workspaces;
+    else if (pkg.workspaces && Array.isArray(pkg.workspaces.packages))
+        globs = pkg.workspaces.packages;
+    if (!globs || globs.length === 0)
+        return repoRoot;
+    const candidates = expandWorkspaceGlobs(repoRoot, globs);
+    if (candidates.length <= 1)
+        return repoRoot;
+    if (args.workspace) {
+        const target = path.resolve(repoRoot, args.workspace);
+        if (candidates.some((c) => path.resolve(c) === target))
+            return target;
+        log(deps, 'warn', `--workspace=${args.workspace} not found among workspace packages.`);
+    }
+    if (args.yes) {
+        log(deps, 'warn', `Multiple workspaces detected (${candidates.length}); pass --workspace=<path> next time.`);
+        return repoRoot;
+    }
+    log(deps, 'info', 'Multiple workspaces detected:');
+    candidates.forEach((c, i) => log(deps, 'info', `  [${i + 1}] ${path.relative(repoRoot, c)}`));
+    const answer = (await deps.prompt('  Select workspace [1]: ')).trim() || '1';
+    const idx = parseInt(answer, 10) - 1;
+    if (Number.isFinite(idx) && idx >= 0 && idx < candidates.length) {
+        return candidates[idx];
+    }
+    return repoRoot;
+}
+// ---------------------------------------------------------------------------
 // Script resolution
 // ---------------------------------------------------------------------------
 /**
@@ -95,6 +254,14 @@ function resolveScriptsDir(startDir = __dirname) {
 // Package-manager detection
 // ---------------------------------------------------------------------------
 function detectPackageManager(repoRoot) {
+    // FA-1 P1-6 — Bun support. Bun ships either `bun.lockb` (binary) or
+    // `bun.lock` (text, newer Bun releases). Detect both before falling back
+    // to pnpm/yarn/npm so monorepos using Bun don't get installed with the
+    // wrong package manager.
+    if (fs.existsSync(path.join(repoRoot, 'bun.lockb')) ||
+        fs.existsSync(path.join(repoRoot, 'bun.lock'))) {
+        return 'bun';
+    }
     if (fs.existsSync(path.join(repoRoot, 'pnpm-lock.yaml')))
         return 'pnpm';
     if (fs.existsSync(path.join(repoRoot, 'yarn.lock')))
@@ -106,8 +273,94 @@ function packageInstallArgs(pm) {
         return ['add', '@gurulu/web'];
     if (pm === 'yarn')
         return ['add', '@gurulu/web'];
+    if (pm === 'bun')
+        return ['add', '@gurulu/web'];
     return ['install', '@gurulu/web'];
 }
+// FA-1 P1-8 — full dotenv-compatible parser. The previous one-line
+// `KEY=value` split mis-handled (a) quoted values with `=` inside,
+// (b) multi-line values inside double-quotes (escape `\n`), and (c) the
+// `export KEY=value` form some teams use. This parser walks the file
+// character-by-character, tracking whether we're inside a quoted value, so
+// the existing-keys set actually contains every declared key — preventing
+// duplicate writes that would override the user's values.
+function parseEnvFile(text) {
+    const keys = new Set();
+    let i = 0;
+    const n = text.length;
+    while (i < n) {
+        // Skip leading whitespace + newlines.
+        while (i < n && (text[i] === ' ' || text[i] === '\t' || text[i] === '\r' || text[i] === '\n')) {
+            i++;
+        }
+        if (i >= n)
+            break;
+        // Comment line.
+        if (text[i] === '#') {
+            while (i < n && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        // Optional `export ` prefix.
+        if (text.startsWith('export ', i) || text.startsWith('export\t', i)) {
+            i += 7;
+            while (i < n && (text[i] === ' ' || text[i] === '\t'))
+                i++;
+        }
+        // Key.
+        const keyStart = i;
+        while (i < n && text[i] !== '=' && text[i] !== '\n' && text[i] !== '#')
+            i++;
+        const key = text.slice(keyStart, i).trim();
+        if (text[i] !== '=') {
+            // No `=` on this line — skip to next newline.
+            while (i < n && text[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (key && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            keys.add(key);
+        }
+        i++; // consume '='
+        // Value — handles "..." (multi-line, escape-aware), '...', and bare.
+        if (text[i] === '"') {
+            i++;
+            while (i < n) {
+                if (text[i] === '\\' && i + 1 < n) {
+                    i += 2;
+                    continue;
+                }
+                if (text[i] === '"') {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+        }
+        else if (text[i] === "'") {
+            i++;
+            while (i < n && text[i] !== "'")
+                i++;
+            if (i < n)
+                i++;
+        }
+        else if (text[i] === '`') {
+            i++;
+            while (i < n && text[i] !== '`')
+                i++;
+            if (i < n)
+                i++;
+        }
+        else {
+            while (i < n && text[i] !== '\n' && text[i] !== '#')
+                i++;
+        }
+        // Skip rest of the line (trailing comment / whitespace).
+        while (i < n && text[i] !== '\n')
+            i++;
+    }
+    return keys;
+}
 function mergeEnvFile(repoRoot, framework, vars) {
     const isNext = framework.startsWith('nextjs') || framework === 'nextjs';
     const filename = isNext ? '.env.local' : '.env';
@@ -116,11 +369,9 @@ function mergeEnvFile(repoRoot, framework, vars) {
     if (fs.existsSync(filePath)) {
         existing = fs.readFileSync(filePath, 'utf8');
     }
-    const existingKeys = new Set(existing
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l && !l.startsWith('#'))
-        .map((l) => l.split('=')[0].trim()));
+    // FA-1 P1-8 — proper quoted/multiline-aware parse so we don't shadow keys
+    // the user already defined inside `KEY="multi\nline"` blocks.
+    const existingKeys = parseEnvFile(existing);
     const added = [];
     const skipped = [];
     const linesToAppend = [];
@@ -129,7 +380,13 @@ function mergeEnvFile(repoRoot, framework, vars) {
             skipped.push(key);
             continue;
         }
-        linesToAppend.push(`${key}=${value}`);
+        // Quote values that contain whitespace, `=`, `#`, or quotes themselves so
+        // they round-trip through any standard dotenv parser.
+        const needsQuote = /[\s="#\\]/.test(value);
+        const serialized = needsQuote
+            ? `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+            : value;
+        linesToAppend.push(`${key}=${serialized}`);
         added.push(key);
     }
     if (linesToAppend.length > 0) {
@@ -140,6 +397,38 @@ function mergeEnvFile(repoRoot, framework, vars) {
     return { file: filename, added, skipped };
 }
 // ---------------------------------------------------------------------------
+// Sprint E2.2 — Fetch canonical install prompt from server endpoint.
+// ---------------------------------------------------------------------------
+async function fetchInstallPrompt(opts) {
+    const fallback = `I have Gurulu analytics installed. Site ID: ${opts.siteId}\n` +
+        `Analyze my codebase and add gurulu.track() calls to\n` +
+        `important user actions: signups, purchases, form submits,\n` +
+        `button clicks, and key conversions. Use the Gurulu MCP\n` +
+        `server (@gurulu/mcp-server) for live event verification.\n` +
+        `Docs: https://gurulu.io/docs/quick-start`;
+    if (!opts.authToken || !opts.siteId)
+        return fallback;
+    try {
+        const url = new URL('/api/cli/install/prompt', opts.ingestUrl);
+        url.searchParams.set('siteId', opts.siteId);
+        if (opts.framework)
+            url.searchParams.set('framework', opts.framework);
+        const res = await globalThis.fetch(url.toString(), {
+            headers: { authorization: `Bearer ${opts.authToken}` },
+        });
+        if (!res.ok)
+            return fallback;
+        const body = await res.json();
+        if (body && typeof body.prompt === 'string' && body.prompt.length > 0) {
+            return body.prompt;
+        }
+        return fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+// ---------------------------------------------------------------------------
 // Default dependency implementations (real spawn + real fetch)
 // ---------------------------------------------------------------------------
 function createDefaultDeps(scriptsDir) {
@@ -251,7 +540,11 @@ function getEnvPrefix(framework) {
     return ''; // Express, Fastify, NestJS don't need prefix
 }
 async function runInstallFlow(args, deps, scriptsDir) {
-    const repoRoot = path.resolve(args.path || process.cwd());
+    const initialRoot = path.resolve(args.path || process.cwd());
+    // Sprint E1.5 — workspace resolution. When the project is a multi-package
+    // workspace, narrow `repoRoot` to the chosen workspace package so scan,
+    // patches, .env merge, and npm install all target the right place.
+    const repoRoot = await resolveWorkspaceRoot(initialRoot, args, deps);
     const summary = {
         scan: null,
         framework: null,
@@ -339,6 +632,16 @@ async function runInstallFlow(args, deps, scriptsDir) {
             planArgs.push('--intent-result', args.intentResultPath);
         }
     }
+    // FA-1 P0-2 — forward self-hosted overrides so the dry-run plan, the
+    // applied tracker tag, and the LLM endpoint base all agree. Without this
+    // self-hosted installs render `<script src="https://gurulu.io/t.js">` even
+    // when the user pointed `--ingest-url` at their own host.
+    if (args.ingestUrl) {
+        planArgs.push('--ingest-url', args.ingestUrl);
+    }
+    if (args.scriptSrc) {
+        planArgs.push('--script-src', args.scriptSrc);
+    }
     const planRes = await deps.runNode(planArgs);
     summary.planDiff = planRes.stdout;
     if (planRes.code !== 0) {
@@ -389,13 +692,52 @@ async function runInstallFlow(args, deps, scriptsDir) {
                 applyArgs.push('--intent-result', args.intentResultPath);
             }
         }
+        // FA-1 P0-2 — also forward to --apply so the file actually written to
+        // disk uses the correct tracker URL.
+        if (args.ingestUrl) {
+            applyArgs.push('--ingest-url', args.ingestUrl);
+        }
+        if (args.scriptSrc) {
+            applyArgs.push('--script-src', args.scriptSrc);
+        }
         const applyRes = await deps.runNode(applyArgs);
+        // Sprint E1.1 — exit code 5 means the agentic-install script auto-rolled
+        // back due to an auto-instrument failure. Mark the summary as rolled back
+        // and skip the npm install / .env merge / ingest ping blocks so the user
+        // isn't left with a half-installed setup.
+        if (applyRes.code === 5) {
+            summary.rolledBack = true;
+            summary.partiallyInstalled = false;
+            log(deps, 'warn', '⚠ Install rolled back (auto-instrument failed; script tag reverted).');
+            return summary;
+        }
         if (applyRes.code !== 0) {
             const msg = `Apply failed (exit ${applyRes.code}): ${applyRes.stderr.trim()}`;
             summary.errors.push(msg);
             log(deps, 'error', msg);
             return summary;
         }
+        // Sprint E1.7 — record components that were successfully installed for
+        // partial-install diagnostics in the summary.
+        // CLI@0.4.4 — re-run idempotency: dedupe via Set so a second `gurulu install`
+        // pass on the same project does not double-list components. Component IDs
+        // hash siteId + framework + path so two different sites in the same repo
+        // remain distinct.
+        const componentScope = `${args.site || args.siteId || 'unknown'}::${args.framework || 'auto'}::${args.path || process.cwd()}`;
+        const existingComponents = new Set(summary.installedComponents || []);
+        const addComponent = (id) => {
+            const key = `${id}@${componentScope}`;
+            if (existingComponents.has(key)) {
+                log(deps, 'info', `Skipping ${id} — already installed for this scope`);
+                return;
+            }
+            existingComponents.add(key);
+        };
+        addComponent('script-tag');
+        addComponent('patch-log');
+        if (args.autoInstrument)
+            addComponent('auto-instrument');
+        summary.installedComponents = Array.from(existingComponents);
         // Parse the machine-readable auto-instrument result line if present.
         if (args.autoInstrument) {
             const lines = (applyRes.stdout || '').split('\n');
@@ -427,6 +769,29 @@ async function runInstallFlow(args, deps, scriptsDir) {
             }
         }
         log(deps, 'success', 'Patches applied.');
+        // Sprint E5.2 — wire a `postbuild` script for Next.js projects so the
+        // CLI's sourcemap uploader runs automatically after every `next build`.
+        // We only touch package.json when the framework is Next.js AND the user
+        // hasn't already defined a `postbuild` (idempotent).
+        if (detectedFw && detectedFw.startsWith('nextjs')) {
+            try {
+                const pkgPath = path.join(repoRoot, 'package.json');
+                if (fs.existsSync(pkgPath)) {
+                    const raw = fs.readFileSync(pkgPath, 'utf8');
+                    const pkgJson = JSON.parse(raw);
+                    pkgJson.scripts = pkgJson.scripts || {};
+                    if (!pkgJson.scripts.postbuild) {
+                        pkgJson.scripts.postbuild =
+                            'gurulu sourcemap upload --release ${npm_package_version} --dir .next/static/chunks';
+                        fs.writeFileSync(pkgPath, JSON.stringify(pkgJson, null, 2) + '\n');
+                        log(deps, 'info', 'Added `postbuild` script for sourcemap upload.');
+                    }
+                }
+            }
+            catch (err) {
+                log(deps, 'warn', `Could not add postbuild script: ${err.message}`);
+            }
+        }
     }
     else {
         if (args.autoInstrument) {
@@ -575,13 +940,21 @@ async function runInstallFlow(args, deps, scriptsDir) {
         console.log('');
         log(deps, 'info', `  ${(0, ui_1.dim)('Or paste this prompt into your AI assistant:')}`);
         console.log('');
+        // Sprint E2.2 — fetch the canonical install prompt from the server so
+        // edits land in `src/lib/cli/install-prompt.ts` (the single source of
+        // truth) instead of being duplicated in three places. We fall back to a
+        // tiny inline body when the endpoint is unreachable or unauthenticated
+        // so legacy installs still see something useful.
+        const promptText = await fetchInstallPrompt({
+            siteId,
+            ingestUrl: args.ingestUrl || process.env.GURULU_INGEST_URL || 'https://gurulu.io',
+            authToken: args.authToken,
+            framework: summary.framework || undefined,
+        });
         console.log((0, ui_1.dim)('  ┌─────────────────────────────────────────────'));
-        console.log((0, ui_1.dim)('  │ ') + 'I have Gurulu analytics installed. Site ID: ' + (0, ui_1.cyan)(siteId));
-        console.log((0, ui_1.dim)('  │ ') + 'Analyze my codebase and add gurulu.track() calls to');
-        console.log((0, ui_1.dim)('  │ ') + 'important user actions: signups, purchases, form submits,');
-        console.log((0, ui_1.dim)('  │ ') + 'button clicks, and key conversions. Use the Gurulu MCP');
-        console.log((0, ui_1.dim)('  │ ') + 'server (@gurulu/mcp-server) for live event verification.');
-        console.log((0, ui_1.dim)('  │ ') + 'Docs: https://gurulu.io/docs/quick-start');
+        for (const line of promptText.split('\n')) {
+            console.log((0, ui_1.dim)('  │ ') + line);
+        }
         console.log((0, ui_1.dim)('  └─────────────────────────────────────────────'));
         console.log('');
         // Goals & funnels management
@@ -613,7 +986,91 @@ async function runInstallFlow(args, deps, scriptsDir) {
     }
     return summary;
 }
+// ---------------------------------------------------------------------------
+// FA-1 P0-5 — Telemetry consent gate (GDPR).
+//
+// `emitInstallTelemetry` previously fired on every install with a repo hash,
+// framework, and CLI version — no consent recorded. We now:
+//   1. Honor opt-out via env (`GURULU_TELEMETRY=off|0`, `DO_NOT_TRACK=1`),
+//      CLI flag (`--no-telemetry`), and persisted CLI config
+//      (`~/.gurulu/config.json` → `telemetry: false`).
+//   2. Prompt for consent on first interactive install and persist the
+//      answer in the same config file.
+//   3. Skip `repoHashOf` computation entirely when telemetry is disabled.
+// ---------------------------------------------------------------------------
+function cliConfigPath() {
+    if (process.env.GURULU_CONFIG_HOME) {
+        return path.join(process.env.GURULU_CONFIG_HOME, 'config.json');
+    }
+    return path.join(os.homedir(), '.gurulu', 'config.json');
+}
+function readCliConfig() {
+    try {
+        const p = cliConfigPath();
+        if (!fs.existsSync(p))
+            return {};
+        const txt = fs.readFileSync(p, 'utf8');
+        const parsed = JSON.parse(txt);
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCliConfig(patch) {
+    try {
+        const p = cliConfigPath();
+        const dir = path.dirname(p);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const current = readCliConfig();
+        const next = { ...current, ...patch };
+        fs.writeFileSync(p, JSON.stringify(next, null, 2));
+        try {
+            fs.chmodSync(p, 0o600);
+        }
+        catch {
+            /* non-unix */
+        }
+    }
+    catch {
+        /* best-effort persistence */
+    }
+}
+function isTelemetryDisabled() {
+    const env = (process.env.GURULU_TELEMETRY || '').toLowerCase();
+    if (env === 'off' || env === '0' || env === 'false' || env === 'no')
+        return true;
+    if (process.env.DO_NOT_TRACK === '1')
+        return true;
+    if (process.argv.includes('--no-telemetry'))
+        return true;
+    const cfg = readCliConfig();
+    if (cfg.telemetry === false)
+        return true;
+    return false;
+}
+/**
+ * First-run consent prompt. Persists the decision so we never re-ask.
+ * No-op when telemetry is already disabled, when a decision is already
+ * recorded, or in non-interactive (`--yes` / `--no-interactive`) mode.
+ */
+async function maybePromptTelemetryConsent(ask, args = {}) {
+    if (isTelemetryDisabled())
+        return;
+    const cfg = readCliConfig();
+    if (typeof cfg.telemetry === 'boolean')
+        return; // already decided
+    if (args.yes)
+        return; // non-interactive: don't ask, default-on but unrecorded
+    const answer = await ask('  Send anonymous install telemetry (framework, CLI version, repo hash) to improve Gurulu? [Y/n]: ');
+    const decided = !answer || !/^n/i.test(answer.trim());
+    writeCliConfig({ telemetry: decided, telemetry_decided_at: new Date().toISOString() });
+}
 function repoHashOf(repoRoot, remoteUrl = null) {
+    // Consent-gated: when telemetry is off, never compute the hash.
+    if (isTelemetryDisabled())
+        return '';
     const h = crypto.createHash('sha256');
     h.update(path.resolve(repoRoot));
     if (remoteUrl)
@@ -630,6 +1087,12 @@ function pickSite(sites, target) {
 }
 /** Send a telemetry POST. Never throws — quota errors are surfaced via `ok`. */
 async function emitInstallTelemetry(deps, payload) {
+    // FA-1 P0-5 — GDPR consent gate. Skip the POST entirely when the user has
+    // opted out via env/flag/config. Returns ok:true so callers don't surface
+    // a fake failure for an intentional opt-out.
+    if (isTelemetryDisabled()) {
+        return { ok: true, quotaExceeded: false };
+    }
     try {
         const res = await deps.postVerify({
             source: 'cli',
@@ -643,7 +1106,48 @@ async function emitInstallTelemetry(deps, payload) {
         return { ok: false, quotaExceeded: false };
     }
 }
+// FA-1 P0-1 — Detect popular CI environments. When a CI is detected and the
+// caller didn't already pass `--yes`, we force non-interactive mode so any
+// `prompt()` calls fall through to the documented default instead of blocking
+// on a closed stdin (which causes the entire install to hang in CI).
+const CI_ENV_VARS = [
+    'CI',
+    'VERCEL',
+    'GITHUB_ACTIONS',
+    'NETLIFY',
+    'GITLAB_CI',
+    'CIRCLECI',
+    'TRAVIS',
+    'BUILDKITE',
+];
+function detectCiEnv(env = process.env) {
+    return CI_ENV_VARS.some((v) => {
+        const raw = env[v];
+        if (!raw)
+            return false;
+        const lower = String(raw).toLowerCase();
+        return lower === '1' || lower === 'true';
+    });
+}
 async function runAuthenticatedInstallFlow(args, authDeps, installDeps, scriptsDir) {
+    // FA-1 P0-1 — CI environments do not have an interactive stdin. Without
+    // this guard every `prompt()` (`Continue with install? [Y/n]`, workspace
+    // picker, telemetry consent, auto-instrument confirm, etc.) blocks on EOF
+    // and the CI job times out instead of failing fast. Default to `--yes` so
+    // every prompt accepts the documented default and the flow can complete.
+    if (!args.yes && detectCiEnv()) {
+        installDeps.log?.info('[install] CI environment detected, defaulting to --yes');
+        args = { ...args, yes: true };
+    }
+    // FA-1 P0-5 — telemetry consent prompt on first interactive install.
+    // Persisted to ~/.gurulu/config.json so we never re-ask.
+    try {
+        const ask = authDeps.prompt || ((q) => installDeps.prompt(q));
+        await maybePromptTelemetryConsent(ask, { yes: args.yes });
+    }
+    catch {
+        /* never block install on consent prompt errors */
+    }
     // Site selection
     let selected = pickSite(authDeps.sites, args.site);
     if (!selected) {
@@ -726,7 +1230,13 @@ async function runAuthenticatedInstallFlow(args, authDeps, installDeps, scriptsD
                     installDeps.log?.warn(`Intent analyzer failed: ${err.message}`);
                     installDeps.log?.warn('⚠ Falling back to built-in generic event set.');
                     intentRecord.error = `analyze_failed:${err.message}`;
-                    intentRecord.analyzed = true; // Mark as analyzed so auto-instrument proceeds
+                    // Sprint E1.2 — distinguish "analyzer ran" from "fallback was used".
+                    // `analyzed=false` so callers can detect that the LLM/heuristic
+                    // analyzer never produced a real result; `analyze_status='fallback'`
+                    // tells them the install still proceeded with a baked-in event set
+                    // instead of failing outright.
+                    intentRecord.analyzed = false;
+                    intentRecord.analyze_status = 'fallback';
                     // Client-side fallback: produce a minimal generic intent so
                     // auto-instrument and pre-seed still work even when the API is down.
                     intent = {
@@ -819,7 +1329,11 @@ async function runAuthenticatedInstallFlow(args, authDeps, installDeps, scriptsD
     let autoInstrumentEnabled = !!args.autoInstrument;
     let intentResultPath;
     if (autoInstrumentEnabled) {
-        if (!intentRecord.analyzed || !intentRecord.accepted || intentRecord.accepted.events === 0) {
+        // Sprint E1.2 — accept either `analyzed=true` OR a fallback intent so
+        // auto-instrument still proceeds when the analyzer crashed and we fell
+        // back to the built-in generic event set.
+        const intentUsable = intentRecord.analyzed || intentRecord.analyze_status === 'fallback';
+        if (!intentUsable || !intentRecord.accepted || intentRecord.accepted.events === 0) {
             installDeps.log?.warn('Auto-instrument requested but no accepted events from intent discovery; disabling.');
             autoInstrumentEnabled = false;
         }
@@ -950,6 +1464,13 @@ async function installCommand(args) {
     // verify as strictly opt-in: only `args.verify === true` runs it. We also
     // patch the CLI option default in `src/index.ts` so the flag matches.
     args = { ...args, verify: args.verify === true };
+    // FA-1 P0-1 — top-level CI guard so the legacy unauthenticated path also
+    // skips interactive prompts when run from CI. (The authenticated flow
+    // re-checks inside `runAuthenticatedInstallFlow` for unit-test clarity.)
+    if (!args.yes && detectCiEnv()) {
+        console.log('[install] CI environment detected, defaulting to --yes');
+        args = { ...args, yes: true };
+    }
     // Legacy unauthenticated path: --site-id passed explicitly and no active profile.
     const profile = await (0, config_1.getActiveProfile)({ profile: args.profile });
     const legacyMode = !!args.siteId && !profile;
@@ -1011,18 +1532,33 @@ async function installCommand(args) {
         },
         intent: {
             analyze: async (signals) => {
-                const res = await (0, api_client_1.cliApi)('/api/cli/install/analyze-intent', {
-                    method: 'POST',
-                    preloadedProfile: profile,
-                    body: JSON.stringify({ signals }),
-                    noExitOnError: true,
-                });
-                const text = await res.text();
-                const parsed = text ? JSON.parse(text) : {};
-                if (!res.ok) {
-                    throw new Error((parsed && parsed.message) || `HTTP ${res.status}`);
+                // FA-1 P0-3 — bound the LLM round-trip. Without this guard a hung
+                // upstream stalls the whole install (Sprint E1.2 fallback never
+                // fires until the request finally errors out). 30s mirrors the
+                // tryLlmExtraction timeout in scripts/gurulu-agentic-install.mjs.
+                try {
+                    const res = await (0, api_client_1.cliApi)('/api/cli/install/analyze-intent', {
+                        method: 'POST',
+                        preloadedProfile: profile,
+                        body: JSON.stringify({ signals }),
+                        noExitOnError: true,
+                        signal: AbortSignal.timeout(30_000),
+                    });
+                    const text = await res.text();
+                    const parsed = text ? JSON.parse(text) : {};
+                    if (!res.ok) {
+                        throw new Error((parsed && parsed.message) || `HTTP ${res.status}`);
+                    }
+                    return parsed.intent;
+                }
+                catch (err) {
+                    const e = err;
+                    if (e && (e.name === 'AbortError' || e.name === 'TimeoutError')) {
+                        console.warn('[install] LLM analyze-intent timeout — falling back to heuristic intent');
+                        throw new Error('analyze-intent timeout');
+                    }
+                    throw err;
                 }
-                return parsed.intent;
             },
             preSeed: async (body) => {
                 const res = await (0, api_client_1.cliApi)('/api/cli/install/pre-seed', {