@specglass/cli 0.0.5 → 0.0.7

package/dist/cli.js

@@ -5,6 +5,8 @@ import { render } from "ink";
 import { SpecglassError } from "@specglass/core";
 import { DevCommand } from "./commands/dev.js";
 import { BuildCommand } from "./commands/build.js";
+import { CheckCommand } from "./commands/check.js";
+import { MigrateCommand, SUPPORTED_PLATFORMS } from "./commands/migrate.js";
 import { setupErrorHandlers, setupSigintHandler, renderErrorAndExit, EXIT_CODES } from "./utils/error-handler.js";
 setupErrorHandlers();
 setupSigintHandler();
@@ -13,14 +15,22 @@ const cli = meow(`
     $ specglass <command>
 
   Commands
-    dev     Start the development server
-    build   Build static site for production
+    dev       Start the development server
+    build     Build static site for production
+    check     Run validation checks (links, frontmatter, spec drift)
+    migrate   Migrate docs from another platform (Mintlify, Docusaurus, ReadMe, GitBook)
 
   Options
-    --port, -p     Port for the dev server (default: 4321)
-    --config, -c   Path to specglass.config.ts
-    --help         Show this help message
-    --version      Show version number
+    --port, -p              Port for the dev server (default: 4321)
+    --config, -c            Path to specglass.config.ts
+    --links-only            Only run link validation
+    --frontmatter-only      Only run frontmatter validation
+    --spec-drift-only       Only run spec drift validation
+    --from                  Source platform to migrate from (mintlify, docusaurus, readme, gitbook)
+    --dry-run               Preview migration plan without calling AI API
+    --yes, -y               Skip consent prompt (for CI automation)
+    --help                  Show this help message
+    --version               Show version number
 
   Examples
     $ specglass dev
@@ -28,6 +38,10 @@ const cli = meow(`
     $ specglass dev --config ./custom.config.ts
     $ specglass build
     $ specglass build --config ./custom.config.ts
+    $ specglass check
+    $ specglass check --links-only
+    $ specglass migrate --from mintlify
+    $ specglass migrate --from mintlify --dry-run
 `, {
     importMeta: import.meta,
     flags: {
@@ -40,6 +54,30 @@ const cli = meow(`
             type: "string",
             shortFlag: "c",
         },
+        linksOnly: {
+            type: "boolean",
+            default: false,
+        },
+        frontmatterOnly: {
+            type: "boolean",
+            default: false,
+        },
+        specDriftOnly: {
+            type: "boolean",
+            default: false,
+        },
+        from: {
+            type: "string",
+        },
+        dryRun: {
+            type: "boolean",
+            default: false,
+        },
+        yes: {
+            type: "boolean",
+            shortFlag: "y",
+            default: false,
+        },
     },
 });
 const [command] = cli.input;
