@prave/cli 1.6.0 → 1.6.2

package/dist/commands/advisor.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { track } from '../lib/analytics.js';
+import { api, ApiError } from '../lib/api.js';
+import { CONFIG } from '../lib/config.js';
+import { requireAuth } from '../lib/credentials.js';
+import { log } from '../utils/logger.js';
+const RULE = '─────────────────────────────────────────';
+export async function advisorCommand(task, opts = {}) {
+    const mode = opts.auto ? 'auto' : 'manual';
+    track('cli_advisor', { auto_mode: opts.auto === true, task_length: task?.length ?? 0 });
+    if (mode === 'manual') {
+        if (!task || task.trim().length < 8) {
+            log.error('Pass a task description of at least 8 characters, or use --auto.');
+            process.exitCode = 1;
+            return;
+        }
+    }
+    await requireAuth('advisor');
+    const spinner = ora(mode === 'auto' ? 'Thinking…' : `Thinking about "${truncate(task, 60)}"…`).start();
+    try {
+        const { data } = await api.post('/api/v1/advisor', { mode, task: mode === 'manual' ? task : undefined }, true);
+        spinner.stop();
+        console.log(chalk.dim(RULE));
+        const hasReasoned = data.recommendations.length > 0;
+        console.log(chalk.bold(hasReasoned ? 'Recommended for you' : 'Starting points'));
+        console.log(chalk.dim(RULE));
+        console.log(wrap(data.prose, 78));
+        console.log();
+        if (hasReasoned) {
+            for (const rec of data.recommendations) {
+                printSkill(rec.slug, rec.reason);
+            }
+        }
+        else if (data.candidate_slugs.length > 0) {
+            for (const slug of data.candidate_slugs) {
+                printSkill(slug);
+            }
+        }
+        else {
+            log.dim('No specific Skills to recommend yet.');
+        }
+        console.log(chalk.dim(`Quota: ${data.quota.used} / ${data.quota.limit} today on the ${data.quota.plan} plan.`));
+    }
+    catch (err) {
+        spinner.stop();
+        log.error(err instanceof ApiError ? err.message : err.message);
+        process.exitCode = 1;
+    }
+}
+/**
+ * Print one Skill row — bullet · slug · optional Why · install command
+ * · clickable prave.app link. The link is what lets the user verify
+ * the Skill on the web before pulling it into their library.
+ */
+function printSkill(slug, reason) {
+    console.log(`  ${chalk.cyan('▸')} ${chalk.bold(slug)}`);
+    if (reason) {
+        console.log(`    ${chalk.dim('Why:')} ${wrap(reason, 70).split('\n').join('\n    ')}`);
+    }
+    console.log(`    ${chalk.dim(`prave install ${slug}`)}`);
+    console.log(`    ${chalk.dim(`${CONFIG.webUrl}/skills/${slug}`)}`);
+    console.log();
+}
+function truncate(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}
+function wrap(text, width) {
+    const out = [];
+    for (const para of text.split('\n')) {
+        const words = para.trim().split(/\s+/);
+        let line = '';
+        for (const w of words) {
+            if ((line + ' ' + w).trim().length > width) {
+                out.push(line.trim());
+                line = w;
+            }
+            else {
+                line = `${line} ${w}`;
+            }
+        }
+        if (line.trim())
+            out.push(line.trim());
+    }
+    return out.join('\n');
+}

package/dist/commands/mcp-server.js

@@ -4,6 +4,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { api, ApiError } from '../lib/api.js';
+import { CONFIG } from '../lib/config.js';
 import { loadCredentials } from '../lib/credentials.js';
 const TOOLS = [
     {
@@ -62,6 +63,23 @@ const TOOLS = [
             required: ['slug'],
         },
     },
+    {
+        name: 'prave_advisor',
+        description: "Contextual Skill advisor. Given a user task (e.g. 'I'm building a Next.js app with Stripe and auth'), returns a prose recommendation explaining which Skills genuinely fit and why. Tiered freemium quota — Free 3/day, Pro 10/day, Max 30/day — enforced server-side. Use this when the user asks 'what Skills should I install for X?' or 'help me pick Skills for my project'.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: "The user's task / context. Min 8 chars. Omit to run in auto mode.",
+                },
+                auto: {
+                    type: 'boolean',
+                    description: "When true, ignore `task` and synthesise context from the user's installed Skills + recent usage.",
+                },
+            },
+        },
+    },
 ];
 export async function mcpServerCommand() {
     // Auth check up-front. If the user runs `prave mcp-server` without
@@ -96,6 +114,8 @@ export async function mcpServerCommand() {
                     return await handleAuditLibrary();
                 case 'prave_install_skill':
                     return await handleInstallSkill(args);
+                case 'prave_advisor':
+                    return await handleAdvisor(args);
                 default:
                     return mcpError(`Unknown tool: ${name}`);
             }
@@ -202,6 +222,37 @@ async function handleInstallSkill(args) {
         });
     });
 }
