@prave/cli 1.5.1 → 1.6.0

package/dist/commands/hooks.js

@@ -0,0 +1,234 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { track } from '../lib/analytics.js';
+import { api, ApiError } from '../lib/api.js';
+import { requireAuth } from '../lib/credentials.js';
+import { detectCollisions, installRegistryHook, listForeignHooks, listRegistryHooks, removeRegistryHook, } from '../lib/hook.js';
+import { assertSlug, InvalidSlugError } from '../lib/slug.js';
+import { log } from '../utils/logger.js';
+/* ─── install ─────────────────────────────────────────────────── */
+export async function hooksInstallCommand(slug, opts = {}) {
+    track('cli_hooks_install', { slug, dry_run: !!opts.dryRun });
+    try {
+        assertSlug(slug);
+    }
+    catch (err) {
+        if (err instanceof InvalidSlugError) {
+            log.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    await requireAuth('hooks');
+    const spinner = ora(`Fetching hook ${chalk.cyan(slug)}…`).start();
+    let hook;
+    try {
+        const { data } = await api.get(`/api/v1/hooks/${encodeURIComponent(slug)}`);
+        hook = data;
+    }
+    catch (err) {
+        spinner.fail(`Hook ${chalk.cyan(slug)} not found`);
+        if (err instanceof ApiError && err.status !== 404)
+            log.error(err.message);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed(`Fetched ${chalk.cyan(hook.name)}`);
+    const def = {
+        slug: hook.slug,
+        event: hook.event,
+        matcher: hook.matcher,
+        command: hook.command,
+        timeout_seconds: hook.timeout_seconds,
+    };
+    const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+    if (opts.dryRun) {
+        printDryRunDiff(result.before, result.after);
+        log.info(`(dry-run) ${result.changed ? 'Would install' : 'No change needed for'} ${chalk.cyan(slug)}.`);
+        return;
+    }
+    if (!result.changed) {
+        log.info(`Already installed: ${chalk.cyan(slug)} — no change.`);
+        return;
+    }
+    // Record the install receipt so the dashboard count + trending sort
+    // stay accurate. Best-effort: a network blip here must not undo the
+    // local install.
+    try {
+        await api.post(`/api/v1/hooks/${encodeURIComponent(slug)}/install`, {}, true);
+    }
+    catch (err) {
+        log.warn(`Local install succeeded but server receipt failed: ${err.message}`);
+    }
+    log.success(`Installed ${chalk.cyan(slug)} → ${result.settingsPath}`);
+}
+/* ─── remove ──────────────────────────────────────────────────── */
+export async function hooksRemoveCommand(slug, opts = {}) {
+    track('cli_hooks_remove', { slug, dry_run: !!opts.dryRun });
+    try {
+        assertSlug(slug);
+    }
+    catch (err) {
+        if (err instanceof InvalidSlugError) {
+            log.error(err.message);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    const result = await removeRegistryHook(slug, { dryRun: opts.dryRun });
+    if (opts.dryRun) {
+        printDryRunDiff(result.before, result.after);
+        log.info(`(dry-run) ${result.changed ? 'Would remove' : 'No matching hook for'} ${chalk.cyan(slug)}.`);
+        return;
+    }
+    if (!result.changed) {
+        log.info(`No installed hook with slug ${chalk.cyan(slug)} — nothing to remove.`);
+        return;
+    }
+    log.success(`Removed ${chalk.cyan(slug)} from ${result.settingsPath}`);
+    // Soft uninstall on the server so the user's dashboard count drops.
+    try {
+        await requireAuth('hooks');
+        await api.del(`/api/v1/hooks/${encodeURIComponent(slug)}/install`, true);
+    }
+    catch {
+        /* offline / not logged in — local state is what matters */
+    }
+}
+/* ─── list ────────────────────────────────────────────────────── */
+export async function hooksListCommand() {
+    track('cli_hooks_list', {});
+    const installed = await listRegistryHooks();
+    if (installed.length === 0) {
+        log.info('No prave-managed hooks installed locally.');
+        return;
+    }
+    log.info(`${chalk.bold(installed.length)} prave-managed hook${installed.length === 1 ? '' : 's'} installed:\n`);
+    for (const h of installed) {
+        console.log(`  ${chalk.cyan(h.slug)}  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}` +
+            (h.timeout ? chalk.dim(`  (${h.timeout}s)`) : ''));
+        console.log(`    ${chalk.gray(h.command)}`);
+    }
+}
+/* ─── sync ────────────────────────────────────────────────────── */
+export async function hooksSyncCommand(opts = {}) {
+    track('cli_hooks_sync', { dry_run: !!opts.dryRun });
+    await requireAuth('hooks');
+    const installed = await listRegistryHooks();
+    if (installed.length === 0) {
+        log.info('No local prave-managed hooks to sync.');
+        return;
+    }
+    const slugs = installed.map((h) => h.slug);
+    const spinner = ora(`Syncing ${slugs.length} hook${slugs.length === 1 ? '' : 's'}…`).start();
+    let bulk;
+    try {
+        const { data } = await api.post('/api/v1/hooks/bulk/sync', { slugs }, true);
+        bulk = data;
+    }
+    catch (err) {
+        spinner.fail('Sync failed');
+        log.error(err.message);
+        process.exitCode = 1;
+        return;
+    }
+    spinner.succeed('Sync received');
+    let updated = 0;
+    for (const item of bulk.items) {
+        if (!item.hook)
+            continue;
+        const def = {
+            slug: item.hook.slug,
+            event: item.hook.event,
+            matcher: item.hook.matcher,
+            command: item.hook.command,
+            timeout_seconds: item.hook.timeout_seconds,
+        };
+        const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+        if (result.changed)
+            updated++;
+    }
+    if (bulk.missing.length) {
+        log.warn(`Skipped ${bulk.missing.length} unknown slug${bulk.missing.length === 1 ? '' : 's'}: ${bulk.missing.join(', ')}`);
+    }
+    log.success(`${opts.dryRun ? '(dry-run) ' : ''}Updated ${updated} of ${slugs.length} hook${slugs.length === 1 ? '' : 's'}.`);
+}
+/* ─── audit ───────────────────────────────────────────────────── */
+export async function hooksAuditCommand() {
+    track('cli_hooks_audit', {});
+    const installed = await listRegistryHooks();
+    const foreign = await listForeignHooks();
+    const collisions = detectCollisions(installed);
+    log.info(chalk.bold(`Prave-managed registry hooks: ${installed.length}`));
+    for (const h of installed) {
+        console.log(`  ${chalk.cyan(h.slug)}  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}`);
+    }
+    if (foreign.length) {
+        console.log();
+        log.info(chalk.bold(`User-owned hooks (untouched): ${foreign.length}`));
+        for (const h of foreign) {
+            console.log(`  ${chalk.dim(h.channel + (h.matcher ? `:${h.matcher}` : ''))}  ${chalk.gray(h.command)}`);
+        }
+    }
+    if (collisions.length) {
+        console.log();
+        log.warn(`${collisions.length} collision${collisions.length === 1 ? '' : 's'} detected — multiple registry hooks share an event+matcher pair:`);
+        for (const c of collisions) {
+            console.log(`  ${chalk.yellow(`${c.channel}:${c.matcher ?? '*'}`)}  →  ${c.slugs.map((s) => chalk.cyan(s)).join(', ')}`);
+        }
+    }
+    else {
+        console.log();
+        log.success('No collisions detected.');
+    }
+}
+/* ─── update ──────────────────────────────────────────────────── */
+export async function hooksUpdateCommand(slug, opts = {}) {
+    track('cli_hooks_update', { slug: slug ?? null, dry_run: !!opts.dryRun });
+    await requireAuth('hooks');
+    const installed = await listRegistryHooks();
+    const targets = slug ? installed.filter((h) => h.slug === slug) : installed;
+    if (targets.length === 0) {
+        log.info(slug ? `${chalk.cyan(slug)} is not installed.` : 'No installed registry hooks to update.');
+        return;
+    }
+    let updated = 0;
+    for (const local of targets) {
+        let remote;
+        try {
+            const { data } = await api.get(`/api/v1/hooks/${encodeURIComponent(local.slug)}`);
+            remote = data;
+        }
+        catch (err) {
+            log.warn(`Skipping ${chalk.cyan(local.slug)} — ${err.message}`);
+            continue;
+        }
+        const def = {
+            slug: remote.slug,
+            event: remote.event,
+            matcher: remote.matcher,
+            command: remote.command,
+            timeout_seconds: remote.timeout_seconds,
+        };
+        const result = await installRegistryHook(def, { dryRun: opts.dryRun });
+        if (result.changed) {
+            updated++;
+            log.info(`${opts.dryRun ? '(dry-run) ' : ''}Updated ${chalk.cyan(local.slug)} → v${remote.version}`);
+        }
+        else {
+            log.info(`${chalk.cyan(local.slug)} already current.`);
+        }
+    }
+    log.success(`${opts.dryRun ? '(dry-run) ' : ''}${updated} hook${updated === 1 ? '' : 's'} updated.`);
+}
+/* ─── helpers ─────────────────────────────────────────────────── */
+function printDryRunDiff(before, after) {
+    const b = JSON.stringify(before, null, 2);
+    const a = JSON.stringify(after, null, 2);
+    console.log(chalk.gray('--- before ---'));
+    console.log(chalk.red(b));
+    console.log(chalk.gray('--- after ---'));
+    console.log(chalk.green(a));
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { Command } from 'commander';
 import { conflictsCommand } from './commands/conflicts.js';
 import { diffCommand } from './commands/diff.js';
 import { docsCommand } from './commands/docs.js';
+import { hooksAuditCommand, hooksInstallCommand, hooksListCommand, hooksRemoveCommand, hooksSyncCommand, hooksUpdateCommand, } from './commands/hooks.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
@@ -144,6 +145,38 @@ hook
     .command('uninstall')
     .description('Disable real-time invocation tracking')
     .action(usageHookUninstallCommand);
+/* ─── Hooks Manager — discover, install, sync registry hooks ─── */
+const hooks = program
+    .command('hooks')
+    .description('Manage Claude Code hooks from the Prave registry (separate from `prave usage hook` which tracks Skill invocations)');
+hooks
+    .command('install <slug>')
+    .description('Install a registry hook into ~/.claude/settings.json')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksInstallCommand(slug, opts));
+hooks
+    .command('remove <slug>')
+    .description('Remove a registry hook (only the entry with this slug — never touches the tracking hook)')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksRemoveCommand(slug, opts));
+hooks
+    .command('list')
+    .description('List prave-managed registry hooks installed locally')
+    .action(hooksListCommand);
+hooks
+    .command('sync')
+    .description('Pull the latest content for every installed registry hook')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((opts) => hooksSyncCommand(opts));
+hooks
+    .command('audit')
+    .description('List installed registry + foreign hooks and flag collisions')
+    .action(hooksAuditCommand);
+hooks
+    .command('update [slug]')
+    .description('Refresh installed registry hooks against the server (one slug or all)')
+    .option('--dry-run', "Print the diff that would be applied, but don't write")
+    .action((slug, opts) => hooksUpdateCommand(slug, opts));
 program
     .command('mcp-server')
     .description('Run the Prave MCP server over stdio. Wire into Claude Desktop / Cursor MCP / Continue.dev via { "command": "npx", "args": ["-y", "@prave/cli", "mcp-server"] }. Exposes search, install, audit, my-skills, whatdoes as MCP tools.')

package/dist/lib/hook.js

@@ -14,6 +14,18 @@ import { dirname, join } from 'node:path';
  */
 const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
 const HOOK_MARKER = '__prave_managed';
+/**
+ * Per-entry slug marker added in the Hooks Manager (V1, migration
+ * 060). The tracking hook installed by `prave usage hook install`
+ * deliberately leaves this field undefined — every "registry" hook
+ * installed via `prave hooks install <slug>` stamps its slug here.
+ *
+ * That discrimination is what makes `prave hooks remove <slug>` safe:
+ * it only targets entries with a matching `__prave_slug`, so the
+ * tracking hook can never be removed by mistake. Tests in
+ * `hook.test.ts` pin this invariant.
+ */
+const HOOK_SLUG_MARKER = '__prave_slug';
 /**
  * Agents that currently support a real-time invocation hook. Adding a new
  * agent to this list means implementing its `installFor<Agent>` branch
@@ -21,6 +33,16 @@ const HOOK_MARKER = '__prave_managed';
  * misled about what's actually being instrumented.
  */
 export const HOOK_SUPPORTED = ['claude'];
+const REGISTRY_CHANNELS = [
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'SubagentStop',
+    'Notification',
+    'PreCompact',
+    'SessionStart',
+];
 const HOOK_COMMAND = 'prave usage report';
 // Companion command for the UserPromptSubmit channel so a typed-slash
 // `/graphify` is captured even when the Skill tool path doesn't fire a
@@ -127,7 +149,15 @@ export async function uninstallSkillHook() {
             return;
         const beforeCounts = blocks.map((b) => b.hooks?.length ?? 0);
         const filtered = blocks
-            .map((b) => ({ ...b, hooks: b.hooks?.filter((h) => !h[HOOK_MARKER]) }))
+            .map((b) => ({
+            ...b,
+            // ONLY strip tracking-hook entries — those with
+            // `__prave_managed: true` AND no `__prave_slug`. Registry hooks
+            // installed via `prave hooks install <slug>` carry a
+            // `__prave_slug` and are guarded here so this code path can
+            // never remove them by accident.
+            hooks: b.hooks?.filter((h) => !(h[HOOK_MARKER] && !h[HOOK_SLUG_MARKER])),
+        }))
             .filter((b) => (b.hooks?.length ?? 0) > 0);
         const lengthChanged = filtered.length !== blocks.length;
         const innerChanged = !lengthChanged &&
@@ -164,3 +194,179 @@ async function writeSettings(settings) {
     await mkdir(dirname(SETTINGS_PATH), { recursive: true });
     await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
 }
+/**
+ * Install / upsert a registry hook into `~/.claude/settings.json`.
+ * Read-modify-write is atomic-ish (single fs write) and guarded by
+ * the `__prave_slug` marker so we can:
+ *   • Update an existing entry for the same slug in-place.
+ *   • Never collide with the tracking hook (which has no slug
+ *     marker) or with a hand-written user hook (which has neither
+ *     marker).
+ *
+ * Returns the unified diff representation when `dryRun` is true so
+ * `prave hooks install --dry-run` can show what would change without
+ * actually writing.
+ */
+export async function installRegistryHook(def, opts = {}) {
+    const before = await readSettings();
+    // Defensive deep clone — operating on a copy keeps `before` clean
+    // for the diff output.
+    const after = JSON.parse(JSON.stringify(before));
+    after.hooks ??= {};
+    const channelBlocks = (after.hooks[def.event] ??= []);
+    const entry = {
+        type: 'command',
+        command: def.command,
+        [HOOK_MARKER]: true,
+        [HOOK_SLUG_MARKER]: def.slug,
+    };
+    if (def.timeout_seconds != null)
+        entry.timeout = def.timeout_seconds;
+    // Look for an existing block matching (channel, matcher) AND
+    // already carrying our slug. Upsert vs append accordingly.
+    const matcherKey = def.matcher ?? undefined;
+    const blockIdx = channelBlocks.findIndex((b) => (b.matcher ?? undefined) === matcherKey);
+    let changed = false;
+    if (blockIdx >= 0) {
+        const block = channelBlocks[blockIdx];
+        block.hooks ??= [];
+        const entryIdx = block.hooks.findIndex((h) => h[HOOK_SLUG_MARKER] === def.slug);
+        if (entryIdx >= 0) {
+            const prev = block.hooks[entryIdx];
+            if (prev.command !== entry.command || prev.timeout !== entry.timeout) {
+                block.hooks[entryIdx] = entry;
+                changed = true;
+            }
+        }
+        else {
+            block.hooks.push(entry);
+            changed = true;
+        }
+    }
+    else {
+        channelBlocks.push({
+            matcher: matcherKey,
+            hooks: [entry],
+        });
+        changed = true;
+    }
+    if (changed && !opts.dryRun)
+        await writeSettings(after);
+    return { changed, settingsPath: SETTINGS_PATH, before, after };
+}
+/**
+ * Remove the registry hook with the given slug. Filters by
+ * `__prave_slug === slug` so the tracking hook (no slug) and any
+ * foreign user hook (no marker) are NEVER touched.
+ */
+export async function removeRegistryHook(slug, opts = {}) {
+    const before = await readSettings();
+    const after = JSON.parse(JSON.stringify(before));
+    if (!after.hooks)
+        return { changed: false, settingsPath: SETTINGS_PATH, before, after };
+    let touched = false;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = after.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        const filtered = blocks
+            .map((b) => ({
+            ...b,
+            hooks: b.hooks?.filter((h) => h[HOOK_SLUG_MARKER] !== slug),
+        }))
+            .filter((b) => (b.hooks?.length ?? 0) > 0);
+        if (filtered.length !== blocks.length ||
+            filtered.some((b, i) => (b.hooks?.length ?? 0) !== (blocks[i]?.hooks?.length ?? 0))) {
+            touched = true;
+            if (after.hooks) {
+                if (filtered.length)
+                    after.hooks[channel] = filtered;
+                else
+                    delete after.hooks[channel];
+            }
+        }
+    }
+    if (after.hooks && Object.keys(after.hooks).length === 0)
+        delete after.hooks;
+    if (touched && !opts.dryRun)
+        await writeSettings(after);
+    return { changed: touched, settingsPath: SETTINGS_PATH, before, after };
+}
+/**
+ * Enumerate the registry hooks currently installed locally — used by
+ * `prave hooks list` and `prave hooks audit`.
+ */
+export async function listRegistryHooks() {
+    const settings = await readSettings();
+    const out = [];
+    if (!settings.hooks)
+        return out;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = settings.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        for (const b of blocks) {
+            for (const h of b.hooks ?? []) {
+                if (!h[HOOK_SLUG_MARKER])
+                    continue;
+                out.push({
+                    channel,
+                    matcher: b.matcher ?? null,
+                    slug: h[HOOK_SLUG_MARKER],
+                    command: h.command,
+                    timeout: h.timeout ?? null,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Foreign (user-authored) hooks living alongside our managed entries.
+ * Surfaced by `prave hooks audit` as informational context — never
+ * touched by any of the write helpers above.
+ */
+export async function listForeignHooks() {
+    const settings = await readSettings();
+    const out = [];
+    if (!settings.hooks)
+        return out;
+    for (const channel of REGISTRY_CHANNELS) {
+        const blocks = settings.hooks[channel];
+        if (!blocks?.length)
+            continue;
+        for (const b of blocks) {
+            for (const h of b.hooks ?? []) {
+                if (h[HOOK_MARKER])
+                    continue;
+                out.push({ channel, matcher: b.matcher ?? null, command: h.command });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Detect duplicate-coverage collisions inside the registry: two
+ * different prave-managed slugs writing to the same
+ * (channel, matcher) pair. The audit command surfaces these so the
+ * user can manually decide which one to keep.
+ */
+export function detectCollisions(installed) {
+    const buckets = new Map();
+    for (const h of installed) {
+        const key = `${h.channel}|${h.matcher ?? '*'}`;
+        const list = buckets.get(key) ?? [];
+        list.push(h.slug);
+        buckets.set(key, list);
+    }
+    const out = [];
+    for (const [key, slugs] of buckets) {
+        if (slugs.length < 2)
+            continue;
+        const parts = key.split('|');
+        const channel = parts[0];
+        const matcher = parts[1] === '*' ? null : (parts[1] ?? null);
+        out.push({ channel, matcher, slugs });
+    }
+    return out;
+}

package/package.json

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