@@ -52,6 +90,21 @@ else if (command === "dev") {
 else if (command === "build") {
     render(_jsx(BuildCommand, { configPath: cli.flags.config }));
 }
+else if (command === "check") {
+    render(_jsx(CheckCommand, { configPath: cli.flags.config, linksOnly: cli.flags.linksOnly, frontmatterOnly: cli.flags.frontmatterOnly, specDriftOnly: cli.flags.specDriftOnly }));
+}
+else if (command === "migrate") {
+    const from = cli.flags.from;
+    if (!from) {
+        renderErrorAndExit(new SpecglassError("Missing required --from flag", "MISSING_FLAG", undefined, undefined, `Specify the source platform: --from <platform>\nSupported platforms: ${SUPPORTED_PLATFORMS.join(", ")}`), EXIT_CODES.ERROR);
+    }
+    else if (!SUPPORTED_PLATFORMS.includes(from)) {
+        renderErrorAndExit(new SpecglassError(`Unsupported platform: ${from}`, "UNSUPPORTED_PLATFORM", undefined, undefined, `Supported platforms: ${SUPPORTED_PLATFORMS.join(", ")}`), EXIT_CODES.ERROR);
+    }
+    else {
+        render(_jsx(MigrateCommand, { from: from, dryRun: cli.flags.dryRun, yes: cli.flags.yes, configPath: cli.flags.config }));
+    }
+}
 else {
-    renderErrorAndExit(new SpecglassError(`Unknown command: ${command}`, "UNKNOWN_COMMAND", undefined, undefined, "Available commands: dev, build. Run 'specglass --help' for usage."), EXIT_CODES.ERROR);
+    renderErrorAndExit(new SpecglassError(`Unknown command: ${command}`, "UNKNOWN_COMMAND", undefined, undefined, "Available commands: dev, build, check, migrate. Run 'specglass --help' for usage."), EXIT_CODES.ERROR);
 }

package/dist/commands/check.d.ts

@@ -0,0 +1,7 @@
+export interface CheckCommandProps {
+    configPath?: string;
+    linksOnly?: boolean;
+    frontmatterOnly?: boolean;
+    specDriftOnly?: boolean;
+}
+export declare function CheckCommand(props: CheckCommandProps): import("react/jsx-runtime").JSX.Element;

package/dist/commands/check.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } from "react";
+import { Box } from "ink";
+import { Spinner } from "@inkjs/ui";
+import { loadConfig, SpecglassError, runValidators, validateLinks, validateFrontmatter, validateSpecDrift, } from "@specglass/core";
+import { buildValidatorContext } from "../utils/context-builder.js";
+import { CheckResultsDisplay } from "../ui/check-results-display.js";
+import { ErrorDisplay } from "../ui/error-display.js";
+import { isConfigError, EXIT_CODES } from "../utils/error-handler.js";
+/**
+ * Compose the validator array based on active filter flags.
+ * If no filter is active, all validators run.
+ */
+function composeValidators(props) {
+    const { linksOnly, frontmatterOnly, specDriftOnly } = props;
+    const hasFilter = linksOnly || frontmatterOnly || specDriftOnly;
+    if (!hasFilter) {
+        return [validateLinks, validateFrontmatter, validateSpecDrift];
+    }
+    const validators = [];
+    if (linksOnly)
+        validators.push(validateLinks);
+    if (frontmatterOnly)
+        validators.push(validateFrontmatter);
+    if (specDriftOnly)
+        validators.push(validateSpecDrift);
+    return validators;
+}
+export function CheckCommand(props) {
+    const { configPath, linksOnly, frontmatterOnly, specDriftOnly } = props;
+    const [status, setStatus] = useState("loading-config");
+    const [error, setError] = useState(null);
+    const [results, setResults] = useState([]);
+    useEffect(() => {
+        let aborted = false;
+        async function run() {
+            try {
+                // Phase 1: Load & validate config
+                const config = await loadConfig(configPath);
+                if (aborted)
+                    return;
+                // Phase 2: Build validator context
+                setStatus("checking");
+                const context = await buildValidatorContext(config, process.cwd());
+                if (aborted)
+                    return;
+                // Phase 3: Run validators
+                const validators = composeValidators(props);
+                const findings = await runValidators(validators, context);
+                if (aborted)
+                    return;
+                // Phase 4: Report results
+                setResults(findings);
+                setStatus("done");
+                // Exit based on severity: errors = exit 1, warnings only = exit 0
+                const hasErrors = findings.some((f) => f.severity === "error");
+                setTimeout(() => {
+                    process.exit(hasErrors ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS);
+                }, 100);
+            }
+            catch (err) {
+                if (aborted)
+                    return;
+                const specglassErr = err instanceof SpecglassError
+                    ? err
+                    : new SpecglassError(err instanceof Error ? err.message : String(err), "CHECK_UNEXPECTED_ERROR");
+                setError(specglassErr);
+                setStatus("error");
+                const exitCode = isConfigError(specglassErr)
+                    ? EXIT_CODES.CONFIG_ERROR
+                    : EXIT_CODES.ERROR;
+                setTimeout(() => process.exit(exitCode), 100);
+            }
+        }
+        run();
+        return () => {
+            aborted = true;
+        };
+    }, [configPath, linksOnly, frontmatterOnly, specDriftOnly]);
+    if (status === "error" && error) {
+        return (_jsx(Box, { flexDirection: "column", children: _jsx(ErrorDisplay, { error: error }) }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [status === "loading-config" && (_jsx(Box, { children: _jsx(Spinner, { label: "Loading specglass config..." }) })), status === "checking" && (_jsx(Box, { children: _jsx(Spinner, { label: "Running validation checks..." }) })), status === "done" && _jsx(CheckResultsDisplay, { results: results })] }));
+}

