🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
checkpoint: File edit:
rUvbe47a5f93767
diff --git a/v3/@claude-flow/shared/src/hooks/safety/file-organization.ts b/v3/@claude-flow/shared/src/hooks/safety/file-organization.tsnew file mode 100644index 0000000000..0e2b0cf0c0--- /dev/null+++ b/v3/@claude-flow/shared/src/hooks/safety/file-organization.ts@@ -0,0 +1,473 @@+/**+ * V3 File Organization Hook+ *+ * TypeScript conversion of V2 file-hook.sh.+ * Enforces file organization, blocks writes to root folder,+ * suggests proper directories, and recommends formatters.+ *+ * @module v3/shared/hooks/safety/file-organization+ */++import * as path from 'path';+import {+ HookEvent,+ HookContext,+ HookResult,+ HookPriority,+ FileOperationInfo,+} from '../types.js';+import { HookRegistry } from '../registry.js';++/**+ * File organization hook result+ */+export interface FileOrganizationResult extends HookResult {+ /** Whether the file operation should be blocked */+ blocked: boolean;+ /** Reason for blocking */+ blockReason?: string;+ /** Suggested new path */+ suggestedPath?: string;+ /** Suggested directory */+ suggestedDirectory?: string;+ /** Formatter recommendation */+ formatter?: FormatterRecommendation;+ /** Linter recommendation */+ linter?: LinterRecommendation;+ /** File type detected */+ fileType?: string;+ /** Warnings */+ warnings?: string[];+ /** Organization issues detected */+ issues?: OrganizationIssue[];+}++/**+ * Formatter recommendation+ */+export interface FormatterRecommendation {+ /** Formatter name */+ name: string;+ /** Command to run */+ command: string;+ /** Config file to check for */+ configFile?: string;+ /** Whether config exists */+ configExists?: boolean;+}++/**+ * Linter recommendation+ */+export interface LinterRecommendation {+ /** Linter name */+ name: string;+ /** Command to run */+ command: string;+ /** Config file to check for */+ configFile?: string;+}++/**+ * Organization issue+ */+export interface OrganizationIssue {+ /** Issue type */+ type: 'wrong-directory' | 'naming-convention' | 'missing-config' | 'root-write';+ /** Issue severity */+ severity: 'info' | 'warning' | 'error';+ /** Issue description */+ description: string;+ /** Suggested fix */+ suggestedFix?: string;+}++/**+ * File type mapping to directories+ */+const FILE_TYPE_DIRECTORIES: Array<{+ /** File extension or pattern */+ pattern: RegExp;+ /** Suggested directories */+ directories: string[];+ /** File type name */+ type: string;+ /** Whether to block root writes */+ blockRoot: boolean;+}> = [+ // Source files+ { pattern: /\.(ts|tsx)$/, directories: ['src/', 'lib/'], type: 'TypeScript source', blockRoot: true },+ { pattern: /\.(js|jsx|mjs|cjs)$/, directories: ['src/', 'lib/', 'dist/'], type: 'JavaScript source', blockRoot: true },+ { pattern: /\.py$/, directories: ['src/', 'lib/', 'app/'], type: 'Python source', blockRoot: true },+ { pattern: /\.go$/, directories: ['cmd/', 'pkg/', 'internal/'], type: 'Go source', blockRoot: true },+ { pattern: /\.rs$/, directories: ['src/'], type: 'Rust source', blockRoot: true },+ { pattern: /\.java$/, directories: ['src/main/java/', 'src/'], type: 'Java source', blockRoot: true },+ { pattern: /\.rb$/, directories: ['lib/', 'app/'], type: 'Ruby source', blockRoot: true },+ { pattern: /\.php$/, directories: ['src/', 'app/'], type: 'PHP source', blockRoot: true },+ { pattern: /\.cs$/, directories: ['src/'], type: 'C# source', blockRoot: true },+ { pattern: /\.cpp?$/, directories: ['src/'], type: 'C/C++ source', blockRoot: true },+ { pattern: /\.swift$/, directories: ['Sources/'], type: 'Swift source', blockRoot: true },+ { pattern: /\.kt$/, directories: ['src/main/kotlin/', 'src/'], type: 'Kotlin source', blockRoot: true },++ // Test files+ { pattern: /\.test\.(ts|tsx|js|jsx)$/, directories: ['tests/', '__tests__/', 'test/'], type: 'test file', blockRoot: true },+ { pattern: /\.spec\.(ts|tsx|js|jsx)$/, directories: ['tests/', '__tests__/', 'test/', 'spec/'], type: 'spec file', blockRoot: true },+ { pattern: /_test\.go$/, directories: ['tests/', 'test/'], type: 'Go test file', blockRoot: true },+ { pattern: /test_.*\.py$/, directories: ['tests/', 'test/'], type: 'Python test file', blockRoot: true },+ { pattern: /.*_test\.py$/, directories: ['tests/', 'test/'], type: 'Python test file', blockRoot: true },++ // Config files (usually allowed at root)+ { pattern: /\.(json|yaml|yml|toml)$/, directories: ['config/', './', 'configs/'], type: 'config file', blockRoot: false },+ { pattern: /\.(env|env\.[a-z]+)$/, directories: ['./'], type: 'environment file', blockRoot: false },++ // Documentation+ { pattern: /\.md$/, directories: ['docs/', './'], type: 'Markdown documentation', blockRoot: false },+ { pattern: /\.rst$/, directories: ['docs/'], type: 'reStructuredText documentation', blockRoot: true },+ { pattern: /\.adoc$/, directories: ['docs/'], type: 'AsciiDoc documentation', blockRoot: true },++ // Assets+ { pattern: /\.(css|scss|sass|less)$/, directories: ['styles/', 'src/styles/', 'assets/css/'], type: 'stylesheet', blockRoot: true },+ { pattern: /\.(png|jpg|jpeg|gif|svg|ico)$/, directories: ['assets/', 'public/', 'images/', 'static/'], type: 'image', blockRoot: true },+ { pattern: /\.(woff2?|ttf|otf|eot)$/, directories: ['assets/fonts/', 'fonts/', 'public/fonts/'], type: 'font', blockRoot: true },++ // Scripts+ { pattern: /\.sh$/, directories: ['scripts/', 'bin/'], type: 'shell script', blockRoot: true },+ { pattern: /\.ps1$/, directories: ['scripts/', 'bin/'], type: 'PowerShell script', blockRoot: true },++ // Data+ { pattern: /\.sql$/, directories: ['migrations/', 'db/', 'database/'], type: 'SQL file', blockRoot: true },+ { pattern: /\.csv$/, directories: ['data/', 'fixtures/', 'test/fixtures/'], type: 'CSV data', blockRoot: true },+];++/**+ * Formatter recommendations by file extension+ */+const FORMATTERS: Record<string, FormatterRecommendation> = {+ '.ts': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.tsx': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.js': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.jsx': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.json': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.md': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.yaml': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.yml': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.py': { name: 'Black', command: 'black', configFile: 'pyproject.toml' },+ '.go': { name: 'gofmt', command: 'gofmt -w', configFile: undefined },+ '.rs': { name: 'rustfmt', command: 'rustfmt', configFile: 'rustfmt.toml' },+ '.java': { name: 'google-java-format', command: 'google-java-format -i', configFile: undefined },+ '.rb': { name: 'RuboCop', command: 'rubocop -a', configFile: '.rubocop.yml' },+ '.php': { name: 'PHP-CS-Fixer', command: 'php-cs-fixer fix', configFile: '.php-cs-fixer.php' },+ '.cs': { name: 'dotnet-format', command: 'dotnet format', configFile: '.editorconfig' },+ '.swift': { name: 'swift-format', command: 'swift-format -i', configFile: '.swift-format' },+ '.kt': { name: 'ktlint', command: 'ktlint -F', configFile: '.editorconfig' },+ '.css': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.scss': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+ '.html': { name: 'Prettier', command: 'prettier --write', configFile: '.prettierrc' },+};++/**+ * Linter recommendations by file extension+ */+const LINTERS: Record<string, LinterRecommendation> = {+ '.ts': { name: 'ESLint', command: 'eslint --fix', configFile: '.eslintrc' },+ '.tsx': { name: 'ESLint', command: 'eslint --fix', configFile: '.eslintrc' },+ '.js': { name: 'ESLint', command: 'eslint --fix', configFile: '.eslintrc' },+ '.jsx': { name: 'ESLint', command: 'eslint --fix', configFile: '.eslintrc' },+ '.py': { name: 'Pylint', command: 'pylint', configFile: 'pylintrc' },+ '.go': { name: 'golangci-lint', command: 'golangci-lint run', configFile: '.golangci.yml' },+ '.rs': { name: 'Clippy', command: 'cargo clippy', configFile: 'Cargo.toml' },+ '.rb': { name: 'RuboCop', command: 'rubocop', configFile: '.rubocop.yml' },+ '.php': { name: 'PHPStan', command: 'phpstan analyse', configFile: 'phpstan.neon' },+};++/**+ * Naming convention checks+ */+const NAMING_CONVENTIONS: Array<{+ /** Pattern to match file names */+ pattern: RegExp;+ /** Expected naming convention */+ convention: 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case';+ /** File types this applies to */+ fileTypes: RegExp;+}> = [+ { pattern: /^[a-z][a-z0-9-]*\.[a-z]+$/, convention: 'kebab-case', fileTypes: /\.(tsx?|jsx?|css|scss)$/ },+ { pattern: /^[a-z][a-z0-9_]*\.[a-z]+$/, convention: 'snake_case', fileTypes: /\.py$/ },+ { pattern: /^[a-z][a-z0-9_]*\.[a-z]+$/, convention: 'snake_case', fileTypes: /\.go$/ },+ { pattern: /^[A-Z][a-zA-Z0-9]*\.[a-z]+$/, convention: 'PascalCase', fileTypes: /\.(java|kt|cs)$/ },+];++/**+ * File Organization Hook Manager+ */+export class FileOrganizationHook {+ private registry: HookRegistry;+ private projectRoot: string = process.cwd();++ constructor(registry: HookRegistry) {+ this.registry = registry;+ this.registerHooks();+ }++ /**+ * Register file organization hooks+ */+ private registerHooks(): void {+ // Pre-edit hook+ this.registry.register(+ HookEvent.PreEdit,+ this.analyzeFileOperation.bind(this),+ HookPriority.High,+ { name: 'file-organization:pre-edit' }+ );++ // Pre-write hook+ this.registry.register(+ HookEvent.PreWrite,+ this.analyzeFileOperation.bind(this),+ HookPriority.High,+ { name: 'file-organization:pre-write' }+ );+ }++ /**+ * Analyze file operation for organization issues+ */+ async analyzeFileOperation(context: HookContext): Promise<FileOrganizationResult> {+ const fileInfo = context.file;+ if (!fileInfo) {+ return this.createResult(false, []);+ }++ const filePath = fileInfo.path;+ const fileName = path.basename(filePath);+ const dirName = path.dirname(filePath);+ const ext = path.extname(filePath);++ const issues: OrganizationIssue[] = [];+ const warnings: string[] = [];+ let blocked = false;+ let blockReason: string | undefined;+ let suggestedPath: string | undefined;+ let suggestedDirectory: string | undefined;++ // Check if writing to root folder+ const isRootWrite = this.isRootDirectory(dirName);+ const fileTypeInfo = this.getFileTypeInfo(fileName);++ if (isRootWrite && fileTypeInfo?.blockRoot) {+ blocked = true;+ blockReason = `Source files should not be written to root folder. Suggested: ${fileTypeInfo.directories[0]}`;+ suggestedDirectory = fileTypeInfo.directories[0];+ suggestedPath = path.join(suggestedDirectory, fileName);++ issues.push({+ type: 'root-write',+ severity: 'error',+ description: `${fileTypeInfo.type} files should not be in the root directory`,+ suggestedFix: `Move to ${suggestedDirectory}`,+ });+ }++ // Check if file is in wrong directory+ if (!isRootWrite && fileTypeInfo) {+ const isInCorrectDir = fileTypeInfo.directories.some(dir =>+ this.normalizePath(dirName).includes(this.normalizePath(dir))+ );++ if (!isInCorrectDir) {+ issues.push({+ type: 'wrong-directory',+ severity: 'warning',+ description: `${fileTypeInfo.type} typically goes in: ${fileTypeInfo.directories.join(' or ')}`,+ suggestedFix: `Consider moving to ${fileTypeInfo.directories[0]}`,+ });+ warnings.push(`File may be in wrong directory. Expected: ${fileTypeInfo.directories.join(' or ')}`);+ }+ }++ // Check naming convention+ const namingIssue = this.checkNamingConvention(fileName, ext);+ if (namingIssue) {+ issues.push(namingIssue);+ warnings.push(namingIssue.description);+ }++ // Get formatter recommendation+ const formatter = this.getFormatterRecommendation(ext);++ // Get linter recommendation+ const linter = this.getLinterRecommendation(ext);++ return {+ success: true,+ blocked,+ blockReason,+ suggestedPath,+ suggestedDirectory,+ formatter,+ linter,+ fileType: fileTypeInfo?.type,+ warnings: warnings.length > 0 ? warnings : undefined,+ issues: issues.length > 0 ? issues : undefined,+ abort: blocked,+ data: blocked ? undefined : {+ file: {+ ...fileInfo,+ path: suggestedPath || filePath,+ },+ metadata: {+ formatter: formatter?.command,+ linter: linter?.command,+ },+ },+ };+ }++ /**+ * Check if directory is root+ */+ private isRootDirectory(dirName: string): boolean {+ const normalized = this.normalizePath(dirName);+ return normalized === '.' ||+ normalized === './' ||+ normalized === '' ||+ normalized === this.normalizePath(this.projectRoot);+ }++ /**+ * Normalize path for comparison+ */+ private normalizePath(p: string): string {+ return p.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '');+ }++ /**+ * Get file type information+ */+ private getFileTypeInfo(fileName: string): {+ directories: string[];+ type: string;+ blockRoot: boolean;+ } | null {+ for (const info of FILE_TYPE_DIRECTORIES) {+ if (info.pattern.test(fileName)) {+ return {+ directories: info.directories,+ type: info.type,+ blockRoot: info.blockRoot,+ };+ }+ }+ return null;+ }++ /**+ * Check naming convention+ */+ private checkNamingConvention(fileName: string, ext: string): OrganizationIssue | null {+ for (const rule of NAMING_CONVENTIONS) {+ if (rule.fileTypes.test(ext)) {+ const baseName = fileName.replace(ext, '');+ if (!rule.pattern.test(fileName)) {+ return {+ type: 'naming-convention',+ severity: 'info',+ description: `File name may not follow ${rule.convention} convention`,+ suggestedFix: `Consider renaming to follow ${rule.convention}`,+ };+ }+ }+ }+ return null;+ }++ /**+ * Get formatter recommendation+ */+ private getFormatterRecommendation(ext: string): FormatterRecommendation | undefined {+ return FORMATTERS[ext];+ }++ /**+ * Get linter recommendation+ */+ private getLinterRecommendation(ext: string): LinterRecommendation | undefined {+ return LINTERS[ext];+ }++ /**+ * Create result object+ */+ private createResult(blocked: boolean, issues: OrganizationIssue[]): FileOrganizationResult {+ return {+ success: true,+ blocked,+ issues: issues.length > 0 ? issues : undefined,+ };+ }++ /**+ * Manually analyze a file path+ */+ async analyze(filePath: string): Promise<FileOrganizationResult> {+ const context: HookContext = {+ event: HookEvent.PreEdit,+ timestamp: new Date(),+ file: {+ path: filePath,+ operation: 'write',+ },+ };++ return this.analyzeFileOperation(context);+ }++ /**+ * Get suggested directory for a file+ */+ getSuggestedDirectory(fileName: string): string | null {+ const info = this.getFileTypeInfo(fileName);+ return info?.directories[0] || null;+ }++ /**+ * Check if a file path would be blocked+ */+ wouldBlock(filePath: string): boolean {+ const fileName = path.basename(filePath);+ const dirName = path.dirname(filePath);+ const isRoot = this.isRootDirectory(dirName);+ const info = this.getFileTypeInfo(fileName);++ return isRoot && (info?.blockRoot ?? false);+ }++ /**+ * Set project root directory+ */+ setProjectRoot(root: string): void {+ this.projectRoot = root;+ }++ /**+ * Get all formatter recommendations+ */+ getAllFormatters(): Record<string, FormatterRecommendation> {+ return { ...FORMATTERS };+ }++ /**+ * Get all linter recommendations+ */+ getAllLinters(): Record<string, LinterRecommendation> {+ return { ...LINTERS };+ }+}++/**+ * Create file organization hook+ */+export function createFileOrganizationHook(registry: HookRegistry): FileOrganizationHook {+ return new FileOrganizationHook(registry);+}diff --git a/v3/mcp/tools/index.ts b/v3/mcp/tools/index.tsindex b0a76ae2c3..e6a29eb5f2 100644--- a/v3/mcp/tools/index.ts+++ b/v3/mcp/tools/index.ts@@ -356,4 +356,7 @@ export default {memoryTools,configTools,hooksTools,+ taskTools,+ systemTools,+ sessionTools,};