@anydocs/core 1.0.0

package/dist/schemas/docs-schema.js

@@ -0,0 +1,212 @@
+import { isDocsLang, isPageStatus, } from "../types/docs.js";
+import { ValidationError } from "../errors/validation-error.js";
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function createDocsValidationError(entity, rule, remediation, metadata) {
+    return new ValidationError(`Validation failed for "${entity}" on rule "${rule}".`, {
+        entity,
+        rule,
+        remediation,
+        metadata,
+    });
+}
+function assertNonEmptyString(value, entity, rule, remediation) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw createDocsValidationError(entity, rule, remediation, { received: value });
+    }
+}
+function assertOptionalStringArray(value, entity, rule, remediation) {
+    if (value == null) {
+        return;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw createDocsValidationError(entity, rule, remediation, { received: value });
+    }
+}
+function assertOptionalNavGroupId(value, pathLabel) {
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw createDocsValidationError('nav-item', 'group-id-string', 'Use a non-empty string for "id" on navigation groups when a stable group id is needed.', { path: pathLabel, received: value });
+    }
+    const trimmed = value.trim();
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(trimmed)) {
+        throw createDocsValidationError('nav-item', 'group-id-format', 'Use lowercase letters, numbers, and hyphens only for navigation group ids.', { path: pathLabel, received: value });
+    }
+    return trimmed;
+}
+function validateNavItem(input, pathLabel) {
+    if (!isRecord(input) || typeof input.type !== 'string') {
+        throw createDocsValidationError('nav-item', 'nav-item-structure', 'Ensure each navigation item is an object with a valid "type" field.', { path: pathLabel, received: input });
+    }
+    switch (input.type) {
+        case 'section':
+        case 'folder': {
+            assertNonEmptyString(input.title, 'nav-item', 'group-title-required', 'Provide a non-empty "title" for section and folder navigation items.');
+            if (!Array.isArray(input.children)) {
+                throw createDocsValidationError('nav-item', 'group-children-required', 'Provide a "children" array for section and folder navigation items.', { path: pathLabel, received: input.children });
+            }
+            return {
+                type: input.type,
+                ...(assertOptionalNavGroupId(input.id, pathLabel) ? { id: assertOptionalNavGroupId(input.id, pathLabel) } : {}),
+                title: input.title.trim(),
+                children: input.children.map((child, index) => validateNavItem(child, `${pathLabel}.children[${index}]`)),
+            };
+        }
+        case 'page': {
+            assertNonEmptyString(input.pageId, 'nav-item', 'page-id-required', 'Provide a non-empty "pageId" for page navigation items.');
+            if (input.titleOverride != null && typeof input.titleOverride !== 'string') {
+                throw createDocsValidationError('nav-item', 'title-override-string', 'Use a string for "titleOverride" when overriding a page title.', { path: pathLabel, received: input.titleOverride });
+            }
+            if (input.hidden != null && typeof input.hidden !== 'boolean') {
+                throw createDocsValidationError('nav-item', 'hidden-boolean', 'Use a boolean for "hidden" on page navigation items.', { path: pathLabel, received: input.hidden });
+            }
+            return {
+                type: 'page',
+                pageId: input.pageId.trim(),
+                ...(input.titleOverride ? { titleOverride: input.titleOverride } : {}),
+                ...(typeof input.hidden === 'boolean' ? { hidden: input.hidden } : {}),
+            };
+        }
+        case 'link': {
+            assertNonEmptyString(input.title, 'nav-item', 'link-title-required', 'Provide a non-empty "title" for link navigation items.');
+            assertNonEmptyString(input.href, 'nav-item', 'link-href-required', 'Provide a non-empty "href" for link navigation items.');
+            return {
+                type: 'link',
+                title: input.title.trim(),
+                href: input.href.trim(),
+            };
+        }
+        default:
+            throw createDocsValidationError('nav-item', 'unsupported-nav-item-type', 'Use only section, folder, page, or link navigation item types.', { path: pathLabel, received: input.type });
+    }
+}
+function validateReviewWarning(input, index) {
+    if (!isRecord(input)) {
+        throw createDocsValidationError('page-review-warning', 'page-review-warning-object', 'Use an object for each page review warning entry.', { index, received: input });
+    }
+    assertNonEmptyString(input.code, 'page-review-warning', 'page-review-warning-code-required', 'Provide a non-empty code for each review warning.');
+    assertNonEmptyString(input.message, 'page-review-warning', 'page-review-warning-message-required', 'Provide a non-empty message for each review warning.');
+    if (input.remediation != null && typeof input.remediation !== 'string') {
+        throw createDocsValidationError('page-review-warning', 'page-review-warning-remediation-string', 'Use a string remediation when a review warning includes remediation guidance.', { index, received: input.remediation });
+    }
+    if (input.metadata != null && !isRecord(input.metadata)) {
+        throw createDocsValidationError('page-review-warning', 'page-review-warning-metadata-object', 'Use an object for review warning metadata when it is present.', { index, received: input.metadata });
+    }
+    return {
+        code: input.code.trim(),
+        message: input.message.trim(),
+        ...(typeof input.remediation === 'string' ? { remediation: input.remediation } : {}),
+        ...(isRecord(input.metadata) ? { metadata: input.metadata } : {}),
+    };
+}
+function validatePageReview(input) {
+    if (!isRecord(input)) {
+        throw createDocsValidationError('page-review', 'page-review-object', 'Use an object for page review metadata when review metadata is present.', { received: input });
+    }
+    if (typeof input.required !== 'boolean') {
+        throw createDocsValidationError('page-review', 'page-review-required-boolean', 'Provide a boolean "required" field on page review metadata.', { received: input.required });
+    }
+    if (input.sourceType !== 'legacy-import' && input.sourceType !== 'ai-generated') {
+        throw createDocsValidationError('page-review', 'page-review-source-type', 'Use "legacy-import" or "ai-generated" for page review sourceType.', { received: input.sourceType });
+    }
+    assertNonEmptyString(input.sourceId, 'page-review', 'page-review-source-id-required', 'Provide a non-empty sourceId for page review metadata.');
+    if (input.itemId != null && typeof input.itemId !== 'string') {
+        throw createDocsValidationError('page-review', 'page-review-item-id-string', 'Use a string itemId when page review metadata includes an itemId.', { received: input.itemId });
+    }
+    if (input.sourcePath != null && typeof input.sourcePath !== 'string') {
+        throw createDocsValidationError('page-review', 'page-review-source-path-string', 'Use a string sourcePath when page review metadata includes a sourcePath.', { received: input.sourcePath });
+    }
+    if (input.approvedAt != null && typeof input.approvedAt !== 'string') {
+        throw createDocsValidationError('page-review', 'page-review-approved-at-string', 'Use an ISO 8601 string for approvedAt when review approval metadata is present.', { received: input.approvedAt });
+    }
+    if (input.metadata != null && !isRecord(input.metadata)) {
+        throw createDocsValidationError('page-review', 'page-review-metadata-object', 'Use an object for page review metadata.metadata when present.', { received: input.metadata });
+    }
+    if (input.warnings != null && !Array.isArray(input.warnings)) {
+        throw createDocsValidationError('page-review', 'page-review-warnings-array', 'Use an array for page review warnings when present.', { received: input.warnings });
+    }
+    return {
+        required: input.required,
+        sourceType: input.sourceType,
+        sourceId: input.sourceId.trim(),
+        ...(typeof input.itemId === 'string' ? { itemId: input.itemId } : {}),
+        ...(typeof input.sourcePath === 'string' ? { sourcePath: input.sourcePath } : {}),
+        ...(typeof input.approvedAt === 'string' ? { approvedAt: input.approvedAt } : {}),
+        ...(isRecord(input.metadata) ? { metadata: input.metadata } : {}),
+        ...(Array.isArray(input.warnings)
+            ? { warnings: input.warnings.map((warning, index) => validateReviewWarning(warning, index)) }
+            : {}),
+    };
+}
+export function validateNavigationDoc(input) {
+    if (!isRecord(input)) {
+        throw createDocsValidationError('navigation-doc', 'navigation-doc-must-be-object', 'Ensure the navigation file is a JSON object.');
+    }
+    if (typeof input.version !== 'number') {
+        throw createDocsValidationError('navigation-doc', 'navigation-version-required', 'Provide a numeric "version" on the navigation document.', { received: input.version });
+    }
+    if (!Array.isArray(input.items)) {
+        throw createDocsValidationError('navigation-doc', 'navigation-items-required', 'Provide an "items" array on the navigation document.', { received: input.items });
+    }
+    return {
+        version: input.version,
+        items: input.items.map((item, index) => validateNavItem(item, `items[${index}]`)),
+    };
+}
+export function validatePageDoc(input, options = {}) {
+    if (!isRecord(input)) {
+        throw createDocsValidationError('page-doc', 'page-doc-must-be-object', 'Ensure the page document is a JSON object.');
+    }
+    assertNonEmptyString(input.id, 'page-doc', 'page-id-required', 'Provide a non-empty "id" for the page.');
+    if (!isDocsLang(input.lang)) {
+        throw createDocsValidationError('page-doc', 'page-language-invalid', 'Use a supported docs language such as "en" or "zh".', { received: input.lang });
+    }
+    assertNonEmptyString(input.slug, 'page-doc', 'page-slug-required', 'Provide a non-empty "slug" for the page.');
+    assertNonEmptyString(input.title, 'page-doc', 'page-title-required', 'Provide a non-empty "title" for the page.');
+    if (input.description != null && typeof input.description !== 'string') {
+        throw createDocsValidationError('page-doc', 'page-description-string', 'Use a string for "description" when the field is present.', { received: input.description });
+    }
+    assertOptionalStringArray(input.tags, 'page-doc', 'page-tags-string-array', 'Use a string array for "tags" when tags are present.');
+    if (!isPageStatus(input.status)) {
+        throw createDocsValidationError('page-doc', 'page-status-invalid', 'Use one of the supported page statuses: draft, in_review, published.', { received: input.status });
+    }
+    if (input.updatedAt != null && typeof input.updatedAt !== 'string') {
+        throw createDocsValidationError('page-doc', 'page-updated-at-string', 'Use an ISO 8601 string for "updatedAt" when the field is present.', { received: input.updatedAt });
+    }
+    if (input.render != null) {
+        if (!isRecord(input.render)) {
+            throw createDocsValidationError('page-doc', 'page-render-must-be-object', 'Use an object for "render" when render metadata is present.', { received: input.render });
+        }
+        if (input.render.markdown != null && typeof input.render.markdown !== 'string') {
+            throw createDocsValidationError('page-doc', 'page-render-markdown-string', 'Use a string for render.markdown when present.', { received: input.render.markdown });
+        }
+        if (input.render.plainText != null && typeof input.render.plainText !== 'string') {
+            throw createDocsValidationError('page-doc', 'page-render-plain-text-string', 'Use a string for render.plainText when present.', { received: input.render.plainText });
+        }
+    }
+    if (!('content' in input)) {
+        throw createDocsValidationError('page-doc', 'page-content-required', 'Provide a "content" payload for the page document.');
+    }
+    if (options.validateContent) {
+        options.validateContent(input.content);
+    }
+    if (input.review != null && !isRecord(input.review)) {
+        throw createDocsValidationError('page-doc', 'page-review-object', 'Use an object for page review metadata when the review field is present.', { received: input.review });
+    }
+    return {
+        id: input.id.trim(),
+        lang: input.lang,
+        slug: input.slug.trim(),
+        title: input.title.trim(),
+        ...(typeof input.description === 'string' ? { description: input.description } : {}),
+        ...(Array.isArray(input.tags) ? { tags: input.tags } : {}),
+        status: input.status,
+        ...(typeof input.updatedAt === 'string' ? { updatedAt: input.updatedAt } : {}),
+        content: input.content,
+        ...(isRecord(input.render) ? { render: input.render } : {}),
+        ...(isRecord(input.review) ? { review: validatePageReview(input.review) } : {}),
+    };
+}

