@prave/cli 1.4.9 → 1.4.11

package/dist/commands/login.js

@@ -5,6 +5,7 @@ import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { saveCredentials } from '../lib/credentials.js';
+import { readLocalConfig, writeLocalConfigPatch } from '../lib/local-config.js';
 import { log } from '../utils/logger.js';
 /**
  * `prave login` — device-code flow against the Prave API / Supabase session.
@@ -51,12 +52,23 @@ export async function loginCommand() {
             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.
+            // First-login onboarding only. The agent picker + hook installer
+            // used to fire on EVERY login, which was annoying for users who
+            // re-login often (CI environments, multi-machine setups, after a
+            // token expiry). Now we gate on a persisted flag in
+            // ~/.prave/config.json — once they've completed the picker once,
+            // it never auto-fires again. Manual re-run available via
+            // `prave settings agent`.
             try {
-                const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
-                await runAgentOnboarding();
+                const cfg = await readLocalConfig();
+                if (cfg.agent_onboarding_done !== true) {
+                    const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
+                    await runAgentOnboarding();
+                    await writeLocalConfigPatch({ agent_onboarding_done: true });
+                }
+                else {
+                    log.dim('Welcome back — run `prave settings agent` to change your agent setup.');
+                }
             }
             catch (onboardErr) {
                 log.dim(`Agent onboarding skipped: ${onboardErr.message}`);

package/dist/commands/settings.js

@@ -1,10 +1,9 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import { AGENT_REGISTRY } from '@prave/shared';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
-import { CONFIG } from '../lib/config.js';
+import { writeLocalConfigPatch } from '../lib/local-config.js';
 import { log } from '../utils/logger.js';
 function detectOs() {
     if (process.platform === 'darwin')
@@ -13,20 +12,14 @@ function detectOs() {
         return 'windows';
     return 'linux';
 }
-async function loadLocalConfig() {
-    try {
-        const raw = await readFile(CONFIG.configPath, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return {};
-    }
-}
 async function saveLocalConfig(settings) {
-    await mkdir(CONFIG.praveDir, { recursive: true });
-    const existing = await loadLocalConfig();
-    const next = { ...existing, agentSettings: settings };
-    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
+    // Mark onboarding done as a side effect — running `prave settings
+    // agent` manually counts as completing the picker, so the user won't
+    // get auto-prompted again on the next `prave login`.
+    await writeLocalConfigPatch({
+        agentSettings: settings,
+        agent_onboarding_done: true,
+    });
 }
 async function fetchSettings() {
     const { data } = await api.get('/api/v1/settings/agents', true);

package/dist/commands/usage.js

@@ -432,8 +432,8 @@ export async function usageStatusCommand() {
     const checkmark = (ok) => (ok ? chalk.green('✓') : chalk.red('✗'));
     log.info(chalk.bold('Usage tracking status'));
     console.log();
-    console.log(`  ${checkmark(toolHookInstalled)} PostToolUse hook (Skill tool fires): ${toolHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
-    console.log(`  ${checkmark(promptHookInstalled)} UserPromptSubmit hook (slash commands like /graphify): ${promptHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
+    console.log(`  ${checkmark(toolHookInstalled)} Skill invocation tracking: ${toolHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
+    console.log(`  ${checkmark(promptHookInstalled)} Slash-command tracking (e.g. /graphify): ${promptHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
     console.log(`  ${checkmark(apiReachable)} API reachable + auth valid: ${apiReachable ? chalk.green('yes') : chalk.red(apiMessage || 'no')}`);
     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))}`);
@@ -470,7 +470,7 @@ export async function usageStatusCommand() {
         console.log();
         log.warn('Telemetry may be incomplete. Suggested fixes:');
         if (!toolHookInstalled || !promptHookInstalled) {
-            log.dim('  • Run `prave usage hook install` to wire BOTH PostToolUse and UserPromptSubmit.');
+            log.dim('  • Run `prave usage hook install` to enable both Skill-fire and slash-command tracking.');
         }
         if (!apiReachable) {
             log.dim('  • Run `prave login` — your access token may have expired (silently 401-ing).');

package/dist/index.js

@@ -25,6 +25,7 @@ import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { initAnalytics } from './lib/analytics.js';
 import { captureAuthSnapshot, nudgeFirstRun } from './lib/nudge.js';
+import { maybeCheckForUpdate } from './lib/update-check.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
 initAnalytics(pkg.version);
@@ -49,7 +50,7 @@ const program = new Command()
     .addHelpText('after', '\nRun `prave <cmd> --help` for command-specific options.');
 program
     .command('login')
-    .description('Authenticate this machine via device-code (browser opens, no password is ever typed). Tokens are saved chmod-600 to ~/.prave/credentials.json and refresh automatically.')
+    .description('Sign this machine in (browser opens, no password typed). Credentials are stored securely on disk and refreshed automatically.')
     .action(loginCommand);
 program
     .command('logout')
@@ -130,17 +131,17 @@ const usage = program
     .description('Track which Skills you actually use (powers the optimiser)');
 usage
     .command('report')
-    .description('Internal: invoked by the Claude Code PostToolUse / UserPromptSubmit hook (reads stdin)')
-    .option('--source <kind>', 'hook channel that fired this report ("tool" or "prompt")', 'tool')
+    .description('Internal: invoked by the agent when a Skill fires (reads payload from stdin)')
+    .option('--source <kind>', 'event channel that fired this report', 'tool')
     .action((opts) => usageReportCommand(opts));
-const hook = usage.command('hook').description('Install/uninstall the Claude Code real-time usage hook');
+const hook = usage.command('hook').description('Enable / disable real-time Skill invocation tracking');
 hook
     .command('install')
-    .description('Add a PostToolUse hook to ~/.claude/settings.json')
+    .description('Enable real-time invocation tracking for your installed Skills')
     .action(usageHookInstallCommand);
 hook
     .command('uninstall')
-    .description('Remove the Prave-managed hook from ~/.claude/settings.json')
+    .description('Disable real-time invocation tracking')
     .action(usageHookUninstallCommand);
 program
     .command('mcp-server')
@@ -188,7 +189,7 @@ program
         '  prave optimize --remove-unused     # delete 30d-silent skills from disk',
         '',
         'Usage tracking (Pro+)',
-        '  prave usage hook install           # real-time PostToolUse hook',
+        '  prave usage hook install           # enable real-time invocation tracking',
         '  prave usage hook uninstall',
         '',
         'Settings',
@@ -217,6 +218,19 @@ program.hook('preAction', async () => {
         /* never block the command on nudge bookkeeping */
     }
 });
