@cdoing/core 0.1.0

package/src/context-providers/tree.ts

@@ -0,0 +1,161 @@
+/**
+ * Tree Context Provider — @tree
+ *
+ * Generates a file tree visualization of the workspace.
+ * Helps the AI understand the project structure at a glance.
+ *
+ * Usage:
+ *   @tree          → full tree (default depth 3)
+ *   @tree src      → tree of a subdirectory
+ *   @tree 5        → custom depth
+ *
+ * How it works:
+ *   1. Walks the directory recursively up to the configured depth
+ *   2. Respects .gitignore patterns
+ *   3. Formats as an ASCII tree (like the `tree` command)
+ *
+ * Learning note: We use recursion with a depth limit to prevent
+ * scanning massive directories. The .gitignore filtering ensures
+ * we don't include node_modules, dist, etc.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Default max depth for tree traversal */
+const DEFAULT_DEPTH = 3;
+
+/** Max items to include in the tree output */
+const MAX_ITEMS = 500;
+
+/** Directories to always skip (even without .gitignore) */
+const ALWAYS_SKIP = new Set([
+  "node_modules", ".git", ".next", ".nuxt", "__pycache__",
+  ".cache", ".turbo", "dist", "build", ".DS_Store",
+  "coverage", ".nyc_output", ".pytest_cache", "venv",
+  ".venv", "env", ".env", ".tox",
+]);
+
+export class TreeContextProvider implements ContextProvider {
+  id = "tree";
+  trigger = "@tree";
+  description = "Show workspace file tree structure";
+  requiresArg = false;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const workingDir = options?.workingDir || process.cwd();
+
+    // Parse argument: could be a path, a depth number, or "path depth"
+    let targetDir = workingDir;
+    let maxDepth = DEFAULT_DEPTH;
+
+    if (arg) {
+      const parts = arg.trim().split(/\s+/);
+      for (const part of parts) {
+        const num = parseInt(part, 10);
+        if (!isNaN(num) && num > 0 && num <= 10) {
+          maxDepth = num;
+        } else {
+          // Treat as a subdirectory path
+          const resolved = path.resolve(workingDir, part);
+          if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+            targetDir = resolved;
+          }
+        }
+      }
+    }
+
+    // Build the tree
+    let itemCount = 0;
+    const lines: string[] = [];
+    const rootName = path.basename(targetDir);
+    lines.push(rootName + "/");
+
+    buildTree(targetDir, "", maxDepth, 0, lines, { count: 0, max: MAX_ITEMS });
+    itemCount = lines.length - 1; // Subtract the root line
+
+    const treeOutput = lines.join("\n");
+    const relativePath = path.relative(workingDir, targetDir) || ".";
+
+    return {
+      label: `File Tree: ${relativePath}`,
+      content: `## File Tree: ${relativePath} (depth: ${maxDepth})\n\n\`\`\`\n${treeOutput}\n\`\`\``,
+      metadata: {
+        source: targetDir,
+        truncated: itemCount >= MAX_ITEMS,
+        itemCount,
+      },
+    };
+  }
+}
+
+/**
+ * Recursively build an ASCII tree representation.
+ *
+ * Uses box-drawing characters for a clean visual:
+ *   ├── file.ts
+ *   ├── src/
+ *   │   ├── index.ts
+ *   │   └── utils/
+ *   └── package.json
+ *
+ * Learning note: The `prefix` parameter builds up as we recurse deeper,
+ * adding "│   " or "    " to maintain the visual tree structure.
+ */
+function buildTree(
+  dir: string,
+  prefix: string,
+  maxDepth: number,
+  currentDepth: number,
+  lines: string[],
+  counter: { count: number; max: number },
+): void {
+  if (currentDepth >= maxDepth || counter.count >= counter.max) return;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // Permission denied or other read errors
+  }
+
+  // Filter out hidden/ignored directories and sort (dirs first, then files)
+  const filtered = entries
+    .filter((e) => !e.name.startsWith(".") || e.name === ".cdoing")
+    .filter((e) => !ALWAYS_SKIP.has(e.name))
+    .sort((a, b) => {
+      // Directories first, then alphabetical
+      if (a.isDirectory() && !b.isDirectory()) return -1;
+      if (!a.isDirectory() && b.isDirectory()) return 1;
+      return a.name.localeCompare(b.name);
+    });
+
+  for (let i = 0; i < filtered.length; i++) {
+    if (counter.count >= counter.max) {
+      lines.push(`${prefix}... [truncated at ${counter.max} items]`);
+      return;
+    }
+
+    const entry = filtered[i];
+    const isLast = i === filtered.length - 1;
+    const connector = isLast ? "└── " : "├── ";
+    const childPrefix = isLast ? "    " : "│   ";
+
+    if (entry.isDirectory()) {
+      lines.push(`${prefix}${connector}${entry.name}/`);
+      counter.count++;
+      buildTree(
+        path.join(dir, entry.name),
+        prefix + childPrefix,
+        maxDepth,
+        currentDepth + 1,
+        lines,
+        counter,
+      );
+    } else {
+      lines.push(`${prefix}${connector}${entry.name}`);
+      counter.count++;
+    }
+  }
+}

