@compilr-dev/sdk 0.9.7 → 0.9.9

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/guide/guide-tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Guide Tool Factory — creates an environment-aware compilr_guide tool.
+ *
+ * The tool definition lives in the SDK. Each host app (CLI, Desktop)
+ * registers environment-specific content via additionalEntries.
+ */
+import type { GuideToolConfig } from './types.js';
+interface GuideInput {
+    query?: string;
+    list_topics?: boolean;
+}
+/**
+ * Create the compilr_guide tool for the given environment.
+ *
+ * @example
+ * ```typescript
+ * // In CLI
+ * const guideTool = createGuideTool({
+ *   environment: 'cli',
+ *   additionalEntries: CLI_GUIDE_ENTRIES,
+ * });
+ *
+ * // In Desktop
+ * const guideTool = createGuideTool({
+ *   environment: 'desktop',
+ *   additionalEntries: DESKTOP_GUIDE_ENTRIES,
+ * });
+ * ```
+ */
+export declare function createGuideTool(config: GuideToolConfig): import("@compilr-dev/agents").Tool<GuideInput>;
+export {};

package/dist/guide/guide-tool.js

@@ -0,0 +1,90 @@
+/**
+ * Guide Tool Factory — creates an environment-aware compilr_guide tool.
+ *
+ * The tool definition lives in the SDK. Each host app (CLI, Desktop)
+ * registers environment-specific content via additionalEntries.
+ */
+import { defineTool } from '@compilr-dev/agents';
+import { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+import { searchGuideEntries } from './search.js';
+/**
+ * Create the compilr_guide tool for the given environment.
+ *
+ * @example
+ * ```typescript
+ * // In CLI
+ * const guideTool = createGuideTool({
+ *   environment: 'cli',
+ *   additionalEntries: CLI_GUIDE_ENTRIES,
+ * });
+ *
+ * // In Desktop
+ * const guideTool = createGuideTool({
+ *   environment: 'desktop',
+ *   additionalEntries: DESKTOP_GUIDE_ENTRIES,
+ * });
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createGuideTool(config) {
+    // Merge shared + environment-specific content
+    const allEntries = [...SHARED_GUIDE_ENTRIES, ...(config.additionalEntries ?? [])];
+    const envLabel = config.environment === 'desktop' ? 'Desktop' : 'CLI';
+    return defineTool({
+        name: 'compilr_guide',
+        description: `Get documentation about Compilr Dev ${envLabel} features and capabilities. ` +
+            `Use this to answer user questions about how to use the ${envLabel.toLowerCase()}. ` +
+            'Query by topic (e.g., "creating-project", "team-agents", "image-support") or ' +
+            'set list_topics=true to see all available topics.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Topic or keyword to look up. Examples: "creating-project", "team-agents", "permissions", "image-support"',
+                },
+                list_topics: {
+                    type: 'boolean',
+                    description: 'Set to true to list all available guide topics',
+                },
+            },
+        },
+        execute: (input) => {
+            if (input.list_topics) {
+                const topics = allEntries.map((e) => `- ${e.id} — ${e.title}`).join('\n');
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: `Available guide topics (${envLabel}):\n\n${topics}`,
+                    },
+                });
+            }
+            if (!input.query) {
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: 'Provide a query (topic or keyword) or set list_topics=true to see all topics.',
+                    },
+                });
+            }
+            const results = searchGuideEntries(allEntries, input.query);
+            if (results.length === 0) {
+                const topics = allEntries.map((e) => e.id).join(', ');
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        output: `No guide found for "${input.query}".\n\nAvailable topics: ${topics}`,
+                    },
+                });
+            }
+            const formatted = results
+                .map((entry) => `## ${entry.title}\n\n${entry.content}`)
+                .join('\n\n---\n\n');
+            return Promise.resolve({
+                success: true,
+                result: { output: formatted },
+            });
+        },
+        silent: true,
+    });
+}

package/dist/guide/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Guide module — environment-aware documentation tool.
+ */
+export { createGuideTool } from './guide-tool.js';
+export { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+export { searchGuideEntries, topicToGuideEntry } from './search.js';
+export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from './types.js';

package/dist/guide/index.js

@@ -0,0 +1,6 @@
+/**
+ * Guide module — environment-aware documentation tool.
+ */
+export { createGuideTool } from './guide-tool.js';
+export { SHARED_GUIDE_ENTRIES } from './shared-content.js';
+export { searchGuideEntries, topicToGuideEntry } from './search.js';

package/dist/guide/search.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Guide search — finds relevant entries by query.
+ */
+import type { GuideEntry } from './types.js';
+/**
+ * Search guide entries by keyword, topic ID, or free text.
+ * Returns up to maxResults matches, ranked by relevance.
+ */
+export declare function searchGuideEntries(entries: GuideEntry[], query: string, maxResults?: number): GuideEntry[];
+/**
+ * Convert a ContentTopic to a GuideEntry (plain text).
+ */
+export declare function topicToGuideEntry(topic: {
+    id: string;
+    title: string;
+    keywords: string[];
+    sections: Array<{
+        title?: string;
+        items: string[];
+    }>;
+}): GuideEntry;

package/dist/guide/search.js

@@ -0,0 +1,62 @@
+/**
+ * Guide search — finds relevant entries by query.
+ */
+/**
+ * Search guide entries by keyword, topic ID, or free text.
+ * Returns up to maxResults matches, ranked by relevance.
+ */
+export function searchGuideEntries(entries, query, maxResults = 3) {
+    const q = query.toLowerCase().trim();
+    if (!q)
+        return [];
+    // 1. Exact ID match
+    const exactMatch = entries.find((e) => e.id === q);
+    if (exactMatch)
+        return [exactMatch];
+    // 2. Command match (e.g., "/design" → "skill-design", or "design")
+    const cmdQuery = q.startsWith('/') ? q : `/${q}`;
+    const cmdMatch = entries.find((e) => e.keywords.includes(cmdQuery) || e.keywords.includes(q));
+    if (cmdMatch)
+        return [cmdMatch];
+    // 3. Keyword + title + content search with scoring
+    const scored = entries
+        .map((e) => {
+        let score = 0;
+        // Keyword match (strongest signal)
+        if (e.keywords.some((k) => k === q))
+            score += 10;
+        if (e.keywords.some((k) => k.includes(q)))
+            score += 5;
+        if (e.keywords.some((k) => q.includes(k) && k.length > 2))
+            score += 3;
+        // Title match
+        if (e.title.toLowerCase().includes(q))
+            score += 4;
+        // Content match (weakest signal)
+        if (e.content.toLowerCase().includes(q))
+            score += 1;
+        return { entry: e, score };
+    })
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, maxResults).map((s) => s.entry);
+}
+/**
+ * Convert a ContentTopic to a GuideEntry (plain text).
+ */
+export function topicToGuideEntry(topic) {
+    const parts = [];
+    for (const section of topic.sections) {
+        if (section.title)
+            parts.push(section.title);
+        for (const item of section.items) {
+            parts.push(`  ${item}`);
+        }
+    }
+    return {
+        id: topic.id,
+        title: topic.title,
+        keywords: topic.keywords,
+        content: parts.join('\n'),
+    };
+}

package/dist/guide/shared-content.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared Guide Content — environment-agnostic topics.
+ *
+ * These apply to both CLI and Desktop. Each entry describes a feature
+ * that works the same way regardless of the host application.
+ */
+import type { GuideEntry } from './types.js';
+export declare const SHARED_GUIDE_ENTRIES: GuideEntry[];