pulse-coder-engine 0.0.1-alpha.1

package/src/plugin/UserConfigPlugin.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+
+/**
+ * 用户配置插件接口 - 面向终端用户
+ * 使用声明式配置扩展引擎能力
+ */
+export interface UserConfigPlugin {
+  version: string;
+  name?: string;
+  description?: string;
+
+  // 工具配置 - 使用现有工具类型的具体配置
+  tools?: Record<string, ToolConfig>;
+
+  // MCP 服务器配置
+  mcp?: {
+    servers: MCPServerConfig[];
+  };
+
+  // 提示词配置
+  prompts?: {
+    system?: string;
+    user?: string;
+    assistant?: string;
+  };
+
+  // 子代理配置
+  subAgents?: SubAgentConfig[];
+
+  // 技能配置 (向后兼容)
+  skills?: {
+    directories?: string[];
+    autoScan?: boolean;
+    cache?: boolean;
+  };
+
+  // 环境配置
+  env?: Record<string, string>;
+
+  // 条件配置
+  conditions?: {
+    environment?: string;
+    features?: string[];
+  };
+}
+
+/**
+ * 工具配置接口
+ */
+export const ToolConfigSchema = z.object({
+  type: z.enum(['bash', 'http', 'javascript', 'skill', 'custom']),
+
+  // Bash 工具配置
+  command: z.string().optional(),
+  args: z.array(z.string()).optional(),
+  cwd: z.string().optional(),
+  env: z.any().optional(),
+  timeout: z.number().optional(),
+
+  // HTTP 工具配置
+  method: z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).optional(),
+  url: z.string().optional(),
+  baseUrl: z.string().optional(),
+  headers: z.any().optional(),
+  params: z.any().optional(),
+  data: z.any().optional(),
+
+  // JavaScript 工具配置
+  code: z.string().optional(),
+
+  // 通用字段
+  description: z.string().optional(),
+  enabled: z.boolean().optional().default(true),
+
+  // 条件字段
+  conditions: z.object({
+    environment: z.string().optional(),
+    platform: z.string().optional()
+  }).optional()
+});
+
+export type ToolConfig = z.infer<typeof ToolConfigSchema>;
+
+/**
+ * MCP 服务器配置接口
+ */
+export const MCPServerConfigSchema = z.object({
+  name: z.string(),
+  command: z.string(),
+  args: z.array(z.string()).optional(),
+  env: z.any().optional(),
+  cwd: z.string().optional(),
+  timeout: z.number().optional(),
+  description: z.string().optional(),
+  enabled: z.boolean().optional().default(true)
+});
+
+export type MCPServerConfig = z.infer<typeof MCPServerConfigSchema>;
+
+/**
+ * 子代理配置接口
+ */
+export const SubAgentConfigSchema = z.object({
+  name: z.string(),
+  trigger: z.array(z.string()),
+  prompt: z.string(),
+  model: z.string().optional(),
+  temperature: z.number().optional(),
+  maxTokens: z.number().optional(),
+  tools: z.array(z.string()).optional(),
+  enabled: z.boolean().optional().default(true)
+});
+
+export type SubAgentConfig = z.infer<typeof SubAgentConfigSchema>;
+
+/**
+ * 用户配置插件加载选项
+ */
+export interface UserConfigPluginLoadOptions {
+  configs?: UserConfigPlugin[];
+  dirs?: string[];
+  scan?: boolean;
+}
+
+/**
+ * 默认用户配置插件目录
+ */
+export const DEFAULT_USER_CONFIG_PLUGIN_DIRS = [
+  '.pulse-coder/config',
+  '.coder/config',
+  '~/.pulse-coder/config',
+  '~/.coder/config',
+  './config'
+];
+
+/**
+ * 支持的文件格式
+ */
+export const SUPPORTED_CONFIG_FORMATS = ['.json', '.yaml', '.yml'];
+
+/**
+ * 配置验证结果
+ */
+export interface ConfigValidationResult {
+  valid: boolean;
+  errors?: string[];
+  warnings?: string[];
+}
+
+/**
+ * 环境变量替换工具
+ */
+export class ConfigVariableResolver {
+  private env: Record<string, string>;
+
+  constructor(env: Record<string, string> = {}) {
+    this.env = env;
+  }
+
+  resolve(value: string): string {
+    return value.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+      const [name, defaultValue] = varName.split(':-');
+      return this.env[name] || defaultValue || match;
+    });
+  }
+
+  resolveObject(obj: any): any {
+    if (typeof obj === 'string') {
+      return this.resolve(obj);
+    }
+    if (Array.isArray(obj)) {
+      return obj.map(item => this.resolveObject(item));
+    }
+    if (typeof obj === 'object' && obj !== null) {
+      const resolved: any = {};
+      for (const [key, value] of Object.entries(obj)) {
+        resolved[key] = this.resolveObject(value);
+      }
+      return resolved;
+    }
+    return obj;
+  }
+}

