@prave/cli 1.0.1 → 1.0.2

package/dist/commands/deploy.js

@@ -6,6 +6,7 @@ import ora from 'ora';
 import { AGENT_REGISTRY } from '@prave/shared';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
+import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { CONFIG } from '../lib/config.js';
 import { log } from '../utils/logger.js';
 function detectOsKey(detected) {
@@ -73,6 +74,17 @@ export async function deployCommand(skillName, opts = {}) {
     if (!session)
         return;
     const start = Date.now();
+    // Plan-gate the multi-agent target list. Free can only deploy to
+    // Claude Code; Pro+ unlocks all 6. We compute the allowed set from
+    // PLAN_LIMITS so the Stripe-side and CLI-side stay in lockstep.
+    const me = await fetchMyPlan();
+    const allowedAgents = new Set(me.limits.multi_agent_targets);
+    if (allowedAgents.size === 0) {
+        log.warn(`Your ${me.limits.label} plan can't deploy to any agent.`);
+        log.dim(formatUpgradeHint('explorer'));
+        process.exitCode = 1;
+        return;
+    }
     let settings;
     try {
         const { data } = await api.get('/api/v1/settings/agents', true);
@@ -86,7 +98,16 @@ export async function deployCommand(skillName, opts = {}) {
     const targetFilter = opts.agent && opts.agent.toLowerCase() !== 'all'
         ? opts.agent.toLowerCase()
         : null;
-    const targets = settings.enabled_agents.filter((a) => targetFilter === null || a === targetFilter);
+    const targets = settings.enabled_agents
+        .filter((a) => allowedAgents.has(a))
+        .filter((a) => targetFilter === null || a === targetFilter);
+    // If the user picked a target their plan can't reach, tell them why.
+    if (targetFilter && !allowedAgents.has(targetFilter)) {
+        log.warn(`Deploying to ${targetFilter} requires the Pro plan. Free can only deploy to Claude Code.`);
+        log.dim(formatUpgradeHint('explorer'));
+        process.exitCode = 1;
+        return;
+    }
     if (targets.length === 0) {
         log.warn('No matching agents enabled. Run `prave settings` to configure.');
         return;

package/dist/commands/export.js

@@ -10,12 +10,12 @@ import { log } from '../utils/logger.js';
  */
 export async function exportCommand(slug, opts = {}) {
     const session = await loadCredentials();
-    // Plan gate: Free can't export. Explorer caps at 50/mo (server-enforced
-    // via per-user counter once that lands; CLI-side we only flag the gate).
+    // Plan gate: export is part of the Pro+ authoring toolkit. Free can browse
+    // and install, not extract for republishing.
     if (session) {
         const me = await fetchMyPlan();
-        if (me.limits.cli_exports_monthly === 0) {
-            log.warn('Export requires the Explorer plan or higher.');
+        if (!me.limits.can_authoring_public && !me.limits.can_authoring_private) {
+            log.warn('Export requires the Pro plan or higher.');
             log.dim(formatUpgradeHint('explorer'));
             return;
         }

package/dist/commands/import.js

@@ -79,19 +79,32 @@ export async function importCommand(opts) {
         return;
     }
     const visibility = opts.private ? 'private' : 'public';
-    // Plan gate: clamp the queue to the caller's import / private quota so
-    // we don't waste 70 round-trips against a Free account that maxes at 10.
+    // Plan gate: authoring (public + private) is Pro+. Free is read-only on
+    // the registry side — discover, install, bookmark, but no upload.
     const me = await fetchMyPlan();
-    if (visibility === 'private' && !me.limits.can_private_skills) {
-        log.warn('Private imports require the Explorer plan.');
+    if (!me.limits.can_authoring_public && !me.limits.can_authoring_private) {
+        log.warn('Uploading Skills requires the Pro plan or higher.');
         log.dim(formatUpgradeHint('explorer'));
         return;
     }
+    if (visibility === 'private' && !me.limits.can_authoring_private) {
+        log.warn('Private uploads require the Pro plan.');
+        log.dim(formatUpgradeHint('explorer'));
+        return;
+    }
+    if (visibility === 'public' && !me.limits.can_authoring_public) {
+        log.warn('Public uploads require the Pro plan.');
+        log.dim(formatUpgradeHint('explorer'));
+        return;
+    }
+    // Clamp the queue to the caller's authoring ceiling. `null` = unlimited
+    // (Pro + Max), so the cap-check is a no-op for paid tiers.
     let queue = skills;
-    if (me.limits.cli_max_imports !== null && queue.length > me.limits.cli_max_imports) {
-        log.warn(`Your ${me.plan} plan caps imports at ${me.limits.cli_max_imports}. Trimming queue from ${queue.length} → ${me.limits.cli_max_imports}.`);
+    if (me.limits.authoring_max_skills !== null &&
+        queue.length > me.limits.authoring_max_skills) {
+        log.warn(`Your ${me.limits.label} plan caps authored Skills at ${me.limits.authoring_max_skills}. Trimming queue from ${queue.length} → ${me.limits.authoring_max_skills}.`);
         log.dim(formatUpgradeHint('explorer'));
-        queue = queue.slice(0, me.limits.cli_max_imports);
+        queue = queue.slice(0, me.limits.authoring_max_skills);
     }
     const uploadSpinner = ora(`Uploading ${queue.length} skills as ${visibility}…`).start();
     let ok = 0;

package/dist/commands/install.js

@@ -6,6 +6,7 @@ import ora from 'ora';
 import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { loadCredentials, requireAuth } from '../lib/credentials.js';
+import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { log } from '../utils/logger.js';
 /**
  * `prave install <slug>` — pulls SKILL.md to ~/.claude/skills/<slug>/.
@@ -25,6 +26,28 @@ export async function installCommand(slug, opts = {}) {
     const session = await requireAuth('prave install');
     if (!session)
         return;
+    // Plan gate — Free is capped at 5 installs / month. We surface the
+    // remaining count proactively so the user knows where they stand
+    // before hitting the wall on `install N+1`.
+    const me = await fetchMyPlan();
+    if (me.limits.install_monthly_limit !== null) {
+        try {
+            const { data } = await api.get('/api/v1/me/usage-snapshot', true);
+            const remaining = data.installs.remaining;
+            if (remaining !== null && remaining <= 0) {
+                log.warn(`Your ${me.limits.label} plan caps installs at ${me.limits.install_monthly_limit}/month. You've used all of them.`);
+                log.dim(formatUpgradeHint('explorer'));
+                process.exitCode = 1;
+                return;
+            }
+            if (remaining !== null && remaining <= 2) {
+                log.dim(`Heads up — ${remaining} install${remaining === 1 ? '' : 's'} left this month on the ${me.limits.label} plan.`);
+            }
+        }
+        catch {
+            /* snapshot endpoint unavailable — server still gates */
+        }
+    }
     const spinner = ora(`Resolving ${slug}…`).start();
     let installedSlugs = [];
     try {

package/dist/commands/update.js

@@ -6,6 +6,7 @@ import ora from 'ora';
 import { api } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { requireAuth } from '../lib/credentials.js';
+import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
 import { log } from '../utils/logger.js';
 /**
  * `prave update [<slug>]` — diff every CLI-installed Skill against its
@@ -24,6 +25,13 @@ export async function updateCommand(slug, opts = {}) {
     const session = await requireAuth('prave update');
     if (!session)
         return;
+    const me = await fetchMyPlan();
+    if (!me.limits.can_cli_update) {
+        log.warn(`\`prave update\` requires the Pro plan or higher.`);
+        log.dim(formatUpgradeHint('explorer'));
+        process.exitCode = 1;
+        return;
+    }
     const spinner = ora(slug ? `Resolving ${slug}…` : 'Checking your installed skills…').start();
     let installs;
     try {

package/dist/commands/usage.js

@@ -104,43 +104,93 @@ export async function usageScanCommand(opts) {
 /**
  * `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).
+ * a single-event POST against the slug-keyed self-healing endpoint.
+ * Errors are silent (we never want a hook failure to disturb the user's
+ * workflow); set `PRAVE_DEBUG=1` to see what's happening in
+ * `~/.prave/usage.log`.
  */
 export async function usageReportCommand() {
-    // Hook payload arrives on stdin. If we can't read it, exit silently.
+    const debug = process.env.PRAVE_DEBUG === '1' || process.env.PRAVE_DEBUG === 'true';
     const stdinPayload = await readStdin();
-    if (!stdinPayload)
+    if (!stdinPayload) {
+        if (debug)
+            await debugLog('no stdin payload');
         return;
+    }
+    if (debug)
+        await debugLog(`stdin len=${stdinPayload.length}`);
+    // Claude Code's PostToolUse payload is documented as `{tool_name,
+    // tool_input, tool_response, ...}`, but we still defend against
+    // alternate shapes (capitalisation, future schema drift) so the hook
+    // doesn't silently break on a single field rename.
     let parsed = {};
     try {
         parsed = JSON.parse(stdinPayload);
     }
     catch {
+        if (debug)
+            await debugLog('payload is not valid JSON');
         return;
     }
-    const rawSlug = parsed.tool_input?.skill;
-    if (typeof rawSlug !== 'string' || !rawSlug.trim())
+    const rawSlug = extractSkillSlug(parsed);
+    if (!rawSlug) {
+        if (debug)
+            await debugLog(`no skill slug in payload: ${stdinPayload.slice(0, 200)}`);
         return;
-    const slug = rawSlug.toLowerCase().split(':').pop()?.trim();
+    }
+    const slug = rawSlug.toLowerCase().split(':').pop()?.trim().replace(/[^a-z0-9_-]+/g, '-');
     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.
+    if (debug)
+        await debugLog(`slug=${slug}`);
     const session = await requireAuthSilent();
-    if (!session)
+    if (!session) {
+        if (debug)
+            await debugLog('no auth — skipping');
         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);
+        const { data } = await api.post('/api/v1/intelligence/usage/by-slug', { slug, agent_type: 'claude', triggered_at: new Date().toISOString() }, true);
+        if (debug)
+            await debugLog(`ok recorded=${data.recorded} stub=${data.created_stub}`);
     }
-    catch {
+    catch (err) {
+        if (debug)
+            await debugLog(`error: ${err.message}`);
         /* silent — never break the host shell */
     }
 }
+/**
+ * Walk the hook payload looking for the invoked Skill's slug. Tries the
+ * documented Claude Code path first, then several plausible aliases so
+ * we don't break if the schema gains a new wrapper or rename.
+ */
+function extractSkillSlug(payload) {
+    const candidates = [
+        payload.tool_input?.skill,
+        payload.toolInput?.skill,
+        payload.input?.skill,
+        payload.parameters?.skill,
+        payload.skill,
+    ];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c.trim())
+            return c;
+    }
+    return null;
+}
+async function debugLog(line) {
+    try {
+        const { mkdir, appendFile } = await import('node:fs/promises');
+        const { join } = await import('node:path');
+        await mkdir(CONFIG.praveDir, { recursive: true });
+        const stamp = new Date().toISOString();
+        await appendFile(join(CONFIG.praveDir, 'usage.log'), `${stamp} ${line}\n`);
+    }
+    catch {
+        /* swallow — debug is best-effort */
+    }
+}
 export async function usageHookInstallCommand() {
     const session = await requireAuth('prave usage hook install');
     if (!session)
@@ -168,6 +218,83 @@ export async function usageHookUninstallCommand() {
     const results = await uninstallHooksForAgents(agents);
     printAgentResults(results, 'uninstall');
 }
+/**
+ * `prave usage status` — diagnostic. Reports hook health, recent event
+ * counts, and a tail of the debug log so users can troubleshoot why
+ * "unused for 30+ days" still shows up after running a Skill.
+ */
+export async function usageStatusCommand() {
+    const session = await requireAuth('prave usage status');
+    if (!session)
+        return;
+    const { existsSync } = await import('node:fs');
+    const { readFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { homedir } = await import('node:os');
+    // 1. Hook installed?
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    let hookInstalled = false;
+    try {
+        const raw = await readFile(settingsPath, 'utf8');
+        hookInstalled = raw.includes('__prave_managed') && raw.includes('Skill');
+    }
+    catch {
+        /* no settings.json yet */
+    }
+    // 2. Last 7 days of recorded events from the API.
+    let recent7 = 0;
+    let topSlugs = [];
+    try {
+        const { data } = await api.get('/api/v1/intelligence/usage/recent?days=7', true);
+        recent7 = data.events?.length ?? 0;
+        topSlugs = data.by_skill ?? [];
+    }
+    catch {
+        /* endpoint optional — older servers may not have it */
+    }
+    // 3. Cursor watermark — when did the scanner last run?
+    const cursorPath = join(CONFIG.praveDir, 'usage-cursor.json');
+    let lastScanAt = null;
+    try {
+        const raw = await readFile(cursorPath, 'utf8');
+        lastScanAt = JSON.parse(raw).lastScanAt ?? null;
+    }
+    catch {
+        /* never scanned */
+    }
+    // 4. Debug log tail.
+    const logPath = join(CONFIG.praveDir, 'usage.log');
+    const debugAvailable = existsSync(logPath);
+    // Render.
+    const checkmark = (ok) => (ok ? chalk.green('✓') : chalk.dim('—'));
+    log.info(chalk.bold('Usage tracking status'));
+    console.log();
+    console.log(`  ${checkmark(hookInstalled)} Real-time hook (Claude Code): ${hookInstalled ? chalk.green('installed') : chalk.yellow('not installed — `prave usage hook install`')}`);
+    console.log(`  ${checkmark(Boolean(lastScanAt))} Transcript scanner watermark: ${lastScanAt ?? chalk.dim('never run — `prave sync` includes it')}`);
+    console.log(`  ${checkmark(recent7 > 0)} Events in last 7 days: ${chalk.cyan(String(recent7))}`);
+    if (topSlugs.length) {
+        console.log();
+        console.log(chalk.dim('  Most active in last 7 days:'));
+        for (const s of topSlugs.slice(0, 5)) {
+            console.log(`    ${chalk.cyan(s.count.toString().padStart(4))}  ${s.name}`);
+        }
+    }
+    console.log();
+    if (debugAvailable) {
+        log.dim(`Debug log: ${logPath}`);
+        log.dim('Set PRAVE_DEBUG=1 in your shell to enable verbose hook logging.');
+    }
+    else {
+        log.dim('No debug log yet. Set PRAVE_DEBUG=1 to capture every hook fire to ~/.prave/usage.log');
+    }
+    if (recent7 === 0) {
+        console.log();
+        log.warn('No events recorded yet. Quick checks:');
+        log.dim('  1. Is the hook installed? See checkmarks above.');
+        log.dim('  2. Run a Skill in Claude Code, then `tail ~/.prave/usage.log` (with PRAVE_DEBUG=1)');
+        log.dim('  3. Or run `prave usage scan --since 7d` to backfill from transcripts.');
+    }
+}
 async function fetchEnabledAgents() {
     try {
         const { data } = await api.get('/api/v1/settings/agents', true);

package/dist/index.js

@@ -20,7 +20,7 @@ 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 { usageHookInstallCommand, usageHookUninstallCommand, usageReportCommand, usageScanCommand, usageStatusCommand, } from './commands/usage.js';
 import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -110,6 +110,10 @@ usage
     .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('status')
+    .description('Diagnose hook health, recent event counts, and most-used Skills')
+    .action(usageStatusCommand);
 usage
     .command('report')
     .description('Internal: invoked by the Claude Code PostToolUse hook (reads stdin)')

package/dist/lib/plan.js

@@ -26,6 +26,14 @@ export const fetchMyPlan = async () => {
         return fallback;
     }
 };
-export const formatUpgradeHint = (required) => required === 'creator'
-    ? 'Upgrade to Creator at https://prave.app/dashboard/settings'
-    : 'Upgrade to Explorer (€4/mo) at https://prave.app/dashboard/settings';
+/**
+ * Stable copy block surfaced by every plan-gated CLI command. Built from
+ * `PLAN_LIMITS` so prices/labels stay consistent with the SaaS pricing
+ * card automatically.
+ */
+export const formatUpgradeHint = (required) => {
+    const limits = PLAN_LIMITS[required];
+    if (required === 'free')
+        return 'You\'re already on the Free plan.';
+    return `Upgrade to ${limits.label} ($${limits.price_usd_monthly}/mo or $${limits.price_usd_yearly}/yr) at https://prave.app/dashboard/settings/billing`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Prave CLI — import, export, install, sync Claude Skills.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "1.0.1"
+    "@prave/shared": "1.0.2"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",