@cdoing/core 0.1.0

package/src/context-providers/folder.ts

@@ -0,0 +1,106 @@
+/**
+ * Folder Context Provider — @folder
+ *
+ * Includes all files from a directory as context.
+ * Usage:
+ *   @folder src/utils     — include all files from src/utils
+ *   @folder src/api 5     — include files, max 5 files
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+const MAX_FILES = 20;
+const MAX_FILE_CHARS = 3000;
+const MAX_TOTAL_CHARS = 50000;
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "__pycache__", ".cache", "coverage"]);
+
+export class FolderContextProvider implements ContextProvider {
+  id = "folder";
+  trigger = "@folder";
+  description = "Include all files from a directory as context";
+  requiresArg = true;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    if (!arg?.trim()) {
+      return { label: "Folder", content: "Usage: @folder <directory> [maxFiles]" };
+    }
+
+    const parts = arg.trim().split(/\s+/);
+    const dirPath = parts[0];
+    const maxFiles = parseInt(parts[1], 10) || MAX_FILES;
+    const workingDir = options?.workingDir || process.cwd();
+    const fullPath = path.isAbsolute(dirPath) ? dirPath : path.resolve(workingDir, dirPath);
+
+    if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isDirectory()) {
+      return { label: "Folder", content: `Directory not found: ${dirPath}` };
+    }
+
+    const files = this.collectFiles(fullPath, maxFiles);
+    if (files.length === 0) {
+      return { label: `Folder: ${dirPath}`, content: `No files found in ${dirPath}` };
+    }
+
+    let totalChars = 0;
+    const sections: string[] = [`## Folder: ${dirPath} (${files.length} files)`];
+
+    for (const file of files) {
+      if (totalChars >= MAX_TOTAL_CHARS) {
+        sections.push(`\n... [truncated, ${MAX_TOTAL_CHARS} char limit reached]`);
+        break;
+      }
+
+      const rel = path.relative(fullPath, file);
+      try {
+        let content = fs.readFileSync(file, "utf-8");
+        if (content.length > MAX_FILE_CHARS) {
+          content = content.substring(0, MAX_FILE_CHARS) + "\n... [truncated]";
+        }
+        const ext = path.extname(file).substring(1) || "txt";
+        sections.push(`\n### ${rel}\n\`\`\`${ext}\n${content}\n\`\`\``);
+        totalChars += content.length;
+      } catch {
+        sections.push(`\n### ${rel}\n(unable to read)`);
+      }
+    }
+
+    return {
+      label: `Folder: ${dirPath}`,
+      content: sections.join("\n"),
+      metadata: { itemCount: files.length },
+    };
+  }
+
+  private collectFiles(dir: string, limit: number): string[] {
+    const result: string[] = [];
+    this.walk(dir, result, limit);
+    return result;
+  }
+
+  private walk(dir: string, result: string[], limit: number): void {
+    if (result.length >= limit) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    // Files first, then directories
+    const files = entries.filter((e) => e.isFile());
+    const dirs = entries.filter((e) => e.isDirectory() && !SKIP_DIRS.has(e.name) && !e.name.startsWith("."));
+
+    for (const f of files) {
+      if (result.length >= limit) return;
+      result.push(path.join(dir, f.name));
+    }
+
+    for (const d of dirs) {
+      if (result.length >= limit) return;
+      this.walk(path.join(dir, d.name), result, limit);
+    }
+  }
+}

package/src/context-providers/git.ts

@@ -0,0 +1,72 @@
+/**
+ * Git Context Provider — @git
+ *
+ * Provides git context: branch, status, recent commits, blame, log.
+ * Usage:
+ *   @git              — branch + status + recent commits
+ *   @git log 20       — last 20 commits
+ *   @git blame file   — blame for a file
+ *   @git branch       — all branches
+ */
+
+import { exec } from "child_process";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+export class GitContextProvider implements ContextProvider {
+  id = "git";
+  trigger = "@git";
+  description = "Git context: branch, status, commits, blame";
+  requiresArg = false;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const workingDir = options?.workingDir || process.cwd();
+    const parts = (arg || "").trim().split(/\s+/);
+    const subcommand = parts[0] || "";
+
+    try {
+      switch (subcommand) {
+        case "log": {
+          const count = parseInt(parts[1], 10) || 10;
+          const log = await run(`git log --oneline -${count}`, workingDir);
+          return { label: `Git log (${count})`, content: `## Git Log (last ${count} commits)\n\`\`\`\n${log}\n\`\`\`` };
+        }
+        case "blame": {
+          const file = parts[1];
+          if (!file) return { label: "Git blame", content: "Usage: @git blame <file>" };
+          const blame = await run(`git blame --line-porcelain "${file}" | grep -E "^(author |summary |\t)" | head -100`, workingDir);
+          return { label: `Git blame: ${file}`, content: `## Git Blame: ${file}\n\`\`\`\n${blame}\n\`\`\`` };
+        }
+        case "branch": {
+          const branches = await run("git branch -a --no-color", workingDir);
+          return { label: "Git branches", content: `## Git Branches\n\`\`\`\n${branches}\n\`\`\`` };
+        }
+        default: {
+          // Default: branch + status + recent commits
+          const [branch, status, log] = await Promise.all([
+            run("git branch --show-current", workingDir),
+            run("git status --short", workingDir),
+            run("git log --oneline -10", workingDir),
+          ]);
+          const sections = [
+            `## Git Context`,
+            `**Branch:** ${branch.trim()}`,
+            `\n### Status\n\`\`\`\n${status.trim() || "(clean)"}\n\`\`\``,
+            `\n### Recent Commits\n\`\`\`\n${log.trim()}\n\`\`\``,
+          ];
+          return { label: `Git: ${branch.trim()}`, content: sections.join("\n") };
+        }
+      }
+    } catch (err) {
+      return { label: "Git", content: `Git error: ${(err as Error).message}` };
+    }
+  }
+}
+
+function run(command: string, cwd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec(command, { cwd, timeout: 10000, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err && !stdout) return reject(new Error(stderr?.trim() || err.message));
+      resolve(stdout);
+    });
+  });
+}