package/src/prompt/index.ts

@@ -0,0 +1 @@
+export * from './system';

package/src/prompt/system.ts

@@ -0,0 +1,126 @@
+export const generateSystemPrompt = () => {
+  const basePrompt = `
+You are Pulse Coder, the best coding agent on the planet.
+
+You are an interactive CLI tool that helps users with software engineering tasks. Use the instructions below and the tools available to you to assist the user.
+
+## Editing constraints
+- Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
+- Only add comments if they are necessary to make a non-obvious block easier to understand.
+- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
+
+## Skills
+- If query matches an available skill's description or instruction [use skill], use the skill tool to get detailed instructions.
+- You should Load a skill to get detailed instructions for a specific task. It always is a complex task that requires multiple steps.
+- You should check the skill is complete and follow the step-by-step guidance. If the skill is not complete, you should ask the user for more information.
+
+## Tool usage
+- Prefer specialized tools over shell for file operations:
+  - Use Read to view files, Edit to modify files, and Write only when needed.
+  - Use Glob to find files by name and Grep to search file contents.
+- Use Bash for terminal operations (git, bun, builds, tests, running scripts).
+- Run tool calls in parallel when neither call needs the other’s output; otherwise run sequentially.
+
+## Git and workspace hygiene
+- You may be in a dirty git worktree.
+    * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
+    * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
+    * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
+    * If the changes are in unrelated files, just ignore them and don't revert them.
+- Do not amend commits unless explicitly requested.
+- **NEVER** use destructive commands like \`git reset --hard\` or \`git checkout--\` unless specifically requested or approved by the user.
+
+## Frontend tasks
+When doing frontend design tasks, avoid collapsing into bland, generic layouts.
+Aim for interfaces that feel intentional and deliberate.
+- Typography: Use expressive, purposeful fonts and avoid default stacks (Inter, Roboto, Arial, system).
+- Color & Look: Choose a clear visual direction; define CSS variables; avoid purple-on-white defaults. No purple bias or dark mode bias.
+- Motion: Use a few meaningful animations (page-load, staggered reveals) instead of generic micro-motions.
+- Background: Don't rely on flat, single-color backgrounds; use gradients, shapes, or subtle patterns to build atmosphere.
+- Overall: Avoid boilerplate layouts and interchangeable UI patterns. Vary themes, type families, and visual languages across outputs.
+- Ensure the page loads properly on both desktop and mobile.
+
+Exception: If working within an existing website or design system, preserve the established patterns, structure, and visual language.
+
+## Presenting your work and final message
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+- Default: be very concise; friendly coding teammate tone.
+- Default: do the work without asking questions. Treat short tasks as sufficient direction; infer missing details by reading the codebase and following existing conventions.
+- Questions: only ask when you are truly blocked after checking relevant context AND you cannot safely pick a reasonable default. This usually means one of:
+  * The request is ambiguous in a way that materially changes the result and you cannot disambiguate by reading the repo.
+  * The action is destructive/irreversible, touches production, or changes billing/security posture.
+  * You need a secret/credential/value that cannot be inferred (API key, account id, etc.).
+- If you must ask: do all non-blocked work first, then ask exactly one targeted question, include your recommended default, and state what would change based on the answer.
+- Never ask permission questions like "Should I proceed?" or "Do you want me to run tests?"; proceed with the most reasonable option and mention what you did.
+
+## Clarification Tool
+
+Use the 'clarify' tool when you genuinely need information from the user to proceed. This tool pauses execution and waits for user input.
+
+**When to use clarify:**
+- The request is ambiguous in a way that materially affects the implementation and cannot be resolved by reading the codebase
+- You cannot safely infer the answer from existing code, conventions, or context
+- You need confirmation before destructive or irreversible actions (e.g., deleting resources, modifying production data)
+- You need specific values that cannot be guessed (API keys, account IDs, specific user choices between valid alternatives)
+
+**When NOT to use clarify:**
+- For trivial decisions you can make based on codebase conventions or common practices
+- For permission questions like "Should I proceed?" (just proceed with the best option)
+- For information that's likely in the codebase, configuration files, or documentation (read those first)
+- Multiple times in a row - complete all non-blocked work first, then ask one clear question
+- For choices where a reasonable default exists (use the default and mention what you chose)
+
+**How to use clarify:**
+- Ask ONE clear, specific question per clarification
+- Provide context if needed to help the user understand the choice
+- Include a recommended default answer when applicable
+- Explain briefly what would change based on the answer
+
+Example usage: Call clarify with a question, optional context, and optional default answer. The tool will pause and wait for the user's response.
+- For substantial work, summarize clearly; follow final‑answer formatting.
+- Skip heavy formatting for simple confirmations.
+- Don't dump large files you've written; reference paths only.
+- No "save/copy this file" - User is on the same machine.
+- Offer logical next steps (tests, commits, build) briefly; add verify steps if you couldn't do something.
+- For code changes:
+  * Lead with a quick explanation of the change, and then give more details on the context covering where and why a change was made. Do not start this explanation with "summary", just jump right in.
+  * If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps.
+  * When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.
+- The user does not command execution outputs. When asked to show the output of a command (e.g. \`git show\`), relay the important details in your answer or summarize the key lines so the user understands the result.
+
+## Final answer structure and style guidelines
+
+- Plain text; CLI handles styling. Use structure only when it helps scanability.
+- Headers: optional; short Title Case (1-3 words) wrapped in **…**; no blank line before the first bullet; add only if they truly help.
+- Bullets: use - ; merge related points; keep to one line when possible; 4–6 per list ordered by importance; keep phrasing consistent.
+- Monospace: backticks for commands/paths/env vars/code ids and inline examples; use for literal keyword bullets; never combine with **.
+- Code samples or multi-line snippets should be wrapped in fenced code blocks; include an info string as often as possible.
+- Structure: group related bullets; order sections general → specific → supporting; for subsections, start with a bolded keyword bullet, then items; match complexity to the task.
+- Tone: collaborative, concise, factual; present tense, active voice; self‑contained; no "above/below"; parallel wording.
+- Don'ts: no nested bullets/hierarchies; no ANSI codes; don't cram unrelated keywords; keep keyword lists short—wrap/reformat if long; avoid naming formatting styles in answers.
+- Adaptation: code explanations → precise, structured with code refs; simple tasks → lead with outcome; big changes → logical walkthrough + rationale + next actions; casual one-offs → plain sentences, no headers/bullets.
+- File References: When referencing files in your response follow the below rules:
+  * Use inline code to make file paths clickable.
+  * Each reference should have a stand alone path. Even if it's the same file.
+  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
+  * Optionally include line/column (1‑based): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
+  * Do not use URIs like file://, vscode://, or https://.
+  * Do not provide range of lines
+  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\project\main.rs:12:5
+
+Here is some useful information about the environment you are running in:
+<env>
+  Working directory: ${process.cwd()}
+  Platform: darwin
+  Today's date: ${new Date().toLocaleDateString()}
+</env>
+<files>
+
+</files>`;
+
+  return basePrompt;
+};
+
+export default generateSystemPrompt;

