devbrain-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,26 +1,26 @@
-# devbrain
-
-DevBrain is an offline-first CLI tool designed to provide persistent, deterministic project memory for AI assistants.
-
-## Installation
-
-```bash
-npm install -g devbrain-cli
-```
-
-## Quick Start
-
-1. Initialize DevBrain in your project:
-   ```bash
-   devbrain init
-   ```
-2. Scan the repository and generate memory:
-   ```bash
-   devbrain learn
-   ```
-3. Generate LLM-ready consolidated context output:
-   ```bash
-   devbrain context
-   ```
-
-For detailed documentation, community guidelines, and license details, please visit the [DevBrain GitHub repository](https://github.com/CodeItAlone/devbrain#readme).
+# devbrain
+
+DevBrain is an offline-first CLI tool designed to provide persistent, deterministic project memory for AI assistants.
+
+## Installation
+
+```bash
+npm install -g devbrain-cli
+```
+
+## Quick Start
+
+1. Initialize DevBrain in your project:
+   ```bash
+   devbrain init
+   ```
+2. Scan the repository and generate memory:
+   ```bash
+   devbrain learn
+   ```
+3. Generate LLM-ready consolidated context output:
+   ```bash
+   devbrain context
+   ```
+
+For detailed documentation, community guidelines, and license details, please visit the [DevBrain GitHub repository](https://github.com/CodeItAlone/devbrain#readme).

package/dist/bin.js

@@ -3,6 +3,10 @@ import { Command } from 'commander';
 import { InitCommand } from './commands/init.command.js';
 import { LearnCommand } from './commands/learn.command.js';
 import { ContextCommand } from './commands/context.command.js';
+import { StatusCommand } from './commands/status.command.js';
+import { HistoryCommand } from './commands/history.command.js';
+import { HookCommand } from './commands/hook.command.js';
+import { SearchCommand } from './commands/search.command.js';
 import { DEVBRAIN_VERSION } from '@devbrain/shared';
 const program = new Command();
 program
@@ -23,21 +27,79 @@ program
     .command('learn')
     .description('Scan repository files and update documentation memory deterministically')
     .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .option('-f, --force', 'Force a full scanned refresh of memory')
+    .option('--silent', 'Execute silently in the background')
     .option('--no-gitignore', 'Skip matching .gitignore exclude rules')
+    .option('--repair', 'Repair and rebuild vector index from scratch')
     .action(async (options) => {
     const cwd = process.cwd();
     const cmd = new LearnCommand();
-    await cmd.execute(cwd, !!options.debug, { respectGitignore: options.gitignore !== false });
+    await cmd.execute(cwd, !!options.debug, {
+        force: !!options.force,
+        silent: !!options.silent,
+        respectGitignore: options.gitignore !== false,
+        repair: !!options.repair,
+    });
 });
 program
-    .command('context')
+    .command('context [query]')
     .description('Consolidate persistent documentation memory into an optimized prompt context')
     .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
     .option('-r, --raw', 'Omit debug and formatting statistics in output')
-    .action(async (options) => {
+    .action(async (query, options) => {
     const cwd = process.cwd();
     const cmd = new ContextCommand();
-    await cmd.execute(cwd, !!options.debug, { raw: !!options.raw });
+    await cmd.execute(cwd, !!options.debug, { raw: !!options.raw, query });
+});
+program
+    .command('search <query>')
+    .description('Semantically search repository memories for relevant information')
+    .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .option('--top <number>', 'Number of top results to return', (v) => parseInt(v, 10))
+    .action(async (query, options) => {
+    const cwd = process.cwd();
+    const cmd = new SearchCommand();
+    await cmd.execute(cwd, !!options.debug, { query, top: options.top });
+});
+program
+    .command('status')
+    .description('Display autonomous Git integration status and repository statistics')
+    .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const cmd = new StatusCommand();
+    await cmd.execute(cwd, !!options.debug, {});
+});
+program
+    .command('history')
+    .description('Display commit history processing logs and version metrics')
+    .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const cmd = new HistoryCommand();
+    await cmd.execute(cwd, !!options.debug, {});
+});
+// Git Hook Subcommand group
+const hookGroup = program
+    .command('hook')
+    .description('Manage DevBrain autonomous Git integration hooks');
+hookGroup
+    .command('install')
+    .description('Install the post-commit git hook')
+    .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const cmd = new HookCommand();
+    await cmd.execute(cwd, !!options.debug, { action: 'install' });
+});
+hookGroup
+    .command('remove')
+    .description('Remove the post-commit git hook')
+    .option('-d, --debug', 'Enable verbose debug outputs and print stack traces')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const cmd = new HookCommand();
+    await cmd.execute(cwd, !!options.debug, { action: 'remove' });
 });
 // Handle unknown commands
 program.on('command:*', () => {

package/dist/commands/context.command.d.ts

@@ -2,6 +2,7 @@ import { CommandContext } from '@devbrain/shared';
 import { CommandPipeline } from '../pipeline/command.pipeline.js';
 interface ContextArgs {
     raw?: boolean;
+    query?: string;
 }
 /**
  * Command pipeline for "devbrain context".
@@ -9,7 +10,7 @@ interface ContextArgs {
 export declare class ContextCommand extends CommandPipeline<ContextArgs> {
     protected validate(context: CommandContext, _args: ContextArgs): Promise<void>;
     protected createContext(_context: CommandContext, _args: ContextArgs): Promise<void>;
-    protected executeService(context: CommandContext, _args: ContextArgs): Promise<string>;
+    protected executeService(context: CommandContext, args: ContextArgs): Promise<string>;
     protected writeOutput(_context: CommandContext, output: string, _args: ContextArgs): Promise<void>;
     protected reportResult(_context: CommandContext, output: string, args: ContextArgs): Promise<void>;
 }

package/dist/commands/context.command.js

@@ -15,10 +15,48 @@ export class ContextCommand extends CommandPipeline {
     async createContext(_context, _args) {
         // No-op: context built from memory files
     }
-    async executeService(context, _args) {
-        const memoryDir = join(context.cwd, context.config.memory.directory);
-        const contextService = new ContextService(this.fsService);
-        return await contextService.buildContext(memoryDir);
+    async executeService(context, args) {
+        if (args.query) {
+            const dbPath = join(context.cwd, DEVBRAIN_DIR_NAME, 'vectors.db');
+            // Fallback if vectors.db doesn't exist yet
+            if (!(await this.fsService.exists(dbPath))) {
+                this.logger.warn('Vector store database not found. Returning full repository context. Run "devbrain learn" to initialize the vector database.');
+                const memoryDir = join(context.cwd, context.config.memory.directory);
+                const contextService = new ContextService(this.fsService);
+                return await contextService.buildContext(memoryDir);
+            }
+            // Initialize retriever components
+            const { SQLiteVectorStore, TransformersProvider, RankingEngine, SemanticRetriever, ContextBuilder } = await import('@devbrain/core');
+            const vectorStore = new SQLiteVectorStore(dbPath);
+            try {
+                const embeddingProvider = new TransformersProvider();
+                const rankingEngine = new RankingEngine(context.config);
+                const retriever = new SemanticRetriever(vectorStore, embeddingProvider, rankingEngine, context.config);
+                const contextBuilder = new ContextBuilder();
+                // Retrieve recent commits from history
+                let recentCommits = [];
+                try {
+                    const { HistoryManager } = await import('@devbrain/core');
+                    const historyManager = new HistoryManager(context.cwd, this.fsService);
+                    const history = await historyManager.loadHistory();
+                    if (history && history.commits) {
+                        recentCommits = history.commits.map(c => ({ hash: c.commitHash, message: c.commitMessage }));
+                    }
+                }
+                catch { }
+                const topK = context.config?.semanticSearch?.topK ?? 8;
+                const results = await retriever.searchRelevantMemories(args.query, topK, recentCommits);
+                return contextBuilder.buildContext(args.query, results);
+            }
+            finally {
+                vectorStore.close();
+            }
+        }
+        else {
+            const memoryDir = join(context.cwd, context.config.memory.directory);
+            const contextService = new ContextService(this.fsService);
+            return await contextService.buildContext(memoryDir);
+        }
     }
     async writeOutput(_context, output, _args) {
         // Output prompt directly to stdout so it can be piped or copied

package/dist/commands/history.command.d.ts

@@ -0,0 +1,10 @@
+import { CommandContext } from '@devbrain/shared';
+import { CommandPipeline } from '../pipeline/command.pipeline.js';
+export declare class HistoryCommand extends CommandPipeline {
+    private historyManager;
+    protected validate(context: CommandContext, _args: any): Promise<void>;
+    protected createContext(context: CommandContext, _args: any): Promise<void>;
+    protected executeService(context: CommandContext, _args: any): Promise<any>;
+    protected writeOutput(_context: CommandContext, _output: any, _args: any): Promise<void>;
+    protected reportResult(context: CommandContext, output: any, _args: any): Promise<void>;
+}

package/dist/commands/history.command.js

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import { DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME, VERSION_FILE_NAME } from '@devbrain/shared';
+import { HistoryManager } from '@devbrain/core';
+import { CommandPipeline } from '../pipeline/command.pipeline.js';
+import chalk from 'chalk';
+export class HistoryCommand extends CommandPipeline {
+    historyManager;
+    async validate(context, _args) {
+        const configPath = join(context.cwd, DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME);
+        if (!(await this.fsService.exists(configPath))) {
+            throw new Error('DevBrain is not initialized. Run "devbrain init" first.');
+        }
+    }
+    async createContext(context, _args) {
+        this.historyManager = new HistoryManager(context.cwd, this.fsService);
+    }
+    async executeService(context, _args) {
+        const history = await this.historyManager.loadHistory();
+        const versionPath = join(context.cwd, DEVBRAIN_DIR_NAME, VERSION_FILE_NAME);
+        let versionInfo = null;
+        if (await this.fsService.exists(versionPath)) {
+            try {
+                versionInfo = await this.fsService.readJson(versionPath);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        return {
+            history,
+            versionInfo,
+        };
+    }
+    async writeOutput(_context, _output, _args) {
+        // No-op
+    }
+    async reportResult(context, output, _args) {
+        this.logger.header('DevBrain Commit Processing History');
+        const history = output.history;
+        console.log(`- Latest Processed Commit: ${chalk.yellow(history.lastProcessedCommit || 'none')}`);
+        console.log(`- Memory Schema Version: ${chalk.green(output.versionInfo?.version || '0.1.0')}`);
+        console.log(`- Total Commits Learned: ${chalk.cyan(history.commits.length)}`);
+        console.log('');
+        if (history.commits.length === 0) {
+            console.log(chalk.gray('No commit learning logs recorded. Run a commit or "devbrain learn" to populate history.'));
+            return;
+        }
+        console.log(chalk.bold('Learned Commits Log:'));
+        // Display up to 10 recent commits
+        const displayedCommits = history.commits.slice(0, 10);
+        for (const commit of displayedCommits) {
+            const hash = chalk.yellow(commit.commitHash);
+            const date = chalk.gray(new Date(commit.timestamp).toLocaleString());
+            const msg = commit.commitMessage.split('\n')[0];
+            const statusIcon = commit.status === 'success'
+                ? chalk.green('✔')
+                : commit.status === 'skipped' ? chalk.yellow('ℹ') : chalk.red('✖');
+            console.log(` ${statusIcon} ${hash} [${date}] - ${msg}`);
+        }
+        if (history.commits.length > 10) {
+            console.log(chalk.gray(`\n...and ${history.commits.length - 10} more older entries.`));
+        }
+        console.log('');
+    }
+}
+//# sourceMappingURL=history.command.js.map

package/dist/commands/hook.command.d.ts

@@ -0,0 +1,14 @@
+import { CommandContext } from '@devbrain/shared';
+import { CommandPipeline } from '../pipeline/command.pipeline.js';
+interface HookArgs {
+    action: 'install' | 'remove';
+}
+export declare class HookCommand extends CommandPipeline<HookArgs> {
+    private gitService;
+    protected validate(context: CommandContext, _args: HookArgs): Promise<void>;
+    protected createContext(context: CommandContext, _args: HookArgs): Promise<void>;
+    protected executeService(context: CommandContext, args: HookArgs): Promise<void>;
+    protected writeOutput(_context: CommandContext, _output: any, _args: HookArgs): Promise<void>;
+    protected reportResult(context: CommandContext, _output: any, args: HookArgs): Promise<void>;
+}
+export {};

package/dist/commands/hook.command.js

@@ -0,0 +1,40 @@
+import { join } from 'node:path';
+import { DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME } from '@devbrain/shared';
+import { GitService } from '@devbrain/core';
+import { CommandPipeline } from '../pipeline/command.pipeline.js';
+export class HookCommand extends CommandPipeline {
+    gitService;
+    async validate(context, _args) {
+        const configPath = join(context.cwd, DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME);
+        if (!(await this.fsService.exists(configPath))) {
+            throw new Error('DevBrain is not initialized. Run "devbrain init" first.');
+        }
+    }
+    async createContext(context, _args) {
+        this.gitService = new GitService(context.cwd, this.fsService);
+    }
+    async executeService(context, args) {
+        const isGit = await this.gitService.isGitRepository();
+        if (!isGit) {
+            throw new Error('This workspace is not a valid Git repository.');
+        }
+        if (args.action === 'install') {
+            await this.gitService.installHook('post-commit');
+        }
+        else if (args.action === 'remove') {
+            await this.gitService.removeHook('post-commit');
+        }
+    }
+    async writeOutput(_context, _output, _args) {
+        // No-op
+    }
+    async reportResult(context, _output, args) {
+        if (args.action === 'install') {
+            this.logger.success('Successfully installed post-commit hook for DevBrain.');
+        }
+        else {
+            this.logger.success('Successfully removed post-commit hook for DevBrain.');
+        }
+    }
+}
+//# sourceMappingURL=hook.command.js.map

package/dist/commands/init.command.d.ts

@@ -7,6 +7,7 @@ interface InitArgs {
  * Command pipeline for "devbrain init".
  */
 export declare class InitCommand extends CommandPipeline<InitArgs> {
+    private hookInstalled;
     protected validate(context: CommandContext, args: InitArgs): Promise<void>;
     protected createContext(context: CommandContext, _args: InitArgs): Promise<void>;
     protected executeService(context: CommandContext, _args: InitArgs): Promise<void>;

package/dist/commands/init.command.js

@@ -1,10 +1,12 @@
 import { join, basename } from 'node:path';
-import { ValidationError, DEVBRAIN_VERSION, DEFAULT_IGNORE_PATTERNS, DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME, DEFAULT_MEMORY_DIR, } from '@devbrain/shared';
+import { ValidationError, DEVBRAIN_VERSION, DEFAULT_IGNORE_PATTERNS, DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME, VERSION_FILE_NAME, CUSTOM_NOTES_FILE_NAME, DEFAULT_MEMORY_DIR, } from '@devbrain/shared';
+import { GitService } from '@devbrain/core';
 import { CommandPipeline } from '../pipeline/command.pipeline.js';
 /**
  * Command pipeline for "devbrain init".
  */
 export class InitCommand extends CommandPipeline {
+    hookInstalled = false;
     async validate(context, args) {
         const configPath = join(context.cwd, DEVBRAIN_DIR_NAME, CONFIG_FILE_NAME);
         if (!args.force && (await this.fsService.exists(configPath))) {
@@ -12,7 +14,6 @@ export class InitCommand extends CommandPipeline {
         }
     }
     async createContext(context, _args) {
-        // Setup default config parameters
         const projectName = basename(context.cwd);
         context.config = {
             version: DEVBRAIN_VERSION,
@@ -28,30 +29,65 @@ export class InitCommand extends CommandPipeline {
                 format: 'markdown',
                 directory: DEFAULT_MEMORY_DIR,
             },
+            auto_update: true,
+            enabled_hooks: ['post-commit'],
+            ignored_directories: [],
+            ignored_extensions: [],
+            maximum_incremental_files: 50,
+            documentation_generation: true,
+            context_generation: true,
+            verbose_logging: false,
+            safe_mode: true,
         };
     }
     async executeService(context, _args) {
         const devbrainPath = join(context.cwd, DEVBRAIN_DIR_NAME);
         const configPath = join(devbrainPath, CONFIG_FILE_NAME);
-        const memoryPath = join(context.cwd, context.config.memory.directory);
-        // Create directories
+        const versionPath = join(devbrainPath, VERSION_FILE_NAME);
+        const customNotesPath = join(devbrainPath, CUSTOM_NOTES_FILE_NAME);
+        // Create directories & write config
         await this.fsService.writeJson(configPath, context.config);
-        // Generate starter memory summary
-        const summaryPath = join(memoryPath, 'summary.md');
-        const initialSummary = [
-            `# Project Summary: ${context.config.project.name}`,
-            '',
-            '## Overview',
-            'This project has been initialized with DevBrain. Run "devbrain learn" to populate structured memory.',
-            '',
-        ].join('\n');
-        await this.fsService.write(summaryPath, initialSummary);
+        // Create version.json
+        const versionData = {
+            version: DEVBRAIN_VERSION,
+            memorySchema: 2,
+            lastMigration: new Date().toISOString().split('T')[0],
+        };
+        await this.fsService.writeJson(versionPath, versionData);
+        // Write starter custom_notes.md if not present
+        if (!(await this.fsService.exists(customNotesPath))) {
+            const defaultCustomNotes = [
+                '# Custom Developer Notes',
+                '',
+                'Use this file to document manual project conventions, architecture diagrams, decision logs, or any other notes.',
+                'This file will NEVER be overwritten by DevBrain.',
+                '',
+            ].join('\n');
+            await this.fsService.write(customNotesPath, defaultCustomNotes);
+        }
+        // Git Hook Integration
+        try {
+            const gitService = new GitService(context.cwd, this.fsService);
+            if (await gitService.isGitRepository()) {
+                await gitService.installHook('post-commit');
+                this.hookInstalled = true;
+            }
+        }
+        catch (err) {
+            this.logger.warn(`Failed to configure Git hooks: ${err.message || err}`);
+        }
     }
     async writeOutput(_context, _output, _args) {
-        // No-op: files written in execution service
+        // No-op
     }
     async reportResult(context, _output, _args) {
         this.logger.success(`Initialized DevBrain project memory directory at ${join(context.cwd, DEVBRAIN_DIR_NAME)}`);
+        if (this.hookInstalled) {
+            this.logger.success('Automatically installed post-commit Git hook.');
+        }
+        else {
+            this.logger.warn('Git hooks not installed (directory is not a Git repository).');
+        }
     }
 }
 //# sourceMappingURL=init.command.js.map

package/dist/commands/learn.command.d.ts

@@ -1,17 +1,30 @@
 import { CommandContext } from '@devbrain/shared';
 import { CommandPipeline } from '../pipeline/command.pipeline.js';
 interface LearnArgs {
+    force?: boolean;
+    silent?: boolean;
     respectGitignore?: boolean;
+    repair?: boolean;
 }
 /**
  * Command pipeline for "devbrain learn".
  */
 export declare class LearnCommand extends CommandPipeline<LearnArgs> {
-    private filesList;
+    private lockManager;
+    private loggerService;
+    private gitService;
+    private historyManager;
+    private memoryEngine;
+    private memoryService;
+    private contextService;
+    private stats;
     protected validate(context: CommandContext, _args: LearnArgs): Promise<void>;
-    protected createContext(context: CommandContext, args: LearnArgs): Promise<void>;
-    protected executeService(context: CommandContext, _args: LearnArgs): Promise<void>;
+    protected createContext(context: CommandContext, _args: LearnArgs): Promise<void>;
+    execute(cwd: string, debug: boolean, args: LearnArgs): Promise<void>;
+    protected executeService(context: CommandContext, args: LearnArgs): Promise<any>;
+    private synchronizeProjectMemory;
+    private synchronizeVectorIndex;
     protected writeOutput(_context: CommandContext, _output: any, _args: LearnArgs): Promise<void>;
-    protected reportResult(context: CommandContext, _output: any, _args: LearnArgs): Promise<void>;
+    protected reportResult(context: CommandContext, output: any, args: LearnArgs): Promise<void>;
 }
 export {};