@prave/cli 0.4.10 → 1.0.0

package/dist/lib/hook.js

@@ -0,0 +1,131 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Real-time usage hook installer. Currently only Claude Code exposes a
+ * suitable hook contract (`PostToolUse` with stdin payload) — the other
+ * supported agents (Codex, Cursor, Gemini, Cline, Amp) don't yet ship
+ * a comparable mechanism, so for those we degrade gracefully and let
+ * the transcript scanner cover them once they do.
+ *
+ * The Claude block is wrapped with sentinel keys (`__prave_managed: true`)
+ * so the uninstaller can find and remove only the Prave entry without
+ * disturbing user-authored hooks. Idempotent: re-installing just refreshes.
+ */
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+const HOOK_MARKER = '__prave_managed';
+/**
+ * Agents that currently support a real-time invocation hook. Adding a new
+ * agent to this list means implementing its `installFor<Agent>` branch
+ * below; until then we surface "not yet supported" so users are never
+ * misled about what's actually being instrumented.
+ */
+export const HOOK_SUPPORTED = ['claude'];
+const HOOK_COMMAND = 'prave usage report';
+export async function installSkillHook() {
+    const settings = await readSettings();
+    settings.hooks ??= {};
+    settings.hooks.PostToolUse ??= [];
+    const blocks = settings.hooks.PostToolUse;
+    const existingIdx = blocks.findIndex((b) => b.matcher === 'Skill' && b.hooks?.some((h) => h[HOOK_MARKER]));
+    const fresh = {
+        matcher: 'Skill',
+        hooks: [{ type: 'command', command: HOOK_COMMAND, [HOOK_MARKER]: true }],
+    };
+    if (existingIdx >= 0) {
+        const existingCmd = blocks[existingIdx]?.hooks?.[0]?.command;
+        if (existingCmd === HOOK_COMMAND) {
+            return { installed: false, alreadyPresent: true, settingsPath: SETTINGS_PATH };
+        }
+        blocks[existingIdx] = fresh;
+    }
+    else {
+        blocks.push(fresh);
+    }
+    await writeSettings(settings);
+    return { installed: true, alreadyPresent: false, settingsPath: SETTINGS_PATH };
+}
+export async function installHooksForAgents(agents) {
+    const out = [];
+    for (const agent of agents) {
+        if (!HOOK_SUPPORTED.includes(agent)) {
+            out.push({
+                agent,
+                status: 'unsupported',
+                message: `${agent} doesn't expose a real-time hook contract yet — transcript scanner via \`prave sync\` will track usage when supported.`,
+            });
+            continue;
+        }
+        try {
+            const result = await installSkillHook();
+            out.push({
+                agent,
+                status: result.alreadyPresent ? 'already' : 'installed',
+                message: result.settingsPath,
+            });
+        }
+        catch (err) {
+            out.push({ agent, status: 'error', message: err.message });
+        }
+    }
+    return out;
+}
+export async function uninstallHooksForAgents(agents) {
+    const out = [];
+    for (const agent of agents) {
+        if (!HOOK_SUPPORTED.includes(agent)) {
+            out.push({ agent, status: 'unsupported' });
+            continue;
+        }
+        try {
+            const result = await uninstallSkillHook();
+            out.push({
+                agent,
+                status: result.removed ? 'installed' : 'already',
+                message: result.settingsPath,
+            });
+        }
+        catch (err) {
+            out.push({ agent, status: 'error', message: err.message });
+        }
+    }
+    return out;
+}
+export async function uninstallSkillHook() {
+    const settings = await readSettings();
+    const blocks = settings.hooks?.PostToolUse;
+    if (!blocks?.length)
+        return { removed: false, settingsPath: SETTINGS_PATH };
+    const before = blocks.length;
+    const filtered = blocks
+        .map((b) => ({
+        ...b,
+        hooks: b.hooks?.filter((h) => !h[HOOK_MARKER]),
+    }))
+        .filter((b) => (b.hooks?.length ?? 0) > 0);
+    if (filtered.length === before && filtered.every((b, i) => b.hooks?.length === blocks[i]?.hooks?.length)) {
+        return { removed: false, settingsPath: SETTINGS_PATH };
+    }
+    if (settings.hooks) {
+        settings.hooks.PostToolUse = filtered;
+        if (!filtered.length)
+            delete settings.hooks.PostToolUse;
+        if (Object.keys(settings.hooks).length === 0)
+            delete settings.hooks;
+    }
+    await writeSettings(settings);
+    return { removed: true, settingsPath: SETTINGS_PATH };
+}
+async function readSettings() {
+    try {
+        const raw = await readFile(SETTINGS_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeSettings(settings) {
+    await mkdir(dirname(SETTINGS_PATH), { recursive: true });
+    await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
+}

package/dist/lib/prompt.js

@@ -0,0 +1,124 @@
+import { stdin, stdout } from 'node:process';
+import readline from 'node:readline';
+import chalk from 'chalk';
+export async function checkboxPrompt(question, items, opts = {}) {
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return fallbackPrompt(question, items, opts);
+    }
+    const selected = new Set(opts.initial ?? []);
+    let cursor = 0;
+    const minSelected = opts.minSelected ?? 0;
+    const cleanup = () => {
+        if (typeof stdin.setRawMode === 'function')
+            stdin.setRawMode(false);
+        stdin.removeAllListeners('keypress');
+        stdin.pause();
+        stdout.write(showCursor);
+    };
+    return new Promise((resolve) => {
+        readline.emitKeypressEvents(stdin);
+        if (typeof stdin.setRawMode === 'function')
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdout.write(hideCursor);
+        let firstRender = true;
+        const render = () => {
+            if (!firstRender) {
+                // Move cursor up to the start of our last render and erase down.
+                stdout.write(`\x1b[${items.length + 2}A`);
+                stdout.write('\x1b[J');
+            }
+            firstRender = false;
+            stdout.write(`${chalk.bold(question)}  ${chalk.dim('(space=toggle, a=all, enter=confirm, esc=cancel)')}\n`);
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const isCursor = i === cursor;
+                const isSelected = selected.has(item.value);
+                const box = isSelected ? chalk.green('◉') : chalk.dim('◯');
+                const arrow = isCursor ? chalk.cyan('›') : ' ';
+                const label = isCursor ? chalk.cyan(item.label) : item.label;
+                const hint = item.hint ? chalk.dim(`  — ${item.hint}`) : '';
+                stdout.write(`${arrow} ${box} ${label}${hint}\n`);
+            }
+            const ok = selected.size >= minSelected;
+            stdout.write(`${chalk.dim(ok
+                ? `${selected.size} selected · enter to confirm`
+                : `at least ${minSelected} required · ${selected.size} selected`)}\n`);
+        };
+        const onKey = (_str, key) => {
+            if (!key)
+                return;
+            if (key.ctrl && key.name === 'c') {
+                cleanup();
+                resolve(null);
+                return;
+            }
+            switch (key.name) {
+                case 'up':
+                case 'k':
+                    cursor = (cursor - 1 + items.length) % items.length;
+                    break;
+                case 'down':
+                case 'j':
+                    cursor = (cursor + 1) % items.length;
+                    break;
+                case 'space': {
+                    const v = items[cursor].value;
+                    if (selected.has(v))
+                        selected.delete(v);
+                    else
+                        selected.add(v);
+                    break;
+                }
+                case 'a':
+                    if (selected.size === items.length)
+                        selected.clear();
+                    else
+                        for (const i of items)
+                            selected.add(i.value);
+                    break;
+                case 'return':
+                    if (selected.size < minSelected)
+                        return;
+                    cleanup();
+                    resolve([...selected]);
+                    return;
+                case 'escape':
+                case 'q':
+                    cleanup();
+                    resolve(null);
+                    return;
+            }
+            render();
+        };
+        stdin.on('keypress', onKey);
+        render();
+    });
+}
+const hideCursor = '\x1b[?25l';
+const showCursor = '\x1b[?25h';
+async function fallbackPrompt(question, items, opts) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write(`${question}\n`);
+        for (const i of items) {
+            stdout.write(`  - ${i.value}${i.label !== i.value ? ` (${i.label})` : ''}${i.hint ? `  — ${i.hint}` : ''}\n`);
+        }
+        const def = (opts.initial ?? []).join(',');
+        const ans = (await rl.question(`Comma-separated values${def ? ` [${def}]` : ''}: `)).trim();
+        if (!ans && opts.initial)
+            return [...opts.initial];
+        if (!ans)
+            return [];
+        const valid = new Set(items.map((i) => i.value));
+        const tokens = ans
+            .split(',')
+            .map((s) => s.trim())
+            .filter((t) => valid.has(t));
+        return tokens;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/usage-cursor.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CONFIG } from './config.js';
+/**
+ * Persistent watermark for the transcript scanner. Without it every
+ * `prave usage scan` would re-walk every JSONL we've ever recorded; with
+ * it we only re-process files modified since the last successful scan.
+ *
+ * Stored at `~/.prave/usage-cursor.json` (plain text, no secrets) so it
+ * survives across CLI versions and machine reboots.
+ */
+const CURSOR_PATH = join(CONFIG.praveDir, 'usage-cursor.json');
+export async function loadCursor() {
+    try {
+        const raw = await readFile(CURSOR_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.lastScanAt) {
+            const ms = Date.parse(parsed.lastScanAt);
+            if (!Number.isNaN(ms))
+                return new Date(ms);
+        }
+    }
+    catch {
+        /* fall through to default */
+    }
+    // First run: look back 30 days. Matches the optimiser's "30+ days
+    // unused" window so the very first scan can fully populate it.
+    return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+}
+export async function saveCursor(at = new Date()) {
+    await mkdir(dirname(CURSOR_PATH), { recursive: true });
+    const state = { lastScanAt: at.toISOString() };
+    await writeFile(CURSOR_PATH, JSON.stringify(state, null, 2), 'utf8');
+}