package/dist/commands/migrate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Migration command — `specglass migrate --from <platform>`
+ *
+ * Migrates documentation from another platform to specglass/ndocs format.
+ * Includes platform detection, consent flow, AI-powered content conversion,
+ * and file writing.
+ */
+import { SUPPORTED_PLATFORMS, type SupportedPlatform } from "../migration/detector.js";
+export { SUPPORTED_PLATFORMS };
+export interface MigrateCommandProps {
+    from: SupportedPlatform;
+    dryRun?: boolean;
+    yes?: boolean;
+    configPath?: string;
+}
+export declare function MigrateCommand(props: MigrateCommandProps): import("react/jsx-runtime").JSX.Element;

package/dist/commands/migrate.js

@@ -0,0 +1,172 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Migration command — `specglass migrate --from <platform>`
+ *
+ * Migrates documentation from another platform to specglass/ndocs format.
+ * Includes platform detection, consent flow, AI-powered content conversion,
+ * and file writing.
+ */
+import { useState, useEffect, useCallback, useRef } from "react";
+import { Box, Text } from "ink";
+import { Spinner } from "@inkjs/ui";
+import { SpecglassError } from "@specglass/core";
+import { detectPlatform, SUPPORTED_PLATFORMS, } from "../migration/detector.js";
+import { buildMigrationPlan } from "../migration/planner.js";
+import { getApiKey, convertAll, } from "../migration/converter.js";
+import { writeAll } from "../migration/writer.js";
+import { ConsentPrompt } from "../ui/consent-prompt.js";
+import { ErrorDisplay } from "../ui/error-display.js";
+import { EXIT_CODES } from "../utils/error-handler.js";
+import { resolve, join } from "path";
+export { SUPPORTED_PLATFORMS };
+export function MigrateCommand(props) {
+    const { from, dryRun = false, yes = false } = props;
+    const [status, setStatus] = useState("detecting");
+    const [error, setError] = useState(null);
+    const [plan, setPlan] = useState(null);
+    const [progressText, setProgressText] = useState("");
+    const [writeResult, setWriteResult] = useState(null);
+    const conversionResults = useRef([]);
+    // Handle consent decision
+    const onConsentDecision = useCallback((consented) => {
+        if (consented) {
+            setStatus("converting");
+        }
+        else {
+            setStatus("declined");
+            setTimeout(() => process.exit(EXIT_CODES.SUCCESS), 100);
+        }
+    }, []);
+    useEffect(() => {
+        let aborted = false;
+        async function run() {
+            try {
+                // Phase 1: Detect source platform
+                const projectRoot = resolve(process.cwd());
+                const result = detectPlatform(from, projectRoot);
+                if (aborted)
+                    return;
+                if (!result.success) {
+                    throw new SpecglassError(`No ${from} project detected in the current directory`, "PLATFORM_NOT_DETECTED", projectRoot, undefined, `Expected files: ${result.failure.expectedFiles.join(", ")}\n${result.failure.hint}`);
+                }
+                // Phase 2: Build migration plan
+                const targetContentDir = join(projectRoot, "src", "content", "docs");
+                const migrationPlan = buildMigrationPlan(result.detected, targetContentDir);
+                if (aborted)
+                    return;
+                setPlan(migrationPlan);
+                if (dryRun) {
+                    // Dry-run: show plan and exit
+                    setStatus("done");
+                    setTimeout(() => process.exit(EXIT_CODES.SUCCESS), 100);
+                }
+                else {
+                    // Live migration: show consent prompt
+                    setStatus("consent");
+                }
+            }
+            catch (err) {
+                if (aborted)
+                    return;
+                const specglassErr = err instanceof SpecglassError
+                    ? err
+                    : new SpecglassError(err instanceof Error ? err.message : String(err), "MIGRATE_UNEXPECTED_ERROR");
+                setError(specglassErr);
+                setStatus("error");
+                setTimeout(() => process.exit(EXIT_CODES.ERROR), 100);
+            }
+        }
+        run();
+        return () => {
+            aborted = true;
+        };
+    }, [from, dryRun]);
+    // AI conversion phase — Story 7.2
+    useEffect(() => {
+        if (status !== "converting")
+            return;
+        if (!plan)
+            return;
+        let aborted = false;
+        async function runConversion() {
+            try {
+                const apiKey = getApiKey();
+                conversionResults.current = [];
+                for await (const result of convertAll({
+                    apiKey,
+                    plan: plan,
+                    onProgress: (file, index, total) => {
+                        if (!aborted) {
+                            setProgressText(`Converting ${index + 1}/${total}: ${file.targetRelativePath}`);
+                        }
+                    },
+                })) {
+                    if (aborted)
+                        return;
+                    conversionResults.current.push(result);
+                }
+                if (aborted)
+                    return;
+                setStatus("writing");
+            }
+            catch (err) {
+                if (aborted)
+                    return;
+                const specglassErr = err instanceof SpecglassError
+                    ? err
+                    : new SpecglassError(err instanceof Error ? err.message : String(err), "MIGRATE_CONVERSION_ERROR");
+                setError(specglassErr);
+                setStatus("error");
+                setTimeout(() => process.exit(EXIT_CODES.ERROR), 100);
+            }
+        }
+        runConversion();
+        return () => {
+            aborted = true;
+        };
+    }, [status, plan]);
+    // File writing phase
+    useEffect(() => {
+        if (status !== "writing")
+            return;
+        if (!plan)
+            return;
+        let aborted = false;
+        async function runWrite() {
+            try {
+                setProgressText("Writing converted files...");
+                const result = await writeAll(plan.targetContentDir, conversionResults.current, plan.navigationMappings, plan.files);
+                if (aborted)
+                    return;
+                setWriteResult(result);
+                setStatus("done");
+                setTimeout(() => process.exit(result.filesFailed > 0 ? EXIT_CODES.ERROR : EXIT_CODES.SUCCESS), 100);
+            }
+            catch (err) {
+                if (aborted)
+                    return;
+                const specglassErr = new SpecglassError(err instanceof Error ? err.message : String(err), "MIGRATE_WRITE_ERROR");
+                setError(specglassErr);
+                setStatus("error");
+                setTimeout(() => process.exit(EXIT_CODES.ERROR), 100);
+            }
+        }
+        runWrite();
+        return () => {
+            aborted = true;
+        };
+    }, [status, plan]);
+    // ─── Render based on status ─────────────────────────────────────
+    if (status === "error" && error) {
+        return (_jsx(Box, { flexDirection: "column", children: _jsx(ErrorDisplay, { error: error }) }));
+    }
+    if (status === "declined") {
+        return (_jsx(Box, { flexDirection: "column", paddingX: 1, children: _jsx(Text, { color: "yellow", children: "\u270B Migration cancelled \u2014 no data was sent." }) }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [status === "detecting" && (_jsx(Spinner, { label: `Detecting ${from} project...` })), status === "consent" && plan && (_jsx(ConsentPrompt, { plan: plan, autoConsent: yes, onDecision: onConsentDecision })), status === "converting" && (_jsx(Spinner, { label: progressText || "Starting AI conversion..." })), status === "writing" && (_jsx(Spinner, { label: progressText || "Writing files..." })), status === "done" && plan && (_jsx(MigrationPlanDisplay, { plan: plan, dryRun: dryRun, writeResult: writeResult }))] }));
+}
+function MigrationPlanDisplay({ plan, dryRun, writeResult }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [dryRun && (_jsx(Text, { bold: true, color: "cyan", children: "\uD83D\uDCCB Migration Plan (dry-run \u2014 no changes will be made)" })), !dryRun && writeResult && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: writeResult.filesFailed > 0 ? "yellow" : "green", children: writeResult.filesFailed > 0
+                            ? "⚠️ Migration Complete (with errors)"
+                            : "✅ Migration Complete" }), _jsxs(Text, { children: ["Files converted: ", _jsx(Text, { bold: true, color: "green", children: writeResult.filesWritten }), writeResult.filesCopied > 0 && (_jsxs(Text, { children: [" | Copied: ", _jsx(Text, { bold: true, color: "cyan", children: writeResult.filesCopied })] })), writeResult.filesFailed > 0 && (_jsxs(Text, { children: [" | Failed: ", _jsx(Text, { bold: true, color: "red", children: writeResult.filesFailed })] }))] }), _jsxs(Text, { children: ["Target: ", _jsx(Text, { dimColor: true, children: plan.targetContentDir })] }), writeResult.errors.length > 0 && (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, color: "red", children: "Errors:" }), writeResult.errors.map((e, i) => (_jsxs(Text, { color: "red", children: ["  \u2022 ", e.path, ": ", e.error] }, i)))] }))] })), !dryRun && !writeResult && (_jsx(Text, { bold: true, color: "green", children: "\u2705 Migration Complete" })), _jsx(Text, { children: " " }), _jsxs(Text, { bold: true, children: ["Platform: ", _jsx(Text, { color: "yellow", children: plan.platform })] }), _jsxs(Text, { children: ["Total files: ", _jsx(Text, { bold: true, children: plan.files.length })] }), _jsxs(Text, { children: ["AI conversions: ", _jsx(Text, { bold: true, children: plan.aiConversionCount })] }), plan.simpleCopyCount > 0 && (_jsxs(Text, { children: ["Simple copies: ", _jsx(Text, { bold: true, children: plan.simpleCopyCount })] })), _jsx(Text, { children: " " }), _jsx(Text, { bold: true, underline: true, children: "File Mapping:" }), plan.files.slice(0, 20).map((file, i) => (_jsxs(Box, { children: [_jsxs(Text, { dimColor: true, children: ["  ", file.needsConversion ? "🔄" : "📋", " "] }), _jsx(Text, { dimColor: true, children: file.sourcePath }), _jsx(Text, { dimColor: true, children: " \u2192 " }), _jsx(Text, { children: file.targetRelativePath })] }, i))), plan.files.length > 20 && (_jsxs(Text, { dimColor: true, children: ["  ... and ", plan.files.length - 20, " more files"] })), _jsx(Text, { children: " " }), plan.componentMappings.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, underline: true, children: "Component Conversions:" }), plan.componentMappings.map((mapping, i) => (_jsxs(Text, { dimColor: true, children: ["  ", mapping.source, " \u2192 ", mapping.target] }, i))), _jsx(Text, { children: " " })] })), plan.navigationMappings.length > 0 && (_jsxs(_Fragment, { children: [_jsx(Text, { bold: true, underline: true, children: "Navigation Structure:" }), plan.navigationMappings.map((mapping, i) => (_jsxs(Text, { dimColor: true, children: ["  ", mapping.sourceLabel, " \u2192 ", mapping.targetDir, "/"] }, i)))] })), dryRun && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Text, { dimColor: true, children: "Run without --dry-run to execute the migration." })] }))] }));
+}