package/src/context-providers/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Context Providers — Pluggable system for injecting context into chat messages.
+ *
+ * Each provider implements a simple interface:
+ *   - id: unique name (e.g., "terminal", "open", "url")
+ *   - trigger: the @ keyword that activates it (e.g., "@terminal")
+ *   - resolve(): fetches and returns the context content
+ *
+ * This module re-exports all built-in context providers and the
+ * registry that manages them.
+ *
+ * Learning note: This follows the Strategy Pattern — each provider
+ * encapsulates a different way to gather context, and the registry
+ * lets you swap/add providers without modifying consuming code.
+ */
+
+export { ContextProviderRegistry } from "./registry";
+export type { ContextProvider, ContextResult } from "./types";
+export { TerminalContextProvider } from "./terminal";
+export { OpenFilesContextProvider } from "./open-files";
+export { UrlContextProvider } from "./url";
+export { TreeContextProvider } from "./tree";
+export { ProblemsContextProvider } from "./problems";
+export { CodebaseContextProvider } from "./codebase";
+export { ClipboardContextProvider } from "./clipboard";
+export { FileIncludeContextProvider } from "./file-include";

package/src/context-providers/open-files.ts

@@ -0,0 +1,113 @@
+/**
+ * Open Files Context Provider — @open
+ *
+ * Attaches the content of all currently open editor tabs.
+ * Useful for providing broad context about what the user is working on.
+ *
+ * How it works:
+ *   1. Receives list of open file paths from the IDE
+ *   2. Reads each file's content
+ *   3. Formats them with file headers for the LLM
+ *   4. Applies smart truncation for large files
+ *
+ * Learning note: We truncate large files rather than skipping them
+ * entirely — the file header + first N lines still provides useful
+ * context about the file's purpose and structure.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Max chars per file before truncation */
+const PER_FILE_LIMIT = 5000;
+
+/** Max total chars for all open files combined */
+const TOTAL_LIMIT = 30000;
+
+export class OpenFilesContextProvider implements ContextProvider {
+  id = "open";
+  trigger = "@open";
+  description = "Include all open editor files";
+  requiresArg = false;
+
+  async resolve(_arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const openFiles = options?.openFiles || [];
+    const workingDir = options?.workingDir || process.cwd();
+
+    if (openFiles.length === 0) {
+      return {
+        label: "Open Files",
+        content: "[No files are currently open in the editor.]",
+        metadata: { source: "editor", itemCount: 0 },
+      };
+    }
+
+    const sections: string[] = [];
+    let totalChars = 0;
+    let truncatedCount = 0;
+
+    for (const filePath of openFiles) {
+      // Resolve relative paths against working directory
+      const absPath = path.isAbsolute(filePath)
+        ? filePath
+        : path.join(workingDir, filePath);
+
+      // Read file content safely
+      let content: string;
+      try {
+        content = fs.readFileSync(absPath, "utf-8");
+      } catch {
+        sections.push(`### ${filePath}\n\n[Unable to read file]`);
+        continue;
+      }
+
+      // Truncate individual files that are too large
+      let wasTruncated = false;
+      if (content.length > PER_FILE_LIMIT) {
+        content = content.substring(0, PER_FILE_LIMIT);
+        wasTruncated = true;
+        truncatedCount++;
+      }
+
+      // Stop adding files if we've exceeded the total limit
+      if (totalChars + content.length > TOTAL_LIMIT) {
+        sections.push(`\n... [${openFiles.length - sections.length} more files omitted for context space]`);
+        break;
+      }
+
+      // Detect language from file extension for syntax highlighting
+      const ext = path.extname(filePath).slice(1);
+      const lang = EXT_TO_LANG[ext] || ext || "text";
+
+      sections.push(
+        `### ${filePath}${wasTruncated ? " (truncated)" : ""}\n\n\`\`\`${lang}\n${content}\n\`\`\``
+      );
+      totalChars += content.length;
+    }
+
+    return {
+      label: `Open Files (${openFiles.length})`,
+      content: `## Open Editor Files\n\n${sections.join("\n\n")}`,
+      metadata: {
+        source: "editor",
+        truncated: truncatedCount > 0,
+        itemCount: openFiles.length,
+      },
+    };
+  }
+}
+
+/** Map file extensions to markdown language identifiers */
+const EXT_TO_LANG: Record<string, string> = {
+  ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx",
+  py: "python", rs: "rust", go: "go", java: "java",
+  rb: "ruby", php: "php", cs: "csharp", cpp: "cpp",
+  c: "c", h: "c", hpp: "cpp", swift: "swift",
+  kt: "kotlin", scala: "scala", r: "r",
+  html: "html", css: "css", scss: "scss", less: "less",
+  json: "json", yaml: "yaml", yml: "yaml", toml: "toml",
+  xml: "xml", sql: "sql", sh: "bash", bash: "bash",
+  zsh: "bash", fish: "fish", ps1: "powershell",
+  md: "markdown", mdx: "markdown", txt: "text",
+};