+async function handleAdvisor(args) {
+    const mode = args.auto ? 'auto' : 'manual';
+    if (mode === 'manual' && (!args.task || args.task.trim().length < 8)) {
+        return mcpError("Pass a `task` of at least 8 characters describing what the user is building, or set `auto: true` to use their installed Skills as context.");
+    }
+    const { data } = await api.post('/api/v1/advisor', { mode, task: mode === 'manual' ? args.task : undefined }, true);
+    const lines = [data.prose, ''];
+    const hasReasoned = data.recommendations.length > 0;
+    if (hasReasoned) {
+        for (const rec of data.recommendations) {
+            lines.push(`• ${rec.slug}`);
+            lines.push(`  Why: ${rec.reason}`);
+            lines.push(`  Install: prave install ${rec.slug}`);
+            lines.push(`  View: ${CONFIG.webUrl}/skills/${rec.slug}`);
+        }
+    }
+    else if (data.candidate_slugs.length > 0) {
+        lines.push('Starting points (no reasoned picks — browse these on prave.app):');
+        for (const slug of data.candidate_slugs) {
+            lines.push(`• ${slug}`);
+            lines.push(`  Install: prave install ${slug}`);
+            lines.push(`  View: ${CONFIG.webUrl}/skills/${slug}`);
+        }
+    }
+    else {
+        lines.push('(No specific Skills recommended for this context.)');
+    }
+    lines.push('');
+    lines.push(`Advisor quota: ${data.quota.used} / ${data.quota.limit} today on the ${data.quota.plan} plan.`);
+    return mcpText(lines.join('\n'));
+}
 /* ─── helpers ──────────────────────────────────────────────────── */
 function mcpText(text) {
     return { content: [{ type: 'text', text }] };

package/dist/commands/usage.js

@@ -118,9 +118,30 @@ export async function usageScanCommand(opts) {
  *   - one POST attempt with a hard 4 s deadline (background-friendly)
  *   - on auth/network failure we log + bail; never throw
  */
+/**
+ * Telemetry hook reporter. Reads the agent's hook payload from stdin,
+ * extracts the slug, and posts to /api/v1/intelligence/usage/by-slug.
+ *
+ * Forward-compat: `--agent` is parameterised so when Codex/Gemini/
+ * Cursor/Continue/Cline/Amp ship their own lifecycle-hook contracts,
+ * the install code only needs to write a different value into the
+ * generated hook command. The reporter itself stays the same.
+ *
+ * Today only `claude` produces hook payloads; the API endpoint accepts
+ * the full enum already (intelligence.routes.ts), so this CLI change
+ * unlocks the path with zero server work.
+ */
+const TRACKED_AGENTS = ['claude', 'codex', 'cursor', 'gemini', 'cline', 'amp'];
+function normaliseAgent(input) {
+    const lower = (input ?? '').toLowerCase();
+    return TRACKED_AGENTS.includes(lower)
+        ? lower
+        : 'claude';
+}
 export async function usageReportCommand(opts = {}) {
     const debug = process.env.PRAVE_DEBUG === '1' || process.env.PRAVE_DEBUG === 'true';
     const source = opts.source === 'prompt' ? 'prompt' : 'tool';
+    const agent_type = normaliseAgent(opts.agent);
     await rotateHookLog();
     const stdinPayload = await readStdin();
     if (!stdinPayload) {
@@ -197,7 +218,7 @@ export async function usageReportCommand(opts = {}) {
     if (!session) {
         await bufferEvent({
             slug,
-            agent_type: 'claude',
+            agent_type,
             triggered_at,
             meta: { ...meta, source },
         });
@@ -209,7 +230,7 @@ export async function usageReportCommand(opts = {}) {
     try {
         const { data } = await api.post('/api/v1/intelligence/usage/by-slug', {
             slug,
-            agent_type: 'claude',
+            agent_type,
             triggered_at,
             meta: { ...meta, source },
         }, true);
@@ -223,7 +244,7 @@ export async function usageReportCommand(opts = {}) {
         // the event isn't lost. The next successful command will replay.
         await bufferEvent({
             slug,
-            agent_type: 'claude',
+            agent_type,
             triggered_at,
             meta: { ...meta, source },
         });

package/dist/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { conflictsCommand } from './commands/conflicts.js';
 import { diffCommand } from './commands/diff.js';
+import { advisorCommand } from './commands/advisor.js';
 import { docsCommand } from './commands/docs.js';
 import { hooksAuditCommand, hooksInstallCommand, hooksListCommand, hooksRemoveCommand, hooksSyncCommand, hooksUpdateCommand, } from './commands/hooks.js';
 import { importCommand } from './commands/import.js';
@@ -110,6 +111,11 @@ program
     .command('whatdoes <skillname>')
     .description("Inspect a skill's triggers, tokens, conflicts")
     .action(whatdoesCommand);
+program
+    .command('advisor [task...]')
+    .description('Prose recommendation from the contextual Skill advisor — pass a task description, or use --auto to base it on your installed Skills.')
+    .option('--auto', 'use your installed Skills + recent usage as context (no task argument)')
+    .action((taskWords, opts) => advisorCommand(taskWords.length ? taskWords.join(' ') : undefined, opts));
 program
     .command('overview')
     .description('Summary of your skill set, conflicts, and token cost')
@@ -135,6 +141,7 @@ usage
     .command('report')
     .description('Internal: invoked by the agent when a Skill fires (reads payload from stdin)')
     .option('--source <kind>', 'event channel that fired this report', 'tool')
+    .option('--agent <name>', 'which agent fired the event (claude | codex | cursor | gemini | cline | amp). Forward-compat: only `claude` is wired by `prave usage hook install` today, but the parameter lets future installers point at other runtimes.', 'claude')
     .action((opts) => usageReportCommand(opts));
 const hook = usage.command('hook').description('Enable / disable real-time Skill invocation tracking');
 hook

package/dist/lib/hook.js

@@ -43,11 +43,16 @@ const REGISTRY_CHANNELS = [
     'PreCompact',
     'SessionStart',
 ];
-const HOOK_COMMAND = 'prave usage report';
+// Stamped with `--agent claude` so the reporter attributes the
+// invocation to the right runtime in our usage telemetry. Forward-
+// compat: when Codex/Gemini/Cursor add equivalent lifecycle hooks,
+// the new per-agent install branch will write `--agent codex` (etc.)
+// — the reporter itself already accepts the full enum.
+const HOOK_COMMAND = 'prave usage report --agent=claude';
 // Companion command for the UserPromptSubmit channel so a typed-slash
 // `/graphify` is captured even when the Skill tool path doesn't fire a
 // matching PostToolUse with a populated `tool_input.skill` field.
-const PROMPT_HOOK_COMMAND = 'prave usage report --source=prompt';
+const PROMPT_HOOK_COMMAND = 'prave usage report --source=prompt --agent=claude';
 /**
  * Install on BOTH `PostToolUse` (matcher `Skill`) and `UserPromptSubmit`
  * (catches slash commands like `/graphify` before tool dispatch). The two

package/dist/lib/usage-scanner.js

@@ -1,9 +1,30 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
 /**
- * Scan every .jsonl transcript newer than `since` for Skill invocations.
+ * Per-agent transcript roots. Today only `claude` ships a structured
+ * JSONL transcript at a known path; the other agents either don't
+ * persist transcripts in a comparable shape (Codex, Gemini CLI), keep
+ * them in opaque formats (Cursor, Continue), or don't expose them on
+ * disk at all (Cline, Amp).
+ *
+ * Forward-compat: when an agent publishes a JSONL-style transcript
+ * convention with `tool_use`-shaped lines, drop an entry into the map
+ * and the scanner picks it up automatically. The `extractEventsFromLine`
+ * parser is JSON-shape-agnostic — it walks any object tree looking for
+ * a `name === 'Skill'` tool-use plus the canonical `<command-name>`
+ * marker. As long as the new agent's transcript surfaces those it's a
+ * zero-code-change integration.
+ */
+const AGENT_TRANSCRIPT_ROOTS = {
+    claude: join(homedir(), '.claude', 'projects'),
+    // codex:    join(homedir(), '.codex', 'projects'),    // TBD — Codex transcript path
+    // gemini:   join(homedir(), '.gemini-cli', 'sessions'), // TBD — Gemini CLI session path
+    // cursor:   …                                          // currently no disk transcript
+};
+/**
+ * Scan every .jsonl transcript newer than `since` for Skill invocations
+ * across every agent we know how to read.
  *
  * @param installedSlugs the slugs we recognise — anything outside this
  *  set is ignored to avoid noise from quoted text.
@@ -18,9 +39,15 @@ export async function scanTranscriptsForUsage(installedSlugs, since) {
     const slugSet = new Set(installedSlugs);
     const sinceMs = since.getTime();
     const events = [];
-    const projectDirs = await safeReaddir(PROJECTS_DIR);
+    for (const root of Object.values(AGENT_TRANSCRIPT_ROOTS)) {
+        await scanTranscriptRoot(root, slugSet, sinceMs, events);
+    }
+    return events;
+}
+async function scanTranscriptRoot(root, slugSet, sinceMs, events) {
+    const projectDirs = await safeReaddir(root);
     for (const projectName of projectDirs) {
-        const projectDir = join(PROJECTS_DIR, projectName);
+        const projectDir = join(root, projectName);
         const projectStat = await safeStat(projectDir);
         if (!projectStat?.isDirectory())
             continue;
@@ -46,7 +73,6 @@ export async function scanTranscriptsForUsage(installedSlugs, since) {
             }
         }
     }
-    return events;
 }
 const COMMAND_NAME_RE = /<command-name>\s*\/?([a-z0-9][a-z0-9_-]{0,80})\s*<\/command-name>/gi;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -54,7 +54,7 @@
     "ora": "^8.0.1",
     "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.5.0"
+    "@prave/shared": "1.5.2"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",