@cdoing/core 0.1.0

package/src/plan/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Plan Mode — Read-only planning before execution.
+ *
+ * When activated (/plan command), the agent:
+ *   1. Analyzes the request using read-only tools (file_read, grep, glob)
+ *   2. Generates a step-by-step implementation plan as markdown
+ *   3. Presents the plan for user review
+ *   4. User can approve, edit, or reject before execution
+ *
+ * The plan is stored as a structured object so it can be:
+ *   - Displayed as an interactive checklist in VS Code
+ *   - Edited by the user before approval
+ *   - Executed step-by-step with progress tracking
+ *
+ * Learning note: Plan mode is a form of "chain of thought" for the AI.
+ * By forcing the agent to plan before acting, it produces better results
+ * and gives the user a chance to course-correct before any files change.
+ */
+
+export { PlanManager, type Plan, type PlanStep, type PlanStatus } from "./manager";

package/src/plan/manager.ts

@@ -0,0 +1,233 @@
+/**
+ * Plan Manager — Creates, stores, and executes implementation plans.
+ *
+ * A plan is a structured breakdown of what the agent intends to do.
+ * Each step has a description, status, and optional tool call info.
+ *
+ * Learning note: This follows the Command Pattern — each plan step
+ * is a serializable command that can be reviewed before execution.
+ */
+
+/**
+ * Status of the overall plan.
+ */
+export type PlanStatus = "drafting" | "pending_approval" | "approved" | "executing" | "completed" | "rejected";
+
+/**
+ * A single step in the plan.
+ */
+export interface PlanStep {
+  /** Step number (1-based) */
+  number: number;
+
+  /** What this step will do (human-readable) */
+  description: string;
+
+  /** Which tool to use (e.g., "file_edit", "shell_exec") */
+  tool?: string;
+
+  /** Target file or resource */
+  target?: string;
+
+  /** Current status of this step */
+  status: "pending" | "in_progress" | "completed" | "skipped";
+
+  /** Optional details or notes */
+  details?: string;
+}
+
+/**
+ * A complete implementation plan.
+ */
+export interface Plan {
+  /** Unique plan ID */
+  id: string;
+
+  /** One-line summary of what the plan achieves */
+  summary: string;
+
+  /** Ordered list of steps */
+  steps: PlanStep[];
+
+  /** Current plan status */
+  status: PlanStatus;
+
+  /** When the plan was created */
+  createdAt: number;
+
+  /** The original user request that generated this plan */
+  originalRequest: string;
+}
+
+export class PlanManager {
+  /** The current active plan (only one at a time) */
+  private currentPlan: Plan | null = null;
+
+  /**
+   * Create a new plan from the agent's analysis.
+   *
+   * @param request - The original user request
+   * @param summary - One-line summary
+   * @param steps - Ordered list of step descriptions
+   * @returns The created plan
+   */
+  createPlan(request: string, summary: string, steps: string[]): Plan {
+    this.currentPlan = {
+      id: `plan_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+      summary,
+      steps: steps.map((desc, i) => ({
+        number: i + 1,
+        description: desc,
+        status: "pending",
+      })),
+      status: "pending_approval",
+      createdAt: Date.now(),
+      originalRequest: request,
+    };
+
+    return this.currentPlan;
+  }
+
+  /**
+   * Get the current active plan.
+   */
+  getCurrentPlan(): Plan | null {
+    return this.currentPlan;
+  }
+
+  /**
+   * Approve the plan for execution.
+   */
+  approvePlan(): boolean {
+    if (!this.currentPlan || this.currentPlan.status !== "pending_approval") {
+      return false;
+    }
+    this.currentPlan.status = "approved";
+    return true;
+  }
+
+  /**
+   * Reject the plan.
+   */
+  rejectPlan(): boolean {
+    if (!this.currentPlan) return false;
+    this.currentPlan.status = "rejected";
+    return true;
+  }
+
+  /**
+   * Mark the plan as executing.
+   */
+  startExecution(): boolean {
+    if (!this.currentPlan || this.currentPlan.status !== "approved") {
+      return false;
+    }
+    this.currentPlan.status = "executing";
+    return true;
+  }
+
+  /**
+   * Update a step's status.
+   */
+  updateStep(stepNumber: number, status: PlanStep["status"], details?: string): boolean {
+    if (!this.currentPlan) return false;
+
+    const step = this.currentPlan.steps.find((s) => s.number === stepNumber);
+    if (!step) return false;
+
+    step.status = status;
+    if (details) step.details = details;
+
+    // Check if all steps are completed
+    const allDone = this.currentPlan.steps.every(
+      (s) => s.status === "completed" || s.status === "skipped"
+    );
+    if (allDone) {
+      this.currentPlan.status = "completed";
+    }
+
+    return true;
+  }
+
+  /**
+   * Format the plan as markdown for display.
+   *
+   * Learning note: We use checkbox syntax (- [ ] / - [x]) so the
+   * plan looks like an interactive checklist in the chat.
+   */
+  formatPlan(): string {
+    if (!this.currentPlan) return "No active plan.";
+
+    const plan = this.currentPlan;
+    const lines: string[] = [
+      `## Plan: ${plan.summary}`,
+      "",
+      `**Status:** ${this.formatStatus(plan.status)}`,
+      "",
+    ];
+
+    for (const step of plan.steps) {
+      const checkbox = step.status === "completed" ? "[x]"
+        : step.status === "skipped" ? "[-]"
+        : step.status === "in_progress" ? "[~]"
+        : "[ ]";
+
+      let line = `${step.number}. ${checkbox} ${step.description}`;
+      if (step.tool) line += ` _(${step.tool})_`;
+      if (step.target) line += ` → \`${step.target}\``;
+      lines.push(line);
+
+      if (step.details) {
+        lines.push(`   _${step.details}_`);
+      }
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Get the plan as a system prompt addition.
+   * Used to guide the agent during execution.
+   */
+  getPlanPrompt(): string {
+    if (!this.currentPlan) return "";
+
+    const plan = this.currentPlan;
+    const stepList = plan.steps
+      .map((s) => `${s.number}. [${s.status}] ${s.description}`)
+      .join("\n");
+
+    return [
+      "# Active Plan",
+      "",
+      `Goal: ${plan.summary}`,
+      "",
+      "Steps:",
+      stepList,
+      "",
+      "Execute the next pending step. After completing each step, update its status.",
+      "If a step fails, explain why and suggest alternatives.",
+    ].join("\n");
+  }
+
+  /**
+   * Clear the current plan.
+   */
+  clearPlan(): void {
+    this.currentPlan = null;
+  }
+
+  /**
+   * Format a plan status as a human-readable string.
+   */
+  private formatStatus(status: PlanStatus): string {
+    switch (status) {
+      case "drafting": return "Drafting...";
+      case "pending_approval": return "Waiting for approval";
+      case "approved": return "Approved";
+      case "executing": return "Executing...";
+      case "completed": return "Completed";
+      case "rejected": return "Rejected";
+    }
+  }
+}

package/src/rules/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Project Rules — Hierarchical rule system for project-specific AI behavior.
+ *
+ * Similar to Cursor's .cursor/rules/ and Claude Code's CLAUDE.md,
+ * but with glob-based path scoping.
+ *
+ * Rule hierarchy (highest priority first):
+ *   1. Path-specific rules (.cdoing/rules/*.md with glob patterns)
+ *   2. Project rules (.cdoing/config.md or CDOING.md)
+ *   3. Global rules (~/.cdoing/rules/*.md)
+ *
+ * Each rule file is a markdown file with optional frontmatter:
+ *
+ *   ---
+ *   globs: ["*.ts", "src/api/**"]
+ *   description: Rules for TypeScript API files
+ *   ---
+ *
+ *   Always use async/await instead of callbacks.
+ *   Prefer named exports over default exports.
+ *
+ * Learning note: Glob-based scoping lets you have different coding
+ * standards for different parts of your project. For example, strict
+ * type rules for API code but relaxed rules for scripts.
+ */
+
+export { RulesManager } from "./manager";
+export type { Rule, RuleSource } from "./types";

package/src/rules/manager.ts

@@ -0,0 +1,276 @@
+/**
+ * Rules Manager — Loads, caches, and resolves project rules.
+ *
+ * Scans rule directories in priority order and returns rules
+ * that match the current file context.
+ *
+ * Learning note: The manager uses lazy loading — rules are only
+ * read from disk when first needed, then cached until the file
+ * system changes. This prevents slow startup on large projects.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { minimatch } from "minimatch";
+import type { Rule, RuleSource, RuleFrontmatter } from "./types";
+
+export class RulesManager {
+  /** Cached rules, indexed by source directory */
+  private cache = new Map<string, Rule[]>();
+
+  /** Working directory (project root) */
+  private workingDir: string;
+
+  constructor(workingDir: string) {
+    this.workingDir = workingDir;
+  }
+
+  /**
+   * Get all rules that apply to a given file path.
+   * Rules are returned in priority order (most specific first).
+   *
+   * @param filePath - The file being edited/created (for glob matching)
+   * @returns Array of matching rules
+   */
+  getRulesForFile(filePath?: string): Rule[] {
+    const allRules = this.loadAllRules();
+
+    if (!filePath) {
+      // No file context — return all rules without glob restrictions
+      return allRules.filter((r) => r.globs.length === 0);
+    }
+
+    // Resolve to relative path for glob matching
+    const relativePath = path.isAbsolute(filePath)
+      ? path.relative(this.workingDir, filePath)
+      : filePath;
+
+    return allRules.filter((rule) => {
+      // Rules without globs apply to everything
+      if (rule.globs.length === 0) return true;
+
+      // Check if any glob pattern matches the file
+      return rule.globs.some((glob) => this.matchGlob(relativePath, glob));
+    });
+  }
+
+  /**
+   * Get all rules formatted as a single string for the system prompt.
+   *
+   * @param filePath - Optional file context for filtering
+   * @returns Formatted rules text, or empty string if no rules
+   */
+  formatForPrompt(filePath?: string): string {
+    const rules = this.getRulesForFile(filePath);
+    if (rules.length === 0) return "";
+
+    const sections = rules.map((rule) => {
+      const header = rule.description
+        ? `### ${rule.description}`
+        : `### Rule from ${path.basename(rule.filePath)}`;
+
+      const scope = rule.globs.length > 0
+        ? `_Applies to: ${rule.globs.join(", ")}_\n`
+        : "";
+
+      return `${header}\n${scope}\n${rule.content}`;
+    });
+
+    return `# Project Rules\n\n${sections.join("\n\n---\n\n")}`;
+  }
+
+  /**
+   * Load all rules from all sources.
+   * Results are cached — call invalidateCache() to refresh.
+   */
+  private loadAllRules(): Rule[] {
+    const rules: Rule[] = [];
+
+    // 1. Global rules (~/.cdoing/rules/)
+    const globalDir = path.join(os.homedir(), ".cdoing", "rules");
+    rules.push(...this.loadRulesFromDir(globalDir, "global"));
+
+    // 2. Project rules (.cdoing/rules/)
+    const projectDir = path.join(this.workingDir, ".cdoing", "rules");
+    rules.push(...this.loadRulesFromDir(projectDir, "path-specific"));
+
+    return rules;
+  }
+
+  /**
+   * Load rules from a directory of markdown files.
+   *
+   * Learning note: Each .md file in the rules directory becomes a rule.
+   * YAML frontmatter is parsed for glob patterns and descriptions.
+   */
+  private loadRulesFromDir(dir: string, source: RuleSource): Rule[] {
+    // Check cache
+    const cached = this.cache.get(dir);
+    if (cached) return cached;
+
+    const rules: Rule[] = [];
+
+    if (!fs.existsSync(dir)) {
+      this.cache.set(dir, rules);
+      return rules;
+    }
+
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+    } catch {
+      this.cache.set(dir, rules);
+      return rules;
+    }
+
+    for (const file of entries) {
+      const filePath = path.join(dir, file);
+      try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        const parsed = this.parseRuleFile(content);
+
+        rules.push({
+          source,
+          filePath,
+          globs: parsed.globs,
+          description: parsed.description || file.replace(/\.md$/, ""),
+          content: parsed.content,
+        });
+      } catch {
+        // Skip unreadable files
+      }
+    }
+
+    this.cache.set(dir, rules);
+    return rules;
+  }
+
+  /**
+   * Parse a rule markdown file, extracting frontmatter and content.
+   *
+   * Frontmatter format:
+   *   ---
+   *   globs: ["*.ts", "src/**"]
+   *   description: TypeScript coding rules
+   *   ---
+   *
+   * Learning note: We use a simple regex-based parser instead of
+   * a YAML library to avoid adding dependencies. This handles
+   * the common cases well enough.
+   */
+  private parseRuleFile(raw: string): { globs: string[]; description: string; content: string } {
+    const frontmatterMatch = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+
+    if (!frontmatterMatch) {
+      // No frontmatter — entire file is content
+      return { globs: [], description: "", content: raw.trim() };
+    }
+
+    const [, frontmatterStr, content] = frontmatterMatch;
+
+    // Simple key-value parsing for frontmatter
+    let globs: string[] = [];
+    let description = "";
+
+    for (const line of frontmatterStr.split("\n")) {
+      const globMatch = line.match(/^globs:\s*\[(.+)\]$/);
+      if (globMatch) {
+        // Parse glob array: ["*.ts", "src/**"]
+        globs = globMatch[1]
+          .split(",")
+          .map((g) => g.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean);
+      }
+
+      const globSingle = line.match(/^globs:\s*["'](.+)["']$/);
+      if (globSingle) {
+        globs = [globSingle[1]];
+      }
+
+      const descMatch = line.match(/^description:\s*(.+)$/);
+      if (descMatch) {
+        description = descMatch[1].trim().replace(/^["']|["']$/g, "");
+      }
+    }
+
+    return { globs, description, content: content.trim() };
+  }
+
+  /**
+   * Check if a file path matches a glob pattern.
+   * Uses minimatch for proper glob matching.
+   */
+  private matchGlob(filePath: string, pattern: string): boolean {
+    try {
+      return minimatch(filePath, pattern, { matchBase: true });
+    } catch {
+      // If minimatch isn't available, fall back to simple extension matching
+      if (pattern.startsWith("*.")) {
+        const ext = pattern.slice(1); // e.g., ".ts"
+        return filePath.endsWith(ext);
+      }
+      return filePath.includes(pattern);
+    }
+  }
+
+  /**
+   * Format rules for CLI display, showing file paths and sources.
+   */
+  formatForDisplay(): string {
+    const allRules = this.loadAllRules();
+    if (allRules.length === 0) return "No rules defined.";
+
+    const globalDir = path.join(os.homedir(), ".cdoing", "rules");
+    const projectDir = path.join(this.workingDir, ".cdoing", "rules");
+
+    const lines: string[] = ["# Rules\n"];
+
+    // Group by source
+    const globalRules = allRules.filter((r) => r.source === "global");
+    const projectRules = allRules.filter((r) => r.source === "path-specific");
+
+    if (globalRules.length > 0) {
+      lines.push(`## Global rules (${globalDir}/)`);
+      for (const rule of globalRules) {
+        const globs = rule.globs.length > 0 ? ` [${rule.globs.join(", ")}]` : "";
+        lines.push(`  - ${rule.filePath}${globs}`);
+      }
+      lines.push("");
+    } else {
+      lines.push(`## Global rules — none found`);
+      lines.push(`  Directory: ${globalDir}/`);
+      lines.push("");
+    }
+
+    if (projectRules.length > 0) {
+      lines.push(`## Project rules (${projectDir}/)`);
+      for (const rule of projectRules) {
+        const globs = rule.globs.length > 0 ? ` [${rule.globs.join(", ")}]` : "";
+        lines.push(`  - ${rule.filePath}${globs}`);
+      }
+      lines.push("");
+    } else {
+      lines.push(`## Project rules — none found`);
+      lines.push(`  Directory: ${projectDir}/`);
+      lines.push("");
+    }
+
+    return lines.join("\n");
+  }
+
+  /**
+   * Clear the rule cache (call after file changes).
+   */
+  invalidateCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Update the working directory.
+   */
+  setWorkingDir(dir: string): void {
+    this.workingDir = dir;
+    this.invalidateCache();
+  }
+}

package/src/rules/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Rule Types — Shared type definitions for the rules system.
+ *
+ * Learning note: Separating types from implementation keeps
+ * the codebase clean and prevents circular imports.
+ */
+
+/**
+ * A single rule definition loaded from a .md file.
+ */
+export interface Rule {
+  /** Where the rule was loaded from */
+  source: RuleSource;
+
+  /** Absolute path to the rule file */
+  filePath: string;
+
+  /** Glob patterns this rule applies to (empty = applies to all files) */
+  globs: string[];
+
+  /** Human-readable description of what the rule enforces */
+  description: string;
+
+  /** The actual rule content (markdown text) */
+  content: string;
+}
+
+/**
+ * Where a rule was loaded from — determines priority.
+ * path-specific > project > global
+ */
+export type RuleSource = "global" | "project" | "path-specific";
+
+/**
+ * Frontmatter parsed from a rule markdown file.
+ */
+export interface RuleFrontmatter {
+  globs?: string | string[];
+  description?: string;
+}