package/dist/schemas/index.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC"}

package/dist/schemas/index.js

@@ -0,0 +1,3 @@
+export * from "./api-source-schema.js";
+export * from "./docs-schema.js";
+export * from "./project-schema.js";

package/dist/schemas/project-schema.d.ts

@@ -0,0 +1,3 @@
+import { type ProjectConfig } from '../types/project.ts';
+export declare function validateProjectConfig(input: unknown): ProjectConfig;
+//# sourceMappingURL=project-schema.d.ts.map

package/dist/schemas/project-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-schema.d.ts","sourceRoot":"","sources":["../../src/schemas/project-schema.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAyJ7B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAmUnE"}

package/dist/schemas/project-schema.js

@@ -0,0 +1,268 @@
+import { ValidationError } from "../errors/validation-error.js";
+import { SUPPORTED_DOCS_CODE_THEMES, SUPPORTED_DOCS_LANGUAGES, } from "../types/project.js";
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSupportedLanguage(value) {
+    return typeof value === 'string' && SUPPORTED_DOCS_LANGUAGES.includes(value);
+}
+function makeValidationError(rule, remediation, metadata) {
+    return new ValidationError(`Project configuration failed validation for rule "${rule}".`, {
+        entity: 'project-config',
+        rule,
+        remediation,
+        metadata,
+    });
+}
+function isHexColor(value) {
+    return /^#[0-9a-fA-F]{6}$/.test(value);
+}
+function isSlugLikeId(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+function validateTopNavLabel(input, itemId) {
+    if (typeof input === 'string') {
+        if (input.trim().length === 0) {
+            throw makeValidationError('site-navigation-top-nav-label-string', 'Use a non-empty string for a top navigation label.', { itemId, received: input });
+        }
+        return input.trim();
+    }
+    if (!isRecord(input)) {
+        throw makeValidationError('site-navigation-top-nav-label-object', 'Use a string or language-keyed object for top navigation labels.', { itemId, received: input });
+    }
+    const next = {};
+    for (const language of SUPPORTED_DOCS_LANGUAGES) {
+        const value = input[language];
+        if (value == null) {
+            continue;
+        }
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw makeValidationError('site-navigation-top-nav-label-language-string', `Use a non-empty string for "site.navigation.topNav[].label.${language}" when provided.`, { itemId, language, received: value });
+        }
+        next[language] = value.trim();
+    }
+    if (Object.keys(next).length === 0) {
+        throw makeValidationError('site-navigation-top-nav-label-language-required', 'Provide at least one localized top navigation label value.', { itemId, received: input });
+    }
+    return next;
+}
+function validateTopNavItem(input, index) {
+    if (!isRecord(input)) {
+        throw makeValidationError('site-navigation-top-nav-item-object', 'Use an object for each top navigation item.', { index, received: input });
+    }
+    const id = input.id;
+    if (typeof id !== 'string' || id.trim().length === 0 || !isSlugLikeId(id.trim())) {
+        throw makeValidationError('site-navigation-top-nav-item-id', 'Use a lowercase slug-like id for each top navigation item.', { index, received: id });
+    }
+    if (input.type !== 'nav-group' && input.type !== 'external') {
+        throw makeValidationError('site-navigation-top-nav-item-type', 'Use "nav-group" or "external" for each top navigation item type.', { index, itemId: id.trim(), received: input.type });
+    }
+    const label = validateTopNavLabel(input.label, id.trim());
+    if (input.type === 'nav-group') {
+        const groupId = input.groupId;
+        if (typeof groupId !== 'string' || groupId.trim().length === 0 || !isSlugLikeId(groupId.trim())) {
+            throw makeValidationError('site-navigation-top-nav-group-id', 'Use a lowercase slug-like "groupId" for nav-group top navigation items.', { index, itemId: id.trim(), received: groupId });
+        }
+        return {
+            id: id.trim(),
+            type: 'nav-group',
+            groupId: groupId.trim(),
+            label,
+        };
+    }
+    const href = input.href;
+    if (typeof href !== 'string' || href.trim().length === 0) {
+        throw makeValidationError('site-navigation-top-nav-href', 'Provide a non-empty "href" for external top navigation items.', { index, itemId: id.trim(), received: href });
+    }
+    if (input.openInNewTab != null && typeof input.openInNewTab !== 'boolean') {
+        throw makeValidationError('site-navigation-top-nav-open-in-new-tab', 'Use a boolean for "openInNewTab" on external top navigation items.', { index, itemId: id.trim(), received: input.openInNewTab });
+    }
+    return {
+        id: id.trim(),
+        type: 'external',
+        href: href.trim(),
+        ...(typeof input.openInNewTab === 'boolean' ? { openInNewTab: input.openInNewTab } : {}),
+        label,
+    };
+}
+export function validateProjectConfig(input) {
+    if (!isRecord(input)) {
+        throw makeValidationError('config-must-be-object', 'Ensure anydocs.config.json contains a single JSON object.');
+    }
+    const version = input.version;
+    if (version !== 1) {
+        throw makeValidationError('version-must-be-1', 'Set "version" to 1 in anydocs.config.json.', { received: version });
+    }
+    const projectId = input.projectId;
+    if (typeof projectId !== 'string' || projectId.trim().length === 0) {
+        throw makeValidationError('project-id-required', 'Provide a non-empty "projectId" using URL-safe characters.', { received: projectId });
+    }
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(projectId)) {
+        throw makeValidationError('project-id-format', 'Use lowercase letters, numbers, and hyphens only for "projectId".', { received: projectId });
+    }
+    const name = input.name;
+    if (typeof name !== 'string' || name.trim().length === 0) {
+        throw makeValidationError('project-name-required', 'Provide a non-empty human-readable "name" in anydocs.config.json.', { received: name });
+    }
+    const defaultLanguage = input.defaultLanguage;
+    if (!isSupportedLanguage(defaultLanguage)) {
+        throw makeValidationError('default-language-invalid', `Set "defaultLanguage" to one of: ${SUPPORTED_DOCS_LANGUAGES.join(', ')}.`, { received: defaultLanguage });
+    }
+    const languages = input.languages;
+    if (!Array.isArray(languages) || languages.length === 0) {
+        throw makeValidationError('languages-required', 'Provide a non-empty "languages" array in anydocs.config.json.', { received: languages });
+    }
+    const uniqueLanguages = new Set();
+    for (const language of languages) {
+        if (!isSupportedLanguage(language)) {
+            throw makeValidationError('language-variant-invalid', `Only these languages are supported in Phase 1: ${SUPPORTED_DOCS_LANGUAGES.join(', ')}.`, { received: language });
+        }
+        uniqueLanguages.add(language);
+    }
+    if (!uniqueLanguages.has(defaultLanguage)) {
+        throw makeValidationError('default-language-must-be-enabled', 'Include the default language in the "languages" array.', { defaultLanguage, languages: [...uniqueLanguages] });
+    }
+    const site = input.site;
+    if (!isRecord(site)) {
+        throw makeValidationError('site-required', 'Provide a "site" object in anydocs.config.json.', { received: site });
+    }
+    const theme = site.theme;
+    if (!isRecord(theme)) {
+        throw makeValidationError('site-theme-required', 'Provide a "theme" object under "site" in anydocs.config.json.', { received: theme });
+    }
+    const themeId = theme.id;
+    if (typeof themeId !== 'string' || themeId.trim().length === 0) {
+        throw makeValidationError('site-theme-id-required', 'Provide a non-empty "site.theme.id" in anydocs.config.json.', { received: themeId });
+    }
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(themeId)) {
+        throw makeValidationError('site-theme-id-format', 'Use lowercase letters, numbers, and hyphens only for "site.theme.id".', { received: themeId });
+    }
+    const branding = theme.branding;
+    if (branding != null && !isRecord(branding)) {
+        throw makeValidationError('site-theme-branding-object', 'Use an object for "site.theme.branding" when specifying reader branding overrides.', { received: branding });
+    }
+    const siteTitle = branding?.siteTitle;
+    if (siteTitle != null && (typeof siteTitle !== 'string' || siteTitle.trim().length === 0)) {
+        throw makeValidationError('site-theme-branding-site-title-string', 'Use a non-empty string for "site.theme.branding.siteTitle" when overriding the reader title.', { received: siteTitle });
+    }
+    const homeLabel = branding?.homeLabel;
+    if (homeLabel != null && (typeof homeLabel !== 'string' || homeLabel.trim().length === 0)) {
+        throw makeValidationError('site-theme-branding-home-label-string', 'Use a non-empty string for "site.theme.branding.homeLabel" when overriding the footer home label.', { received: homeLabel });
+    }
+    const logoSrc = branding?.logoSrc;
+    if (logoSrc != null && (typeof logoSrc !== 'string' || logoSrc.trim().length === 0)) {
+        throw makeValidationError('site-theme-branding-logo-src-string', 'Use a non-empty string for "site.theme.branding.logoSrc" when configuring a sidebar logo URL or path.', { received: logoSrc });
+    }
+    const logoAlt = branding?.logoAlt;
+    if (logoAlt != null && (typeof logoAlt !== 'string' || logoAlt.trim().length === 0)) {
+        throw makeValidationError('site-theme-branding-logo-alt-string', 'Use a non-empty string for "site.theme.branding.logoAlt" when overriding sidebar logo alt text.', { received: logoAlt });
+    }
+    const chrome = theme.chrome;
+    if (chrome != null && !isRecord(chrome)) {
+        throw makeValidationError('site-theme-chrome-object', 'Use an object for "site.theme.chrome" when specifying reader chrome overrides.', { received: chrome });
+    }
+    const showSearch = chrome?.showSearch;
+    if (showSearch != null && typeof showSearch !== 'boolean') {
+        throw makeValidationError('site-theme-chrome-show-search-boolean', 'Use a boolean for "site.theme.chrome.showSearch" when toggling sidebar search visibility.', { received: showSearch });
+    }
+    const colors = theme.colors;
+    if (colors != null && !isRecord(colors)) {
+        throw makeValidationError('site-theme-colors-object', 'Use an object for "site.theme.colors" when specifying semantic theme color overrides.', { received: colors });
+    }
+    const colorEntries = [
+        ['primary', colors?.primary],
+        ['primaryForeground', colors?.primaryForeground],
+        ['accent', colors?.accent],
+        ['accentForeground', colors?.accentForeground],
+        ['sidebarActive', colors?.sidebarActive],
+        ['sidebarActiveForeground', colors?.sidebarActiveForeground],
+    ];
+    for (const [field, value] of colorEntries) {
+        if (value == null) {
+            continue;
+        }
+        if (typeof value !== 'string' || !isHexColor(value.trim())) {
+            throw makeValidationError(`site-theme-colors-${field}-hex`, `Use a "#RRGGBB" value for "site.theme.colors.${field}".`, { received: value });
+        }
+    }
+    const codeTheme = theme.codeTheme;
+    if (codeTheme != null && !SUPPORTED_DOCS_CODE_THEMES.includes(codeTheme)) {
+        throw makeValidationError('site-theme-code-theme-invalid', `Set "site.theme.codeTheme" to one of: ${SUPPORTED_DOCS_CODE_THEMES.join(', ')}.`, { received: codeTheme });
+    }
+    const navigation = site.navigation;
+    if (navigation != null && !isRecord(navigation)) {
+        throw makeValidationError('site-navigation-object', 'Use an object for "site.navigation" when specifying site-shell navigation settings.', { received: navigation });
+    }
+    const rawTopNav = navigation?.topNav;
+    if (rawTopNav != null && !Array.isArray(rawTopNav)) {
+        throw makeValidationError('site-navigation-top-nav-array', 'Use an array for "site.navigation.topNav" when specifying top navigation items.', { received: rawTopNav });
+    }
+    const topNav = rawTopNav?.map((item, index) => validateTopNavItem(item, index)) ?? [];
+    const topNavIds = new Set();
+    for (const item of topNav) {
+        if (topNavIds.has(item.id)) {
+            throw makeValidationError('site-navigation-top-nav-item-id-unique', 'Use unique ids for top navigation items.', { itemId: item.id });
+        }
+        topNavIds.add(item.id);
+    }
+    const build = input.build;
+    if (build != null && !isRecord(build)) {
+        throw makeValidationError('build-must-be-object', 'Use an object for "build" when specifying build options.', { received: build });
+    }
+    const outputDir = build?.outputDir;
+    if (outputDir != null && (typeof outputDir !== 'string' || outputDir.trim().length === 0)) {
+        throw makeValidationError('build-output-dir-string', 'Use a non-empty string for "build.outputDir" when overriding the output directory.', { received: outputDir });
+    }
+    return {
+        version: 1,
+        projectId,
+        name: name.trim(),
+        defaultLanguage,
+        languages: [...uniqueLanguages],
+        site: {
+            theme: {
+                id: themeId.trim(),
+                ...(branding
+                    ? {
+                        branding: {
+                            ...(typeof siteTitle === 'string' ? { siteTitle: siteTitle.trim() } : {}),
+                            ...(typeof homeLabel === 'string' ? { homeLabel: homeLabel.trim() } : {}),
+                            ...(typeof logoSrc === 'string' ? { logoSrc: logoSrc.trim() } : {}),
+                            ...(typeof logoAlt === 'string' ? { logoAlt: logoAlt.trim() } : {}),
+                        },
+                    }
+                    : {}),
+                ...(chrome
+                    ? {
+                        chrome: {
+                            ...(typeof showSearch === 'boolean' ? { showSearch } : {}),
+                        },
+                    }
+                    : {}),
+                ...(colors
+                    ? {
+                        colors: {
+                            ...(typeof colors.primary === 'string' ? { primary: colors.primary.trim() } : {}),
+                            ...(typeof colors.primaryForeground === 'string'
+                                ? { primaryForeground: colors.primaryForeground.trim() }
+                                : {}),
+                            ...(typeof colors.accent === 'string' ? { accent: colors.accent.trim() } : {}),
+                            ...(typeof colors.accentForeground === 'string'
+                                ? { accentForeground: colors.accentForeground.trim() }
+                                : {}),
+                            ...(typeof colors.sidebarActive === 'string'
+                                ? { sidebarActive: colors.sidebarActive.trim() }
+                                : {}),
+                            ...(typeof colors.sidebarActiveForeground === 'string'
+                                ? { sidebarActiveForeground: colors.sidebarActiveForeground.trim() }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                ...(typeof codeTheme === 'string' ? { codeTheme: codeTheme } : {}),
+            },
+            ...(topNav.length > 0 ? { navigation: { topNav } } : {}),
+        },
+        ...(typeof outputDir === 'string' ? { build: { outputDir: outputDir.trim() } } : {}),
+    };
+}

package/dist/services/authoring-service.d.ts

@@ -0,0 +1,137 @@
+import type { DocsLang, NavItem, NavigationDoc, PageDoc, PageRender, PageReview, PageStatus } from '../types/docs.ts';
+import type { ProjectConfig } from '../types/project.ts';
+export type CreatePageInput<TContent = unknown> = {
+    projectRoot: string;
+    lang: DocsLang;
+    page: {
+        id: string;
+        slug: string;
+        title: string;
+        description?: string;
+        tags?: string[];
+        status?: PageStatus;
+        content?: TContent;
+        render?: PageRender;
+        review?: PageReview;
+    };
+};
+export type UpdatePagePatch<TContent = unknown> = {
+    slug?: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    content?: TContent;
+    render?: PageRender;
+    review?: PageReview;
+};
+export type UpdatePageInput<TContent = unknown> = {
+    projectRoot: string;
+    lang: DocsLang;
+    pageId: string;
+    patch: UpdatePagePatch<TContent>;
+    regenerateRender?: boolean;
+};
+export type SetPageStatusInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    pageId: string;
+    status: PageStatus;
+};
+export type DeletePageInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    pageId: string;
+};
+export type BatchCreatePagesInput<TContent = unknown> = {
+    projectRoot: string;
+    lang: DocsLang;
+    pages: Array<CreatePageInput<TContent>['page']>;
+};
+export type BatchUpdatePagesInput<TContent = unknown> = {
+    projectRoot: string;
+    lang: DocsLang;
+    updates: Array<{
+        pageId: string;
+        patch: UpdatePagePatch<TContent>;
+        regenerateRender?: boolean;
+    }>;
+};
+export type BatchSetPageStatusesInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    updates: Array<{
+        pageId: string;
+        status: PageStatus;
+    }>;
+};
+export type AuthoringPageResult<TContent = unknown> = {
+    filePath: string;
+    page: PageDoc<TContent>;
+};
+export type AuthoringDeletePageResult = {
+    filePath: string;
+    pageId: string;
+    lang: DocsLang;
+    removedNavigationRefs: number;
+};
+export type AuthoringBatchPagesResult<TContent = unknown> = {
+    count: number;
+    files: string[];
+    pages: Array<PageDoc<TContent>>;
+};
+export type AuthoringNavigationResult = {
+    filePath: string;
+    navigation: NavigationDoc;
+};
+export type SetNavigationInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    navigation: NavigationDoc;
+};
+export type ReplaceNavigationItemsInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    items: NavigationDoc['items'];
+};
+export type InsertNavigationItemInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    item: NavItem;
+    parentPath?: string;
+    index?: number;
+};
+export type DeleteNavigationItemInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    itemPath: string;
+};
+export type MoveNavigationItemInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    itemPath: string;
+    parentPath?: string;
+    index?: number;
+};
+export type SetProjectLanguagesInput = {
+    projectRoot: string;
+    languages: DocsLang[];
+    defaultLanguage?: DocsLang;
+};
+export type AuthoringProjectConfigResult = {
+    filePath: string;
+    config: ProjectConfig;
+};
+export declare function createPage<TContent = unknown>(input: CreatePageInput<TContent>): Promise<AuthoringPageResult<TContent>>;
+export declare function createPagesBatch<TContent = unknown>(input: BatchCreatePagesInput<TContent>): Promise<AuthoringBatchPagesResult<TContent>>;
+export declare function updatePage<TContent = unknown>(input: UpdatePageInput<TContent>): Promise<AuthoringPageResult<TContent>>;
+export declare function updatePagesBatch<TContent = unknown>(input: BatchUpdatePagesInput<TContent>): Promise<AuthoringBatchPagesResult<TContent>>;
+export declare function setPageStatus<TContent = unknown>(input: SetPageStatusInput): Promise<AuthoringPageResult<TContent>>;
+export declare function setPageStatusesBatch<TContent = unknown>(input: BatchSetPageStatusesInput): Promise<AuthoringBatchPagesResult<TContent>>;
+export declare function deleteAuthoredPage(input: DeletePageInput): Promise<AuthoringDeletePageResult>;
+export declare function setNavigation(input: SetNavigationInput): Promise<AuthoringNavigationResult>;
+export declare function replaceNavigationItems(input: ReplaceNavigationItemsInput): Promise<AuthoringNavigationResult>;
+export declare function insertNavigationItem(input: InsertNavigationItemInput): Promise<AuthoringNavigationResult>;
+export declare function deleteNavigationItem(input: DeleteNavigationItemInput): Promise<AuthoringNavigationResult>;
+export declare function moveNavigationItem(input: MoveNavigationItemInput): Promise<AuthoringNavigationResult>;
+export declare function setProjectLanguages(input: SetProjectLanguagesInput): Promise<AuthoringProjectConfigResult>;
+//# sourceMappingURL=authoring-service.d.ts.map

package/dist/services/authoring-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-service.d.ts","sourceRoot":"","sources":["../../src/services/authoring-service.ts"],"names":[],"mappings":"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"}