package/src/shared/types.ts

@@ -0,0 +1,50 @@
+import type { FlexibleSchema, ModelMessage } from "ai";
+
+export interface ClarificationRequest {
+  id: string;
+  question: string;
+  context?: string;
+  defaultAnswer?: string;
+  timeout: number;
+}
+
+export interface ToolExecutionContext {
+  onClarificationRequest?: (request: ClarificationRequest) => Promise<string>;
+  abortSignal?: AbortSignal;
+}
+
+export interface Tool<Input = any, Output = any> {
+  name: string;
+  description: string;
+  inputSchema: FlexibleSchema<Input>;
+  execute: (input: Input, context?: ToolExecutionContext) => Promise<Output>;
+}
+
+export interface Context {
+  messages: ModelMessage[];
+}
+
+export interface IPlugin {
+  name: string;
+  version: string;
+  extensions: Extension[];
+  activate(context: IExtensionContext): Promise<void>;
+  deactivate?(): Promise<void>;
+}
+
+export interface Extension {
+  type: 'skill' | 'mcp' | 'tool' | 'context';
+  provider: any;
+}
+
+export interface IExtensionContext {
+  registerTools(toolName: string, tool: Tool<any, any>): void;
+  logger: ILogger;
+}
+
+export interface ILogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, error?: Error, meta?: Record<string, unknown>): void;
+}

