@stan-chen/simple-cli 0.2.1

package/dist/skills.js

@@ -0,0 +1,288 @@
+/**
+ * Skills/Presets System
+ * Based on OpenHands skills and Aider prompts
+ * Provides specialized behavior presets for different tasks
+ */
+import { readFile, writeFile, readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+// Built-in skills
+export const builtinSkills = {
+    // Code editing skill (default)
+    code: {
+        name: 'code',
+        description: 'General coding assistant with file editing and custom skill creation capabilities',
+        systemPrompt: `You are a coding assistant. You help users write, modify, and debug code.
+
+## Custom Skills (Self-Evolution)
+You can create your own specialized tools in \`skills/\`, \`scripts/\`, or \`tools/\`:
+1. **TypeScript/JS**: Standard native exports.
+2. **Scripts & Binaries**: 
+   - Write any script (Python, Bash, PowerShell, etc.) or binary.
+   - **Documentation**: Provide a matching \`.md\` or \`.txt\` file (e.g., \`tool.py\` + \`tool.md\`).
+   - **Internal Documentation**: Alternatively, put Markdown in a comment block at the very top of your script.
+   
+3. **AI Attribution**: All self-created tools MUST include a marker as the first line:
+   - **Scripts**: A comment e.g. \`# [Simple-CLI AI-Created]\` or \`// [Simple-CLI AI-Created]\`.
+   - **Documentation**: A hidden comment e.g. \`<!-- [Simple-CLI AI-Created] -->\`.
+
+**Markdown Specification Example**:
+\`\`\`markdown
+<!-- [Simple-CLI AI-Created] -->
+# toolName
+Brief description.
+
+## Command
+python scripts/tool.py
+\`\`\`
+Inputs are passed via **stdin** (JSON) and the \`TOOL_INPUT\` env var.
+After creating/modifying, call \`reloadTools\`.
+
+4. **Self-Orchestration**: If a project lacks clear success criteria (missing \`.agent/\` or \`.simple/\` directories), you should take the initiative to create them. Use these folders to store implementation plans, SPEC/PRDs, and validation tests.
+
+When making changes to files:
+1. Read the file first to understand the context
+2. Make precise, targeted changes using search/replace
+3. Verify changes don't break existing functionality
+4. Follow the existing code style`,
+        tools: ['readFiles', 'writeFiles', 'runCommand', 'glob', 'grep', 'lint', 'reloadTools'],
+    },
+    // Architect skill for planning
+    architect: {
+        name: 'architect',
+        description: 'Design and planning mode - focuses on architecture decisions',
+        systemPrompt: `You are a software architect assistant. Your role is to:
+
+1. Help design system architecture
+2. Make technology decisions
+3. Plan implementation strategies
+4. Review and improve existing designs
+
+When working on architecture:
+- Ask clarifying questions about requirements
+- Consider scalability, maintainability, and security
+- Provide multiple options when appropriate
+- Document decisions and trade-offs
+
+Focus on high-level design rather than implementation details.
+Generate diagrams and documentation when helpful.`,
+        tools: ['readFiles', 'glob', 'grep', 'memory'],
+        modelPreference: 'orchestrator',
+    },
+    // Ask skill for questions only
+    ask: {
+        name: 'ask',
+        description: 'Question-answering mode - no file modifications',
+        systemPrompt: `You are a helpful coding assistant in read-only mode.
+
+You can:
+- Answer questions about the codebase
+- Explain how code works
+- Suggest improvements
+- Help with debugging
+
+You should NOT:
+- Modify any files
+- Run commands that change state
+- Create new files
+
+Always read files before answering questions about them.`,
+        tools: ['readFiles', 'glob', 'grep'],
+    },
+    // Help/docs skill
+    help: {
+        name: 'help',
+        description: 'Help and documentation assistant',
+        systemPrompt: `You are a documentation assistant. Help users understand:
+
+- How to use this CLI tool
+- Programming concepts and patterns
+- Best practices and conventions
+- Error messages and debugging
+
+Be concise and provide examples when helpful.
+Reference official documentation when available.`,
+        tools: ['readFiles', 'scrapeUrl'],
+    },
+    // Test skill
+    test: {
+        name: 'test',
+        description: 'Test writing and debugging assistant',
+        systemPrompt: `You are a test engineering assistant. Your focus is:
+
+1. Writing comprehensive tests
+2. Debugging failing tests
+3. Improving test coverage
+4. Setting up test infrastructure
+
+Test guidelines:
+- Follow the project's existing test patterns
+- Cover edge cases and error conditions
+- Write clear test descriptions
+- Use appropriate mocking when needed
+
+After writing tests, run them to verify they pass.`,
+        tools: ['readFiles', 'writeFiles', 'runCommand', 'glob', 'grep', 'lint'],
+    },
+    // Debug skill
+    debug: {
+        name: 'debug',
+        description: 'Debugging assistant for troubleshooting issues',
+        systemPrompt: `You are a debugging assistant. Your process:
+
+1. Understand the error or unexpected behavior
+2. Reproduce the issue if possible
+3. Analyze logs, stack traces, and code
+4. Form hypotheses about the cause
+5. Test fixes incrementally
+
+Debugging tips:
+- Add logging to understand program flow
+- Check recent changes that might have caused the issue
+- Look for common patterns (null checks, async issues, etc.)
+- Use the linter to catch syntax errors`,
+        tools: ['readFiles', 'writeFiles', 'runCommand', 'grep', 'lint', 'git'],
+    },
+    // Refactor skill
+    refactor: {
+        name: 'refactor',
+        description: 'Code refactoring with safety focus',
+        systemPrompt: `You are a refactoring assistant. Your approach:
+
+1. Understand the current implementation
+2. Identify areas for improvement
+3. Make incremental, safe changes
+4. Verify behavior is preserved
+
+Refactoring principles:
+- Small, focused changes
+- Maintain existing tests
+- Improve readability and maintainability
+- Reduce duplication
+- Follow SOLID principles
+
+Always run tests after refactoring to ensure nothing broke.`,
+        tools: ['readFiles', 'writeFiles', 'runCommand', 'glob', 'grep', 'lint', 'git'],
+    },
+    // Review skill
+    review: {
+        name: 'review',
+        description: 'Code review assistant',
+        systemPrompt: `You are a code reviewer. Review code for:
+
+1. Correctness - Does it work as intended?
+2. Security - Are there vulnerabilities?
+3. Performance - Are there inefficiencies?
+4. Style - Does it follow conventions?
+5. Maintainability - Is it easy to understand?
+
+Provide constructive feedback with specific suggestions.
+Prioritize critical issues over minor style concerns.`,
+        tools: ['readFiles', 'glob', 'grep', 'git', 'lint'],
+    },
+    // Shell skill
+    shell: {
+        name: 'shell',
+        description: 'Shell/command-line assistant',
+        systemPrompt: `You are a shell/command-line assistant. Help with:
+
+- Writing shell scripts
+- Running and debugging commands
+- System administration tasks
+- Build and deployment scripts
+
+Safety guidelines:
+- Explain what commands do before running
+- Use safe defaults (no force flags unless needed)
+- Be careful with destructive operations
+- Test commands before applying to production`,
+        tools: ['runCommand', 'readFiles', 'writeFiles', 'glob'],
+    },
+    // Git skill
+    git: {
+        name: 'git',
+        description: 'Git version control assistant',
+        systemPrompt: `You are a Git assistant. Help with:
+
+- Understanding git history and changes
+- Creating meaningful commits
+- Managing branches
+- Resolving merge conflicts
+- Best practices for version control
+
+Git guidelines:
+- Write clear, descriptive commit messages
+- Make small, focused commits
+- Keep branches up to date
+- Review changes before committing`,
+        tools: ['git', 'readFiles', 'glob', 'grep'],
+    },
+};
+// Get active skill from environment or default
+export function getActiveSkill() {
+    const skillName = process.env.SIMPLE_CLI_SKILL || 'code';
+    return builtinSkills[skillName] || builtinSkills.code;
+}
+// Set active skill
+export function setActiveSkill(name) {
+    if (builtinSkills[name]) {
+        process.env.SIMPLE_CLI_SKILL = name;
+        return builtinSkills[name];
+    }
+    return undefined;
+}
+// List available skills
+export function listSkills() {
+    return Object.values(builtinSkills);
+}
+// Load custom skill from file
+export async function loadSkillFromFile(path) {
+    try {
+        const content = await readFile(path, 'utf-8');
+        const skill = JSON.parse(content);
+        if (!skill.name || !skill.systemPrompt) {
+            return null;
+        }
+        return skill;
+    }
+    catch {
+        return null;
+    }
+}
+// Save custom skill to file
+export async function saveSkillToFile(skill, path) {
+    await writeFile(path, JSON.stringify(skill, null, 2));
+}
+// Load all custom skills from a directory
+export async function loadCustomSkills(dir) {
+    const skills = {};
+    if (!existsSync(dir)) {
+        return skills;
+    }
+    try {
+        const files = await readdir(dir);
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const skill = await loadSkillFromFile(join(dir, file));
+                if (skill) {
+                    skills[skill.name] = skill;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return skills;
+}
+// Get skill system prompt with context
+export function buildSkillPrompt(skill, context) {
+    let prompt = skill.systemPrompt;
+    if (context?.files?.length) {
+        prompt += `\n\n## Active Files\nYou are working with these files:\n${context.files.join('\n')}`;
+    }
+    if (context?.repoMap) {
+        prompt += `\n\n## Repository Structure\n${context.repoMap}`;
+    }
+    return prompt;
+}

package/dist/swarm/coordinator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Swarm Coordinator - Orchestrates multiple workers executing tasks
+ */
+import { EventEmitter } from 'events';
+import type { SwarmTask, CoordinatorOptions, SwarmResult, SwarmEventMap } from './types.js';
+export declare class SwarmCoordinator extends EventEmitter {
+    private options;
+    private taskQueue;
+    private workerPool;
+    private retryPolicy;
+    private running;
+    private startTime;
+    private aborted;
+    constructor(options?: CoordinatorOptions);
+    /**
+     * Add a single task
+     */
+    addTask(task: SwarmTask): void;
+    /**
+     * Add multiple tasks
+     */
+    addTasks(tasks: SwarmTask[]): void;
+    /**
+     * Get next task from queue
+     */
+    getTask(): SwarmTask | null;
+    /**
+     * Peek at next task
+     */
+    peekTask(): SwarmTask | null;
+    /**
+     * Get all workers status
+     */
+    getAllWorkers(): import("./types.js").WorkerStatus[];
+    /**
+     * Get worker status by ID
+     */
+    getWorkerStatus(id: string): import("./types.js").WorkerStatus | undefined;
+    /**
+     * Stop the swarm gracefully
+     */
+    stop(): void;
+    /**
+     * Abort immediately
+     */
+    abort(): void;
+    /**
+     * Run the swarm
+     */
+    run(concurrency?: number): Promise<SwarmResult>;
+    /**
+     * Main processing loop
+     */
+    private processLoop;
+    /**
+     * Execute a single task on a worker
+     */
+    private executeTask;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+    /**
+     * Get queue statistics
+     */
+    getStats(): {
+        total: number;
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+    };
+    /**
+     * Check if swarm is running
+     */
+    isRunning(): boolean;
+    /**
+     * Type-safe event emitter methods
+     */
+    on<K extends keyof SwarmEventMap>(event: K, listener: SwarmEventMap[K]): this;
+    emit<K extends keyof SwarmEventMap>(event: K, ...args: Parameters<SwarmEventMap[K]>): boolean;
+}
+/**
+ * Create a swarm coordinator
+ */
+export declare function createSwarmCoordinator(options?: CoordinatorOptions): SwarmCoordinator;

package/dist/swarm/coordinator.js

@@ -0,0 +1,257 @@
+/**
+ * Swarm Coordinator - Orchestrates multiple workers executing tasks
+ */
+import { EventEmitter } from 'events';
+import { DEFAULT_COORDINATOR_OPTIONS, DEFAULT_RETRY_POLICY } from './types.js';
+import { TaskQueue } from './task.js';
+import { WorkerPool } from './worker.js';
+export class SwarmCoordinator extends EventEmitter {
+    options;
+    taskQueue;
+    workerPool;
+    retryPolicy;
+    running = false;
+    startTime = 0;
+    aborted = false;
+    constructor(options = {}) {
+        super();
+        this.options = {
+            ...DEFAULT_COORDINATOR_OPTIONS,
+            ...options,
+            retryPolicy: {
+                ...DEFAULT_RETRY_POLICY,
+                ...options.retryPolicy,
+            },
+        };
+        this.retryPolicy = this.options.retryPolicy;
+        this.taskQueue = new TaskQueue();
+        this.workerPool = new WorkerPool(this.options.concurrency, {
+            cwd: this.options.cwd,
+            yolo: this.options.yolo,
+            timeout: this.options.timeout,
+        });
+    }
+    /**
+     * Add a single task
+     */
+    addTask(task) {
+        this.taskQueue.addTask(task);
+    }
+    /**
+     * Add multiple tasks
+     */
+    addTasks(tasks) {
+        this.taskQueue.addTasks(tasks);
+    }
+    /**
+     * Get next task from queue
+     */
+    getTask() {
+        return this.taskQueue.getNextTask();
+    }
+    /**
+     * Peek at next task
+     */
+    peekTask() {
+        return this.taskQueue.peekNextTask();
+    }
+    /**
+     * Get all workers status
+     */
+    getAllWorkers() {
+        return this.workerPool.getAllWorkers().map(w => w.getStatus());
+    }
+    /**
+     * Get worker status by ID
+     */
+    getWorkerStatus(id) {
+        return this.workerPool.getWorkerById(id)?.getStatus();
+    }
+    /**
+     * Stop the swarm gracefully
+     */
+    stop() {
+        this.running = false;
+    }
+    /**
+     * Abort immediately
+     */
+    abort() {
+        this.aborted = true;
+        this.running = false;
+        this.workerPool.killAll();
+    }
+    /**
+     * Run the swarm
+     */
+    async run(concurrency) {
+        if (concurrency !== undefined) {
+            this.options.concurrency = concurrency;
+            this.workerPool = new WorkerPool(concurrency, {
+                cwd: this.options.cwd,
+                yolo: this.options.yolo,
+                timeout: this.options.timeout,
+            });
+        }
+        this.running = true;
+        this.aborted = false;
+        this.startTime = Date.now();
+        // Skip tasks blocked by failed dependencies
+        const skipped = this.taskQueue.skipBlockedTasks();
+        for (const taskId of skipped) {
+            const task = this.taskQueue.getTask(taskId);
+            if (task) {
+                this.emit('task:fail', task, new Error('Blocked by failed dependency'));
+            }
+        }
+        // Process tasks
+        await this.processLoop();
+        // Mark as no longer running
+        this.running = false;
+        // Build result
+        const stats = this.taskQueue.getStats();
+        const results = this.taskQueue.getResults();
+        const failures = this.taskQueue.getFailures();
+        const duration = Date.now() - this.startTime;
+        const result = {
+            total: stats.total,
+            completed: stats.completed,
+            failed: stats.failed,
+            skipped: skipped.length,
+            duration,
+            successRate: stats.total > 0 ? stats.completed / stats.total : 0,
+            results,
+            failedTasks: failures,
+        };
+        this.emit('swarm:complete', result);
+        return result;
+    }
+    /**
+     * Main processing loop
+     */
+    async processLoop() {
+        const activePromises = new Map();
+        while (this.running && !this.aborted) {
+            // Check if done
+            if (this.taskQueue.isDone() && activePromises.size === 0) {
+                break;
+            }
+            // Skip blocked tasks
+            const skipped = this.taskQueue.skipBlockedTasks();
+            for (const taskId of skipped) {
+                const task = this.taskQueue.getTask(taskId);
+                if (task) {
+                    this.emit('task:fail', task, new Error('Blocked by failed dependency'));
+                }
+            }
+            // Try to start new tasks
+            while (this.workerPool.getAvailableCount() > 0) {
+                const task = this.taskQueue.getNextTask();
+                if (!task)
+                    break;
+                const worker = this.workerPool.getWorker();
+                if (!worker) {
+                    // No worker available, put task back
+                    this.taskQueue.addTask(task);
+                    break;
+                }
+                // Start task execution
+                const promise = this.executeTask(worker, task);
+                activePromises.set(task.id, promise);
+                promise.finally(() => {
+                    activePromises.delete(task.id);
+                });
+            }
+            // Wait a bit before checking again
+            if (activePromises.size > 0) {
+                await Promise.race([
+                    ...activePromises.values(),
+                    this.sleep(100),
+                ]);
+            }
+            else if (this.taskQueue.hasWork()) {
+                // Have work but no available workers, wait
+                await this.sleep(100);
+            }
+            else {
+                break;
+            }
+        }
+        // Wait for remaining tasks to complete
+        if (activePromises.size > 0) {
+            await Promise.all(activePromises.values());
+        }
+    }
+    /**
+     * Execute a single task on a worker
+     */
+    async executeTask(worker, task) {
+        const attempt = this.taskQueue.getAttempts(task.id) + 1;
+        this.emit('task:start', task, worker.id);
+        if (attempt > 1) {
+            this.emit('task:retry', task, attempt);
+        }
+        try {
+            const result = await worker.execute(task);
+            if (result.success) {
+                const taskResult = {
+                    task,
+                    workerId: worker.id,
+                    result,
+                };
+                this.taskQueue.completeTask(task.id, taskResult);
+                this.emit('task:complete', task, result);
+            }
+            else {
+                const willRetry = this.taskQueue.failTask(task.id, result.error || 'Unknown error', this.retryPolicy.maxRetries);
+                if (!willRetry) {
+                    this.emit('task:fail', task, new Error(result.error || 'Max retries exceeded'));
+                }
+            }
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            const willRetry = this.taskQueue.failTask(task.id, errorMsg, this.retryPolicy.maxRetries);
+            if (!willRetry) {
+                this.emit('task:fail', task, error instanceof Error ? error : new Error(errorMsg));
+            }
+        }
+        finally {
+            // Release worker back to pool
+            this.workerPool.releaseWorker(worker);
+        }
+    }
+    /**
+     * Sleep helper
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Get queue statistics
+     */
+    getStats() {
+        return this.taskQueue.getStats();
+    }
+    /**
+     * Check if swarm is running
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Type-safe event emitter methods
+     */
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+}
+/**
+ * Create a swarm coordinator
+ */
+export function createSwarmCoordinator(options) {
+    return new SwarmCoordinator(options);
+}

package/dist/swarm/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Swarm Module - Coordinate multiple Simple-CLI agents
+ *
+ * @example
+ * ```typescript
+ * import { SwarmCoordinator } from 'simplecli/swarm';
+ *
+ * const coordinator = new SwarmCoordinator({
+ *   cwd: '/path/to/repo',
+ *   concurrency: 4,
+ *   yolo: true,
+ * });
+ *
+ * coordinator.addTasks([
+ *   { id: 'task1', type: 'implement', description: '...', scope: {}, priority: 1, timeout: 300000, retries: 2 },
+ *   { id: 'task2', type: 'test', description: '...', scope: {}, priority: 2, timeout: 180000, retries: 1 },
+ * ]);
+ *
+ * const result = await coordinator.run();
+ * console.log(`Completed: ${result.completed}/${result.total}`);
+ * ```
+ */
+export type { SwarmTask, TaskScope, TaskType, Priority, WorkerStatus, WorkerState, WorkerResult, TaskResult, FailedTask, SwarmResult, CoordinatorOptions, RetryPolicy, SwarmEventMap, } from './types.js';
+export { swarmTaskSchema, taskScopeSchema, DEFAULT_RETRY_POLICY, DEFAULT_COORDINATOR_OPTIONS, } from './types.js';
+export { TaskQueue } from './task.js';
+export { Worker, WorkerPool } from './worker.js';
+export type { WorkerOptions } from './worker.js';
+export { SwarmCoordinator, createSwarmCoordinator } from './coordinator.js';

package/dist/swarm/index.js

@@ -0,0 +1,29 @@
+/**
+ * Swarm Module - Coordinate multiple Simple-CLI agents
+ *
+ * @example
+ * ```typescript
+ * import { SwarmCoordinator } from 'simplecli/swarm';
+ *
+ * const coordinator = new SwarmCoordinator({
+ *   cwd: '/path/to/repo',
+ *   concurrency: 4,
+ *   yolo: true,
+ * });
+ *
+ * coordinator.addTasks([
+ *   { id: 'task1', type: 'implement', description: '...', scope: {}, priority: 1, timeout: 300000, retries: 2 },
+ *   { id: 'task2', type: 'test', description: '...', scope: {}, priority: 2, timeout: 180000, retries: 1 },
+ * ]);
+ *
+ * const result = await coordinator.run();
+ * console.log(`Completed: ${result.completed}/${result.total}`);
+ * ```
+ */
+export { swarmTaskSchema, taskScopeSchema, DEFAULT_RETRY_POLICY, DEFAULT_COORDINATOR_OPTIONS, } from './types.js';
+// Task Queue
+export { TaskQueue } from './task.js';
+// Worker
+export { Worker, WorkerPool } from './worker.js';
+// Coordinator
+export { SwarmCoordinator, createSwarmCoordinator } from './coordinator.js';