devbrain-cli 0.1.0

package/node_modules/@devbrain/core/dist/context/context.service.js

@@ -0,0 +1,72 @@
+import { join } from 'node:path';
+import { FilesystemService } from '../filesystem/filesystem.service.js';
+import { ValidationError } from '@devbrain/shared';
+/**
+ * Service responsible for reading generated project memory and consolidating it into an optimized AI prompt context.
+ */
+export class ContextService {
+    fsService;
+    constructor(fsService = new FilesystemService()) {
+        this.fsService = fsService;
+    }
+    /**
+     * Reads memory markdown files, validates existence, and compiles them into a single token-efficient string.
+     */
+    async buildContext(memoryDir) {
+        const files = [
+            'summary.md',
+            'stack.md',
+            'architecture.md',
+            'features.md',
+            'rules.md',
+            'timeline.md',
+        ];
+        const parts = [];
+        // Ensure memory folder exists
+        if (!(await this.fsService.exists(memoryDir))) {
+            throw new ValidationError('Project memory directory not found.', `The directory ${memoryDir} does not exist.`, 'Run "devbrain learn" to scan the repository and populate the memory files first.');
+        }
+        parts.push('<!-- START OF DEVBRAIN AI ASSISTANT CONTEXT SCHEMA -->');
+        parts.push('# DEVBRAIN PROJECT CONTEXT INDEX');
+        parts.push('');
+        for (const file of files) {
+            const filePath = join(memoryDir, file);
+            if (!(await this.fsService.exists(filePath))) {
+                continue; // Skip missing files gracefully or use a warning comment
+            }
+            const content = await this.fsService.read(filePath);
+            const formatted = this.normalizeHeadings(file, content);
+            parts.push(formatted);
+            parts.push('');
+        }
+        parts.push('<!-- END OF DEVBRAIN AI ASSISTANT CONTEXT SCHEMA -->');
+        return parts.join('\n');
+    }
+    /**
+     * Formats and converts absolute top-level headers (#) to sub-headers (##)
+     * to maintain a single root h1 structure and optimizes whitespaces.
+     */
+    normalizeHeadings(fileName, content) {
+        const sectionName = fileName.replace('.md', '').toUpperCase();
+        const lines = content.split('\n');
+        const processedLines = [`## SECTION: ${sectionName}`, ''];
+        for (let line of lines) {
+            line = line.trimEnd();
+            // Translate root header # to second-level ##
+            if (line.startsWith('# ')) {
+                processedLines.push(`### ${line.substring(2)}`);
+            }
+            else if (line.startsWith('## ')) {
+                processedLines.push(`#### ${line.substring(3)}`);
+            }
+            else if (line.startsWith('### ')) {
+                processedLines.push(`##### ${line.substring(4)}`);
+            }
+            else {
+                processedLines.push(line);
+            }
+        }
+        return processedLines.join('\n').trim();
+    }
+}
+//# sourceMappingURL=context.service.js.map

package/node_modules/@devbrain/core/dist/filesystem/filesystem.service.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Service for safe filesystem operations.
+ */
+export declare class FilesystemService {
+    /**
+     * Check if a path exists.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Reads contents of a file as a string.
+     */
+    read(path: string): Promise<string>;
+    /**
+     * Writes content to a file, creating directories recursively.
+     */
+    write(path: string, content: string): Promise<void>;
+    /**
+     * Atomically writes file content by writing to a temporary file then renaming.
+     */
+    writeAtomic(path: string, content: string): Promise<void>;
+    /**
+     * Reads and parses a JSON file.
+     */
+    readJson<T>(path: string): Promise<T>;
+    /**
+     * Writes JSON data to a file (optionally atomically).
+     */
+    writeJson(path: string, data: any, indent?: number): Promise<void>;
+}

package/node_modules/@devbrain/core/dist/filesystem/filesystem.service.js

