skrypt-ai 0.4.2 → 0.6.0

package/dist/context-hub/index.js

@@ -0,0 +1,179 @@
+import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { IMPORT_MAPPINGS } from './mappings.js';
+/**
+ * Check if the `chub` CLI is installed
+ */
+export function isChubInstalled() {
+    try {
+        const result = spawnSync('chub', ['--version'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract Context Hub IDs from import lines by matching against known mappings
+ */
+export function extractDependencyIds(imports) {
+    const hits = new Map();
+    for (const line of imports) {
+        for (const mapping of IMPORT_MAPPINGS) {
+            if (mapping.pattern.test(line)) {
+                hits.set(mapping.chubId, (hits.get(mapping.chubId) || 0) + 1);
+            }
+        }
+    }
+    // Sort by frequency (most imported first), cap at 10
+    return [...hits.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([id]) => id);
+}
+/**
+ * Fetch docs from Context Hub for the given IDs
+ */
+export function fetchContextHubDocs(chubIds, language) {
+    const results = new Map();
+    for (const id of chubIds) {
+        try {
+            const args = ['get', id];
+            if (language) {
+                args.push('--lang', language);
+            }
+            const result = spawnSync('chub', args, {
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 15000,
+            });
+            if (result.status === 0 && result.stdout?.trim()) {
+                results.set(id, result.stdout.trim());
+            }
+        }
+        catch {
+            // Skip failures silently
+        }
+    }
+    return results;
+}
+/**
+ * Given an element's imports, return relevant fetched docs as a single string
+ */
+export function matchImportsToContext(imports, contextMap) {
+    if (!imports.length || !contextMap.size)
+        return undefined;
+    const ids = extractDependencyIds(imports);
+    const matched = [];
+    for (const id of ids) {
+        const content = contextMap.get(id);
+        if (content) {
+            matched.push(`## ${id}\n${content}`);
+        }
+    }
+    if (!matched.length)
+        return undefined;
+    return matched.join('\n\n');
+}
+/**
+ * Export generated docs to Context Hub format
+ */
+export function exportToContextHub(docs, outputDir, options) {
+    const { projectName, languages, version, description } = options;
+    const isMultiLang = languages.length > 1;
+    // Create directory structure
+    const baseDir = join(outputDir, 'context-hub', projectName, 'docs', 'api');
+    let filesWritten = 0;
+    // Group docs by element kind for organized output
+    const byKind = new Map();
+    for (const doc of docs) {
+        if (doc.error)
+            continue;
+        const kind = doc.element.kind;
+        if (!byKind.has(kind))
+            byKind.set(kind, []);
+        byKind.get(kind).push(doc);
+    }
+    const buildContent = (lang) => {
+        const today = new Date().toISOString().split('T')[0];
+        let content = '---\n';
+        content += `name: "api"\n`;
+        content += `description: "${description || `API documentation for ${projectName}`}"\n`;
+        content += `metadata:\n`;
+        content += `  languages: "${lang || languages.join(', ')}"\n`;
+        content += `  versions: "${version || '1.0.0'}"\n`;
+        content += `  revision: 1\n`;
+        content += `  updated-on: "${today}"\n`;
+        content += `  source: community\n`;
+        content += `  tags: "${projectName},api,documentation"\n`;
+        content += '---\n\n';
+        content += `# ${projectName} API Documentation\n\n`;
+        for (const [kind, kindDocs] of byKind) {
+            const heading = kind.charAt(0).toUpperCase() + kind.slice(1) + 's';
+            content += `## ${heading}\n\n`;
+            for (const doc of kindDocs) {
+                content += `### ${doc.element.name}\n\n`;
+                if (doc.markdown) {
+                    content += doc.markdown + '\n\n';
+                }
+                // Pick the right code example for this language
+                if (lang === 'python' && doc.pythonExample) {
+                    content += `\`\`\`python\n${doc.pythonExample}\n\`\`\`\n\n`;
+                }
+                else if (lang === 'javascript' || lang === 'typescript') {
+                    const code = doc.typescriptExample || doc.codeExample;
+                    if (code) {
+                        content += `\`\`\`typescript\n${code}\n\`\`\`\n\n`;
+                    }
+                }
+                else if (doc.codeExample) {
+                    content += `\`\`\`${doc.codeLanguage}\n${doc.codeExample}\n\`\`\`\n\n`;
+                }
+            }
+        }
+        return content;
+    };
+    if (isMultiLang) {
+        // Write per-language files
+        for (const lang of languages) {
+            const langDir = join(baseDir, lang);
+            mkdirSync(langDir, { recursive: true });
+            writeFileSync(join(langDir, 'DOC.md'), buildContent(lang));
+            filesWritten++;
+        }
+    }
+    else {
+        // Single-language file
+        mkdirSync(baseDir, { recursive: true });
+        writeFileSync(join(baseDir, 'DOC.md'), buildContent(languages[0]));
+        filesWritten++;
+    }
+    // Write submission instructions README
+    const readmeDir = join(outputDir, 'context-hub');
+    const readme = `# Context Hub Submission
+
+Your documentation has been exported in Context Hub format.
+
+## How to submit
+
+1. Fork https://github.com/andrewyng/context-hub
+2. Copy the \`${projectName}/\` directory into the \`contexts/\` folder of your fork
+3. Open a pull request with a brief description of your project
+
+## What is Context Hub?
+
+Context Hub is a curated registry of machine-readable API docs for AI coding agents.
+Once submitted, any developer using \`chub\` will be able to pull your docs directly
+into their AI coding workflow.
+
+Learn more: https://github.com/andrewyng/context-hub
+`;
+    writeFileSync(join(readmeDir, 'README.md'), readme);
+    filesWritten++;
+    return { outputDir: readmeDir, filesWritten, languages };
+}

package/dist/context-hub/mappings.d.ts

@@ -0,0 +1,8 @@
+import { ImportMapping } from './types.js';
+/**
+ * Static registry mapping import patterns to Context Hub IDs.
+ *
+ * Covers ES6 imports, CommonJS require(), and Python imports.
+ * Sorted roughly by ecosystem popularity.
+ */
+export declare const IMPORT_MAPPINGS: ImportMapping[];

package/dist/context-hub/mappings.js

@@ -0,0 +1,55 @@
+/**
+ * Static registry mapping import patterns to Context Hub IDs.
+ *
+ * Covers ES6 imports, CommonJS require(), and Python imports.
+ * Sorted roughly by ecosystem popularity.
+ */
+export const IMPORT_MAPPINGS = [
+    // --- JavaScript / TypeScript ---
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]stripe['"]/, chubId: 'stripe/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]openai['"]/, chubId: 'openai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@anthropic-ai\/sdk['"]/, chubId: 'anthropic/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@google-cloud\//, chubId: 'google-cloud/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]firebase['"]/, chubId: 'firebase/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@supabase\/supabase-js['"]/, chubId: 'supabase/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@prisma\/client['"]/, chubId: 'prisma/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]drizzle-orm['"]/, chubId: 'drizzle/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]next['"]/, chubId: 'nextjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]next\//, chubId: 'nextjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]express['"]/, chubId: 'express/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]hono['"]/, chubId: 'hono/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@aws-sdk\//, chubId: 'aws/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]axios['"]/, chubId: 'axios/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]zod['"]/, chubId: 'zod/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@trpc\//, chubId: 'trpc/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@tanstack\/react-query['"]/, chubId: 'tanstack-query/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@clerk\//, chubId: 'clerk/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@auth\//, chubId: 'authjs/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]mongoose['"]/, chubId: 'mongoose/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]typeorm['"]/, chubId: 'typeorm/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@langchain\//, chubId: 'langchain/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]llamaindex['"]/, chubId: 'llamaindex/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@pinecone-database\/pinecone['"]/, chubId: 'pinecone/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@vercel\/ai['"]/, chubId: 'vercel-ai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]ai['"]/, chubId: 'vercel-ai/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@sentry\//, chubId: 'sentry/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@reduxjs\/toolkit['"]/, chubId: 'redux-toolkit/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]graphql['"]/, chubId: 'graphql/api' },
+    { pattern: /(?:from\s+|require\s*\(\s*)['"]@apollo\//, chubId: 'apollo/api' },
+    // --- Python ---
+    { pattern: /^(?:from|import)\s+fastapi/, chubId: 'fastapi/api' },
+    { pattern: /^(?:from|import)\s+django/, chubId: 'django/api' },
+    { pattern: /^(?:from|import)\s+flask/, chubId: 'flask/api' },
+    { pattern: /^(?:from|import)\s+sqlalchemy/, chubId: 'sqlalchemy/api' },
+    { pattern: /^(?:from|import)\s+pydantic/, chubId: 'pydantic/api' },
+    { pattern: /^(?:from|import)\s+pandas/, chubId: 'pandas/api' },
+    { pattern: /^(?:from|import)\s+numpy/, chubId: 'numpy/api' },
+    { pattern: /^(?:from|import)\s+torch/, chubId: 'pytorch/api' },
+    { pattern: /^(?:from|import)\s+tensorflow/, chubId: 'tensorflow/api' },
+    { pattern: /^(?:from|import)\s+langchain/, chubId: 'langchain/api' },
+    { pattern: /^(?:from|import)\s+anthropic/, chubId: 'anthropic/api' },
+    { pattern: /^(?:from|import)\s+openai/, chubId: 'openai/api' },
+    { pattern: /^(?:from|import)\s+stripe/, chubId: 'stripe/api' },
+    { pattern: /^(?:from|import)\s+boto3/, chubId: 'aws/api' },
+    { pattern: /^(?:from|import)\s+celery/, chubId: 'celery/api' },
+];

package/dist/context-hub/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Options for exporting docs to Context Hub format
+ */
+export interface ContextHubExportOptions {
+    projectName: string;
+    languages: string[];
+    version?: string;
+    description?: string;
+}
+/**
+ * Result of a Context Hub export
+ */
+export interface ContextHubExportResult {
+    outputDir: string;
+    filesWritten: number;
+    languages: string[];
+}
+/**
+ * Fetched context from Context Hub for a dependency
+ */
+export interface ContextHubContext {
+    id: string;
+    content: string;
+}
+/**
+ * Maps an import pattern to a Context Hub ID
+ */
+export interface ImportMapping {
+    /** Regex pattern to match against import lines */
+    pattern: RegExp;
+    /** Context Hub ID (e.g., "stripe/api") */
+    chubId: string;
+}

package/dist/context-hub/types.js

@@ -0,0 +1 @@
+export {};

package/dist/generator/generator.js

@@ -1,9 +1,10 @@
 import { generateDocumentation } from '../llm/index.js';
+import { matchImportsToContext } from '../context-hub/index.js';
 /**
  * Build enhanced context for LLM from API element
  */
-function buildElementContext(element) {
-    return {
+function buildElementContext(element, externalContext, projectContext) {
+    const ctx = {
         kind: element.kind,
         name: element.name,
         signature: element.signature,
@@ -14,8 +15,13 @@ function buildElementContext(element) {
         imports: element.imports,
         packageName: element.packageName,
         sourceContext: element.sourceContext,
-        filePath: element.filePath
+        filePath: element.filePath,
+        projectContext
     };
+    if (externalContext && element.imports?.length) {
+        ctx.externalDocs = matchImportsToContext(element.imports, externalContext);
+    }
+    return ctx;
 }
 /**
  * Detect code language from file path
@@ -31,6 +37,18 @@ function detectLanguageFromFile(filePath) {
         return 'go';
     if (filePath.endsWith('.rs'))
         return 'rust';
+    if (filePath.endsWith('.java'))
+        return 'java';
+    if (filePath.endsWith('.cs'))
+        return 'csharp';
+    if (filePath.endsWith('.php'))
+        return 'php';
+    if (filePath.endsWith('.kt') || filePath.endsWith('.kts'))
+        return 'kotlin';
+    if (filePath.endsWith('.swift'))
+        return 'swift';
+    if (filePath.endsWith('.rb'))
+        return 'ruby';
     return 'typescript';
 }
 /**
@@ -49,7 +67,7 @@ export async function generateForElement(element, client, options, onProgress) {
     const useMultiLang = options.multiLanguage ?? false;
     report('generating');
     try {
-        const elementContext = buildElementContext(element);
+        const elementContext = buildElementContext(element, options.externalContext, options.projectContext);
         const result = await generateDocumentation(client, elementContext, { multiLanguage: useMultiLang });
         report('done');
         return {
@@ -58,7 +76,8 @@ export async function generateForElement(element, client, options, onProgress) {
             codeExample: result.codeExample,
             codeLanguage,
             typescriptExample: result.typescriptExample,
-            pythonExample: result.pythonExample
+            pythonExample: result.pythonExample,
+            usage: result.usage
         };
     }
     catch (err) {
@@ -77,6 +96,8 @@ export async function generateForElement(element, client, options, onProgress) {
  */
 export async function generateForElements(elements, client, options) {
     const results = [];
+    let totalTokens = 0;
+    const MAX_TOKENS = options.maxTokens ?? 1_000_000; // default 1M tokens (~$10-20)
     for (let i = 0; i < elements.length; i++) {
         const element = elements[i];
         if (!element)
@@ -89,6 +110,14 @@ export async function generateForElements(elements, client, options) {
             });
         });
         results.push(doc);
+        if (doc.usage) {
+            totalTokens += (doc.usage.inputTokens ?? 0) + (doc.usage.outputTokens ?? 0);
+        }
+        if (totalTokens > MAX_TOKENS) {
+            console.warn(`\nToken budget exceeded (${totalTokens.toLocaleString()} tokens used). Stopping generation.`);
+            console.warn('Use --max-tokens to increase the limit.');
+            break;
+        }
     }
     return results;
 }
@@ -137,7 +166,11 @@ function formatDocSection(doc, headingLevel = '###') {
     }
     else if (doc.codeExample) {
         section += '**Example:**\n\n';
-        const ext = doc.codeLanguage === 'typescript' ? 'ts' : doc.codeLanguage === 'python' ? 'py' : 'js';
+        const extMap = {
+            typescript: 'ts', javascript: 'js', python: 'py', go: 'go', rust: 'rs',
+            java: 'java', csharp: 'cs', php: 'php', kotlin: 'kt', swift: 'swift', ruby: 'rb'
+        };
+        const ext = extMap[doc.codeLanguage] ?? 'js';
         section += `\`\`\`${doc.codeLanguage} example.${ext}\n${doc.codeExample}\n\`\`\`\n\n`;
     }
     return section;

package/dist/generator/types.d.ts

@@ -10,6 +10,10 @@ export interface GeneratedDoc {
     error?: string;
     typescriptExample?: string;
     pythonExample?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
 }
 /**
  * Progress callback for generation
@@ -26,6 +30,9 @@ export interface GenerationProgress {
 export interface GenerationOptions {
     onProgress?: (progress: GenerationProgress) => void;
     multiLanguage?: boolean;
+    externalContext?: Map<string, string>;
+    maxTokens?: number;
+    projectContext?: string;
 }
 /**
  * Result of generating docs for a file

package/dist/generator/writer.d.ts

@@ -10,7 +10,9 @@ export declare function writeLlmsTxt(docs: GeneratedDoc[], outputDir: string, op
 /**
  * Write generated docs to output directory
  */
-export declare function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string): Promise<{
+export declare function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string, options?: {
+    force?: boolean;
+}): Promise<{
     filesWritten: number;
     totalDocs: number;
 }>;

package/dist/generator/writer.js

@@ -1,5 +1,6 @@
-import { mkdir, writeFile } from 'fs/promises';
-import { dirname, join, basename, relative } from 'path';
+import { mkdir, writeFile, readdir } from 'fs/promises';
+import { dirname, join, basename, relative, resolve, sep } from 'path';
+import { existsSync } from 'fs';
 import { formatAsMarkdown } from './generator.js';
 import { organizeByTopic, detectCrossReferences, getCrossRefsForElement } from './organizer.js';
 import { slugify } from '../utils/files.js';
@@ -71,9 +72,22 @@ export async function writeLlmsTxt(docs, outputDir, options = {}) {
 /**
  * Write generated docs to output directory
  */
-export async function writeDocsToDirectory(results, outputDir, sourceDir) {
+export async function writeDocsToDirectory(results, outputDir, sourceDir, options) {
     let filesWritten = 0;
     let totalDocs = 0;
+    // Check for existing doc files before overwriting
+    if (existsSync(outputDir)) {
+        try {
+            const entries = await readdir(outputDir);
+            const existing = entries.filter(f => f.endsWith('.md') || f.endsWith('.mdx'));
+            if (existing.length > 0 && !options?.force) {
+                console.warn(`Warning: Output directory already contains ${existing.length} doc files. Use --force to overwrite.`);
+            }
+        }
+        catch {
+            // Directory read failed, proceed anyway
+        }
+    }
     // Create output directory
     await mkdir(outputDir, { recursive: true });
     for (const result of results) {
@@ -88,6 +102,12 @@ export async function writeDocsToDirectory(results, outputDir, sourceDir) {
         }
         const docFileName = relPath.replace(/\.[^.]+$/, '.md');
         const outputPath = join(outputDir, docFileName);
+        // Double-check resolved path stays within output directory
+        const resolvedOutput = resolve(outputPath);
+        if (!resolvedOutput.startsWith(resolve(outputDir) + sep) && resolvedOutput !== resolve(outputDir)) {
+            console.warn(`Skipping file outside output directory: ${result.filePath}`);
+            continue;
+        }
         // Create subdirectories if needed
         await mkdir(dirname(outputPath), { recursive: true });
         // Generate markdown content
@@ -174,9 +194,12 @@ export async function writeDocsByTopic(docs, outputDir) {
  */
 function formatTopicMarkdown(topic, allCrossRefs) {
     // MDX frontmatter (standard across doc platforms)
+    const safeTitle = topic.name.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
+    const rawDesc = topic.description || `API reference for ${topic.name}`;
+    const safeDesc = rawDesc.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
     let content = `---
-title: "${topic.name}"
-description: "${topic.description || `API reference for ${topic.name}`}"
+title: "${safeTitle}"
+description: "${safeDesc}"
 ---
 
 `;
@@ -185,8 +208,14 @@ description: "${topic.description || `API reference for ${topic.name}`}"
     for (const doc of topic.docs) {
         const anchor = slugify(doc.element.name);
         const icon = doc.element.kind === 'class' ? 'cube' : doc.element.kind === 'method' ? 'code' : 'function';
-        content += `  <Card title="${doc.element.name}" icon="${icon}" href="#${anchor}">\n`;
-        content += `    ${doc.element.kind}\n`;
+        // Use short description (first ~5 words) or fall back to kind
+        const rawDocstring = doc.element.docstring?.replace(/^@\w+\s+\S+\s*/, '')?.trim();
+        const desc = rawDocstring
+            ? rawDocstring.split(/\s+/).slice(0, 5).join(' ').replace(/[.,:;]$/, '')
+            : doc.element.kind;
+        const safeName = doc.element.name.replace(/"/g, '&quot;');
+        content += `  <Card title="${safeName}" icon="${icon}" href="#${anchor}">\n`;
+        content += `    ${desc}\n`;
         content += `  </Card>\n`;
     }
     content += '</CardGroup>\n\n';

package/dist/importers/confluence.d.ts

@@ -0,0 +1,5 @@
+import type { ImportResult } from './types.js';
+/**
+ * Import Confluence HTML space export.
+ */
+export declare function importConfluence(dir: string, name?: string): ImportResult;

package/dist/importers/confluence.js

@@ -0,0 +1,137 @@
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, relative, basename, extname } from 'path';
+import { transformConfluenceCallouts, transformConfluenceHtml, normalizeFrontmatter, } from './transform.js';
+/**
+ * Import Confluence HTML space export.
+ */
+export function importConfluence(dir, name) {
+    const result = createEmptyResult(name);
+    const stats = { callouts: 0, tabs: 0, codeGroups: 0, steps: 0, accordions: 0, images: 0, other: 0 };
+    // Find all HTML files
+    const htmlFiles = findHtmlFiles(dir);
+    if (htmlFiles.length === 0) {
+        result.warnings.push('No .html files found in Confluence export');
+        return result;
+    }
+    const pages = [];
+    for (const filePath of htmlFiles) {
+        // Skip index.html (usually a listing page)
+        if (basename(filePath) === 'index.html')
+            continue;
+        const page = processConfluencePage(dir, filePath, stats, result);
+        if (page)
+            pages.push(page);
+    }
+    if (pages.length > 0) {
+        result.navigation.push({ group: name || 'Documentation', pages });
+    }
+    // Copy attachments
+    const attachmentsDir = join(dir, 'attachments');
+    if (existsSync(attachmentsDir)) {
+        collectAttachments(attachmentsDir, result, stats);
+    }
+    result.stats = {
+        pages: result.files.size,
+        groups: result.navigation.length,
+        transforms: stats,
+    };
+    return result;
+}
+function findHtmlFiles(dir) {
+    const files = [];
+    try {
+        for (const entry of readdirSync(dir)) {
+            const fullPath = join(dir, entry);
+            try {
+                const stat = statSync(fullPath);
+                if (stat.isFile() && extname(entry) === '.html') {
+                    files.push(fullPath);
+                }
+                else if (stat.isDirectory() && !entry.startsWith('.') && entry !== 'attachments') {
+                    files.push(...findHtmlFiles(fullPath));
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch { /* skip */ }
+    return files;
+}
+function processConfluencePage(dir, filePath, stats, result) {
+    const rawContent = readFileSync(filePath, 'utf-8');
+    let content = rawContent;
+    // Extract body content
+    const bodyMatch = content.match(/<body[^>]*>([\s\S]*)<\/body>/i);
+    if (bodyMatch)
+        content = bodyMatch[1];
+    // Extract title from <title> tag or <h1> (use rawContent to search full HTML)
+    let title = '';
+    const titleMatch = rawContent.match(/<title>([^<]+)<\/title>/i);
+    if (titleMatch)
+        title = titleMatch[1].trim();
+    if (!title) {
+        const h1Match = content.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+        if (h1Match)
+            title = h1Match[1].replace(/<[^>]+>/g, '').trim();
+    }
+    if (!title)
+        title = basename(filePath, '.html').replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+    const originalContent = content;
+    // Apply transforms: callouts first, then general HTML conversion
+    content = transformConfluenceCallouts(content);
+    content = transformConfluenceHtml(content);
+    content = normalizeFrontmatter(content, { title });
+    stats.callouts += countNew(originalContent, content, '<Callout');
+    stats.accordions += countNew(originalContent, content, '<Accordion');
+    const rel = relative(dir, filePath);
+    const slug = basename(filePath, '.html').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    const outputPath = `content/docs/${slug}.mdx`;
+    result.files.set(outputPath, content);
+    return { title, slug, sourcePath: rel, content };
+}
+function collectAttachments(attachmentsDir, result, stats) {
+    const imgExts = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp']);
+    function walk(dir) {
+        try {
+            for (const entry of readdirSync(dir)) {
+                const fullPath = join(dir, entry);
+                try {
+                    const stat = statSync(fullPath);
+                    if (stat.isDirectory()) {
+                        walk(fullPath);
+                    }
+                    else if (imgExts.has(extname(entry).toLowerCase())) {
+                        const dest = `public/images/${entry}`;
+                        result.assets.set(dest, fullPath);
+                        stats.images++;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        catch { /* skip */ }
+    }
+    walk(attachmentsDir);
+}
+function countNew(original, transformed, marker) {
+    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const origCount = (original.match(new RegExp(escaped, 'g')) || []).length;
+    const newCount = (transformed.match(new RegExp(escaped, 'g')) || []).length;
+    return Math.max(0, newCount - origCount);
+}
+function createEmptyResult(name) {
+    return {
+        navigation: [],
+        name: name || 'Documentation',
+        description: 'Imported from Confluence',
+        files: new Map(),
+        assets: new Map(),
+        warnings: [],
+        stats: { pages: 0, groups: 0, transforms: { callouts: 0, tabs: 0, codeGroups: 0, steps: 0, accordions: 0, images: 0, other: 0 } },
+        sourceFormat: 'confluence',
+    };
+}

package/dist/importers/detect.d.ts

@@ -0,0 +1,20 @@
+import type { ImportFormat } from './types.js';
+/**
+ * Auto-detect documentation format from a directory by checking marker files.
+ * First match wins (priority order).
+ */
+export declare function detectFormat(dir: string): ImportFormat;
+/**
+ * Check if a string is a GitHub URL
+ */
+export declare function isGitHubUrl(input: string): boolean;
+/**
+ * Parse a GitHub URL into components
+ * Supports: https://github.com/owner/repo/tree/branch/path
+ */
+export declare function parseGitHubUrl(url: string): {
+    owner: string;
+    repo: string;
+    path: string;
+    ref: string;
+};