@prave/cli 0.4.10 → 1.0.0

package/dist/commands/usage.js

@@ -0,0 +1,267 @@
+import { readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+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 { AGENT_REGISTRY } from '@prave/shared';
+import { loadCursor, saveCursor } from '../lib/usage-cursor.js';
+import { scanTranscriptsForUsage } from '../lib/usage-scanner.js';
+import { log } from '../utils/logger.js';
+/**
+ * `prave usage scan` — read every recent JSONL transcript on disk, find
+ * Skill invocations, and POST them to `/api/v1/intelligence/usage/batch`.
+ * Hour-bucket dedup happens server-side, so re-runs are cheap.
+ *
+ * Use `--since=7d` to override the watermark (handy when you've manually
+ * cleared the cursor or want to backfill). `--quiet` suppresses output —
+ * used by `prave sync` to chain a scan without spamming the terminal.
+ */
+export async function usageScanCommand(opts) {
+    const session = await requireAuth('prave usage scan');
+    if (!session)
+        return;
+    const since = opts.since ? parseSinceFlag(opts.since) : await loadCursor();
+    const spinner = opts.quiet ? null : ora('Scanning Claude Code transcripts…').start();
+    // 1. Gather installed slug list — this is our recognition allowlist.
+    const slugs = await listInstalledSlugs();
+    if (!slugs.length) {
+        spinner?.warn('No Skills installed locally — nothing to track.');
+        return;
+    }
+    // 2. Scan local JSONL transcripts.
+    let events = [];
+    try {
+        events = await scanTranscriptsForUsage(slugs, since);
+    }
+    catch (err) {
+        spinner?.fail(`Scan failed: ${err.message}`);
+        return;
+    }
+    if (!events.length) {
+        spinner?.succeed(`No new Skill invocations since ${since.toISOString()}.`);
+        await saveCursor();
+        return;
+    }
+    if (spinner)
+        spinner.text = `Mapping ${events.length} events to your Skill catalog…`;
+    // 3. Map slug → skill_metadata_id via the intelligence API.
+    let metadata = [];
+    try {
+        const { data } = await api.get('/api/v1/intelligence/skills', true);
+        metadata = data;
+    }
+    catch (err) {
+        spinner?.fail(err instanceof ApiError
+            ? `Couldn't fetch your Skill catalog: ${err.message}`
+            : 'Network error fetching your Skill catalog.');
+        return;
+    }
+    const slugToId = buildSlugMap(metadata);
+    const payload = events
+        .map((e) => {
+        const id = slugToId.get(e.slug);
+        if (!id)
+            return null;
+        return {
+            skill_metadata_id: id,
+            triggered_at: e.triggered_at,
+            trigger_phrase: e.trigger_phrase ?? null,
+        };
+    })
+        .filter((e) => Boolean(e));
+    if (!payload.length) {
+        spinner?.succeed('Found events, but none matched the Skills tracked on your account. Run `prave import --upload` first.');
+        return;
+    }
+    // 4. Send in chunks of 500 (server cap).
+    if (spinner)
+        spinner.text = `Reporting ${payload.length} events…`;
+    let inserted = 0;
+    let deduped = 0;
+    for (let i = 0; i < payload.length; i += 500) {
+        const slice = payload.slice(i, i + 500);
+        try {
+            const { data } = await api.post('/api/v1/intelligence/usage/batch', { events: slice }, true);
+            inserted += data.inserted;
+            deduped += data.deduped;
+        }
+        catch (err) {
+            spinner?.fail(`Upload failed mid-batch: ${err.message}`);
+            return;
+        }
+    }
+    await saveCursor();
+    if (spinner) {
+        spinner.succeed(`${chalk.bold(inserted)} new event${inserted === 1 ? '' : 's'} reported · ${deduped} already known.`);
+    }
+    else if (!opts.quiet) {
+        log.dim(`Usage: ${inserted} new, ${deduped} known.`);
+    }
+}
+/**
+ * `prave usage report` — invoked by the Claude Code `PostToolUse` hook.
+ * Reads the hook payload from stdin, extracts the Skill name, and fires
+ * a single-event POST. Errors are silent (we never want a hook failure
+ * to disturb the user's workflow).
+ */
+export async function usageReportCommand() {
+    // Hook payload arrives on stdin. If we can't read it, exit silently.
+    const stdinPayload = await readStdin();
+    if (!stdinPayload)
+        return;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(stdinPayload);
+    }
+    catch {
+        return;
+    }
+    const rawSlug = parsed.tool_input?.skill;
+    if (typeof rawSlug !== 'string' || !rawSlug.trim())
+        return;
+    const slug = rawSlug.toLowerCase().split(':').pop()?.trim();
+    if (!slug)
+        return;
+    // No auth → bail silently. The user is browsing logged-out; we're not
+    // going to bug them with a login prompt from a background hook.
+    const session = await requireAuthSilent();
+    if (!session)
+        return;
+    try {
+        const { data: metadata } = await api.get('/api/v1/intelligence/skills', true);
+        const id = buildSlugMap(metadata).get(slug);
+        if (!id)
+            return;
+        await api.post('/api/v1/intelligence/usage', { skill_metadata_id: id, trigger_phrase: null }, true);
+    }
+    catch {
+        /* silent — never break the host shell */
+    }
+}
+export async function usageHookInstallCommand() {
+    const session = await requireAuth('prave usage hook install');
+    if (!session)
+        return;
+    const agents = await fetchEnabledAgents();
+    if (!agents.length) {
+        log.warn('No agents enabled on your account. Run `prave settings` or `prave login` first.');
+        return;
+    }
+    const results = await installHooksForAgents(agents);
+    printAgentResults(results, 'install');
+}
+export async function usageHookUninstallCommand() {
+    const session = await requireAuth('prave usage hook uninstall');
+    if (!session)
+        return;
+    const agents = await fetchEnabledAgents();
+    if (!agents.length) {
+        // Nothing in the SaaS profile? Try removing from Claude anyway —
+        // the user might have installed manually.
+        const results = await uninstallHooksForAgents(['claude']);
+        printAgentResults(results, 'uninstall');
+        return;
+    }
+    const results = await uninstallHooksForAgents(agents);
+    printAgentResults(results, 'uninstall');
+}
+async function fetchEnabledAgents() {
+    try {
+        const { data } = await api.get('/api/v1/settings/agents', true);
+        return data.enabled_agents ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function printAgentResults(results, verb) {
+    for (const r of results) {
+        const label = AGENT_REGISTRY[r.agent].label;
+        if (r.status === 'installed') {
+            log.success(`${label} hook ${verb === 'install' ? 'installed' : 'removed'}`);
+        }
+        else if (r.status === 'already') {
+            log.dim(`${label}: ${verb === 'install' ? 'already installed' : 'nothing to remove'}`);
+        }
+        else if (r.status === 'unsupported') {
+            log.dim(`${label}: real-time hook not yet supported — usage scan still tracks via \`prave sync\`.`);
+        }
+        else {
+            log.warn(`${label}: ${r.message ?? 'failed'}`);
+        }
+    }
+    if (verb === 'install') {
+        const installed = results.filter((r) => r.status === 'installed' || r.status === 'already');
+        if (installed.length) {
+            log.dim(`Run \`prave usage hook uninstall\` to remove. Supported agents: ${HOOK_SUPPORTED.join(', ')}.`);
+        }
+    }
+}
+async function listInstalledSlugs() {
+    try {
+        const entries = await readdir(CONFIG.skillsDir);
+        const slugs = [];
+        for (const name of entries) {
+            if (name.startsWith('.'))
+                continue;
+            const dir = join(CONFIG.skillsDir, name);
+            if ((await stat(dir).catch(() => null))?.isDirectory())
+                slugs.push(name.toLowerCase());
+        }
+        return slugs;
+    }
+    catch {
+        return [];
+    }
+}
+function buildSlugMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        if (!row.file_path)
+            continue;
+        // file_path looks like "<skillsDir>/<slug>/SKILL.md" — slug is the
+        // parent directory name. We also fall back to the row's `name` so a
+        // server that stored the slug in `name` still resolves.
+        const parts = row.file_path.split('/').filter(Boolean);
+        const skillIdx = parts.findIndex((p) => p === 'skills');
+        const slug = skillIdx >= 0 && parts[skillIdx + 1]
+            ? parts[skillIdx + 1].toLowerCase()
+            : (basename(row.file_path.replace(/\/SKILL\.md$/i, '')) || '').toLowerCase();
+        if (slug)
+            map.set(slug, row.id);
+        if (row.name)
+            map.set(row.name.toLowerCase(), row.id);
+    }
+    return map;
+}
+function parseSinceFlag(raw) {
+    const m = /^(\d+)([dh])$/.exec(raw.trim());
+    if (!m)
+        return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const n = Number(m[1]);
+    const unit = m[2];
+    const ms = unit === 'h' ? n * 60 * 60 * 1000 : n * 24 * 60 * 60 * 1000;
+    return new Date(Date.now() - ms);
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        if (Buffer.concat(chunks).length > 1_000_000)
+            break;
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Auth check with no UX side-effects. Used by the hook so a logged-out
+ * user never sees a stray "please log in" message during their workflow.
+ */
+async function requireAuthSilent() {
+    const { loadCredentials } = await import('../lib/credentials.js');
+    return loadCredentials();
+}

package/dist/commands/whoami.js

@@ -1,5 +1,15 @@
+import { ApiError, api } from '../lib/api.js';
 import { loadCredentials } from '../lib/credentials.js';
 import { log } from '../utils/logger.js';
+/**
+ * `prave whoami` — quick check that the local credentials still authenticate
+ * against the API. Hits `GET /api/v1/me` so the displayed name is always the
+ * server-side truth (and any stale local data gets refreshed implicitly via
+ * the auto-refresh path on api.get).
+ *
+ * If we can't reach the API (offline, server down) we fall back to the
+ * locally cached email so the command stays useful in airplane mode.
+ */
 export async function whoamiCommand() {
     const creds = await loadCredentials();
     if (!creds) {
@@ -7,7 +17,25 @@ export async function whoamiCommand() {
         process.exitCode = 1;
         return;
     }
-    log.kv('user_id', creds.user_id);
-    if (creds.email)
-        log.kv('email', creds.email);
+    try {
+        const { data } = await api.get('/api/v1/me', true);
+        const handle = data.username || data.display_name || data.email || creds.email || 'unknown';
+        log.kv('user', handle);
+        if (data.email)
+            log.kv('email', data.email);
+        log.kv('plan', data.plan);
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 401) {
+            log.warn('Session expired. Run `prave login` again.');
+            process.exitCode = 1;
+            return;
+        }
+        // Offline or transient API error — fall back to local creds so the
+        // command still does *something* useful instead of crashing.
+        if (creds.email)
+            log.kv('user', creds.email);
+        else
+            log.kv('user', creds.user_id);
+    }
 }

package/dist/index.js

@@ -19,6 +19,8 @@ import { searchCommand } from './commands/search.js';
 import { settingsCommand } from './commands/settings.js';
 import { syncCommand } from './commands/sync.js';
 import { uninstallCommand } from './commands/uninstall.js';
+import { updateCommand } from './commands/update.js';
+import { usageHookInstallCommand, usageHookUninstallCommand, usageReportCommand, usageScanCommand, } from './commands/usage.js';
 import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -33,8 +35,9 @@ program.command('whoami').description('Show the signed-in user').action(whoamiCo
 program
     .command('import')
     .description('Scan ~/.claude/skills/ — optionally upload to Prave')
-    .option('--upload', 'upload scanned skills')
-    .option('--private', 'upload as private (requires --upload)')
+    .option('--upload', 'upload scanned skills (requires --public or --private)')
+    .option('--public', 'upload as public (listed in the registry)')
+    .option('--private', 'upload as private (only you can see them)')
     .action(importCommand);
 program
     .command('install <slug>')
@@ -50,6 +53,12 @@ program
     .command('sync')
     .description('Pull updates for every locally installed Skill')
     .action(syncCommand);
+program
+    .command('update [slug]')
+    .description('Diff installed Skills against the registry and pull anything outdated')
+    .option('--dry-run', "preview what would change, don't write")
+    .option('--yes', 'skip confirmation prompt')
+    .action((slug, opts) => updateCommand(slug, opts));
 program
     .command('list')
     .description('List installed Skills (default) or remote ones')
@@ -92,6 +101,28 @@ program
     .description('Recommendations: underused, mergeable, and heavy skills')
     .option('--apply', 'placeholder for auto-apply')
     .action(optimizeCommand);
+const usage = program
+    .command('usage')
+    .description('Track which Skills you actually use (powers the optimiser)');
+usage
+    .command('scan')
+    .description('Scan local Claude Code transcripts and report invocations to Prave')
+    .option('--since <window>', 'override the watermark, e.g. "7d" or "12h"')
+    .option('--quiet', 'log a one-liner instead of a spinner')
+    .action(usageScanCommand);
+usage
+    .command('report')
+    .description('Internal: invoked by the Claude Code PostToolUse hook (reads stdin)')
+    .action(usageReportCommand);
+const hook = usage.command('hook').description('Install/uninstall the Claude Code real-time usage hook');
+hook
+    .command('install')
+    .description('Add a PostToolUse hook to ~/.claude/settings.json')
+    .action(usageHookInstallCommand);
+hook
+    .command('uninstall')
+    .description('Remove the Prave-managed hook from ~/.claude/settings.json')
+    .action(usageHookUninstallCommand);
 program
     .command('find <query>')
     .description('Smart skill search across local and marketplace')

package/dist/lib/agent-onboarding.js

@@ -0,0 +1,107 @@
+import { AGENT_REGISTRY, AGENT_TYPES } from '@prave/shared';
+import chalk from 'chalk';
+import { api } from './api.js';
+import { HOOK_SUPPORTED, installHooksForAgents } from './hook.js';
+import { checkboxPrompt } from './prompt.js';
+import { log } from '../utils/logger.js';
+/**
+ * Shared "pick which agents you use" flow. Called by `prave login`
+ * (right after credentials are saved) and reused by
+ * `prave settings → Agent Configuration` so the user gets exactly the
+ * same UX in both places — no 1-5 numeric menus, no comma-separated
+ * typing.
+ *
+ * After the pick we also offer to install the real-time hook on every
+ * supported agent. Hook installation is opt-in: if the user just wants
+ * the agents enabled without hooks, they hit `n` at the second prompt.
+ */
+export async function runAgentOnboarding() {
+    // 1. Pull whatever the SaaS profile already has so we prefill the
+    //    selection from the user's web settings.
+    let current = null;
+    try {
+        const { data } = await api.get('/api/v1/settings/agents', true);
+        current = data;
+    }
+    catch {
+        /* fresh user with no saved prefs — fall through to defaults */
+    }
+    const items = AGENT_TYPES.map((id) => {
+        const meta = AGENT_REGISTRY[id];
+        const supportsHook = HOOK_SUPPORTED.includes(id);
+        return {
+            value: id,
+            label: meta.label,
+            hint: supportsHook ? `${meta.description} · real-time hook` : meta.description,
+        };
+    });
+    const initial = (current?.enabled_agents ?? ['claude']);
+    const picked = await checkboxPrompt('Which agents should Prave manage?', items, { initial, minSelected: 1 });
+    if (!picked) {
+        log.warn('No agents selected — keeping previous selection.');
+        return current;
+    }
+    // 2. Persist to SaaS so web + CLI stay in sync.
+    let updated = current ?? {
+        user_id: '',
+        enabled_agents: [],
+        skill_paths: {},
+        detected_os: detectOs(),
+        updated_at: new Date().toISOString(),
+    };
+    try {
+        const { data } = await api.put('/api/v1/settings/agents', { enabled_agents: picked, detected_os: detectOs() }, true);
+        updated = data;
+        log.info(`Enabled agents: ${chalk.cyan(updated.enabled_agents.join(', '))}`);
+    }
+    catch (err) {
+        log.warn(`Couldn't sync agents to your account: ${err.message}`);
+        return current;
+    }
+    // 3. Offer to install the real-time hook on every agent that supports
+    //    it. We make this a single y/n — the hook itself is uniform across
+    //    the chosen agents, so a per-agent confirmation would be friction.
+    const supportedPicks = picked.filter((a) => HOOK_SUPPORTED.includes(a));
+    if (!supportedPicks.length) {
+        log.dim('No real-time hook contract for the agents you picked yet — usage will still be tracked via `prave usage scan` (auto-runs on `prave sync`).');
+        return updated;
+    }
+    const wantHook = await yesNoPrompt(`Install the real-time usage hook for ${supportedPicks
+        .map((a) => AGENT_REGISTRY[a].label)
+        .join(', ')}? [y/N] `);
+    if (!wantHook) {
+        log.dim('Skipped. Run `prave usage hook install` later to enable.');
+        return updated;
+    }
+    const results = await installHooksForAgents(picked);
+    for (const r of results) {
+        const label = AGENT_REGISTRY[r.agent].label;
+        if (r.status === 'installed')
+            log.success(`${label} hook installed`);
+        else if (r.status === 'already')
+            log.dim(`${label} hook already present`);
+        else if (r.status === 'unsupported')
+            log.dim(`${label}: ${r.message}`);
+        else
+            log.warn(`${label}: ${r.message ?? 'install failed'}`);
+    }
+    return updated;
+}
+function detectOs() {
+    if (process.platform === 'darwin')
+        return 'mac';
+    if (process.platform === 'win32')
+        return 'windows';
+    return 'linux';
+}
+async function yesNoPrompt(question) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const ans = (await rl.question(question)).trim().toLowerCase();
+        return ans === 'y' || ans === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/api.js

@@ -1,6 +1,6 @@
 import { request } from 'undici';
 import { CONFIG } from './config.js';
-import { loadCredentials } from './credentials.js';
+import { loadCredentials, saveCredentials } from './credentials.js';
 export class ApiError extends Error {
     status;
     constructor(message, status) {
@@ -9,7 +9,52 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
-async function call(method, path, body, withAuth = false) {
+/**
+ * Single-flight refresh — multiple parallel requests all hitting 401 share
+ * one refresh round-trip instead of stampeding the API and burning the
+ * Supabase rate limiter.
+ */
+let refreshing = null;
+async function refreshTokens() {
+    if (refreshing)
+        return refreshing;
+    refreshing = (async () => {
+        const creds = await loadCredentials();
+        if (!creds?.refresh_token)
+            return null;
+        try {
+            const { statusCode, body } = await request(`${CONFIG.apiUrl}/api/v1/cli/refresh`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ refresh_token: creds.refresh_token }),
+            });
+            const text = await body.text();
+            if (statusCode !== 200)
+                return null;
+            const payload = JSON.parse(text);
+            if (!payload.success || !payload.data)
+                return null;
+            const next = {
+                ...creds,
+                access_token: payload.data.access_token,
+                refresh_token: payload.data.refresh_token ?? creds.refresh_token,
+                user_id: payload.data.user_id,
+            };
+            await saveCredentials(next);
+            return next;
+        }
+        catch {
+            return null;
+        }
+    })();
+    try {
+        return await refreshing;
+    }
+    finally {
+        refreshing = null;
+    }
+}
+async function call(method, path, body, withAuth = false, attempt = 0) {
     const headers = { 'Content-Type': 'application/json' };
     if (withAuth) {
         const creds = await loadCredentials();
@@ -26,6 +71,13 @@ async function call(method, path, body, withAuth = false) {
     if (statusCode === 204)
         return { data: undefined, status: statusCode };
     const payload = text ? JSON.parse(text) : { success: true, data: null, error: null };
+    // 401 with a refresh token on file → swap the access token and retry once.
+    // Any other status, or a second 401, falls through to the normal error path.
+    if (statusCode === 401 && withAuth && attempt === 0) {
+        const refreshed = await refreshTokens();
+        if (refreshed)
+            return call(method, path, body, withAuth, attempt + 1);
+    }
     if (statusCode >= 400 || payload.success === false) {
         throw new ApiError(payload.error ?? `HTTP ${statusCode}`, statusCode);
     }

package/dist/lib/credentials.js

@@ -23,3 +23,24 @@ export async function clearCredentials() {
         /* already gone */
     }
 }
+/**
+ * Gate for CLI commands that mutate Prave-side state or whose effect we
+ * need to track (installs, deploys, settings, intelligence). Search and
+ * read-only Discover paths are intentionally NOT gated — anyone can
+ * browse the public registry from the terminal.
+ *
+ * Prints a friendly hint and sets a non-zero exit code when the caller
+ * isn't logged in.
+ */
+export async function requireAuth(commandName) {
+    const creds = await loadCredentials();
+    if (creds)
+        return creds;
+    // Lazy-import the chalk/log utilities here to avoid a circular dep on
+    // the credentials module.
+    const { log } = await import('../utils/logger.js');
+    log.warn(`\`${commandName}\` requires sign-in.`);
+    log.dim('Run `prave login` first — installs are tracked against your account so we can keep counts honest.');
+    process.exitCode = 1;
+    return null;
+}