@@ -0,0 +1,87 @@
+import { mkdir, readFile, writeFile, rename, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { FilesystemError } from '@devbrain/shared';
+/**
+ * Service for safe filesystem operations.
+ */
+export class FilesystemService {
+    /**
+     * Check if a path exists.
+     */
+    async exists(path) {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Reads contents of a file as a string.
+     */
+    async read(path) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            throw new FilesystemError(`Failed to read file at ${path}`, error.message || 'File might not exist or is not readable', 'Verify the path is correct and has appropriate read permissions.');
+        }
+    }
+    /**
+     * Writes content to a file, creating directories recursively.
+     */
+    async write(path, content) {
+        try {
+            const dir = dirname(path);
+            await mkdir(dir, { recursive: true });
+            await writeFile(path, content, 'utf8');
+        }
+        catch (error) {
+            throw new FilesystemError(`Failed to write file to ${path}`, error.message || 'Directory could not be created or file is locked', 'Check disk space, directory write permissions, and that target file is not locked.');
+        }
+    }
+    /**
+     * Atomically writes file content by writing to a temporary file then renaming.
+     */
+    async writeAtomic(path, content) {
+        const tempPath = `${path}.tmp-${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+        try {
+            await this.write(tempPath, content);
+            await rename(tempPath, path);
+        }
+        catch (error) {
+            // Clean up temp path if it exists
+            try {
+                if (await this.exists(tempPath)) {
+                    const { unlink } = await import('node:fs/promises');
+                    await unlink(tempPath);
+                }
+            }
+            catch {
+                // Ignore cleanup error
+            }
+            throw new FilesystemError(`Failed to atomically write file to ${path}`, error.message || 'Atomic rename failed', 'Ensure the destination folder is writable and in the same filesystem drive.');
+        }
+    }
+    /**
+     * Reads and parses a JSON file.
+     */
+    async readJson(path) {
+        const raw = await this.read(path);
+        try {
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            throw new FilesystemError(`Failed to parse JSON file at ${path}`, error.message || 'Invalid JSON format', 'Correct the JSON syntax or reconstruct the file configuration.');
+        }
+    }
+    /**
+     * Writes JSON data to a file (optionally atomically).
+     */
+    async writeJson(path, data, indent = 2) {
+        const content = JSON.stringify(data, null, indent) + '\n';
+        await this.writeAtomic(path, content);
+    }
+}
+//# sourceMappingURL=filesystem.service.js.map

package/node_modules/@devbrain/core/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { FilesystemService } from './filesystem/filesystem.service.js';
+export { RepositoryScanner, ScanOptions } from './analysis/scanner.js';
+export { Analyzer } from './analysis/analyzer.interface.js';
+export { AnalyzerRegistry } from './analysis/analyzer.registry.js';
+export { MemoryService } from './memory/memory.service.js';
+export { ContextService } from './context/context.service.js';
+export { ReadmeAnalyzer } from './analysis/analyzers/readme.analyzer.js';
+export { PackageJsonAnalyzer } from './analysis/analyzers/package-json.analyzer.js';
+export { TsconfigAnalyzer } from './analysis/analyzers/tsconfig.analyzer.js';
+export { GitAnalyzer } from './analysis/analyzers/git.analyzer.js';
+export { DockerfileAnalyzer } from './analysis/analyzers/docker.analyzer.js';
+export { RequirementsTxtAnalyzer } from './analysis/analyzers/requirements-txt.analyzer.js';
+export { PomXmlAnalyzer } from './analysis/analyzers/pom-xml.analyzer.js';
+export { BuildGradleAnalyzer } from './analysis/analyzers/build-gradle.analyzer.js';

package/node_modules/@devbrain/core/dist/index.js

@@ -0,0 +1,16 @@
+// Public API exports for @devbrain/core
+export { FilesystemService } from './filesystem/filesystem.service.js';
+export { RepositoryScanner } from './analysis/scanner.js';
+export { AnalyzerRegistry } from './analysis/analyzer.registry.js';
+export { MemoryService } from './memory/memory.service.js';
+export { ContextService } from './context/context.service.js';
+// Concrete Analyzer exports
+export { ReadmeAnalyzer } from './analysis/analyzers/readme.analyzer.js';
+export { PackageJsonAnalyzer } from './analysis/analyzers/package-json.analyzer.js';
+export { TsconfigAnalyzer } from './analysis/analyzers/tsconfig.analyzer.js';
+export { GitAnalyzer } from './analysis/analyzers/git.analyzer.js';
+export { DockerfileAnalyzer } from './analysis/analyzers/docker.analyzer.js';
+export { RequirementsTxtAnalyzer } from './analysis/analyzers/requirements-txt.analyzer.js';
+export { PomXmlAnalyzer } from './analysis/analyzers/pom-xml.analyzer.js';
+export { BuildGradleAnalyzer } from './analysis/analyzers/build-gradle.analyzer.js';
+//# sourceMappingURL=index.js.map

package/node_modules/@devbrain/core/dist/memory/memory.service.d.ts

@@ -0,0 +1,19 @@
+import { AggregatedAnalysis } from '@devbrain/shared';
+import { FilesystemService } from '../filesystem/filesystem.service.js';
+/**
+ * Service responsible for generating deterministic, human-readable markdown project documentation.
+ */
+export declare class MemoryService {
+    private readonly fsService;
+    constructor(fsService?: FilesystemService);
+    /**
+     * Generates memory markdown files and writes them to the specified directory.
+     */
+    generateMemory(analysis: AggregatedAnalysis, memoryDir: string): Promise<void>;
+    private buildSummary;
+    private buildStack;
+    private buildArchitecture;
+    private buildFeatures;
+    private buildRules;
+    private buildTimeline;
+}

package/node_modules/@devbrain/core/dist/memory/memory.service.js

@@ -0,0 +1,158 @@
+import { join } from 'node:path';
+import { FilesystemService } from '../filesystem/filesystem.service.js';
+/**
+ * Service responsible for generating deterministic, human-readable markdown project documentation.
+ */
+export class MemoryService {
+    fsService;
+    constructor(fsService = new FilesystemService()) {
+        this.fsService = fsService;
+    }
+    /**
+     * Generates memory markdown files and writes them to the specified directory.
+     */
+    async generateMemory(analysis, memoryDir) {
+        const summary = this.buildSummary(analysis);
+        const stack = this.buildStack(analysis);
+        const architecture = this.buildArchitecture(analysis);
+        const features = this.buildFeatures(analysis);
+        const rules = this.buildRules(analysis);
+        const timeline = this.buildTimeline(analysis);
+        await this.fsService.write(join(memoryDir, 'summary.md'), summary);
+        await this.fsService.write(join(memoryDir, 'stack.md'), stack);
+        await this.fsService.write(join(memoryDir, 'architecture.md'), architecture);
+        await this.fsService.write(join(memoryDir, 'features.md'), features);
+        await this.fsService.write(join(memoryDir, 'rules.md'), rules);
+        await this.fsService.write(join(memoryDir, 'timeline.md'), timeline);
+    }
+    buildSummary(analysis) {
+        const readmeData = analysis.analyzers.readme || {};
+        const packageJsonData = analysis.analyzers['package-json'] || {};
+        const overview = readmeData.description || 'No project description available.';
+        const projectName = analysis.projectName || packageJsonData.name || 'unnamed-project';
+        const fileList = [...analysis.files].sort();
+        const treeLines = fileList.map((f) => `- ${f}`).join('\n');
+        return [
+            `# Project Summary: ${projectName}`,
+            '',
+            '## Overview',
+            overview,
+            '',
+            '## Repository Structure',
+            `Total Files Tracked: ${analysis.files.length}`,
+            '',
+            treeLines,
+            '',
+        ].join('\n');
+    }
+    buildStack(analysis) {
+        const techList = [...analysis.technologies]
+            .sort()
+            .map((t) => `- **${t}**`)
+            .join('\n') || '- None detected';
+        const fwList = [...analysis.frameworks]
+            .sort()
+            .map((f) => `- **${f}**`)
+            .join('\n') || '- None detected';
+        return [
+            '# Technology Stack',
+            '',
+            '## Core Languages & Runtimes',
+            techList,
+            '',
+            '## Frameworks & Libraries',
+            fwList,
+            '',
+        ].join('\n');
+    }
+    buildArchitecture(analysis) {
+        const packageJsonData = analysis.analyzers['package-json'] || {};
+        const dockerfileData = analysis.analyzers.dockerfile || {};
+        const backendTech = analysis.technologies.includes('Node.js') ? 'Node.js' : 'unknown';
+        const buildTool = packageJsonData.dependencies ? 'npm' : 'unknown';
+        const dockerBase = dockerfileData.baseImage
+            ? `Docker (Base image: ${dockerfileData.baseImage})`
+            : 'None detected';
+        return [
+            '# Project Architecture',
+            '',
+            '## Layers & Runtimes',
+            `- **Backend Runtime**: ${backendTech}`,
+            `- **Build / Package Manager**: ${buildTool}`,
+            `- **Containerization / Deployment**: ${dockerBase}`,
+            '',
+            '## Module System & Standards',
+            `- **Primary Language**: ${analysis.metadata.projectLanguage || 'unknown'}`,
+            `- **Default Framework**: ${analysis.metadata.projectFramework || 'None'}`,
+            '',
+        ].join('\n');
+    }
+    buildFeatures(analysis) {
+        const packageJsonData = analysis.analyzers['package-json'] || {};
+        const scripts = packageJsonData.scripts || [];
+        // Scan file paths to infer feature areas
+        const features = [];
+        const files = analysis.files;
+        if (files.some((f) => f.includes('controller')))
+            features.push('Controller layer (business routing)');
+        if (files.some((f) => f.includes('route')))
+            features.push('API routing definition');
+        if (files.some((f) => f.includes('component') || f.includes('view')))
+            features.push('UI components / presentation layer');
+        if (files.some((f) => f.includes('service') || f.includes('provider')))
+            features.push('Service integrations / business logic');
+        if (files.some((f) => f.includes('model') || f.includes('entity')))
+            features.push('Data models / entity schemas');
+        if (files.some((f) => f.includes('tests/') || f.endsWith('.test.ts') || f.endsWith('.spec.ts')))
+            features.push('Unit/Integration Testing suite');
+        const featureList = features.map((f) => `- ${f}`).join('\n') || '- Basic codebase files structure';
+        const scriptsList = scripts.map((s) => `- \`npm run ${s}\``).join('\n') || '- None declared';
+        return [
+            '# Product Features',
+            '',
+            '## Codebase Feature Capabilities',
+            featureList,
+            '',
+            '## Runnable Project Commands',
+            scriptsList,
+            '',
+        ].join('\n');
+    }
+    buildRules(analysis) {
+        const tsconfigData = analysis.analyzers.tsconfig || {};
+        const rules = [
+            '# Project Coding Rules & Conventions',
+            '',
+            '## Compiler Options & Code Style Standards',
+        ];
+        if (tsconfigData.target) {
+            rules.push(`- **TypeScript Target**: ${tsconfigData.target}`);
+            rules.push(`- **Module System**: ${tsconfigData.module}`);
+            rules.push(`- **Strict Type Checking**: ${tsconfigData.strict ? 'Enabled' : 'Disabled'}`);
+            rules.push(`- **JSX Engine**: ${tsconfigData.jsx}`);
+        }
+        else {
+            rules.push('- No TypeScript rules detected. Applying default ES rules.');
+        }
+        rules.push('', '## General Architecture Rules', '- Enforce clean boundaries: CLI layer -> Core layer -> Shared utility layer.', '- Modular composition preferred over inheritance patterns.', '');
+        return rules.join('\n');
+    }
+    buildTimeline(analysis) {
+        const gitData = analysis.analyzers.git || {};
+        const commits = gitData.recentCommits || [];
+        const commitLines = commits.map((c) => `- **${c.hash}** - ${c.message} (${c.author})`).join('\n') ||
+            '- No commits found or git history unavailable';
+        const branch = gitData.branch || 'unknown';
+        return [
+            '# Project Timeline & History',
+            '',
+            '## Git Metrics',
+            `- **Current Branch**: ${branch}`,
+            '',
+            '## Recent Commit Log',
+            commitLines,
+            '',
+        ].join('\n');
+    }
+}
+//# sourceMappingURL=memory.service.js.map

