@anydocs/core 1.0.0

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

@@ -0,0 +1,239 @@
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ValidationError } from "../errors/validation-error.js";
+import { loadProjectContract } from "../fs/content-repository.js";
+function createImportValidationError(message, rule, remediation, metadata) {
+    return new ValidationError(message, {
+        entity: 'legacy-import',
+        rule,
+        remediation,
+        metadata,
+    });
+}
+function normalizeImportSlug(relativePath) {
+    const withoutExtension = relativePath.replace(/\.(md|mdx)$/i, '');
+    return withoutExtension
+        .split(path.sep)
+        .join('/')
+        .split('/')
+        .map((segment) => segment
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, ''))
+        .filter(Boolean)
+        .join('/');
+}
+function inferTitle(slug, frontmatter, body) {
+    const title = frontmatter.title;
+    if (typeof title === 'string' && title.trim()) {
+        return title.trim();
+    }
+    const headingMatch = body.match(/^#\s+(.+)$/m);
+    if (headingMatch?.[1]) {
+        return headingMatch[1].trim();
+    }
+    const leaf = slug.split('/').at(-1) ?? 'untitled';
+    return leaf
+        .split('-')
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(' ');
+}
+function inferDescription(frontmatter) {
+    const description = frontmatter.description;
+    return typeof description === 'string' && description.trim() ? description.trim() : undefined;
+}
+function inferTags(frontmatter) {
+    const tags = frontmatter.tags;
+    if (Array.isArray(tags)) {
+        const normalized = tags.map((tag) => String(tag).trim()).filter(Boolean);
+        return normalized.length ? normalized : undefined;
+    }
+    if (typeof tags === 'string' && tags.trim()) {
+        return tags
+            .split(',')
+            .map((tag) => tag.trim())
+            .filter(Boolean);
+    }
+    return undefined;
+}
+function parseFrontmatter(rawContent, sourcePath) {
+    if (!rawContent.startsWith('---\n') && !rawContent.startsWith('---\r\n')) {
+        return { body: rawContent, frontmatter: {} };
+    }
+    const frontmatterMatch = rawContent.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!frontmatterMatch) {
+        throw createImportValidationError(`Legacy document "${sourcePath}" contains an unclosed frontmatter block.`, 'legacy-frontmatter-closed', 'Close the frontmatter block with a terminating --- line or remove the malformed frontmatter.', { sourcePath });
+    }
+    const rawFrontmatter = frontmatterMatch[1] ?? '';
+    const body = rawContent.slice(frontmatterMatch[0].length);
+    const frontmatter = {};
+    for (const line of rawFrontmatter.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const separatorIndex = trimmed.indexOf(':');
+        if (separatorIndex <= 0) {
+            throw createImportValidationError(`Legacy document "${sourcePath}" contains malformed frontmatter.`, 'legacy-frontmatter-key-value', 'Use simple "key: value" frontmatter lines for supported legacy imports.', { sourcePath, line: trimmed });
+        }
+        const key = trimmed.slice(0, separatorIndex).trim();
+        const value = trimmed.slice(separatorIndex + 1).trim();
+        if (!key) {
+            throw createImportValidationError(`Legacy document "${sourcePath}" contains malformed frontmatter.`, 'legacy-frontmatter-key-required', 'Provide a non-empty frontmatter key before the colon.', { sourcePath, line: trimmed });
+        }
+        if (value.startsWith('[') && value.endsWith(']')) {
+            frontmatter[key] = value
+                .slice(1, -1)
+                .split(',')
+                .map((entry) => entry.trim().replace(/^['"]|['"]$/g, ''))
+                .filter(Boolean);
+            continue;
+        }
+        frontmatter[key] = value.replace(/^['"]|['"]$/g, '');
+    }
+    return { body, frontmatter };
+}
+async function collectLegacyFiles(sourceRoot) {
+    const entries = await readdir(sourceRoot, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(sourceRoot, entry.name);
+        if (entry.isDirectory()) {
+            const nestedFiles = await collectLegacyFiles(absolutePath);
+            files.push(...nestedFiles);
+            continue;
+        }
+        const extension = path.extname(entry.name).toLowerCase();
+        if (extension !== '.md' && extension !== '.mdx') {
+            continue;
+        }
+        const rawContent = await readFile(absolutePath, 'utf8');
+        const { body, frontmatter } = parseFrontmatter(rawContent, absolutePath);
+        files.push({
+            absolutePath,
+            relativePath: absolutePath,
+            format: extension === '.mdx' ? 'mdx' : 'markdown',
+            rawContent,
+            body,
+            frontmatter,
+        });
+    }
+    return files;
+}
+function toRelativeFiles(sourceRoot, files) {
+    return files.map((file) => ({
+        ...file,
+        relativePath: path.relative(sourceRoot, file.absolutePath),
+    }));
+}
+function createItemId(relativePath, index) {
+    const base = relativePath
+        .replace(/\.(md|mdx)$/i, '')
+        .split(path.sep)
+        .join('-')
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return base || `legacy-item-${index + 1}`;
+}
+function buildImportItems(files, lang, importedAt) {
+    const seenSlugs = new Set();
+    return files.map((file, index) => {
+        const slug = normalizeImportSlug(file.relativePath);
+        if (!slug) {
+            throw createImportValidationError(`Legacy document "${file.relativePath}" could not be normalized into a slug.`, 'legacy-slug-normalized', 'Rename the source file or move it into a directory structure that produces a non-empty slug.', { sourcePath: file.relativePath });
+        }
+        if (seenSlugs.has(slug)) {
+            throw createImportValidationError(`Legacy import contains duplicate slug "${slug}".`, 'legacy-import-slug-unique', 'Rename or move the conflicting source files so each imported document has a unique slug.', { slug, sourcePath: file.relativePath });
+        }
+        seenSlugs.add(slug);
+        return {
+            id: createItemId(file.relativePath, index),
+            sourcePath: file.relativePath.split(path.sep).join('/'),
+            lang,
+            slug,
+            title: inferTitle(slug, file.frontmatter, file.body),
+            description: inferDescription(file.frontmatter),
+            tags: inferTags(file.frontmatter),
+            format: file.format,
+            importedAt,
+            rawContent: file.rawContent,
+            body: file.body,
+            frontmatter: file.frontmatter,
+            status: 'staged',
+        };
+    });
+}
+async function writeJson(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+export async function importLegacyDocumentation(options) {
+    const contractResult = await loadProjectContract(options.repoRoot, options.projectId);
+    if (!contractResult.ok) {
+        throw contractResult.error;
+    }
+    const contract = contractResult.value;
+    const lang = options.lang ?? contract.config.defaultLanguage;
+    const sourceStats = await stat(options.sourceRoot).catch(() => null);
+    if (!sourceStats?.isDirectory()) {
+        throw createImportValidationError(`Legacy source root "${options.sourceRoot}" does not exist or is not a directory.`, 'legacy-source-root-directory', 'Provide a directory containing .md or .mdx files for import.', { sourceRoot: options.sourceRoot });
+    }
+    const collectedFiles = toRelativeFiles(options.sourceRoot, await collectLegacyFiles(options.sourceRoot));
+    if (collectedFiles.length === 0) {
+        throw createImportValidationError(`Legacy source root "${options.sourceRoot}" does not contain any supported files.`, 'legacy-source-supported-files-required', 'Add at least one .md or .mdx file before invoking the import workflow.', { sourceRoot: options.sourceRoot });
+    }
+    const importedAt = new Date().toISOString();
+    const items = buildImportItems(collectedFiles, lang, importedAt);
+    const importId = `legacy-${importedAt.replace(/[:.]/g, '-').toLowerCase()}`;
+    const importRoot = path.join(contract.paths.importsRoot, importId);
+    const manifestFile = path.join(importRoot, 'manifest.json');
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'anydocs-legacy-import-'));
+    try {
+        const stagedImportRoot = path.join(tempRoot, importId);
+        const stagedItemsRoot = path.join(stagedImportRoot, 'items');
+        const manifest = {
+            version: 1,
+            importId,
+            projectId: contract.config.projectId,
+            sourceRoot: options.sourceRoot,
+            importedAt,
+            itemCount: items.length,
+            status: 'staged',
+            items: items.map((item) => ({
+                id: item.id,
+                sourcePath: item.sourcePath,
+                lang: item.lang,
+                slug: item.slug,
+                title: item.title,
+                format: item.format,
+                status: item.status,
+            })),
+        };
+        await writeJson(path.join(stagedImportRoot, 'manifest.json'), manifest);
+        for (const item of items) {
+            await writeJson(path.join(stagedItemsRoot, `${item.id}.json`), item);
+        }
+        await mkdir(contract.paths.importsRoot, { recursive: true });
+        await rename(stagedImportRoot, importRoot);
+        return {
+            importId,
+            importRoot,
+            manifestFile,
+            itemCount: items.length,
+            items: manifest.items,
+        };
+    }
+    catch (error) {
+        await rm(importRoot, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/services/page-template-service.d.ts

@@ -0,0 +1,81 @@
+import type { DocsLang, PageStatus, PageReview } from '../types/docs.ts';
+import type { AuthoringPageResult, UpdatePagePatch } from './authoring-service.ts';
+export declare const PAGE_TEMPLATE_KINDS: readonly ["concept", "how_to", "reference"];
+export type PageTemplateKind = (typeof PAGE_TEMPLATE_KINDS)[number];
+export type PageTemplateCalloutTheme = 'info' | 'warning' | 'success';
+export type PageTemplateCalloutInput = {
+    title?: string;
+    body: string;
+    theme?: PageTemplateCalloutTheme;
+};
+export type PageTemplateSectionInput = {
+    title: string;
+    body?: string;
+    items?: string[];
+    code?: string;
+    language?: string;
+    callout?: PageTemplateCalloutInput;
+};
+export type PageTemplateStepInput = {
+    title: string;
+    body?: string;
+    code?: string;
+    language?: string;
+};
+export type CreatePageFromTemplateInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    page: {
+        id: string;
+        slug: string;
+        title: string;
+        description?: string;
+        tags?: string[];
+        status?: PageStatus;
+        review?: PageReview;
+    };
+    template: PageTemplateKind;
+    summary?: string;
+    sections?: PageTemplateSectionInput[];
+    steps?: PageTemplateStepInput[];
+    callouts?: PageTemplateCalloutInput[];
+};
+export type UpdatePageFromTemplateInput = {
+    projectRoot: string;
+    lang: DocsLang;
+    pageId: string;
+    patch?: Pick<UpdatePagePatch<Record<string, unknown>>, 'slug' | 'title' | 'description' | 'tags' | 'review'>;
+    template: PageTemplateKind;
+    summary?: string;
+    sections?: PageTemplateSectionInput[];
+    steps?: PageTemplateStepInput[];
+    callouts?: PageTemplateCalloutInput[];
+};
+export declare const PAGE_TEMPLATE_DEFINITIONS: readonly [{
+    readonly id: "concept";
+    readonly label: "Concept";
+    readonly description: "Explain an idea, architecture, or mental model with sectioned prose and supporting callouts.";
+    readonly recommendedInputs: readonly ["summary", "sections"];
+}, {
+    readonly id: "how_to";
+    readonly label: "How-To";
+    readonly description: "Teach a procedure with ordered steps, optional code examples, and final guidance.";
+    readonly recommendedInputs: readonly ["summary", "steps"];
+}, {
+    readonly id: "reference";
+    readonly label: "Reference";
+    readonly description: "Capture stable facts, options, APIs, and operational details in scan-friendly sections.";
+    readonly recommendedInputs: readonly ["summary", "sections"];
+}];
+type PageTemplateComposition = {
+    content: Record<string, unknown>;
+    render: {
+        markdown: string;
+        plainText: string;
+    };
+};
+export declare function composePageFromTemplate(input: Omit<CreatePageFromTemplateInput, 'projectRoot' | 'lang' | 'page'>): PageTemplateComposition;
+export declare function createPageFromTemplate(input: CreatePageFromTemplateInput): Promise<AuthoringPageResult<Record<string, unknown>>>;
+export declare function updatePageFromTemplate(input: UpdatePageFromTemplateInput): Promise<AuthoringPageResult<Record<string, unknown>>>;
+export {};
+//# sourceMappingURL=page-template-service.d.ts.map

package/dist/services/page-template-service.d.ts.map

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

package/dist/services/page-template-service.js

@@ -0,0 +1,342 @@
+import { ValidationError } from "../errors/validation-error.js";
+import { createPage, updatePage } from "./authoring-service.js";
+export const PAGE_TEMPLATE_KINDS = ['concept', 'how_to', 'reference'];
+export const PAGE_TEMPLATE_DEFINITIONS = [
+    {
+        id: 'concept',
+        label: 'Concept',
+        description: 'Explain an idea, architecture, or mental model with sectioned prose and supporting callouts.',
+        recommendedInputs: ['summary', 'sections'],
+    },
+    {
+        id: 'how_to',
+        label: 'How-To',
+        description: 'Teach a procedure with ordered steps, optional code examples, and final guidance.',
+        recommendedInputs: ['summary', 'steps'],
+    },
+    {
+        id: 'reference',
+        label: 'Reference',
+        description: 'Capture stable facts, options, APIs, and operational details in scan-friendly sections.',
+        recommendedInputs: ['summary', 'sections'],
+    },
+];
+function normalizeText(value, key) {
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new ValidationError(`Template field "${key}" must be a string.`, {
+            entity: 'page-template',
+            rule: 'page-template-string-field',
+            remediation: `Provide "${key}" as a string or omit it.`,
+            metadata: { key, received: value },
+        });
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeStringList(values, key) {
+    if (values == null) {
+        return [];
+    }
+    if (!Array.isArray(values) || values.some((value) => typeof value !== 'string')) {
+        throw new ValidationError(`Template field "${key}" must be a string array.`, {
+            entity: 'page-template',
+            rule: 'page-template-string-array-field',
+            remediation: `Provide "${key}" as an array of non-empty strings.`,
+            metadata: { key, received: values },
+        });
+    }
+    return values.map((value) => value.trim()).filter(Boolean);
+}
+function normalizeCallout(value, key) {
+    const body = normalizeText(value.body, `${key}.body`);
+    if (!body) {
+        throw new ValidationError(`Template callout "${key}" must include body text.`, {
+            entity: 'page-template',
+            rule: 'page-template-callout-body-required',
+            remediation: 'Provide a non-empty callout body.',
+            metadata: { key },
+        });
+    }
+    return {
+        body,
+        ...(normalizeText(value.title, `${key}.title`) ? { title: normalizeText(value.title, `${key}.title`) } : {}),
+        ...(value.theme ? { theme: value.theme } : {}),
+    };
+}
+function normalizeSections(sections) {
+    if (sections == null) {
+        return [];
+    }
+    if (!Array.isArray(sections)) {
+        throw new ValidationError('Template field "sections" must be an array.', {
+            entity: 'page-template',
+            rule: 'page-template-sections-array',
+            remediation: 'Provide "sections" as an array of structured section objects.',
+            metadata: { received: sections },
+        });
+    }
+    return sections.map((section, index) => {
+        const title = normalizeText(section.title, `sections[${index}].title`);
+        const body = normalizeText(section.body, `sections[${index}].body`);
+        const items = normalizeStringList(section.items, `sections[${index}].items`);
+        const code = normalizeText(section.code, `sections[${index}].code`);
+        const language = normalizeText(section.language, `sections[${index}].language`);
+        const callout = section.callout ? normalizeCallout(section.callout, `sections[${index}].callout`) : undefined;
+        if (!title) {
+            throw new ValidationError(`Template section ${index + 1} must include a title.`, {
+                entity: 'page-template',
+                rule: 'page-template-section-title-required',
+                remediation: 'Provide a non-empty section title.',
+                metadata: { index },
+            });
+        }
+        if (!body && items.length === 0 && !code && !callout) {
+            throw new ValidationError(`Template section "${title}" has no content.`, {
+                entity: 'page-template',
+                rule: 'page-template-section-content-required',
+                remediation: 'Provide body, items, code, or a callout for each section.',
+                metadata: { index, title },
+            });
+        }
+        return {
+            title,
+            ...(body ? { body } : {}),
+            ...(items.length > 0 ? { items } : {}),
+            ...(code ? { code } : {}),
+            ...(language ? { language } : {}),
+            ...(callout ? { callout } : {}),
+        };
+    });
+}
+function normalizeSteps(steps) {
+    if (steps == null) {
+        return [];
+    }
+    if (!Array.isArray(steps)) {
+        throw new ValidationError('Template field "steps" must be an array.', {
+            entity: 'page-template',
+            rule: 'page-template-steps-array',
+            remediation: 'Provide "steps" as an array of structured step objects.',
+            metadata: { received: steps },
+        });
+    }
+    return steps.map((step, index) => {
+        const title = normalizeText(step.title, `steps[${index}].title`);
+        const body = normalizeText(step.body, `steps[${index}].body`);
+        const code = normalizeText(step.code, `steps[${index}].code`);
+        const language = normalizeText(step.language, `steps[${index}].language`);
+        if (!title) {
+            throw new ValidationError(`Template step ${index + 1} must include a title.`, {
+                entity: 'page-template',
+                rule: 'page-template-step-title-required',
+                remediation: 'Provide a non-empty step title.',
+                metadata: { index },
+            });
+        }
+        if (!body && !code) {
+            throw new ValidationError(`Template step "${title}" has no content.`, {
+                entity: 'page-template',
+                rule: 'page-template-step-content-required',
+                remediation: 'Provide step body text or code.',
+                metadata: { index, title },
+            });
+        }
+        return {
+            title,
+            ...(body ? { body } : {}),
+            ...(code ? { code } : {}),
+            ...(language ? { language } : {}),
+        };
+    });
+}
+class YooptaTemplateBuilder {
+    constructor() {
+        this.content = {};
+        this.markdownBlocks = [];
+        this.plainTextBlocks = [];
+        this.blockOrder = 0;
+        this.idCounter = 1;
+    }
+    paragraph(text) {
+        const normalized = text.trim();
+        if (!normalized)
+            return;
+        this.pushBlock('Paragraph', 'paragraph', [{ text: normalized }], { nodeType: 'block' });
+        this.markdownBlocks.push(normalized);
+        this.plainTextBlocks.push(normalized);
+    }
+    heading(level, text) {
+        const normalized = text.trim();
+        if (!normalized)
+            return;
+        const type = level === 2 ? 'HeadingTwo' : 'HeadingThree';
+        const elementType = level === 2 ? 'heading-two' : 'heading-three';
+        this.pushBlock(type, elementType, [{ text: normalized }], { nodeType: 'block' });
+        this.markdownBlocks.push(`${'#'.repeat(level)} ${normalized}`);
+        this.plainTextBlocks.push(normalized);
+    }
+    bulletedList(items) {
+        for (const item of items.map((value) => value.trim()).filter(Boolean)) {
+            this.pushBlock('BulletedList', 'bulleted-list', [{ text: item }], { nodeType: 'block' });
+            this.markdownBlocks.push(`- ${item}`);
+            this.plainTextBlocks.push(item);
+        }
+    }
+    numberedList(items) {
+        items
+            .map((value) => value.trim())
+            .filter(Boolean)
+            .forEach((item, index) => {
+            this.pushBlock('NumberedList', 'numbered-list', [{ text: item }], { nodeType: 'block' });
+            this.markdownBlocks.push(`${index + 1}. ${item}`);
+            this.plainTextBlocks.push(item);
+        });
+    }
+    code(code, language) {
+        const normalized = code.trim();
+        if (!normalized)
+            return;
+        this.pushBlock('Code', 'code', [{ text: normalized }], {
+            nodeType: 'void',
+            ...(language ? { language } : {}),
+        });
+        this.markdownBlocks.push(`\`\`\`${language ?? ''}\n${normalized}\n\`\`\``);
+        this.plainTextBlocks.push(normalized);
+    }
+    callout(callout) {
+        const parts = [callout.title?.trim(), callout.body.trim()].filter(Boolean);
+        const text = parts.join(': ');
+        if (!text)
+            return;
+        this.pushBlock('Callout', 'callout', [{ text }], {
+            nodeType: 'block',
+            theme: callout.theme ?? 'info',
+        });
+        this.markdownBlocks.push(`> ${text}`);
+        this.plainTextBlocks.push(text);
+    }
+    build() {
+        return {
+            content: this.content,
+            render: {
+                markdown: this.markdownBlocks.join('\n\n'),
+                plainText: this.plainTextBlocks.join('\n\n'),
+            },
+        };
+    }
+    nextId(prefix) {
+        const value = `${prefix}-${this.idCounter}`;
+        this.idCounter += 1;
+        return value;
+    }
+    pushBlock(type, elementType, children, props) {
+        const blockId = this.nextId('block');
+        const elementId = this.nextId('element');
+        this.content[blockId] = {
+            id: blockId,
+            type,
+            value: [
+                {
+                    id: elementId,
+                    type: elementType,
+                    children,
+                    props,
+                },
+            ],
+            meta: { order: this.blockOrder, depth: 0 },
+        };
+        this.blockOrder += 1;
+    }
+}
+export function composePageFromTemplate(input) {
+    const summary = normalizeText(input.summary, 'summary');
+    const sections = normalizeSections(input.sections);
+    const steps = normalizeSteps(input.steps);
+    const callouts = (input.callouts ?? []).map((callout, index) => normalizeCallout(callout, `callouts[${index}]`));
+    if (input.template === 'how_to' && steps.length === 0) {
+        throw new ValidationError('Template "how_to" requires at least one step.', {
+            entity: 'page-template',
+            rule: 'page-template-how-to-steps-required',
+            remediation: 'Provide at least one structured step when using the "how_to" template.',
+            metadata: { template: input.template },
+        });
+    }
+    if (!summary && sections.length === 0 && steps.length === 0 && callouts.length === 0) {
+        throw new ValidationError(`Template "${input.template}" has no content to compose.`, {
+            entity: 'page-template',
+            rule: 'page-template-content-required',
+            remediation: 'Provide summary, sections, steps, or callouts when creating a templated page.',
+            metadata: { template: input.template },
+        });
+    }
+    const builder = new YooptaTemplateBuilder();
+    if (summary) {
+        builder.paragraph(summary);
+    }
+    if (input.template === 'how_to' && steps.length > 0) {
+        builder.heading(2, 'Steps');
+        builder.numberedList(steps.map((step) => step.title));
+        for (const step of steps) {
+            builder.heading(3, step.title);
+            if (step.body)
+                builder.paragraph(step.body);
+            if (step.code)
+                builder.code(step.code, step.language);
+        }
+    }
+    for (const section of sections) {
+        builder.heading(2, section.title);
+        if (section.body)
+            builder.paragraph(section.body);
+        if (section.items)
+            builder.bulletedList(section.items);
+        if (section.code)
+            builder.code(section.code, section.language);
+        if (section.callout)
+            builder.callout(section.callout);
+    }
+    for (const callout of callouts) {
+        builder.callout(callout);
+    }
+    return builder.build();
+}
+export async function createPageFromTemplate(input) {
+    const composition = composePageFromTemplate({
+        template: input.template,
+        summary: input.summary,
+        sections: input.sections,
+        steps: input.steps,
+        callouts: input.callouts,
+    });
+    return createPage({
+        projectRoot: input.projectRoot,
+        lang: input.lang,
+        page: {
+            ...input.page,
+            content: composition.content,
+            render: composition.render,
+        },
+    });
+}
+export async function updatePageFromTemplate(input) {
+    const composition = composePageFromTemplate({
+        template: input.template,
+        summary: input.summary,
+        sections: input.sections,
+        steps: input.steps,
+        callouts: input.callouts,
+    });
+    return updatePage({
+        projectRoot: input.projectRoot,
+        lang: input.lang,
+        pageId: input.pageId,
+        patch: {
+            ...(input.patch ?? {}),
+            content: composition.content,
+            render: composition.render,
+        },
+    });
+}