package/dist/migration/converter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Migration converter — handles AI-powered content conversion using the Claude API.
+ *
+ * Sends source documentation files to Claude for semantic conversion to ndocs MDX format.
+ * Uses the Anthropic SDK with BYOK (Bring Your Own Key) pattern.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import type { SupportedPlatform } from "./detector.js";
+import type { MigrationPlan, PlannedFile, ComponentMapping } from "./planner.js";
+/** Result of converting a single file. */
+export interface ConversionResult {
+    /** The planned file entry. */
+    file: PlannedFile;
+    /** Converted MDX content (empty string on failure). */
+    content: string;
+    /** Whether the conversion succeeded. */
+    success: boolean;
+    /** Error message if conversion failed. */
+    error?: string;
+}
+/** Options for the convertAll function. */
+export interface ConversionOptions {
+    /** Anthropic API key. */
+    apiKey: string;
+    /** The migration plan to execute. */
+    plan: MigrationPlan;
+    /** Progress callback — called for each file before conversion starts. */
+    onProgress?: (file: PlannedFile, index: number, total: number) => void;
+}
+/**
+ * Build the system prompt for Claude — defines role, rules, and component mappings.
+ */
+export declare function buildSystemPrompt(platform: SupportedPlatform, componentMappings: ComponentMapping[]): string;
+/**
+ * Build the user message for Claude — contains the source file content.
+ */
+export declare function buildUserMessage(sourceContent: string, sourcePath: string, platform: SupportedPlatform): string;
+/**
+ * Convert a single source file to ndocs MDX format using Claude.
+ */
+export declare function convertFile(client: Anthropic, sourcePath: string, platform: SupportedPlatform, componentMappings: ComponentMapping[]): Promise<string>;
+/**
+ * Convert all files in a migration plan using Claude.
+ * Yields results as each file is processed (sequential to respect rate limits).
+ */
+export declare function convertAll(options: ConversionOptions): AsyncGenerator<ConversionResult>;
+/**
+ * Validate that the ANTHROPIC_API_KEY is available.
+ * Returns the key or throws a SpecglassError.
+ */
+export declare function getApiKey(): string;