package/src/context-providers/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Context Provider Types — Defines the contract for all context providers.
+ *
+ * Learning note: Using interfaces (not classes) keeps this flexible.
+ * Any object that satisfies these shapes can be a context provider,
+ * whether it's a simple object literal or a full class instance.
+ */
+
+/**
+ * The result returned by a context provider after resolving.
+ * Contains the formatted content ready to inject into the prompt.
+ */
+export interface ContextResult {
+  /** Human-readable label shown in the UI (e.g., "Terminal Output") */
+  label: string;
+
+  /** The actual content to inject into the conversation */
+  content: string;
+
+  /** Optional metadata for display purposes */
+  metadata?: {
+    source?: string;       // Where the content came from
+    truncated?: boolean;   // Whether the content was trimmed
+    itemCount?: number;    // Number of items (files, diagnostics, etc.)
+  };
+}
+
+/**
+ * A context provider resolves an @ mention into content.
+ *
+ * Example: "@terminal" → last terminal output
+ *          "@url https://example.com" → fetched page content
+ */
+export interface ContextProvider {
+  /** Unique identifier (e.g., "terminal", "open", "url") */
+  id: string;
+
+  /** The @ trigger keyword (e.g., "@terminal") */
+  trigger: string;
+
+  /** Short description shown in autocomplete */
+  description: string;
+
+  /**
+   * Whether this provider needs an argument after the trigger.
+   * E.g., "@url" needs a URL, but "@terminal" doesn't.
+   */
+  requiresArg: boolean;
+
+  /**
+   * Resolve the context — fetch the actual content.
+   *
+   * @param arg - Optional argument (e.g., URL for @url provider)
+   * @param options - Runtime context (working dir, VS Code API, etc.)
+   * @returns The resolved context content
+   */
+  resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult>;
+}
+
+/**
+ * Options passed to context providers at resolve time.
+ * Provides access to runtime environment without tight coupling.
+ */
+export interface ContextResolveOptions {
+  /** Current working directory */
+  workingDir?: string;
+
+  /** Open file paths (for @open provider) */
+  openFiles?: string[];
+
+  /** Recent terminal output (for @terminal provider) */
+  terminalOutput?: string;
+
+  /** Diagnostics/problems (for @problems provider) */
+  diagnostics?: Array<{
+    file: string;
+    line: number;
+    severity: "error" | "warning" | "info" | "hint";
+    message: string;
+  }>;
+
+  /** Max content length (chars) before truncation */
+  maxContentLength?: number;
+}

package/src/context-providers/url.ts

