@compilr-dev/agents 0.0.1

package/dist/rehearsal/manager.js

@@ -0,0 +1,290 @@
+/**
+ * Rehearsal Manager
+ *
+ * Coordinates rehearsal analyzers to provide impact analysis
+ * for destructive operations before they are executed.
+ */
+import { GitRehearsalAnalyzer } from './git-analyzer.js';
+import { FileRehearsalAnalyzer } from './file-analyzer.js';
+/**
+ * Severity level ordering for comparison
+ */
+const SEVERITY_ORDER = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    critical: 3,
+};
+/**
+ * Compare severity levels
+ */
+function compareSeverity(a, b) {
+    return SEVERITY_ORDER[a] - SEVERITY_ORDER[b];
+}
+/**
+ * RehearsalManager - Coordinates impact analysis for destructive operations
+ *
+ * @example
+ * ```typescript
+ * const manager = new RehearsalManager({
+ *   workingDirectory: '/path/to/project',
+ * });
+ *
+ * // Analyze before executing
+ * const result = await manager.rehearse('rm -rf node_modules');
+ *
+ * if (result.recommendation === 'abort') {
+ *   console.log('Operation too dangerous:', result.warnings);
+ * } else if (result.recommendation === 'confirm') {
+ *   const confirmed = await askUser(result.impact.summary);
+ *   if (confirmed) {
+ *     // Execute the operation
+ *   }
+ * }
+ * ```
+ */
+export class RehearsalManager {
+    analyzers = new Map();
+    workingDirectory;
+    warningThreshold;
+    sessionStartTime;
+    sessionModifiedFiles = new Set();
+    trackSessionFiles;
+    eventHandler;
+    constructor(options = {}) {
+        this.workingDirectory = options.workingDirectory ?? process.cwd();
+        this.warningThreshold = options.warningThreshold ?? 'medium';
+        this.sessionStartTime = options.sessionStartTime ?? new Date();
+        this.trackSessionFiles = options.trackSessionFiles ?? true;
+        // Add built-in analyzers if requested (default: true)
+        if (options.includeBuiltinAnalyzers !== false) {
+            this.registerAnalyzer(new GitRehearsalAnalyzer());
+            this.registerAnalyzer(new FileRehearsalAnalyzer());
+        }
+        // Add custom analyzers
+        if (options.analyzers) {
+            for (const analyzer of options.analyzers) {
+                this.registerAnalyzer(analyzer);
+            }
+        }
+        // Set up callbacks
+        if (options.onRehearsal) {
+            const rehearsalCallback = options.onRehearsal;
+            this.onEvent((event) => {
+                if (event.type === 'rehearsal_complete' && event.result) {
+                    rehearsalCallback(event.result);
+                }
+            });
+        }
+    }
+    /**
+     * Register an analyzer
+     */
+    registerAnalyzer(analyzer) {
+        this.analyzers.set(analyzer.id, analyzer);
+        return this;
+    }
+    /**
+     * Unregister an analyzer
+     */
+    unregisterAnalyzer(id) {
+        return this.analyzers.delete(id);
+    }
+    /**
+     * Get all registered analyzers
+     */
+    getAnalyzers() {
+        return Array.from(this.analyzers.values());
+    }
+    /**
+     * Set event handler
+     */
+    onEvent(handler) {
+        this.eventHandler = handler;
+        return this;
+    }
+    /**
+     * Emit an event
+     */
+    emit(event) {
+        if (this.eventHandler) {
+            this.eventHandler(event);
+        }
+    }
+    /**
+     * Track a file as modified in this session
+     */
+    trackFileModification(filePath) {
+        if (this.trackSessionFiles) {
+            this.sessionModifiedFiles.add(filePath);
+        }
+    }
+    /**
+     * Get files modified in this session
+     */
+    getSessionModifiedFiles() {
+        return Array.from(this.sessionModifiedFiles);
+    }
+    /**
+     * Check if an operation is potentially destructive
+     */
+    isDestructive(operation) {
+        for (const analyzer of this.analyzers.values()) {
+            if (analyzer.canAnalyze(operation)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Find the appropriate analyzer for an operation
+     */
+    findAnalyzer(operation) {
+        for (const analyzer of this.analyzers.values()) {
+            if (analyzer.canAnalyze(operation)) {
+                return analyzer;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Rehearse an operation - analyze its impact before execution
+     *
+     * @param operation - The command or operation to analyze
+     * @returns Impact analysis result
+     */
+    async rehearse(operation) {
+        this.emit({
+            type: 'rehearsal_start',
+            operation,
+            timestamp: new Date(),
+        });
+        const context = {
+            workingDirectory: this.workingDirectory,
+            sessionModifiedFiles: this.getSessionModifiedFiles(),
+            sessionStartTime: this.sessionStartTime,
+        };
+        // Find appropriate analyzer
+        const analyzer = this.findAnalyzer(operation);
+        let result;
+        if (analyzer) {
+            result = await analyzer.analyze(operation, context);
+        }
+        else {
+            // No specific analyzer - return generic result
+            result = {
+                operation,
+                category: 'unknown',
+                isDestructive: false,
+                isReversible: true,
+                impact: {
+                    filesAffected: 0,
+                    linesAffected: 0,
+                    affectedFiles: [],
+                    summary: 'No specific analysis available for this operation',
+                },
+                severity: 'low',
+                warnings: [],
+                recommendation: 'proceed',
+                analysisTimeMs: 0,
+            };
+        }
+        // Emit warning if severity exceeds threshold
+        if (compareSeverity(result.severity, this.warningThreshold) >= 0) {
+            this.emit({
+                type: 'warning_triggered',
+                operation,
+                result,
+                timestamp: new Date(),
+            });
+        }
+        this.emit({
+            type: 'rehearsal_complete',
+            operation,
+            result,
+            timestamp: new Date(),
+        });
+        return result;
+    }
+    /**
+     * Rehearse multiple operations
+     */
+    async rehearseAll(operations) {
+        const results = [];
+        for (const operation of operations) {
+            const result = await this.rehearse(operation);
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * Check if an operation should proceed based on rehearsal
+     *
+     * @returns true if safe to proceed, false if should abort
+     */
+    async shouldProceed(operation) {
+        const result = await this.rehearse(operation);
+        return result.recommendation === 'proceed' || result.recommendation === 'caution';
+    }
+    /**
+     * Get a formatted summary of a rehearsal result
+     */
+    formatResult(result) {
+        const lines = [];
+        // Header
+        lines.push(`=== Rehearsal Analysis ===`);
+        lines.push(`Operation: ${result.operation}`);
+        lines.push(`Category: ${result.category}`);
+        lines.push(`Severity: ${result.severity.toUpperCase()}`);
+        lines.push(`Recommendation: ${result.recommendation.toUpperCase()}`);
+        lines.push('');
+        // Impact summary
+        lines.push(`--- Impact ---`);
+        lines.push(result.impact.summary);
+        if (result.impact.filesAffected > 0) {
+            lines.push(`Files affected: ${String(result.impact.filesAffected)}`);
+        }
+        if (result.impact.linesAffected > 0) {
+            lines.push(`Lines affected: ${String(result.impact.linesAffected)}`);
+        }
+        if (result.impact.timeInvestment) {
+            lines.push(`Time investment: ${result.impact.timeInvestment}`);
+        }
+        lines.push('');
+        // Warnings
+        if (result.warnings.length > 0) {
+            lines.push(`--- Warnings ---`);
+            for (const warning of result.warnings) {
+                lines.push(`⚠️  ${warning}`);
+            }
+            lines.push('');
+        }
+        // Alternatives
+        if (result.alternatives && result.alternatives.length > 0) {
+            lines.push(`--- Safer Alternatives ---`);
+            for (const alt of result.alternatives) {
+                lines.push(`• ${alt}`);
+            }
+            lines.push('');
+        }
+        // Affected files (limited)
+        if (result.impact.affectedFiles.length > 0) {
+            lines.push(`--- Affected Files (first 10) ---`);
+            const filesToShow = result.impact.affectedFiles.slice(0, 10);
+            for (const file of filesToShow) {
+                const info = file.linesAffected ? ` (${String(file.linesAffected)} lines)` : '';
+                lines.push(`• ${file.path}${info}`);
+            }
+            if (result.impact.affectedFiles.length > 10) {
+                lines.push(`... and ${String(result.impact.affectedFiles.length - 10)} more files`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+/**
+ * Create a RehearsalManager with default configuration
+ */
+export function createRehearsalManager(options) {
+    return new RehearsalManager(options);
+}

package/dist/rehearsal/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Rehearsal System Types
+ *
+ * The Rehearsal system provides impact analysis for destructive operations
+ * before they are executed. This is a novel safety feature that goes beyond
+ * simple dry-run by actually analyzing what would be affected.
+ */
+/**
+ * Severity level of the operation's potential impact
+ */
+export type ImpactSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Recommendation based on impact analysis
+ */
+export type RehearsalRecommendation = 'proceed' | 'caution' | 'confirm' | 'abort';
+/**
+ * Category of destructive operation
+ */
+export type OperationCategory = 'git' | 'file' | 'database' | 'network' | 'system' | 'unknown';
+/**
+ * Information about a file that would be affected
+ */
+export interface AffectedFile {
+    /**
+     * Path to the file
+     */
+    path: string;
+    /**
+     * Type of change that would occur
+     */
+    changeType: 'delete' | 'overwrite' | 'reset' | 'modify';
+    /**
+     * Number of lines that would be affected (if applicable)
+     */
+    linesAffected?: number;
+    /**
+     * When the file was last modified
+     */
+    lastModified?: Date;
+    /**
+     * Size of the file in bytes
+     */
+    size?: number;
+    /**
+     * Whether this file has uncommitted changes (for git operations)
+     */
+    hasUncommittedChanges?: boolean;
+}
+/**
+ * Detailed impact analysis of a destructive operation
+ */
+export interface RehearsalImpact {
+    /**
+     * Total number of files that would be affected
+     */
+    filesAffected: number;
+    /**
+     * Total lines of code that would be changed/lost
+     */
+    linesAffected: number;
+    /**
+     * List of affected files with details
+     */
+    affectedFiles: AffectedFile[];
+    /**
+     * Human-readable time investment summary
+     * e.g., "Files modified in the last 2 hours"
+     */
+    timeInvestment?: string;
+    /**
+     * Estimated hours of work that could be lost
+     */
+    estimatedWorkHours?: number;
+    /**
+     * Size of data that would be affected (in bytes)
+     */
+    dataSize?: number;
+    /**
+     * Human-readable summary of the impact
+     */
+    summary: string;
+}
+/**
+ * Result of rehearsing a destructive operation
+ */
+export interface RehearsalResult {
+    /**
+     * The original operation/command being rehearsed
+     */
+    operation: string;
+    /**
+     * Category of the operation
+     */
+    category: OperationCategory;
+    /**
+     * Whether this operation is considered destructive
+     */
+    isDestructive: boolean;
+    /**
+     * Whether the operation can be reversed/undone
+     */
+    isReversible: boolean;
+    /**
+     * Detailed impact analysis
+     */
+    impact: RehearsalImpact;
+    /**
+     * Severity of the potential impact
+     */
+    severity: ImpactSeverity;
+    /**
+     * Warning messages about potential issues
+     */
+    warnings: string[];
+    /**
+     * Recommendation on how to proceed
+     */
+    recommendation: RehearsalRecommendation;
+    /**
+     * Suggested safer alternatives (if any)
+     */
+    alternatives?: string[];
+    /**
+     * Time taken to perform the analysis (ms)
+     */
+    analysisTimeMs: number;
+}
+/**
+ * Context provided to analyzers for better impact assessment
+ */
+export interface RehearsalContext {
+    /**
+     * Working directory for the operation
+     */
+    workingDirectory: string;
+    /**
+     * Whether we're in a git repository
+     */
+    isGitRepo?: boolean;
+    /**
+     * Current git branch (if in a git repo)
+     */
+    currentBranch?: string;
+    /**
+     * Files that have been modified in this session
+     */
+    sessionModifiedFiles?: string[];
+    /**
+     * Start time of the current session (for time investment calculation)
+     */
+    sessionStartTime?: Date;
+    /**
+     * Additional context from the agent
+     */
+    agentContext?: Record<string, unknown>;
+}
+/**
+ * Interface for operation-specific analyzers
+ */
+export interface RehearsalAnalyzer {
+    /**
+     * Unique identifier for this analyzer
+     */
+    readonly id: string;
+    /**
+     * Human-readable name
+     */
+    readonly name: string;
+    /**
+     * Category of operations this analyzer handles
+     */
+    readonly category: OperationCategory;
+    /**
+     * Patterns that this analyzer can handle
+     */
+    readonly patterns: RegExp[];
+    /**
+     * Check if this analyzer can handle the given operation
+     */
+    canAnalyze(operation: string): boolean;
+    /**
+     * Analyze the operation and return impact assessment
+     */
+    analyze(operation: string, context: RehearsalContext): Promise<RehearsalResult>;
+}
+/**
+ * Options for the RehearsalManager
+ */
+export interface RehearsalManagerOptions {
+    /**
+     * Working directory (defaults to process.cwd())
+     */
+    workingDirectory?: string;
+    /**
+     * Custom analyzers to add
+     */
+    analyzers?: RehearsalAnalyzer[];
+    /**
+     * Whether to include built-in analyzers (default: true)
+     */
+    includeBuiltinAnalyzers?: boolean;
+    /**
+     * Minimum severity to trigger warnings (default: 'medium')
+     */
+    warningThreshold?: ImpactSeverity;
+    /**
+     * Callback when a rehearsal is performed
+     */
+    onRehearsal?: (result: RehearsalResult) => void;
+    /**
+     * Session start time for time investment calculations
+     */
+    sessionStartTime?: Date;
+    /**
+     * Track files modified during session
+     */
+    trackSessionFiles?: boolean;
+}
+/**
+ * Event types emitted by RehearsalManager
+ */
+export type RehearsalEventType = 'rehearsal_start' | 'rehearsal_complete' | 'warning_triggered';
+/**
+ * Events emitted during rehearsal
+ */
+export interface RehearsalEvent {
+    type: RehearsalEventType;
+    operation: string;
+    result?: RehearsalResult;
+    timestamp: Date;
+}
+/**
+ * Handler for rehearsal events
+ */
+export type RehearsalEventHandler = (event: RehearsalEvent) => void;

package/dist/rehearsal/types.js

@@ -0,0 +1,8 @@
+/**
+ * Rehearsal System Types
+ *
+ * The Rehearsal system provides impact analysis for destructive operations
+ * before they are executed. This is a novel safety feature that goes beyond
+ * simple dry-run by actually analyzing what would be affected.
+ */
+export {};

package/dist/skills/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Skills System - Prompt expansions for specialized agent behavior
+ *
+ * Skills are reusable prompt templates that can be invoked to provide
+ * specialized capabilities to agents. They allow you to define
+ * domain-specific instructions that can be dynamically added to conversations.
+ */
+/**
+ * Skill definition
+ */
+export interface Skill {
+    /**
+     * Unique identifier for the skill
+     */
+    name: string;
+    /**
+     * Human-readable description of what the skill does
+     */
+    description: string;
+    /**
+     * The prompt content that will be expanded when the skill is invoked
+     */
+    prompt: string;
+    /**
+     * Optional tags for categorization
+     */
+    tags?: string[];
+    /**
+     * Optional version string
+     */
+    version?: string;
+    /**
+     * Whether this skill is enabled (default: true)
+     */
+    enabled?: boolean;
+}
+/**
+ * Result of invoking a skill
+ */
+export interface SkillInvocationResult {
+    /**
+     * The skill that was invoked
+     */
+    skill: Skill;
+    /**
+     * The expanded prompt content
+     */
+    prompt: string;
+    /**
+     * Whether the invocation was successful
+     */
+    success: boolean;
+    /**
+     * Error message if invocation failed
+     */
+    error?: string;
+}
+/**
+ * Options for skill invocation
+ */
+export interface SkillInvokeOptions {
+    /**
+     * Variables to interpolate into the skill prompt
+     * Use {{variable}} syntax in the prompt template
+     */
+    variables?: Record<string, string>;
+    /**
+     * Additional context to prepend to the prompt
+     */
+    context?: string;
+}
+/**
+ * Skill Registry - Manages skill registration and invocation
+ */
+export declare class SkillRegistry {
+    private readonly skills;
+    /**
+     * Register a new skill
+     */
+    register(skill: Skill): void;
+    /**
+     * Register multiple skills at once
+     */
+    registerAll(skills: Skill[]): void;
+    /**
+     * Get a skill by name
+     */
+    get(name: string): Skill | undefined;
+    /**
+     * Check if a skill exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered skills
+     */
+    getAll(): Skill[];
+    /**
+     * Get all enabled skills
+     */
+    getEnabled(): Skill[];
+    /**
+     * Get skills by tag
+     */
+    getByTag(tag: string): Skill[];
+    /**
+     * Get skill names
+     */
+    getNames(): string[];
+    /**
+     * Remove a skill
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all skills
+     */
+    clear(): void;
+    /**
+     * Enable a skill
+     */
+    enable(name: string): boolean;
+    /**
+     * Disable a skill
+     */
+    disable(name: string): boolean;
+    /**
+     * Invoke a skill by name
+     */
+    invoke(name: string, options?: SkillInvokeOptions): SkillInvocationResult;
+    /**
+     * Get skill count
+     */
+    get size(): number;
+}
+/**
+ * Helper function to define a skill
+ */
+export declare function defineSkill(options: {
+    name: string;
+    description: string;
+    prompt: string;
+    tags?: string[];
+    version?: string;
+    enabled?: boolean;
+}): Skill;
+/**
+ * Create a new skill registry
+ */
+export declare function createSkillRegistry(): SkillRegistry;
+/**
+ * Built-in skills that are commonly useful
+ */
+export declare const builtinSkills: Skill[];
+/**
+ * Get the default skill registry
+ */
+export declare function getDefaultSkillRegistry(): SkillRegistry;
+/**
+ * Reset the default registry to built-in skills only
+ */
+export declare function resetDefaultSkillRegistry(): void;