package/dist/migration/converter.js

@@ -0,0 +1,110 @@
+/**
+ * Migration converter — handles AI-powered content conversion using the Claude API.
+ *
+ * Sends source documentation files to Claude for semantic conversion to ndocs MDX format.
+ * Uses the Anthropic SDK with BYOK (Bring Your Own Key) pattern.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { readFile } from "fs/promises";
+import { SpecglassError } from "@specglass/core";
+/** Default Claude model used for conversion. */
+const DEFAULT_MODEL = "claude-sonnet-4-20250514";
+/**
+ * Build the system prompt for Claude — defines role, rules, and component mappings.
+ */
+export function buildSystemPrompt(platform, componentMappings) {
+    const mappingLines = componentMappings
+        .map((m) => `  - ${m.source} → ${m.target}`)
+        .join("\n");
+    return `You are a documentation migration tool. You convert ${platform} documentation files to ndocs MDX format.
+
+## Rules
+
+1. Convert ALL platform-specific syntax to standard MDX
+2. Apply these component mappings:
+${mappingLines}
+3. Generate valid frontmatter with at minimum:
+   - title: extracted from the first heading or existing frontmatter
+   - description: a brief description of the page content
+4. Preserve ALL content semantics — do not lose any information
+5. Convert relative links to work in the new file structure
+6. Remove any platform-specific imports that are not needed in ndocs
+7. Output ONLY the converted MDX content — no explanations, no wrapping code fences`;
+}
+/**
+ * Build the user message for Claude — contains the source file content.
+ */
+export function buildUserMessage(sourceContent, sourcePath, platform) {
+    return `Convert this ${platform} file to ndocs MDX format.
+
+Source path: ${sourcePath}
+
+${sourceContent}`;
+}
+/**
+ * Convert a single source file to ndocs MDX format using Claude.
+ */
+export async function convertFile(client, sourcePath, platform, componentMappings) {
+    const sourceContent = await readFile(sourcePath, "utf-8");
+    const systemPrompt = buildSystemPrompt(platform, componentMappings);
+    const userMessage = buildUserMessage(sourceContent, sourcePath, platform);
+    const model = process.env.ANTHROPIC_MODEL || DEFAULT_MODEL;
+    const message = await client.messages.create({
+        model,
+        max_tokens: 8192,
+        system: systemPrompt,
+        messages: [{ role: "user", content: userMessage }],
+    });
+    // Extract text content from the response
+    const textBlock = message.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+        throw new Error("No text content in Claude response");
+    }
+    // Warn if response was truncated due to max_tokens
+    if (message.stop_reason === "max_tokens") {
+        throw new Error(`Claude response truncated for ${sourcePath} — file may be too large for max_tokens=8192`);
+    }
+    return textBlock.text;
+}
+/**
+ * Convert all files in a migration plan using Claude.
+ * Yields results as each file is processed (sequential to respect rate limits).
+ */
+export async function* convertAll(options) {
+    const { apiKey, plan, onProgress } = options;
+    const client = new Anthropic({ apiKey });
+    const filesToConvert = plan.files.filter((f) => f.needsConversion);
+    for (let i = 0; i < filesToConvert.length; i++) {
+        const file = filesToConvert[i];
+        if (onProgress) {
+            onProgress(file, i, filesToConvert.length);
+        }
+        try {
+            const content = await convertFile(client, file.sourcePath, plan.platform, plan.componentMappings);
+            yield {
+                file,
+                content,
+                success: true,
+            };
+        }
+        catch (err) {
+            yield {
+                file,
+                content: "",
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+/**
+ * Validate that the ANTHROPIC_API_KEY is available.
+ * Returns the key or throws a SpecglassError.
+ */
+export function getApiKey() {
+    const key = process.env.ANTHROPIC_API_KEY;
+    if (!key) {
+        throw new SpecglassError("Missing ANTHROPIC_API_KEY environment variable", "MISSING_API_KEY", undefined, undefined, "Set ANTHROPIC_API_KEY environment variable with your Anthropic API key.\nGet one at https://console.anthropic.com/");
+    }
+    return key;
+}

package/dist/migration/detector.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Source platform detection for migration.
+ *
+ * Detects which documentation platform is being used in a project
+ * by looking for platform-specific configuration files and content.
+ */
+/** Supported source platforms for migration. */
+export declare const SUPPORTED_PLATFORMS: readonly ["mintlify", "docusaurus", "readme", "gitbook"];
+export type SupportedPlatform = (typeof SUPPORTED_PLATFORMS)[number];
+/** Result of platform detection — describes the source project. */
+export interface DetectedPlatform {
+    /** Which platform was detected. */
+    platform: SupportedPlatform;
+    /** Absolute path to the source content directory. */
+    sourceDir: string;
+    /** Absolute path to the platform config file (if found). */
+    configPath: string | null;
+    /** Absolute path to the navigation config file (if found). */
+    navConfigPath: string | null;
+    /** List of content files found (absolute paths). */
+    contentFiles: string[];
+}
+/** Detection failure result. */
+export interface DetectionFailure {
+    /** What files we looked for and didn't find. */
+    expectedFiles: string[];
+    /** Hint message for the user. */
+    hint: string;
+}
+/** Result type for platform detection. */
+export type DetectionResult = {
+    success: true;
+    detected: DetectedPlatform;
+} | {
+    success: false;
+    failure: DetectionFailure;
+};
+/**
+ * Detect a source platform's content in the given project root.
+ *
+ * @param platform - Which platform to detect
+ * @param projectRoot - Absolute path to the project root (defaults to cwd)
+ * @returns Detection result — success with detected platform info, or failure with hints
+ */
+export declare function detectPlatform(platform: SupportedPlatform, projectRoot?: string): DetectionResult;