package/src/tools/bash.ts

@@ -0,0 +1,59 @@
+import z from "zod";
+import { execSync } from "child_process";
+import type { Tool } from "../shared/types";
+import { truncateOutput } from "./utils";
+
+export const BashTool: Tool<
+  { command: string; timeout?: number; cwd?: string; description?: string },
+  { output: string; error?: string; exitCode?: number }
+> = {
+  name: 'bash',
+  description: 'Execute a bash command and return the output. Supports timeout and working directory configuration.',
+  inputSchema: z.object({
+    command: z.string().describe('The bash command to execute'),
+    timeout: z.number().optional().describe('Optional timeout in milliseconds (max 600000ms / 10 minutes). Defaults to 120000ms (2 minutes).'),
+    cwd: z.string().optional().describe('Optional working directory for command execution. Defaults to current directory.'),
+    description: z.string().optional().describe('Optional description of what this command does (for logging/debugging)'),
+  }),
+  execute: async ({ command, timeout = 120000, cwd, description }) => {
+    // Validate timeout
+    if (timeout && (timeout < 0 || timeout > 600000)) {
+      throw new Error('Timeout must be between 0 and 600000ms (10 minutes)');
+    }
+
+    try {
+      const output = execSync(command, {
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024 * 10, // 10MB
+        timeout: timeout || 120000,
+        cwd: cwd || process.cwd(),
+        shell: '/bin/bash',
+      });
+      return {
+        output: truncateOutput(output || '(command completed with no output)'),
+        exitCode: 0,
+      };
+    } catch (error: any) {
+      const exitCode = error.status || error.code || 1;
+      const stdout = String(error.stdout || '');
+      const stderr = String(error.stderr || error.message || '');
+
+      // Check if it's a timeout error
+      if (error.killed && error.signal === 'SIGTERM') {
+        return {
+          output: truncateOutput(stdout),
+          error: truncateOutput(`Command timed out after ${timeout}ms\n${stderr}`),
+          exitCode,
+        };
+      }
+
+      return {
+        output: truncateOutput(stdout),
+        error: truncateOutput(stderr),
+        exitCode,
+      };
+    }
+  },
+};
+
+export default BashTool;

package/src/tools/clarify.ts

