@cdoing/core 0.1.0

package/src/context-providers/clipboard.ts

@@ -0,0 +1,48 @@
+import { execSync } from "child_process";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/**
+ * @clip — pastes clipboard content into the prompt.
+ * Works on macOS (pbpaste), Linux with xclip/xsel/wl-paste.
+ */
+export class ClipboardContextProvider implements ContextProvider {
+  id = "clipboard";
+  trigger = "@clip";
+  description = "Paste clipboard content into the message";
+  requiresArg = false;
+
+  async resolve(_arg?: string, _opts?: ContextResolveOptions): Promise<ContextResult> {
+    let content = "";
+
+    try {
+      const platform = process.platform;
+      if (platform === "darwin") {
+        content = execSync("pbpaste", { encoding: "utf8" });
+      } else if (platform === "linux") {
+        // Try wl-paste (Wayland), then xclip, then xsel
+        try {
+          content = execSync("wl-paste --no-newline 2>/dev/null", { encoding: "utf8" });
+        } catch {
+          try {
+            content = execSync("xclip -selection clipboard -o 2>/dev/null", { encoding: "utf8" });
+          } catch {
+            content = execSync("xsel --clipboard --output 2>/dev/null", { encoding: "utf8" });
+          }
+        }
+      } else {
+        return { label: "Clipboard", content: "", metadata: { source: "unsupported platform" } };
+      }
+    } catch {
+      return { label: "Clipboard", content: "(clipboard is empty or unavailable)" };
+    }
+
+    const trimmed = content.trim();
+    if (!trimmed) return { label: "Clipboard", content: "(clipboard is empty)" };
+
+    return {
+      label: "Clipboard",
+      content: `<clipboard>\n${trimmed}\n</clipboard>`,
+      metadata: { source: "system clipboard", itemCount: trimmed.split("\n").length },
+    };
+  }
+}

package/src/context-providers/codebase.ts