package/node_modules/@devbrain/core/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@devbrain/core",
+  "version": "0.1.0",
+  "private": true,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "@devbrain/shared": "^0.1.0"
+  },
+  "devDependencies": {
+    "fast-glob": "^3.3.2",
+    "fast-xml-parser": "^5.9.3",
+    "simple-git": "^3.23.0"
+  }
+}

package/node_modules/@devbrain/shared/dist/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const DEVBRAIN_VERSION = "0.1.0";
+export declare const DEFAULT_IGNORE_PATTERNS: string[];
+export declare const CONFIG_FILE_NAME = "config.json";
+export declare const MEMORY_DIR_NAME = "memory";
+export declare const DEVBRAIN_DIR_NAME = ".devbrain";
+export declare const DEFAULT_MEMORY_DIR = ".devbrain/memory";

package/node_modules/@devbrain/shared/dist/constants.js

@@ -0,0 +1,15 @@
+export const DEVBRAIN_VERSION = '0.1.0';
+export const DEFAULT_IGNORE_PATTERNS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/coverage/**',
+    '**/target/**',
+    '**/build/**',
+    '**/.cache/**',
+];
+export const CONFIG_FILE_NAME = 'config.json';
+export const MEMORY_DIR_NAME = 'memory';
+export const DEVBRAIN_DIR_NAME = '.devbrain';
+export const DEFAULT_MEMORY_DIR = `${DEVBRAIN_DIR_NAME}/${MEMORY_DIR_NAME}`;
+//# sourceMappingURL=constants.js.map

package/node_modules/@devbrain/shared/dist/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Base error class for all DevBrain errors.
+ * Provides structured details: what happened, why, and how to fix it.
+ */
+export declare class DevBrainError extends Error {
+    readonly code: string;
+    readonly explanation: string;
+    readonly remediation: string;
+    constructor(code: string, message: string, explanation: string, remediation: string);
+    /**
+     * Formats the error into a detailed, user-friendly CLI report.
+     */
+    formatReport(): string;
+}
+/**
+ * Thrown when config validation fails.
+ */
+export declare class ValidationError extends DevBrainError {
+    constructor(message: string, explanation: string, remediation: string);
+}
+/**
+ * Thrown when a filesystem operation fails.
+ */
+export declare class FilesystemError extends DevBrainError {
+    constructor(message: string, explanation: string, remediation: string);
+}
+/**
+ * Thrown when an analyzer plugin execution fails.
+ */
+export declare class AnalyzerError extends DevBrainError {
+    constructor(message: string, explanation: string, remediation: string);
+}
+/**
+ * Thrown when command pipeline lifecycle encounters an execution error.
+ */
+export declare class CommandError extends DevBrainError {
+    constructor(message: string, explanation: string, remediation: string);
+}

