@valkyrianlabs/payload-markdown-docs 0.1.0-canary.0

package/dist/sync/frontmatter.js

@@ -0,0 +1,210 @@
+import { normalizeDocsPath } from './paths.js';
+const knownFrontmatterFields = new Set([
+    'description',
+    'draft',
+    'navTitle',
+    'order',
+    'redirectFrom',
+    'slug',
+    'status',
+    'tags',
+    'title'
+]);
+const arrayFrontmatterFields = new Set([
+    'redirectFrom',
+    'tags'
+]);
+const stripQuotes = (value)=>{
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+};
+const createFrontmatterIssue = ({ message, path })=>({
+        code: 'invalid_frontmatter',
+        message,
+        path
+    });
+const isFrontmatterKey = (value)=>{
+    const firstCharacter = value.charCodeAt(0);
+    const startsWithLetter = firstCharacter >= 65 && firstCharacter <= 90 || firstCharacter >= 97 && firstCharacter <= 122;
+    if (!startsWithLetter) {
+        return false;
+    }
+    return [
+        ...value
+    ].every((character)=>{
+        const code = character.charCodeAt(0);
+        return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122;
+    });
+};
+const assignFrontmatterValue = ({ frontmatter, key, path, rawValue })=>{
+    const value = stripQuotes(rawValue);
+    switch(key){
+        case 'description':
+        case 'navTitle':
+        case 'slug':
+        case 'title':
+            frontmatter[key] = value;
+            return undefined;
+        case 'draft':
+            if (value === 'true' || value === 'false') {
+                frontmatter.draft = value === 'true';
+                return undefined;
+            }
+            return createFrontmatterIssue({
+                message: 'Frontmatter field "draft" must be a boolean.',
+                path
+            });
+        case 'order':
+            {
+                const order = Number(value);
+                if (Number.isFinite(order)) {
+                    frontmatter.order = order;
+                    return undefined;
+                }
+                return createFrontmatterIssue({
+                    message: 'Frontmatter field "order" must be a number.',
+                    path
+                });
+            }
+        case 'status':
+            if (value === 'draft' || value === 'published') {
+                frontmatter.status = value;
+                return undefined;
+            }
+            return createFrontmatterIssue({
+                message: 'Frontmatter field "status" must be "draft" or "published".',
+                path
+            });
+        default:
+            return undefined;
+    }
+};
+const validateParsedFrontmatter = (frontmatter, path)=>{
+    const issues = [];
+    if (frontmatter.slug && !/^[a-z0-9][a-z0-9-]*$/i.test(frontmatter.slug)) {
+        issues.push(createFrontmatterIssue({
+            message: 'Frontmatter field "slug" must contain only letters, numbers, and hyphens.',
+            path
+        }));
+    }
+    return issues;
+};
+export const parseDocsFrontmatter = (markdown, options = {})=>{
+    const issues = [];
+    const warnings = [];
+    if (!markdown.startsWith('---\n') && !markdown.startsWith('---\r\n')) {
+        return {
+            content: markdown,
+            frontmatter: {},
+            issues,
+            warnings
+        };
+    }
+    const lines = markdown.split(/\r?\n/);
+    const closingIndex = lines.findIndex((line, index)=>index > 0 && line.trim() === '---');
+    if (closingIndex === -1) {
+        return {
+            content: markdown,
+            frontmatter: {},
+            issues: [
+                createFrontmatterIssue({
+                    message: 'Frontmatter block is missing a closing delimiter.',
+                    path: options.path
+                })
+            ],
+            warnings
+        };
+    }
+    const frontmatter = {};
+    const frontmatterLines = lines.slice(1, closingIndex);
+    let currentArrayKey;
+    for (const line of frontmatterLines){
+        if (line.trim() === '') {
+            continue;
+        }
+        const trimmedStart = line.trimStart();
+        if (trimmedStart.startsWith('- ')) {
+            if (!currentArrayKey) {
+                issues.push(createFrontmatterIssue({
+                    message: 'Frontmatter array item does not belong to a supported array field.',
+                    path: options.path
+                }));
+                continue;
+            }
+            frontmatter[currentArrayKey] = [
+                ...frontmatter[currentArrayKey] ?? [],
+                stripQuotes(trimmedStart.slice(2))
+            ];
+            continue;
+        }
+        const separatorIndex = line.indexOf(':');
+        const key = separatorIndex > 0 ? line.slice(0, separatorIndex).trim() : '';
+        const rawValue = separatorIndex > 0 ? line.slice(separatorIndex + 1).trim() : '';
+        if (!isFrontmatterKey(key)) {
+            issues.push(createFrontmatterIssue({
+                message: `Unsupported frontmatter line: ${line}`,
+                path: options.path
+            }));
+            currentArrayKey = undefined;
+            continue;
+        }
+        currentArrayKey = undefined;
+        if (!knownFrontmatterFields.has(key)) {
+            warnings.push({
+                code: 'invalid_frontmatter',
+                message: `Unknown frontmatter field "${key}" was ignored.`,
+                path: options.path
+            });
+            continue;
+        }
+        if (arrayFrontmatterFields.has(key)) {
+            if (rawValue.trim() !== '') {
+                issues.push(createFrontmatterIssue({
+                    message: `Frontmatter field "${key}" must use list item syntax.`,
+                    path: options.path
+                }));
+                continue;
+            }
+            currentArrayKey = key;
+            frontmatter[currentArrayKey] = [];
+            continue;
+        }
+        const issue = assignFrontmatterValue({
+            frontmatter,
+            key,
+            path: options.path,
+            rawValue
+        });
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    issues.push(...validateParsedFrontmatter(frontmatter, options.path));
+    return {
+        content: lines.slice(closingIndex + 1).join('\n').replace(/^\n/, ''),
+        frontmatter,
+        issues,
+        warnings
+    };
+};
+export const inferTitleFromMarkdown = (content)=>{
+    const h1Line = content.split(/\r?\n/).find((line)=>/^#\s+[^#]/.test(line.trim()));
+    return h1Line?.replace(/^#\s+/, '').replace(/\s+#*$/, '').trim() || undefined;
+};
+export const titleFromSourcePath = (sourcePath)=>{
+    const normalizedPath = normalizeDocsPath(sourcePath);
+    if (!normalizedPath.ok) {
+        return 'Untitled';
+    }
+    const pathSegments = normalizedPath.path.split('/');
+    const lastSegment = pathSegments.at(-1) ?? 'index.md';
+    const baseName = lastSegment === 'index.md' ? pathSegments.at(-2) ?? 'index' : lastSegment;
+    const withoutExtension = baseName.replace(/\.md$/, '');
+    return withoutExtension.split(/[-_\s]+/).filter(Boolean).map((part)=>`${part.charAt(0).toUpperCase()}${part.slice(1)}`).join(' ');
+};
+export const resolveDocsTitle = ({ content, frontmatter, sourcePath })=>frontmatter.title ?? inferTitleFromMarkdown(content) ?? titleFromSourcePath(sourcePath);
+
+//# sourceMappingURL=frontmatter.js.map

package/dist/sync/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/frontmatter.ts"],"sourcesContent":["import type { DocsValidationIssue } from './validate.js'\n\nimport { normalizeDocsPath } from './paths.js'\n\nexport type DocsFrontmatter = {\n  description?: string\n  draft?: boolean\n  navTitle?: string\n  order?: number\n  redirectFrom?: string[]\n  slug?: string\n  status?: 'draft' | 'published'\n  tags?: string[]\n  title?: string\n}\n\nexport type ParseDocsFrontmatterResult = {\n  content: string\n  frontmatter: DocsFrontmatter\n  issues: DocsValidationIssue[]\n  warnings: DocsValidationIssue[]\n}\n\nconst knownFrontmatterFields = new Set([\n  'description',\n  'draft',\n  'navTitle',\n  'order',\n  'redirectFrom',\n  'slug',\n  'status',\n  'tags',\n  'title',\n])\n\nconst arrayFrontmatterFields = new Set(['redirectFrom', 'tags'])\n\nconst stripQuotes = (value: string): string => {\n  const trimmed = value.trim()\n\n  if (\n    (trimmed.startsWith('\"') && trimmed.endsWith('\"')) ||\n    (trimmed.startsWith(\"'\") && trimmed.endsWith(\"'\"))\n  ) {\n    return trimmed.slice(1, -1)\n  }\n\n  return trimmed\n}\n\nconst createFrontmatterIssue = ({\n  message,\n  path,\n}: {\n  message: string\n  path?: string\n}): DocsValidationIssue => ({\n  code: 'invalid_frontmatter',\n  message,\n  path,\n})\n\nconst isFrontmatterKey = (value: string): boolean => {\n  const firstCharacter = value.charCodeAt(0)\n  const startsWithLetter =\n    (firstCharacter >= 65 && firstCharacter <= 90) ||\n    (firstCharacter >= 97 && firstCharacter <= 122)\n\n  if (!startsWithLetter) {\n    return false\n  }\n\n  return [...value].every((character) => {\n    const code = character.charCodeAt(0)\n\n    return (\n      (code >= 48 && code <= 57) ||\n      (code >= 65 && code <= 90) ||\n      (code >= 97 && code <= 122)\n    )\n  })\n}\n\nconst assignFrontmatterValue = ({\n  frontmatter,\n  key,\n  path,\n  rawValue,\n}: {\n  frontmatter: DocsFrontmatter\n  key: string\n  path?: string\n  rawValue: string\n}): DocsValidationIssue | undefined => {\n  const value = stripQuotes(rawValue)\n\n  switch (key) {\n    case 'description':\n    case 'navTitle':\n    case 'slug':\n    case 'title':\n      frontmatter[key] = value\n      return undefined\n\n    case 'draft':\n      if (value === 'true' || value === 'false') {\n        frontmatter.draft = value === 'true'\n        return undefined\n      }\n\n      return createFrontmatterIssue({\n        message: 'Frontmatter field \"draft\" must be a boolean.',\n        path,\n      })\n\n    case 'order': {\n      const order = Number(value)\n\n      if (Number.isFinite(order)) {\n        frontmatter.order = order\n        return undefined\n      }\n\n      return createFrontmatterIssue({\n        message: 'Frontmatter field \"order\" must be a number.',\n        path,\n      })\n    }\n\n    case 'status':\n      if (value === 'draft' || value === 'published') {\n        frontmatter.status = value\n        return undefined\n      }\n\n      return createFrontmatterIssue({\n        message: 'Frontmatter field \"status\" must be \"draft\" or \"published\".',\n        path,\n      })\n\n    default:\n      return undefined\n  }\n}\n\nconst validateParsedFrontmatter = (\n  frontmatter: DocsFrontmatter,\n  path?: string,\n): DocsValidationIssue[] => {\n  const issues: DocsValidationIssue[] = []\n\n  if (frontmatter.slug && !/^[a-z0-9][a-z0-9-]*$/i.test(frontmatter.slug)) {\n    issues.push(\n      createFrontmatterIssue({\n        message:\n          'Frontmatter field \"slug\" must contain only letters, numbers, and hyphens.',\n        path,\n      }),\n    )\n  }\n\n  return issues\n}\n\nexport const parseDocsFrontmatter = (\n  markdown: string,\n  options: {\n    path?: string\n  } = {},\n): ParseDocsFrontmatterResult => {\n  const issues: DocsValidationIssue[] = []\n  const warnings: DocsValidationIssue[] = []\n\n  if (!markdown.startsWith('---\\n') && !markdown.startsWith('---\\r\\n')) {\n    return {\n      content: markdown,\n      frontmatter: {},\n      issues,\n      warnings,\n    }\n  }\n\n  const lines = markdown.split(/\\r?\\n/)\n  const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === '---')\n\n  if (closingIndex === -1) {\n    return {\n      content: markdown,\n      frontmatter: {},\n      issues: [\n        createFrontmatterIssue({\n          message: 'Frontmatter block is missing a closing delimiter.',\n          path: options.path,\n        }),\n      ],\n      warnings,\n    }\n  }\n\n  const frontmatter: DocsFrontmatter = {}\n  const frontmatterLines = lines.slice(1, closingIndex)\n  let currentArrayKey: 'redirectFrom' | 'tags' | undefined\n\n  for (const line of frontmatterLines) {\n    if (line.trim() === '') {\n      continue\n    }\n\n    const trimmedStart = line.trimStart()\n\n    if (trimmedStart.startsWith('- ')) {\n      if (!currentArrayKey) {\n        issues.push(\n          createFrontmatterIssue({\n            message: 'Frontmatter array item does not belong to a supported array field.',\n            path: options.path,\n          }),\n        )\n        continue\n      }\n\n      frontmatter[currentArrayKey] = [\n        ...(frontmatter[currentArrayKey] ?? []),\n        stripQuotes(trimmedStart.slice(2)),\n      ]\n      continue\n    }\n\n    const separatorIndex = line.indexOf(':')\n    const key = separatorIndex > 0 ? line.slice(0, separatorIndex).trim() : ''\n    const rawValue = separatorIndex > 0 ? line.slice(separatorIndex + 1).trim() : ''\n\n    if (!isFrontmatterKey(key)) {\n      issues.push(\n        createFrontmatterIssue({\n          message: `Unsupported frontmatter line: ${line}`,\n          path: options.path,\n        }),\n      )\n      currentArrayKey = undefined\n      continue\n    }\n\n    currentArrayKey = undefined\n\n    if (!knownFrontmatterFields.has(key)) {\n      warnings.push({\n        code: 'invalid_frontmatter',\n        message: `Unknown frontmatter field \"${key}\" was ignored.`,\n        path: options.path,\n      })\n      continue\n    }\n\n    if (arrayFrontmatterFields.has(key)) {\n      if (rawValue.trim() !== '') {\n        issues.push(\n          createFrontmatterIssue({\n            message: `Frontmatter field \"${key}\" must use list item syntax.`,\n            path: options.path,\n          }),\n        )\n        continue\n      }\n\n      currentArrayKey = key as 'redirectFrom' | 'tags'\n      frontmatter[currentArrayKey] = []\n      continue\n    }\n\n    const issue = assignFrontmatterValue({\n      frontmatter,\n      key,\n      path: options.path,\n      rawValue,\n    })\n\n    if (issue) {\n      issues.push(issue)\n    }\n  }\n\n  issues.push(...validateParsedFrontmatter(frontmatter, options.path))\n\n  return {\n    content: lines.slice(closingIndex + 1).join('\\n').replace(/^\\n/, ''),\n    frontmatter,\n    issues,\n    warnings,\n  }\n}\n\nexport const inferTitleFromMarkdown = (content: string): string | undefined => {\n  const h1Line = content\n    .split(/\\r?\\n/)\n    .find((line) => /^#\\s+[^#]/.test(line.trim()))\n\n  return h1Line?.replace(/^#\\s+/, '').replace(/\\s+#*$/, '').trim() || undefined\n}\n\nexport const titleFromSourcePath = (sourcePath: string): string => {\n  const normalizedPath = normalizeDocsPath(sourcePath)\n\n  if (!normalizedPath.ok) {\n    return 'Untitled'\n  }\n\n  const pathSegments = normalizedPath.path.split('/')\n  const lastSegment = pathSegments.at(-1) ?? 'index.md'\n  const baseName = lastSegment === 'index.md' ? pathSegments.at(-2) ?? 'index' : lastSegment\n  const withoutExtension = baseName.replace(/\\.md$/, '')\n\n  return withoutExtension\n    .split(/[-_\\s]+/)\n    .filter(Boolean)\n    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)\n    .join(' ')\n}\n\nexport const resolveDocsTitle = ({\n  content,\n  frontmatter,\n  sourcePath,\n}: {\n  content: string\n  frontmatter: DocsFrontmatter\n  sourcePath: string\n}): string =>\n  frontmatter.title ?? inferTitleFromMarkdown(content) ?? titleFromSourcePath(sourcePath)\n"],"names":["normalizeDocsPath","knownFrontmatterFields","Set","arrayFrontmatterFields","stripQuotes","value","trimmed","trim","startsWith","endsWith","slice","createFrontmatterIssue","message","path","code","isFrontmatterKey","firstCharacter","charCodeAt","startsWithLetter","every","character","assignFrontmatterValue","frontmatter","key","rawValue","undefined","draft","order","Number","isFinite","status","validateParsedFrontmatter","issues","slug","test","push","parseDocsFrontmatter","markdown","options","warnings","content","lines","split","closingIndex","findIndex","line","index","frontmatterLines","currentArrayKey","trimmedStart","trimStart","separatorIndex","indexOf","has","issue","join","replace","inferTitleFromMarkdown","h1Line","find","titleFromSourcePath","sourcePath","normalizedPath","ok","pathSegments","lastSegment","at","baseName","withoutExtension","filter","Boolean","map","part","charAt","toUpperCase","resolveDocsTitle","title"],"mappings":"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"}

package/dist/sync/hash.d.ts

@@ -0,0 +1 @@
+export declare const sha256Hex: (content: string | Uint8Array) => string;

package/dist/sync/hash.js

@@ -0,0 +1,8 @@
+import { createHash } from 'node:crypto';
+export const sha256Hex = (content)=>{
+    const hash = createHash('sha256');
+    hash.update(content);
+    return hash.digest('hex');
+};
+
+//# sourceMappingURL=hash.js.map

package/dist/sync/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/hash.ts"],"sourcesContent":["import { createHash } from 'node:crypto'\n\nexport const sha256Hex = (content: string | Uint8Array): string => {\n  const hash = createHash('sha256')\n\n  hash.update(content)\n\n  return hash.digest('hex')\n}\n"],"names":["createHash","sha256Hex","content","hash","update","digest"],"mappings":"AAAA,SAASA,UAAU,QAAQ,cAAa;AAExC,OAAO,MAAMC,YAAY,CAACC;IACxB,MAAMC,OAAOH,WAAW;IAExBG,KAAKC,MAAM,CAACF;IAEZ,OAAOC,KAAKE,MAAM,CAAC;AACrB,EAAC"}

package/dist/sync/index.d.ts

@@ -0,0 +1,12 @@
+export { AI_MARKDOWN_EXPORT_MANIFEST_FILENAMES, isAiMarkdownExportManifestPath, isExcludedFromAiExport, matchesAiExportExcludePattern, parseDocsAiExportManifestYaml, validateDocsAiExportManifest, } from './aiExportManifest.js';
+export type { DocsAiExportHeadingMode, DocsAiExportManifest, DocsAiExportManifestInput, DocsAiExportManifestValidationOptions, DocsAiExportManifestValidationResult, DocsAiExportOrphans, } from './aiExportManifest.js';
+export { inferTitleFromMarkdown, parseDocsFrontmatter, resolveDocsTitle, titleFromSourcePath, } from './frontmatter.js';
+export type { DocsFrontmatter, ParseDocsFrontmatterResult, } from './frontmatter.js';
+export { sha256Hex } from './hash.js';
+export { buildDocsManifest } from './manifest.js';
+export type { DocsDeleteBehavior, DocsManifest, DocsManifestFile, DocsManifestInputFile, DocsManifestSource, DocsSyncMode, ValidatedDocsManifest, ValidatedDocsManifestFile, } from './manifest.js';
+export { deriveRouteFromSourcePath, normalizeDocsPath } from './paths.js';
+export { planDocsSync } from './plan.js';
+export type { DocsSyncPlan, ExistingDocsRecord, PlannedDocChange, } from './plan.js';
+export { validateDocsManifest } from './validate.js';
+export type { DocsValidationErrorCode, DocsValidationIssue, DocsValidationOptions, DocsValidationResult, } from './validate.js';

package/dist/sync/index.js

@@ -0,0 +1,9 @@
+export { AI_MARKDOWN_EXPORT_MANIFEST_FILENAMES, isAiMarkdownExportManifestPath, isExcludedFromAiExport, matchesAiExportExcludePattern, parseDocsAiExportManifestYaml, validateDocsAiExportManifest } from './aiExportManifest.js';
+export { inferTitleFromMarkdown, parseDocsFrontmatter, resolveDocsTitle, titleFromSourcePath } from './frontmatter.js';
+export { sha256Hex } from './hash.js';
+export { buildDocsManifest } from './manifest.js';
+export { deriveRouteFromSourcePath, normalizeDocsPath } from './paths.js';
+export { planDocsSync } from './plan.js';
+export { validateDocsManifest } from './validate.js';
+
+//# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/index.ts"],"sourcesContent":["export {\n  AI_MARKDOWN_EXPORT_MANIFEST_FILENAMES,\n  isAiMarkdownExportManifestPath,\n  isExcludedFromAiExport,\n  matchesAiExportExcludePattern,\n  parseDocsAiExportManifestYaml,\n  validateDocsAiExportManifest,\n} from './aiExportManifest.js'\nexport type {\n  DocsAiExportHeadingMode,\n  DocsAiExportManifest,\n  DocsAiExportManifestInput,\n  DocsAiExportManifestValidationOptions,\n  DocsAiExportManifestValidationResult,\n  DocsAiExportOrphans,\n} from './aiExportManifest.js'\nexport {\n  inferTitleFromMarkdown,\n  parseDocsFrontmatter,\n  resolveDocsTitle,\n  titleFromSourcePath,\n} from './frontmatter.js'\nexport type {\n  DocsFrontmatter,\n  ParseDocsFrontmatterResult,\n} from './frontmatter.js'\nexport { sha256Hex } from './hash.js'\nexport { buildDocsManifest } from './manifest.js'\nexport type {\n  DocsDeleteBehavior,\n  DocsManifest,\n  DocsManifestFile,\n  DocsManifestInputFile,\n  DocsManifestSource,\n  DocsSyncMode,\n  ValidatedDocsManifest,\n  ValidatedDocsManifestFile,\n} from './manifest.js'\nexport { deriveRouteFromSourcePath, normalizeDocsPath } from './paths.js'\nexport { planDocsSync } from './plan.js'\nexport type {\n  DocsSyncPlan,\n  ExistingDocsRecord,\n  PlannedDocChange,\n} from './plan.js'\nexport { validateDocsManifest } from './validate.js'\nexport type {\n  DocsValidationErrorCode,\n  DocsValidationIssue,\n  DocsValidationOptions,\n  DocsValidationResult,\n} from './validate.js'\n"],"names":["AI_MARKDOWN_EXPORT_MANIFEST_FILENAMES","isAiMarkdownExportManifestPath","isExcludedFromAiExport","matchesAiExportExcludePattern","parseDocsAiExportManifestYaml","validateDocsAiExportManifest","inferTitleFromMarkdown","parseDocsFrontmatter","resolveDocsTitle","titleFromSourcePath","sha256Hex","buildDocsManifest","deriveRouteFromSourcePath","normalizeDocsPath","planDocsSync","validateDocsManifest"],"mappings":"AAAA,SACEA,qCAAqC,EACrCC,8BAA8B,EAC9BC,sBAAsB,EACtBC,6BAA6B,EAC7BC,6BAA6B,EAC7BC,4BAA4B,QACvB,wBAAuB;AAS9B,SACEC,sBAAsB,EACtBC,oBAAoB,EACpBC,gBAAgB,EAChBC,mBAAmB,QACd,mBAAkB;AAKzB,SAASC,SAAS,QAAQ,YAAW;AACrC,SAASC,iBAAiB,QAAQ,gBAAe;AAWjD,SAASC,yBAAyB,EAAEC,iBAAiB,QAAQ,aAAY;AACzE,SAASC,YAAY,QAAQ,YAAW;AAMxC,SAASC,oBAAoB,QAAQ,gBAAe"}

package/dist/sync/manifest.d.ts

@@ -0,0 +1,58 @@
+import type { DocsAiExportManifest } from './aiExportManifest.js';
+import type { DocsFrontmatter } from './frontmatter.js';
+export type DocsSyncMode = 'dry-run' | 'sync';
+export type DocsDeleteBehavior = 'archive' | 'delete' | 'draft' | 'ignore';
+export type DocsManifestSource = {
+    branch?: string;
+    commit?: string;
+    id: string;
+    repository?: string;
+    root?: string;
+};
+export type DocsManifestFile = {
+    content: string;
+    path: string;
+    sha256?: string;
+};
+export type DocsManifest = {
+    aiExport?: DocsAiExportManifest;
+    deleteBehavior?: DocsDeleteBehavior;
+    files: DocsManifestFile[];
+    mode?: DocsSyncMode;
+    publish?: boolean;
+    source: DocsManifestSource;
+    version: 1;
+};
+export type ValidatedDocsManifestFile = {
+    content: string;
+    frontmatter: DocsFrontmatter;
+    path: string;
+    route: string;
+    sha256: string;
+    title: string;
+};
+export type ValidatedDocsManifest = {
+    aiExport?: DocsAiExportManifest;
+    deleteBehavior: DocsDeleteBehavior;
+    files: ValidatedDocsManifestFile[];
+    mode: DocsSyncMode;
+    publish: boolean;
+    source: DocsManifestSource;
+    version: 1;
+};
+export type DocsManifestInputFile = {
+    content: string;
+    path: string;
+};
+export declare const buildDocsManifest: ({ aiExport, branch, commit, deleteBehavior, files, mode, publish, repository, root, sourceId, }: {
+    aiExport?: DocsAiExportManifest;
+    branch?: string;
+    commit?: string;
+    deleteBehavior?: DocsDeleteBehavior;
+    files: DocsManifestInputFile[];
+    mode?: DocsSyncMode;
+    publish?: boolean;
+    repository?: string;
+    root?: string;
+    sourceId: string;
+}) => DocsManifest;

package/dist/sync/manifest.js

@@ -0,0 +1,21 @@
+import { sha256Hex } from './hash.js';
+export const buildDocsManifest = ({ aiExport, branch, commit, deleteBehavior, files, mode, publish, repository, root, sourceId })=>({
+        aiExport,
+        deleteBehavior,
+        files: files.map((file)=>({
+                ...file,
+                sha256: sha256Hex(file.content)
+            })),
+        mode,
+        publish,
+        source: {
+            id: sourceId,
+            branch,
+            commit,
+            repository,
+            root
+        },
+        version: 1
+    });
+
+//# sourceMappingURL=manifest.js.map

package/dist/sync/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/manifest.ts"],"sourcesContent":["import type { DocsAiExportManifest } from './aiExportManifest.js'\nimport type { DocsFrontmatter } from './frontmatter.js'\n\nimport { sha256Hex } from './hash.js'\n\nexport type DocsSyncMode = 'dry-run' | 'sync'\n\nexport type DocsDeleteBehavior = 'archive' | 'delete' | 'draft' | 'ignore'\n\nexport type DocsManifestSource = {\n  branch?: string\n  commit?: string\n  id: string\n  repository?: string\n  root?: string\n}\n\nexport type DocsManifestFile = {\n  content: string\n  path: string\n  sha256?: string\n}\n\nexport type DocsManifest = {\n  aiExport?: DocsAiExportManifest\n  deleteBehavior?: DocsDeleteBehavior\n  files: DocsManifestFile[]\n  mode?: DocsSyncMode\n  publish?: boolean\n  source: DocsManifestSource\n  version: 1\n}\n\nexport type ValidatedDocsManifestFile = {\n  content: string\n  frontmatter: DocsFrontmatter\n  path: string\n  route: string\n  sha256: string\n  title: string\n}\n\nexport type ValidatedDocsManifest = {\n  aiExport?: DocsAiExportManifest\n  deleteBehavior: DocsDeleteBehavior\n  files: ValidatedDocsManifestFile[]\n  mode: DocsSyncMode\n  publish: boolean\n  source: DocsManifestSource\n  version: 1\n}\n\nexport type DocsManifestInputFile = {\n  content: string\n  path: string\n}\n\nexport const buildDocsManifest = ({\n  aiExport,\n  branch,\n  commit,\n  deleteBehavior,\n  files,\n  mode,\n  publish,\n  repository,\n  root,\n  sourceId,\n}: {\n  aiExport?: DocsAiExportManifest\n  branch?: string\n  commit?: string\n  deleteBehavior?: DocsDeleteBehavior\n  files: DocsManifestInputFile[]\n  mode?: DocsSyncMode\n  publish?: boolean\n  repository?: string\n  root?: string\n  sourceId: string\n}): DocsManifest => ({\n  aiExport,\n  deleteBehavior,\n  files: files.map((file) => ({\n    ...file,\n    sha256: sha256Hex(file.content),\n  })),\n  mode,\n  publish,\n  source: {\n    id: sourceId,\n    branch,\n    commit,\n    repository,\n    root,\n  },\n  version: 1,\n})\n"],"names":["sha256Hex","buildDocsManifest","aiExport","branch","commit","deleteBehavior","files","mode","publish","repository","root","sourceId","map","file","sha256","content","source","id","version"],"mappings":"AAGA,SAASA,SAAS,QAAQ,YAAW;AAsDrC,OAAO,MAAMC,oBAAoB,CAAC,EAChCC,QAAQ,EACRC,MAAM,EACNC,MAAM,EACNC,cAAc,EACdC,KAAK,EACLC,IAAI,EACJC,OAAO,EACPC,UAAU,EACVC,IAAI,EACJC,QAAQ,EAYT,GAAoB,CAAA;QACnBT;QACAG;QACAC,OAAOA,MAAMM,GAAG,CAAC,CAACC,OAAU,CAAA;gBAC1B,GAAGA,IAAI;gBACPC,QAAQd,UAAUa,KAAKE,OAAO;YAChC,CAAA;QACAR;QACAC;QACAQ,QAAQ;YACNC,IAAIN;YACJR;YACAC;YACAK;YACAC;QACF;QACAQ,SAAS;IACX,CAAA,EAAE"}

package/dist/sync/paths.d.ts

@@ -0,0 +1,16 @@
+import type { DocsValidationErrorCode } from './validate.js';
+export type NormalizeDocsPathResult = {
+    code: DocsValidationErrorCode;
+    message: string;
+    ok: false;
+} | {
+    ok: true;
+    path: string;
+    routeSegments: string[];
+};
+export declare const normalizeDocsPath: (input: string) => NormalizeDocsPathResult;
+export declare const deriveRouteFromSourcePath: ({ slug, routeBase, sourcePath, }: {
+    routeBase: string;
+    slug?: string;
+    sourcePath: string;
+}) => string;

package/dist/sync/paths.js

@@ -0,0 +1,116 @@
+const trimLeadingCurrentDirectory = (path)=>{
+    let nextPath = path;
+    while(nextPath.startsWith('./')){
+        nextPath = nextPath.slice(2);
+    }
+    return nextPath;
+};
+export const normalizeDocsPath = (input)=>{
+    if (typeof input !== 'string' || input.trim() === '') {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path must be a non-empty string.',
+            ok: false
+        };
+    }
+    const trimmedInput = input.trim();
+    if (/^[a-z]:[\\/]/i.test(trimmedInput)) {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path must not be an absolute Windows path.',
+            ok: false
+        };
+    }
+    if (trimmedInput.startsWith('/')) {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path must not be an absolute path.',
+            ok: false
+        };
+    }
+    const normalizedPath = trimLeadingCurrentDirectory(trimmedInput.replace(/\\/g, '/').replace(/\/+/g, '/'));
+    if (normalizedPath === '' || normalizedPath.endsWith('/')) {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path must point to a Markdown file.',
+            ok: false
+        };
+    }
+    const segments = normalizedPath.split('/');
+    if (segments.some((segment)=>segment === '..')) {
+        return {
+            code: 'path_traversal',
+            message: 'Docs path must not contain path traversal segments.',
+            ok: false
+        };
+    }
+    if (segments.some((segment)=>segment === '' || segment === '.')) {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path contains an invalid path segment.',
+            ok: false
+        };
+    }
+    if (!normalizedPath.endsWith('.md')) {
+        return {
+            code: 'non_markdown_file',
+            message: 'Docs path must end in .md.',
+            ok: false
+        };
+    }
+    const fileName = segments.at(-1);
+    if (!fileName || fileName === '.md') {
+        return {
+            code: 'invalid_path',
+            message: 'Docs path must include a Markdown filename.',
+            ok: false
+        };
+    }
+    const routeSegments = segments.map((segment, index)=>{
+        if (index === segments.length - 1) {
+            return segment.slice(0, -'.md'.length);
+        }
+        return segment;
+    });
+    if (routeSegments.at(-1) === 'index') {
+        routeSegments.pop();
+    }
+    return {
+        ok: true,
+        path: normalizedPath,
+        routeSegments
+    };
+};
+const normalizeRouteBase = (routeBase)=>{
+    const normalized = `/${routeBase.trim()}`.replace(/\\/g, '/').replace(/\/+/g, '/');
+    const withoutTrailingSlash = normalized.length > 1 ? normalized.replace(/\/+$/g, '') : normalized;
+    return withoutTrailingSlash || '/';
+};
+export const deriveRouteFromSourcePath = ({ slug, routeBase, sourcePath })=>{
+    const normalizedPath = normalizeDocsPath(sourcePath);
+    const normalizedRouteBase = normalizeRouteBase(routeBase);
+    if (!normalizedPath.ok) {
+        return normalizedRouteBase;
+    }
+    let routeSegments = [
+        ...normalizedPath.routeSegments
+    ];
+    const routeBaseSegments = normalizedRouteBase.split('/').filter(Boolean);
+    if (routeBaseSegments.length > 0 && routeBaseSegments.every((segment, index)=>routeSegments[index] === segment)) {
+        routeSegments = routeSegments.slice(routeBaseSegments.length);
+    }
+    if (slug && routeSegments.length > 0) {
+        routeSegments[routeSegments.length - 1] = slug;
+    } else if (slug) {
+        routeSegments = [
+            slug
+        ];
+    }
+    const routeSuffix = routeSegments.join('/');
+    if (!routeSuffix) {
+        return normalizedRouteBase;
+    }
+    return `${normalizedRouteBase}/${routeSuffix}`.replace(/\/+/g, '/');
+};
+
+//# sourceMappingURL=paths.js.map