@@ -0,0 +1,74 @@
+import z from "zod";
+import type { Tool, ToolExecutionContext } from "../shared/types";
+import { CLARIFICATION_TIMEOUT } from "../config/index.js";
+import { randomUUID } from "crypto";
+
+export interface ClarifyInput {
+  question: string;
+  context?: string;
+  defaultAnswer?: string;
+  timeout?: number;
+}
+
+export interface ClarifyOutput {
+  answer: string;
+  timedOut: boolean;
+}
+
+export const ClarifyTool: Tool<ClarifyInput, ClarifyOutput> = {
+  name: 'clarify',
+  description: 'Ask the user a clarifying question and wait for their response. Use this when you need information from the user to proceed with the task.',
+  inputSchema: z.object({
+    question: z.string().describe('The question to ask the user'),
+    context: z.string().optional().describe('Additional context to help the user answer'),
+    defaultAnswer: z.string().optional().describe('Default answer if user does not respond within timeout'),
+    timeout: z.number().optional().describe('Timeout in milliseconds (default: 5 minutes)')
+  }),
+  execute: async (input, toolContext) => {
+    if (!toolContext?.onClarificationRequest) {
+      throw new Error('Clarification is not supported in this context. The clarify tool requires a CLI interface with user interaction.');
+    }
+
+    const timeout = input.timeout ?? CLARIFICATION_TIMEOUT;
+    const requestId = randomUUID();
+
+    try {
+      // Create a promise that rejects on timeout
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Clarification request timed out after ${timeout}ms`));
+        }, timeout);
+      });
+
+      // Race between user response and timeout
+      const answer = await Promise.race([
+        toolContext.onClarificationRequest({
+          id: requestId,
+          question: input.question,
+          context: input.context,
+          defaultAnswer: input.defaultAnswer,
+          timeout
+        }),
+        timeoutPromise
+      ]);
+
+      return {
+        answer,
+        timedOut: false
+      };
+    } catch (error: any) {
+      // If timeout occurred and we have a default answer, use it
+      if (error?.message?.includes('timed out') && input.defaultAnswer) {
+        return {
+          answer: input.defaultAnswer,
+          timedOut: true
+        };
+      }
+
+      // Otherwise, re-throw the error
+      throw error;
+    }
+  },
+};
+
+export default ClarifyTool;

package/src/tools/edit.ts

@@ -0,0 +1,79 @@
+import z from "zod";
+import { readFileSync, writeFileSync } from "fs";
+import type { Tool } from "../shared/types";
+import { truncateOutput } from "./utils";
+
+export const EditTool: Tool<
+  { filePath: string; oldString: string; newString: string; replaceAll?: boolean },
+  { success: boolean; replacements: number; preview?: string }
+> = {
+  name: 'edit',
+  description: 'Performs exact string replacements in files. Use this to edit existing files by replacing old_string with new_string.',
+  inputSchema: z.object({
+    filePath: z.string().describe('The absolute path to the file to modify'),
+    oldString: z.string().describe('The exact text to replace (must match exactly)'),
+    newString: z.string().describe('The text to replace it with (must be different from old_string)'),
+    replaceAll: z.boolean().optional().default(false).describe('Replace all occurrences of old_string (default false)'),
+  }),
+  execute: async ({ filePath, oldString, newString, replaceAll = false }) => {
+    // Validate that old and new strings are different
+    if (oldString === newString) {
+      throw new Error('old_string and new_string must be different');
+    }
+
+    // Read the file
+    const content = readFileSync(filePath, 'utf-8');
+
+    // Check if oldString exists in the file
+    if (!content.includes(oldString)) {
+      throw new Error(`old_string not found in file: ${filePath}`);
+    }
+
+    let newContent: string;
+    let replacements = 0;
+
+    if (replaceAll) {
+      // Replace all occurrences
+      const parts = content.split(oldString);
+      replacements = parts.length - 1;
+      newContent = parts.join(newString);
+    } else {
+      // Replace only the first occurrence
+      const index = content.indexOf(oldString);
+      if (index === -1) {
+        throw new Error(`old_string not found in file: ${filePath}`);
+      }
+
+      // Check if the string is unique (appears only once)
+      const secondIndex = content.indexOf(oldString, index + oldString.length);
+      if (secondIndex !== -1) {
+        throw new Error(
+          'old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance.'
+        );
+      }
+
+      newContent = content.slice(0, index) + newString + content.slice(index + oldString.length);
+      replacements = 1;
+    }
+
+    // Write the modified content back
+    writeFileSync(filePath, newContent, 'utf-8');
+
+    // Generate a preview of the changes (show the changed section with context)
+    const changedIndex = newContent.indexOf(newString);
+    const contextLength = 200;
+    const start = Math.max(0, changedIndex - contextLength);
+    const end = Math.min(newContent.length, changedIndex + newString.length + contextLength);
+    const preview = truncateOutput(
+      `...${newContent.slice(start, end)}...`
+    );
+
+    return {
+      success: true,
+      replacements,
+      preview,
+    };
+  },
+};
+
+export default EditTool;