@@ -0,0 +1,138 @@
+/**
+ * URL Context Provider — @url
+ *
+ * Fetches a web page and converts it to clean markdown for context.
+ * Reuses the existing web_fetch tool logic under the hood.
+ *
+ * Usage: @url https://docs.example.com/api
+ *
+ * How it works:
+ *   1. User types @url followed by a URL
+ *   2. We fetch the page HTML
+ *   3. Strip tags, scripts, styles → extract readable text
+ *   4. Format as markdown and inject into the conversation
+ *
+ * Learning note: This provider REQUIRES an argument (the URL).
+ * The `requiresArg` flag tells the UI to keep the input open
+ * until the user provides the URL after the @ trigger.
+ */
+
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Max chars for fetched content */
+const DEFAULT_MAX_CHARS = 15000;
+
+export class UrlContextProvider implements ContextProvider {
+  id = "url";
+  trigger = "@url";
+  description = "Fetch and attach web page content";
+  requiresArg = true;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    if (!arg || !arg.trim()) {
+      return {
+        label: "URL",
+        content: "[Please provide a URL after @url, e.g.: @url https://docs.example.com]",
+        metadata: { source: "web" },
+      };
+    }
+
+    const url = arg.trim();
+    const maxChars = options?.maxContentLength ?? DEFAULT_MAX_CHARS;
+
+    try {
+      // Fetch the URL content
+      const response = await fetch(url, {
+        headers: {
+          "User-Agent": "Cdoing-Agent/1.0 (Context Fetcher)",
+          "Accept": "text/html,text/plain,application/json",
+        },
+        signal: AbortSignal.timeout(15000), // 15 second timeout
+      });
+
+      if (!response.ok) {
+        return {
+          label: `URL: ${url}`,
+          content: `[Failed to fetch ${url}: HTTP ${response.status} ${response.statusText}]`,
+          metadata: { source: "web" },
+        };
+      }
+
+      const contentType = response.headers.get("content-type") || "";
+      let body = await response.text();
+
+      // Convert HTML to readable text
+      if (contentType.includes("html")) {
+        body = htmlToText(body);
+      }
+
+      // Truncate if needed
+      let truncated = false;
+      if (body.length > maxChars) {
+        body = body.substring(0, maxChars);
+        truncated = true;
+      }
+
+      return {
+        label: `URL: ${url}`,
+        content: `## Web Content: ${url}\n\n${body}${truncated ? "\n\n... [content truncated]" : ""}`,
+        metadata: {
+          source: url,
+          truncated,
+        },
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        label: `URL: ${url}`,
+        content: `[Error fetching ${url}: ${message}]`,
+        metadata: { source: "web" },
+      };
+    }
+  }
+}
+
+/**
+ * Convert HTML to readable plain text.
+ * Strips tags, scripts, styles, and normalizes whitespace.
+ *
+ * Learning note: This is a simple regex-based approach that works
+ * well enough for most pages. For production, you'd use a proper
+ * HTML parser like cheerio or jsdom.
+ */
+function htmlToText(html: string): string {
+  return html
+    // Remove script and style blocks entirely
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, "")
+    // Convert common elements to markdown equivalents
+    .replace(/<h1[^>]*>(.*?)<\/h1>/gi, "\n# $1\n")
+    .replace(/<h2[^>]*>(.*?)<\/h2>/gi, "\n## $1\n")
+    .replace(/<h3[^>]*>(.*?)<\/h3>/gi, "\n### $1\n")
+    .replace(/<h[4-6][^>]*>(.*?)<\/h[4-6]>/gi, "\n#### $1\n")
+    .replace(/<li[^>]*>(.*?)<\/li>/gi, "- $1\n")
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<p[^>]*>/gi, "\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<code[^>]*>(.*?)<\/code>/gi, "`$1`")
+    .replace(/<pre[^>]*>(.*?)<\/pre>/gis, "\n```\n$1\n```\n")
+    .replace(/<a[^>]*href="([^"]*)"[^>]*>(.*?)<\/a>/gi, "[$2]($1)")
+    .replace(/<strong[^>]*>(.*?)<\/strong>/gi, "**$1**")
+    .replace(/<b[^>]*>(.*?)<\/b>/gi, "**$1**")
+    .replace(/<em[^>]*>(.*?)<\/em>/gi, "*$1*")
+    .replace(/<i[^>]*>(.*?)<\/i>/gi, "*$1*")
+    // Strip remaining HTML tags
+    .replace(/<[^>]+>/g, "")
+    // Decode common HTML entities
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ")
+    // Normalize whitespace
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/[ \t]+/g, " ")
+    .trim();
+}

package/src/effort/index.ts

