sourcebook 0.5.0 → 0.5.2

package/README.md

@@ -4,25 +4,27 @@
 
 # sourcebook
 
-Generate AI context files from your codebase's actual conventions. Not what agents already know — what they keep missing.
+**AI can read your code. It still doesn't know how your project works.**
+
+sourcebook captures the project knowledge your team carries in its head — conventions, patterns, traps, and where things actually go — and turns it into context your coding agent can use.
 
 ```bash
 npx sourcebook init
 ```
 
-One command. Analyzes your codebase. Outputs a `CLAUDE.md` tuned for how your project actually works.
-
 <p align="center">
   <img src="demo.svg" alt="sourcebook demo" width="820" />
 </p>
 
+> Tools like Repomix give AI your entire codebase. sourcebook gives it your project knowledge.
+
 ## Why
 
-AI coding agents spend most of their context window just orienting — reading files to build a mental model before doing real work. Developers manually write context files (`CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`), but most are generic and go stale fast.
+AI coding agents spend most of their context window orienting — reading files to build a mental model before doing real work. Most context files (`CLAUDE.md`, `.cursorrules`) are generic and go stale fast.
 
-Research shows auto-generated context that restates obvious information (tech stack, directory structure) actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — things agents can't figure out by reading the code alone.
+Research shows auto-generated context that restates obvious information actually makes agents [worse by 2-3%](https://arxiv.org/abs/2502.09601). The only context that helps is **non-discoverable information** — the project knowledge agents can't figure out by reading code alone.
 
-sourcebook inverts the typical approach: instead of dumping everything, it extracts only what agents keep missing, filtered through a discoverability test.
+sourcebook extracts only what agents keep missing: the conventions, hidden dependencies, fragile areas, and dominant patterns that live in your team's heads — not in the code.
 
 ## What It Finds
 

package/dist/auth/license.d.ts

@@ -18,6 +18,10 @@ export declare function checkLicense(): Promise<LicenseInfo>;
  * Save a license key to disk.
  */
 export declare function saveLicenseKey(key: string): void;
+/**
+ * Remove the license key from disk.
+ */
+export declare function removeLicenseKey(): void;
 /**
  * Gate a feature behind Pro license.
  * Prints upgrade message and exits if not licensed.

package/dist/auth/license.js

@@ -44,12 +44,13 @@ export async function checkLicense() {
     catch {
         // Network error or timeout — fall back to cache or offline validation
         if (cached && cached.key === key) {
-            return cached.info;
-        }
-        // Offline grace: if key looks valid (format check), allow Pro for 7 days
-        if (isValidKeyFormat(key)) {
-            return { valid: true, tier: "pro" };
+            // Only grant offline access if last validation was within 7 days
+            const OFFLINE_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+            if (Date.now() - cached.timestamp <= OFFLINE_GRACE_MS) {
+                return cached.info;
+            }
         }
+        // No valid cached validation within 7 days — deny access
     }
     return { valid: false, tier: "free" };
 }
@@ -58,9 +59,22 @@ export async function checkLicense() {
  */
 export function saveLicenseKey(key) {
     if (!fs.existsSync(LICENSE_DIR)) {
-        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+        fs.mkdirSync(LICENSE_DIR, { recursive: true, mode: 0o700 });
+    }
+    fs.writeFileSync(LICENSE_FILE, key.trim(), { encoding: "utf-8", mode: 0o600 });
+}
+/**
+ * Remove the license key from disk.
+ */
+export function removeLicenseKey() {
+    try {
+        if (fs.existsSync(LICENSE_FILE)) {
+            fs.unlinkSync(LICENSE_FILE);
+        }
+    }
+    catch {
+        // ignore cleanup errors
     }
-    fs.writeFileSync(LICENSE_FILE, key.trim(), "utf-8");
 }
 /**
  * Read the license key from disk.
@@ -93,10 +107,10 @@ function readCache() {
 }
 function writeCache(key, info) {
     if (!fs.existsSync(LICENSE_DIR)) {
-        fs.mkdirSync(LICENSE_DIR, { recursive: true });
+        fs.mkdirSync(LICENSE_DIR, { recursive: true, mode: 0o700 });
     }
     const entry = { key, info, timestamp: Date.now() };
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), "utf-8");
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(entry), { encoding: "utf-8", mode: 0o600 });
 }
 function isCacheExpired(timestamp) {
     return Date.now() - timestamp > CACHE_TTL_MS;

package/dist/commands/activate.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { saveLicenseKey, checkLicense } from "../auth/license.js";
+import { saveLicenseKey, removeLicenseKey, checkLicense } from "../auth/license.js";
 export async function activate(key) {
     if (!key || key.trim().length === 0) {
         console.log(chalk.red("\nNo license key provided."));
@@ -9,9 +9,9 @@ export async function activate(key) {
     }
     console.log(chalk.bold("\nsourcebook activate"));
     console.log(chalk.dim("Validating license key...\n"));
-    // Save key first
+    // Validate first, only save if valid
+    // Temporarily save so checkLicense can read it, then remove if invalid
     saveLicenseKey(key);
-    // Validate it
     const license = await checkLicense();
     if (license.tier === "pro" || license.tier === "team") {
         console.log(chalk.green("✓") +
@@ -30,9 +30,11 @@ export async function activate(key) {
         console.log("");
     }
     else {
+        // Validation failed — remove the saved key to prevent offline bypass
+        removeLicenseKey();
         console.log(chalk.yellow("⚠") +
-            " License key saved but could not be validated.");
-        console.log(chalk.dim("  This may be a network issue. The key will be re-validated on next use."));
+            " License key could not be validated and was not saved.");
+        console.log(chalk.dim("  This may be a network issue. Please try again when you have an internet connection."));
         console.log(chalk.dim("  If the problem persists, contact roy@maroond.ai\n"));
     }
 }

package/dist/commands/update.js

@@ -28,6 +28,8 @@ const SOURCEBOOK_HEADERS = new Set([
     "High-Impact Files",
     "Code Conventions",
     "Constraints",
+    "Quick Reference",
+    "Dominant Patterns",
 ]);
 /**
  * Re-analyze and regenerate context files while preserving manual edits.

package/dist/scanner/build.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 export async function detectBuildCommands(dir) {
     const commands = {};
     // Check package.json scripts

package/dist/scanner/frameworks.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 export async function detectFrameworks(dir, files) {
     const detected = [];
     // Read all package.json files (root + workspaces/sub-packages)
@@ -8,7 +15,9 @@ export async function detectFrameworks(dir, files) {
         pkgFiles.push("package.json");
     const allDeps = {};
     for (const pkgFile of pkgFiles) {
-        const pkgPath = path.join(dir, pkgFile);
+        const pkgPath = safePath(dir, pkgFile);
+        if (!pkgPath)
+            continue;
         if (fs.existsSync(pkgPath)) {
             try {
                 const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
@@ -44,29 +53,31 @@ export async function detectFrameworks(dir, files) {
         // Check for next.config
         const nextConfig = files.find((f) => /^next\.config\.(js|mjs|ts)$/.test(f));
         if (nextConfig) {
-            try {
-                const configContent = fs.readFileSync(path.join(dir, nextConfig), "utf-8");
-                if (configContent.includes("output:") && configContent.includes("standalone")) {
-                    findings.push({
-                        category: "Next.js deployment",
-                        description: "Standalone output mode is enabled. Build produces a self-contained server in .next/standalone.",
-                        confidence: "high",
-                        discoverable: false,
-                    });
+            const safeNextConfig = safePath(dir, nextConfig);
+            if (safeNextConfig)
+                try {
+                    const configContent = fs.readFileSync(safeNextConfig, "utf-8");
+                    if (configContent.includes("output:") && configContent.includes("standalone")) {
+                        findings.push({
+                            category: "Next.js deployment",
+                            description: "Standalone output mode is enabled. Build produces a self-contained server in .next/standalone.",
+                            confidence: "high",
+                            discoverable: false,
+                        });
+                    }
+                    if (configContent.includes("images") && configContent.includes("remotePatterns")) {
+                        findings.push({
+                            category: "Next.js images",
+                            description: "Remote image patterns are configured. New image domains must be added to next.config before use.",
+                            rationale: "Agents will try to use next/image with arbitrary URLs and get 400 errors without this config.",
+                            confidence: "high",
+                            discoverable: false,
+                        });
+                    }
                 }
-                if (configContent.includes("images") && configContent.includes("remotePatterns")) {
-                    findings.push({
-                        category: "Next.js images",
-                        description: "Remote image patterns are configured. New image domains must be added to next.config before use.",
-                        rationale: "Agents will try to use next/image with arbitrary URLs and get 400 errors without this config.",
-                        confidence: "high",
-                        discoverable: false,
-                    });
+                catch {
+                    // can't read config
                 }
-            }
-            catch {
-                // can't read config
-            }
         }
         detected.push({
             name: "Next.js",
@@ -157,7 +168,10 @@ export async function detectFrameworks(dir, files) {
         if (hasTwConfig) {
             try {
                 const configPath = files.find((f) => /^tailwind\.config\.(js|ts|mjs|cjs)$/.test(f));
-                const content = fs.readFileSync(path.join(dir, configPath), "utf-8");
+                const safeConfigPath = safePath(dir, configPath);
+                if (!safeConfigPath)
+                    throw new Error("path escape");
+                const content = fs.readFileSync(safeConfigPath, "utf-8");
                 if (content.includes("extend") && content.includes("colors")) {
                     findings.push({
                         category: "Tailwind",
@@ -204,9 +218,7 @@ export async function detectFrameworks(dir, files) {
                 }
                 const paths = tsconfig?.compilerOptions?.paths;
                 if (paths) {
-                    const aliases = Object.keys(paths)
-                        .map((k) => k.replace("/*", ""))
-                        .join(", ");
+                    const aliases = [...new Set(Object.keys(paths).map((k) => k.replace("/*", "")))].join(", ");
                     findings.push({
                         category: "TypeScript imports",
                         description: `Path aliases configured: ${aliases}. Use these instead of relative imports.`,

package/dist/scanner/git.js

@@ -1,4 +1,4 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 /**
  * Mine git history for non-obvious context:
@@ -33,7 +33,7 @@ export async function analyzeGitHistory(dir) {
 }
 function isGitRepo(dir) {
     try {
-        execSync("git rev-parse --is-inside-work-tree", {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
             cwd: dir,
             stdio: "pipe",
         });
@@ -45,7 +45,7 @@ function isGitRepo(dir) {
 }
 function git(dir, args) {
     try {
-        return execSync(`git ${args}`, {
+        return execFileSync("git", args, {
             cwd: dir,
             stdio: "pipe",
             maxBuffer: 10 * 1024 * 1024,
@@ -60,16 +60,21 @@ function git(dir, args) {
  */
 function detectRevertedPatterns(dir, revertedPatterns) {
     const findings = [];
-    const revertLog = git(dir, 'log --grep="^Revert" --oneline --since="1 year ago" -50');
+    const revertLog = git(dir, ["log", "--grep=^Revert", "--oneline", "--since=1 year ago", "-50"]);
     if (!revertLog.trim())
         return findings;
     const reverts = revertLog.trim().split("\n").filter(Boolean);
     if (reverts.length >= 2) {
         // Extract what was reverted
         const revertDescriptions = [];
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
         for (const line of reverts.slice(0, 10)) {
             const match = line.match(/^[a-f0-9]+ Revert "(.+)"/);
-            if (match) {
+            if (match && !REVERT_NOISE.some(n => n.test(match[1]))) {
                 revertDescriptions.push(match[1]);
                 revertedPatterns.push(match[1]);
             }
@@ -94,7 +99,7 @@ function detectRevertedPatterns(dir, revertedPatterns) {
 function detectAntiPatterns(dir) {
     const findings = [];
     // Extract detailed info from reverted commits
-    const revertLog = git(dir, 'log --grep="^Revert" --format="%s" --since="1 year ago" -20');
+    const revertLog = git(dir, ["log", "--grep=^Revert", "--format=%s", "--since=1 year ago", "-20"]);
     if (revertLog.trim()) {
         const antiPatterns = [];
         for (const line of revertLog.trim().split("\n").filter(Boolean)) {
@@ -103,8 +108,15 @@ function detectAntiPatterns(dir) {
                 antiPatterns.push(match[1]);
             }
         }
-        if (antiPatterns.length > 0) {
-            for (const pattern of antiPatterns.slice(0, 5)) {
+        // Filter out noise: CI config, deps, version bumps
+        const REVERT_NOISE = [
+            /\.yml$/i, /\.yaml$/i, /scorecard/i, /dependabot/i,
+            /^update /i, /^bump /i, /^deps/i, /^ci:/i, /^build:/i,
+            /^chore\(deps\)/i, /^chore\(release\)/i,
+        ];
+        const meaningful = antiPatterns.filter(p => !REVERT_NOISE.some(n => n.test(p)));
+        if (meaningful.length > 0) {
+            for (const pattern of meaningful.slice(0, 5)) {
                 findings.push({
                     category: "Anti-patterns",
                     description: `Tried and reverted: "${pattern}". This approach was explicitly rejected.`,
@@ -116,13 +128,13 @@ function detectAntiPatterns(dir) {
         }
     }
     // Detect files deleted in bulk (abandoned features/approaches)
-    const deletedLog = git(dir, 'log --diff-filter=D --name-only --pretty=format:"COMMIT %s" --since="6 months ago" -50');
+    const deletedLog = git(dir, ["log", "--diff-filter=D", "--name-only", "--pretty=format:COMMIT %s", "--since=6 months ago", "-50"]);
     if (deletedLog.trim()) {
         const deletionBatches = [];
         let currentMessage = "";
         let currentFiles = [];
         for (const line of deletedLog.split("\n")) {
-            const commitMatch = line.match(/^"?COMMIT (.+)"?$/);
+            const commitMatch = line.match(/^COMMIT (.+)$/);
             if (commitMatch) {
                 if (currentFiles.length >= 3) {
                     deletionBatches.push({ message: currentMessage, files: currentFiles });
@@ -137,8 +149,22 @@ function detectAntiPatterns(dir) {
         if (currentFiles.length >= 3) {
             deletionBatches.push({ message: currentMessage, files: currentFiles });
         }
+        // Filter out release/changeset/version commits and revert-of-revert noise
+        const NOISE_PATTERNS = [
+            /^chore\(release\)/i,
+            /^\[ci\] release/i,
+            /^version packages/i,
+            /^changeset/i,
+            /^bump/i,
+            /^release/i,
+            /^Revert "Revert/i,
+            /^merge/i,
+            /^ci:/i,
+            /^build:/i,
+            /^Revert /i,
+        ];
         // Only report significant deletions (3+ files in one commit = abandoned feature)
-        for (const batch of deletionBatches.slice(0, 3)) {
+        for (const batch of deletionBatches.filter(b => !NOISE_PATTERNS.some(p => p.test(b.message))).slice(0, 3)) {
             if (batch.files.length >= 3) {
                 const fileList = batch.files.slice(0, 3).map((f) => path.basename(f)).join(", ");
                 findings.push({
@@ -159,7 +185,7 @@ function detectAntiPatterns(dir) {
 function detectActiveAreas(dir, activeAreas) {
     const findings = [];
     // Get files changed in the last 30 days, count changes per directory
-    const recentChanges = git(dir, 'log --since="30 days ago" --name-only --pretty=format: --diff-filter=AMRC');
+    const recentChanges = git(dir, ["log", "--since=30 days ago", "--name-only", "--pretty=format:", "--diff-filter=AMRC"]);
     if (!recentChanges.trim())
         return findings;
     const dirCounts = new Map();
@@ -198,14 +224,14 @@ function detectActiveAreas(dir, activeAreas) {
 function detectCoChangeCoupling(dir, clusters) {
     const findings = [];
     // Get the last 200 commits with their changed files
-    const log = git(dir, 'log --name-only --pretty=format:"COMMIT" --since="6 months ago" -200');
+    const log = git(dir, ["log", "--name-only", "--pretty=format:COMMIT", "--since=6 months ago", "-200"]);
     if (!log.trim())
         return findings;
     // Parse commits into file groups
     const commits = [];
     let current = [];
     for (const line of log.split("\n")) {
-        if (line.trim() === '"COMMIT"' || line.trim() === "COMMIT") {
+        if (line.trim() === "COMMIT") {
             if (current.length > 0)
                 commits.push(current);
             current = [];
@@ -293,7 +319,7 @@ function detectCoChangeCoupling(dir, clusters) {
 function detectRapidReEdits(dir) {
     const findings = [];
     // Get files with high commit frequency in short windows
-    const log = git(dir, 'log --format="%H %aI" --name-only --since="3 months ago" -300');
+    const log = git(dir, ["log", "--format=%H %aI", "--name-only", "--since=3 months ago", "-300"]);
     if (!log.trim())
         return findings;
     // Track edits per file with timestamps
@@ -313,9 +339,17 @@ function detectRapidReEdits(dir) {
     }
     // Find files edited 5+ times within a 7-day window
     const churnyFiles = [];
+    // Filter out non-source files that naturally churn
+    const NON_SOURCE_PATTERNS = [
+        /\.md$/i, /\.mdx$/i, /\.rst$/i, /\.txt$/i, /\.json$/i, /\.ya?ml$/i, /\.lock$/i, /\.log$/i,
+        /CHANGELOG/i, /\.env/, /\.generated\./, /\.config\./,
+        /\.github\//, /\.claude\//, /dashboard\//, /ops\//,
+    ];
     for (const [file, dates] of fileEdits) {
         if (dates.length < 5)
             continue;
+        if (NON_SOURCE_PATTERNS.some((p) => p.test(file)))
+            continue;
         // Sort dates
         dates.sort((a, b) => a.getTime() - b.getTime());
         // Sliding window: find any 7-day window with 5+ edits
@@ -354,7 +388,7 @@ function detectRapidReEdits(dir) {
  */
 function detectCommitPatterns(dir) {
     const findings = [];
-    const log = git(dir, 'log --oneline --since="6 months ago" -200');
+    const log = git(dir, ["log", "--oneline", "--since=6 months ago", "-200"]);
     if (!log.trim())
         return findings;
     const messages = log.trim().split("\n").filter(Boolean);
@@ -377,7 +411,7 @@ function detectCommitPatterns(dir) {
             .map(([scope]) => scope);
         findings.push({
             category: "Commit conventions",
-            description: `Uses Conventional Commits (feat/fix/docs/etc). ${topScopes.length > 0 ? `Common scopes: ${topScopes.join(", ")}` : ""}. Follow this pattern for new commits.`,
+            description: `Uses Conventional Commits (feat/fix/docs/etc).${topScopes.length > 0 ? ` Common scopes: ${topScopes.join(", ")}.` : ""} Follow this pattern for new commits.`,
             confidence: "high",
             discoverable: false,
         });

package/dist/scanner/graph.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 /**
  * Build an import/dependency graph and run PageRank to identify
  * the most structurally important files. Conventions found in
@@ -16,7 +23,9 @@ export async function analyzeImportGraph(dir, files) {
     const edges = [];
     const fileSet = new Set(sourceFiles);
     for (const file of sourceFiles) {
-        const filePath = path.join(dir, file);
+        const filePath = safePath(dir, file);
+        if (!filePath)
+            continue;
         let content;
         try {
             content = fs.readFileSync(filePath, "utf-8");

package/dist/scanner/index.js

@@ -28,6 +28,7 @@ export async function scanProject(dir) {
         nodir: true,
         ignore: IGNORE_PATTERNS,
         dot: true,
+        follow: false,
     });
     // Detect languages from file extensions
     const languages = detectLanguages(files);

package/dist/scanner/patterns.js

@@ -1,5 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
+function safePath(dir, file) {
+    const resolved = path.resolve(path.join(dir, file));
+    if (!resolved.startsWith(path.resolve(dir) + path.sep) && resolved !== path.resolve(dir)) {
+        return null;
+    }
+    return resolved;
+}
 /**
  * Detect code patterns and conventions that are non-obvious.
  * This is the core intelligence layer -- finding things agents miss.
@@ -17,8 +24,11 @@ export async function detectPatterns(dir, files, frameworks) {
     const sampled = sampleFiles(sourceFiles, 50);
     const fileContents = new Map();
     for (const file of sampled) {
+        const safe = safePath(dir, file);
+        if (!safe)
+            continue;
         try {
-            const content = fs.readFileSync(path.join(dir, file), "utf-8");
+            const content = fs.readFileSync(safe, "utf-8");
             fileContents.set(file, content);
         }
         catch {
@@ -54,8 +64,11 @@ function sampleFiles(files, maxCount) {
         f.includes("layout.") ||
         f.includes("middleware."));
     const rest = files.filter((f) => !priority.includes(f));
-    const shuffled = rest.sort(() => Math.random() - 0.5);
-    return [...priority, ...shuffled].slice(0, maxCount);
+    // Deterministic sampling: sort by path, take evenly spaced files
+    const sorted = rest.sort();
+    const step = Math.max(1, Math.floor(sorted.length / Math.max(1, maxCount - priority.length)));
+    const sampled = sorted.filter((_, i) => i % step === 0);
+    return [...priority, ...sampled].slice(0, maxCount);
 }
 function detectBarrelExports(files, contents) {
     const indexFiles = files.filter((f) => path.basename(f).startsWith("index.") && !f.includes("node_modules"));
@@ -275,8 +288,11 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     const allContents = new Map(contents);
     for (const file of extraSample) {
         if (!allContents.has(file)) {
+            const safe = safePath(dir, file);
+            if (!safe)
+                continue;
             try {
-                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                const content = fs.readFileSync(safe, "utf-8");
                 allContents.set(file, content);
             }
             catch { /* skip */ }
@@ -305,7 +321,25 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
             }
         }
     }
-    const dominantI18n = i18nPatterns.filter((p) => p.count >= 3).sort((a, b) => b.count - a.count);
+    // Filter: if only t() matched, require corroborating evidence (i18n files or packages)
+    const hasI18nFiles = files.some((f) => f.includes("locale") || f.includes("i18n") || f.includes("translations") || f.includes("messages/"));
+    let hasI18nPackage = false;
+    for (const [f, c] of allContents) {
+        if (f.endsWith("package.json") && (c.includes("i18next") || c.includes("react-intl") || c.includes("next-intl") || c.includes("@lingui"))) {
+            hasI18nPackage = true;
+            break;
+        }
+    }
+    const dominantI18n = i18nPatterns
+        .filter((p) => {
+        if (p.count < 3)
+            return false;
+        // t() alone is too generic — require corroborating evidence
+        if (p.hook === 't("key")' && !hasI18nFiles && !hasI18nPackage)
+            return false;
+        return true;
+    })
+        .sort((a, b) => b.count - a.count);
     if (dominantI18n.length > 0) {
         const primary = dominantI18n[0];
         let desc = `User-facing strings use ${primary.hook} for internationalization.`;
@@ -332,10 +366,10 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 2. ROUTING / API PATTERNS
     // ========================================
     const routerPatterns = [
-        { pattern: "trpc\\.router|createTRPCRouter|t\\.router", name: "tRPC routers", count: 0 },
+        { pattern: "trpc\\.router|createTRPCRouter|from ['\"]@trpc", name: "tRPC routers", count: 0 },
         { pattern: "express\\.Router|router\\.get|router\\.post", name: "Express routers", count: 0 },
         { pattern: "app\\.get\\(|app\\.post\\(|app\\.put\\(", name: "Express app routes", count: 0 },
-        { pattern: "Hono|app\\.route\\(|c\\.json\\(", name: "Hono routes", count: 0 },
+        { pattern: "new Hono|from ['\"]hono['\"]", name: "Hono routes", count: 0 },
         { pattern: "FastAPI|@app\\.(get|post|put|delete)", name: "FastAPI endpoints", count: 0 },
         { pattern: "flask\\.route|@app\\.route", name: "Flask routes", count: 0 },
         { pattern: "gin\\.Engine|r\\.GET|r\\.POST", name: "Gin routes", count: 0 },
@@ -364,7 +398,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // ========================================
     const schemaPatterns = [
         { pattern: "z\\.object|z\\.string|z\\.number", name: "Zod", usage: "Use Zod schemas for validation", count: 0 },
-        { pattern: "BaseModel|Field\\(", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
+        { pattern: "class\\s+\\w+\\(BaseModel\\)|from pydantic", name: "Pydantic", usage: "Use Pydantic BaseModel for data classes", count: 0 },
         { pattern: "Joi\\.object|Joi\\.string", name: "Joi", usage: "Use Joi schemas for validation", count: 0 },
         { pattern: "yup\\.object|yup\\.string", name: "Yup", usage: "Use Yup schemas for validation", count: 0 },
         { pattern: "class.*Serializer.*:|serializers\\.Serializer", name: "Django serializers", usage: "Use Django REST serializers for API data", count: 0 },
@@ -420,7 +454,7 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 5. TESTING PATTERNS
     // ========================================
     const testPatterns = [
-        { pattern: "describe\\(|it\\(|test\\(", name: "Jest/Vitest", count: 0 },
+        { pattern: "describe\\(|it\\(|test\\(", name: "_generic_test", count: 0 },
         { pattern: "def test_|class Test|pytest", name: "pytest", count: 0 },
         { pattern: "func Test.*\\(t \\*testing\\.T\\)", name: "Go testing", count: 0 },
         { pattern: "expect\\(.*\\)\\.to", name: "Chai/expect", count: 0 },
@@ -432,8 +466,11 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
         .slice(0, 10);
     for (const file of testSampled) {
         if (!allContents.has(file)) {
+            const safe = safePath(dir, file);
+            if (!safe)
+                continue;
             try {
-                const content = fs.readFileSync(path.join(dir, file), "utf-8");
+                const content = fs.readFileSync(safe, "utf-8");
                 allContents.set(file, content);
             }
             catch { /* skip */ }
@@ -450,7 +487,46 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     }
     const dominantTest = testPatterns.filter((p) => p.count >= 2).sort((a, b) => b.count - a.count);
     if (dominantTest.length > 0) {
-        const primary = dominantTest[0];
+        let primary = dominantTest[0];
+        // Disambiguate generic test pattern by checking package.json devDependencies
+        if (primary.name === "_generic_test") {
+            let pkgContent = allContents.get("package.json") || "";
+            if (!pkgContent) {
+                const pkgPath = safePath(dir, "package.json");
+                if (pkgPath) {
+                    try {
+                        pkgContent = fs.readFileSync(pkgPath, "utf-8");
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            if (pkgContent.includes('"vitest"')) {
+                primary = { ...primary, name: "Vitest" };
+            }
+            else if (pkgContent.includes('"jest"') || pkgContent.includes('"@jest/')) {
+                primary = { ...primary, name: "Jest" };
+            }
+            else if (pkgContent.includes('"mocha"')) {
+                primary = { ...primary, name: "Mocha" };
+            }
+            else if (pkgContent.includes('"jasmine"')) {
+                primary = { ...primary, name: "Jasmine" };
+            }
+            else {
+                // Check for Deno (deno.json/deno.jsonc) or Bun (bun.lockb)
+                const hasDeno = files.some(f => f === "deno.json" || f === "deno.jsonc" || f === "deno.lock");
+                const hasBun = files.some(f => f === "bun.lockb" || f === "bunfig.toml");
+                if (hasDeno) {
+                    primary = { ...primary, name: "Deno test" };
+                }
+                else if (hasBun) {
+                    primary = { ...primary, name: "Bun test" };
+                }
+                else {
+                    primary = { ...primary, name: "Jest" }; // default for JS/TS projects
+                }
+            }
+        }
         // Also detect common test utilities/helpers
         const testHelperFiles = files.filter((f) => (f.includes("test-utils") || f.includes("testUtils") || f.includes("fixtures") || f.includes("helpers")) &&
             (f.includes("test") || f.includes("spec")));
@@ -511,9 +587,9 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     // 7. STYLING CONVENTIONS
     // ========================================
     const stylePatterns = [
-        { pattern: "className=|class=.*tw-", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
-        { pattern: "styled\\.|styled\\(|css`", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
-        { pattern: "styles\\.\\w+|from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
+        { pattern: "class=.*tw-|className=[\"'](?:flex |grid |p-|m-|text-|bg-|border-|rounded-|shadow-|w-|h-)", name: "Tailwind CSS", desc: "Styling uses Tailwind CSS utility classes", count: 0 },
+        { pattern: "from ['\"]styled-components|from ['\"]@emotion|styled\\.|styled\\(", name: "styled-components/Emotion", desc: "Styling uses CSS-in-JS (styled-components or Emotion)", count: 0 },
+        { pattern: "from.*\\.module\\.(css|scss)", name: "CSS Modules", desc: "Styling uses CSS Modules (*.module.css)", count: 0 },
     ];
     for (const [f, content] of allContents) {
         for (const p of stylePatterns) {
@@ -530,13 +606,15 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
         if (primary.name === "Tailwind CSS") {
             const twConfig = files.find((f) => f.includes("tailwind.config"));
             if (twConfig) {
-                try {
-                    const configContent = fs.readFileSync(path.join(dir, twConfig), "utf-8");
-                    if (configContent.includes("colors") || configContent.includes("extend")) {
-                        desc += ` Custom design tokens defined in ${twConfig} — use these instead of arbitrary values.`;
+                const safeTw = safePath(dir, twConfig);
+                if (safeTw)
+                    try {
+                        const configContent = fs.readFileSync(safeTw, "utf-8");
+                        if (configContent.includes("colors") || configContent.includes("extend")) {
+                            desc += ` Custom design tokens defined in ${twConfig} — use these instead of arbitrary values.`;
+                        }
                     }
-                }
-                catch { /* skip */ }
+                    catch { /* skip */ }
             }
         }
         findings.push({
@@ -627,13 +705,15 @@ function detectDominantPatterns(dir, files, contents, frameworks) {
     if (dominantRouter.length > 0) {
         const routeDirs = files
             .filter((f) => (f.includes("routes") || f.includes("routers") || f.includes("api/") || f.includes("app/api/")) &&
-            !f.includes("node_modules") && !f.includes(".test.") &&
+            !f.includes("node_modules") && !f.includes(".test.") && !f.includes(".spec.") &&
+            !f.includes("test/") && !f.includes("tests/") && !f.includes("__test") &&
+            !f.includes("fixture") && !f.includes("mock") &&
             (f.endsWith(".ts") || f.endsWith(".js") || f.endsWith(".py") || f.endsWith(".go")))
             .map((f) => {
             const parts = f.split("/");
-            // Get the directory containing route files
             return parts.slice(0, -1).join("/");
         })
+            .filter((v) => v && v !== "." && v.length > 0) // filter empty/root paths
             .filter((v, i, a) => a.indexOf(v) === i)
             .slice(0, 3);
         if (routeDirs.length > 0) {

package/dist/utils/output.js

@@ -2,9 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 export async function writeOutput(dir, filename, content) {
     const filePath = path.join(dir, filename);
-    const parentDir = path.dirname(filePath);
+    const resolved = path.resolve(filePath);
+    if (!resolved.startsWith(path.resolve(dir) + path.sep)) {
+        throw new Error(`Output path escapes target directory: ${filename}`);
+    }
+    const parentDir = path.dirname(resolved);
     if (!fs.existsSync(parentDir)) {
         fs.mkdirSync(parentDir, { recursive: true });
     }
-    fs.writeFileSync(filePath, content, "utf-8");
+    fs.writeFileSync(resolved, content, "utf-8");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcebook",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {