@gurulu/cli 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @gurulu/cli
+
+CLI wizard for setting up Gurulu.io analytics in any project.
+
+## Quick Start
+
+```bash
+npx @gurulu/cli init
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gurulu init` | Set up Gurulu analytics (auto-detects framework) |
+| `gurulu login` | Authenticate with your Personal API Key |
+| `gurulu events` | List detected events from your site |
+| `gurulu status` | Quick health check |
+| `gurulu doctor` | Comprehensive diagnostics |
+| `gurulu add-server` | Add server-side SDK (@gurulu/node) |
+
+## Supported Frameworks
+
+- Next.js (App Router & Pages Router)
+- React (Vite & CRA)
+- Vue 3
+- Nuxt 3
+- Svelte & SvelteKit
+- Astro
+- Express
+- NestJS
+- Plain HTML
+
+## Authentication
+
+```bash
+gurulu login --api-key pak_live_xxxxx
+```
+
+Or set the `GURULU_API_KEY` environment variable.
+
+## Non-Interactive Mode
+
+All commands support `--no-interactive` for CI/CD:
+
+```bash
+gurulu init --site-id abc123 --token tok_xxx --no-interactive
+```
+
+## JSON Output
+
+Use `--json` flag for machine-readable output:
+
+```bash
+gurulu events --json
+gurulu status --json
+gurulu doctor --json
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+node bin/gurulu.js --help
+```