@@ -0,0 +1,177 @@
+/**
+ * Effort Level Control — Adjusts how deeply the agent analyzes requests.
+ *
+ * Inspired by Claude Code's --effort flag and Cursor's MAX mode.
+ *
+ * Effort levels:
+ *   - low:    Quick responses, minimal analysis. Good for simple questions.
+ *   - medium: Default. Balanced analysis and speed.
+ *   - high:   Deep analysis, reads more files, considers edge cases.
+ *   - max:    Extended thinking, comprehensive analysis, multiple passes.
+ *
+ * How it affects behavior:
+ *   - System prompt instructions change based on level
+ *   - Temperature may be adjusted
+ *   - Token limits are scaled
+ *   - The agent is instructed to use more/fewer tools
+ *
+ * Learning note: This is essentially a UX abstraction over multiple
+ * model parameters. Instead of asking users to tweak temperature,
+ * max tokens, and system prompt, they just say "try harder" or
+ * "be quick about it".
+ */
+
+/**
+ * Available effort levels, from quickest to most thorough.
+ */
+export type EffortLevel = "low" | "medium" | "high" | "max";
+
+/**
+ * Configuration values for each effort level.
+ */
+export interface EffortConfig {
+  /** How this level affects the system prompt */
+  systemPromptAddition: string;
+
+  /** Temperature override (null = use default) */
+  temperature: number | null;
+
+  /** Max tokens multiplier (1.0 = default) */
+  maxTokensMultiplier: number;
+
+  /** Max agent turns multiplier */
+  maxTurnsMultiplier: number;
+
+  /** Human-readable description */
+  description: string;
+}
+
+/**
+ * Predefined configurations for each effort level.
+ *
+ * Learning note: These are tuned to balance speed vs thoroughness.
+ * Lower effort = faster, cheaper, more concise.
+ * Higher effort = slower, more expensive, more comprehensive.
+ */
+const EFFORT_CONFIGS: Record<EffortLevel, EffortConfig> = {
+  low: {
+    systemPromptAddition: [
+      "# Effort: Low",
+      "Be very concise. Give the shortest correct answer.",
+      "- Skip detailed explanations unless asked",
+      "- Use the fewest tools possible",
+      "- Don't read files you don't need",
+      "- One-sentence summaries are fine",
+      "- Prefer quick fixes over comprehensive solutions",
+    ].join("\n"),
+    temperature: null,
+    maxTokensMultiplier: 0.5,
+    maxTurnsMultiplier: 0.5,
+    description: "Quick, minimal analysis",
+  },
+
+  medium: {
+    systemPromptAddition: "",  // Default behavior, no additions needed
+    temperature: null,
+    maxTokensMultiplier: 1.0,
+    maxTurnsMultiplier: 1.0,
+    description: "Balanced (default)",
+  },
+
+  high: {
+    systemPromptAddition: [
+      "# Effort: High",
+      "Take extra care with this task. Be thorough.",
+      "- Read all relevant files before making changes",
+      "- Consider edge cases and error scenarios",
+      "- Verify your changes compile/run correctly",
+      "- Explain your reasoning for non-obvious decisions",
+      "- Search for related code that might need updating",
+    ].join("\n"),
+    temperature: null,
+    maxTokensMultiplier: 1.5,
+    maxTurnsMultiplier: 2.0,
+    description: "Deep analysis, thorough",
+  },
+
+  max: {
+    systemPromptAddition: [
+      "# Effort: Maximum",
+      "This is a critical task. Use maximum thoroughness.",
+      "- Exhaustively search the codebase for context",
+      "- Read ALL related files, tests, and documentation",
+      "- Consider architectural implications",
+      "- Check for breaking changes across the project",
+      "- Run tests and verify everything works",
+      "- Think step-by-step before making changes",
+      "- Consider multiple approaches and pick the best one",
+      "- Add proper error handling and edge case coverage",
+    ].join("\n"),
+    temperature: null,
+    maxTokensMultiplier: 2.0,
+    maxTurnsMultiplier: 3.0,
+    description: "Maximum thoroughness, extended thinking",
+  },
+};
+
+/**
+ * Manages the current effort level and provides configuration.
+ */
+export class EffortManager {
+  private level: EffortLevel = "medium";
+
+  /**
+   * Set the effort level.
+   */
+  setLevel(level: EffortLevel): void {
+    if (!EFFORT_CONFIGS[level]) {
+      throw new Error(`Invalid effort level: ${level}. Use: low, medium, high, max`);
+    }
+    this.level = level;
+  }
+
+  /**
+   * Get the current effort level.
+   */
+  getLevel(): EffortLevel {
+    return this.level;
+  }
+
+  /**
+   * Get the configuration for the current effort level.
+   */
+  getConfig(): EffortConfig {
+    return EFFORT_CONFIGS[this.level];
+  }
+
+  /**
+   * Get the system prompt addition for the current level.
+   * Returns empty string for medium (default) level.
+   */
+  getSystemPromptAddition(): string {
+    return EFFORT_CONFIGS[this.level].systemPromptAddition;
+  }
+
+  /**
+   * Get all available levels with descriptions.
+   * Useful for displaying in help or settings UI.
+   */
+  static getAllLevels(): Array<{ level: EffortLevel; description: string }> {
+    return Object.entries(EFFORT_CONFIGS).map(([level, config]) => ({
+      level: level as EffortLevel,
+      description: config.description,
+    }));
+  }
+
+  /**
+   * Parse an effort level from a string (case-insensitive).
+   * Returns null if the string is not a valid level.
+   */
+  static parse(input: string): EffortLevel | null {
+    const normalized = input.toLowerCase().trim();
+    if (normalized in EFFORT_CONFIGS) {
+      return normalized as EffortLevel;
+    }
+    return null;
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,148 @@
+/**
+ * Hooks System — run user-configured shell commands before/after tool execution.
+ *
+ * Configuration stored in ~/.cdoing/hooks.json or .cdoing/hooks.json (project-level).
+ *
+ * Example hooks.json:
+ * {
+ *   "hooks": [
+ *     { "event": "pre:file_write", "command": "echo 'Writing file: {{file_path}}'" },
+ *     { "event": "post:shell_exec", "command": "echo 'Command finished'" },
+ *     { "event": "pre:*", "command": "echo 'Tool called: {{tool_name}}'" }
+ *   ]
+ * }
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { exec } from "child_process";
+
+export interface HookDefinition {
+  /** Event pattern: "pre:tool_name", "post:tool_name", "pre:*", "post:*" */
+  event: string;
+  /** Shell command to execute. Supports {{variable}} placeholders. */
+  command: string;
+  /** Timeout in ms (default: 10000) */
+  timeout?: number;
+}
+
+export interface HookResult {
+  hook: HookDefinition;
+  success: boolean;
+  output: string;
+  error?: string;
+}
+
+export class HookManager {
+  private hooks: HookDefinition[] = [];
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+    this.loadHooks();
+  }
+
+  setWorkingDir(dir: string): void {
+    this.workingDir = dir;
+    this.loadHooks();
+  }
+
+  private loadHooks(): void {
+    this.hooks = [];
+
+    // Load global hooks
+    const globalFile = path.join(os.homedir(), ".cdoing", "hooks.json");
+    this.loadFromFile(globalFile);
+
+    // Load project hooks (overrides/supplements global)
+    const projectFile = path.join(this.workingDir, ".cdoing", "hooks.json");
+    this.loadFromFile(projectFile);
+  }
+
+  private loadFromFile(filePath: string): void {
+    try {
+      if (fs.existsSync(filePath)) {
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        if (Array.isArray(data.hooks)) {
+          this.hooks.push(...data.hooks);
+        }
+      }
+    } catch {
+      // skip invalid files
+    }
+  }
+
+  /** Find hooks matching a given event */
+  private findHooks(event: string): HookDefinition[] {
+    const [phase, toolName] = event.split(":");
+    return this.hooks.filter((h) => {
+      const [hPhase, hTool] = h.event.split(":");
+      return hPhase === phase && (hTool === "*" || hTool === toolName);
+    });
+  }
+
+  /** Run all hooks for an event */
+  async runHooks(
+    event: string,
+    variables: Record<string, string>
+  ): Promise<HookResult[]> {
+    const matching = this.findHooks(event);
+    if (matching.length === 0) return [];
+
+    const results: HookResult[] = [];
+    for (const hook of matching) {
+      const result = await this.executeHook(hook, variables);
+      results.push(result);
+    }
+    return results;
+  }
+
+  /** Execute a single hook */
+  private executeHook(
+    hook: HookDefinition,
+    variables: Record<string, string>
+  ): Promise<HookResult> {
+    // Replace {{variable}} placeholders
+    let command = hook.command;
+    for (const [key, value] of Object.entries(variables)) {
+      command = command.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+    }
+
+    const timeout = hook.timeout || 10000;
+
+    return new Promise((resolve) => {
+      exec(command, {
+        cwd: this.workingDir,
+        timeout,
+        maxBuffer: 1024 * 1024,
+        env: { ...process.env },
+      }, (error, stdout, stderr) => {
+        if (error) {
+          resolve({
+            hook,
+            success: false,
+            output: stdout || "",
+            error: stderr || error.message,
+          });
+        } else {
+          resolve({
+            hook,
+            success: true,
+            output: (stdout || "").trim(),
+          });
+        }
+      });
+    });
+  }
+
+  /** Check if any hooks are configured */
+  hasHooks(): boolean {
+    return this.hooks.length > 0;
+  }
+
+  /** Get all configured hooks */
+  getHooks(): ReadonlyArray<HookDefinition> {
+    return this.hooks;
+  }
+}