@compilr-dev/sdk 0.9.8 → 0.9.9

package/dist/detection/common.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Common Detection Utilities
+ *
+ * Shared by all type-specific strategies: git detection, README parsing,
+ * file counting, folder name parsing.
+ */
+import type { DetectionResult } from './types.js';
+/**
+ * Detect common project info (runs for ALL project types).
+ * Returns a base DetectionResult with name, git, README, file counts.
+ */
+export declare function detectCommon(projectPath: string): DetectionResult;
+/**
+ * List files matching a pattern in a directory (non-recursive or single level).
+ */
+export declare function findFiles(dir: string, predicate: (name: string, ext: string) => boolean, maxDepth?: number): string[];
+/**
+ * Check if a directory exists within the project.
+ */
+export declare function hasDirectory(projectPath: string, dirName: string): boolean;
+/**
+ * Read a file's content if it exists, or return undefined.
+ */
+export declare function readFileIfExists(filePath: string): string | undefined;

package/dist/detection/common.js

@@ -0,0 +1,247 @@
+/**
+ * Common Detection Utilities
+ *
+ * Shared by all type-specific strategies: git detection, README parsing,
+ * file counting, folder name parsing.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+/** Directories to skip when scanning */
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.mypy_cache',
+    '.pytest_cache',
+    '.next',
+    '.nuxt',
+    'dist',
+    'build',
+    'target',
+    '.gradle',
+    '.idea',
+    '.vscode',
+    '.DS_Store',
+    'vendor',
+    '.compilr',
+    '.compilr-dev',
+]);
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdx']);
+/**
+ * Detect common project info (runs for ALL project types).
+ * Returns a base DetectionResult with name, git, README, file counts.
+ */
+export function detectCommon(projectPath) {
+    const folderName = basename(projectPath);
+    const name = slugify(folderName);
+    const displayName = prettify(folderName);
+    // Git detection
+    const hasGit = existsSync(join(projectPath, '.git'));
+    let gitRemote;
+    if (hasGit) {
+        gitRemote = readGitRemote(projectPath);
+    }
+    // COMPILR.md
+    const hasCompilrMd = existsSync(join(projectPath, 'COMPILR.md'));
+    // Description from README
+    const description = readDescription(projectPath);
+    // File counting
+    const content = countFiles(projectPath);
+    return {
+        name,
+        displayName,
+        description,
+        gitRemote,
+        hasGit,
+        hasCompilrMd,
+        content,
+    };
+}
+/**
+ * Read the git remote URL from .git/config.
+ */
+function readGitRemote(projectPath) {
+    const configPath = join(projectPath, '.git', 'config');
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const config = readFileSync(configPath, 'utf-8');
+        const match = config.match(/\[remote "origin"\]\s*\n\s*url\s*=\s*(.+)/);
+        return match?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read description from README.md or COMPILR.md (first non-heading paragraph).
+ */
+function readDescription(projectPath) {
+    const candidates = ['README.md', 'readme.md', 'COMPILR.md'];
+    for (const file of candidates) {
+        const filePath = join(projectPath, file);
+        if (!existsSync(filePath))
+            continue;
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const lines = content.split('\n');
+            // Find first non-empty, non-heading line
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                if (trimmed.startsWith('#'))
+                    continue;
+                if (trimmed.startsWith('!['))
+                    continue; // badge images
+                if (trimmed.startsWith('<!--'))
+                    continue;
+                // Found a content line — take up to 200 chars
+                return trimmed.length > 200 ? trimmed.slice(0, 200) + '...' : trimmed;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Count files in a project directory (non-recursive into ignored dirs).
+ */
+function countFiles(projectPath) {
+    let fileCount = 0;
+    let totalSizeBytes = 0;
+    let markdownFiles = 0;
+    let imageFiles = 0;
+    function walk(dir, depth) {
+        if (depth > 8)
+            return; // Don't go too deep
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            if (entry.startsWith('.') && entry !== '.git')
+                continue;
+            const fullPath = join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(fullPath, depth + 1);
+            }
+            else if (stat.isFile()) {
+                fileCount++;
+                totalSizeBytes += stat.size;
+                const ext = extname(entry).toLowerCase();
+                if (MARKDOWN_EXTENSIONS.has(ext))
+                    markdownFiles++;
+                if (IMAGE_EXTENSIONS.has(ext))
+                    imageFiles++;
+            }
+        }
+    }
+    walk(projectPath, 0);
+    return {
+        fileCount,
+        totalSizeKB: Math.round(totalSizeBytes / 1024),
+        markdownFiles,
+        imageFiles,
+    };
+}
+/**
+ * List files matching a pattern in a directory (non-recursive or single level).
+ */
+export function findFiles(dir, predicate, maxDepth = 2) {
+    const results = [];
+    function walk(currentDir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(currentDir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const fullPath = join(currentDir, entry);
+            let stat;
+            try {
+                stat = statSync(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(fullPath, depth + 1);
+            }
+            else if (stat.isFile()) {
+                const ext = extname(entry).toLowerCase();
+                if (predicate(entry, ext)) {
+                    // Return relative path from root dir
+                    results.push(fullPath.slice(dir.length + 1));
+                }
+            }
+        }
+    }
+    walk(dir, 0);
+    return results;
+}
+/**
+ * Check if a directory exists within the project.
+ */
+export function hasDirectory(projectPath, dirName) {
+    const dirPath = join(projectPath, dirName);
+    try {
+        return existsSync(dirPath) && statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a file's content if it exists, or return undefined.
+ */
+export function readFileIfExists(filePath) {
+    try {
+        if (existsSync(filePath))
+            return readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+/**
+ * Slugify a folder name for use as project name.
+ */
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Prettify a folder name for display.
+ */
+function prettify(name) {
+    return name.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}

package/dist/detection/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Project Detection — Universal project content detection.
+ */
+export { detectProject, suggestProjectType } from './project-detector.js';
+export { detectCommon } from './common.js';
+export type { DetectProjectOptions, DetectionResult, ContentSummary, DetectionStrategy, } from './types.js';

package/dist/detection/index.js

@@ -0,0 +1,5 @@
+/**
+ * Project Detection — Universal project content detection.
+ */
+export { detectProject, suggestProjectType } from './project-detector.js';
+export { detectCommon } from './common.js';

package/dist/detection/project-detector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Project Detector — Universal project detection dispatcher.
+ *
+ * Runs common detection (git, README, file counts) for all types,
+ * then delegates to a type-specific strategy for additional scanning.
+ */
+import type { DetectProjectOptions, DetectionResult } from './types.js';
+/**
+ * Detect project contents based on the specified type.
+ *
+ * 1. Runs common detection (git, README, file counts) for all types
+ * 2. Delegates to type-specific strategy for additional scanning
+ *
+ * @example
+ * ```typescript
+ * const result = await detectProject({
+ *   path: '/Users/me/projects/my-app',
+ *   type: 'web',
+ * });
+ * console.log(result.content.language); // 'typescript'
+ * console.log(result.content.framework); // 'react + express'
+ * ```
+ */
+export declare function detectProject(options: DetectProjectOptions): DetectionResult;
+/**
+ * Quick check to suggest a project type based on folder contents.
+ * Returns the most likely type, or 'general' if uncertain.
+ */
+export declare function suggestProjectType(projectPath: string): string;

package/dist/detection/project-detector.js

@@ -0,0 +1,106 @@
+/**
+ * Project Detector — Universal project detection dispatcher.
+ *
+ * Runs common detection (git, README, file counts) for all types,
+ * then delegates to a type-specific strategy for additional scanning.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectCommon } from './common.js';
+import { detectSoftware } from './strategies/software.js';
+import { detectResearch } from './strategies/research.js';
+import { detectBook } from './strategies/book.js';
+import { detectBusiness } from './strategies/business.js';
+import { detectContent } from './strategies/content.js';
+import { detectTechDocs } from './strategies/tech-docs.js';
+import { detectCourse } from './strategies/course.js';
+import { detectGeneral } from './strategies/general.js';
+/**
+ * Strategy map — maps project type IDs to detection functions.
+ * Software subtypes (web, cli, library, api) all use the software strategy.
+ */
+const STRATEGIES = {
+    // Software types
+    web: detectSoftware,
+    cli: detectSoftware,
+    library: detectSoftware,
+    api: detectSoftware,
+    // Non-software types
+    research: detectResearch,
+    book: detectBook,
+    'business-plan': detectBusiness,
+    content: detectContent,
+    'tech-docs': detectTechDocs,
+    course: detectCourse,
+    // Catch-all
+    general: detectGeneral,
+};
+/**
+ * Detect project contents based on the specified type.
+ *
+ * 1. Runs common detection (git, README, file counts) for all types
+ * 2. Delegates to type-specific strategy for additional scanning
+ *
+ * @example
+ * ```typescript
+ * const result = await detectProject({
+ *   path: '/Users/me/projects/my-app',
+ *   type: 'web',
+ * });
+ * console.log(result.content.language); // 'typescript'
+ * console.log(result.content.framework); // 'react + express'
+ * ```
+ */
+export function detectProject(options) {
+    // Step 1: Common detection (runs for ALL types)
+    const base = detectCommon(options.path);
+    // Step 2: Type-specific strategy
+    const strategy = STRATEGIES[options.type] ?? detectGeneral;
+    const enrichedContent = strategy(options.path, base.content);
+    return {
+        ...base,
+        content: enrichedContent,
+    };
+}
+/**
+ * Quick check to suggest a project type based on folder contents.
+ * Returns the most likely type, or 'general' if uncertain.
+ */
+export function suggestProjectType(projectPath) {
+    // Software indicators (strongest signals)
+    if (existsSync(join(projectPath, 'package.json')))
+        return 'web';
+    if (existsSync(join(projectPath, 'go.mod')))
+        return 'web';
+    if (existsSync(join(projectPath, 'Cargo.toml')))
+        return 'web';
+    if (existsSync(join(projectPath, 'pyproject.toml')) ||
+        existsSync(join(projectPath, 'requirements.txt'))) {
+        // Python could be software or research — check for research indicators
+        if (existsSync(join(projectPath, 'references.bib')) ||
+            existsSync(join(projectPath, 'main.tex'))) {
+            return 'research';
+        }
+        return 'web';
+    }
+    if (existsSync(join(projectPath, 'pom.xml')) || existsSync(join(projectPath, 'build.gradle')))
+        return 'web';
+    // Research indicators
+    try {
+        const entries = readdirSync(projectPath);
+        if (entries.some((f) => f.endsWith('.bib')))
+            return 'research';
+        if (entries.includes('main.tex'))
+            return 'research';
+        // Tech docs indicators
+        if (entries.includes('mkdocs.yml') || entries.includes('docusaurus.config.js'))
+            return 'tech-docs';
+        // Book indicators
+        if (entries.some((f) => /^(chapter|ch)[-_]?\d/i.test(f)))
+            return 'book';
+    }
+    catch {
+        /* unreadable directory */
+    }
+    return 'general';
+}

package/dist/detection/strategies/book.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Book Detection Strategy
+ *
+ * Detects: chapter files, outline, manuscript/draft folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectBook(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/book.js

@@ -0,0 +1,48 @@
+/**
+ * Book Detection Strategy
+ *
+ * Detects: chapter files, outline, manuscript/draft folders.
+ */
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectBook(path, base) {
+    const result = { ...base };
+    // Chapter files (chapter-1.md, ch01.md, chapters/01-intro.md, etc.)
+    const chapterPattern = /^(chapter|ch)[-_]?\d/i;
+    const chapterFiles = findFiles(path, (name) => chapterPattern.test(name), 2);
+    // Also check chapters/ directory
+    if (hasDirectory(path, 'chapters')) {
+        const inDir = findFiles(join(path, 'chapters'), (_name, ext) => ext === '.md' || ext === '.txt', 1);
+        chapterFiles.push(...inDir.map((f) => `chapters/${f}`));
+    }
+    if (chapterFiles.length > 0) {
+        result.chapterCount = chapterFiles.length;
+    }
+    // Outline file
+    const outlineCandidates = [
+        'outline.md',
+        'outline.txt',
+        'OUTLINE.md',
+        'toc.md',
+        'table-of-contents.md',
+    ];
+    for (const candidate of outlineCandidates) {
+        const found = findFiles(path, (name) => name.toLowerCase() === candidate.toLowerCase(), 0);
+        if (found.length > 0) {
+            result.outlineFile = found[0];
+            break;
+        }
+    }
+    // Draft/manuscript files
+    const draftDirs = ['manuscript', 'drafts', 'draft', 'content'];
+    for (const dir of draftDirs) {
+        if (hasDirectory(path, dir)) {
+            const drafts = findFiles(join(path, dir), (_name, ext) => ext === '.md' || ext === '.txt', 1);
+            if (drafts.length > 0) {
+                result.draftFiles = drafts.map((f) => `${dir}/${f}`);
+                break;
+            }
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/business.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Business Plan Detection Strategy
+ *
+ * Detects: spreadsheets, presentations, analysis folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectBusiness(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/business.js

@@ -0,0 +1,22 @@
+/**
+ * Business Plan Detection Strategy
+ *
+ * Detects: spreadsheets, presentations, analysis folders.
+ */
+import { findFiles } from '../common.js';
+export function detectBusiness(path, base) {
+    const result = { ...base };
+    // Spreadsheet files
+    const spreadsheetExts = new Set(['.xlsx', '.xls', '.csv', '.tsv', '.ods']);
+    const spreadsheets = findFiles(path, (_name, ext) => spreadsheetExts.has(ext), 2);
+    if (spreadsheets.length > 0) {
+        result.spreadsheetFiles = spreadsheets.length;
+    }
+    // Presentation files
+    const presentationExts = new Set(['.pptx', '.ppt', '.pdf', '.key']);
+    const presentations = findFiles(path, (_name, ext) => presentationExts.has(ext), 2);
+    if (presentations.length > 0) {
+        result.presentationFiles = presentations.length;
+    }
+    return result;
+}

package/dist/detection/strategies/content.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content & Marketing Detection Strategy
+ *
+ * Detects: article folders, editorial calendar, media assets.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectContent(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/content.js

@@ -0,0 +1,21 @@
+/**
+ * Content & Marketing Detection Strategy
+ *
+ * Detects: article folders, editorial calendar, media assets.
+ */
+import { findFiles, hasDirectory } from '../common.js';
+export function detectContent(path, base) {
+    const result = { ...base };
+    // Draft files in common content directories
+    const contentDirs = ['articles', 'posts', 'content', 'blog', 'drafts'];
+    for (const dir of contentDirs) {
+        if (hasDirectory(path, dir)) {
+            const drafts = findFiles(`${path}/${dir}`, (_name, ext) => ext === '.md' || ext === '.txt', 1);
+            if (drafts.length > 0) {
+                result.draftFiles = drafts.map((f) => `${dir}/${f}`);
+                break;
+            }
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/course.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Course / Training Detection Strategy
+ *
+ * Detects: lesson/module directories, exercise files, syllabus.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectCourse(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/course.js

@@ -0,0 +1,30 @@
+/**
+ * Course / Training Detection Strategy
+ *
+ * Detects: lesson/module directories, exercise files, syllabus.
+ */
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectCourse(path, base) {
+    const result = { ...base };
+    // Lesson/module directories
+    const lessonDirs = ['modules', 'lessons', 'units', 'weeks', 'sessions'];
+    for (const dir of lessonDirs) {
+        if (hasDirectory(path, dir)) {
+            // Count subdirectories as lessons
+            const items = findFiles(join(path, dir), () => true, 0);
+            result.lessonCount = items.length;
+            break;
+        }
+    }
+    // Exercise files
+    const exerciseDirs = ['exercises', 'homework', 'labs', 'assignments'];
+    for (const dir of exerciseDirs) {
+        if (hasDirectory(path, dir)) {
+            const files = findFiles(join(path, dir), () => true, 1);
+            result.exerciseFiles = files.length;
+            break;
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/general.d.ts

@@ -0,0 +1,8 @@
+/**
+ * General Detection Strategy
+ *
+ * Minimal scan — just the common detection (git, README, file counts).
+ * No type-specific additions.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectGeneral(_path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/general.js

@@ -0,0 +1,10 @@
+/**
+ * General Detection Strategy
+ *
+ * Minimal scan — just the common detection (git, README, file counts).
+ * No type-specific additions.
+ */
+export function detectGeneral(_path, base) {
+    // Common detection already covers everything for general projects
+    return { ...base };
+}

package/dist/detection/strategies/research.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Research Detection Strategy
+ *
+ * Detects: bibliography files, LaTeX, data files, draft folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectResearch(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/research.js

@@ -0,0 +1,44 @@
+/**
+ * Research Detection Strategy
+ *
+ * Detects: bibliography files, LaTeX, data files, draft folders.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectResearch(path, base) {
+    const result = { ...base };
+    // Bibliography (.bib files)
+    const bibFiles = findFiles(path, (_name, ext) => ext === '.bib', 1);
+    if (bibFiles.length > 0) {
+        result.bibliographyFile = bibFiles[0];
+        try {
+            const content = readFileSync(join(path, bibFiles[0]), 'utf-8');
+            result.bibliographyEntries = (content.match(/@\w+\{/g) ?? []).length;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // LaTeX files
+    const texFiles = findFiles(path, (_name, ext) => ext === '.tex', 2);
+    if (texFiles.length > 0) {
+        result.latexFiles = texFiles;
+    }
+    // Data files (.csv, .xlsx, .json in data/ or root)
+    const dataExtensions = new Set(['.csv', '.xlsx', '.xls', '.json', '.tsv']);
+    const dataFiles = findFiles(path, (_name, ext) => dataExtensions.has(ext), 2);
+    if (dataFiles.length > 0) {
+        result.dataFiles = dataFiles.length;
+    }
+    // Check for common research folders
+    if (hasDirectory(path, 'drafts') || hasDirectory(path, 'papers')) {
+        // Count draft markdown files
+        const draftDir = hasDirectory(path, 'drafts') ? 'drafts' : 'papers';
+        const drafts = findFiles(join(path, draftDir), (_name, ext) => ext === '.md' || ext === '.tex', 1);
+        if (drafts.length > 0) {
+            result.draftFiles = drafts.map((f) => `${draftDir}/${f}`);
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/software.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Software Detection Strategy
+ *
+ * Detects: language, framework, package manager, entry points, test framework.
+ * Uses file-based heuristics (package.json, go.mod, pyproject.toml, etc.).
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectSoftware(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/software.js

@@ -0,0 +1,199 @@
+/**
+ * Software Detection Strategy
+ *
+ * Detects: language, framework, package manager, entry points, test framework.
+ * Uses file-based heuristics (package.json, go.mod, pyproject.toml, etc.).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findFiles, readFileIfExists } from '../common.js';
+export function detectSoftware(path, base) {
+    const result = { ...base };
+    // ── Node.js / JavaScript / TypeScript ─────────────────────────────
+    const pkgJsonPath = join(path, 'package.json');
+    if (existsSync(pkgJsonPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+            const rawDeps = (pkg.dependencies ?? {});
+            const rawDevDeps = (pkg.devDependencies ?? {});
+            const deps = { ...rawDeps, ...rawDevDeps };
+            // Language
+            result.language =
+                deps.typescript || existsSync(join(path, 'tsconfig.json')) ? 'typescript' : 'javascript';
+            // Framework
+            if (deps.next)
+                result.framework = 'next';
+            else if (deps.react)
+                result.framework = deps.express ? 'react + express' : 'react';
+            else if (deps.vue)
+                result.framework = deps.express ? 'vue + express' : 'vue';
+            else if (deps.svelte || deps['@sveltejs/kit'])
+                result.framework = 'svelte';
+            else if (deps.express)
+                result.framework = 'express';
+            else if (deps.fastify)
+                result.framework = 'fastify';
+            else if (deps.hono)
+                result.framework = 'hono';
+            // Package manager
+            if (existsSync(join(path, 'pnpm-lock.yaml')))
+                result.packageManager = 'pnpm';
+            else if (existsSync(join(path, 'yarn.lock')))
+                result.packageManager = 'yarn';
+            else if (existsSync(join(path, 'bun.lockb')))
+                result.packageManager = 'bun';
+            else
+                result.packageManager = 'npm';
+            // Test framework
+            if (deps.vitest)
+                result.testFramework = 'vitest';
+            else if (deps.jest)
+                result.testFramework = 'jest';
+            else if (deps.mocha)
+                result.testFramework = 'mocha';
+            else if (deps['@playwright/test'])
+                result.testFramework = 'playwright';
+            // Entry points
+            const entries = [];
+            for (const candidate of [
+                'src/index.ts',
+                'src/index.js',
+                'src/main.ts',
+                'src/main.js',
+                'src/app.ts',
+                'src/app.js',
+                'index.ts',
+                'index.js',
+            ]) {
+                if (existsSync(join(path, candidate)))
+                    entries.push(candidate);
+            }
+            if (entries.length > 0)
+                result.entryPoints = entries;
+        }
+        catch {
+            /* invalid package.json */
+        }
+        return result;
+    }
+    // ── Python ────────────────────────────────────────────────────────
+    const hasPyproject = existsSync(join(path, 'pyproject.toml'));
+    const hasRequirements = existsSync(join(path, 'requirements.txt'));
+    const hasSetupPy = existsSync(join(path, 'setup.py'));
+    if (hasPyproject || hasRequirements || hasSetupPy) {
+        result.language = 'python';
+        if (hasPyproject) {
+            const content = readFileIfExists(join(path, 'pyproject.toml'));
+            if (content) {
+                if (content.includes('poetry'))
+                    result.packageManager = 'poetry';
+                else if (content.includes('pdm'))
+                    result.packageManager = 'pdm';
+                else
+                    result.packageManager = 'pip';
+                if (content.includes('fastapi'))
+                    result.framework = 'fastapi';
+                else if (content.includes('django'))
+                    result.framework = 'django';
+                else if (content.includes('flask'))
+                    result.framework = 'flask';
+                if (content.includes('pytest'))
+                    result.testFramework = 'pytest';
+            }
+        }
+        else {
+            result.packageManager = 'pip';
+            const reqs = readFileIfExists(join(path, 'requirements.txt'));
+            if (reqs) {
+                if (reqs.includes('fastapi'))
+                    result.framework = 'fastapi';
+                else if (reqs.includes('django'))
+                    result.framework = 'django';
+                else if (reqs.includes('flask'))
+                    result.framework = 'flask';
+                if (reqs.includes('pytest'))
+                    result.testFramework = 'pytest';
+            }
+        }
+        const entries = [];
+        for (const candidate of ['main.py', 'app.py', 'server.py', 'src/main.py', 'src/app.py']) {
+            if (existsSync(join(path, candidate)))
+                entries.push(candidate);
+        }
+        if (entries.length > 0)
+            result.entryPoints = entries;
+        return result;
+    }
+    // ── Go ────────────────────────────────────────────────────────────
+    if (existsSync(join(path, 'go.mod'))) {
+        result.language = 'go';
+        result.packageManager = 'go mod';
+        const goMod = readFileIfExists(join(path, 'go.mod'));
+        if (goMod) {
+            if (goMod.includes('github.com/gin-gonic/gin'))
+                result.framework = 'gin';
+            else if (goMod.includes('github.com/labstack/echo'))
+                result.framework = 'echo';
+            else if (goMod.includes('github.com/gofiber/fiber'))
+                result.framework = 'fiber';
+        }
+        const entries = [];
+        for (const candidate of ['main.go', 'cmd/main.go', 'cmd/server/main.go']) {
+            if (existsSync(join(path, candidate)))
+                entries.push(candidate);
+        }
+        if (entries.length > 0)
+            result.entryPoints = entries;
+        return result;
+    }
+    // ── Rust ──────────────────────────────────────────────────────────
+    if (existsSync(join(path, 'Cargo.toml'))) {
+        result.language = 'rust';
+        result.packageManager = 'cargo';
+        const cargo = readFileIfExists(join(path, 'Cargo.toml'));
+        if (cargo) {
+            if (cargo.includes('actix-web'))
+                result.framework = 'actix';
+            else if (cargo.includes('axum'))
+                result.framework = 'axum';
+            else if (cargo.includes('rocket'))
+                result.framework = 'rocket';
+        }
+        if (existsSync(join(path, 'src', 'main.rs')))
+            result.entryPoints = ['src/main.rs'];
+        else if (existsSync(join(path, 'src', 'lib.rs')))
+            result.entryPoints = ['src/lib.rs'];
+        return result;
+    }
+    // ── Java / Kotlin ─────────────────────────────────────────────────
+    if (existsSync(join(path, 'pom.xml'))) {
+        result.language = 'java';
+        result.packageManager = 'maven';
+        return result;
+    }
+    if (existsSync(join(path, 'build.gradle')) || existsSync(join(path, 'build.gradle.kts'))) {
+        result.language = existsSync(join(path, 'build.gradle.kts')) ? 'kotlin' : 'java';
+        result.packageManager = 'gradle';
+        return result;
+    }
+    // ── Fallback: check for common source files ───────────────────────
+    const sourceFiles = findFiles(path, (_name, ext) => ['.ts', '.js', '.py', '.go', '.rs', '.java', '.kt', '.rb', '.php', '.cs', '.swift'].includes(ext), 1);
+    if (sourceFiles.length > 0) {
+        const ext = sourceFiles[0].split('.').pop();
+        const langMap = {
+            ts: 'typescript',
+            js: 'javascript',
+            py: 'python',
+            go: 'go',
+            rs: 'rust',
+            java: 'java',
+            kt: 'kotlin',
+            rb: 'ruby',
+            php: 'php',
+            cs: 'csharp',
+            swift: 'swift',
+        };
+        result.language = ext ? langMap[ext] : undefined;
+    }
+    return result;
+}

package/dist/detection/strategies/tech-docs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tech Docs Detection Strategy
+ *
+ * Detects: documentation frameworks (mkdocs, docusaurus, sphinx), docs folder.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectTechDocs(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/tech-docs.js

@@ -0,0 +1,51 @@
+/**
+ * Tech Docs Detection Strategy
+ *
+ * Detects: documentation frameworks (mkdocs, docusaurus, sphinx), docs folder.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { hasDirectory } from '../common.js';
+export function detectTechDocs(path, base) {
+    const result = { ...base };
+    // MkDocs
+    if (existsSync(join(path, 'mkdocs.yml')) || existsSync(join(path, 'mkdocs.yaml'))) {
+        result.docsFramework = 'mkdocs';
+        result.docsConfigFile = existsSync(join(path, 'mkdocs.yml')) ? 'mkdocs.yml' : 'mkdocs.yaml';
+        return result;
+    }
+    // Docusaurus
+    if (existsSync(join(path, 'docusaurus.config.js')) ||
+        existsSync(join(path, 'docusaurus.config.ts'))) {
+        result.docsFramework = 'docusaurus';
+        result.docsConfigFile = existsSync(join(path, 'docusaurus.config.js'))
+            ? 'docusaurus.config.js'
+            : 'docusaurus.config.ts';
+        return result;
+    }
+    // Sphinx
+    if (existsSync(join(path, 'conf.py')) || existsSync(join(path, 'source', 'conf.py'))) {
+        result.docsFramework = 'sphinx';
+        result.docsConfigFile = existsSync(join(path, 'conf.py')) ? 'conf.py' : 'source/conf.py';
+        return result;
+    }
+    // VitePress
+    if (existsSync(join(path, '.vitepress', 'config.ts')) ||
+        existsSync(join(path, '.vitepress', 'config.js'))) {
+        result.docsFramework = 'vitepress';
+        result.docsConfigFile = '.vitepress/config.ts';
+        return result;
+    }
+    // GitBook
+    if (existsSync(join(path, 'SUMMARY.md'))) {
+        result.docsFramework = 'gitbook';
+        result.docsConfigFile = 'SUMMARY.md';
+        return result;
+    }
+    // Generic docs/ folder
+    if (hasDirectory(path, 'docs')) {
+        result.docsFramework = 'custom';
+        return result;
+    }
+    return result;
+}

package/dist/detection/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Project Detection Types
+ *
+ * Universal detection result that works across all project types.
+ * Type-specific fields are optional — only populated when relevant.
+ */
+export interface DetectProjectOptions {
+    /** Absolute path to the project folder */
+    path: string;
+    /** Project type — determines detection strategy */
+    type: string;
+}
+export interface DetectionResult {
+    /** Inferred project name (slug: lowercase, hyphens) */
+    name: string;
+    /** Display name (prettified from folder name or config) */
+    displayName: string;
+    /** Description (from README first paragraph, package.json, etc.) */
+    description?: string;
+    /** Git remote URL (if .git exists with a remote) */
+    gitRemote?: string;
+    /** Whether .git directory exists */
+    hasGit: boolean;
+    /** Whether COMPILR.md exists in the project root */
+    hasCompilrMd: boolean;
+    /** Type-specific detection results */
+    content: ContentSummary;
+}
+export interface ContentSummary {
+    /** Total files found (excluding ignored dirs) */
+    fileCount: number;
+    /** Total size in KB */
+    totalSizeKB: number;
+    /** Markdown files count */
+    markdownFiles: number;
+    /** Image files count */
+    imageFiles: number;
+    /** Detected language (typescript, python, go, rust, java, etc.) */
+    language?: string;
+    /** Detected framework (react, next, express, fastapi, gin, etc.) */
+    framework?: string;
+    /** Package manager (npm, yarn, pnpm, pip, poetry, go mod, cargo) */
+    packageManager?: string;
+    /** Main entry points found */
+    entryPoints?: string[];
+    /** Test framework detected */
+    testFramework?: string;
+    /** Path to .bib file */
+    bibliographyFile?: string;
+    /** Number of bib entries */
+    bibliographyEntries?: number;
+    /** LaTeX files found */
+    latexFiles?: string[];
+    /** Data files (.csv, .xlsx, .json in data/ or root) */
+    dataFiles?: number;
+    /** Number of chapter files detected */
+    chapterCount?: number;
+    /** Path to outline file */
+    outlineFile?: string;
+    /** Manuscript/draft files */
+    draftFiles?: string[];
+    /** Spreadsheet files (.xlsx, .csv) */
+    spreadsheetFiles?: number;
+    /** Presentation files (.pptx, .pdf) */
+    presentationFiles?: number;
+    /** Documentation framework (mkdocs, docusaurus, sphinx, etc.) */
+    docsFramework?: string;
+    /** Config file path */
+    docsConfigFile?: string;
+    /** Lesson/module directories */
+    lessonCount?: number;
+    /** Exercise files */
+    exerciseFiles?: number;
+}
+/**
+ * Detection strategy function signature.
+ * Each strategy receives the project path and a base summary,
+ * then adds type-specific fields.
+ */
+export type DetectionStrategy = (path: string, base: ContentSummary) => ContentSummary;

package/dist/detection/types.js

@@ -0,0 +1,7 @@
+/**
+ * Project Detection Types
+ *
+ * Universal detection result that works across all project types.
+ * Type-specific fields are optional — only populated when relevant.
+ */
+export {};

package/dist/index.d.ts

@@ -58,6 +58,8 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 export type { SQLiteRepositories, CreateSQLiteRepositoriesOptions, ProjectDeleteHooks, ProjectRecord, WorkItemRecord, ProjectDocumentRecord, WorkItemCommentRecord, } from './platform/index.js';
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 export type { AskUserQuestion, AskUserInput, AskUserResult, AskUserHandler, AskUserSimpleInput, AskUserSimpleResult, AskUserSimpleHandler, } from './tools/index.js';
+export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';
+export type { DetectProjectOptions, DetectionResult, ContentSummary } from './detection/index.js';
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';
 export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './guide/index.js';
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';

package/dist/index.js

@@ -129,6 +129,10 @@ export { createSQLiteRepositories, SQLiteProjectRepository, SQLiteWorkItemReposi
 // =============================================================================
 export { createAskUserTool, createAskUserSimpleTool } from './tools/index.js';
 // =============================================================================
+// Project Detection (universal project content detection)
+// =============================================================================
+export { detectProject, suggestProjectType, detectCommon } from './detection/index.js';
+// =============================================================================
 // Guide Tool (environment-aware documentation)
 // =============================================================================
 export { createGuideTool, SHARED_GUIDE_ENTRIES, searchGuideEntries, topicToGuideEntry, } from './guide/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",