byterover-cli 1.7.2 → 2.0.0

package/dist/server/infra/connectors/skill/skill-connector-config.d.ts

@@ -1,45 +1,104 @@
-/**
- * Scope for skill connector configuration.
- * - 'project': Path relative to project root
- * - 'global': Path relative to user home directory
- */
-export type SkillConfigScope = 'global' | 'project';
 /**
  * Configuration for agent-specific skill file directories.
+ * Paths are relative to their respective roots and do NOT include the skill name.
  */
 export type SkillConnectorConfig = {
-    /** Base directory for skill files (relative to scope root) */
-    basePath: string;
-    /** Whether path is relative to project root or home dir */
-    scope: SkillConfigScope;
+    /** Base directory for skill files relative to user home directory */
+    globalPath: string;
+    /** Base directory for skill files relative to project root */
+    projectPath: null | string;
 };
 /**
  * Agent-specific skill connector configurations.
- * Maps each supported agent to its skill directory path and scope.
+ * Maps each supported agent to its project and global skill directory paths.
  */
 export declare const SKILL_CONNECTOR_CONFIGS: {
+    readonly Amp: {
+        readonly globalPath: ".config/agents/skills";
+        readonly projectPath: ".agents/skills";
+    };
+    readonly Antigravity: {
+        readonly globalPath: ".gemini/antigravity/skills";
+        readonly projectPath: ".agent/skills";
+    };
+    readonly 'Auggie CLI': {
+        readonly globalPath: ".augment/skills";
+        readonly projectPath: ".augment/skills";
+    };
     readonly 'Claude Code': {
-        readonly basePath: ".claude/skills/byterover";
-        readonly scope: "project";
+        readonly globalPath: ".claude/skills";
+        readonly projectPath: ".claude/skills";
     };
     readonly Codex: {
-        readonly basePath: ".codex/skills/byterover";
-        readonly scope: "global";
+        readonly globalPath: ".agents/skills";
+        readonly projectPath: ".agents/skills";
     };
     readonly Cursor: {
-        readonly basePath: ".cursor/skills/byterover";
-        readonly scope: "project";
+        readonly globalPath: ".cursor/skills";
+        readonly projectPath: ".cursor/skills";
+    };
+    readonly 'Gemini CLI': {
+        readonly globalPath: ".gemini/skills";
+        readonly projectPath: ".gemini/skills";
     };
     readonly 'Github Copilot': {
-        readonly basePath: ".github/skills/byterover";
-        readonly scope: "project";
+        readonly globalPath: ".copilot/skills";
+        readonly projectPath: ".github/skills";
+    };
+    readonly Junie: {
+        readonly globalPath: ".junie/skills";
+        readonly projectPath: ".junie/skills";
+    };
+    readonly 'Kilo Code': {
+        readonly globalPath: ".kilocode/skills";
+        readonly projectPath: ".kilocode/skills";
+    };
+    readonly Kiro: {
+        readonly globalPath: ".kiro/skills";
+        readonly projectPath: ".kiro/skills";
+    };
+    readonly OpenClaw: {
+        readonly globalPath: ".openclaw/skills";
+        readonly projectPath: null;
+    };
+    readonly OpenCode: {
+        readonly globalPath: ".config/opencode/skills";
+        readonly projectPath: ".opencode/skills";
+    };
+    readonly Qoder: {
+        readonly globalPath: ".qoder/skills";
+        readonly projectPath: ".qoder/skills";
+    };
+    readonly 'Roo Code': {
+        readonly globalPath: ".roo/skills";
+        readonly projectPath: ".roo/skills";
+    };
+    readonly 'Trae.ai': {
+        readonly globalPath: ".trae/skills";
+        readonly projectPath: ".trae/skills";
+    };
+    readonly Warp: {
+        readonly globalPath: ".warp/skills";
+        readonly projectPath: ".warp/skills";
+    };
+    readonly Windsurf: {
+        readonly globalPath: ".codeium/windsurf/skills";
+        readonly projectPath: ".windsurf/skills";
     };
 };
 /**
  * Type representing agents that have skill connector support.
  */
 export type SkillSupportedAgent = keyof typeof SKILL_CONNECTOR_CONFIGS;