+// Once-a-day npm update check. Most invocations short-circuit on the
+// 24-hour throttle stored in ~/.prave/config.json; when the throttle
+// has elapsed, a short fetch to the npm registry compares versions
+// and prints a one-line upgrade hint at the end of the command. Hard
+// 2-second timeout so a slow registry can never block the user.
+program.hook('postAction', async () => {
+    try {
+        await maybeCheckForUpdate(pkg.version);
+    }
+    catch {
+        /* nudges + update checks are decorative — never block on them */
+    }
+});
 // Global first-run banner. Fires once on the user's very first command
 // regardless of which one it was — catches commands that don't have a
 // per-action nudge wired in (e.g. `prave docs`, `prave conflicts`).

package/dist/lib/local-config.js

@@ -0,0 +1,44 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { CONFIG } from './config.js';
+/**
+ * Shared read / write for `~/.prave/config.json`.
+ *
+ * The same file holds three classes of state, all merged into one
+ * JSON object so callers can patch one key without clobbering the
+ * others:
+ *
+ *   • `agentSettings` — written by `prave settings`
+ *   • Nudge bookkeeping (`first_run`, `nudge_count`) — written by
+ *     the conversion-nudge module
+ *   • Onboarding flags (`agent_onboarding_done`) — written by
+ *     `prave login` so we only walk the user through the agent
+ *     picker once
+ *
+ * Previously each consumer reimplemented the same readFile / merge /
+ * writeFile dance — three copies in three files. Centralising here
+ * means a missing key in one consumer no longer wipes the keys
+ * another consumer just wrote.
+ */
+export async function readLocalConfig() {
+    try {
+        const raw = await readFile(CONFIG.configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge-write: reads the current config, shallow-merges `patch`, and
+ * writes the result. Creates `~/.prave/` with restrictive mode (0700)
+ * if it doesn't exist yet.
+ */
+export async function writeLocalConfigPatch(patch) {
+    const existing = await readLocalConfig();
+    const next = { ...existing, ...patch };
+    await mkdir(CONFIG.praveDir, { recursive: true, mode: 0o700 });
+    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
+}

package/dist/lib/nudge-constants.js

@@ -47,7 +47,7 @@ export const NUDGE_DEEP = {
     bullets: [
         'AI-generated descriptions for all your Skills',
         'Conflict detection across your library',
-        '30-day usage history from PostToolUse hook',
+        '30-day Skill invocation history',
         'Cross-machine sync',
     ],
     cta: 'prave.app/signup  ·  free forever  ·  10 seconds',

package/dist/lib/nudge.js

@@ -1,8 +1,27 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import chalk from 'chalk';
-import { CONFIG } from './config.js';
 import { loadCredentials } from './credentials.js';
+import { readLocalConfig, writeLocalConfigPatch } from './local-config.js';
 import { isAlwaysShow, NUDGE_FIRST_RUN, nudgeFor, } from './nudge-constants.js';
+/**
+ * Conversion nudges for anonymous CLI users.
+ *
+ * 4,300 npm-installs, 1 signed-in account. The CLI works for anonymous
+ * users by design (lower friction = more installs) but the handoff to
+ * the dashboard was missing. These nudges fix that.
+ *
+ * Rules baked in here, not in the call sites:
+ *   • Silent for signed-in users. Always.
+ *   • Soft nudges throttled to ~1 in every 3 commands via a counter
+ *     persisted to ~/.prave/config.json (`nudge_count`).
+ *   • Strong nudges (overview/whatdoes/first-run) bypass the throttle —
+ *     they're the highest-intent moments and worth a fuller pitch.
+ *   • First-run banner shows once on the user's very first command;
+ *     `first_run: false` then locks it down forever.
+ *   • One nudge per process. Multiple commands chained in a wrapper
+ *     script don't spam.
+ *   • Skipped when stdout isn't a TTY (piped output, CI) and when
+ *     PRAVE_QUIET=1 / PRAVE_TELEMETRY=0.
+ */
 let alreadyNudged = false;
 /**
  * Auth snapshot captured at command START, used at command END.
@@ -35,24 +54,6 @@ export async function isAuthenticated() {
     }
     return true;
 }
-async function readConfig() {
-    try {
-        const raw = await readFile(CONFIG.configPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object')
-            return parsed;
-        return {};
-    }
-    catch {
-        return {};
-    }
-}
-async function writeConfigPatch(patch) {
-    const existing = await readConfig();
-    const next = { ...existing, ...patch };
-    await mkdir(CONFIG.praveDir, { recursive: true, mode: 0o700 });
-    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
-}
 /**
  * Counter-based throttle for soft nudges. Reads the current count,
  * increments, persists, and returns true when (count % 3 === 0) — so
@@ -60,10 +61,10 @@ async function writeConfigPatch(patch) {
  * we'd rather skip than be loud on the user's first real command.
  */
 export async function shouldShowNudge() {
-    const cfg = await readConfig();
+    const cfg = await readLocalConfig();
     const current = typeof cfg.nudge_count === 'number' ? cfg.nudge_count : 0;
     const next = current + 1;
-    await writeConfigPatch({ nudge_count: next });
+    await writeLocalConfigPatch({ nudge_count: next });
     return next % 3 === 0;
 }
 /* --------------------------------------------------------------------- */
@@ -141,7 +142,7 @@ export async function nudgeFirstRun() {
     const startedAnon = wasAnonymousAtStart ?? !(await isAuthenticated());
     if (!startedAnon)
         return false;
-    const cfg = await readConfig();
+    const cfg = await readLocalConfig();
     // first_run defaults to "yes, show it" unless we've already flipped
     // the flag. A missing config file → first run.
     const alreadyShown = cfg.first_run === false;
@@ -149,7 +150,7 @@ export async function nudgeFirstRun() {
         return false;
     alreadyNudged = true;
     showNudge(NUDGE_FIRST_RUN);
-    await writeConfigPatch({ first_run: false });
+    await writeLocalConfigPatch({ first_run: false });
     return true;
 }
 /**

package/dist/lib/update-check.js

@@ -0,0 +1,129 @@
+import chalk from 'chalk';
+import { readLocalConfig, writeLocalConfigPatch } from './local-config.js';
+/**
+ * Once-a-day npm update check.
+ *
+ * A real "first command in a fresh terminal session" hook would need
+ * shell integration we don't ship. The user-visible behaviour is
+ * identical with a 24-hour timestamp throttle: the first `prave <cmd>`
+ * the user runs on any given day reaches out to npm, compares versions,
+ * and prints a one-line dim hint if a newer release exists. Subsequent
+ * commands inside the same window skip the network round-trip entirely.
+ *
+ * Rules:
+ *   • Hard cap on round-trip time (2 s). A slow npm registry must NEVER
+ *     block the user's command. The promise is fire-and-forget from the
+ *     caller's perspective — we always return cleanly.
+ *   • Skipped when stdout isn't a TTY (pipes, CI), or when
+ *     PRAVE_QUIET=1 / PRAVE_TELEMETRY=0 is set.
+ *   • The check itself runs through `node fetch` so we don't take a
+ *     dependency on a specific HTTP client (the CLI's `api.ts` is
+ *     auth-aware and overkill for a public, unauthenticated GET).
+ *   • Persists `last_update_check` (unix ms) in ~/.prave/config.json
+ *     regardless of outcome — a network blip is treated like a clean
+ *     "you're up to date" so we don't re-spam npm every command after
+ *     a failure.
+ */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const REQUEST_TIMEOUT_MS = 2_000;
+const NPM_PACKAGE = '@prave/cli';
+/**
+ * Returns true if the throttle has elapsed and we should hit npm now.
+ * Reads-and-writes the config so concurrent invocations from the same
+ * shell don't double-fire (last-write-wins is fine here).
+ */
+async function dueForCheck() {
+    const cfg = await readLocalConfig();
+    const last = typeof cfg.last_update_check === 'number' ? cfg.last_update_check : 0;
+    return Date.now() - last >= CHECK_INTERVAL_MS;
+}
+/**
+ * SemVer-ish comparator. Returns:
+ *   < 0  if a < b
+ *   0    if equal
+ *   > 0  if a > b
+ *
+ * Tolerates pre-release tails (`1.4.9-rc.1`) by lexicographically
+ * comparing them when the numeric tuples tie. Sufficient for the
+ * "newer is available" hint; we don't ship a strict semver library.
+ */
+function compareVersions(a, b) {
+    const [aNum, aPre = ''] = a.split('-', 2);
+    const [bNum, bPre = ''] = b.split('-', 2);
+    const aParts = aNum.split('.').map((n) => parseInt(n, 10));
+    const bParts = bNum.split('.').map((n) => parseInt(n, 10));
+    const length = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < length; i++) {
+        const x = aParts[i] ?? 0;
+        const y = bParts[i] ?? 0;
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return 0; // unparseable → treat as equal
+        if (x !== y)
+            return x - y;
+    }
+    // Numeric tuples equal — a release version > any pre-release of the
+    // same number ("1.4.9" > "1.4.9-rc.1"), and pre-releases sort by
+    // lexicographic order ("1.4.9-rc.1" < "1.4.9-rc.2").
+    if (aPre === bPre)
+        return 0;
+    if (!aPre)
+        return 1;
+    if (!bPre)
+        return -1;
+    return aPre < bPre ? -1 : 1;
+}
+async function fetchLatestVersion() {
+    // npm's registry returns the latest version in dist-tags without
+    // requiring an unauthenticated header; this is the same endpoint
+    // `npm view @prave/cli version` hits.
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(NPM_PACKAGE)}/dist-tags`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        return typeof json.latest === 'string' ? json.latest : null;
+    }
+    catch {
+        // Aborted, offline, registry down, JSON broken — treat as "no update".
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function printUpgradeNotice(current, latest) {
+    const rule = chalk.dim('─'.repeat(60));
+    console.log();
+    console.log(rule);
+    console.log(`${chalk.yellow('↑')}  ${chalk.bold('Prave CLI update available')}  ` +
+        `${chalk.dim(current)} ${chalk.dim('→')} ${chalk.green(latest)}`);
+    console.log(chalk.dim(`   Run  npm install -g ${NPM_PACKAGE}@latest`));
+    console.log(rule);
+}
+/**
+ * Public entry. Cheap to call: most invocations short-circuit on the
+ * throttle and don't touch the network. Caller is expected to `await`
+ * but the promise resolves quickly in the steady state.
+ */
+export async function maybeCheckForUpdate(currentVersion) {
+    if (!process.stdout.isTTY)
+        return;
+    if (process.env.PRAVE_QUIET === '1')
+        return;
+    if (process.env.PRAVE_TELEMETRY === '0')
+        return;
+    if (!(await dueForCheck()))
+        return;
+    // Record the attempt up-front so a network hang doesn't cause us to
+    // re-fire on every subsequent command before this one resolves.
+    await writeLocalConfigPatch({ last_update_check: Date.now() });
+    const latest = await fetchLatestVersion();
+    if (!latest)
+        return;
+    if (compareVersions(latest, currentVersion) <= 0)
+        return;
+    printUpgradeNotice(currentVersion, latest);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.4.9",
+  "version": "1.4.11",
   "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.4.9"
+    "@prave/shared": "1.4.11"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",