@@ -0,0 +1,274 @@
+/**
+ * Codebase Context Provider — @codebase
+ *
+ * Semantic search across the entire repository.
+ * Finds the most relevant files/code for a given query.
+ *
+ * How it works:
+ *   1. User types @codebase followed by a search query
+ *   2. We search file names and content using glob + grep
+ *   3. Rank results by relevance (filename match > content match)
+ *   4. Return the top N most relevant code snippets
+ *
+ * Learning note: This is a text-based search approach (not embedding-based).
+ * For true semantic search, you'd want vector embeddings + a vector DB.
+ * But text search with smart ranking gets you 80% of the way there
+ * and works offline without any setup.
+ *
+ * Future enhancement: Add optional embedding-based indexing for
+ * projects that configure it.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { execSync } from "child_process";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+/** Max files to include in results */
+const MAX_RESULTS = 10;
+
+/** Max chars per file snippet */
+const SNIPPET_LIMIT = 2000;
+
+/** Total max chars for all results */
+const TOTAL_LIMIT = 20000;
+
+/** File extensions to search (common code files) */
+const CODE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".py", ".rs", ".go", ".java",
+  ".rb", ".php", ".cs", ".cpp", ".c", ".h", ".hpp", ".swift",
+  ".kt", ".scala", ".r", ".html", ".css", ".scss", ".less",
+  ".json", ".yaml", ".yml", ".toml", ".xml", ".sql", ".sh",
+  ".bash", ".zsh", ".md", ".mdx", ".txt", ".vue", ".svelte",
+]);
+
+/** Directories to skip during search */
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".nuxt",
+  "__pycache__", ".cache", ".turbo", "coverage", "venv",
+  ".venv", ".tox", "target", "vendor",
+]);
+
+export class CodebaseContextProvider implements ContextProvider {
+  id = "codebase";
+  trigger = "@codebase";
+  description = "Search the entire codebase for relevant code";
+  requiresArg = true;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const query = arg?.trim();
+    if (!query) {
+      return {
+        label: "Codebase Search",
+        content: "[Please provide a search query after @codebase, e.g.: @codebase authentication flow]",
+        metadata: { source: "codebase" },
+      };
+    }
+
+    const workingDir = options?.workingDir || process.cwd();
+
+    // Search using ripgrep if available, fall back to simple search
+    const results = await this.search(query, workingDir);
+
+    if (results.length === 0) {
+      return {
+        label: `Codebase: "${query}"`,
+        content: `[No results found for "${query}" in the codebase.]`,
+        metadata: { source: "codebase", itemCount: 0 },
+      };
+    }
+
+    // Format results with code snippets
+    const sections: string[] = [];
+    let totalChars = 0;
+
+    for (const result of results.slice(0, MAX_RESULTS)) {
+      if (totalChars >= TOTAL_LIMIT) {
+        sections.push(`\n... [more results omitted]`);
+        break;
+      }
+
+      const relPath = path.relative(workingDir, result.file);
+      const ext = path.extname(result.file).slice(1);
+      const lang = ext || "text";
+
+      let snippet = result.snippet;
+      if (snippet.length > SNIPPET_LIMIT) {
+        snippet = snippet.substring(0, SNIPPET_LIMIT) + "\n... [truncated]";
+      }
+
+      sections.push(`### ${relPath}${result.line ? `:${result.line}` : ""}\n\n\`\`\`${lang}\n${snippet}\n\`\`\``);
+      totalChars += snippet.length;
+    }
+
+    return {
+      label: `Codebase: "${query}" (${results.length} results)`,
+      content: `## Codebase Search: "${query}"\n\n${sections.join("\n\n")}`,
+      metadata: {
+        source: "codebase",
+        itemCount: results.length,
+        truncated: results.length > MAX_RESULTS,
+      },
+    };
+  }
+
+  /**
+   * Search the codebase for a query string.
+   * Uses ripgrep (rg) if available for fast searching,
+   * otherwise falls back to a simple Node.js file walker.
+   */
+  private async search(
+    query: string,
+    workingDir: string,
+  ): Promise<Array<{ file: string; line?: number; snippet: string; score: number }>> {
+    // Try ripgrep first (much faster for large codebases)
+    try {
+      return this.searchWithRipgrep(query, workingDir);
+    } catch {
+      // Fall back to simple search
+      return this.searchSimple(query, workingDir);
+    }
+  }
+
+  /**
+   * Fast search using ripgrep (rg).
+   * Learning note: ripgrep respects .gitignore by default,
+   * which is exactly what we want.
+   */
+  private searchWithRipgrep(
+    query: string,
+    workingDir: string,
+  ): Array<{ file: string; line?: number; snippet: string; score: number }> {
+    // Use ripgrep with context lines around matches
+    const escapedQuery = query.replace(/['"\\]/g, "\\$&");
+    const output = execSync(
+      `rg --ignore-case --max-count=3 --context=3 --with-filename --line-number "${escapedQuery}" .`,
+      {
+        cwd: workingDir,
+        encoding: "utf-8",
+        timeout: 10000,
+        maxBuffer: 5 * 1024 * 1024,
+      },
+    );
+
+    // Parse ripgrep output into structured results
+    const results = new Map<string, { file: string; line?: number; snippet: string; score: number }>();
+
+    const lines = output.split("\n");
+    let currentFile = "";
+    let currentSnippet = "";
+    let currentLine: number | undefined;
+
+    for (const line of lines) {
+      // ripgrep format: "file:line:content" or "file-line-content" (context)
+      const match = line.match(/^(.+?)[:-](\d+)[:-](.*)$/);
+      if (match) {
+        const [, file, lineNum, content] = match;
+        const absFile = path.resolve(workingDir, file);
+
+        if (file !== currentFile) {
+          // Save previous file's results
+          if (currentFile && currentSnippet) {
+            const existing = results.get(currentFile);
+            if (!existing || currentSnippet.length > existing.snippet.length) {
+              results.set(currentFile, {
+                file: path.resolve(workingDir, currentFile),
+                line: currentLine,
+                snippet: currentSnippet.trim(),
+                score: 1,
+              });
+            }
+          }
+          currentFile = file;
+          currentSnippet = "";
+          currentLine = parseInt(lineNum, 10);
+        }
+        currentSnippet += content + "\n";
+      } else if (line === "--") {
+        // Separator between matches in the same file
+        currentSnippet += "...\n";
+      }
+    }
+
+    // Don't forget the last file
+    if (currentFile && currentSnippet) {
+      results.set(currentFile, {
+        file: path.resolve(workingDir, currentFile),
+        line: currentLine,
+        snippet: currentSnippet.trim(),
+        score: 1,
+      });
+    }
+
+    return Array.from(results.values());
+  }
+
+  /**
+   * Simple fallback search using Node.js file system.
+   * Slower but works everywhere without external dependencies.
+   */
+  private searchSimple(
+    query: string,
+    workingDir: string,
+  ): Array<{ file: string; line?: number; snippet: string; score: number }> {
+    const results: Array<{ file: string; line?: number; snippet: string; score: number }> = [];
+    const queryLower = query.toLowerCase();
+
+    // Walk directory tree
+    const walk = (dir: string, depth: number): void => {
+      if (depth > 5 || results.length >= MAX_RESULTS * 2) return;
+
+      let entries: fs.Dirent[];
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+
+      for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".cdoing") continue;
+        if (SKIP_DIRS.has(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          walk(fullPath, depth + 1);
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name);
+          if (!CODE_EXTENSIONS.has(ext)) continue;
+
+          try {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            const contentLower = content.toLowerCase();
+
+            // Check if query appears in content
+            const index = contentLower.indexOf(queryLower);
+            if (index >= 0) {
+              // Extract a snippet around the match
+              const linesBefore = content.substring(0, index).split("\n");
+              const lineNum = linesBefore.length;
+              const allLines = content.split("\n");
+              const start = Math.max(0, lineNum - 4);
+              const end = Math.min(allLines.length, lineNum + 4);
+              const snippet = allLines.slice(start, end).join("\n");
+
+              // Score based on match quality
+              let score = 1;
+              if (entry.name.toLowerCase().includes(queryLower)) score += 5; // Filename match
+              if (content.toLowerCase().split(queryLower).length > 2) score += 2; // Multiple matches
+
+              results.push({ file: fullPath, line: lineNum, snippet, score });
+            }
+          } catch {
+            // Skip unreadable files
+          }
+        }
+      }
+    };
+
+    walk(workingDir, 0);
+
+    // Sort by score (highest first) and return top results
+    return results.sort((a, b) => b.score - a.score).slice(0, MAX_RESULTS);
+  }
+}

