sourcebook 0.1.0 → 0.4.1

package/dist/commands/update.d.ts

@@ -0,0 +1,17 @@
+interface UpdateOptions {
+    dir: string;
+    format: string;
+    budget: string;
+}
+/**
+ * Re-analyze and regenerate context files while preserving manual edits.
+ *
+ * Strategy:
+ * 1. Read existing output file
+ * 2. Parse into sections (split on ## headers)
+ * 3. Identify manual sections (headers not in SOURCEBOOK_HEADERS)
+ * 4. Re-run scan and generate fresh content
+ * 5. Replace sourcebook sections, keep manual sections in their original positions
+ */
+export declare function update(options: UpdateOptions): Promise<void>;
+export {};

package/dist/commands/update.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { scanProject } from "../scanner/index.js";
+import { generateClaude } from "../generators/claude.js";
+import { generateCursor, generateCursorLegacy } from "../generators/cursor.js";
+import { generateCopilot } from "../generators/copilot.js";
+import { writeOutput } from "../utils/output.js";
+import { requirePro } from "../auth/license.js";
+// Headers that sourcebook generates — anything else is user-added
+const SOURCEBOOK_HEADERS = new Set([
+    "CLAUDE.md",
+    "Commands",
+    "Critical Constraints",
+    "Stack",
+    "Project Structure",
+    "Core Modules (by structural importance)",
+    "Core Modules",
+    "Conventions & Patterns",
+    "Conventions",
+    "Additional Context",
+    "Additional Notes",
+    "What to Add Manually",
+    "Copilot Instructions",
+    "Development Commands",
+    "Important Constraints",
+    "Technology Stack",
+    "High-Impact Files",
+    "Code Conventions",
+    "Constraints",
+]);
+/**
+ * Re-analyze and regenerate context files while preserving manual edits.
+ *
+ * Strategy:
+ * 1. Read existing output file
+ * 2. Parse into sections (split on ## headers)
+ * 3. Identify manual sections (headers not in SOURCEBOOK_HEADERS)
+ * 4. Re-run scan and generate fresh content
+ * 5. Replace sourcebook sections, keep manual sections in their original positions
+ */
+export async function update(options) {
+    await requirePro("sourcebook update");
+    const targetDir = path.resolve(options.dir);
+    const formats = options.format.split(",").map((f) => f.trim());
+    const budget = parseInt(options.budget, 10);
+    console.log(chalk.bold("\nsourcebook update"));
+    console.log(chalk.dim("Re-analyzing while preserving your edits...\n"));
+    const scan = await scanProject(targetDir);
+    console.log(chalk.green("✓") + " Scanned project structure");
+    console.log(chalk.dim(`  ${scan.files.length} files, ${scan.frameworks.length} frameworks detected`));
+    console.log(chalk.green("✓") + ` Extracted ${scan.findings.length} findings\n`);
+    for (const format of formats) {
+        switch (format) {
+            case "claude": {
+                const fresh = generateClaude(scan, budget);
+                const existing = readExisting(targetDir, "CLAUDE.md");
+                const merged = existing ? mergeContent(existing, fresh) : fresh;
+                await writeOutput(targetDir, "CLAUDE.md", merged);
+                const preserved = existing ? countManualSections(existing) : 0;
+                console.log(chalk.green("✓") +
+                    ` Updated CLAUDE.md` +
+                    (preserved > 0 ? chalk.dim(` (${preserved} manual section${preserved > 1 ? "s" : ""} preserved)`) : ""));
+                break;
+            }
+            case "cursor": {
+                const fresh = generateCursor(scan, budget);
+                await writeOutput(targetDir, ".cursor/rules/sourcebook.mdc", fresh);
+                const legacyFresh = generateCursorLegacy(scan, budget);
+                await writeOutput(targetDir, ".cursorrules", legacyFresh);
+                console.log(chalk.green("✓") + " Updated .cursor/rules/sourcebook.mdc");
+                break;
+            }
+            case "copilot": {
+                const fresh = generateCopilot(scan, budget);
+                const existing = readExisting(targetDir, ".github/copilot-instructions.md");
+                const merged = existing ? mergeContent(existing, fresh) : fresh;
+                await writeOutput(targetDir, ".github/copilot-instructions.md", merged);
+                const preserved = existing ? countManualSections(existing) : 0;
+                console.log(chalk.green("✓") +
+                    ` Updated .github/copilot-instructions.md` +
+                    (preserved > 0 ? chalk.dim(` (${preserved} manual section${preserved > 1 ? "s" : ""} preserved)`) : ""));
+                break;
+            }
+            case "all": {
+                // Recurse for each format
+                for (const f of ["claude", "cursor", "copilot"]) {
+                    await update({ ...options, format: f });
+                }
+                return;
+            }
+            default:
+                console.log(chalk.yellow(`⚠ Format "${format}" not yet supported`));
+        }
+    }
+    console.log(chalk.dim("\nDone. Your manual sections were preserved.\n"));
+}
+function readExisting(dir, filename) {
+    const filePath = path.join(dir, filename);
+    try {
+        return fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse markdown into sections split by ## headers.
+ */
+function parseSections(content) {
+    const sections = [];
+    const lines = content.split("\n");
+    let currentHeader = "";
+    let currentBody = [];
+    for (const line of lines) {
+        const headerMatch = line.match(/^##\s+(.+)/);
+        if (headerMatch) {
+            if (currentHeader || currentBody.length > 0) {
+                sections.push({ header: currentHeader, body: currentBody.join("\n") });
+            }
+            currentHeader = headerMatch[1].trim();
+            currentBody = [];
+        }
+        else {
+            currentBody.push(line);
+        }
+    }
+    if (currentHeader || currentBody.length > 0) {
+        sections.push({ header: currentHeader, body: currentBody.join("\n") });
+    }
+    return sections;
+}
+function isSourcebookSection(header) {
+    return SOURCEBOOK_HEADERS.has(header) || header === "";
+}
+function countManualSections(content) {
+    const sections = parseSections(content);
+    return sections.filter((s) => s.header && !isSourcebookSection(s.header)).length;
+}
+/**
+ * Merge fresh sourcebook output with existing content,
+ * preserving any manually added sections.
+ */
+function mergeContent(existing, fresh) {
+    const existingSections = parseSections(existing);
+    const freshSections = parseSections(fresh);
+    // Extract manual sections from existing content
+    const manualSections = existingSections.filter((s) => s.header && !isSourcebookSection(s.header));
+    if (manualSections.length === 0) {
+        // No manual sections — just use the fresh content
+        return fresh;
+    }
+    // Find where "What to Add Manually" or last section is in fresh content
+    // Insert manual sections before the footer
+    const result = [];
+    let insertedManual = false;
+    for (const section of freshSections) {
+        // Insert manual sections before the "What to Add Manually" footer
+        if (section.header === "What to Add Manually" && !insertedManual) {
+            for (const manual of manualSections) {
+                result.push(`## ${manual.header}`);
+                result.push(manual.body);
+            }
+            insertedManual = true;
+        }
+        if (section.header) {
+            result.push(`## ${section.header}`);
+        }
+        result.push(section.body);
+    }
+    // If we never found the footer, append manual sections at the end
+    if (!insertedManual) {
+        for (const manual of manualSections) {
+            result.push(`## ${manual.header}`);
+            result.push(manual.body);
+        }
+    }
+    return result.join("\n");
+}

package/dist/generators/agents.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectScan } from "../types.js";
+/**
+ * Generate an AGENTS.md file from scan results.
+ * Used by GitHub Copilot, OpenAI Codex, and other AGENTS.md-aware tools.
+ * Format follows the AGENTS.md spec: markdown with directives for agent behavior.
+ */
+export declare function generateAgents(scan: ProjectScan, budget: number): string;

package/dist/generators/agents.js

@@ -0,0 +1,119 @@
+import { hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
+/**
+ * Generate an AGENTS.md file from scan results.
+ * Used by GitHub Copilot, OpenAI Codex, and other AGENTS.md-aware tools.
+ * Format follows the AGENTS.md spec: markdown with directives for agent behavior.
+ */
+export function generateAgents(scan, budget) {
+    const { critical, important, supplementary } = categorizeFindings(scan.findings);
+    const sections = [];
+    sections.push({
+        key: "header",
+        content: [
+            "# AGENTS.md",
+            "",
+            "Agent instructions for this repository.",
+            "Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.",
+            "",
+        ].join("\n"),
+        priority: 100,
+    });
+    // Commands
+    if (hasCommands(scan.commands)) {
+        const lines = ["## Commands", ""];
+        if (scan.commands.dev)
+            lines.push(`- **Dev:** \`${scan.commands.dev}\``);
+        if (scan.commands.build)
+            lines.push(`- **Build:** \`${scan.commands.build}\``);
+        if (scan.commands.test)
+            lines.push(`- **Test:** \`${scan.commands.test}\``);
+        if (scan.commands.lint)
+            lines.push(`- **Lint:** \`${scan.commands.lint}\``);
+        for (const [name, cmd] of Object.entries(scan.commands)) {
+            if (cmd && !["dev", "build", "test", "lint", "start"].includes(name)) {
+                lines.push(`- **${name}:** \`${cmd}\``);
+            }
+        }
+        lines.push("");
+        sections.push({ key: "commands", content: lines.join("\n"), priority: 95 });
+    }
+    // Critical constraints as agent directives
+    if (critical.length > 0) {
+        const lines = [
+            "## Constraints",
+            "",
+            "These constraints MUST be followed when modifying this codebase:",
+            "",
+        ];
+        for (const finding of critical) {
+            lines.push(`- **${finding.category}:** ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
+    }
+    // Stack
+    if (scan.frameworks.length > 0) {
+        sections.push({
+            key: "stack",
+            content: [
+                "## Stack",
+                "",
+                scan.frameworks.join(", "),
+                "",
+            ].join("\n"),
+            priority: 50,
+        });
+    }
+    // Core modules
+    if (scan.rankedFiles && scan.rankedFiles.length > 0) {
+        const lines = [
+            "## Core Modules (by structural importance)",
+            "",
+        ];
+        for (const { file, score } of scan.rankedFiles.slice(0, 5)) {
+            lines.push(`- \`${file}\``);
+        }
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
+    }
+    // Conventions
+    if (important.length > 0) {
+        const lines = [
+            "## Conventions",
+            "",
+        ];
+        for (const finding of important) {
+            lines.push(`- **${finding.category}:** ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
+    }
+    // Additional context
+    if (supplementary.length > 0) {
+        const lines = ["## Additional Context", ""];
+        for (const finding of supplementary) {
+            lines.push(`- ${finding.description}`);
+        }
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
+    }
+    // Manual section prompt
+    sections.push({
+        key: "manual",
+        content: [
+            "## What to Add Manually",
+            "",
+            "The most valuable context is what only you know. Add:",
+            "",
+            "- Architectural decisions and why they were made",
+            "- Past incidents that shaped current conventions",
+            "- Deprecated patterns to avoid in new code",
+            "- Domain-specific rules or terminology",
+            "- Environment setup beyond what .env.example shows",
+            "",
+        ].join("\n"),
+        priority: 10,
+    });
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
+}

package/dist/generators/claude.js

@@ -1,3 +1,4 @@
+import { groupByCategory, hasCommands, categorizeFindings, enforceTokenBudget, } from "./shared.js";
 /**
  * Generate a CLAUDE.md file from scan results.
  *
@@ -8,47 +9,47 @@
  * 3. Karpathy's program.md pattern: constraints, gotchas, and autonomy boundaries
  */
 export function generateClaude(scan, budget) {
-    // Separate findings by importance for context-rot-aware placement
-    const critical = scan.findings.filter((f) => f.confidence === "high" && isCritical(f));
-    const important = scan.findings.filter((f) => f.confidence === "high" && !isCritical(f));
-    const supplementary = scan.findings.filter((f) => f.confidence === "medium");
+    const { critical, important, supplementary } = categorizeFindings(scan.findings);
     const sections = [];
     // ============================================
     // BEGINNING: Most critical info goes here
     // (LLMs retain start of context best)
     // ============================================
-    sections.push("# CLAUDE.md");
-    sections.push("");
-    sections.push("This file provides guidance to Claude Code when working with this codebase.");
-    sections.push("Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.");
-    sections.push("");
+    const header = [
+        "# CLAUDE.md",
+        "",
+        "This file provides guidance to Claude Code when working with this codebase.",
+        "Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.",
+        "",
+    ].join("\n");
+    sections.push({ key: "header", content: header, priority: 100 });
     // Commands first -- most immediately actionable
     if (hasCommands(scan.commands)) {
-        sections.push("## Commands");
-        sections.push("");
+        const lines = ["## Commands", ""];
         if (scan.commands.dev)
-            sections.push(`- **Dev:** \`${scan.commands.dev}\``);
+            lines.push(`- **Dev:** \`${scan.commands.dev}\``);
         if (scan.commands.build)
-            sections.push(`- **Build:** \`${scan.commands.build}\``);
+            lines.push(`- **Build:** \`${scan.commands.build}\``);
         if (scan.commands.test)
-            sections.push(`- **Test:** \`${scan.commands.test}\``);
+            lines.push(`- **Test:** \`${scan.commands.test}\``);
         if (scan.commands.lint)
-            sections.push(`- **Lint:** \`${scan.commands.lint}\``);
+            lines.push(`- **Lint:** \`${scan.commands.lint}\``);
         for (const [name, cmd] of Object.entries(scan.commands)) {
             if (cmd && !["dev", "build", "test", "lint", "start"].includes(name)) {
-                sections.push(`- **${name}:** \`${cmd}\``);
+                lines.push(`- **${name}:** \`${cmd}\``);
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "commands", content: lines.join("\n"), priority: 95 });
     }
-    // Critical warnings/constraints near the top (danger zone, fragile code, hidden deps)
+    // Critical warnings/constraints near the top
     if (critical.length > 0) {
-        sections.push("## Critical Constraints");
-        sections.push("");
+        const lines = ["## Critical Constraints", ""];
         for (const finding of critical) {
-            sections.push(`- **${finding.category}:** ${finding.description}`);
+            lines.push(`- **${finding.category}:** ${finding.description}`);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "critical", content: lines.join("\n"), priority: 90 });
     }
     // ============================================
     // MIDDLE: Less critical but useful info
@@ -56,136 +57,85 @@ export function generateClaude(scan, budget) {
     // ============================================
     // Stack (brief)
     if (scan.frameworks.length > 0) {
-        sections.push("## Stack");
-        sections.push("");
-        sections.push(scan.frameworks.join(", "));
-        sections.push("");
+        const content = ["## Stack", "", scan.frameworks.join(", "), ""].join("\n");
+        sections.push({ key: "stack", content, priority: 50 });
     }
     // Key directories (only non-obvious ones)
     if (Object.keys(scan.structure.directories).length > 0) {
         const nonObvious = Object.entries(scan.structure.directories).filter(([dir]) => !["src", "public", "node_modules", "dist", "build"].includes(dir));
         if (nonObvious.length > 0) {
-            sections.push("## Project Structure");
-            sections.push("");
+            const lines = ["## Project Structure", ""];
             for (const [dir, purpose] of nonObvious) {
-                sections.push(`- \`${dir}/\` — ${purpose}`);
+                lines.push(`- \`${dir}/\` — ${purpose}`);
             }
-            sections.push("");
+            lines.push("");
+            sections.push({ key: "structure", content: lines.join("\n"), priority: 40 });
         }
     }
     // Core modules (from PageRank)
     if (scan.rankedFiles && scan.rankedFiles.length > 0) {
         const top5 = scan.rankedFiles.slice(0, 5);
-        sections.push("## Core Modules (by structural importance)");
-        sections.push("");
+        const lines = ["## Core Modules (by structural importance)", ""];
         for (const { file } of top5) {
-            sections.push(`- \`${file}\``);
+            lines.push(`- \`${file}\``);
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "core_modules", content: lines.join("\n"), priority: 60 });
     }
     // Important findings (high confidence, non-critical)
     if (important.length > 0) {
-        sections.push("## Conventions & Patterns");
-        sections.push("");
+        const lines = ["## Conventions & Patterns", ""];
         const grouped = groupByCategory(important);
         for (const [category, findings] of grouped) {
             if (findings.length === 1) {
-                sections.push(`- **${category}:** ${findings[0].description}`);
+                lines.push(`- **${category}:** ${findings[0].description}`);
             }
             else {
-                sections.push(`- **${category}:**`);
+                lines.push(`- **${category}:**`);
                 for (const f of findings) {
-                    sections.push(`  - ${f.description}`);
+                    lines.push(`  - ${f.description}`);
                 }
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "conventions", content: lines.join("\n"), priority: 30 });
     }
     // Supplementary findings (medium confidence)
     if (supplementary.length > 0) {
-        sections.push("## Additional Context");
-        sections.push("");
+        const lines = ["## Additional Context", ""];
         const grouped = groupByCategory(supplementary);
         for (const [category, findings] of grouped) {
             if (findings.length === 1) {
-                sections.push(`- **${category}:** ${findings[0].description}`);
+                lines.push(`- **${category}:** ${findings[0].description}`);
             }
             else {
-                sections.push(`- **${category}:**`);
+                lines.push(`- **${category}:**`);
                 for (const f of findings) {
-                    sections.push(`  - ${f.description}`);
+                    lines.push(`  - ${f.description}`);
                 }
             }
         }
-        sections.push("");
+        lines.push("");
+        sections.push({ key: "supplementary", content: lines.join("\n"), priority: 20 });
     }
     // ============================================
     // END: Important reminders go here
     // (LLMs retain end of context second-best)
     // ============================================
-    // "What to add" section -- prompts human to add non-discoverable context
-    sections.push("## What to Add Manually");
-    sections.push("");
-    sections.push("The most valuable context is what only you know. Add:");
-    sections.push("");
-    sections.push("- Architectural decisions and why they were made");
-    sections.push("- Past incidents that shaped current conventions");
-    sections.push("- Deprecated patterns to avoid in new code");
-    sections.push("- Domain-specific rules or terminology");
-    sections.push("- Environment setup beyond what .env.example shows");
-    sections.push("");
-    let output = sections.join("\n");
-    // Token budget enforcement (rough: 1 token ≈ 4 chars)
-    const charBudget = budget * 4;
-    if (output.length > charBudget) {
-        output = output.slice(0, charBudget);
-        const lastNewline = output.lastIndexOf("\n");
-        output =
-            output.slice(0, lastNewline) +
-                "\n\n<!-- truncated to fit token budget -->\n";
-    }
-    return output;
-}
-/**
- * Determine if a finding is "critical" -- things that can cause real damage
- * if an agent gets them wrong. These go at the TOP of the file.
- */
-function isCritical(finding) {
-    const criticalCategories = new Set([
-        "Hidden dependencies",
-        "Circular dependencies",
-        "Core modules",
-        "Fragile code",
-        "Git history",
-        "Commit conventions",
-    ]);
-    const criticalKeywords = [
-        "breaking",
-        "blast radius",
-        "deprecated",
-        "don't",
-        "must",
-        "never",
-        "revert",
-        "fragile",
-        "hidden",
-        "invisible",
-        "coupling",
-    ];
-    if (criticalCategories.has(finding.category))
-        return true;
-    const desc = finding.description.toLowerCase();
-    return criticalKeywords.some((kw) => desc.includes(kw));
-}
-function groupByCategory(findings) {
-    const grouped = new Map();
-    for (const finding of findings) {
-        const existing = grouped.get(finding.category) || [];
-        existing.push(finding);
-        grouped.set(finding.category, existing);
-    }
-    return grouped;
-}
-function hasCommands(commands) {
-    return Object.values(commands).some((v) => v !== undefined);
+    const footer = [
+        "## What to Add Manually",
+        "",
+        "The most valuable context is what only you know. Add:",
+        "",
+        "- Architectural decisions and why they were made",
+        "- Past incidents that shaped current conventions",
+        "- Deprecated patterns to avoid in new code",
+        "- Domain-specific rules or terminology",
+        "- Environment setup beyond what .env.example shows",
+        "",
+    ].join("\n");
+    sections.push({ key: "footer", content: footer, priority: 90 });
+    // Apply smart budget enforcement
+    const kept = enforceTokenBudget(sections, budget);
+    return kept.join("\n");
 }

package/dist/generators/copilot.d.ts

@@ -1,12 +1,6 @@
 import type { ProjectScan } from "../types.js";
 /**
  * Generate GitHub Copilot instructions from scan results.
- *
- * Copilot supports:
- * - `.github/copilot-instructions.md` — repo-level instructions (always loaded)
- * - `.instructions.md` — per-directory instructions (loaded when files in that dir are referenced)
- *
- * We generate the repo-level file. Copilot's format is plain markdown with
- * natural language instructions — more conversational than Cursor's directive style.
+ * Outputs .github/copilot-instructions.md — conversational style.
  */
 export declare function generateCopilot(scan: ProjectScan, budget: number): string;