package/bin/gurulu.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/api-client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Phase 18.5 W2 — Thin fetch wrapper used by all authenticated CLI
+ * commands. Handles auth header injection, user-agent, and the common
+ * 401/402/429/5xx error presentations.
+ */
+import { type ActiveProfile } from './config';
+export declare function userAgent(): string;
+export interface CliApiOptions extends RequestInit {
+    profile?: string;
+    skipAuth?: boolean;
+    /** Used internally by tests — inject a pre-resolved profile. */
+    preloadedProfile?: ActiveProfile;
+    /** Disable process.exit for tests. */
+    noExitOnError?: boolean;
+}
+export declare class CliApiError extends Error {
+    status: number;
+    code: string;
+    details: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+export declare function cliApi(path: string, init?: CliApiOptions): Promise<Response>;
+/** Helper: POST JSON and return parsed body, with rich error reporting. */
+export declare function cliApiJson<T = unknown>(path: string, init?: CliApiOptions & {
+    method?: string;
+    json?: unknown;
+}): Promise<T>;

package/dist/api-client.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Phase 18.5 W2 — Thin fetch wrapper used by all authenticated CLI
+ * commands. Handles auth header injection, user-agent, and the common
+ * 401/402/429/5xx error presentations.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliApiError = void 0;
+exports.userAgent = userAgent;
+exports.cliApi = cliApi;
+exports.cliApiJson = cliApiJson;
+const os = __importStar(require("os"));
+const config_1 = require("./config");
+let cachedVersion = null;
+function cliVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pkg = require('../package.json');
+        cachedVersion = pkg.version || '0.0.0';
+    }
+    catch {
+        cachedVersion = '0.0.0';
+    }
+    return cachedVersion;
+}
+function userAgent() {
+    return `gurulu-cli/${cliVersion()} (node/${process.versions.node}; ${os.platform()})`;
+}
+class CliApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.CliApiError = CliApiError;
+function fatal(msg, opts) {
+    process.stderr.write(`${msg}\n`);
+    if (!opts.noExitOnError)
+        process.exit(1);
+    throw new CliApiError(0, 'fatal', msg);
+}
+async function cliApi(path, init = {}) {
+    let profile = init.preloadedProfile || null;
+    if (!profile && !init.skipAuth) {
+        try {
+            profile = await (0, config_1.loadActiveProfile)({ profile: init.profile });
+        }
+        catch (err) {
+            fatal(`Not logged in. Run \`gurulu login\` first. (${err.message})`, init);
+        }
+    }
+    const base = profile?.api_base || process.env.GURULU_API_BASE || 'https://gurulu.io';
+    const url = path.startsWith('http') ? path : `${base}${path}`;
+    const headers = new Headers(init.headers || {});
+    if (!headers.has('user-agent'))
+        headers.set('user-agent', userAgent());
+    if (!init.skipAuth && profile) {
+        headers.set('authorization', `Bearer ${profile.secret_key}`);
+    }
+    if (init.body && !headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    let res;
+    try {
+        res = await globalThis.fetch(url, { ...init, headers });
+    }
+    catch (err) {
+        fatal(`Gurulu is temporarily unavailable (network error): ${err.message}`, init);
+    }
+    if (res.status === 401) {
+        fatal('Your session is invalid. Run `gurulu login` again.', init);
+    }
+    if (res.status === 402) {
+        let msg = 'Quota exceeded. Upgrade at https://gurulu.io/settings/billing';
+        try {
+            const body = await res.clone().json();
+            if (body?.message)
+                msg = `Quota exceeded: ${body.message}`;
+            if (body?.upgradeUrl)
+                msg += `\n  → ${body.upgradeUrl}`;
+        }
+        catch {
+            /* ignore */
+        }
+        fatal(msg, init);
+    }
+    if (res.status === 429) {
+        const retry = res.headers.get('retry-after') || '';
+        fatal(`Rate limited by Gurulu${retry ? ` — try again in ${retry}s` : ''}. Try again shortly.`, init);
+    }
+    if (res.status >= 500) {
+        fatal(`Gurulu is temporarily unavailable (HTTP ${res.status}).`, init);
+    }
+    return res;
+}
+/** Helper: POST JSON and return parsed body, with rich error reporting. */
+async function cliApiJson(path, init = {}) {
+    const { json, ...rest } = init;
+    const res = await cliApi(path, {
+        ...rest,
+        method: init.method || (json ? 'POST' : 'GET'),
+        body: json !== undefined ? JSON.stringify(json) : rest.body,
+    });
+    const text = await res.text();
+    const parsed = text ? JSON.parse(text) : {};
+    if (!res.ok) {
+        throw new CliApiError(res.status, parsed?.error || 'http_error', parsed?.message || `HTTP ${res.status}`, parsed);
+    }
+    return parsed;
+}

package/dist/commands/add-server.d.ts

@@ -0,0 +1,9 @@
+interface AddServerArgs {
+    site?: string;
+    noInteractive?: boolean;
+    dryRun?: boolean;
+    json?: boolean;
+    profile?: string;
+}
+export declare function addServerCommand(args: AddServerArgs): Promise<void>;
+export {};

package/dist/commands/add-server.js

@@ -0,0 +1,155 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addServerCommand = addServerCommand;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const config_1 = require("../config");
+const api_client_1 = require("../api-client");
+const ui_1 = require("../utils/ui");
+async function addServerCommand(args) {
+    let profile;
+    try {
+        profile = await (0, config_1.loadActiveProfile)({ profile: args.profile });
+    }
+    catch {
+        profile = null;
+    }
+    const siteId = args.site;
+    const projectDir = process.cwd();
+    if (args.json) {
+        return addServerJSON(siteId, profile, projectDir, args);
+    }
+    (0, ui_1.banner)();
+    console.log((0, ui_1.bold)('  Add Server SDK'));
+    console.log('');
+    // Check for package.json
+    const pkgPath = path_1.default.join(projectDir, 'package.json');
+    if (!fs_1.default.existsSync(pkgPath)) {
+        (0, ui_1.error)('No package.json found in current directory.');
+        process.exit(1);
+    }
+    // Check if already installed
+    const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf-8'));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (allDeps['@gurulu/node']) {
+        (0, ui_1.info)('@gurulu/node is already installed.');
+    }
+    if (!siteId) {
+        (0, ui_1.error)('No site selected. Run "gurulu login" first or use --site <id>.');
+        process.exit(1);
+    }
+    // Get server API key
+    let serverApiKey = process.env.GURULU_SERVER_API_KEY;
+    if (!serverApiKey && profile) {
+        try {
+            const data = await (0, api_client_1.cliApiJson)(`/api/cli/sites/${encodeURIComponent(siteId)}`, { preloadedProfile: profile });
+            serverApiKey = data.site?.publishableKey || '';
+        }
+        catch (err) {
+            (0, ui_1.warn)(`Could not fetch server credentials: ${err.message}`);
+        }
+    }
+    if (!serverApiKey && !args.noInteractive) {
+        serverApiKey = await (0, ui_1.prompt)('  Server API Key: ');
+    }
+    if (!serverApiKey) {
+        (0, ui_1.error)('Server API key required. Set GURULU_SERVER_API_KEY or run "gurulu login" first.');
+        process.exit(1);
+    }
+    if (args.dryRun) {
+        (0, ui_1.info)('Dry run - would perform the following:');
+        (0, ui_1.step)('Install @gurulu/node package');
+        (0, ui_1.step)('Create server SDK config file');
+        (0, ui_1.step)('Add GURULU_SERVER_API_KEY to .env');
+        return;
+    }
+    // Step 1: Install package
+    (0, ui_1.step)('Installing @gurulu/node...');
+    try {
+        // Detect package manager
+        let pm = 'npm install';
+        if (fs_1.default.existsSync(path_1.default.join(projectDir, 'pnpm-lock.yaml'))) {
+            pm = 'pnpm add';
+        }
+        else if (fs_1.default.existsSync(path_1.default.join(projectDir, 'yarn.lock'))) {
+            pm = 'yarn add';
+        }
+        else if (fs_1.default.existsSync(path_1.default.join(projectDir, 'bun.lockb'))) {
+            pm = 'bun add';
+        }
+        (0, child_process_1.execSync)(`${pm} @gurulu/node`, { cwd: projectDir, stdio: 'pipe' });
+        (0, ui_1.success)('Installed @gurulu/node');
+    }
+    catch (err) {
+        (0, ui_1.warn)(`Could not auto-install. Run manually: npm install @gurulu/node`);
+    }
+    // Step 2: Create server config file
+    const configFilePath = path_1.default.join(projectDir, 'src', 'lib', 'gurulu-server.ts');
+    const configCode = `import { GuruluNode } from '@gurulu/node';
+
+export const gurulu = new GuruluNode({
+  siteId: process.env.GURULU_SITE_ID || '${siteId}',
+  apiKey: process.env.GURULU_SERVER_API_KEY || '',
+});
+`;
+    if (!fs_1.default.existsSync(configFilePath)) {
+        const configDir = path_1.default.dirname(configFilePath);
+        fs_1.default.mkdirSync(configDir, { recursive: true });
+        fs_1.default.writeFileSync(configFilePath, configCode);
+        (0, ui_1.success)('Created src/lib/gurulu-server.ts');
+    }
+    else {
+        (0, ui_1.info)('src/lib/gurulu-server.ts already exists, skipping.');
+    }
+    // Step 3: Update .env
+    const envFile = path_1.default.join(projectDir, '.env');
+    const envLines = [
+        `GURULU_SITE_ID=${siteId}`,
+        `GURULU_SERVER_API_KEY=${serverApiKey}`,
+    ];
+    let existingEnv = '';
+    if (fs_1.default.existsSync(envFile)) {
+        existingEnv = fs_1.default.readFileSync(envFile, 'utf-8');
+    }
+    const newLines = envLines.filter(line => {
+        const key = line.split('=')[0];
+        return !existingEnv.includes(key);
+    });
+    if (newLines.length > 0) {
+        const separator = existingEnv && !existingEnv.endsWith('\n') ? '\n' : '';
+        const header = existingEnv.includes('GURULU') ? '' : '# Gurulu.io Server SDK\n';
+        fs_1.default.appendFileSync(envFile, `${separator}${header}${newLines.join('\n')}\n`);
+        (0, ui_1.success)('Updated .env with server credentials');
+    }
+    else {
+        (0, ui_1.info)('.env already has Gurulu server credentials');
+    }
+    // Done
+    console.log('');
+    console.log((0, ui_1.bold)('  Next steps:'));
+    console.log('');
+    (0, ui_1.step)('Import gurulu from src/lib/gurulu-server.ts in your API routes');
+    (0, ui_1.step)(`Use ${(0, ui_1.cyan)('gurulu.track(event, properties)')} to send server-side events`);
+    (0, ui_1.step)(`Use ${(0, ui_1.cyan)('gurulu.identify(userId, traits)')} to identify users`);
+    (0, ui_1.step)(`Run ${(0, ui_1.cyan)('gurulu doctor')} to verify the setup`);
+    console.log('');
+    (0, ui_1.success)('Server SDK setup complete!');
+    console.log('');
+}
+async function addServerJSON(siteId, profile, projectDir, args) {
+    const result = {
+        siteId: siteId || null,
+        authenticated: !!profile,
+        dryRun: !!args.dryRun,
+        steps: [
+            { action: 'install', package: '@gurulu/node' },
+            { action: 'create', file: 'src/lib/gurulu-server.ts' },
+            { action: 'update', file: '.env', keys: ['GURULU_SITE_ID', 'GURULU_SERVER_API_KEY'] },
+        ],
+    };
+    console.log(JSON.stringify(result, null, 2));
+}

package/dist/commands/alerts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Phase 19.5 W2 B4 — `gurulu alerts list|show|channels list`.
+ * Phase 20  W2 B3 — `create|update|delete` + channels create/update/delete.
+ */
+export interface AlertsArgs {
+    action?: string;
+    sub?: string;
+    target?: string;
+    severity?: string;
+    acknowledged?: string;
+    limit?: number;
+    json?: boolean;
+    profile?: string;
+    fromFile?: string;
+    name?: string;
+    type?: string;
+    metric?: string;
+    note?: string;
+    yes?: boolean;
+    dryRun?: boolean;
+}
+export declare function alertsCommand(args: AlertsArgs): Promise<void>;