package/src/context-providers/diff.ts

@@ -0,0 +1,66 @@
+/**
+ * Diff Context Provider — @diff
+ *
+ * Provides current working changes as context.
+ * Usage:
+ *   @diff           — unstaged working changes
+ *   @diff staged    — staged changes
+ *   @diff main      — diff against main branch
+ */
+
+import { exec } from "child_process";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+const MAX_DIFF_CHARS = 30000;
+
+export class DiffContextProvider implements ContextProvider {
+  id = "diff";
+  trigger = "@diff";
+  description = "Current git diff (working changes, staged, or vs branch)";
+  requiresArg = false;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    const workingDir = options?.workingDir || process.cwd();
+    const target = (arg || "").trim();
+
+    let command = "git diff";
+    let label = "Working changes";
+
+    if (target === "staged") {
+      command = "git diff --cached";
+      label = "Staged changes";
+    } else if (target) {
+      // Sanitize
+      if (!/^[a-zA-Z0-9_.\/~^@{}\-]+$/.test(target)) {
+        return { label: "Diff", content: `Invalid git ref: "${target}"` };
+      }
+      command = `git diff ${target}`;
+      label = `Diff vs ${target}`;
+    }
+
+    try {
+      const diff = await new Promise<string>((resolve, reject) => {
+        exec(command, { cwd: workingDir, timeout: 15000, maxBuffer: 5 * 1024 * 1024 }, (err, stdout, stderr) => {
+          if (err && !stdout) return reject(new Error(stderr?.trim() || err.message));
+          resolve(stdout);
+        });
+      });
+
+      const trimmedDiff = diff.trim();
+      if (!trimmedDiff) {
+        return { label, content: `## ${label}\nNo changes.` };
+      }
+
+      const truncated = trimmedDiff.length > MAX_DIFF_CHARS
+        ? trimmedDiff.substring(0, MAX_DIFF_CHARS) + "\n... [truncated]"
+        : trimmedDiff;
+
+      return {
+        label,
+        content: `## ${label}\n\`\`\`diff\n${truncated}\n\`\`\``,
+      };
+    } catch (err) {
+      return { label: "Diff", content: `Diff error: ${(err as Error).message}` };
+    }
+  }
+}

