saturndocs 0.1.0

package/dist/chunk-I6U4V7B4.js

@@ -0,0 +1,1552 @@
+import {
+  parseOpenApi
+} from "./chunk-S45UWCML.js";
+import {
+  navigationGroups,
+  parseDocsConfig,
+  parseModelsConfig
+} from "./chunk-R3X2DPFF.js";
+import {
+  messageOf
+} from "./chunk-VNYDYHXM.js";
+
+// src/commands/deploy.ts
+import { randomUUID } from "crypto";
+import { createReadStream as createReadStream2 } from "fs";
+import pc from "picocolors";
+
+// src/lib/bundle.ts
+import { createHash } from "crypto";
+import { createReadStream, createWriteStream } from "fs";
+import { lstat, mkdir, mkdtemp, readFile, readdir, rm, stat } from "fs/promises";
+import { tmpdir } from "os";
+import { join, posix, resolve } from "path";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+import { createGzip } from "zlib";
+
+// ../source-abi/dist/index.js
+import { parse, parseDocument } from "yaml";
+import { unified } from "unified";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+var SOURCE_ABI_VERSION = 3;
+var SOURCE_LIMITS = Object.freeze({
+  maxFileBytes: 26214400,
+  maxTotalBytes: 209715200,
+  maxFileCount: 5e3,
+  maxPageCount: 2e3,
+  maxPathDepth: 12,
+  maxPathBytes: 512,
+  maxSegmentBytes: 255,
+  maxDocsJsonBytes: 1048576,
+  maxModelsTomlBytes: 65536,
+  maxOpenApiBytes: 4194304,
+  maxFrontmatterBytes: 65536,
+  maxThemeCssBytes: 262144
+});
+var SOURCE_ALLOWED_ROOTS = Object.freeze([
+  "docs.json",
+  "models.toml",
+  "pages/**",
+  "public/**",
+  "openapi/**"
+]);
+var SOURCE_ALLOWED_EXTENSIONS = Object.freeze({
+  root: Object.freeze([".json", ".toml"]),
+  pages: Object.freeze([".md", ".mdx"]),
+  openapi: Object.freeze([".json", ".yaml", ".yml"]),
+  public: Object.freeze([
+    ".css",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".avif",
+    ".svg",
+    ".ico",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".otf",
+    ".eot",
+    ".mp4",
+    ".webm",
+    ".mp3",
+    ".wav",
+    ".ogg",
+    ".oga",
+    ".ogv",
+    ".pdf",
+    ".txt",
+    ".csv"
+  ])
+});
+var RESERVED_URL_PREFIXES = Object.freeze([
+  "/api",
+  "/api/*",
+  "/auth",
+  "/auth/*",
+  "/mcp",
+  "/ask",
+  "/runtime",
+  "/runtime/*"
+]);
+var REJECTED_GENERATED_ROOTS = Object.freeze([
+  "dist",
+  "pagefind",
+  "_astro",
+  "worker/generated",
+  "node_modules",
+  ".git"
+]);
+var REJECTED_GENERATED_FILENAMES = Object.freeze([
+  "llms.txt",
+  "llms-full.txt",
+  "robots.txt",
+  "sitemap*",
+  "*auth-manifest*.json"
+]);
+var SOURCE_MEDIA_TYPES = Object.freeze({
+  ".avif": "image/avif",
+  ".csv": "text/csv",
+  ".css": "text/css",
+  ".eot": "application/vnd.ms-fontobject",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".json": "application/json",
+  ".md": "text/markdown",
+  ".mdx": "text/mdx",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".ogv": "video/ogg",
+  ".otf": "font/otf",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".toml": "application/toml",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".yaml": "application/yaml",
+  ".yml": "application/yaml"
+});
+var textEncoder = new TextEncoder();
+var WINDOWS_DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+var ASCII_SOURCE_PATH = /^[A-Za-z0-9._/-]+$/;
+var ASCII_SOURCE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var PAGE_EXTENSIONS = new Set(SOURCE_ALLOWED_EXTENSIONS.pages);
+var PUBLIC_EXTENSIONS = new Set(SOURCE_ALLOWED_EXTENSIONS.public);
+var OPENAPI_EXTENSIONS = new Set(SOURCE_ALLOWED_EXTENSIONS.openapi);
+function sourceExtension(path) {
+  const filename = path.slice(path.lastIndexOf("/") + 1);
+  const dot = filename.lastIndexOf(".");
+  return dot <= 0 ? null : filename.slice(dot).toLowerCase();
+}
+function inspectSourcePath(raw) {
+  const normalized = raw;
+  const segments = normalized.split("/");
+  const tooDeep = segments.length > SOURCE_LIMITS.maxPathDepth;
+  const tooLong = textEncoder.encode(normalized).byteLength > SOURCE_LIMITS.maxPathBytes;
+  const segmentTooLong = segments.some(
+    (segment) => textEncoder.encode(segment).byteLength > SOURCE_LIMITS.maxSegmentBytes
+  );
+  let syntaxValid = normalized.length > 0;
+  if (normalized.startsWith("/") || normalized.endsWith("/") || !ASCII_SOURCE_PATH.test(normalized)) {
+    syntaxValid = false;
+  }
+  for (const segment of segments) {
+    if (segment.length === 0 || !ASCII_SOURCE_SEGMENT.test(segment) || segment === "." || segment === ".." || WINDOWS_DEVICE_NAME.test(segment) || segment.endsWith(".")) {
+      syntaxValid = false;
+    }
+  }
+  return { normalized, segments, syntaxValid, tooDeep, tooLong, segmentTooLong };
+}
+function isKnownSourceRoot(path) {
+  if (path === "docs.json" || path === "models.toml") return true;
+  return path.startsWith("pages/") || path.startsWith("public/") || path.startsWith("openapi/");
+}
+function isAllowedSourceLocation(path) {
+  const extension = sourceExtension(path);
+  if (path === "docs.json") return extension === ".json";
+  if (path === "models.toml") return extension === ".toml";
+  if (path.startsWith("pages/")) {
+    return extension !== null && PAGE_EXTENSIONS.has(extension);
+  }
+  if (path.startsWith("public/")) {
+    if (extension === ".css") return path === "public/theme.css";
+    return extension !== null && PUBLIC_EXTENSIONS.has(extension);
+  }
+  if (path.startsWith("openapi/")) {
+    return extension !== null && OPENAPI_EXTENSIONS.has(extension);
+  }
+  return false;
+}
+function isStaticallyGeneratedArtifact(path) {
+  const lower = path.toLowerCase();
+  const filename = lower.slice(lower.lastIndexOf("/") + 1);
+  if (lower === "dist" || lower.startsWith("dist/") || lower === "pagefind" || lower.startsWith("pagefind/") || lower === "_astro" || lower.startsWith("_astro/") || lower === "node_modules" || lower.startsWith("node_modules/") || lower === ".git" || lower.startsWith(".git/") || lower === "worker/generated" || lower.startsWith("worker/generated/")) {
+    return true;
+  }
+  return filename === "llms.txt" || filename === "llms-full.txt" || filename === "robots.txt" || filename.startsWith("sitemap") || filename.endsWith(".json") && filename.includes("auth-manifest");
+}
+function canonicalizeSourcePath(raw) {
+  const inspected = inspectSourcePath(raw);
+  if (!inspected.syntaxValid || inspected.tooDeep || inspected.tooLong || inspected.segmentTooLong || !isAllowedSourceLocation(inspected.normalized) || isStaticallyGeneratedArtifact(inspected.normalized)) {
+    return null;
+  }
+  return inspected.normalized;
+}
+function detectSourceMediaType(path) {
+  const extension = sourceExtension(path);
+  if (extension === null) return null;
+  return SOURCE_MEDIA_TYPES[extension] ?? null;
+}
+function unicodeCaseFold(value) {
+  return value.toLowerCase();
+}
+var textEncoder2 = new TextEncoder();
+function compareCodePoints2(left, right) {
+  const leftPoints = Array.from(left, (point) => point.codePointAt(0));
+  const rightPoints = Array.from(right, (point) => point.codePointAt(0));
+  const count = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < count; index += 1) {
+    const difference = leftPoints[index] - rightPoints[index];
+    if (difference !== 0) return difference;
+  }
+  return leftPoints.length - rightPoints.length;
+}
+function sortViolations(violations) {
+  return violations.sort((left, right) => {
+    if (left.path === null && right.path !== null) return -1;
+    if (left.path !== null && right.path === null) return 1;
+    const pathOrder = compareCodePoints2(left.path ?? "", right.path ?? "");
+    if (pathOrder !== 0) return pathOrder;
+    const codeOrder = compareCodePoints2(left.code, right.code);
+    if (codeOrder !== 0) return codeOrder;
+    return compareCodePoints2(left.message, right.message);
+  });
+}
+function isRootSpecificTypeInvalid(path) {
+  return (path.startsWith("pages/") || path.startsWith("public/") || path.startsWith("openapi/") || path === "docs.json" || path === "models.toml") && !isAllowedSourceLocation(path);
+}
+function isReservedRoute(path) {
+  return RESERVED_URL_PREFIXES.some((pattern) => {
+    if (pattern.endsWith("/*")) {
+      return path.startsWith(pattern.slice(0, -1));
+    }
+    return path === pattern;
+  });
+}
+function servedRoute(path) {
+  if (path.startsWith("pages/")) {
+    const extension = sourceExtension(path);
+    if (extension !== ".md" && extension !== ".mdx") return null;
+    const logical = path.slice("pages/".length, -extension.length);
+    return logical === "index" ? "/" : `/${logical}`;
+  }
+  if (path.startsWith("public/")) {
+    return `/${path.slice("public/".length)}`;
+  }
+  return null;
+}
+function pageTwinPaths(paths) {
+  const pages = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    if (!path.startsWith("pages/")) continue;
+    const extension = sourceExtension(path);
+    if (extension === ".md" || extension === ".mdx") {
+      pages.add(path.slice("pages/".length, -extension.length));
+    }
+  }
+  const twins = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    if (path.startsWith("pages/") || sourceExtension(path) !== ".md") continue;
+    if (pages.has(path.slice(0, -3))) twins.add(path);
+  }
+  return twins;
+}
+function validateBundleStructure(files) {
+  const violations = [];
+  const inspected = files.map((file) => ({ file, path: inspectSourcePath(file.path) }));
+  const normalizedPaths = inspected.filter((item) => item.path.syntaxValid).map((item) => item.path.normalized);
+  const generatedTwins = pageTwinPaths(normalizedPaths);
+  if (files.length > SOURCE_LIMITS.maxFileCount) {
+    violations.push({
+      path: null,
+      code: "too_many_files",
+      severity: "error",
+      message: `bundle has ${files.length} files; maximum is ${SOURCE_LIMITS.maxFileCount}`
+    });
+  }
+  let totalSize = 0;
+  let pageCount = 0;
+  let hasDocsJson = false;
+  for (const { file, path } of inspected) {
+    const sizeValid = Number.isSafeInteger(file.size) && file.size >= 0;
+    totalSize += sizeValid ? file.size : 0;
+    const displayPath = path.syntaxValid ? path.normalized : file.path;
+    if (!sizeValid) {
+      violations.push({
+        path: displayPath,
+        code: "invalid_size",
+        severity: "error",
+        message: "source file size must be a non-negative safe integer"
+      });
+    }
+    if (!path.syntaxValid || path.tooLong || path.segmentTooLong) {
+      violations.push({
+        path: displayPath,
+        code: "invalid_path",
+        severity: "error",
+        message: "source path is not a valid canonical logical path"
+      });
+    }
+    if (path.tooDeep) {
+      violations.push({
+        path: displayPath,
+        code: "path_too_deep",
+        severity: "error",
+        message: `source path has ${path.segments.length} segments; maximum is ${SOURCE_LIMITS.maxPathDepth}`
+      });
+    }
+    if (sizeValid && file.size > SOURCE_LIMITS.maxFileBytes) {
+      violations.push({
+        path: displayPath,
+        code: "file_too_large",
+        severity: "error",
+        message: `source file is ${file.size} bytes; maximum is ${SOURCE_LIMITS.maxFileBytes}`
+      });
+    }
+    if (sizeValid && path.syntaxValid && path.normalized === "public/theme.css" && file.size > SOURCE_LIMITS.maxThemeCssBytes) {
+      violations.push({
+        path: path.normalized,
+        code: "theme_css_too_large",
+        severity: "error",
+        message: `public/theme.css is ${file.size} bytes; maximum is ${SOURCE_LIMITS.maxThemeCssBytes}`
+      });
+    }
+    if (!path.syntaxValid) continue;
+    const normalized = path.normalized;
+    if (normalized === "docs.json" && !path.tooLong && !path.segmentTooLong && isAllowedSourceLocation(normalized) && !isStaticallyGeneratedArtifact(normalized)) {
+      hasDocsJson = true;
+    }
+    const mediaType = detectSourceMediaType(normalized);
+    if (mediaType === null || isRootSpecificTypeInvalid(normalized)) {
+      violations.push({
+        path: normalized,
+        code: "inadmissible_type",
+        severity: "error",
+        message: "file extension is not admissible at this source location"
+      });
+    }
+    if (!isKnownSourceRoot(normalized)) {
+      violations.push({
+        path: normalized,
+        code: "unknown_root",
+        severity: "error",
+        message: "source path is not under an allowed source root"
+      });
+    }
+    if (isStaticallyGeneratedArtifact(normalized) || generatedTwins.has(normalized)) {
+      violations.push({
+        path: normalized,
+        code: "generated_artifact",
+        severity: "error",
+        message: "build-generated output is not admissible as source"
+      });
+    }
+    if (sourceExtension(normalized) === ".svg") {
+      violations.push({
+        path: normalized,
+        code: "active_content",
+        severity: "warning",
+        message: "SVG is active content and requires release-layer policy"
+      });
+    }
+    const route = servedRoute(normalized);
+    if (route !== null && isReservedRoute(route)) {
+      violations.push({
+        path: normalized,
+        code: "reserved_route",
+        severity: "error",
+        message: `source path would claim reserved route ${route}`
+      });
+    }
+    const extension = sourceExtension(normalized);
+    if (normalized.startsWith("pages/") && (extension === ".md" || extension === ".mdx")) {
+      pageCount += 1;
+    }
+  }
+  if (!hasDocsJson) {
+    violations.push({
+      path: null,
+      code: "missing_docs_json",
+      severity: "error",
+      message: "bundle must contain an admissible docs.json entry"
+    });
+  }
+  if (totalSize > SOURCE_LIMITS.maxTotalBytes) {
+    violations.push({
+      path: null,
+      code: "bundle_too_large",
+      severity: "error",
+      message: `bundle is ${totalSize} bytes; maximum is ${SOURCE_LIMITS.maxTotalBytes}`
+    });
+  }
+  if (pageCount > SOURCE_LIMITS.maxPageCount) {
+    violations.push({
+      path: null,
+      code: "too_many_pages",
+      severity: "error",
+      message: `bundle has ${pageCount} page files; maximum is ${SOURCE_LIMITS.maxPageCount}`
+    });
+  }
+  const caseGroups = /* @__PURE__ */ new Map();
+  for (const path of normalizedPaths) {
+    const folded = unicodeCaseFold(path);
+    const group = caseGroups.get(folded) ?? [];
+    group.push(path);
+    caseGroups.set(folded, group);
+  }
+  for (const group of caseGroups.values()) {
+    const paths = [...group].sort(compareCodePoints2);
+    for (let index = 1; index < paths.length; index += 1) {
+      violations.push({
+        path: paths[index],
+        code: "case_collision",
+        severity: "error",
+        message: `source path collides case-insensitively with ${paths[0]}`
+      });
+    }
+  }
+  const pageKinds = /* @__PURE__ */ new Map();
+  for (const path of normalizedPaths) {
+    if (!path.startsWith("pages/")) continue;
+    const extension = sourceExtension(path);
+    if (extension !== ".md" && extension !== ".mdx") continue;
+    const logical = path.slice(0, -extension.length);
+    const kind = pageKinds.get(logical) ?? {};
+    if (extension === ".md") kind.md = path;
+    else kind.mdx = path;
+    pageKinds.set(logical, kind);
+  }
+  for (const kind of pageKinds.values()) {
+    if (kind.md && kind.mdx) {
+      violations.push({
+        path: kind.mdx,
+        code: "md_mdx_collision",
+        severity: "error",
+        message: `logical page resolves to both ${kind.md} and ${kind.mdx}`
+      });
+    }
+  }
+  return sortViolations(violations);
+}
+var STRING = "string";
+var BOOLEAN = "boolean";
+var HREF = "href";
+var SRC = "src";
+var CALLOUT_ATTRIBUTES = { title: STRING, icon: STRING };
+var COMPONENTS = {
+  Accordion: {
+    attributes: { title: STRING, icon: STRING, defaultOpen: BOOLEAN },
+    required: ["title"]
+  },
+  AccordionGroup: { attributes: {} },
+  AppPreview: {
+    attributes: {
+      url: STRING,
+      query: STRING,
+      tool: STRING,
+      response: STRING,
+      entities: STRING,
+      relationships: STRING
+    },
+    required: ["query", "tool", "response", "entities", "relationships"]
+  },
+  BrandAsset: {
+    attributes: {
+      title: STRING,
+      src: SRC,
+      alt: STRING,
+      surface: ["light", "dark", "neutral"],
+      background: "color",
+      description: STRING,
+      downloadLabel: STRING
+    },
+    required: ["title", "src", "alt"],
+    empty: true
+  },
+  Callout: {
+    attributes: {
+      type: ["note", "info", "tip", "warning", "check", "danger"],
+      title: STRING,
+      icon: STRING
+    }
+  },
+  Card: { attributes: { title: STRING, icon: STRING, href: HREF } },
+  CardGroup: { attributes: { cols: "cols" } },
+  Check: { attributes: CALLOUT_ATTRIBUTES },
+  CodeGroup: { attributes: { label: STRING } },
+  Columns: { attributes: { cols: "cols" } },
+  ColorSwatch: {
+    attributes: { name: STRING, value: "color", usage: STRING },
+    required: ["name", "value"],
+    empty: true
+  },
+  CommandStep: {
+    attributes: { number: STRING, title: STRING, command: STRING },
+    required: ["number", "title", "command"],
+    empty: true
+  },
+  CommandTimeline: { attributes: {} },
+  Danger: { attributes: CALLOUT_ATTRIBUTES },
+  DomainCard: {
+    attributes: { name: STRING, emoji: STRING, domain: STRING, entities: STRING },
+    required: ["name", "emoji", "domain", "entities"],
+    empty: true
+  },
+  DomainCarousel: { attributes: {} },
+  Expandable: {
+    attributes: { title: STRING, defaultOpen: BOOLEAN },
+    required: ["title"]
+  },
+  FooterColumn: { attributes: { title: STRING }, required: ["title"] },
+  Frame: { attributes: { caption: STRING, surface: ["default", "light", "dark"] } },
+  FrameworkCard: {
+    attributes: { title: STRING, support: ["Full Streaming", "Tool Events"] },
+    required: ["title", "support"]
+  },
+  FrameworkGrid: { attributes: {} },
+  Icon: {
+    attributes: { icon: STRING, size: "iconSize" },
+    required: ["icon"],
+    empty: true
+  },
+  Info: { attributes: CALLOUT_ATTRIBUTES },
+  LandingCta: {
+    attributes: {
+      title: STRING,
+      description: STRING,
+      primaryLabel: STRING,
+      primaryHref: HREF,
+      secondaryLabel: STRING,
+      secondaryHref: HREF
+    },
+    required: ["title"]
+  },
+  LandingFooter: {
+    attributes: { name: STRING, logo: SRC, description: STRING },
+    required: ["name"]
+  },
+  LandingHero: {
+    attributes: {
+      title: STRING,
+      description: STRING,
+      eyebrow: STRING,
+      primaryLabel: STRING,
+      primaryHref: HREF,
+      secondaryLabel: STRING,
+      secondaryHref: HREF,
+      align: ["left", "center"],
+      visualMode: ["static", "sequence"],
+      terminalLabel: STRING,
+      previewLabel: STRING
+    },
+    required: ["title"]
+  },
+  LandingSection: {
+    attributes: {
+      title: STRING,
+      description: STRING,
+      eyebrow: STRING,
+      align: ["left", "center"],
+      tone: ["default", "muted", "accent"]
+    },
+    required: ["title"]
+  },
+  MemorySequence: { attributes: {} },
+  MemoryStage: {
+    attributes: {
+      stage: ["short", "long", "reasoning", "connected"],
+      badge: STRING,
+      title: STRING,
+      description: STRING
+    },
+    required: ["stage", "badge", "title", "description"],
+    empty: true
+  },
+  Note: { attributes: CALLOUT_ATTRIBUTES },
+  ParamField: {
+    attributes: {
+      path: STRING,
+      name: STRING,
+      query: STRING,
+      body: STRING,
+      type: STRING,
+      required: BOOLEAN,
+      default: "default"
+    }
+  },
+  PortalCard: {
+    attributes: { title: STRING, icon: STRING, href: HREF, description: STRING },
+    required: ["title", "href"]
+  },
+  ResponseField: {
+    attributes: { name: STRING, type: STRING, required: BOOLEAN },
+    required: ["name"]
+  },
+  Stat: {
+    attributes: {
+      label: STRING,
+      value: "numberOrString",
+      caption: STRING,
+      title: STRING,
+      accent: BOOLEAN,
+      bare: BOOLEAN
+    },
+    required: ["label", "value"]
+  },
+  Step: { attributes: { title: STRING } },
+  Steps: { attributes: {} },
+  Tab: { attributes: { title: STRING }, required: ["title"] },
+  Tabs: { attributes: { label: STRING } },
+  TerminalWindow: { attributes: { title: STRING, command: STRING, variant: ["default", "showcase", "compact"] } },
+  Tip: { attributes: CALLOUT_ATTRIBUTES },
+  TypeSpecimen: {
+    attributes: {
+      family: STRING,
+      role: STRING,
+      weights: STRING,
+      sample: STRING,
+      variant: ["body", "heading", "mono"]
+    },
+    required: ["family", "role", "weights", "sample", "variant"],
+    empty: true
+  },
+  UsageExample: {
+    attributes: { verdict: ["do", "dont"], title: STRING },
+    required: ["verdict", "title"]
+  },
+  Video: {
+    attributes: {
+      src: SRC,
+      title: STRING,
+      summary: STRING,
+      caption: STRING,
+      poster: SRC,
+      kind: ["auto", "video", "iframe"]
+    },
+    required: ["src", "title"]
+  },
+  Warning: { attributes: CALLOUT_ATTRIBUTES }
+};
+var NATIVE_ELEMENTS = {
+  img: {
+    attributes: { src: SRC, alt: STRING, width: "dimension", height: "dimension" },
+    required: ["src"],
+    empty: true
+  },
+  kbd: { attributes: {} }
+};
+var STANDARD_NODES = /* @__PURE__ */ new Set([
+  "blockquote",
+  "break",
+  "code",
+  "definition",
+  "delete",
+  "emphasis",
+  "heading",
+  "image",
+  "imageReference",
+  "inlineCode",
+  "link",
+  "linkReference",
+  "list",
+  "listItem",
+  "paragraph",
+  "root",
+  "strong",
+  "table",
+  "tableCell",
+  "tableRow",
+  "text",
+  "thematicBreak"
+]);
+var markdownParser = unified().use(remarkParse).use(remarkGfm);
+var mdxParser = unified().use(remarkParse).use(remarkMdx).use(remarkGfm);
+function issue(message) {
+  return { code: "inadmissible_page_content", message };
+}
+function expressionValue(attribute) {
+  return attribute.value && typeof attribute.value === "object" ? attribute.value.value : null;
+}
+function directBoolean(attribute) {
+  if (attribute.value === null) return true;
+  const value = expressionValue(attribute);
+  return value === "true" || value === "false";
+}
+function directNumber(attribute) {
+  const value = expressionValue(attribute);
+  if (value === null || !/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+function safeUrl(raw, context) {
+  if (raw.length === 0 || raw.trim() !== raw || /[\u0000-\u001f\u007f]/.test(raw) || /\s/u.test(raw) || raw.includes("\\") || raw.startsWith("//")) {
+    return false;
+  }
+  if (raw.startsWith("/") || raw.startsWith("./") || raw.startsWith("../") || raw.startsWith("#") || raw.startsWith("?")) {
+    return true;
+  }
+  const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(raw)?.[1]?.toLowerCase();
+  if (scheme !== void 0) {
+    return scheme === "http" || scheme === "https" || context === "href" && scheme === "mailto";
+  }
+  return !raw.includes(":");
+}
+function validAttribute(attribute, kind) {
+  if (attribute.type !== "mdxJsxAttribute") return false;
+  if (kind === "boolean") return directBoolean(attribute);
+  if (kind === "color") {
+    return typeof attribute.value === "string" && /^#[0-9A-Fa-f]{6}$/.test(attribute.value);
+  }
+  if (kind === "cols") {
+    const value = directNumber(attribute);
+    return value !== null && Number.isInteger(value) && value >= 1 && value <= 6;
+  }
+  if (kind === "default") {
+    return typeof attribute.value === "string" || directBoolean(attribute) || directNumber(attribute) !== null;
+  }
+  if (kind === "numberOrString") {
+    return typeof attribute.value === "string" || directNumber(attribute) !== null;
+  }
+  if (kind === "dimension") {
+    if (typeof attribute.value === "string") return /^(?:0|[1-9]\d*)$/.test(attribute.value);
+    const value = directNumber(attribute);
+    return value !== null && Number.isInteger(value) && value >= 0;
+  }
+  if (kind === "iconSize") {
+    if (typeof attribute.value === "string") {
+      const match = /^(0|(?:0|[1-9]\d*)(?:\.\d+)?)(px|rem|em)?$/.exec(attribute.value);
+      return match !== null && Number(match[1]) <= 512;
+    }
+    const value = directNumber(attribute);
+    return value !== null && value >= 0 && value <= 512;
+  }
+  if (kind === "href" || kind === "src") {
+    return typeof attribute.value === "string" && safeUrl(attribute.value, kind);
+  }
+  if (kind === "string") return typeof attribute.value === "string";
+  return typeof attribute.value === "string" && kind.includes(attribute.value);
+}
+function validateElement(node) {
+  if (node.name === null || node.name === void 0) return issue("MDX fragments are not admissible");
+  const policy = COMPONENTS[node.name] ?? NATIVE_ELEMENTS[node.name];
+  if (policy === void 0) return issue(`element ${node.name} is not admissible`);
+  const seen = /* @__PURE__ */ new Set();
+  for (const attribute of node.attributes ?? []) {
+    if (attribute.type !== "mdxJsxAttribute" || attribute.name === void 0) {
+      return issue(`spread attributes are not admissible on ${node.name}`);
+    }
+    if (seen.has(attribute.name)) return issue(`duplicate attribute ${attribute.name} on ${node.name}`);
+    seen.add(attribute.name);
+    const kind = policy.attributes[attribute.name];
+    if (kind === void 0) return issue(`attribute ${attribute.name} is not admissible on ${node.name}`);
+    if (!validAttribute(attribute, kind)) {
+      return issue(`attribute ${attribute.name} has an inadmissible value on ${node.name}`);
+    }
+  }
+  for (const required of policy.required ?? []) {
+    if (!seen.has(required)) return issue(`attribute ${required} is required on ${node.name}`);
+  }
+  if (policy.empty && (node.children?.length ?? 0) > 0) return issue(`${node.name} must not have children`);
+  return null;
+}
+function validatePageSource(path, source, policy = {}) {
+  let tree;
+  try {
+    tree = (path.toLowerCase().endsWith(".mdx") ? mdxParser : markdownParser).parse(source);
+  } catch (error) {
+    return {
+      code: "invalid_page_syntax",
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const definitions = /* @__PURE__ */ new Map();
+  const collectDefinitions = (node) => {
+    if (node.type === "definition" && node.identifier !== void 0 && node.url !== void 0) {
+      definitions.set(node.identifier, node.url);
+    }
+    for (const child of node.children ?? []) collectDefinitions(child);
+  };
+  collectDefinitions(tree);
+  const visit = (node) => {
+    if (node.type === "heading" && node.depth === 1 && policy.allowLevelOneHeading === false) {
+      return {
+        code: "page_heading_conflict",
+        message: "standard documentation pages receive their level-one heading from frontmatter title; remove the authored level-one heading or set pageHeader: false when the page owns its title"
+      };
+    }
+    if (node.type === "mdxjsEsm") return issue("ESM is not admissible in page source");
+    if (node.type === "mdxFlowExpression" || node.type === "mdxTextExpression") {
+      return issue("MDX expressions are not admissible in page content");
+    }
+    if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
+      const elementIssue = validateElement(node);
+      if (elementIssue !== null) return elementIssue;
+    } else if (node.type === "html") {
+      return issue("raw HTML is not admissible in page source");
+    } else if (!STANDARD_NODES.has(node.type)) {
+      return issue(`syntax node ${node.type} is not admissible`);
+    }
+    if ((node.type === "link" || node.type === "definition") && node.url !== void 0) {
+      if (!safeUrl(node.url, "href")) return issue(`URL scheme is not admissible: ${node.url}`);
+    }
+    if (node.type === "image" && node.url !== void 0 && !safeUrl(node.url, "src")) {
+      return issue(`image URL scheme is not admissible: ${node.url}`);
+    }
+    if (node.type === "linkReference" && node.identifier !== void 0) {
+      const url = definitions.get(node.identifier);
+      if (url !== void 0 && !safeUrl(url, "href")) return issue(`URL scheme is not admissible: ${url}`);
+    }
+    if (node.type === "imageReference" && node.identifier !== void 0) {
+      const url = definitions.get(node.identifier);
+      if (url !== void 0 && !safeUrl(url, "src")) return issue(`image URL scheme is not admissible: ${url}`);
+    }
+    for (const child of node.children ?? []) {
+      const childIssue = visit(child);
+      if (childIssue !== null) return childIssue;
+    }
+    return null;
+  };
+  return visit(tree);
+}
+var RUNBOOK_MIN_STEPS = 3;
+var RUNBOOK_MAX_STEPS = 8;
+var RUNBOOK_MAX_STEP_WORDS = 40;
+var RUNBOOK_TARGETS = ["code", "workspace"];
+var RUNBOOK_KEYS = ["goal", "prerequisites", "steps", "expected", "verify", "target"];
+var RUNBOOK_KEY_SET = new Set(RUNBOOK_KEYS);
+var LINE_BREAK = /[\r\n]/;
+var CONTROL_CHARACTER = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function filledString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function wordCount(value) {
+  return value.trim().split(/\s+/).length;
+}
+function proseProblems(value, field) {
+  const problems = [];
+  if (LINE_BREAK.test(value)) {
+    problems.push(
+      `runbook.${field} must not contain a line break. Move long context into the page body.`
+    );
+  }
+  if (CONTROL_CHARACTER.test(value)) {
+    problems.push(`runbook.${field} must not contain a control character.`);
+  }
+  return problems;
+}
+function stringListProblems(value, field) {
+  if (!Array.isArray(value)) return [`runbook.${field} must be a list of strings.`];
+  return value.flatMap(
+    (entry, index) => filledString(entry) ? [] : [`runbook.${field}[${index}] must be a non-empty string.`]
+  );
+}
+function runbookProblems(value) {
+  if (!isRecord(value)) return ["runbook must be an object with goal, steps, expected, and verify."];
+  const problems = [];
+  for (const key of Object.keys(value)) {
+    if (!RUNBOOK_KEY_SET.has(key)) {
+      problems.push(
+        `runbook.${key} is not a runbook field. Allowed fields: ${RUNBOOK_KEYS.join(", ")}.`
+      );
+    }
+  }
+  for (const field of ["goal", "expected", "verify"]) {
+    const entry = value[field];
+    if (!filledString(entry)) {
+      problems.push(`runbook.${field} is required and must be a non-empty string.`);
+      continue;
+    }
+    problems.push(...proseProblems(entry, field));
+  }
+  if (value["prerequisites"] !== void 0) {
+    const listProblems = stringListProblems(value["prerequisites"], "prerequisites");
+    problems.push(...listProblems);
+    if (listProblems.length === 0) {
+      for (const [index, entry] of value["prerequisites"].entries()) {
+        problems.push(...proseProblems(entry, `prerequisites[${index}]`));
+      }
+    }
+  }
+  if (value["steps"] === void 0) {
+    problems.push("runbook.steps is required and must be a list of strings.");
+  } else {
+    const listProblems = stringListProblems(value["steps"], "steps");
+    problems.push(...listProblems);
+    if (listProblems.length === 0) {
+      const steps = value["steps"];
+      if (steps.length < RUNBOOK_MIN_STEPS || steps.length > RUNBOOK_MAX_STEPS) {
+        problems.push(
+          `runbook.steps must hold ${RUNBOOK_MIN_STEPS} to ${RUNBOOK_MAX_STEPS} steps, not ${steps.length}. Move long context into the page body.`
+        );
+      }
+      for (const [index, step] of steps.entries()) {
+        problems.push(...proseProblems(step, `steps[${index}]`));
+        if (wordCount(step) > RUNBOOK_MAX_STEP_WORDS) {
+          problems.push(
+            `runbook.steps[${index}] is ${wordCount(step)} words. A step may hold at most ${RUNBOOK_MAX_STEP_WORDS} words.`
+          );
+        }
+      }
+    }
+  }
+  const target = value["target"];
+  if (target !== void 0 && !RUNBOOK_TARGETS.includes(target)) {
+    problems.push(`runbook.target must be ${RUNBOOK_TARGETS.join(" or ")}.`);
+  }
+  return problems;
+}
+var fatalUtf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+var boundedUtf8Decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+var textEncoder3 = new TextEncoder();
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function addViolation(violations, path, code, message) {
+  violations.push({ path, code, severity: "error", message });
+}
+function decodeUtf8(bytes, path, violations, maxBytes) {
+  if (maxBytes !== void 0 && bytes.byteLength > maxBytes) {
+    addViolation(
+      violations,
+      path,
+      "semantic_input_too_large",
+      `${path} exceeds ${maxBytes} bytes`
+    );
+    return null;
+  }
+  try {
+    const source = fatalUtf8Decoder.decode(bytes);
+    if (source.startsWith("\uFEFF")) {
+      addViolation(violations, path, "invalid_utf8", `${path} must not begin with a UTF-8 BOM`);
+      return null;
+    }
+    return source;
+  } catch (error) {
+    addViolation(
+      violations,
+      path,
+      "invalid_utf8",
+      `${path} is not valid UTF-8: ${errorMessage(error)}`
+    );
+    return null;
+  }
+}
+function readSemanticFile(input, path, violations) {
+  try {
+    const bytes = input.readFile(path);
+    return bytes === null ? { present: false, bytes: null } : { present: true, bytes };
+  } catch (error) {
+    addViolation(violations, path, "read_error", errorMessage(error));
+    return { present: true, bytes: null };
+  }
+}
+function parseDocsJson(bytes, violations) {
+  const source = decodeUtf8(bytes, "docs.json", violations, SOURCE_LIMITS.maxDocsJsonBytes);
+  if (source === null) return null;
+  try {
+    const document = parseDocument(source, { schema: "json", uniqueKeys: true });
+    if (document.errors.length > 0) throw document.errors[0];
+  } catch (error) {
+    addViolation(
+      violations,
+      "docs.json",
+      "invalid_docs_json",
+      `docs.json has duplicate keys or invalid JSON structure: ${errorMessage(error)}`
+    );
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (error) {
+    addViolation(
+      violations,
+      "docs.json",
+      "invalid_docs_json",
+      `docs.json is not valid JSON: ${errorMessage(error)}`
+    );
+    return null;
+  }
+  try {
+    return parseDocsConfig(parsed);
+  } catch (error) {
+    addViolation(violations, "docs.json", "invalid_docs_json", errorMessage(error));
+    return null;
+  }
+}
+function frontmatterPolicy(bytes) {
+  let openingLength = 0;
+  if (bytes[0] === 45 && bytes[1] === 45 && bytes[2] === 45) {
+    let index = 3;
+    while (bytes[index] === 32 || bytes[index] === 9) index += 1;
+    if (bytes[index] === 10) openingLength = index + 1;
+    else if (bytes[index] === 13 && bytes[index + 1] === 10) openingLength = index + 2;
+    else if (index < bytes.byteLength) throw new Error("frontmatter opening marker is malformed");
+  }
+  if (openingLength === 0) {
+    return {
+      grouped: false,
+      pagefindFalse: false,
+      pageLayout: "docs",
+      pageHeader: true,
+      bodyOffset: 0
+    };
+  }
+  const searchEnd = Math.min(
+    bytes.byteLength,
+    openingLength + SOURCE_LIMITS.maxFrontmatterBytes
+  );
+  const bounded = boundedUtf8Decoder.decode(bytes.subarray(openingLength, searchEnd));
+  const closing = /(?:^|\r?\n)---[\t ]*(?:\r?\n|$)/.exec(bounded);
+  if (!closing) {
+    throw new Error(
+      `frontmatter closing marker was not found within ${SOURCE_LIMITS.maxFrontmatterBytes} bytes`
+    );
+  }
+  const block = bounded.slice(0, closing.index);
+  if (textEncoder3.encode(block).byteLength > SOURCE_LIMITS.maxFrontmatterBytes) {
+    throw new Error(`frontmatter exceeds ${SOURCE_LIMITS.maxFrontmatterBytes} bytes`);
+  }
+  const bodyOffset = openingLength + textEncoder3.encode(bounded.slice(0, closing.index + closing[0].length)).byteLength;
+  const parsed = parse(block, {
+    maxAliasCount: 0,
+    schema: "core",
+    uniqueKeys: true
+  });
+  if (parsed === null || parsed === void 0) {
+    return {
+      grouped: false,
+      pagefindFalse: false,
+      pageLayout: "docs",
+      pageHeader: true,
+      bodyOffset
+    };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("frontmatter must be a top-level YAML mapping");
+  }
+  const record = parsed;
+  const allowed = /* @__PURE__ */ new Set([
+    "title",
+    "description",
+    "pageLayout",
+    "groups",
+    "pagefind",
+    "noindex",
+    "public",
+    "pageHeader",
+    "runbook"
+  ]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) throw new Error(`frontmatter key is not admissible: ${key}`);
+  }
+  for (const key of ["title", "description"]) {
+    if (record[key] !== void 0 && typeof record[key] !== "string") {
+      throw new Error(`frontmatter ${key} must be a string`);
+    }
+  }
+  if (record["pageLayout"] !== void 0 && !["docs", "landing"].includes(String(record["pageLayout"]))) {
+    throw new Error("frontmatter pageLayout must be docs or landing");
+  }
+  if (record["groups"] !== void 0 && (!Array.isArray(record["groups"]) || record["groups"].some((group) => typeof group !== "string"))) {
+    throw new Error("frontmatter groups must be an array of strings");
+  }
+  for (const key of ["pagefind", "noindex", "public", "pageHeader"]) {
+    if (record[key] !== void 0 && typeof record[key] !== "boolean") {
+      throw new Error(`frontmatter ${key} must be a boolean`);
+    }
+  }
+  if (record["runbook"] !== void 0) {
+    const problems = runbookProblems(record["runbook"]);
+    if (problems.length > 0) {
+      throw new Error(`frontmatter runbook is invalid: ${problems.join(" ")}`);
+    }
+  }
+  return {
+    grouped: Array.isArray(record["groups"]) && record["groups"].length > 0,
+    pagefindFalse: record["pagefind"] === false,
+    pageLayout: record["pageLayout"] === "landing" ? "landing" : "docs",
+    pageHeader: record["pageHeader"] !== false,
+    bodyOffset
+  };
+}
+function pageCandidates(entry) {
+  const mdx = `pages/${entry}.mdx`;
+  const md = `pages/${entry}.md`;
+  if (canonicalizeSourcePath(mdx) !== mdx || canonicalizeSourcePath(md) !== md) return null;
+  return { mdx, md };
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasExternalRef(value, seen = /* @__PURE__ */ new Set()) {
+  if (typeof value !== "object" || value === null) return false;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  if (Array.isArray(value)) return value.some((item) => hasExternalRef(item, seen));
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "$ref" && typeof child === "string") {
+      const hash = child.indexOf("#");
+      const filePart = hash === -1 ? child : child.slice(0, hash);
+      if (filePart.length > 0) return true;
+    }
+    if (hasExternalRef(child, seen)) return true;
+  }
+  return false;
+}
+function validateOpenApiDocument(source) {
+  const document = parse(source, {
+    maxAliasCount: 0,
+    schema: "core",
+    uniqueKeys: true
+  });
+  if (!isRecord2(document)) throw new Error("OpenAPI document must be an object");
+  const isOpenApi3 = typeof document["openapi"] === "string" && /^3\./.test(document["openapi"]);
+  const isSwagger2 = document["swagger"] === "2.0";
+  if (!isOpenApi3 && !isSwagger2) {
+    throw new Error("document must declare top-level openapi 3.x or swagger 2.0");
+  }
+  if (hasExternalRef(document)) {
+    throw new Error(`external OpenAPI $ref values are not admissible in source ABI v${SOURCE_ABI_VERSION}`);
+  }
+  parseOpenApi(source);
+}
+function prepareSemanticValidation(input) {
+  const violations = [];
+  const config = parseDocsJson(input.docsJson, violations);
+  if (config === null) return { config, pagePaths: [], pagePathSet: /* @__PURE__ */ new Set(), violations };
+  if (input.modelsToml !== void 0) {
+    const source = decodeUtf8(
+      input.modelsToml,
+      "models.toml",
+      violations,
+      SOURCE_LIMITS.maxModelsTomlBytes
+    );
+    if (source !== null) {
+      try {
+        parseModelsConfig(source);
+      } catch (error) {
+        addViolation(violations, "models.toml", "invalid_models_toml", errorMessage(error));
+      }
+    }
+  }
+  const pagePaths = [...input.pagePaths].sort();
+  const pagePathSet = /* @__PURE__ */ new Set();
+  for (const path of pagePaths) {
+    const extension = sourceExtension(path);
+    if (pagePathSet.has(path) || !path.startsWith("pages/") || canonicalizeSourcePath(path) !== path || extension !== ".md" && extension !== ".mdx") {
+      addViolation(
+        violations,
+        path,
+        "inadmissible_page_content",
+        `page path is not a unique canonical page source path: ${path}`
+      );
+      continue;
+    }
+    pagePathSet.add(path);
+  }
+  return { config, pagePaths, pagePathSet, violations };
+}
+function validatePageBytes(path, bytes, violations) {
+  const source = decodeUtf8(bytes, path, violations);
+  if (source === null) return;
+  try {
+    const policy = frontmatterPolicy(bytes);
+    if (policy.grouped && !policy.pagefindFalse) {
+      addViolation(
+        violations,
+        path,
+        "pagefind_required",
+        "grouped pages must set pagefind: false"
+      );
+    }
+    const body = fatalUtf8Decoder.decode(bytes.subarray(policy.bodyOffset));
+    const pageIssue = validatePageSource(path, body, {
+      allowLevelOneHeading: policy.pageLayout === "landing" || !policy.pageHeader
+    });
+    if (pageIssue !== null) addViolation(violations, path, pageIssue.code, pageIssue.message);
+  } catch (error) {
+    addViolation(violations, path, "invalid_frontmatter", errorMessage(error));
+  }
+}
+function validateNavigation(config, prepared) {
+  const { pagePaths, pagePathSet, violations } = prepared;
+  const pages = new Set(navigationGroups(config).flatMap((group) => group.pages));
+  const referencedPagePaths = /* @__PURE__ */ new Set();
+  for (const entry of pages) {
+    const candidates = pageCandidates(entry);
+    if (!candidates) {
+      addViolation(
+        violations,
+        "docs.json",
+        "invalid_navigation_path",
+        `navigation page is not a canonical source path: ${entry}`
+      );
+      continue;
+    }
+    const hasMdx = pagePathSet.has(candidates.mdx);
+    const hasMd = pagePathSet.has(candidates.md);
+    if (hasMdx) referencedPagePaths.add(candidates.mdx);
+    if (hasMd) referencedPagePaths.add(candidates.md);
+    if (hasMdx && hasMd) {
+      addViolation(
+        violations,
+        candidates.mdx,
+        "md_mdx_collision",
+        `navigation page resolves to both ${candidates.mdx} and ${candidates.md}`
+      );
+      continue;
+    }
+    if (!hasMdx && !hasMd) {
+      addViolation(
+        violations,
+        candidates.mdx,
+        "missing_page",
+        `navigation page ${entry} has no .mdx or .md source file`
+      );
+    }
+  }
+  for (const path of pagePaths) {
+    if (!referencedPagePaths.has(path)) {
+      addViolation(
+        violations,
+        path,
+        "unreferenced_page",
+        `page source is not referenced by docs.json navigation: ${path}`
+      );
+    }
+  }
+}
+function openApiPaths(config, violations) {
+  const valid = [];
+  const paths = new Set(
+    navigationGroups(config).map((group) => group.openapi).filter((path) => path !== void 0)
+  );
+  for (const path of paths) {
+    const extension = sourceExtension(path);
+    if (!path.startsWith("openapi/") || canonicalizeSourcePath(path) !== path || extension !== ".json" && extension !== ".yaml" && extension !== ".yml") {
+      addViolation(
+        violations,
+        "docs.json",
+        "invalid_openapi_path",
+        `OpenAPI path must be a canonical openapi/** path: ${path}`
+      );
+    } else {
+      valid.push(path);
+    }
+  }
+  return valid;
+}
+function validateOpenApiBytes(path, bytes, violations) {
+  const source = decodeUtf8(bytes, path, violations, SOURCE_LIMITS.maxOpenApiBytes);
+  if (source === null) return;
+  try {
+    validateOpenApiDocument(source);
+  } catch (error) {
+    addViolation(violations, path, "invalid_openapi", errorMessage(error));
+  }
+}
+function validateBundleSemantics(input) {
+  const prepared = prepareSemanticValidation(input);
+  if (!prepared.config) return sortViolations(prepared.violations);
+  for (const path of prepared.pagePaths) {
+    if (!prepared.pagePathSet.has(path)) continue;
+    const read = readSemanticFile(input, path, prepared.violations);
+    if (!read.present) {
+      addViolation(prepared.violations, path, "read_error", "listed page source is missing");
+      continue;
+    }
+    if (read.bytes === null) continue;
+    validatePageBytes(path, read.bytes, prepared.violations);
+  }
+  validateNavigation(prepared.config, prepared);
+  for (const path of openApiPaths(prepared.config, prepared.violations)) {
+    const read = readSemanticFile(input, path, prepared.violations);
+    if (!read.present) {
+      addViolation(prepared.violations, path, "missing_openapi", "referenced OpenAPI file is missing");
+      continue;
+    }
+    if (read.bytes === null) continue;
+    validateOpenApiBytes(path, read.bytes, prepared.violations);
+  }
+  return sortViolations(prepared.violations);
+}
+var encoder = new TextEncoder();
+var TAR_BLOCK_SIZE = 512;
+var TAR_TRAILER_SIZE = 1024;
+function tarPadding(size) {
+  return (TAR_BLOCK_SIZE - size % TAR_BLOCK_SIZE) % TAR_BLOCK_SIZE;
+}
+function writeText(target, offset, length, value) {
+  target.set(encoder.encode(value).subarray(0, length), offset);
+}
+function octal(value, length) {
+  return `${value.toString(8).padStart(length - 1, "0")}\0`;
+}
+function tarHeader(name, size, options = {}) {
+  const header = new Uint8Array(TAR_BLOCK_SIZE);
+  writeText(header, 0, 100, name);
+  writeText(header, 100, 8, octal(options.mode ?? 420, 8));
+  writeText(header, 108, 8, octal(0, 8));
+  writeText(header, 116, 8, octal(0, 8));
+  writeText(header, 124, 12, octal(size, 12));
+  writeText(header, 136, 12, octal(0, 12));
+  header.fill(32, 148, 156);
+  header[156] = (options.type ?? "0").charCodeAt(0);
+  writeText(header, 257, 6, "ustar\0");
+  writeText(header, 263, 2, "00");
+  const checksum = header.reduce((sum, byte) => sum + byte, 0);
+  writeText(header, 148, 8, `${checksum.toString(8).padStart(6, "0")}\0 `);
+  return header;
+}
+function paxRecord(key, value) {
+  let length = encoder.encode(`${key}=${value}
+`).byteLength + 3;
+  for (; ; ) {
+    const record = encoder.encode(`${length} ${key}=${value}
+`);
+    if (record.byteLength === length) return record;
+    length = record.byteLength;
+  }
+}
+
+// src/lib/bundle.ts
+var encoder2 = new TextEncoder();
+async function collectDirectory(root, relative, files) {
+  const absolute = join(root, ...relative.split("/"));
+  const entries = await readdir(absolute, { withFileTypes: true });
+  for (const entry of entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)) {
+    const path = posix.join(relative, entry.name);
+    const absolutePath = join(root, ...path.split("/"));
+    if (entry.isSymbolicLink()) throw new Error(`source bundle cannot contain a symbolic link: ${path}`);
+    if (entry.isDirectory()) await collectDirectory(root, path, files);
+    else if (entry.isFile()) files.push({ path, absolutePath, bytes: new Uint8Array(await readFile(absolutePath)) });
+    else throw new Error(`source bundle contains an unsupported filesystem entry: ${path}`);
+  }
+}
+async function collectSourceFiles(docsDir) {
+  const files = [];
+  for (const [legacy, replacement] of [["assets", "public"], ["api-reference", "openapi"]]) {
+    if (await lstat(join(docsDir, legacy)).catch(() => null) !== null) {
+      throw new Error(`legacy ${legacy}/ source is not publishable; move it to ${replacement}/`);
+    }
+  }
+  for (const name of ["docs.json", "models.toml"]) {
+    const absolutePath = join(docsDir, name);
+    const info = await lstat(absolutePath).catch(() => null);
+    if (info === null) continue;
+    if (info.isSymbolicLink() || !info.isFile()) throw new Error(`${name} must be a regular file`);
+    files.push({ path: name, absolutePath, bytes: new Uint8Array(await readFile(absolutePath)) });
+  }
+  for (const name of ["pages", "public", "openapi"]) {
+    const absolutePath = join(docsDir, name);
+    const info = await lstat(absolutePath).catch(() => null);
+    if (info === null) continue;
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`${name} must be a regular directory`);
+    await collectDirectory(docsDir, name, files);
+  }
+  return files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+}
+function validateSourceFiles(files) {
+  const structural = validateBundleStructure(files.map((file) => ({ path: file.path, size: file.bytes.byteLength })));
+  const errors = structural.filter((violation) => violation.severity === "error");
+  if (errors.length > 0) throw new Error(errors.map((violation) => `${violation.path ?? "bundle"}: ${violation.message}`).join("\n"));
+  const byPath = new Map(files.map((file) => [file.path, file.bytes]));
+  const semantic = validateBundleSemantics({
+    docsJson: byPath.get("docs.json") ?? new Uint8Array(),
+    modelsToml: byPath.get("models.toml"),
+    pagePaths: files.map((file) => file.path).filter((path) => path.startsWith("pages/") && /\.(?:md|mdx)$/i.test(path)),
+    readFile: (path) => byPath.get(path) ?? null
+  });
+  if (semantic.length > 0) throw new Error(semantic.map((violation) => `${violation.path ?? "bundle"}: ${violation.message}`).join("\n"));
+  return structural.filter((violation) => violation.severity === "warning");
+}
+async function* tarEntries(files) {
+  for (let index = 0; index < files.length; index += 1) {
+    const file = files[index];
+    let headerName = file.path;
+    if (encoder2.encode(file.path).byteLength > 100) {
+      const pax = paxRecord("path", file.path);
+      yield tarHeader(`PaxHeaders/${index}`, pax.byteLength, { type: "x", mode: 384 });
+      yield pax;
+      const paxPadding = tarPadding(pax.byteLength);
+      if (paxPadding > 0) yield new Uint8Array(paxPadding);
+      headerName = `file-${index}`;
+    }
+    yield tarHeader(headerName, file.bytes.byteLength);
+    yield file.bytes;
+    const filePadding = tarPadding(file.bytes.byteLength);
+    if (filePadding > 0) yield new Uint8Array(filePadding);
+  }
+  yield new Uint8Array(TAR_TRAILER_SIZE);
+}
+async function fileSha256(path) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest("hex");
+}
+async function createBundleArchive(inputDir) {
+  const docsDir = resolve(inputDir);
+  const info = await lstat(docsDir).catch(() => null);
+  if (info === null || !info.isDirectory() || info.isSymbolicLink()) throw new Error(`docs directory not found: ${docsDir}`);
+  const files = await collectSourceFiles(docsDir);
+  const warnings = validateSourceFiles(files);
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "saturndocs-deploy-"));
+  await mkdir(temporaryRoot, { recursive: true });
+  const archivePath = join(temporaryRoot, "source.tar.gz");
+  try {
+    await pipeline(Readable.from(tarEntries(files)), createGzip({ level: 9 }), createWriteStream(archivePath, { mode: 384 }));
+    const archiveInfo = await stat(archivePath);
+    return {
+      path: archivePath,
+      byteLength: archiveInfo.size,
+      sha256: await fileSha256(archivePath),
+      warnings,
+      cleanup: () => rm(temporaryRoot, { recursive: true, force: true })
+    };
+  } catch (error) {
+    await rm(temporaryRoot, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+// src/commands/deploy.ts
+var DEFAULT_API_URL = "https://saturndocs-ops.saturndocs.workers.dev";
+var TERMINAL_STATES = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled", "superseded", "timed_out"]);
+function trimSlash(value) {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+async function responseValue(response) {
+  const value = await response.json().catch(() => null);
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function apiError(response, value) {
+  const code = typeof value.code === "string" ? value.code : `http_${response.status}`;
+  const message = typeof value.error === "string" ? value.error : "request failed";
+  return new Error(`${code}: ${message}`);
+}
+async function deployBundle(input) {
+  const archive = await createBundleArchive(input.docsDir);
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const apiUrl = trimSlash(input.apiUrl);
+  const idempotencyKey = input.idempotencyKey ?? randomUUID();
+  try {
+    let accepted = {};
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      let response;
+      try {
+        response = await fetchImpl(`${apiUrl}/v1/deployments`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${input.token}`,
+            "content-type": "application/gzip",
+            "content-length": String(archive.byteLength),
+            "x-saturndocs-content-sha256": archive.sha256,
+            "x-saturndocs-idempotency-key": idempotencyKey,
+            "x-saturndocs-promote": String(input.promote)
+          },
+          body: createReadStream2(archive.path),
+          duplex: "half",
+          redirect: "error"
+        });
+      } catch (error) {
+        if (attempt === 2) throw error;
+        await new Promise((resolve2) => setTimeout(resolve2, 500));
+        continue;
+      }
+      accepted = await responseValue(response);
+      if (response.ok) break;
+      if (response.status === 503 && accepted.code === "queue_unavailable" && attempt < 2) {
+        await new Promise((resolve2) => setTimeout(resolve2, 500));
+        continue;
+      }
+      throw apiError(response, accepted);
+    }
+    if (typeof accepted.job_id !== "string" || typeof accepted.status_url !== "string") throw new Error("deployment response is invalid");
+    const statusUrl = new URL(accepted.status_url, `${apiUrl}/`);
+    if (statusUrl.origin !== new URL(apiUrl).origin) throw new Error("deployment status URL has an unexpected origin");
+    const startedAt = Date.now();
+    const timeoutMs = input.timeoutMs ?? 9e5;
+    let previousState = "";
+    for (; ; ) {
+      if (Date.now() - startedAt > timeoutMs) throw new Error(`deployment timed out after ${Math.ceil(timeoutMs / 1e3)} seconds`);
+      const statusResponse = await fetchImpl(statusUrl, { headers: { authorization: `Bearer ${input.token}` }, redirect: "error" });
+      const value = await responseValue(statusResponse);
+      if (!statusResponse.ok) throw apiError(statusResponse, value);
+      if (typeof value.job_id !== "string" || typeof value.state !== "string") throw new Error("job status response is invalid");
+      const status = value;
+      if (status.state !== previousState) {
+        previousState = status.state;
+        input.onState?.(status);
+      }
+      if (TERMINAL_STATES.has(status.state)) {
+        if (status.state !== "succeeded") throw new Error(`${status.error_code ?? status.state}: deployment ${status.state}`);
+        if (input.promote && (!Number.isSafeInteger(status.generation) || status.generation < 1)) {
+          throw new Error("promotion_not_applied: deployment succeeded without activating the release");
+        }
+        return status;
+      }
+      await new Promise((resolve2) => setTimeout(resolve2, input.pollIntervalMs ?? 2e3));
+    }
+  } finally {
+    await archive.cleanup();
+  }
+}
+function registerDeploy(program) {
+  program.command("deploy").description("Publish a docs directory through the SaturnDocs operations pipeline").argument("[dir]", "docs directory (contains docs.json)", ".").option("--api-url <url>", "operations API URL", process.env.SATURNDOCS_API_URL ?? DEFAULT_API_URL).option("--token <token>", "site-bound API token", process.env.SATURNDOCS_TOKEN).option("--candidate", "build a verified candidate without activating it").option("--timeout <seconds>", "maximum wait in seconds", "900").action(async (dir, options) => {
+    if (!options.token) throw new Error("SATURNDOCS_TOKEN or --token is required");
+    const timeoutSeconds = Number(options.timeout);
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) throw new Error("--timeout must be a positive number of seconds");
+    try {
+      const result = await deployBundle({
+        docsDir: dir,
+        apiUrl: options.apiUrl,
+        token: options.token,
+        promote: options.candidate !== true,
+        timeoutMs: timeoutSeconds * 1e3,
+        onState(status) {
+          console.log(pc.dim(`deployment ${status.state}`));
+        }
+      });
+      const outcome = result.generation === void 0 ? "verified candidate" : `served generation ${result.generation}`;
+      console.log(pc.green(`\u2713 ${outcome}: ${result.release_id ?? result.job_id}`));
+    } catch (error) {
+      console.error(pc.red(`error: ${messageOf(error)}`));
+      process.exitCode = 1;
+    }
+  });
+}
+
+export {
+  createBundleArchive,
+  deployBundle,
+  registerDeploy
+};