@anydocs/core 1.0.0

package/dist/services/legacy-conversion-service.js

@@ -0,0 +1,601 @@
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ValidationError } from "../errors/validation-error.js";
+import { createDocsRepository, listPages, loadNavigation, saveNavigation, savePage, } from "../fs/docs-repository.js";
+import { loadProjectContract } from "../fs/content-repository.js";
+import { isDocsLang } from "../types/docs.js";
+import { assertValidPageId, normalizeSlug } from "../utils/slug.js";
+const SUPPORTED_FRONTMATTER_KEYS = new Set(['title', 'description', 'tags']);
+const MARKDOWN_REVIEW_PATTERNS = [
+    { code: 'code-fence', label: 'code fences', pattern: /^```/m },
+    { code: 'blockquote', label: 'blockquotes', pattern: /^>\s+/m },
+    { code: 'bulleted-list', label: 'bulleted lists', pattern: /^\s*[-*+]\s+/m },
+    { code: 'numbered-list', label: 'numbered lists', pattern: /^\s*\d+\.\s+/m },
+    { code: 'table', label: 'tables', pattern: /^\|.+\|$/m },
+    { code: 'link', label: 'markdown links', pattern: /\[[^\]]+\]\([^)]+\)/m },
+    { code: 'image', label: 'images', pattern: /!\[[^\]]*\]\([^)]+\)/m },
+];
+function createConversionValidationError(message, rule, remediation, metadata) {
+    return new ValidationError(message, {
+        entity: 'legacy-conversion',
+        rule,
+        remediation,
+        metadata,
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertSafeImportId(importId) {
+    if (typeof importId !== 'string' ||
+        importId.trim().length === 0 ||
+        importId.includes('/') ||
+        importId.includes('\\') ||
+        importId.includes('..')) {
+        throw createConversionValidationError(`Invalid import id "${importId}".`, 'legacy-import-id-safe-path', 'Use a generated importId without path separators or parent-directory traversal.', { importId });
+    }
+}
+async function readJsonWithValidation(filePath, entity, rule) {
+    const raw = await readFile(filePath, 'utf8').catch(() => {
+        throw createConversionValidationError(`Missing required ${entity} at "${filePath}".`, 'legacy-import-required-file-exists', `Restore the ${entity} or rerun the import workflow before conversion.`, { filePath, entity });
+    });
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw createConversionValidationError(`${entity} at "${filePath}" is not valid JSON.`, rule, `Fix the malformed ${entity} JSON or rerun the import workflow to regenerate it.`, {
+            filePath,
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+function validateManifest(input, importId) {
+    if (!isRecord(input)) {
+        throw createConversionValidationError('Legacy import manifest must be a JSON object.', 'legacy-import-manifest-object', 'Restore the manifest.json file generated by the import workflow.', { received: input });
+    }
+    if (input.version !== 1) {
+        throw createConversionValidationError('Legacy import manifest version is unsupported.', 'legacy-import-manifest-version', 'Regenerate the staged import with the current anydocs import workflow.', { received: input.version });
+    }
+    if (input.importId !== importId) {
+        throw createConversionValidationError(`Legacy import manifest does not match import "${importId}".`, 'legacy-import-manifest-id-match', 'Use the manifest belonging to the requested importId.', { expected: importId, received: input.importId });
+    }
+    if (typeof input.projectId !== 'string' || input.projectId.trim().length === 0) {
+        throw createConversionValidationError('Legacy import manifest is missing a valid projectId.', 'legacy-import-manifest-project-id', 'Regenerate the staged import so it records the target project id.', { received: input.projectId });
+    }
+    if (typeof input.sourceRoot !== 'string' || input.sourceRoot.trim().length === 0) {
+        throw createConversionValidationError('Legacy import manifest is missing a valid sourceRoot.', 'legacy-import-manifest-source-root', 'Regenerate the staged import so it records the legacy source root.', { received: input.sourceRoot });
+    }
+    if (typeof input.importedAt !== 'string' || input.importedAt.trim().length === 0) {
+        throw createConversionValidationError('Legacy import manifest is missing a valid importedAt timestamp.', 'legacy-import-manifest-imported-at', 'Regenerate the staged import so it records when the import occurred.', { received: input.importedAt });
+    }
+    if (input.status !== 'staged' && input.status !== 'converted') {
+        throw createConversionValidationError('Legacy import manifest has an unsupported status.', 'legacy-import-manifest-status', 'Use a manifest generated by the current import workflow.', { received: input.status });
+    }
+    if (!Array.isArray(input.items)) {
+        throw createConversionValidationError('Legacy import manifest must include an items array.', 'legacy-import-manifest-items', 'Regenerate the staged import so the manifest lists imported items.', { received: input.items });
+    }
+    return {
+        version: 1,
+        importId,
+        projectId: input.projectId.trim(),
+        sourceRoot: input.sourceRoot.trim(),
+        importedAt: input.importedAt.trim(),
+        itemCount: typeof input.itemCount === 'number' ? input.itemCount : input.items.length,
+        status: input.status,
+        items: input.items.map((item) => {
+            if (!isRecord(item)) {
+                throw createConversionValidationError('Legacy import manifest item must be an object.', 'legacy-import-manifest-item-object', 'Regenerate the staged import so manifest items are valid JSON objects.', { received: item });
+            }
+            if (typeof item.id !== 'string' || item.id.trim().length === 0) {
+                throw createConversionValidationError('Legacy import manifest item is missing an id.', 'legacy-import-manifest-item-id', 'Regenerate the staged import so each item has a stable id.', { received: item.id });
+            }
+            if (!isDocsLang(item.lang)) {
+                throw createConversionValidationError('Legacy import manifest item language is invalid.', 'legacy-import-manifest-item-lang', 'Regenerate the staged import using a supported docs language.', { received: item.lang, itemId: item.id });
+            }
+            if (item.status !== 'staged' && item.status !== 'converted') {
+                throw createConversionValidationError('Legacy import manifest item status is unsupported.', 'legacy-import-manifest-item-status', 'Regenerate the staged import using the current workflow.', { received: item.status, itemId: item.id });
+            }
+            return {
+                id: item.id.trim(),
+                sourcePath: typeof item.sourcePath === 'string' ? item.sourcePath : '',
+                lang: item.lang,
+                slug: typeof item.slug === 'string' ? item.slug : '',
+                title: typeof item.title === 'string' ? item.title : '',
+                format: item.format === 'mdx' ? 'mdx' : 'markdown',
+                status: item.status,
+            };
+        }),
+    };
+}
+function validateImportItem(input, expectedItemId) {
+    if (!isRecord(input)) {
+        throw createConversionValidationError('Legacy import item must be a JSON object.', 'legacy-import-item-object', 'Restore the staged import item JSON or rerun the import workflow.', { received: input, expectedItemId });
+    }
+    if (typeof input.id !== 'string' || input.id.trim().length === 0 || input.id !== expectedItemId) {
+        throw createConversionValidationError(`Legacy import item does not match "${expectedItemId}".`, 'legacy-import-item-id-match', 'Use the staged import item file that belongs to the requested import manifest.', { expectedItemId, received: input.id });
+    }
+    if (!isDocsLang(input.lang)) {
+        throw createConversionValidationError('Legacy import item language is invalid.', 'legacy-import-item-lang', 'Regenerate the staged import using a supported docs language.', { received: input.lang, itemId: expectedItemId });
+    }
+    if (typeof input.slug !== 'string' || normalizeSlug(input.slug).length === 0) {
+        throw createConversionValidationError('Legacy import item slug is invalid.', 'legacy-import-item-slug', 'Fix the staged import item slug or rerun the import workflow.', { received: input.slug, itemId: expectedItemId });
+    }
+    if (typeof input.title !== 'string' || input.title.trim().length === 0) {
+        throw createConversionValidationError('Legacy import item title is invalid.', 'legacy-import-item-title', 'Provide a non-empty title in the staged import item before conversion.', { received: input.title, itemId: expectedItemId });
+    }
+    if (input.format !== 'markdown' && input.format !== 'mdx') {
+        throw createConversionValidationError('Legacy import item format is unsupported.', 'legacy-import-item-format', 'Use staged items generated from .md or .mdx sources only.', { received: input.format, itemId: expectedItemId });
+    }
+    if (typeof input.importedAt !== 'string' || input.importedAt.trim().length === 0) {
+        throw createConversionValidationError('Legacy import item importedAt is invalid.', 'legacy-import-item-imported-at', 'Regenerate the staged import so items record their import timestamp.', { received: input.importedAt, itemId: expectedItemId });
+    }
+    if (typeof input.rawContent !== 'string' || typeof input.body !== 'string') {
+        throw createConversionValidationError('Legacy import item content payload is invalid.', 'legacy-import-item-content', 'Regenerate the staged import so each item includes rawContent and body.', { itemId: expectedItemId });
+    }
+    if (!isRecord(input.frontmatter)) {
+        throw createConversionValidationError('Legacy import item frontmatter must be an object.', 'legacy-import-item-frontmatter', 'Regenerate the staged import so parsed frontmatter is stored as a JSON object.', { received: input.frontmatter, itemId: expectedItemId });
+    }
+    if (input.status !== 'staged' && input.status !== 'converted') {
+        throw createConversionValidationError('Legacy import item status is unsupported.', 'legacy-import-item-status', 'Use a staged import item generated by the current import workflow.', { received: input.status, itemId: expectedItemId });
+    }
+    const frontmatter = {};
+    for (const [key, value] of Object.entries(input.frontmatter)) {
+        if (typeof value === 'string') {
+            frontmatter[key] = value;
+            continue;
+        }
+        if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) {
+            frontmatter[key] = value;
+        }
+    }
+    return {
+        id: input.id.trim(),
+        sourcePath: typeof input.sourcePath === 'string' ? input.sourcePath : expectedItemId,
+        lang: input.lang,
+        slug: normalizeSlug(input.slug),
+        title: input.title.trim(),
+        description: typeof input.description === 'string' && input.description.trim() ? input.description.trim() : undefined,
+        tags: Array.isArray(input.tags) ? input.tags.filter((tag) => typeof tag === 'string' && tag.trim().length > 0) : undefined,
+        format: input.format,
+        importedAt: input.importedAt.trim(),
+        rawContent: input.rawContent,
+        body: input.body,
+        frontmatter,
+        status: input.status,
+        convertedAt: typeof input.convertedAt === 'string' ? input.convertedAt : undefined,
+    };
+}
+function stripMarkdown(markdown) {
+    return markdown
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/`[^`]*`/g, ' ')
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+        .replace(/\[[^\]]*\]\([^)]*\)/g, ' ')
+        .replace(/[#>*_~]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function toTitleCase(segment) {
+    return segment
+        .split('-')
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
+function toYooptaParagraphBlock(blockId, elementId, text, order) {
+    return {
+        [blockId]: {
+            id: blockId,
+            type: 'Paragraph',
+            value: [
+                {
+                    id: elementId,
+                    type: 'paragraph',
+                    children: [{ text }],
+                    props: { nodeType: 'block' },
+                },
+            ],
+            meta: { order, depth: 0 },
+        },
+    };
+}
+function toYooptaHeadingBlock(blockId, elementId, text, headingType, elementType, order) {
+    return {
+        [blockId]: {
+            id: blockId,
+            type: headingType,
+            value: [
+                {
+                    id: elementId,
+                    type: elementType,
+                    children: [{ text }],
+                    props: { nodeType: 'block' },
+                },
+            ],
+            meta: { order, depth: 0 },
+        },
+    };
+}
+function createEditableLegacyContent(markdown) {
+    const trimmed = markdown.trim();
+    if (!trimmed) {
+        return toYooptaParagraphBlock('block-1', 'element-1', '', 0);
+    }
+    const chunks = trimmed
+        .split(/\n\s*\n/)
+        .map((chunk) => chunk.trim())
+        .filter(Boolean);
+    return chunks.reduce((content, chunk, index) => {
+        const blockId = `block-${index + 1}`;
+        const elementId = `element-${index + 1}`;
+        if (chunk.startsWith('# ')) {
+            return {
+                ...content,
+                ...toYooptaHeadingBlock(blockId, elementId, chunk.slice(2).trim(), 'HeadingOne', 'h1', index),
+            };
+        }
+        if (chunk.startsWith('## ')) {
+            return {
+                ...content,
+                ...toYooptaHeadingBlock(blockId, elementId, chunk.slice(3).trim(), 'HeadingTwo', 'h2', index),
+            };
+        }
+        if (chunk.startsWith('### ')) {
+            return {
+                ...content,
+                ...toYooptaHeadingBlock(blockId, elementId, chunk.slice(4).trim(), 'HeadingThree', 'h3', index),
+            };
+        }
+        const paragraphText = chunk.replace(/\n+/g, ' ').trim();
+        return {
+            ...content,
+            ...toYooptaParagraphBlock(blockId, elementId, paragraphText, index),
+        };
+    }, {});
+}
+function createUniquePageId(baseId, existingPageIds) {
+    assertValidPageId(baseId);
+    if (!existingPageIds.has(baseId)) {
+        existingPageIds.add(baseId);
+        return { value: baseId };
+    }
+    let suffix = 2;
+    let nextId = `${baseId}-${suffix}`;
+    while (existingPageIds.has(nextId)) {
+        suffix += 1;
+        nextId = `${baseId}-${suffix}`;
+    }
+    existingPageIds.add(nextId);
+    return {
+        value: nextId,
+        warning: {
+            code: 'legacy-import-page-id-conflict',
+            message: `Page id "${baseId}" already exists and was remapped to "${nextId}".`,
+            remediation: 'Review the converted page id and rename it if a more meaningful identifier is needed.',
+            metadata: { requestedPageId: baseId, convertedPageId: nextId },
+        },
+    };
+}
+function createUniqueSlug(baseSlug, existingSlugs) {
+    const normalized = normalizeSlug(baseSlug);
+    if (!normalized) {
+        throw createConversionValidationError('Legacy import item slug could not be normalized.', 'legacy-import-item-slug-normalized', 'Fix the staged import item slug before conversion.', { received: baseSlug });
+    }
+    if (!existingSlugs.has(normalized)) {
+        existingSlugs.add(normalized);
+        return { value: normalized };
+    }
+    const segments = normalized.split('/');
+    const leaf = segments.pop() ?? normalized;
+    let suffix = 2;
+    let candidate = [...segments, `${leaf}-${suffix}`].join('/');
+    while (existingSlugs.has(candidate)) {
+        suffix += 1;
+        candidate = [...segments, `${leaf}-${suffix}`].join('/');
+    }
+    existingSlugs.add(candidate);
+    return {
+        value: candidate,
+        warning: {
+            code: 'legacy-import-slug-conflict',
+            message: `Slug "${normalized}" already exists and was remapped to "${candidate}".`,
+            remediation: 'Review the converted slug and rename it if a cleaner route is desired.',
+            metadata: { requestedSlug: normalized, convertedSlug: candidate },
+        },
+    };
+}
+function collectItemWarnings(item) {
+    const warnings = [];
+    if (item.format === 'mdx') {
+        warnings.push({
+            itemId: item.id,
+            code: 'legacy-import-mdx-review-required',
+            message: `Imported "${item.sourcePath}" originated from MDX and should be reviewed for unsupported JSX or component usage.`,
+            remediation: 'Open the converted draft page and confirm the markdown/render output matches the intended MDX content.',
+            metadata: { sourcePath: item.sourcePath },
+        });
+    }
+    const unmappedFrontmatterKeys = Object.keys(item.frontmatter).filter((key) => !SUPPORTED_FRONTMATTER_KEYS.has(key));
+    if (unmappedFrontmatterKeys.length > 0) {
+        warnings.push({
+            itemId: item.id,
+            code: 'legacy-import-frontmatter-unmapped',
+            message: `Imported "${item.sourcePath}" includes frontmatter keys that were preserved in content metadata but not mapped to first-class page fields.`,
+            remediation: 'Review the converted page content metadata and manually map any important legacy frontmatter fields.',
+            metadata: { sourcePath: item.sourcePath, keys: unmappedFrontmatterKeys },
+        });
+    }
+    const detectedConstructs = MARKDOWN_REVIEW_PATTERNS.filter((entry) => entry.pattern.test(item.body));
+    if (detectedConstructs.length > 0) {
+        warnings.push({
+            itemId: item.id,
+            code: 'legacy-import-markdown-construct-review-required',
+            message: `Imported "${item.sourcePath}" contains markdown constructs that are preserved as markdown/render output but simplified in the editable Studio content.`,
+            remediation: 'Review the converted draft page and restore any lists, code blocks, tables, links, or quotes that should remain structured after import.',
+            metadata: {
+                sourcePath: item.sourcePath,
+                constructs: detectedConstructs.map((entry) => ({
+                    code: entry.code,
+                    label: entry.label,
+                })),
+            },
+        });
+    }
+    return warnings;
+}
+function createConvertedPage(item, importId, convertedAt, pageId, slug, warnings) {
+    return {
+        id: pageId,
+        lang: item.lang,
+        slug,
+        title: item.title,
+        ...(item.description ? { description: item.description } : {}),
+        ...(item.tags ? { tags: item.tags } : {}),
+        status: 'draft',
+        updatedAt: convertedAt,
+        content: createEditableLegacyContent(item.body),
+        render: {
+            markdown: item.body,
+            plainText: stripMarkdown(item.body),
+        },
+        review: {
+            required: true,
+            sourceType: 'legacy-import',
+            sourceId: importId,
+            itemId: item.id,
+            sourcePath: item.sourcePath,
+            metadata: {
+                format: item.format,
+                importedAt: item.importedAt,
+                convertedAt,
+                frontmatter: item.frontmatter,
+                rawContent: item.rawContent,
+            },
+            warnings: warnings.map((warning) => ({
+                code: warning.code,
+                message: warning.message,
+                ...(warning.remediation ? { remediation: warning.remediation } : {}),
+                ...(warning.metadata ? { metadata: warning.metadata } : {}),
+            })),
+        },
+    };
+}
+function createUpdatedItem(item, convertedAt) {
+    return {
+        ...item,
+        status: 'converted',
+        convertedAt,
+    };
+}
+function buildImportedNavigationSection(importId, items) {
+    const root = {
+        type: 'section',
+        title: `Imported: ${importId}`,
+        children: [],
+    };
+    const folderIndex = new Map();
+    for (const item of items) {
+        const segments = item.slug.split('/').filter(Boolean);
+        const folderSegments = segments.slice(0, -1);
+        let currentChildren = root.children;
+        let currentPath = '';
+        for (const folderSegment of folderSegments) {
+            currentPath = currentPath ? `${currentPath}/${folderSegment}` : folderSegment;
+            let folder = folderIndex.get(currentPath);
+            if (!folder) {
+                folder = {
+                    type: 'folder',
+                    title: toTitleCase(folderSegment),
+                    children: [],
+                };
+                folderIndex.set(currentPath, folder);
+                currentChildren.push(folder);
+            }
+            currentChildren = folder.children;
+        }
+        currentChildren.push({
+            type: 'page',
+            pageId: item.pageId,
+        });
+    }
+    return root;
+}
+async function writeJson(filePath, value) {
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+async function snapshotPath(filePath) {
+    try {
+        const current = await stat(filePath);
+        if (current.isDirectory()) {
+            return { filePath, kind: 'directory' };
+        }
+        return {
+            filePath,
+            kind: 'file',
+            contents: await readFile(filePath, 'utf8'),
+        };
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return { filePath, kind: 'missing' };
+        }
+        throw error;
+    }
+}
+async function restoreSnapshot(snapshot) {
+    if (snapshot.kind === 'missing') {
+        await rm(snapshot.filePath, { recursive: true, force: true });
+        return;
+    }
+    if (snapshot.kind === 'directory') {
+        await rm(snapshot.filePath, { recursive: true, force: true });
+        await mkdir(snapshot.filePath, { recursive: true });
+        return;
+    }
+    await rm(snapshot.filePath, { recursive: true, force: true });
+    await writeFile(snapshot.filePath, snapshot.contents, 'utf8');
+}
+function navigationFilePath(projectRoot, lang) {
+    return path.join(projectRoot, 'navigation', `${lang}.json`);
+}
+function pageFilePath(projectRoot, lang, pageId) {
+    return path.join(projectRoot, 'pages', lang, `${pageId}.json`);
+}
+export async function convertImportedLegacyContent(options) {
+    const contractResult = await loadProjectContract(options.repoRoot, options.projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    assertSafeImportId(options.importId);
+    const contract = contractResult.value;
+    const importRoot = path.join(contract.paths.importsRoot, options.importId);
+    const manifestFile = path.join(importRoot, 'manifest.json');
+    const reportFile = path.join(importRoot, 'conversion-report.json');
+    const rawManifest = await readJsonWithValidation(manifestFile, 'legacy import manifest', 'legacy-import-manifest-json-valid');
+    const manifest = validateManifest(rawManifest, options.importId);
+    if (manifest.status !== 'staged') {
+        throw createConversionValidationError(`Legacy import "${options.importId}" has already been converted.`, 'legacy-import-already-converted', 'Review the existing converted pages or stage a fresh import before converting again.', { importId: options.importId, status: manifest.status });
+    }
+    const repository = createDocsRepository(contract.paths.projectRoot);
+    const convertedAt = new Date().toISOString();
+    const plansByLang = new Map();
+    const globalWarnings = [];
+    const enabledLanguages = new Set(contract.config.languages);
+    const unsupportedLanguageItem = manifest.items.find((item) => !enabledLanguages.has(item.lang));
+    if (unsupportedLanguageItem) {
+        throw createConversionValidationError(`Legacy import item "${unsupportedLanguageItem.id}" targets language "${unsupportedLanguageItem.lang}" which is not enabled for the project.`, 'legacy-import-item-language-enabled', 'Enable the language in anydocs.config.json or restage the import using one of the configured project languages.', {
+            itemId: unsupportedLanguageItem.id,
+            itemLanguage: unsupportedLanguageItem.lang,
+            projectLanguages: contract.config.languages,
+        });
+    }
+    for (const lang of contract.config.languages) {
+        plansByLang.set(lang, []);
+    }
+    for (const lang of contract.config.languages) {
+        const plans = plansByLang.get(lang);
+        if (!plans) {
+            continue;
+        }
+        const existingPages = await listPages(repository, lang);
+        const existingPageIds = new Set(existingPages.map((page) => page.id));
+        const existingSlugs = new Set(existingPages.map((page) => page.slug));
+        const languageManifestItems = manifest.items.filter((item) => item.lang === lang);
+        for (const manifestItem of languageManifestItems) {
+            const itemFile = path.join(importRoot, 'items', `${manifestItem.id}.json`);
+            const rawItem = await readJsonWithValidation(itemFile, 'legacy import item', 'legacy-import-item-json-valid');
+            const item = validateImportItem(rawItem, manifestItem.id);
+            const warnings = collectItemWarnings(item);
+            const pageIdResolution = createUniquePageId(item.id, existingPageIds);
+            if (pageIdResolution.warning) {
+                warnings.push({ ...pageIdResolution.warning, itemId: item.id });
+            }
+            const slugResolution = createUniqueSlug(item.slug, existingSlugs);
+            if (slugResolution.warning) {
+                warnings.push({ ...slugResolution.warning, itemId: item.id });
+            }
+            const entry = {
+                itemId: item.id,
+                pageId: pageIdResolution.value,
+                lang: item.lang,
+                slug: slugResolution.value,
+                status: 'draft',
+                warnings,
+            };
+            plans.push({
+                entry,
+                page: createConvertedPage(item, options.importId, convertedAt, pageIdResolution.value, slugResolution.value, warnings),
+                updatedItem: createUpdatedItem(item, convertedAt),
+            });
+            globalWarnings.push(...warnings);
+        }
+    }
+    const convertedItems = Array.from(plansByLang.values()).flatMap((plans) => plans.map((plan) => plan.entry));
+    const report = {
+        version: 1,
+        importId: options.importId,
+        projectId: contract.config.projectId,
+        convertedAt,
+        status: 'converted',
+        convertedCount: convertedItems.length,
+        items: convertedItems,
+        warnings: globalWarnings,
+    };
+    const updatedManifest = {
+        ...manifest,
+        status: 'converted',
+        items: manifest.items.map((item) => ({
+            ...item,
+            status: 'converted',
+        })),
+    };
+    const snapshotTargets = new Set([manifestFile, reportFile]);
+    for (const [lang, plans] of plansByLang) {
+        if (plans.length === 0) {
+            continue;
+        }
+        snapshotTargets.add(navigationFilePath(contract.paths.projectRoot, lang));
+        for (const plan of plans) {
+            snapshotTargets.add(pageFilePath(contract.paths.projectRoot, lang, plan.page.id));
+            snapshotTargets.add(path.join(importRoot, 'items', `${plan.updatedItem.id}.json`));
+        }
+    }
+    const snapshots = await Promise.all(Array.from(snapshotTargets, (filePath) => snapshotPath(filePath)));
+    try {
+        for (const [lang, plans] of plansByLang) {
+            if (plans.length === 0) {
+                continue;
+            }
+            for (const plan of plans) {
+                await savePage(repository, lang, plan.page);
+            }
+            const navigation = await loadNavigation(repository, lang);
+            const importedSection = buildImportedNavigationSection(options.importId, plans.map((plan) => plan.entry));
+            const updatedNavigation = {
+                version: navigation.version,
+                items: [...navigation.items, importedSection],
+            };
+            const existingPageIds = (await listPages(repository, lang)).map((page) => page.id);
+            await saveNavigation(repository, lang, updatedNavigation, { existingPageIds });
+            for (const plan of plans) {
+                await writeJson(path.join(importRoot, 'items', `${plan.updatedItem.id}.json`), plan.updatedItem);
+            }
+        }
+        await writeJson(reportFile, report);
+        await writeJson(manifestFile, updatedManifest);
+    }
+    catch (error) {
+        for (const snapshot of [...snapshots].reverse()) {
+            await restoreSnapshot(snapshot);
+        }
+        throw error;
+    }
+    return {
+        importId: options.importId,
+        importRoot,
+        reportFile,
+        convertedCount: convertedItems.length,
+        items: convertedItems,
+        warnings: globalWarnings,
+    };
+}

package/dist/services/legacy-import-service.d.ts

@@ -0,0 +1,10 @@
+import type { LegacyImportResult } from '../types/legacy-import.ts';
+import type { DocsLanguage } from '../types/project.ts';
+export type ImportLegacyDocumentationOptions = {
+    repoRoot: string;
+    sourceRoot: string;
+    projectId?: string;
+    lang?: DocsLanguage;
+};
+export declare function importLegacyDocumentation(options: ImportLegacyDocumentationOptions): Promise<LegacyImportResult>;
+//# sourceMappingURL=legacy-import-service.d.ts.map

package/dist/services/legacy-import-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-import-service.d.ts","sourceRoot":"","sources":["../../src/services/legacy-import-service.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAMV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,MAAM,gCAAgC,GAAG;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,CAAC;AA8PF,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,kBAAkB,CAAC,CA8E7B"}