@byterover/claude-plugin 1.0.0

package/dist/commands/doctor.js

@@ -0,0 +1,150 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+import pc from "picocolors";
+import { isBridgeHook, resolveBridgeExecutable } from "../bridge-command.js";
+import { getCcMemoryDir, getClaudeConfigHome } from "../memory-path.js";
+import { readSettingsRaw } from "../schemas/cc-settings.js";
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Check that the bridge is correctly configured")
+        .action(async () => {
+        const cwd = process.cwd();
+        const results = [];
+        // 1. brv CLI found
+        try {
+            const version = execSync("brv --version", {
+                encoding: "utf-8",
+                timeout: 5_000,
+            }).trim();
+            results.push({ label: "brv CLI", pass: true, detail: version });
+        }
+        catch {
+            results.push({
+                label: "brv CLI",
+                pass: false,
+                detail: "not found in PATH",
+            });
+        }
+        // 2. .brv/context-tree/ exists
+        const ctPath = join(cwd, ".brv", "context-tree");
+        results.push({
+            label: "Context tree",
+            pass: existsSync(ctPath),
+            detail: existsSync(ctPath) ? ctPath : `${ctPath} not found`,
+        });
+        // 3. Settings file exists and is valid JSON
+        const settingsPath = join(getClaudeConfigHome(), "settings.json");
+        let settingsValid = false;
+        try {
+            readSettingsRaw(settingsPath);
+            settingsValid = existsSync(settingsPath);
+        }
+        catch {
+            settingsValid = false;
+        }
+        results.push({
+            label: "Claude settings",
+            pass: settingsValid,
+            detail: settingsValid ? settingsPath : `${settingsPath} missing or invalid`,
+        });
+        // 4. Bridge hooks installed
+        if (settingsValid) {
+            const settings = readSettingsRaw(settingsPath);
+            const hooks = settings.hooks;
+            const hasPostToolUse = findBridgeHookInEvent(hooks, "PostToolUse");
+            const hasStop = findBridgeHookInEvent(hooks, "Stop");
+            const hasUserPrompt = findBridgeHookInEvent(hooks, "UserPromptSubmit");
+            const installed = hasPostToolUse && hasStop && hasUserPrompt;
+            results.push({
+                label: "Bridge hooks",
+                pass: installed,
+                detail: installed
+                    ? "PostToolUse + Stop + UserPromptSubmit hooks found"
+                    : `missing: ${[
+                        !hasPostToolUse && "PostToolUse",
+                        !hasStop && "Stop",
+                        !hasUserPrompt && "UserPromptSubmit",
+                    ]
+                        .filter(Boolean)
+                        .join(", ")}`,
+            });
+        }
+        else {
+            results.push({
+                label: "Bridge hooks",
+                pass: false,
+                detail: "cannot check — settings invalid",
+            });
+        }
+        // 5. Bridge executable resolves
+        try {
+            const exe = resolveBridgeExecutable();
+            results.push({
+                label: "Bridge executable",
+                pass: true,
+                detail: exe,
+            });
+        }
+        catch (err) {
+            results.push({
+                label: "Bridge executable",
+                pass: false,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        // 6. cc memory dir resolves
+        try {
+            const memDir = getCcMemoryDir(cwd);
+            const memExists = existsSync(memDir);
+            results.push({
+                label: "Memory directory",
+                pass: memExists,
+                detail: memExists
+                    ? memDir
+                    : `${memDir} (resolved but does not exist yet — will be created on first Claude session)`,
+            });
+        }
+        catch (err) {
+            results.push({
+                label: "Memory directory",
+                pass: false,
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+        // Print results
+        console.log(pc.bold("\nbrv-claude-plugin doctor\n"));
+        let allPass = true;
+        for (const r of results) {
+            const icon = r.pass ? pc.green("\u2713") : pc.red("\u2717");
+            const detail = r.detail ? pc.dim(` — ${r.detail}`) : "";
+            console.log(`  ${icon} ${r.label}${detail}`);
+            if (!r.pass)
+                allPass = false;
+        }
+        console.log();
+        if (allPass) {
+            console.log(pc.green("All checks passed."));
+        }
+        else {
+            console.log(pc.yellow("Some checks failed. Run 'brv-claude-plugin install' to set up."));
+        }
+    });
+}
+function findBridgeHookInEvent(hooks, event) {
+    if (!hooks)
+        return false;
+    const eventHooks = hooks[event];
+    if (!Array.isArray(eventHooks))
+        return false;
+    return eventHooks.some((entry) => {
+        const innerHooks = entry.hooks;
+        if (!Array.isArray(innerHooks))
+            return false;
+        return innerHooks.some((h) => typeof h === "object" &&
+            h !== null &&
+            isBridgeHook(h));
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/ingest.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerIngestCommand(program: Command): void;

package/dist/commands/ingest.js

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { BrvBridge } from "@byterover/brv-bridge";
+import { parseCcMemoryFile } from "../cc-frontmatter.js";
+import { getCcMemoryDir, isCcMemoryPath } from "../memory-path.js";
+import { PostToolUseHookInputSchema } from "../schemas/cc-hook-input.js";
+import { readStdinJson } from "../stdin.js";
+// Files in the memory dir that we should never ingest
+const SKIP_FILES = new Set(["MEMORY.md", "_brv_context.md"]);
+export function registerIngestCommand(program) {
+    program
+        .command("ingest")
+        .description("Ingest a Claude Code memory file into ByteRover context tree (called by PostToolUse hook)")
+        .option("--json", "Output result as JSON")
+        .action(async (opts) => {
+        try {
+            const input = await readStdinJson(PostToolUseHookInputSchema);
+            const toolInput = input.tool_input;
+            const filePath = toolInput.file_path;
+            const toolName = input.tool_name;
+            const cwd = input.cwd;
+            if (!filePath || typeof filePath !== "string") {
+                exit(opts, { ingested: false, reason: "no file_path in tool_input" });
+                return;
+            }
+            // Guard: only process files in cc memory directory
+            const memoryDir = getCcMemoryDir(cwd);
+            if (!isCcMemoryPath(filePath, memoryDir)) {
+                exit(opts, { ingested: false, reason: "not a memory path" });
+                return;
+            }
+            // Guard: skip index and our own file
+            const fileName = basename(filePath);
+            if (SKIP_FILES.has(fileName)) {
+                exit(opts, { ingested: false, reason: `skipped ${fileName}` });
+                return;
+            }
+            // Get file content based on tool type
+            let content;
+            if (toolName === "Write") {
+                // Write tool: content is in tool_input
+                const rawContent = toolInput.content;
+                if (typeof rawContent !== "string") {
+                    exit(opts, { ingested: false, reason: "no content in Write input" });
+                    return;
+                }
+                content = rawContent;
+            }
+            else if (toolName === "Edit") {
+                // Edit tool: only has old_string/new_string — read from disk
+                try {
+                    content = readFileSync(filePath, "utf-8");
+                }
+                catch {
+                    exit(opts, {
+                        ingested: false,
+                        reason: `cannot read file after Edit: ${filePath}`,
+                    });
+                    return;
+                }
+            }
+            else {
+                exit(opts, { ingested: false, reason: `unexpected tool: ${toolName}` });
+                return;
+            }
+            // Parse cc-ts frontmatter
+            const parsed = parseCcMemoryFile(content);
+            if (!parsed) {
+                exit(opts, {
+                    ingested: false,
+                    reason: "invalid cc-ts memory frontmatter",
+                });
+                return;
+            }
+            const { frontmatter, body } = parsed;
+            // Pass content to brv curate without path constraints.
+            // Let ByteRover's agent decide the best domain/topic structure.
+            const curateContext = body.trim();
+            // Fire-and-forget curate
+            const bridge = new BrvBridge({ cwd, persistTimeoutMs: 15_000 });
+            await bridge.persist(curateContext);
+            exit(opts, {
+                ingested: true,
+                name: frontmatter.name,
+                type: frontmatter.type,
+            });
+        }
+        catch (err) {
+            // All errors → stderr + exit 0. Never exit 2 (would block Claude).
+            process.stderr.write(`brv-claude-plugin ingest error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(0);
+        }
+    });
+}
+function exit(opts, result) {
+    if (opts.json) {
+        console.log(JSON.stringify(result));
+    }
+    process.exit(0);
+}
+//# sourceMappingURL=ingest.js.map

package/dist/commands/install.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInstallCommand(program: Command): void;

package/dist/commands/install.js

@@ -0,0 +1,130 @@
+import { join } from "node:path";
+import pc from "picocolors";
+import { buildHookCommand, isBridgeHook, resolveBridgeExecutable, } from "../bridge-command.js";
+import { getClaudeConfigHome } from "../memory-path.js";
+import { backupSettings, readSettingsRaw, writeSettingsRaw, } from "../schemas/cc-settings.js";
+// The hook entries we want to install
+function buildDesiredHooks() {
+    return [
+        {
+            event: "PostToolUse",
+            entry: {
+                matcher: "Write",
+                hooks: [
+                    {
+                        type: "command",
+                        command: buildHookCommand("ingest"),
+                        async: true,
+                        timeout: 15,
+                    },
+                ],
+            },
+        },
+        {
+            event: "PostToolUse",
+            entry: {
+                matcher: "Edit",
+                hooks: [
+                    {
+                        type: "command",
+                        command: buildHookCommand("ingest"),
+                        async: true,
+                        timeout: 15,
+                    },
+                ],
+            },
+        },
+        {
+            event: "Stop",
+            entry: {
+                hooks: [
+                    {
+                        type: "command",
+                        command: buildHookCommand("sync"),
+                        async: true,
+                        timeout: 10,
+                    },
+                ],
+            },
+        },
+        {
+            event: "UserPromptSubmit",
+            entry: {
+                hooks: [
+                    {
+                        type: "command",
+                        command: buildHookCommand("recall"),
+                        timeout: 8,
+                    },
+                ],
+            },
+        },
+    ];
+}
+export function registerInstallCommand(program) {
+    program
+        .command("install")
+        .description("Install Claude Code hooks that bridge auto-memory to ByteRover context tree")
+        .option("--dry-run", "Show what would be written without modifying files")
+        .option("--settings-path <path>", "Override path to Claude Code settings.json")
+        .action(async (opts) => {
+        try {
+            // Validate executable resolves before touching settings
+            const exe = resolveBridgeExecutable();
+            console.log(pc.dim(`Resolved executable: ${exe}`));
+            const settingsPath = opts.settingsPath ??
+                join(getClaudeConfigHome(), "settings.json");
+            const settings = readSettingsRaw(settingsPath);
+            // Ensure hooks object exists
+            if (!settings.hooks || typeof settings.hooks !== "object") {
+                settings.hooks = {};
+            }
+            const hooks = settings.hooks;
+            const desired = buildDesiredHooks();
+            let added = 0;
+            for (const { event, entry } of desired) {
+                if (!Array.isArray(hooks[event])) {
+                    hooks[event] = [];
+                }
+                const eventHooks = hooks[event];
+                // Per-hook dedupe: check if any existing matcher entry with the
+                // same matcher value already contains a bridge hook
+                const matcherValue = "matcher" in entry ? entry.matcher : undefined;
+                const alreadyInstalled = eventHooks.some((existing) => {
+                    const existingMatcher = existing.matcher;
+                    if (existingMatcher !== matcherValue)
+                        return false;
+                    const innerHooks = existing.hooks;
+                    if (!Array.isArray(innerHooks))
+                        return false;
+                    return innerHooks.some((h) => typeof h === "object" &&
+                        h !== null &&
+                        isBridgeHook(h));
+                });
+                if (!alreadyInstalled) {
+                    eventHooks.push(entry);
+                    added++;
+                }
+            }
+            if (added === 0) {
+                console.log(pc.yellow("Bridge hooks already installed. No changes made."));
+                return;
+            }
+            if (opts.dryRun) {
+                console.log(pc.cyan("Dry run — would write:"));
+                console.log(JSON.stringify(settings, null, 2));
+                return;
+            }
+            const backupPath = backupSettings(settingsPath);
+            console.log(pc.dim(`Backup: ${backupPath}`));
+            writeSettingsRaw(settingsPath, settings);
+            console.log(pc.green(`Installed ${added} hook(s) into ${settingsPath}`));
+            console.log(pc.dim("Hooks: PostToolUse(Write), PostToolUse(Edit), Stop"));
+        }
+        catch (err) {
+            console.error(pc.red(`Install failed: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=install.js.map

package/dist/commands/recall.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerRecallCommand(program: Command): void;

package/dist/commands/recall.js

@@ -0,0 +1,41 @@
+import { BrvBridge } from "@byterover/brv-bridge";
+import { UserPromptSubmitHookInputSchema } from "../schemas/cc-hook-input.js";
+import { readStdinJson } from "../stdin.js";
+export function registerRecallCommand(program) {
+    program
+        .command("recall")
+        .description("Query ByteRover for context relevant to the user prompt (called by UserPromptSubmit hook)")
+        .action(async () => {
+        try {
+            const input = await readStdinJson(UserPromptSubmitHookInputSchema);
+            const { prompt, cwd } = input;
+            // Skip trivially short prompts
+            if (prompt.trim().length < 5) {
+                process.exit(0);
+            }
+            // Query ByteRover with the actual user prompt
+            const bridge = new BrvBridge({ cwd, recallTimeoutMs: 6_000 });
+            const { content } = await bridge.recall(prompt);
+            if (!content) {
+                process.exit(0);
+            }
+            // Return additionalContext wrapped in hookSpecificOutput for Claude Code
+            const output = {
+                hookSpecificOutput: {
+                    hookEventName: "UserPromptSubmit",
+                    additionalContext: `<byterover-context>\n` +
+                        `The following knowledge is from ByteRover context engine:\n\n` +
+                        `${content}\n` +
+                        `</byterover-context>`,
+                },
+            };
+            console.log(JSON.stringify(output));
+            process.exit(0);
+        }
+        catch {
+            // All errors → silent exit 0. Never block the prompt.
+            process.exit(0);
+        }
+    });
+}
+//# sourceMappingURL=recall.js.map

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSyncCommand(program: Command): void;

package/dist/commands/sync.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getCcMemoryDir } from "../memory-path.js";
+import { StopHookInputSchema } from "../schemas/cc-hook-input.js";
+import { readStdinJson } from "../stdin.js";
+const BRV_CONTEXT_FILE = "_brv_context.md";
+const CONTEXT_TREE_INDEX = ".brv/context-tree/_index.md";
+const MEMORY_INDEX = "MEMORY.md";
+const POINTER_LINE = "- [ByteRover context](_brv_context.md) \u2014 cross-references from project knowledge base";
+function buildContextTreeGuide(cwd) {
+    const treePath = join(cwd, ".brv/context-tree");
+    return [
+        "<Note>",
+        `The full ByteRover context tree is located at \`${treePath}/\`.`,
+        "All paths referenced below are relative to this directory.",
+        "When you need deeper context on any topic, read the relevant files there.",
+        "Each domain contains topics with detailed narratives, facts, and code references that go beyond this summary.",
+        "</Note>",
+    ].join("\n");
+}
+/**
+ * Strip YAML frontmatter (--- ... ---) from the beginning of a markdown string.
+ * Returns the body content after the closing --- delimiter.
+ */
+function stripFrontmatter(content) {
+    const match = content.match(/^---\n[\s\S]*?\n---\n?/);
+    if (match) {
+        return content.slice(match[0].length);
+    }
+    return content;
+}
+export function registerSyncCommand(program) {
+    program
+        .command("sync")
+        .description("Regenerate _brv_context.md with cross-references from ByteRover context tree (called by Stop hook)")
+        .option("--json", "Output result as JSON")
+        .option("--memory-dir <path>", "Override path to Claude Code memory directory")
+        .action(async (opts) => {
+        try {
+            const input = await readStdinJson(StopHookInputSchema);
+            const cwd = input.cwd;
+            const memoryDir = opts.memoryDir ?? getCcMemoryDir(cwd);
+            // Read the context tree root _index.md directly from disk
+            const indexPath = join(cwd, CONTEXT_TREE_INDEX);
+            let indexBody;
+            if (existsSync(indexPath)) {
+                try {
+                    const raw = readFileSync(indexPath, "utf-8");
+                    const body = stripFrontmatter(raw).trim();
+                    if (body) {
+                        indexBody = body;
+                    }
+                }
+                catch {
+                    // Read failed — fall through to stub
+                }
+            }
+            // Ensure memory dir exists
+            mkdirSync(memoryDir, { recursive: true });
+            const now = new Date().toISOString();
+            const contextPath = join(memoryDir, BRV_CONTEXT_FILE);
+            if (indexBody) {
+                // Success: write guide first, then context tree index body
+                const content = [
+                    "---",
+                    "name: byterover context",
+                    "description: cross-references from ByteRover knowledge base",
+                    "type: reference",
+                    "---",
+                    `Last synced: ${now}`,
+                    "",
+                    buildContextTreeGuide(cwd),
+                    "",
+                    indexBody,
+                    "",
+                ].join("\n");
+                writeFileSync(contextPath, content, "utf-8");
+            }
+            else if (!existsSync(contextPath)) {
+                // No context tree and no existing file — write stub for first run
+                const content = [
+                    "---",
+                    "name: byterover context",
+                    "description: cross-references from ByteRover knowledge base (sync pending)",
+                    "type: reference",
+                    "---",
+                    `Last sync attempt: ${now}`,
+                    "Status: no context tree index available \u2014 .brv/context-tree/_index.md not found or empty.",
+                    "",
+                ].join("\n");
+                writeFileSync(contextPath, content, "utf-8");
+            }
+            // Otherwise: _index.md unavailable but _brv_context.md exists — keep existing content
+            // Add pointer to MEMORY.md if not already present (idempotent)
+            const memoryPath = join(memoryDir, MEMORY_INDEX);
+            let memoryContent = "";
+            if (existsSync(memoryPath)) {
+                memoryContent = readFileSync(memoryPath, "utf-8");
+            }
+            if (!memoryContent.includes(BRV_CONTEXT_FILE)) {
+                const separator = memoryContent.endsWith("\n") || !memoryContent
+                    ? ""
+                    : "\n";
+                writeFileSync(memoryPath, memoryContent + separator + POINTER_LINE + "\n", "utf-8");
+            }
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    synced: true,
+                    hasContent: !!indexBody,
+                    contextPath,
+                }));
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            // Best-effort — never block Claude
+            process.stderr.write(`brv-claude-plugin sync error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(0);
+        }
+    });
+}
+//# sourceMappingURL=sync.js.map

package/dist/commands/uninstall.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerUninstallCommand(program: Command): void;

package/dist/commands/uninstall.js

@@ -0,0 +1,72 @@
+import { join } from "node:path";
+import pc from "picocolors";
+import { isBridgeHook } from "../bridge-command.js";
+import { getClaudeConfigHome } from "../memory-path.js";
+import { backupSettings, readSettingsRaw, writeSettingsRaw, } from "../schemas/cc-settings.js";
+export function registerUninstallCommand(program) {
+    program
+        .command("uninstall")
+        .description("Remove Claude Code hooks installed by the bridge")
+        .option("--settings-path <path>", "Override path to Claude Code settings.json")
+        .action(async (opts) => {
+        try {
+            const settingsPath = opts.settingsPath ??
+                join(getClaudeConfigHome(), "settings.json");
+            const settings = readSettingsRaw(settingsPath);
+            const hooks = settings.hooks;
+            if (!hooks || typeof hooks !== "object") {
+                console.log(pc.yellow("No hooks found in settings. Nothing to remove."));
+                return;
+            }
+            let removed = 0;
+            for (const event of Object.keys(hooks)) {
+                const eventHooks = hooks[event];
+                if (!Array.isArray(eventHooks))
+                    continue;
+                // Per-hook removal: within each matcher entry, remove only bridge hooks
+                for (let i = eventHooks.length - 1; i >= 0; i--) {
+                    const matcherEntry = eventHooks[i];
+                    const innerHooks = matcherEntry.hooks;
+                    if (!Array.isArray(innerHooks))
+                        continue;
+                    const filtered = innerHooks.filter((h) => {
+                        if (typeof h === "object" &&
+                            h !== null &&
+                            isBridgeHook(h)) {
+                            removed++;
+                            return false;
+                        }
+                        return true;
+                    });
+                    if (filtered.length === 0) {
+                        // All hooks in this matcher entry were bridge hooks — remove the entry
+                        eventHooks.splice(i, 1);
+                    }
+                    else {
+                        matcherEntry.hooks = filtered;
+                    }
+                }
+                // Clean up empty event arrays
+                if (eventHooks.length === 0) {
+                    delete hooks[event];
+                }
+            }
+            // Clean up empty hooks object
+            if (Object.keys(hooks).length === 0) {
+                delete settings.hooks;
+            }
+            if (removed === 0) {
+                console.log(pc.yellow("No bridge hooks found. Nothing to remove."));
+                return;
+            }
+            backupSettings(settingsPath);
+            writeSettingsRaw(settingsPath, settings);
+            console.log(pc.green(`Removed ${removed} bridge hook(s) from ${settingsPath}`));
+        }
+        catch (err) {
+            console.error(pc.red(`Uninstall failed: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/memory-path.d.ts

@@ -0,0 +1,16 @@
+export declare function sanitizePath(name: string): string;
+export declare function getClaudeConfigHome(): string;
+export declare function findCanonicalGitRoot(startPath: string): string | null;
+/**
+ * Resolve the Claude Code auto-memory directory for a given project cwd.
+ * Matches cc-ts resolution priority:
+ *   1. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE env var
+ *   2. autoMemoryDirectory from settings (local → user)
+ *   3. <memoryBase>/projects/<sanitized-git-root>/memory/
+ */
+export declare function getCcMemoryDir(cwd: string): string;
+/**
+ * Check if a file path is inside a cc-ts memory directory.
+ * Takes pre-resolved memoryDir for efficiency and clarity.
+ */
+export declare function isCcMemoryPath(filePath: string, memoryDir: string): boolean;