@gurulu/cli 0.4.3 → 0.4.5

package/README.md

@@ -101,3 +101,27 @@ gurulu events list --json
 gurulu status --json
 gurulu doctor --json
 ```
+
+## Telemetry
+
+`gurulu install` records anonymous install telemetry — framework, CLI version,
+install status, and a SHA-256 hash of the absolute repo path — to help us
+improve framework detection and patch reliability. **No source code, file
+contents, or environment variables are ever sent.**
+
+On the first interactive install you'll be asked to opt in. Your choice is
+persisted to `~/.gurulu/config.json` (`telemetry: true|false`) and never
+re-asked.
+
+To opt out:
+
+```bash
+gurulu install --no-telemetry              # one-off
+export GURULU_TELEMETRY=off                # session / shell
+export DO_NOT_TRACK=1                      # honored across most CLI tools
+echo '{"telemetry": false}' > ~/.gurulu/config.json   # permanent
+```
+
+Any of `GURULU_TELEMETRY=off|0|false|no`, `DO_NOT_TRACK=1`, `--no-telemetry`,
+or `telemetry: false` in `~/.gurulu/config.json` disables telemetry — the repo
+hash is never computed and no network request is made.

package/dist/commands/audiences.d.ts

@@ -15,5 +15,9 @@ export interface AudiencesArgs {
     rules?: string;
     yes?: boolean;
     dryRun?: boolean;
+    format?: 'csv' | 'json' | string;
+    output?: string;
+    preview?: boolean;
+    limit?: number;
 }
 export declare function audiencesCommand(args: AudiencesArgs): Promise<void>;

package/dist/commands/audiences.js

@@ -5,6 +5,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.audiencesCommand = audiencesCommand;
+const node_fs_1 = require("node:fs");
 const api_client_1 = require("../api-client");
 const ui_1 = require("../utils/ui");
 const confirm_1 = require("../utils/confirm");
@@ -23,9 +24,11 @@ async function audiencesCommand(args) {
             return updateCmd(args);
         case 'delete':
             return deleteCmd(args);
+        case 'export':
+            return exportCmd(args);
         default:
             (0, ui_1.error)(`Unknown audiences action: ${action}`);
-            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete]');
+            (0, ui_1.info)('Usage: gurulu audiences [list|show|create|update|delete|export]');
             process.exit(1);
     }
 }
@@ -205,3 +208,36 @@ async function deleteCmd(args) {
     });
     (0, ui_1.success)(`Deleted audience ${id}`);
 }
+/**
+ * AU5 (audit-2026-04-29-audience.md) — `gurulu audiences export <name-or-id>`.
+ * Streams the current audience membership as CSV (default) or JSON. With
+ * `--output <path>` we write to disk; otherwise the body goes to stdout.
+ */
+async function exportCmd(args) {
+    const target = args.target;
+    if (!target) {
+        (0, ui_1.error)('Usage: gurulu audiences export <name-or-id> [--format csv|json] [--output file]');
+        process.exit(1);
+    }
+    const id = await resolveId(target, args.profile);
+    const format = (args.format || 'csv').toLowerCase();
+    if (format !== 'csv' && format !== 'json') {
+        (0, ui_1.error)('--format must be csv or json');
+        process.exit(1);
+    }
+    const path = `/api/cli/audiences/${encodeURIComponent(id)}/export?format=${format}&destination=download`;
+    const res = await (0, api_client_1.cliApi)(path, { profile: args.profile });
+    const body = await res.text();
+    if (!res.ok) {
+        (0, ui_1.error)(`Export failed (HTTP ${res.status}): ${body.slice(0, 200)}`);
+        process.exit(1);
+    }
+    if (args.output) {
+        (0, node_fs_1.writeFileSync)(args.output, body, 'utf8');
+        (0, ui_1.success)(`Wrote ${body.length} bytes to ${args.output}`);
+        return;
+    }
+    process.stdout.write(body);
+    if (!body.endsWith('\n'))
+        process.stdout.write('\n');
+}

package/dist/commands/consent.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CLI@0.4.4 — `gurulu consent` — manage per-user consent scopes (GDPR).
+ *
+ * Subcommands:
+ *   gurulu consent set --user-id X --scope marketing_external --state granted|denied
+ *   gurulu consent get --user-id X
+ *   gurulu consent revoke --user-id X
+ *   gurulu consent check --user-id X --destination capi
+ *
+ * TODO(Sprint K): backend endpoints below are not yet live. The CLI command
+ * surface is implemented now so customers can wire automation; once the API
+ * routes ship, the cliApi calls will succeed without any further CLI changes.
+ *   - POST   /api/cli/consent/set       { userId, scope, state }
+ *   - GET    /api/cli/consent/get?userId=...                       (returns scopes[])
+ *   - POST   /api/cli/consent/revoke    { userId }                 (denies all scopes)
+ *   - GET    /api/cli/consent/check?userId=...&destination=...     (returns { allowed: boolean })
+ */
+export interface ConsentArgs {
+    action?: string;
+    userId?: string;
+    scope?: string;
+    state?: string;
+    destination?: string;
+    json?: boolean;
+    profile?: string;
+}
+export declare function consentCommand(args: ConsentArgs): Promise<void>;

package/dist/commands/consent.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * CLI@0.4.4 — `gurulu consent` — manage per-user consent scopes (GDPR).
+ *
+ * Subcommands:
+ *   gurulu consent set --user-id X --scope marketing_external --state granted|denied
+ *   gurulu consent get --user-id X
+ *   gurulu consent revoke --user-id X
+ *   gurulu consent check --user-id X --destination capi
+ *
+ * TODO(Sprint K): backend endpoints below are not yet live. The CLI command
+ * surface is implemented now so customers can wire automation; once the API
+ * routes ship, the cliApi calls will succeed without any further CLI changes.
+ *   - POST   /api/cli/consent/set       { userId, scope, state }
+ *   - GET    /api/cli/consent/get?userId=...                       (returns scopes[])
+ *   - POST   /api/cli/consent/revoke    { userId }                 (denies all scopes)
+ *   - GET    /api/cli/consent/check?userId=...&destination=...     (returns { allowed: boolean })
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consentCommand = consentCommand;
+const config_1 = require("../config");
+const api_client_1 = require("../api-client");
+const ui_1 = require("../utils/ui");
+async function consentCommand(args) {
+    switch (args.action) {
+        case 'set':
+            return consentSet(args);
+        case 'get':
+            return consentGet(args);
+        case 'revoke':
+            return consentRevoke(args);
+        case 'check':
+            return consentCheck(args);
+        default:
+            (0, ui_1.error)(`Unknown action: ${args.action}. Use: set, get, revoke, check`);
+            process.exit(1);
+    }
+}
+async function loadProfileOrExit(args) {
+    try {
+        return await (0, config_1.loadActiveProfile)({ profile: args.profile });
+    }
+    catch {
+        (0, ui_1.error)('Not authenticated. Run "gurulu login" first.');
+        process.exit(1);
+    }
+}
+function emitFallbackNotice(json) {
+    if (json)
+        return;
+    (0, ui_1.info)((0, ui_1.dim)('Note: backend endpoint not yet live (Sprint K candidate). Command-shape is stable.'));
+}
+// ── set ────────────────────────────────────────────────────────────────────
+async function consentSet(args) {
+    if (!args.userId || !args.scope || !args.state) {
+        (0, ui_1.error)('Usage: gurulu consent set --user-id <id> --scope <scope> --state <granted|denied>');
+        process.exit(1);
+    }
+    if (args.state !== 'granted' && args.state !== 'denied') {
+        (0, ui_1.error)('--state must be one of: granted, denied');
+        process.exit(1);
+    }
+    const profile = await loadProfileOrExit(args);
+    try {
+        const res = await (0, api_client_1.cliApi)('/api/cli/consent/set', {
+            method: 'POST',
+            body: JSON.stringify({ userId: args.userId, scope: args.scope, state: args.state }),
+            preloadedProfile: profile,
+        });
+        const data = await res.json().catch(() => ({}));
+        if (res.status === 404) {
+            emitFallbackNotice(args.json);
+            if (args.json) {
+                console.log(JSON.stringify({ ok: false, pending: true, userId: args.userId, scope: args.scope, state: args.state }));
+            }
+            else {
+                (0, ui_1.info)(`Pending: would set consent[${args.scope}] = ${args.state} for ${args.userId}`);
+            }
+            return;
+        }
+        if (!res.ok) {
+            const msg = data.message || data.error || `HTTP ${res.status}`;
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, error: msg }));
+            else
+                (0, ui_1.error)(msg);
+            process.exit(1);
+        }
+        if (args.json)
+            console.log(JSON.stringify(data, null, 2));
+        else
+            (0, ui_1.success)(`Consent[${args.scope}] = ${args.state} for ${args.userId}`);
+    }
+    catch (err) {
+        if (args.json)
+            console.log(JSON.stringify({ ok: false, error: err.message }));
+        else
+            (0, ui_1.error)(`Failed: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── get ────────────────────────────────────────────────────────────────────
+async function consentGet(args) {
+    if (!args.userId) {
+        (0, ui_1.error)('Usage: gurulu consent get --user-id <id>');
+        process.exit(1);
+    }
+    const profile = await loadProfileOrExit(args);
+    try {
+        const res = await (0, api_client_1.cliApi)(`/api/cli/consent/get?userId=${encodeURIComponent(args.userId)}`, { preloadedProfile: profile });
+        const data = await res.json().catch(() => ({}));
+        if (res.status === 404) {
+            emitFallbackNotice(args.json);
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, pending: true, userId: args.userId, scopes: [] }));
+            else
+                (0, ui_1.info)(`Pending: would fetch consent scopes for ${args.userId}`);
+            return;
+        }
+        if (!res.ok) {
+            const msg = data.message || data.error || `HTTP ${res.status}`;
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, error: msg }));
+            else
+                (0, ui_1.error)(msg);
+            process.exit(1);
+        }
+        if (args.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        const scopes = data.scopes || [];
+        if (scopes.length === 0) {
+            (0, ui_1.info)(`No consent records for ${args.userId}`);
+            return;
+        }
+        console.log((0, ui_1.bold)(`Consent scopes for ${args.userId}:`));
+        for (const s of scopes) {
+            const ts = s.updatedAt ? (0, ui_1.dim)(`  (${s.updatedAt})`) : '';
+            (0, ui_1.step)(`${s.scope}: ${s.state}${ts}`);
+        }
+    }
+    catch (err) {
+        if (args.json)
+            console.log(JSON.stringify({ ok: false, error: err.message }));
+        else
+            (0, ui_1.error)(`Failed: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── revoke ─────────────────────────────────────────────────────────────────
+async function consentRevoke(args) {
+    if (!args.userId) {
+        (0, ui_1.error)('Usage: gurulu consent revoke --user-id <id>');
+        process.exit(1);
+    }
+    const profile = await loadProfileOrExit(args);
+    try {
+        const res = await (0, api_client_1.cliApi)('/api/cli/consent/revoke', {
+            method: 'POST',
+            body: JSON.stringify({ userId: args.userId }),
+            preloadedProfile: profile,
+        });
+        const data = await res.json().catch(() => ({}));
+        if (res.status === 404) {
+            emitFallbackNotice(args.json);
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, pending: true, userId: args.userId }));
+            else
+                (0, ui_1.info)(`Pending: would deny all consent scopes for ${args.userId}`);
+            return;
+        }
+        if (!res.ok) {
+            const msg = data.message || data.error || `HTTP ${res.status}`;
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, error: msg }));
+            else
+                (0, ui_1.error)(msg);
+            process.exit(1);
+        }
+        if (args.json)
+            console.log(JSON.stringify(data, null, 2));
+        else
+            (0, ui_1.success)(`All consent scopes revoked for ${args.userId}`);
+    }
+    catch (err) {
+        if (args.json)
+            console.log(JSON.stringify({ ok: false, error: err.message }));
+        else
+            (0, ui_1.error)(`Failed: ${err.message}`);
+        process.exit(1);
+    }
+}
+// ── check ─────────────────────────────────────────────────────────────────
+async function consentCheck(args) {
+    if (!args.userId || !args.destination) {
+        (0, ui_1.error)('Usage: gurulu consent check --user-id <id> --destination <capi|ga4|...>');
+        process.exit(1);
+    }
+    const profile = await loadProfileOrExit(args);
+    try {
+        const data = await (0, api_client_1.cliApiJson)(`/api/cli/consent/check?userId=${encodeURIComponent(args.userId)}&destination=${encodeURIComponent(args.destination)}`, { preloadedProfile: profile });
+        if (args.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (data.allowed) {
+            (0, ui_1.success)(`Dispatch ALLOWED to ${args.destination} for ${args.userId}`);
+        }
+        else {
+            (0, ui_1.info)(`Dispatch DENIED to ${args.destination} for ${args.userId}${data.reason ? ` (${data.reason})` : ''}`);
+        }
+        // Exit code mirrors the boolean for shell scripting.
+        process.exit(data.allowed ? 0 : 2);
+    }
+    catch (err) {
+        const msg = err.message || '';
+        // 404 from the API client means the endpoint isn't live yet.
+        if (/HTTP 404|Not Found/i.test(msg)) {
+            emitFallbackNotice(args.json);
+            if (args.json)
+                console.log(JSON.stringify({ ok: false, pending: true, allowed: null, userId: args.userId, destination: args.destination }));
+            else
+                (0, ui_1.info)(`Pending: would check consent for ${args.userId} → ${args.destination}`);
+            return;
+        }
+        if (args.json)
+            console.log(JSON.stringify({ ok: false, error: msg }));
+        else
+            (0, ui_1.error)(`Failed: ${msg}`);
+        process.exit(1);
+    }
+}

package/dist/commands/db.js

@@ -13,6 +13,7 @@ exports.dbCommand = dbCommand;
 const config_1 = require("../config");
 const api_client_1 = require("../api-client");
 const ui_1 = require("../utils/ui");
+const redact_1 = require("../utils/redact");
 async function dbCommand(args) {
     switch (args.action) {
         case 'connect':
@@ -79,6 +80,13 @@ async function dbConnect(args) {
     }
     const effectivePort = port || (dbType === 'mysql' ? 3306 : 5432);
     (0, ui_1.info)('Testing connection...');
+    // CLI@0.4.4 P0 security — never echo password to stdout/telemetry.
+    // The verbose/debug path used to dump the raw args object; route it through
+    // the redaction helper so password/token/secret keys are masked.
+    if (process.env.GURULU_DEBUG === '1') {
+        const safeArgs = (0, redact_1.redactSensitiveArgs)({ ...args });
+        console.log(`[debug] db connect args: ${(0, redact_1.safeStringifyArgs)(safeArgs)}`);
+    }
     try {
         // First call: test + potentially list tables
         const body = {

package/dist/commands/events.js

@@ -184,7 +184,13 @@ async function defineCmd(args) {
             process.exit(1);
         }
     }
-    const eventName = args.eventName.startsWith('$') ? args.eventName : `$${args.eventName}`;
+    // Use the user-provided name verbatim. The CLI used to force a `$` prefix
+    // because Gurulu's built-ins use one (`$page_view`, `$session_start`), but
+    // built-ins are inconsistent (`click`, `engaged_session` have none) and
+    // mutating the customer's chosen name silently broke schema lookups + made
+    // the generated SDK snippets reference a name that no longer matched the
+    // ingest payload.
+    const eventName = args.eventName;
     const body = {
         siteId: args.site,
         eventName,
@@ -207,10 +213,14 @@ async function verifyCmd(args) {
         (0, ui_1.error)('--site is required.');
         process.exit(1);
     }
+    // Accept both `--event` (verify-original) and `--event-name` (used by
+    // every other events subcommand). Removes the surprising flag-name
+    // inconsistency without breaking existing scripts.
+    const filterEvent = args.event || args.eventName;
     const qs = new URLSearchParams();
     qs.set('siteId', args.site);
-    if (args.event)
-        qs.set('eventName', args.event);
+    if (filterEvent)
+        qs.set('eventName', filterEvent);
     const path = `/api/cli/events/health?${qs.toString()}`;
     const data = await (0, api_client_1.cliApiJson)(path, { profile: args.profile });
     if (args.json) {
@@ -220,7 +230,7 @@ async function verifyCmd(args) {
     console.log((0, ui_1.bold)('\nEvent Health Report'));
     console.log(`Site: ${args.site}`);
     console.log('');
-    if (Array.isArray(data.events)) {
+    if (Array.isArray(data.events) && data.events.length > 0) {
         for (const ev of data.events) {
             const statusIcon = ev.status === 'active'
                 ? (0, ui_1.green)('●')
@@ -237,6 +247,17 @@ async function verifyCmd(args) {
         console.log(`Total events (24h): ${data.total_events}`);
         console.log(`Unique event types: ${data.unique_types ?? 'N/A'}`);
     }
+    else {
+        // Empty: no telemetry yet for the requested filter / definition. Without
+        // this branch the report printed only its header — users couldn't tell
+        // success from "no data found".
+        if (filterEvent) {
+            (0, ui_1.info)(`No telemetry yet for "${filterEvent}". Track it from your app and run verify again.`);
+        }
+        else {
+            (0, ui_1.info)('No telemetry data found for this site in the last 24h.');
+        }
+    }
     console.log('');
 }
 /* ── templates: list vertical event template catalogs ───────────── */

package/dist/commands/heatmap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+export interface HeatmapArgs {
+    action?: string;
+    site?: string;
+    page?: string;
+    pageId?: string;
+    type?: string;
+    range?: string;
+    viewport?: string;
+    json?: boolean;
+    profile?: string;
+}
+export declare function heatmapCommand(args: HeatmapArgs): Promise<void>;

package/dist/commands/heatmap.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Sprint J-Heat HM10 — `gurulu heatmap ...` subcommands.
+ *
+ * Read-only surface backed by `/api/cli/heatmap/list` and
+ * `/api/cli/heatmap/get`. Lets agents and operators inspect heatmap
+ * snapshots without opening the dashboard.
+ *
+ *   gurulu heatmap list   --site <id|name>           [--range 7d|30d] [--json]
+ *   gurulu heatmap export --site <id|name> --page <pageUrl>
+ *                                                    [--type click|scroll]
+ *                                                    [--range 7d|30d]
+ *                                                    [--viewport mobile|tablet|desktop]
+ *                                                    [--page-id <hash>]
+ *                                                    [--json]
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.heatmapCommand = heatmapCommand;
+const api_client_1 = require("../api-client");
+const ui_1 = require("../utils/ui");
+async function resolveSiteId(target, profile) {
+    if (!target)
+        throw new Error('--site is required');
+    const body = await (0, api_client_1.cliApiJson)('/api/cli/sites', { profile });
+    const sites = body.sites || [];
+    const byId = sites.find((s) => s.id === target);
+    if (byId)
+        return byId.id;
+    const byName = sites.find((s) => s.name === target);
+    if (byName)
+        return byName.id;
+    const byDomain = sites.find((s) => s.domain === target);
+    if (byDomain)
+        return byDomain.id;
+    const prefix = sites.find((s) => s.id.startsWith(target));
+    if (prefix)
+        return prefix.id;
+    throw new Error(`Site '${target}' not found.`);
+}
+async function heatmapCommand(args) {
+    const action = args.action || 'list';
+    switch (action) {
+        case 'list':
+            return listCmd(args);
+        case 'export':
+            return exportCmd(args);
+        default:
+            (0, ui_1.error)(`Unknown heatmap action: ${action}`);
+            (0, ui_1.info)('Usage: gurulu heatmap [list|export]');
+            process.exit(1);
+    }
+}
+async function listCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/list?siteId=${encodeURIComponent(siteId)}&range=${range}`, {
+        profile: args.profile,
+    });
+    if (args.json) {
+        process.stdout.write(JSON.stringify(body, null, 2) + '\n');
+        return;
+    }
+    const pages = body.pages || [];
+    if (pages.length === 0) {
+        (0, ui_1.info)(`No heatmap data for site '${body.siteName}' (range=${range}).`);
+        return;
+    }
+    process.stdout.write(['CLICKS', 'VISITORS', 'M/T/D', 'LAST SEEN', 'PAGE URL'].join('\t') + '\n');
+    for (const p of pages) {
+        const mtd = `${p.viewportBuckets.mobile}/${p.viewportBuckets.tablet}/${p.viewportBuckets.desktop}`;
+        process.stdout.write([
+            String(p.clickCount),
+            String(p.visitors),
+            mtd,
+            String(p.lastSeen).slice(0, 19),
+            p.pageUrl,
+        ].join('\t') + '\n');
+    }
+}
+async function exportCmd(args) {
+    if (!args.site) {
+        (0, ui_1.error)('--site is required.');
+        process.exit(1);
+    }
+    if (!args.page) {
+        (0, ui_1.error)('--page <pageUrl> is required.');
+        process.exit(1);
+    }
+    const siteId = await resolveSiteId(args.site, args.profile);
+    const range = args.range === '30d' ? '30d' : '7d';
+    const type = args.type === 'scroll' ? 'scroll' : 'click';
+    const qp = new URLSearchParams({
+        siteId,
+        pageUrl: args.page,
+        range,
+        type,
+    });
+    if (args.pageId)
+        qp.set('pageId', args.pageId);
+    if (args.viewport)
+        qp.set('viewportBucket', args.viewport);
+    const body = await (0, api_client_1.cliApiJson)(`/api/cli/heatmap/get?${qp.toString()}`, {
+        profile: args.profile,
+    });
+    // Export commands always emit machine-readable output by default; the
+    // `--json` flag is accepted for symmetry with the rest of the CLI.
+    process.stdout.write(JSON.stringify(body, null, args.json ? 2 : 0) + '\n');
+}

package/dist/commands/identity.d.ts

@@ -22,5 +22,8 @@ export interface IdentityArgs {
     yes?: boolean;
     json?: boolean;
     profile?: string;
+    file?: string;
+    format?: string;
+    resumeFrom?: number;
 }
 export declare function identityCommand(args: IdentityArgs): Promise<void>;