package/node_modules/@devbrain/shared/dist/errors.js

@@ -0,0 +1,64 @@
+/**
+ * Base error class for all DevBrain errors.
+ * Provides structured details: what happened, why, and how to fix it.
+ */
+export class DevBrainError extends Error {
+    code;
+    explanation;
+    remediation;
+    constructor(code, message, explanation, remediation) {
+        super(message);
+        this.code = code;
+        this.explanation = explanation;
+        this.remediation = remediation;
+        this.name = 'DevBrainError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Formats the error into a detailed, user-friendly CLI report.
+     */
+    formatReport() {
+        return [
+            `Error [${this.code}]: ${this.message}`,
+            `Why: ${this.explanation}`,
+            `Fix: ${this.remediation}`,
+        ].join('\n');
+    }
+}
+/**
+ * Thrown when config validation fails.
+ */
+export class ValidationError extends DevBrainError {
+    constructor(message, explanation, remediation) {
+        super('VALIDATION_ERROR', message, explanation, remediation);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Thrown when a filesystem operation fails.
+ */
+export class FilesystemError extends DevBrainError {
+    constructor(message, explanation, remediation) {
+        super('FILESYSTEM_ERROR', message, explanation, remediation);
+        this.name = 'FilesystemError';
+    }
+}
+/**
+ * Thrown when an analyzer plugin execution fails.
+ */
+export class AnalyzerError extends DevBrainError {
+    constructor(message, explanation, remediation) {
+        super('ANALYZER_ERROR', message, explanation, remediation);
+        this.name = 'AnalyzerError';
+    }
+}
+/**
+ * Thrown when command pipeline lifecycle encounters an execution error.
+ */
+export class CommandError extends DevBrainError {
+    constructor(message, explanation, remediation) {
+        super('COMMAND_ERROR', message, explanation, remediation);
+        this.name = 'CommandError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/node_modules/@devbrain/shared/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './constants.js';

package/node_modules/@devbrain/shared/dist/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './constants.js';
+//# sourceMappingURL=index.js.map

package/node_modules/@devbrain/shared/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration schema for DevBrain.
+ */
+export interface DevBrainConfig {
+    version: string;
+    project: {
+        name: string;
+        language?: string;
+        framework?: string;
+    };
+    scanner: {
+        ignore: string[];
+        followSymlinks: boolean;
+        respectGitignore: boolean;
+    };
+    memory: {
+        format: 'markdown';
+        directory: string;
+    };
+}
+/**
+ * Context that is passed through the command lifecycle pipeline.
+ */
+export interface CommandContext {
+    cwd: string;
+    config?: DevBrainConfig;
+    debug: boolean;
+}
+/**
+ * Result of individual file analysis.
+ */
+export interface AnalysisResult {
+    analyzerId: string;
+    analyzerName: string;
+    data: Record<string, any>;
+}
+/**
+ * Aggregated repository metadata and technology details.
+ */
+export interface AggregatedAnalysis {
+    projectName: string;
+    technologies: string[];
+    frameworks: string[];
+    metadata: Record<string, any>;
+    files: string[];
+    analyzers: Record<string, any>;
+}
+export interface ProjectContext {
+    cwd: string;
+    files: string[];
+    config: DevBrainConfig;
+}

package/node_modules/@devbrain/shared/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/node_modules/@devbrain/shared/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@devbrain/shared",
+  "version": "0.1.0",
+  "private": true,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build"
+  }
+}