package/src/context-providers/docs.ts

@@ -0,0 +1,160 @@
+/**
+ * Docs Context Provider — @docs
+ *
+ * Fetches documentation for packages/libraries and injects into context.
+ * Usage:
+ *   @docs react          — fetch React docs summary
+ *   @docs express/Router — fetch specific section
+ *   @docs https://...    — fetch docs from URL directly
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+const MAX_CHARS = 30000;
+
+/**
+ * Docs registry is loaded from ~/.cdoing/docs-registry.json if it exists.
+ * Users can add their own package → URL mappings there.
+ * Format: { "react": "https://...", "express": "https://..." }
+ */
+function loadDocsRegistry(): Record<string, string> {
+  try {
+    const registryPath = require("path").join(require("os").homedir(), ".cdoing", "docs-registry.json");
+    if (require("fs").existsSync(registryPath)) {
+      return JSON.parse(require("fs").readFileSync(registryPath, "utf-8"));
+    }
+  } catch { /* ignore */ }
+  return {};
+}
+
+export class DocsContextProvider implements ContextProvider {
+  id = "docs";
+  trigger = "@docs";
+  description = "Fetch documentation for a package or URL (@docs react, @docs https://...)";
+  requiresArg = true;
+
+  async resolve(arg?: string, options?: ContextResolveOptions): Promise<ContextResult> {
+    if (!arg?.trim()) {
+      return {
+        label: "Docs",
+        content: `Usage: @docs <package-name> or @docs <url>\n\nSupported packages: ${Object.keys(loadDocsRegistry()).join(", ")}`,
+      };
+    }
+
+    const query = arg.trim().toLowerCase();
+
+    // Direct URL
+    if (query.startsWith("http://") || query.startsWith("https://")) {
+      return this.fetchUrl(query);
+    }
+
+    // Check registry
+    const registryUrl = loadDocsRegistry()[query];
+    if (registryUrl) {
+      return this.fetchUrl(registryUrl, query);
+    }
+
+    // Try to find local docs (README.md in node_modules)
+    const workingDir = options?.workingDir || process.cwd();
+    const localResult = this.findLocalDocs(workingDir, query);
+    if (localResult) return localResult;
+
+    // Try npm registry as fallback
+    return this.fetchNpmReadme(query);
+  }
+
+  private async fetchUrl(url: string, packageName?: string): Promise<ContextResult> {
+    try {
+      const response = await fetch(url, {
+        headers: { "User-Agent": "cdoing-agent/1.0" },
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!response.ok) {
+        return {
+          label: `Docs: ${packageName || url}`,
+          content: `Failed to fetch docs: HTTP ${response.status}`,
+        };
+      }
+
+      let text = await response.text();
+      if (text.length > MAX_CHARS) {
+        text = text.substring(0, MAX_CHARS) + "\n\n... [truncated]";
+      }
+
+      return {
+        label: `Docs: ${packageName || url}`,
+        content: `<docs source="${packageName || url}">\n${text}\n</docs>`,
+        metadata: { source: url, truncated: text.length >= MAX_CHARS },
+      };
+    } catch (err) {
+      return {
+        label: `Docs: ${packageName || url}`,
+        content: `Failed to fetch docs: ${(err as Error).message}`,
+      };
+    }
+  }
+
+  private findLocalDocs(workingDir: string, packageName: string): ContextResult | null {
+    const candidates = [
+      path.join(workingDir, "node_modules", packageName, "README.md"),
+      path.join(workingDir, "node_modules", packageName, "readme.md"),
+      path.join(workingDir, "node_modules", packageName, "Readme.md"),
+      path.join(workingDir, "node_modules", `@${packageName.split("/")[0]}`, packageName.split("/")[1] || "", "README.md"),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        try {
+          let content = fs.readFileSync(candidate, "utf-8");
+          if (content.length > MAX_CHARS) {
+            content = content.substring(0, MAX_CHARS) + "\n\n... [truncated]";
+          }
+          return {
+            label: `Docs: ${packageName} (local)`,
+            content: `<docs source="${packageName}" local="true">\n${content}\n</docs>`,
+            metadata: { source: candidate },
+          };
+        } catch { /* skip */ }
+      }
+    }
+
+    return null;
+  }
+
+  private async fetchNpmReadme(packageName: string): Promise<ContextResult> {
+    try {
+      const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}`, {
+        headers: { "Accept": "application/json", "User-Agent": "cdoing-agent/1.0" },
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!response.ok) {
+        return {
+          label: `Docs: ${packageName}`,
+          content: `Package "${packageName}" not found. Available packages: ${Object.keys(loadDocsRegistry()).join(", ")}`,
+        };
+      }
+
+      const data = await response.json() as { readme?: string; description?: string };
+      let readme = data.readme || data.description || "(no documentation found)";
+
+      if (readme.length > MAX_CHARS) {
+        readme = readme.substring(0, MAX_CHARS) + "\n\n... [truncated]";
+      }
+
+      return {
+        label: `Docs: ${packageName} (npm)`,
+        content: `<docs source="${packageName}" npm="true">\n${readme}\n</docs>`,
+        metadata: { source: `npm:${packageName}`, truncated: readme.length >= MAX_CHARS },
+      };
+    } catch (err) {
+      return {
+        label: `Docs: ${packageName}`,
+        content: `Failed to fetch docs for "${packageName}": ${(err as Error).message}`,
+      };
+    }
+  }
+}

package/src/context-providers/file-include.ts

@@ -0,0 +1,54 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { ContextProvider, ContextResult, ContextResolveOptions } from "./types";
+
+const MAX_BYTES = 100_000; // ~100 KB cap
+
+/**
+ * @file <path> — reads a file and injects its content into the prompt.
+ * Also handles bare relative/absolute paths that look like files.
+ */
+export class FileIncludeContextProvider implements ContextProvider {
+  id = "file";
+  trigger = "@file";
+  description = "Include a file's contents in the message  (@file src/foo.ts)";
+  requiresArg = true;
+
+  async resolve(arg?: string, opts?: ContextResolveOptions): Promise<ContextResult> {
+    const base = opts?.workingDir || process.cwd();
+    const filePath = arg ? path.resolve(base, arg.trim()) : "";
+
+    if (!filePath) {
+      return { label: "File", content: "(no file path provided — usage: @file path/to/file)" };
+    }
+
+    if (!fs.existsSync(filePath)) {
+      return { label: "File", content: `(file not found: ${filePath})` };
+    }
+
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) {
+      // List directory contents instead
+      const entries = fs.readdirSync(filePath).slice(0, 100).join("\n");
+      return {
+        label: "Directory",
+        content: `<directory path="${filePath}">\n${entries}\n</directory>`,
+      };
+    }
+
+    const raw = fs.readFileSync(filePath);
+    const truncated = raw.length > MAX_BYTES;
+    const text = truncated
+      ? raw.slice(0, MAX_BYTES).toString("utf8") + "\n... [truncated]"
+      : raw.toString("utf8");
+
+    const rel = path.relative(base, filePath);
+    const ext = path.extname(filePath).slice(1) || "text";
+
+    return {
+      label: "File",
+      content: `<file path="${rel}">\n\`\`\`${ext}\n${text}\n\`\`\`\n</file>`,
+      metadata: { source: rel, truncated },
+    };
+  }
+}