@prave/cli 1.2.1 → 1.2.2

package/README.md

@@ -172,7 +172,7 @@ API health and uptime: [status.prave.app](https://status.prave.app) — auto-ref
 - 📖 [**CLI Cheat Sheet**](https://prave.app/docs/cli/cheat-sheet) — every command on one page
 - 💚 [**status.prave.app**](https://status.prave.app) — real-time health
 - 🐛 [**GitHub Issues**](https://github.com/eppstudio/prave/issues) — bug reports & feature requests
-- ✉️ [info@epplab-studio.de](mailto:info@epplab-studio.de) — direct contact
+- ✉️ [hello@epplab-studio.de](mailto:hello@epplab-studio.de) — direct contact
 
 ## License
 

package/dist/commands/login.js

@@ -39,6 +39,17 @@ export async function loginCommand() {
                 expires_at: data.expires_at ?? undefined,
             });
             spinner.succeed('Logged in.');
+            // Replay any Skill-invocation events the hook buffered while the
+            // user was offline / signed out. Silent when nothing's queued;
+            // prints "Syncing N events…" + a confirmation when the file has
+            // real backlog. Failures swallowed inside.
+            try {
+                const { flushBufferedTelemetry } = await import('../lib/flush-telemetry.js');
+                await flushBufferedTelemetry();
+            }
+            catch (flushErr) {
+                log.dim(`Telemetry sync skipped: ${flushErr.message}`);
+            }
             // Onboarding: prefill from the SaaS profile, let the user toggle
             // with space/enter, persist back, and offer to install hooks.
             // Failures here are non-fatal — login succeeded.

package/dist/commands/usage.js

@@ -7,6 +7,7 @@ import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { requireAuth } from '../lib/credentials.js';
 import { HOOK_SUPPORTED, installHooksForAgents, uninstallHooksForAgents, } from '../lib/hook.js';
+import { bufferEvent } from '../lib/telemetry-buffer.js';
 import { AGENT_REGISTRY } from '@prave/shared';
 import { loadCursor, saveCursor } from '../lib/usage-cursor.js';
 import { scanTranscriptsForUsage } from '../lib/usage-scanner.js';
@@ -159,12 +160,6 @@ export async function usageReportCommand(opts = {}) {
     }
     if (debug)
         await debugLog(`slug=${slug}`);
-    const session = await requireAuthSilent();
-    if (!session) {
-        if (debug)
-            await debugLog('no auth — skipping');
-        return;
-    }
     // Build the telemetry blob from whatever Claude Code shipped in the
     // payload. Everything is best-effort — missing fields just don't
     // appear in `meta`. The server schema (usageMetaSchema) validates
@@ -192,11 +187,30 @@ export async function usageReportCommand(opts = {}) {
         if (typeof obj.prompt === 'string')
             meta.prompt_chars = obj.prompt.length;
     }
+    const triggered_at = new Date().toISOString();
+    const session = await requireAuthSilent();
+    // No credentials? Don't drop the event — buffer it to disk. The next
+    // `prave login` (or any authenticated command that calls
+    // `flushBufferedTelemetry`) replays the file against the same
+    // by-slug endpoint, so no Skill invocation is ever lost just because
+    // the user happened to be signed out at hook-fire time.
+    if (!session) {
+        await bufferEvent({
+            slug,
+            agent_type: 'claude',
+            triggered_at,
+            meta: { ...meta, source },
+        });
+        await hookLog(`${source}:buffered slug=${slug}`);
+        if (debug)
+            await debugLog(`no auth — buffered to telemetry-queue`);
+        return;
+    }
     try {
         const { data } = await api.post('/api/v1/intelligence/usage/by-slug', {
             slug,
             agent_type: 'claude',
-            triggered_at: new Date().toISOString(),
+            triggered_at,
             meta: { ...meta, source },
         }, true);
         await hookLog(`${source}:ok slug=${slug} recorded=${data.recorded} stub=${data.created_stub}`);
@@ -205,11 +219,18 @@ export async function usageReportCommand(opts = {}) {
         }
     }
     catch (err) {
+        // Network down or API error while authenticated — also buffer so
+        // the event isn't lost. The next successful command will replay.
+        await bufferEvent({
+            slug,
+            agent_type: 'claude',
+            triggered_at,
+            meta: { ...meta, source },
+        });
         const msg = err.message;
-        await hookLog(`${source}:err slug=${slug} ${msg.slice(0, 120)}`);
+        await hookLog(`${source}:buffered-on-err slug=${slug} ${msg.slice(0, 80)}`);
         if (debug)
-            await debugLog(`error: ${msg}`);
-        /* silent — never break the host shell */
+            await debugLog(`api error, buffered: ${msg}`);
     }
 }
 /**

package/dist/lib/flush-telemetry.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { api } from './api.js';
+import { log } from '../utils/logger.js';
+import { flushBuffered, pendingTelemetryCount, } from './telemetry-buffer.js';
+/**
+ * Replay any offline-buffered Skill-invocation events. Called by
+ * `prave login` (right after credentials land on disk) and also by
+ * the API client on every successful authenticated request, so the
+ * queue drains opportunistically even without a fresh login.
+ *
+ * Behavior:
+ *   - silent when the queue is empty (most invocations)
+ *   - prints "Syncing N telemetry events…" + a success or partial
+ *     line when there's a non-zero count
+ *   - never throws — telemetry failures must not break the CLI
+ *
+ * `force` skips the early "empty?" check, useful right after login
+ * where we know we just succeeded and want the user to see whatever
+ * sync number lands (even if zero — feels reassuring).
+ */
+export async function flushBufferedTelemetry(opts = {}) {
+    try {
+        const pending = await pendingTelemetryCount();
+        if (pending === 0 && !opts.force)
+            return;
+        if (pending === 0)
+            return; // even with force, no spinner for 0
+        log.info(`${chalk.cyan('●')} You have telemetry updates from offline sessions. Syncing ${chalk.bold(pending)} event${pending === 1 ? '' : 's'} to your dashboard…`);
+        const result = await flushBuffered(async (body) => {
+            await api.post('/api/v1/intelligence/usage/by-slug', body, true);
+        });
+        if (result.failed === 0) {
+            log.success(`Synced ${chalk.bold(result.sent)} telemetry event${result.sent === 1 ? '' : 's'}. Dashboard is up to date.`);
+        }
+        else {
+            log.warn(`Synced ${result.sent} of ${result.total} — ${result.failed} will retry on the next run.`);
+        }
+    }
+    catch {
+        /* swallow — telemetry sync is best-effort */
+    }
+}

package/dist/lib/telemetry-buffer.js

@@ -0,0 +1,131 @@
+import { appendFile, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG } from './config.js';
+/**
+ * Offline telemetry buffer.
+ *
+ * When the PostToolUse hook fires while the user is logged out (no
+ * credentials in ~/.prave/credentials.json), the Skill invocation would
+ * otherwise be lost — the hook can't reach the API. Instead we append
+ * the event as one JSON line to `~/.prave/telemetry-queue.jsonl` and
+ * replay the whole file the next time the user logs in (or runs any
+ * command that hits the API while authenticated).
+ *
+ * Each line is the exact payload the live hook would have POSTed to
+ * `/api/v1/intelligence/usage/by-slug`, so replay is "send each line
+ * through the same endpoint". Server-side dedup (per-minute bucket
+ * keyed by `skill_metadata_id + agent_type`) makes the flush idempotent
+ * — a flush that crashes mid-way can re-run with no double-counting.
+ *
+ * The queue file is hard-capped at 5000 events (~600 KB of JSONL).
+ * Beyond that we drop the oldest line per fire — telemetry is best-
+ * effort, never something that should grow unbounded on disk.
+ */
+export const TELEMETRY_QUEUE_FILE = join(CONFIG.praveDir, 'telemetry-queue.jsonl');
+const MAX_QUEUE_LINES = 5_000;
+const QUEUE_ROTATE_AT_BYTES = 1_000_000; // 1 MB safety stop
+/**
+ * Append one event to the queue. Best-effort: any FS failure is
+ * swallowed because the hook MUST NOT throw — failing telemetry can
+ * never break the user's editor.
+ */
+export async function bufferEvent(event) {
+    try {
+        await mkdir(CONFIG.praveDir, { recursive: true });
+        // Rotate before append if the file got too big. We keep the
+        // newest half — recent telemetry is more valuable than ancient
+        // backlog the user probably doesn't care about anymore.
+        const info = await stat(TELEMETRY_QUEUE_FILE).catch(() => null);
+        if (info && info.size > QUEUE_ROTATE_AT_BYTES) {
+            const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => '');
+            const lines = raw.split('\n').filter(Boolean);
+            if (lines.length > MAX_QUEUE_LINES) {
+                const trimmed = lines.slice(-Math.floor(MAX_QUEUE_LINES / 2));
+                await writeFile(TELEMETRY_QUEUE_FILE, trimmed.join('\n') + '\n', 'utf8');
+            }
+        }
+        await appendFile(TELEMETRY_QUEUE_FILE, JSON.stringify(event) + '\n', 'utf8');
+    }
+    catch {
+        /* swallow — telemetry is best-effort */
+    }
+}
+/**
+ * Read the queue. Returns parsed events plus the raw line count so
+ * callers can report "N events synced". Skips malformed lines silently
+ * — a single corrupt write must not kill an entire replay.
+ */
+async function readQueue() {
+    const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => null);
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const parsed = JSON.parse(t);
+            if (parsed.slug && parsed.triggered_at)
+                out.push(parsed);
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out;
+}
+/**
+ * Replay the queue against the by-slug endpoint and delete the file on
+ * full success. Caller passes the already-authenticated POST helper so
+ * we don't introduce a circular dep on api.ts.
+ *
+ * On partial failure (network blip mid-flush), the remaining events
+ * are rewritten so a later attempt picks up where we left off. Order
+ * is preserved across rewrites.
+ */
+export async function flushBuffered(postBySlug) {
+    const events = await readQueue();
+    if (!events.length)
+        return { sent: 0, failed: 0, total: 0 };
+    let sent = 0;
+    const remaining = [];
+    for (let i = 0; i < events.length; i++) {
+        const ev = events[i];
+        if (!ev)
+            continue;
+        try {
+            await postBySlug({ ...ev, source: 'buffered' });
+            sent += 1;
+        }
+        catch {
+            // Keep this one and every event after it for the next attempt.
+            // We don't push-and-continue because a network blip likely means
+            // every subsequent POST will fail too — better to stop fast.
+            remaining.push(...events.slice(i));
+            break;
+        }
+    }
+    if (remaining.length === 0) {
+        await unlink(TELEMETRY_QUEUE_FILE).catch(() => { });
+    }
+    else {
+        await writeFile(TELEMETRY_QUEUE_FILE, remaining.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8').catch(() => { });
+    }
+    return { sent, failed: remaining.length, total: events.length };
+}
+/**
+ * Cheap "is there anything to flush?" check — used by login/whoami to
+ * decide whether to print the "syncing pending telemetry" line at all.
+ * Returns 0 when the file doesn't exist OR is empty.
+ */
+export async function pendingTelemetryCount() {
+    const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => null);
+    if (!raw)
+        return 0;
+    let n = 0;
+    for (const line of raw.split('\n'))
+        if (line.trim())
+            n += 1;
+    return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -26,14 +26,14 @@
   "homepage": "https://prave.app",
   "bugs": {
     "url": "https://github.com/eppstudio/prave/issues",
-    "email": "info@epplab-studio.de"
+    "email": "hello@epplab-studio.de"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/eppstudio/prave.git",
     "directory": "apps/cli"
   },
-  "author": "EppLab Studio <info@epplab-studio.de> (https://epplab-studio.de)",
+  "author": "EppLab Studio <hello@epplab-studio.de> (https://epplab-studio.de)",
   "license": "MIT",
   "engines": {
     "node": ">=18"
@@ -51,7 +51,7 @@
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "1.2.1"
+    "@prave/shared": "1.2.2"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",