package/src/context-providers/problems.ts

@@ -0,0 +1,100 @@
+/**
+ * Problems Context Provider — @problems
+ *
+ * Injects VS Code diagnostics (errors, warnings) into the conversation.
+ * Helps the AI understand what's broken without the user copying error messages.
+ *
+ * How it works:
+ *   1. VS Code extension collects diagnostics from all open files
+ *   2. Groups them by file and severity
+ *   3. Formats as a structured list for the LLM
+ *
+ * Learning note: Diagnostics come from VS Code's Language Server Protocol (LSP).
+ * Each diagnostic has a file path, line number, severity, and message.
+ * We pass them via the `options.diagnostics` array from the extension host.
+ */
+
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Emoji icons for each severity level */
+const SEVERITY_ICONS: Record<string, string> = {
+  error: "❌",
+  warning: "⚠️",
+  info: "ℹ️",
+  hint: "💡",
+};
+
+/** Priority order for sorting (errors first) */
+const SEVERITY_ORDER: Record<string, number> = {
+  error: 0,
+  warning: 1,
+  info: 2,
+  hint: 3,
+};
+
+export class ProblemsContextProvider implements ContextProvider {
+  id = "problems";
+  trigger = "@problems";
+  description = "Include current file diagnostics (errors, warnings)";
+  requiresArg = false;
+
+  async resolve(_arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const diagnostics = options?.diagnostics || [];
+
+    if (diagnostics.length === 0) {
+      return {
+        label: "Problems",
+        content: "[No diagnostics found. All files are clean!]",
+        metadata: { source: "diagnostics", itemCount: 0 },
+      };
+    }
+
+    // Sort by severity (errors first), then by file path
+    const sorted = [...diagnostics].sort((a, b) => {
+      const severityDiff = (SEVERITY_ORDER[a.severity] ?? 4) - (SEVERITY_ORDER[b.severity] ?? 4);
+      if (severityDiff !== 0) return severityDiff;
+      return a.file.localeCompare(b.file);
+    });
+
+    // Group diagnostics by file for cleaner formatting
+    const byFile = new Map<string, typeof diagnostics>();
+    for (const diag of sorted) {
+      const existing = byFile.get(diag.file) || [];
+      existing.push(diag);
+      byFile.set(diag.file, existing);
+    }
+
+    // Count by severity
+    const counts = { error: 0, warning: 0, info: 0, hint: 0 };
+    for (const diag of sorted) {
+      counts[diag.severity] = (counts[diag.severity] || 0) + 1;
+    }
+
+    // Format output
+    const sections: string[] = [];
+    for (const [file, diags] of byFile) {
+      const lines = diags.map((d) => {
+        const icon = SEVERITY_ICONS[d.severity] || "•";
+        return `  ${icon} Line ${d.line}: ${d.message}`;
+      });
+      sections.push(`### ${file}\n${lines.join("\n")}`);
+    }
+
+    // Build summary line
+    const summaryParts: string[] = [];
+    if (counts.error > 0) summaryParts.push(`${counts.error} error${counts.error > 1 ? "s" : ""}`);
+    if (counts.warning > 0) summaryParts.push(`${counts.warning} warning${counts.warning > 1 ? "s" : ""}`);
+    if (counts.info > 0) summaryParts.push(`${counts.info} info`);
+    if (counts.hint > 0) summaryParts.push(`${counts.hint} hint${counts.hint > 1 ? "s" : ""}`);
+    const summary = summaryParts.join(", ");
+
+    return {
+      label: `Problems (${summary})`,
+      content: `## Diagnostics: ${summary}\n\n${sections.join("\n\n")}`,
+      metadata: {
+        source: "diagnostics",
+        itemCount: diagnostics.length,
+      },
+    };
+  }
+}