package/dist/sync/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/paths.ts"],"sourcesContent":["import type { DocsValidationErrorCode } from './validate.js'\n\nexport type NormalizeDocsPathResult =\n  | {\n      code: DocsValidationErrorCode\n      message: string\n      ok: false\n    }\n  | {\n      ok: true\n      path: string\n      routeSegments: string[]\n    }\n\nconst trimLeadingCurrentDirectory = (path: string): string => {\n  let nextPath = path\n\n  while (nextPath.startsWith('./')) {\n    nextPath = nextPath.slice(2)\n  }\n\n  return nextPath\n}\n\nexport const normalizeDocsPath = (input: string): NormalizeDocsPathResult => {\n  if (typeof input !== 'string' || input.trim() === '') {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path must be a non-empty string.',\n      ok: false,\n    }\n  }\n\n  const trimmedInput = input.trim()\n\n  if (/^[a-z]:[\\\\/]/i.test(trimmedInput)) {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path must not be an absolute Windows path.',\n      ok: false,\n    }\n  }\n\n  if (trimmedInput.startsWith('/')) {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path must not be an absolute path.',\n      ok: false,\n    }\n  }\n\n  const normalizedPath = trimLeadingCurrentDirectory(\n    trimmedInput.replace(/\\\\/g, '/').replace(/\\/+/g, '/'),\n  )\n\n  if (normalizedPath === '' || normalizedPath.endsWith('/')) {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path must point to a Markdown file.',\n      ok: false,\n    }\n  }\n\n  const segments = normalizedPath.split('/')\n\n  if (segments.some((segment) => segment === '..')) {\n    return {\n      code: 'path_traversal',\n      message: 'Docs path must not contain path traversal segments.',\n      ok: false,\n    }\n  }\n\n  if (segments.some((segment) => segment === '' || segment === '.')) {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path contains an invalid path segment.',\n      ok: false,\n    }\n  }\n\n  if (!normalizedPath.endsWith('.md')) {\n    return {\n      code: 'non_markdown_file',\n      message: 'Docs path must end in .md.',\n      ok: false,\n    }\n  }\n\n  const fileName = segments.at(-1)\n\n  if (!fileName || fileName === '.md') {\n    return {\n      code: 'invalid_path',\n      message: 'Docs path must include a Markdown filename.',\n      ok: false,\n    }\n  }\n\n  const routeSegments = segments.map((segment, index) => {\n    if (index === segments.length - 1) {\n      return segment.slice(0, -'.md'.length)\n    }\n\n    return segment\n  })\n\n  if (routeSegments.at(-1) === 'index') {\n    routeSegments.pop()\n  }\n\n  return {\n    ok: true,\n    path: normalizedPath,\n    routeSegments,\n  }\n}\n\nconst normalizeRouteBase = (routeBase: string): string => {\n  const normalized = `/${routeBase.trim()}`.replace(/\\\\/g, '/').replace(/\\/+/g, '/')\n  const withoutTrailingSlash =\n    normalized.length > 1 ? normalized.replace(/\\/+$/g, '') : normalized\n\n  return withoutTrailingSlash || '/'\n}\n\nexport const deriveRouteFromSourcePath = ({\n  slug,\n  routeBase,\n  sourcePath,\n}: {\n  routeBase: string\n  slug?: string\n  sourcePath: string\n}): string => {\n  const normalizedPath = normalizeDocsPath(sourcePath)\n  const normalizedRouteBase = normalizeRouteBase(routeBase)\n\n  if (!normalizedPath.ok) {\n    return normalizedRouteBase\n  }\n\n  let routeSegments = [...normalizedPath.routeSegments]\n  const routeBaseSegments = normalizedRouteBase.split('/').filter(Boolean)\n\n  if (\n    routeBaseSegments.length > 0 &&\n    routeBaseSegments.every((segment, index) => routeSegments[index] === segment)\n  ) {\n    routeSegments = routeSegments.slice(routeBaseSegments.length)\n  }\n\n  if (slug && routeSegments.length > 0) {\n    routeSegments[routeSegments.length - 1] = slug\n  } else if (slug) {\n    routeSegments = [slug]\n  }\n\n  const routeSuffix = routeSegments.join('/')\n\n  if (!routeSuffix) {\n    return normalizedRouteBase\n  }\n\n  return `${normalizedRouteBase}/${routeSuffix}`.replace(/\\/+/g, '/')\n}\n"],"names":["trimLeadingCurrentDirectory","path","nextPath","startsWith","slice","normalizeDocsPath","input","trim","code","message","ok","trimmedInput","test","normalizedPath","replace","endsWith","segments","split","some","segment","fileName","at","routeSegments","map","index","length","pop","normalizeRouteBase","routeBase","normalized","withoutTrailingSlash","deriveRouteFromSourcePath","slug","sourcePath","normalizedRouteBase","routeBaseSegments","filter","Boolean","every","routeSuffix","join"],"mappings":"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"}

package/dist/sync/plan.d.ts

@@ -0,0 +1,29 @@
+import type { DocsDeleteBehavior, ValidatedDocsManifest, ValidatedDocsManifestFile } from './manifest.js';
+import type { DocsValidationIssue } from './validate.js';
+export type ExistingDocsRecord = {
+    archived?: boolean;
+    route: string;
+    sourceHash?: string;
+    sourcePath: string;
+    title?: string;
+};
+export type PlannedDocChange = {
+    current?: ExistingDocsRecord;
+    desired?: ValidatedDocsManifestFile;
+    reason: string;
+    sourcePath: string;
+};
+export type DocsSyncPlan = {
+    archive: PlannedDocChange[];
+    create: PlannedDocChange[];
+    delete: PlannedDocChange[];
+    draft: PlannedDocChange[];
+    unchanged: PlannedDocChange[];
+    update: PlannedDocChange[];
+    warnings: DocsValidationIssue[];
+};
+export declare const planDocsSync: ({ deleteBehavior, desired, existing, }: {
+    deleteBehavior?: DocsDeleteBehavior;
+    desired: ValidatedDocsManifest;
+    existing: ExistingDocsRecord[];
+}) => DocsSyncPlan;

package/dist/sync/plan.js

@@ -0,0 +1,72 @@
+const createEmptyPlan = ()=>({
+        archive: [],
+        create: [],
+        delete: [],
+        draft: [],
+        unchanged: [],
+        update: [],
+        warnings: []
+    });
+export const planDocsSync = ({ deleteBehavior, desired, existing })=>{
+    const plan = createEmptyPlan();
+    const effectiveDeleteBehavior = deleteBehavior ?? desired.deleteBehavior ?? 'archive';
+    const existingBySourcePath = new Map();
+    for (const existingRecord of existing){
+        if (existingBySourcePath.has(existingRecord.sourcePath)) {
+            plan.warnings.push({
+                code: 'duplicate_existing_path',
+                message: `Existing docs contain duplicate sourcePath "${existingRecord.sourcePath}".`,
+                path: existingRecord.sourcePath
+            });
+            continue;
+        }
+        existingBySourcePath.set(existingRecord.sourcePath, existingRecord);
+    }
+    const desiredSourcePaths = new Set(desired.files.map((file)=>file.path));
+    for (const desiredFile of desired.files){
+        const current = existingBySourcePath.get(desiredFile.path);
+        if (!current) {
+            plan.create.push({
+                desired: desiredFile,
+                reason: 'No existing doc has this sourcePath.',
+                sourcePath: desiredFile.path
+            });
+            continue;
+        }
+        if (current.sourceHash === desiredFile.sha256) {
+            plan.unchanged.push({
+                current,
+                desired: desiredFile,
+                reason: 'Existing source hash matches desired source hash.',
+                sourcePath: desiredFile.path
+            });
+            continue;
+        }
+        plan.update.push({
+            current,
+            desired: desiredFile,
+            reason: 'Existing source hash differs from desired source hash.',
+            sourcePath: desiredFile.path
+        });
+    }
+    for (const current of existingBySourcePath.values()){
+        if (desiredSourcePaths.has(current.sourcePath)) {
+            continue;
+        }
+        const change = {
+            current,
+            reason: 'Existing doc is missing from desired manifest.',
+            sourcePath: current.sourcePath
+        };
+        if (effectiveDeleteBehavior === 'archive') {
+            plan.archive.push(change);
+        } else if (effectiveDeleteBehavior === 'delete') {
+            plan.delete.push(change);
+        } else if (effectiveDeleteBehavior === 'draft') {
+            plan.draft.push(change);
+        }
+    }
+    return plan;
+};
+
+//# sourceMappingURL=plan.js.map

package/dist/sync/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sync/plan.ts"],"sourcesContent":["import type {\n  DocsDeleteBehavior,\n  ValidatedDocsManifest,\n  ValidatedDocsManifestFile,\n} from './manifest.js'\nimport type { DocsValidationIssue } from './validate.js'\n\nexport type ExistingDocsRecord = {\n  archived?: boolean\n  route: string\n  sourceHash?: string\n  sourcePath: string\n  title?: string\n}\n\nexport type PlannedDocChange = {\n  current?: ExistingDocsRecord\n  desired?: ValidatedDocsManifestFile\n  reason: string\n  sourcePath: string\n}\n\nexport type DocsSyncPlan = {\n  archive: PlannedDocChange[]\n  create: PlannedDocChange[]\n  delete: PlannedDocChange[]\n  draft: PlannedDocChange[]\n  unchanged: PlannedDocChange[]\n  update: PlannedDocChange[]\n  warnings: DocsValidationIssue[]\n}\n\nconst createEmptyPlan = (): DocsSyncPlan => ({\n  archive: [],\n  create: [],\n  delete: [],\n  draft: [],\n  unchanged: [],\n  update: [],\n  warnings: [],\n})\n\nexport const planDocsSync = ({\n  deleteBehavior,\n  desired,\n  existing,\n}: {\n  deleteBehavior?: DocsDeleteBehavior\n  desired: ValidatedDocsManifest\n  existing: ExistingDocsRecord[]\n}): DocsSyncPlan => {\n  const plan = createEmptyPlan()\n  const effectiveDeleteBehavior = deleteBehavior ?? desired.deleteBehavior ?? 'archive'\n  const existingBySourcePath = new Map<string, ExistingDocsRecord>()\n\n  for (const existingRecord of existing) {\n    if (existingBySourcePath.has(existingRecord.sourcePath)) {\n      plan.warnings.push({\n        code: 'duplicate_existing_path',\n        message: `Existing docs contain duplicate sourcePath \"${existingRecord.sourcePath}\".`,\n        path: existingRecord.sourcePath,\n      })\n      continue\n    }\n\n    existingBySourcePath.set(existingRecord.sourcePath, existingRecord)\n  }\n\n  const desiredSourcePaths = new Set(desired.files.map((file) => file.path))\n\n  for (const desiredFile of desired.files) {\n    const current = existingBySourcePath.get(desiredFile.path)\n\n    if (!current) {\n      plan.create.push({\n        desired: desiredFile,\n        reason: 'No existing doc has this sourcePath.',\n        sourcePath: desiredFile.path,\n      })\n      continue\n    }\n\n    if (current.sourceHash === desiredFile.sha256) {\n      plan.unchanged.push({\n        current,\n        desired: desiredFile,\n        reason: 'Existing source hash matches desired source hash.',\n        sourcePath: desiredFile.path,\n      })\n      continue\n    }\n\n    plan.update.push({\n      current,\n      desired: desiredFile,\n      reason: 'Existing source hash differs from desired source hash.',\n      sourcePath: desiredFile.path,\n    })\n  }\n\n  for (const current of existingBySourcePath.values()) {\n    if (desiredSourcePaths.has(current.sourcePath)) {\n      continue\n    }\n\n    const change = {\n      current,\n      reason: 'Existing doc is missing from desired manifest.',\n      sourcePath: current.sourcePath,\n    }\n\n    if (effectiveDeleteBehavior === 'archive') {\n      plan.archive.push(change)\n    } else if (effectiveDeleteBehavior === 'delete') {\n      plan.delete.push(change)\n    } else if (effectiveDeleteBehavior === 'draft') {\n      plan.draft.push(change)\n    }\n  }\n\n  return plan\n}\n"],"names":["createEmptyPlan","archive","create","delete","draft","unchanged","update","warnings","planDocsSync","deleteBehavior","desired","existing","plan","effectiveDeleteBehavior","existingBySourcePath","Map","existingRecord","has","sourcePath","push","code","message","path","set","desiredSourcePaths","Set","files","map","file","desiredFile","current","get","reason","sourceHash","sha256","values","change"],"mappings":"AAgCA,MAAMA,kBAAkB,IAAqB,CAAA;QAC3CC,SAAS,EAAE;QACXC,QAAQ,EAAE;QACVC,QAAQ,EAAE;QACVC,OAAO,EAAE;QACTC,WAAW,EAAE;QACbC,QAAQ,EAAE;QACVC,UAAU,EAAE;IACd,CAAA;AAEA,OAAO,MAAMC,eAAe,CAAC,EAC3BC,cAAc,EACdC,OAAO,EACPC,QAAQ,EAKT;IACC,MAAMC,OAAOZ;IACb,MAAMa,0BAA0BJ,kBAAkBC,QAAQD,cAAc,IAAI;IAC5E,MAAMK,uBAAuB,IAAIC;IAEjC,KAAK,MAAMC,kBAAkBL,SAAU;QACrC,IAAIG,qBAAqBG,GAAG,CAACD,eAAeE,UAAU,GAAG;YACvDN,KAAKL,QAAQ,CAACY,IAAI,CAAC;gBACjBC,MAAM;gBACNC,SAAS,CAAC,4CAA4C,EAAEL,eAAeE,UAAU,CAAC,EAAE,CAAC;gBACrFI,MAAMN,eAAeE,UAAU;YACjC;YACA;QACF;QAEAJ,qBAAqBS,GAAG,CAACP,eAAeE,UAAU,EAAEF;IACtD;IAEA,MAAMQ,qBAAqB,IAAIC,IAAIf,QAAQgB,KAAK,CAACC,GAAG,CAAC,CAACC,OAASA,KAAKN,IAAI;IAExE,KAAK,MAAMO,eAAenB,QAAQgB,KAAK,CAAE;QACvC,MAAMI,UAAUhB,qBAAqBiB,GAAG,CAACF,YAAYP,IAAI;QAEzD,IAAI,CAACQ,SAAS;YACZlB,KAAKV,MAAM,CAACiB,IAAI,CAAC;gBACfT,SAASmB;gBACTG,QAAQ;gBACRd,YAAYW,YAAYP,IAAI;YAC9B;YACA;QACF;QAEA,IAAIQ,QAAQG,UAAU,KAAKJ,YAAYK,MAAM,EAAE;YAC7CtB,KAAKP,SAAS,CAACc,IAAI,CAAC;gBAClBW;gBACApB,SAASmB;gBACTG,QAAQ;gBACRd,YAAYW,YAAYP,IAAI;YAC9B;YACA;QACF;QAEAV,KAAKN,MAAM,CAACa,IAAI,CAAC;YACfW;YACApB,SAASmB;YACTG,QAAQ;YACRd,YAAYW,YAAYP,IAAI;QAC9B;IACF;IAEA,KAAK,MAAMQ,WAAWhB,qBAAqBqB,MAAM,GAAI;QACnD,IAAIX,mBAAmBP,GAAG,CAACa,QAAQZ,UAAU,GAAG;YAC9C;QACF;QAEA,MAAMkB,SAAS;YACbN;YACAE,QAAQ;YACRd,YAAYY,QAAQZ,UAAU;QAChC;QAEA,IAAIL,4BAA4B,WAAW;YACzCD,KAAKX,OAAO,CAACkB,IAAI,CAACiB;QACpB,OAAO,IAAIvB,4BAA4B,UAAU;YAC/CD,KAAKT,MAAM,CAACgB,IAAI,CAACiB;QACnB,OAAO,IAAIvB,4BAA4B,SAAS;YAC9CD,KAAKR,KAAK,CAACe,IAAI,CAACiB;QAClB;IACF;IAEA,OAAOxB;AACT,EAAC"}