package/dist/lib/usage-scanner.js

@@ -0,0 +1,154 @@
+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.
+ *
+ * @param installedSlugs the slugs we recognise — anything outside this
+ *  set is ignored to avoid noise from quoted text.
+ * @param since lower bound for transcript modification time. Defaults
+ *  to 30 days ago on a fresh run; the CLI persists a watermark in
+ *  `~/.prave/usage-cursor.json` so subsequent runs only re-scan recent
+ *  transcripts.
+ */
+export async function scanTranscriptsForUsage(installedSlugs, since) {
+    if (!installedSlugs.length)
+        return [];
+    const slugSet = new Set(installedSlugs);
+    const sinceMs = since.getTime();
+    const events = [];
+    const projectDirs = await safeReaddir(PROJECTS_DIR);
+    for (const projectName of projectDirs) {
+        const projectDir = join(PROJECTS_DIR, projectName);
+        const projectStat = await safeStat(projectDir);
+        if (!projectStat?.isDirectory())
+            continue;
+        const files = await safeReaddir(projectDir);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const path = join(projectDir, file);
+            const fileStat = await safeStat(path);
+            if (!fileStat || fileStat.mtimeMs < sinceMs)
+                continue;
+            try {
+                const raw = await readFile(path, 'utf8');
+                const lines = raw.split('\n');
+                for (const line of lines) {
+                    if (!line)
+                        continue;
+                    extractEventsFromLine(line, slugSet, sinceMs, events);
+                }
+            }
+            catch {
+                // Skip unreadable / corrupt JSONLs silently.
+            }
+        }
+    }
+    return events;
+}
+const COMMAND_NAME_RE = /<command-name>\s*\/?([a-z0-9][a-z0-9_-]{0,80})\s*<\/command-name>/gi;
+/**
+ * Per-line extractor. The transcript is one JSON object per line, but
+ * we don't always need to parse the whole thing — slash commands land in
+ * the `<command-name>` string and a regex hit on the raw line is enough.
+ *
+ * For the canonical Skill-tool path we DO parse (only when the line
+ * actually mentions `"name":"Skill"`, so the parse cost stays bounded).
+ */
+function extractEventsFromLine(line, slugSet, sinceMs, out) {
+    // Slash-command hits — cheap and don't require JSON.parse.
+    let m;
+    COMMAND_NAME_RE.lastIndex = 0;
+    while ((m = COMMAND_NAME_RE.exec(line))) {
+        const slug = m[1]?.toLowerCase();
+        if (!slug || !slugSet.has(slug))
+            continue;
+        const ts = sniffTimestamp(line, sinceMs);
+        if (!ts)
+            continue;
+        out.push({ slug, triggered_at: ts, trigger_phrase: `/${slug}` });
+    }
+    // Skill tool invocations — only parse when the line claims to have one.
+    if (!line.includes('"name":"Skill"'))
+        return;
+    try {
+        const obj = JSON.parse(line);
+        walkForSkillToolUse(obj, slugSet, sinceMs, out);
+    }
+    catch {
+        // Malformed line — ignore.
+    }
+}
+function walkForSkillToolUse(node, slugSet, sinceMs, out) {
+    if (!node)
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkForSkillToolUse(item, slugSet, sinceMs, out);
+        return;
+    }
+    if (typeof node !== 'object')
+        return;
+    const obj = node;
+    // Detect a tool_use block at any level.
+    const block = obj;
+    if (block.type === 'tool_use' && block.name === 'Skill' && block.input?.skill) {
+        const slug = String(block.input.skill).toLowerCase().split(':').pop() ?? '';
+        if (slug && slugSet.has(slug)) {
+            const ts = sniffTimestampFromObject(obj, sinceMs);
+            if (ts)
+                out.push({ slug, triggered_at: ts, trigger_phrase: null });
+        }
+    }
+    // Recurse into known transcript fields. We don't blindly walk every
+    // value — that would re-parse user-prompt text trees we explicitly
+    // committed to NOT inspecting.
+    for (const key of ['message', 'content', 'children', 'tool_use', 'tool_results']) {
+        const child = obj[key];
+        if (child)
+            walkForSkillToolUse(child, slugSet, sinceMs, out);
+    }
+}
+/**
+ * Best-effort timestamp recovery from a JSONL line. Claude Code stamps
+ * each line with `"timestamp":"<iso>"` at the top level. If we can't
+ * find one, we drop the event (we'd rather lose a record than mis-date
+ * one).
+ */
+function sniffTimestamp(line, sinceMs) {
+    const match = /"timestamp"\s*:\s*"([^"]+)"/.exec(line);
+    if (!match)
+        return null;
+    const ts = match[1];
+    const ms = Date.parse(ts);
+    if (Number.isNaN(ms) || ms < sinceMs)
+        return null;
+    return ts;
+}
+function sniffTimestampFromObject(obj, sinceMs) {
+    const ts = obj.timestamp;
+    if (typeof ts !== 'string')
+        return null;
+    const ms = Date.parse(ts);
+    if (Number.isNaN(ms) || ms < sinceMs)
+        return null;
+    return ts;
+}
+async function safeReaddir(path) {
+    try {
+        return await readdir(path);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeStat(path) {
+    try {
+        return await stat(path);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

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