+/**
+ * Name used for the ByteRover connector skill subdirectory.
+ */
+export declare const BRV_SKILL_NAME = "byterover";
+/**
+ * Name of the main skill file.
+ */
+export declare const MAIN_SKILL_FILE_NAME = "SKILL.md";
 /**
  * Names of the skill files written by the skill connector.
  */
-export declare const SKILL_FILE_NAMES: readonly ["SKILL.md", "TROUBLESHOOTING.md", "WORKFLOWS.md"];
+export declare const SKILL_FILE_NAMES: readonly ["SKILL.md"];

package/dist/server/infra/connectors/skill/skill-connector-config.js

@@ -1,26 +1,90 @@
 /**
  * Agent-specific skill connector configurations.
- * Maps each supported agent to its skill directory path and scope.
+ * Maps each supported agent to its project and global skill directory paths.
  */
 export const SKILL_CONNECTOR_CONFIGS = {
+    Amp: {
+        globalPath: '.config/agents/skills',
+        projectPath: '.agents/skills',
+    },
+    Antigravity: {
+        globalPath: '.gemini/antigravity/skills',
+        projectPath: '.agent/skills',
+    },
+    'Auggie CLI': {
+        globalPath: '.augment/skills',
+        projectPath: '.augment/skills',
+    },
     'Claude Code': {
-        basePath: '.claude/skills/byterover',
-        scope: 'project',
+        globalPath: '.claude/skills',
+        projectPath: '.claude/skills',
     },
     Codex: {
-        basePath: '.codex/skills/byterover',
-        scope: 'global',
+        globalPath: '.agents/skills',
+        projectPath: '.agents/skills',
     },
     Cursor: {
-        basePath: '.cursor/skills/byterover',
-        scope: 'project',
+        globalPath: '.cursor/skills',
+        projectPath: '.cursor/skills',
+    },
+    'Gemini CLI': {
+        globalPath: '.gemini/skills',
+        projectPath: '.gemini/skills',
     },
     'Github Copilot': {
-        basePath: '.github/skills/byterover',
-        scope: 'project',
+        globalPath: '.copilot/skills',
+        projectPath: '.github/skills',
+    },
+    Junie: {
+        globalPath: '.junie/skills',
+        projectPath: '.junie/skills',
+    },
+    'Kilo Code': {
+        globalPath: '.kilocode/skills',
+        projectPath: '.kilocode/skills',
+    },
+    Kiro: {
+        globalPath: '.kiro/skills',
+        projectPath: '.kiro/skills',
+    },
+    OpenClaw: {
+        globalPath: '.openclaw/skills',
+        projectPath: null,
+    },
+    OpenCode: {
+        globalPath: '.config/opencode/skills',
+        projectPath: '.opencode/skills',
+    },
+    Qoder: {
+        globalPath: '.qoder/skills',
+        projectPath: '.qoder/skills',
+    },
+    'Roo Code': {
+        globalPath: '.roo/skills',
+        projectPath: '.roo/skills',
+    },
+    'Trae.ai': {
+        globalPath: '.trae/skills',
+        projectPath: '.trae/skills',
+    },
+    Warp: {
+        globalPath: '.warp/skills',
+        projectPath: '.warp/skills',
+    },
+    Windsurf: {
+        globalPath: '.codeium/windsurf/skills',
+        projectPath: '.windsurf/skills',
     },
 };
+/**
+ * Name used for the ByteRover connector skill subdirectory.
+ */
+export const BRV_SKILL_NAME = 'byterover';
+/**
+ * Name of the main skill file.
+ */
+export const MAIN_SKILL_FILE_NAME = 'SKILL.md';
 /**
  * Names of the skill files written by the skill connector.
  */
