@anydocs/core 1.0.0

package/dist/fs/docs-repository.js

@@ -0,0 +1,270 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ValidationError } from "../errors/validation-error.js";
+import { isPageApprovedForPublication } from "../publishing/publication-filter.js";
+import { validateNavigationDoc, validatePageDoc, } from "../schemas/docs-schema.js";
+import { assertValidPageId, normalizeSlug } from "../utils/slug.js";
+function createRepositoryValidationError(rule, remediation, metadata) {
+    return new ValidationError(`Docs repository validation failed for rule "${rule}".`, {
+        entity: 'docs-repository',
+        rule,
+        remediation,
+        metadata,
+    });
+}
+export function createDocsRepository(projectRoot) {
+    if (!projectRoot || projectRoot.includes('..')) {
+        throw createRepositoryValidationError('project-root-safe-path', 'Provide a project root without parent-directory traversal.', { projectRoot });
+    }
+    return {
+        projectRoot,
+        pagesRoot: path.join(projectRoot, 'pages'),
+        navigationRoot: path.join(projectRoot, 'navigation'),
+    };
+}
+function pagesDir(repository, lang) {
+    return path.join(repository.pagesRoot, lang);
+}
+function navigationFile(repository, lang) {
+    return path.join(repository.navigationRoot, `${lang}.json`);
+}
+async function readJson(filePath) {
+    const raw = await fs.readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+}
+function isMissingFileError(error) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+}
+async function writeJsonAtomic(filePath, value) {
+    const dir = path.dirname(filePath);
+    const tempFilePath = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tempFilePath, JSON.stringify(value, null, 2) + '\n', 'utf8');
+    await fs.rename(tempFilePath, filePath);
+}
+function findDuplicateSlug(pages, slug, pageId) {
+    return pages.find((page) => page.slug === slug && page.id !== pageId);
+}
+function collectNavigationPageIds(items, out) {
+    for (const item of items) {
+        if (item.type === 'page') {
+            out.push(item.pageId);
+            continue;
+        }
+        if (item.type === 'section' || item.type === 'folder') {
+            collectNavigationPageIds(item.children, out);
+        }
+    }
+}
+function collectTopLevelGroupIds(items) {
+    const ids = new Set();
+    for (const item of items) {
+        if ((item.type === 'section' || item.type === 'folder') && item.id) {
+            ids.add(item.id);
+        }
+    }
+    return ids;
+}
+function removePageReferences(items, pageId) {
+    let removed = 0;
+    const nextItems = [];
+    for (const item of items) {
+        if (item.type === 'page') {
+            if (item.pageId === pageId) {
+                removed += 1;
+                continue;
+            }
+            nextItems.push(item);
+            continue;
+        }
+        if (item.type === 'section' || item.type === 'folder') {
+            const cleaned = removePageReferences(item.children, pageId);
+            removed += cleaned.removed;
+            nextItems.push({ ...item, children: cleaned.items });
+            continue;
+        }
+        nextItems.push(item);
+    }
+    return { items: nextItems, removed };
+}
+export async function initializeDocsRepository(repository, languages = ['en', 'zh']) {
+    await fs.mkdir(repository.navigationRoot, { recursive: true });
+    for (const lang of languages) {
+        await fs.mkdir(pagesDir(repository, lang), { recursive: true });
+        const navFile = navigationFile(repository, lang);
+        try {
+            await fs.access(navFile);
+        }
+        catch {
+            await writeJsonAtomic(navFile, { version: 1, items: [] });
+        }
+    }
+}
+export async function loadNavigation(repository, lang) {
+    try {
+        return validateNavigationDoc(await readJson(navigationFile(repository, lang)));
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { version: 1, items: [] };
+        }
+        throw error;
+    }
+}
+export async function saveNavigation(repository, lang, navigation, options = {}) {
+    const validated = validateNavigationDoc(navigation);
+    if (options.existingPageIds) {
+        const knownPageIds = new Set(options.existingPageIds);
+        const referencedPageIds = [];
+        collectNavigationPageIds(validated.items, referencedPageIds);
+        const missingPageId = referencedPageIds.find((pageId) => !knownPageIds.has(pageId));
+        if (missingPageId) {
+            throw new ValidationError(`Navigation references missing page "${missingPageId}".`, {
+                entity: 'navigation-doc',
+                rule: 'navigation-page-reference-must-exist',
+                remediation: 'Create the referenced page first or remove the missing page reference from navigation.',
+                metadata: { lang, pageId: missingPageId },
+            });
+        }
+    }
+    if (options.requiredTopLevelGroupIds) {
+        const availableGroupIds = collectTopLevelGroupIds(validated.items);
+        for (const groupId of options.requiredTopLevelGroupIds) {
+            if (availableGroupIds.has(groupId)) {
+                continue;
+            }
+            throw new ValidationError(`Navigation is missing required top-level group "${groupId}".`, {
+                entity: 'navigation-doc',
+                rule: 'navigation-top-level-group-must-exist',
+                remediation: 'Create the referenced top-level section or folder, or update site.navigation.topNav to reference an existing group id.',
+                metadata: { lang, groupId },
+            });
+        }
+    }
+    await writeJsonAtomic(navigationFile(repository, lang), validated);
+    return validated;
+}
+export async function listPages(repository, lang, options = {}) {
+    let entries = [];
+    try {
+        entries = await fs.readdir(pagesDir(repository, lang));
+    }
+    catch {
+        return [];
+    }
+    const pages = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        try {
+            const page = validatePageDoc(await readJson(path.join(pagesDir(repository, lang), entry)), options);
+            if (page.lang === lang) {
+                pages.push(page);
+            }
+        }
+        catch (error) {
+            if (isMissingFileError(error)) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    pages.sort((left, right) => left.slug.localeCompare(right.slug));
+    return pages;
+}
+export async function loadPage(repository, lang, pageId, options = {}) {
+    assertValidPageId(pageId);
+    try {
+        const page = validatePageDoc(await readJson(path.join(pagesDir(repository, lang), `${pageId}.json`)), options);
+        return page.lang === lang && page.id === pageId ? page : null;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function savePage(repository, lang, page, options = {}) {
+    const validatedPage = validatePageDoc(page, options);
+    if (validatedPage.lang !== lang) {
+        throw new ValidationError(`Page language "${validatedPage.lang}" does not match requested language "${lang}".`, {
+            entity: 'page-doc',
+            rule: 'page-language-matches-target-language',
+            remediation: 'Save the page under the same language as its page.lang field.',
+            metadata: { pageId: validatedPage.id, pageLang: validatedPage.lang, targetLang: lang },
+        });
+    }
+    assertValidPageId(validatedPage.id);
+    const slug = normalizeSlug(validatedPage.slug);
+    if (!slug) {
+        throw new ValidationError('Page slug is required.', {
+            entity: 'page-doc',
+            rule: 'page-slug-required',
+            remediation: 'Provide a non-empty slug before saving the page.',
+            metadata: { pageId: validatedPage.id },
+        });
+    }
+    const normalizedPage = {
+        ...validatedPage,
+        slug,
+    };
+    if (normalizedPage.status === 'published' && !isPageApprovedForPublication(normalizedPage)) {
+        throw new ValidationError('Page review must be explicitly approved before publication.', {
+            entity: 'page-doc',
+            rule: 'page-review-must-be-approved-before-publication',
+            remediation: 'Use the explicit approve-for-publication action on reviewed imported or AI-generated content before setting status to published.',
+            metadata: {
+                pageId: normalizedPage.id,
+                lang,
+                reviewRequired: normalizedPage.review?.required ?? false,
+                approvedAt: normalizedPage.review?.approvedAt ?? null,
+            },
+        });
+    }
+    const existingPages = await listPages(repository, lang, options);
+    const duplicate = findDuplicateSlug(existingPages, normalizedPage.slug, normalizedPage.id);
+    if (duplicate) {
+        throw new ValidationError(`Duplicate slug "${normalizedPage.slug}" detected.`, {
+            entity: 'page-doc',
+            rule: 'page-slug-unique-per-language',
+            remediation: 'Choose a unique slug for the page within the same language.',
+            metadata: {
+                pageId: normalizedPage.id,
+                duplicatePageId: duplicate.id,
+                slug: normalizedPage.slug,
+                lang,
+            },
+        });
+    }
+    await writeJsonAtomic(path.join(pagesDir(repository, lang), `${normalizedPage.id}.json`), normalizedPage);
+    return normalizedPage;
+}
+export async function findPageBySlug(repository, lang, slug, options = {}) {
+    const normalizedSlug = normalizeSlug(slug);
+    const pages = await listPages(repository, lang, options);
+    return pages.find((page) => page.slug === normalizedSlug) ?? null;
+}
+export async function deletePage(repository, lang, pageId) {
+    const page = await loadPage(repository, lang, pageId);
+    if (!page) {
+        throw new ValidationError(`Page "${pageId}" not found.`, {
+            entity: 'page-doc',
+            rule: 'page-delete-target-must-exist',
+            remediation: 'Delete an existing page or refresh the page list before retrying.',
+            metadata: { lang, pageId },
+        });
+    }
+    await fs.rm(path.join(pagesDir(repository, lang), `${pageId}.json`));
+    const navigation = await loadNavigation(repository, lang);
+    const cleaned = removePageReferences(navigation.items, pageId);
+    await saveNavigation(repository, lang, {
+        ...navigation,
+        items: cleaned.items,
+    });
+    return {
+        pageId,
+        lang,
+        removedNavigationRefs: cleaned.removed,
+    };
+}

package/dist/fs/index.d.ts

@@ -0,0 +1,5 @@
+export * from './api-source-repository.ts';
+export * from './content-repository.ts';
+export * from './docs-repository.ts';
+export * from './project-paths.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/fs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fs/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/fs/index.js

@@ -0,0 +1,4 @@
+export * from "./api-source-repository.js";
+export * from "./content-repository.js";
+export * from "./docs-repository.js";
+export * from "./project-paths.js";

package/dist/fs/project-paths.d.ts

@@ -0,0 +1,4 @@
+import { type ProjectConfig, type ProjectPathContract } from '../types/project.ts';
+export declare function createProjectPathContract(repoRoot: string, config: ProjectConfig, outputDir?: string): ProjectPathContract;
+export declare function assertProjectContractStructure(config: ProjectConfig, paths: ProjectPathContract): void;
+//# sourceMappingURL=project-paths.d.ts.map

package/dist/fs/project-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-paths.d.ts","sourceRoot":"","sources":["../../src/fs/project-paths.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAE7B,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,mBAAmB,CAkDrB;AAED,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,mBAAmB,GACzB,IAAI,CAYN"}

package/dist/fs/project-paths.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { ValidationError } from "../errors/validation-error.js";
+import { ANYDOCS_CONFIG_FILE, ANYDOCS_WORKFLOW_FILE, resolveProjectRoot, } from "../config/project-config.js";
+import { SUPPORTED_DOCS_LANGUAGES, } from "../types/project.js";
+export function createProjectPathContract(repoRoot, config, outputDir) {
+    const projectRoot = resolveProjectRoot(repoRoot, config.projectId);
+    const pagesRoot = path.join(projectRoot, 'pages');
+    const navigationRoot = path.join(projectRoot, 'navigation');
+    // Determine output directory:
+    // 1. Explicit parameter (from CLI --output)
+    // 2. Config file build.outputDir
+    // 3. Default: {repoRoot}/dist
+    const resolvedOutputDir = outputDir
+        ? path.resolve(repoRoot, outputDir)
+        : config.build?.outputDir
+            ? path.resolve(projectRoot, config.build.outputDir)
+            : path.join(repoRoot, 'dist');
+    const artifactRoot = resolvedOutputDir;
+    const machineReadableRoot = path.join(artifactRoot, 'mcp');
+    const languageRoots = Object.fromEntries(SUPPORTED_DOCS_LANGUAGES.map((language) => [
+        language,
+        {
+            pagesDir: path.join(pagesRoot, language),
+            navigationFile: path.join(navigationRoot, `${language}.json`),
+            searchIndexFile: path.join(artifactRoot, `search-index.${language}.json`),
+        },
+    ]));
+    return {
+        repoRoot,
+        projectRoot,
+        configFile: path.join(projectRoot, ANYDOCS_CONFIG_FILE),
+        workflowFile: path.join(projectRoot, ANYDOCS_WORKFLOW_FILE),
+        importsRoot: path.join(projectRoot, 'imports'),
+        apiSourcesRoot: path.join(projectRoot, 'api-sources'),
+        pagesRoot,
+        navigationRoot,
+        artifactRoot,
+        llmsFile: path.join(artifactRoot, 'llms.txt'),
+        machineReadableRoot,
+        languageRoots,
+    };
+}
+export function assertProjectContractStructure(config, paths) {
+    for (const language of config.languages) {
+        const roots = paths.languageRoots[language];
+        if (!roots) {
+            throw new ValidationError(`Missing canonical language paths for "${language}".`, {
+                entity: 'project-path-contract',
+                rule: 'language-roots-must-cover-enabled-languages',
+                remediation: 'Ensure the path contract defines page, navigation, and search paths for every enabled language.',
+                metadata: { language, enabledLanguages: config.languages },
+            });
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './config/index.ts';
+export * from './errors/index.ts';
+export * from './fs/index.ts';
+export * from './publishing/index.ts';
+export * from './schemas/index.ts';
+export * from './services/index.ts';
+export * from './types/index.ts';
+export * from './utils/index.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./config/index.js";
+export * from "./errors/index.js";
+export * from "./fs/index.js";
+export * from "./publishing/index.js";
+export * from "./schemas/index.js";
+export * from "./services/index.js";
+export * from "./types/index.js";
+export * from "./utils/index.js";

package/dist/publishing/build-artifacts.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectContract } from '../types/project.ts';
+import type { BuildWorkflowPublishedSiteResult } from '../services/build-service.ts';
+export declare function writePublishedArtifacts(contract: ProjectContract, siteArtifacts: BuildWorkflowPublishedSiteResult[]): Promise<void>;
+//# sourceMappingURL=build-artifacts.d.ts.map

package/dist/publishing/build-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-artifacts.d.ts","sourceRoot":"","sources":["../../src/publishing/build-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAgD,MAAM,qBAAqB,CAAC;AAEzG,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AA0iBrF,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,eAAe,EACzB,aAAa,EAAE,gCAAgC,EAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAuIf"}