@hyperdrive.bot/gut 0.1.6 → 0.1.9

package/dist/commands/audit.js

@@ -0,0 +1,594 @@
+import { Flags } from '@oclif/core';
+import chalk from 'chalk';
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { BaseCommand } from '../base-command.js';
+export default class Audit extends BaseCommand {
+    static description = 'Access and change audit across workspace';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --entity mindtools',
+        '<%= config.bin %> <%= command.id %> --security',
+        '<%= config.bin %> <%= command.id %> --compliance',
+    ];
+    static flags = {
+        access: Flags.boolean({
+            char: 'a',
+            default: false,
+            description: 'audit access patterns and permissions',
+        }),
+        changes: Flags.boolean({
+            default: false,
+            description: 'audit recent changes and activity',
+        }),
+        compliance: Flags.boolean({
+            char: 'c',
+            default: false,
+            description: 'focus on compliance audit',
+        }),
+        entity: Flags.string({
+            char: 'e',
+            description: 'audit specific entity',
+        }),
+        json: Flags.boolean({
+            default: false,
+            description: 'output as JSON',
+        }),
+        security: Flags.boolean({
+            char: 's',
+            default: false,
+            description: 'focus on security audit',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Audit);
+        let entities = [];
+        if (flags.entity) {
+            const entity = this.entityService.findEntity(flags.entity);
+            if (!entity) {
+                this.error(`Entity '${flags.entity}' not found`);
+            }
+            entities = [entity];
+        }
+        else {
+            entities = this.entityService.getAllEntities();
+        }
+        if (entities.length === 0) {
+            this.error('No entities found to audit');
+        }
+        const auditResults = await this.performAudit(entities, flags);
+        if (flags.json) {
+            this.log(JSON.stringify(auditResults, null, 2));
+            return;
+        }
+        this.displayAuditResults(auditResults);
+    }
+    async auditEntity(entity, flags) {
+        const entityPath = this.entityService.resolveEntityPath(entity);
+        const exists = fs.existsSync(entityPath);
+        const audit = {
+            accessIssues: [],
+            complianceIssues: [],
+            entity: entity.name,
+            exists,
+            fileAudit: { issues: [], recommendations: [], structureScore: 0 },
+            gitAudit: { isGitRepo: false, issues: [] },
+            issues: [],
+            metadataAudit: { hasMetadataFile: false, issues: [], metadataCompleteness: 0 },
+            path: entity.path,
+            securityIssues: [],
+            timestamp: new Date().toISOString(),
+            type: entity.type,
+        };
+        if (!audit.exists) {
+            audit.issues.push({
+                message: 'Entity path does not exist',
+                path: entityPath,
+                severity: 'high',
+                type: 'missing_entity',
+            });
+            return audit;
+        }
+        // Metadata audit
+        audit.metadataAudit = await this.auditMetadata(entity);
+        // Git audit
+        if (await this.gitService.isRepository(entityPath)) {
+            audit.gitAudit = await this.auditGitRepository(entityPath);
+        }
+        // File structure audit
+        audit.fileAudit = await this.auditFileStructure(entityPath, entity.type);
+        // Security audit
+        if (flags.security || !this.hasSpecificAuditType(flags)) {
+            audit.securityIssues = await this.performSecurityAudit(entityPath);
+        }
+        // Compliance audit
+        if (flags.compliance || !this.hasSpecificAuditType(flags)) {
+            audit.complianceIssues = await this.performComplianceAudit(entity);
+        }
+        // Access audit
+        if (flags.access || !this.hasSpecificAuditType(flags)) {
+            audit.accessIssues = await this.performAccessAudit(entity);
+        }
+        return audit;
+    }
+    async auditFileStructure(entityPath, entityType) {
+        const audit = {
+            issues: [],
+            recommendations: [],
+            structureScore: 0,
+        };
+        try {
+            const files = fs.readdirSync(entityPath);
+            // Check for common files based on entity type
+            const expectedFiles = this.getExpectedFiles(entityType);
+            for (const expectedFile of expectedFiles) {
+                if (!files.includes(expectedFile.name)) {
+                    audit.issues.push({
+                        message: `Missing ${expectedFile.description}: ${expectedFile.name}`,
+                        severity: expectedFile.required ? 'medium' : 'low',
+                        type: 'missing_file',
+                    });
+                }
+            }
+            // Check for documentation
+            const hasReadme = files.some(f => f.toLowerCase().startsWith('readme'));
+            if (!hasReadme) {
+                audit.recommendations.push('Add README.md file for documentation');
+            }
+            // Check for configuration files
+            const hasConfig = files.some(f => f.includes('config') || f.includes('.env'));
+            audit.hasConfiguration = hasConfig;
+            audit.structureScore = this.calculateStructureScore(files, expectedFiles);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            audit.issues.push({
+                message: `File structure audit failed: ${message}`,
+                severity: 'high',
+                type: 'file_audit_error',
+            });
+        }
+        return audit;
+    }
+    async auditGitRepository(repoPath) {
+        const audit = {
+            isGitRepo: true,
+            issues: [],
+        };
+        try {
+            // Check git status
+            const status = await this.gitService.getStatus(repoPath);
+            audit.status = status;
+            // Check for uncommitted changes
+            if (status.hasChanges) {
+                audit.issues.push({
+                    message: `Repository has ${status.changes.length} uncommitted changes`,
+                    severity: 'low',
+                    type: 'uncommitted_changes',
+                });
+            }
+            // Check remote configuration
+            try {
+                const remotes = await this.gitService.exec(['remote', '-v'], { cwd: repoPath });
+                audit.hasRemote = remotes.length > 0;
+                if (!audit.hasRemote) {
+                    audit.issues.push({
+                        message: 'Repository has no remote configured',
+                        severity: 'medium',
+                        type: 'no_remote',
+                    });
+                }
+            }
+            catch {
+                audit.hasRemote = false;
+            }
+            // Check branch information
+            try {
+                const branch = await this.gitService.exec(['branch', '--show-current'], { cwd: repoPath });
+                audit.currentBranch = branch.trim();
+                if ((audit.currentBranch === 'master' || audit.currentBranch === 'main') // Check if working directly on main branch
+                    && status.hasChanges) {
+                    audit.issues.push({
+                        message: 'Working directly on main/master branch with uncommitted changes',
+                        severity: 'medium',
+                        type: 'working_on_main',
+                    });
+                }
+            }
+            catch {
+                // Ignore branch check errors
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            audit.issues.push({
+                message: `Git audit failed: ${message}`,
+                severity: 'high',
+                type: 'git_error',
+            });
+        }
+        return audit;
+    }
+    async auditMetadata(entity) {
+        const issues = [];
+        const metadata = entity.metadata || {};
+        // Check required metadata fields
+        if (entity.type === 'client') {
+            if (!metadata.business?.primary_contact) {
+                issues.push({
+                    field: 'business.primary_contact',
+                    message: 'Client entity missing primary contact information',
+                    severity: 'medium',
+                    type: 'missing_metadata',
+                });
+            }
+            if (!metadata.business?.contract_value) {
+                issues.push({
+                    field: 'business.contract_value',
+                    message: 'Client entity missing contract value',
+                    severity: 'low',
+                    type: 'missing_metadata',
+                });
+            }
+        }
+        // Check metadata file existence
+        const entityPath = this.entityService.resolveEntityPath(entity);
+        const metadataPath = path.join(entityPath, '.entity.yaml');
+        return {
+            hasMetadataFile: fs.existsSync(metadataPath),
+            issues,
+            metadataCompleteness: this.calculateMetadataCompleteness(metadata, entity.type),
+        };
+    }
+    calculateMetadataCompleteness(metadata, entityType) {
+        const requiredFields = this.getRequiredMetadataFields(entityType);
+        let completedFields = 0;
+        for (const field of requiredFields) {
+            if (this.hasNestedField(metadata, field)) {
+                completedFields++;
+            }
+        }
+        return requiredFields.length > 0 ? completedFields / requiredFields.length : 1;
+    }
+    calculateStructureScore(files, expectedFiles) {
+        let score = 0;
+        const totalExpected = expectedFiles.length;
+        for (const expected of expectedFiles) {
+            if (files.includes(expected.name)) {
+                score += expected.required ? 2 : 1;
+            }
+        }
+        return totalExpected > 0 ? score / (totalExpected * 2) : 1;
+    }
+    displayAuditResults(results) {
+        this.log(chalk.bold('\n🔍 Workspace Audit Report'));
+        this.log(chalk.dim('─'.repeat(50)));
+        this.log(`📅 Generated: ${new Date(results.timestamp).toLocaleString()}`);
+        this.log(`📊 Scope: ${results.scope.entities.length} entities`);
+        this.log(`🎯 Audit Types: ${results.scope.auditTypes.join(', ')}`);
+        this.log('');
+        // Summary
+        this.log(chalk.bold('📋 Summary:'));
+        const { summary } = results;
+        if (summary.issuesFound === 0) {
+            this.log(chalk.green('✅ No issues found'));
+        }
+        else {
+            this.log(`⚠️  Total Issues: ${chalk.yellow(summary.issuesFound)}`);
+            if (summary.securityIssues > 0) {
+                this.log(`🔒 Security Issues: ${chalk.red(summary.securityIssues)}`);
+            }
+            if (summary.complianceIssues > 0) {
+                this.log(`📋 Compliance Issues: ${chalk.yellow(summary.complianceIssues)}`);
+            }
+            if (summary.accessIssues > 0) {
+                this.log(`🔐 Access Issues: ${chalk.red(summary.accessIssues)}`);
+            }
+        }
+        this.log('');
+        // Detailed findings
+        for (const finding of results.findings) {
+            this.displayEntityAudit(finding);
+        }
+        // Recommendations
+        this.displayRecommendations(results);
+    }
+    displayEntityAudit(audit) {
+        const emoji = this.getTypeEmoji(audit.type);
+        const issueCount = audit.issues.length + audit.securityIssues.length
+            + audit.complianceIssues.length + audit.accessIssues.length;
+        const statusIcon = issueCount === 0
+            ? chalk.green('✅')
+            : (issueCount < 3 ? chalk.yellow('⚠️') : chalk.red('❌'));
+        this.log(`${emoji} ${chalk.bold(audit.entity)} ${statusIcon}`);
+        if (!audit.exists) {
+            this.log(`  ${chalk.red('❌ Entity path does not exist')}`);
+            return;
+        }
+        // Show critical issues
+        const criticalIssues = [
+            ...audit.issues,
+            ...audit.securityIssues,
+            ...audit.complianceIssues,
+            ...audit.accessIssues,
+        ].filter(issue => issue.severity === 'high');
+        if (criticalIssues.length > 0) {
+            this.log(`  ${chalk.red('🚨 Critical Issues:')}`);
+            for (const issue of criticalIssues) {
+                this.log(`    • ${issue.message}`);
+            }
+        }
+        // Show metadata completeness
+        if (audit.metadataAudit?.metadataCompleteness !== undefined) {
+            const completeness = Math.round(audit.metadataAudit.metadataCompleteness * 100);
+            const color = completeness >= 80 ? chalk.green : (completeness >= 60 ? chalk.yellow : chalk.red);
+            this.log(`  📊 Metadata: ${color(`${completeness}% complete`)}`);
+        }
+        // Show git status
+        if (audit.gitAudit?.isGitRepo) {
+            const gitStatus = audit.gitAudit.status?.hasChanges
+                ? chalk.yellow('uncommitted changes')
+                : chalk.green('clean');
+            this.log(`  📁 Git: ${gitStatus}`);
+        }
+        this.log('');
+    }
+    displayRecommendations(results) {
+        const allRecommendations = [];
+        // Collect recommendations from all findings
+        for (const finding of results.findings) {
+            if (finding.fileAudit?.recommendations) {
+                allRecommendations.push(...finding.fileAudit.recommendations);
+            }
+        }
+        if (allRecommendations.length > 0) {
+            this.log(chalk.bold('💡 Recommendations:'));
+            const uniqueRecommendations = [...new Set(allRecommendations)];
+            for (const rec of uniqueRecommendations) {
+                this.log(`  • ${rec}`);
+            }
+        }
+    }
+    getAllFiles(dirPath, maxDepth = 2) {
+        const files = [];
+        const traverse = (currentPath, depth) => {
+            if (depth > maxDepth)
+                return;
+            try {
+                const items = fs.readdirSync(currentPath);
+                for (const item of items) {
+                    if (item.startsWith('.') && item !== '.entity.yaml')
+                        continue;
+                    const itemPath = path.join(currentPath, item);
+                    const stats = fs.statSync(itemPath);
+                    if (stats.isFile()) {
+                        files.push(path.relative(dirPath, itemPath));
+                    }
+                    else if (stats.isDirectory()) {
+                        traverse(itemPath, depth + 1);
+                    }
+                }
+            }
+            catch {
+                // Ignore permission errors
+            }
+        };
+        traverse(dirPath, 0);
+        return files;
+    }
+    // Helper methods
+    getAuditTypes(flags) {
+        const types = [];
+        if (flags.security)
+            types.push('security');
+        if (flags.compliance)
+            types.push('compliance');
+        if (flags.access)
+            types.push('access');
+        if (flags.changes)
+            types.push('changes');
+        if (types.length === 0)
+            types.push('general');
+        return types;
+    }
+    getExpectedFiles(entityType) {
+        const common = [
+            { description: 'Entity metadata', name: '.entity.yaml', required: true },
+            { description: 'Documentation', name: 'README.md', required: false },
+        ];
+        const typeSpecific = {
+            client: [
+                { description: 'Project configuration', name: 'package.json', required: false },
+                { description: 'Git ignore rules', name: '.gitignore', required: true },
+            ],
+            system: [
+                { description: 'Project configuration', name: 'package.json', required: true },
+                { description: 'Git ignore rules', name: '.gitignore', required: true },
+            ],
+        };
+        return [...common, ...(typeSpecific[entityType] || [])];
+    }
+    getRequiredMetadataFields(entityType) {
+        const fields = {
+            client: ['business.primary_contact', 'business.status', 'relationships.dependent_systems'],
+            company: ['business.status'],
+            initiative: ['relationships.related_initiatives'],
+            prospect: ['business.status', 'relationships.similar_entities'],
+            system: ['relationships.dependent_systems'],
+        };
+        return fields[entityType] || [];
+    }
+    hasNestedField(obj, fieldPath) {
+        const parts = fieldPath.split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (!current || typeof current !== 'object' || !(part in current)) {
+                return false;
+            }
+            current = current[part];
+        }
+        return current !== undefined && current !== null && current !== '';
+    }
+    hasSpecificAuditType(flags) {
+        return flags.security || flags.compliance || flags.access || flags.changes;
+    }
+    async performAccessAudit(entity) {
+        const issues = [];
+        // Check path accessibility
+        const entityPath = this.entityService.resolveEntityPath(entity);
+        try {
+            const stats = fs.statSync(entityPath);
+            // Check if path is accessible
+            if (!stats.isDirectory()) {
+                issues.push({
+                    message: 'Entity path is not a directory',
+                    severity: 'high',
+                    type: 'invalid_path',
+                });
+            }
+            // Check permissions (basic check)
+            try {
+                fs.accessSync(entityPath, fs.constants.R_OK | fs.constants.W_OK);
+            }
+            catch {
+                issues.push({
+                    message: 'Insufficient permissions for entity path',
+                    severity: 'high',
+                    type: 'permission_issue',
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push({
+                message: `Cannot access entity path: ${message}`,
+                severity: 'high',
+                type: 'access_error',
+            });
+        }
+        // Check for private/business separation
+        if (entity.type === 'client') {
+            const hasPrivate = entity.path.includes('private') || entity.path.includes('business');
+            const metadata = entity.metadata || {};
+            if (metadata.business && !hasPrivate) {
+                issues.push({
+                    message: 'Client entity with business data should have private/business separation',
+                    severity: 'medium',
+                    type: 'missing_private_separation',
+                });
+            }
+        }
+        return issues;
+    }
+    async performAudit(entities, flags) {
+        const results = {
+            findings: [],
+            scope: {
+                auditTypes: this.getAuditTypes(flags),
+                entities: entities.map(e => e.name),
+            },
+            summary: {
+                accessIssues: 0,
+                complianceIssues: 0,
+                issuesFound: 0,
+                securityIssues: 0,
+                totalEntities: entities.length,
+            },
+            timestamp: new Date().toISOString(),
+        };
+        for (const entity of entities) {
+            const entityAudit = await this.auditEntity(entity, flags);
+            results.findings.push(entityAudit);
+            // Update summary
+            results.summary.issuesFound += entityAudit.issues.length;
+            results.summary.securityIssues += entityAudit.securityIssues.length;
+            results.summary.complianceIssues += entityAudit.complianceIssues.length;
+            results.summary.accessIssues += entityAudit.accessIssues.length;
+        }
+        return results;
+    }
+    async performComplianceAudit(entity) {
+        const issues = [];
+        const metadata = entity.metadata || {};
+        // Check business compliance for client entities
+        if (entity.type === 'client') {
+            if (!metadata.business?.status) {
+                issues.push({
+                    message: 'Client entity missing business status',
+                    severity: 'medium',
+                    type: 'missing_business_status',
+                });
+            }
+            // Check for required documentation
+            const entityPath = this.entityService.resolveEntityPath(entity);
+            const requiredDocs = ['README.md', '.entity.yaml'];
+            for (const doc of requiredDocs) {
+                const docPath = path.join(entityPath, doc);
+                if (!fs.existsSync(docPath)) {
+                    issues.push({
+                        message: `Required documentation missing: ${doc}`,
+                        severity: 'medium',
+                        type: 'missing_documentation',
+                    });
+                }
+            }
+        }
+        // Check metadata completeness
+        const completeness = this.calculateMetadataCompleteness(metadata, entity.type);
+        if (completeness < 0.7) {
+            issues.push({
+                message: `Entity metadata only ${Math.round(completeness * 100)}% complete`,
+                severity: 'low',
+                type: 'incomplete_metadata',
+            });
+        }
+        return issues;
+    }
+    async performSecurityAudit(entityPath) {
+        const issues = [];
+        // Check for sensitive files
+        const sensitivePatterns = [
+            '.env',
+            'secrets',
+            'private',
+            'credentials',
+            'password',
+            'key',
+            'token',
+        ];
+        try {
+            const files = this.getAllFiles(entityPath);
+            for (const file of files) {
+                const fileName = path.basename(file).toLowerCase();
+                for (const pattern of sensitivePatterns) {
+                    if (fileName.includes(pattern)) {
+                        issues.push({
+                            file,
+                            message: `Potentially sensitive file found: ${file}`,
+                            severity: 'high',
+                            type: 'sensitive_file',
+                        });
+                    }
+                }
+            }
+            // Check for .gitignore
+            const gitignorePath = path.join(entityPath, '.gitignore');
+            if (!fs.existsSync(gitignorePath)) {
+                issues.push({
+                    message: 'No .gitignore file found',
+                    severity: 'medium',
+                    type: 'missing_gitignore',
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            issues.push({
+                message: `Security audit failed: ${message}`,
+                severity: 'high',
+                type: 'security_audit_error',
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/back.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '../base-command.js';
+export default class Back extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/back.js

@@ -0,0 +1,29 @@
+import chalk from 'chalk';
+import { BaseCommand } from '../base-command.js';
+/** Minimum history length required to have a previous focus entry */
+const MIN_HISTORY_FOR_PREVIOUS = 2;
+/** Index of the previous entry in the history array (0 is current, 1 is previous) */
+const PREVIOUS_ENTRY_INDEX = 1;
+export default class Back extends BaseCommand {
+    static description = 'Navigate back to the previous focus';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+    ];
+    async run() {
+        await this.parse(Back);
+        const focusedEntities = await this.focusService.getFocusedEntities();
+        const history = this.configService.getHistory();
+        if (history.length < MIN_HISTORY_FOR_PREVIOUS) {
+            this.log(chalk.yellow('No previous focus available'));
+            this.log(chalk.dim('Focus history is empty or has only the current focus'));
+            return;
+        }
+        const previousEntry = history[PREVIOUS_ENTRY_INDEX];
+        const currentEntities = focusedEntities.map(e => e.name).join(', ') || 'none';
+        const previousEntities = previousEntry.entities.join(', ');
+        await this.focusService.switchToPrevious();
+        this.log(chalk.green('✓ Switched to previous focus'));
+        this.log(chalk.dim(`  From: ${currentEntities}`));
+        this.log(chalk.dim(`  To:   ${previousEntities}`));
+    }
+}

package/dist/commands/checkout.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../base-command.js';
+export default class Checkout extends BaseCommand {
+    static args: {
+        branch: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'create-branch': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        from: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}