-export const SKILL_FILE_NAMES = ['SKILL.md', 'TROUBLESHOOTING.md', 'WORKFLOWS.md'];
+export const SKILL_FILE_NAMES = [MAIN_SKILL_FILE_NAME];

package/dist/server/infra/connectors/skill/skill-connector.d.ts

@@ -11,9 +11,15 @@ type SkillConnectorOptions = {
     fileService: IFileService;
     projectRoot: string;
 };
+/**
+ * Options for writeSkillFiles, allowing scope override.
+ */
+export type WriteSkillFilesOptions = {
+    scope?: 'global' | 'project';
+};
 /**
  * Connector that integrates BRV with coding agents via skill files.
- * Writes static markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md)
+ * Writes static markdown files (SKILL.md)
  * into an agent-specific subdirectory.
  */
 export declare class SkillConnector implements IConnector {
@@ -29,11 +35,32 @@ export declare class SkillConnector implements IConnector {
     isSupported(agent: Agent): agent is SkillSupportedAgent;
     status(agent: Agent, options?: ConnectorOperationOptions): Promise<ConnectorStatus>;
     uninstall(agent: Agent, options?: ConnectorOperationOptions): Promise<ConnectorUninstallResult>;
+    /**
+     * Write files to a named skill subdirectory for the given agent.
+     * Used by hub install to write downloaded skill files to e.g. `.claude/skills/{skillName}/`.
+     *
+     * @param options.scope - 'global' writes to home dir, 'project' (default) writes to project root
+     */
+    writeSkillFiles(agent: Agent, skillName: string, files: Array<{
+        content: string;
+        name: string;
+    }>, options?: WriteSkillFilesOptions): Promise<{
+        alreadyInstalled: boolean;
+        installedFiles: string[];
+        installedPath: string;
+    }>;
+    /**
+     * Get the skill connector config for an agent, typed as SkillConnectorConfig
+     * to allow safe optional property access on union types from `as const`.
+     */
+    private getConfig;
     /**
      * Get the full (absolute) path for skill file operations.
-     * - Project scope: relative to project root
-     * - Global scope: relative to os.homedir()
+     * Combines the config base path with the skill name, rooted at either
+     * the project root (project scope) or the user's home directory (global scope).
+     *
+     * @throws Error if the requested scope is not configured for the agent.
      */
-    private getFullPath;
+    private resolveFullPath;
 }
 export {};

package/dist/server/infra/connectors/skill/skill-connector.js

@@ -1,11 +1,11 @@
 import os from 'node:os';
 import path from 'node:path';
 import { AGENT_CONNECTOR_CONFIG } from '../../../core/domain/entities/agent.js';
-import { SKILL_CONNECTOR_CONFIGS, SKILL_FILE_NAMES } from './skill-connector-config.js';
+import { BRV_SKILL_NAME, MAIN_SKILL_FILE_NAME, SKILL_CONNECTOR_CONFIGS, SKILL_FILE_NAMES, } from './skill-connector-config.js';
 import { SkillContentLoader } from './skill-content-loader.js';
 /**
  * Connector that integrates BRV with coding agents via skill files.
- * Writes static markdown files (SKILL.md, TROUBLESHOOTING.md, WORKFLOWS.md)
+ * Writes static markdown files (SKILL.md)
  * into an agent-specific subdirectory.
  */
 export class SkillConnector {
@@ -26,7 +26,12 @@ export class SkillConnector {
         if (!this.isSupported(agent)) {
             throw new Error(`Skill connector does not support agent: ${agent}`);
         }
-        return SKILL_CONNECTOR_CONFIGS[agent].basePath;
+        const config = this.getConfig(agent);
+        const basePath = config.projectPath || config.globalPath;
+        if (!basePath) {
+            throw new Error(`Skill connector has no configured path for agent: ${agent}`);
+        }
+        return path.join(basePath, BRV_SKILL_NAME);
     }
     getSupportedAgents() {
         return this.supportedAgents;
@@ -40,20 +45,29 @@ export class SkillConnector {
                 success: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
+        // Install the skill connector in the project directory by default
+        if (!config.projectPath && !config.globalPath) {
+            return {
+                alreadyInstalled: false,
+                configPath: '',
+                message: `Skill connector has no configured path for agent: ${agent}`,
+                success: false,
+            };
+        }
+        // Install to project directory by default, fall back to global for global-only agents
+        const scope = config.projectPath ? 'project' : 'global';
+        const fullDir = this.resolveFullPath(config, scope, BRV_SKILL_NAME);
         try {
-            // Check if already installed
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
+            const skillFilePath = path.join(fullDir, MAIN_SKILL_FILE_NAME);
             if (await this.fileService.exists(skillFilePath)) {
                 return {
                     alreadyInstalled: true,
-                    configPath: config.basePath,
+                    configPath: fullDir,
                     message: `Skill connector is already installed for ${agent}`,
                     success: true,
                 };
             }
-            // Write all skill files
             await Promise.all(SKILL_FILE_NAMES.map(async (fileName) => {
                 const content = await this.contentLoader.loadSkillFile(fileName);
                 const filePath = path.join(fullDir, fileName);
@@ -69,7 +83,7 @@ export class SkillConnector {
         catch (error) {
             return {
                 alreadyInstalled: false,
-                configPath: config.basePath,
+                configPath: fullDir,
                 message: `Failed to install skill connector for ${agent}: ${error instanceof Error ? error.message : String(error)}`,
                 success: false,
             };
@@ -94,21 +108,42 @@ export class SkillConnector {
                 installed: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
         try {
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
-            const exists = await this.fileService.exists(skillFilePath);
+            // Check project scope first
+            if (config.projectPath) {
+                const projectDir = this.resolveFullPath(config, 'project', BRV_SKILL_NAME);
+                const projectSkillFile = path.join(projectDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(projectSkillFile)) {
+                    return {
+                        configExists: true,
+                        configPath: path.join(config.projectPath, BRV_SKILL_NAME),
+                        installed: true,
+                    };
+                }
+            }
+            // Check global scope
+            if (config.globalPath) {
+                const globalDir = this.resolveFullPath(config, 'global', BRV_SKILL_NAME);
+                const globalSkillFile = path.join(globalDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(globalSkillFile)) {
+                    return {
+                        configExists: true,
+                        configPath: path.join(config.globalPath, BRV_SKILL_NAME),
+                        installed: true,
+                    };
+                }
+            }
             return {
-                configExists: exists,
-                configPath: config.basePath,
-                installed: exists,
+                configExists: false,
+                configPath: '',
+                installed: false,
             };
         }
         catch (error) {
             return {
                 configExists: false,
-                configPath: config.basePath,
+                configPath: '',
                 error: error instanceof Error ? error.message : String(error),
                 installed: false,
             };
@@ -131,45 +166,107 @@ export class SkillConnector {
                 wasInstalled: false,
             };
         }
-        const config = SKILL_CONNECTOR_CONFIGS[agent];
-        const fullDir = this.getFullPath(config.basePath, config.scope);
+        const config = this.getConfig(agent);
         try {
-            const skillFilePath = path.join(fullDir, SKILL_FILE_NAMES[0]);
-            const exists = await this.fileService.exists(skillFilePath);
-            if (!exists) {
-                return {
-                    configPath: config.basePath,
-                    message: `Skill connector is not installed for ${agent}`,
-                    success: true,
-                    wasInstalled: false,
-                };
+            // Try to uninstall from project scope
+            if (config.projectPath) {
+                const projectDir = this.resolveFullPath(config, 'project', BRV_SKILL_NAME);
+                const projectSkillFile = path.join(projectDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(projectSkillFile)) {
+                    await this.fileService.deleteDirectory(projectDir);
+                    return {
+                        configPath: path.join(config.projectPath, BRV_SKILL_NAME),
+                        message: `Skill connector uninstalled for ${agent}`,
+                        success: true,
+                        wasInstalled: true,
+                    };
+                }
+            }
+            // Try to uninstall from global scope
+            if (config.globalPath) {
+                const globalDir = this.resolveFullPath(config, 'global', BRV_SKILL_NAME);
+                const globalSkillFile = path.join(globalDir, SKILL_FILE_NAMES[0]);
+                if (await this.fileService.exists(globalSkillFile)) {
+                    await this.fileService.deleteDirectory(globalDir);
+                    return {
+                        configPath: path.join(config.globalPath, BRV_SKILL_NAME),
+                        message: `Skill connector uninstalled for ${agent}`,
+                        success: true,
+                        wasInstalled: true,
+                    };
+                }
             }
-            await this.fileService.deleteDirectory(fullDir);
             return {
-                configPath: config.basePath,
-                message: `Skill connector uninstalled for ${agent}`,
+                configPath: '',
+                message: `Skill connector is not installed for ${agent}`,
                 success: true,
-                wasInstalled: true,
+                wasInstalled: false,
             };
         }
         catch (error) {
             return {
-                configPath: config.basePath,
+                configPath: '',
                 message: `Failed to uninstall skill connector for ${agent}: ${error instanceof Error ? error.message : String(error)}`,
                 success: false,
                 wasInstalled: true,
             };
         }
     }
+    /**
+     * Write files to a named skill subdirectory for the given agent.
+     * Used by hub install to write downloaded skill files to e.g. `.claude/skills/{skillName}/`.
+     *
+     * @param options.scope - 'global' writes to home dir, 'project' (default) writes to project root
+     */
+    async writeSkillFiles(agent, skillName, files, options) {
+        if (!this.isSupported(agent)) {
+            throw new Error(`Skill connector does not support agent: ${agent}`);
+        }
+        const scope = options?.scope ?? 'project';
+        const config = this.getConfig(agent);
+        const basePath = scope === 'global' ? config.globalPath : config.projectPath;
+        if (!basePath) {
+            throw new Error(`Skill connector does not support ${scope} scope for agent: ${agent}`);
+        }
+        const fullDir = this.resolveFullPath(config, scope, skillName);
+        if (files.length > 0) {
+            const firstFilePath = path.join(fullDir, files[0].name);
+            if (await this.fileService.exists(firstFilePath)) {
+                return { alreadyInstalled: true, installedFiles: [], installedPath: fullDir };
+            }
+        }
+        const installedFiles = [];
+        await Promise.all(files.map(async (file) => {
+            const filePath = path.join(fullDir, file.name);
+            await this.fileService.write(file.content, filePath, 'overwrite');
+            installedFiles.push(filePath);
+        }));
+        return { alreadyInstalled: false, installedFiles, installedPath: fullDir };
+    }
+    /**
+     * Get the skill connector config for an agent, typed as SkillConnectorConfig
+     * to allow safe optional property access on union types from `as const`.
+     */
+    getConfig(agent) {
+        return SKILL_CONNECTOR_CONFIGS[agent];
+    }
     /**
      * Get the full (absolute) path for skill file operations.
-     * - Project scope: relative to project root
-     * - Global scope: relative to os.homedir()
+     * Combines the config base path with the skill name, rooted at either
+     * the project root (project scope) or the user's home directory (global scope).
+     *
+     * @throws Error if the requested scope is not configured for the agent.
      */
-    getFullPath(basePath, scope) {
+    resolveFullPath(config, scope, skillName) {
         if (scope === 'global') {
-            return path.join(os.homedir(), basePath);
+            if (!config.globalPath) {
+                throw new Error('Global path is not configured for this agent');
+            }
+            return path.join(os.homedir(), config.globalPath, skillName);
+        }
+        if (!config.projectPath) {
+            throw new Error('Project path is not configured for this agent');
         }
-        return path.join(this.projectRoot, basePath);
+        return path.join(this.projectRoot, config.projectPath, skillName);
     }
 }

package/dist/server/infra/context-tree/file-context-file-reader.js

@@ -27,13 +27,17 @@ export class FileContextFileReader {
         const fullPath = join(baseDir, BRV_DIR, CONTEXT_TREE_DIR, relativePath);
         try {
             const content = await readFile(fullPath, 'utf8');
-            const title = extractTitle(content, relativePath);
-            const parsedContent = MarkdownWriter.parseContent(content, title);
+            const fallbackTitle = extractTitle(content, relativePath);
+            const parsedContent = MarkdownWriter.parseContent(content, fallbackTitle);
+            // Frontmatter title takes precedence, then H1 heading, then path fallback
+            const title = parsedContent.name || fallbackTitle;
             return {
                 content,
+                keywords: parsedContent.keywords,
                 narrative: parsedContent.narrative,
                 path: relativePath,
                 rawConcept: parsedContent.rawConcept,
+                tags: parsedContent.tags,
                 title,
             };
         }

package/dist/server/infra/context-tree/file-context-tree-merger.d.ts

@@ -0,0 +1,51 @@
+import type { IContextTreeMerger, MergeParams, MergeResult } from '../../core/interfaces/context-tree/i-context-tree-merger.js';
+import type { IContextTreeSnapshotService } from '../../core/interfaces/context-tree/i-context-tree-snapshot-service.js';
+export type FileContextTreeMergerDependencies = {
+    snapshotService: IContextTreeSnapshotService;
+};
+/**
+ * File-based implementation of IContextTreeMerger.
+ *
+ * Merge decision per file (remote hash compared against last snapshot hash):
+ *   - Remote unchanged  → skip; local version wins regardless of local state.
+ *   - Remote changed, local clean, preserveLocalFiles=false → overwrite with remote (regular pull).
+ *   - Remote changed, local clean, preserveLocalFiles=true  → conflict (first-time connect; no
+ *     shared history so the local file is not treated as "old").
+ *   - Remote changed, local also changed                    → conflict.
+ *   Conflict handling: local copy saved to .brv/context-tree-conflicts/ and renamed _N.md;
+ *   remote content written to the original path.
+ *
+ * Clean local files absent from remote are deleted (preserveLocalFiles=false) or preserved
+ * (preserveLocalFiles=true). Locally-deleted files are re-created if remote has a newer version.
+ *
+ * A full backup of the context tree is taken before each merge and used for automatic rollback
+ * on failure. The backup is deleted after a successful merge.
+ */
+export declare class FileContextTreeMerger implements IContextTreeMerger {
+    private static readonly MAX_RENAME_ATTEMPTS;
+    private readonly snapshotService;
+    constructor(deps: FileContextTreeMergerDependencies);
+    private static isErrnoException;
+    merge(params: MergeParams): Promise<MergeResult>;
+    /**
+     * Builds a map of remote files with normalized paths and decoded content.
+     */
+    private buildRemoteFilesMap;
+    /**
+     * Recursively copies a directory tree from src to dest.
+     */
+    private copyDir;
+    /**
+     * Finds the first available filename by inserting _N before the extension.
+     * e.g. "path/to/file.md" → "path/to/file_1.md", "path/to/file_2.md", …
+     */
+    private findAvailableName;
+    private runMerge;
+    /**
+     * Handles a true conflict: saves the local content to the conflict dir and as a _N.md
+     * rename, then writes remote content to the original path.
+     *
+     * @returns The _N.md relative path that the local content was saved to.
+     */
+    private writeConflict;
+}