package/src/context-providers/registry.ts

@@ -0,0 +1,99 @@
+/**
+ * Context Provider Registry — Manages all available @ context providers.
+ *
+ * Responsibilities:
+ *   1. Register/unregister providers
+ *   2. Match user input (e.g., "@terminal") to the right provider
+ *   3. Resolve context by delegating to the matched provider
+ *
+ * Learning note: This is a Service Locator pattern — it decouples
+ * the chat input from specific provider implementations. You can
+ * add new @ providers without touching the input handling code.
+ */
+
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+export class ContextProviderRegistry {
+  /** Map of provider ID → provider instance */
+  private providers = new Map<string, ContextProvider>();
+
+  /**
+   * Register a new context provider.
+   * Replaces any existing provider with the same ID.
+   */
+  register(provider: ContextProvider): void {
+    this.providers.set(provider.id, provider);
+  }
+
+  /**
+   * Remove a provider by ID.
+   */
+  unregister(id: string): void {
+    this.providers.delete(id);
+  }
+
+  /**
+   * Get a provider by its ID.
+   */
+  get(id: string): ContextProvider | undefined {
+    return this.providers.get(id);
+  }
+
+  /**
+   * Get all registered providers (for autocomplete suggestions).
+   */
+  getAll(): ContextProvider[] {
+    return Array.from(this.providers.values());
+  }
+
+  /**
+   * Match a trigger string (e.g., "@terminal", "@url https://...") to a provider.
+   *
+   * Returns the matched provider and any argument after the trigger,
+   * or null if no provider matches.
+   *
+   * Learning note: This parsing is intentionally simple — we split on
+   * the first space to separate trigger from argument.
+   */
+  match(input: string): { provider: ContextProvider; arg?: string } | null {
+    // Input should start with @
+    const trimmed = input.trim();
+    if (!trimmed.startsWith("@")) return null;
+
+    // Split into trigger and argument: "@url https://example.com" → ["@url", "https://example.com"]
+    const spaceIndex = trimmed.indexOf(" ");
+    const trigger = spaceIndex >= 0 ? trimmed.substring(0, spaceIndex) : trimmed;
+    const arg = spaceIndex >= 0 ? trimmed.substring(spaceIndex + 1).trim() : undefined;
+
+    // Find a provider whose trigger matches
+    for (const provider of this.providers.values()) {
+      if (provider.trigger === trigger) {
+        return { provider, arg };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Resolve context from a trigger string.
+   * Convenience method that combines match() + resolve().
+   */
+  async resolve(input: string, options?: ContextResolveOptions): Promise<ContextResult | null> {
+    const match = this.match(input);
+    if (!match) return null;
+
+    return match.provider.resolve(match.arg, options);
+  }
+
+  /**
+   * Get autocomplete suggestions for a partial @ input.
+   * E.g., "@ter" → ["@terminal"]
+   */
+  getSuggestions(partial: string): Array<{ trigger: string; description: string }> {
+    const query = partial.toLowerCase();
+    return this.getAll()
+      .filter((p) => p.trigger.toLowerCase().startsWith(query))
+      .map((p) => ({ trigger: p.trigger, description: p.description }));
+  }
+}

package/src/context-providers/terminal.ts

@@ -0,0 +1,58 @@
+/**
+ * Terminal Context Provider — @terminal
+ *
+ * Injects recent terminal output into the conversation.
+ * Useful when the user wants the AI to analyze command output,
+ * debug errors, or understand build/test results.
+ *
+ * How it works:
+ *   1. In VS Code: captures output from the integrated terminal
+ *   2. In CLI: captures the last shell command output
+ *   3. Formats it with a clear header for the LLM
+ *
+ * Learning note: Terminal output is inherently ephemeral — we only
+ * capture what's available at resolve time. In VS Code, this comes
+ * from the Terminal API; in CLI, from the last !command output.
+ */
+
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Default max characters for terminal output (prevents context window overflow) */
+const DEFAULT_MAX_CHARS = 10000;
+
+export class TerminalContextProvider implements ContextProvider {
+  id = "terminal";
+  trigger = "@terminal";
+  description = "Include recent terminal output";
+  requiresArg = false;
+
+  async resolve(_arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const maxChars = options?.maxContentLength ?? DEFAULT_MAX_CHARS;
+    let output = options?.terminalOutput || "";
+
+    // If no terminal output is available, return a helpful message
+    if (!output.trim()) {
+      return {
+        label: "Terminal Output",
+        content: "[No recent terminal output available. Run a command first, then use @terminal.]",
+        metadata: { source: "terminal", itemCount: 0 },
+      };
+    }
+
+    // Truncate if too long — keep the tail (most recent output is most relevant)
+    let truncated = false;
+    if (output.length > maxChars) {
+      output = output.slice(-maxChars);
+      truncated = true;
+    }
+
+    return {
+      label: "Terminal Output",
+      content: `## Recent Terminal Output\n\n\`\`\`\n${output}\n\`\`\``,
+      metadata: {
+        source: "terminal",
+        truncated,
+      },
+    };
+  }
+}