@mesh-tech/mesh-cli 0.36.0 → 0.38.0

package/dist/bin/mesh.chunk-2QIVBQX5.js

@@ -0,0 +1,647 @@
+// packages/api-registry/src/docs-source.ts
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+var PAGE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]*(?:\/[a-z0-9][a-z0-9_-]*)*$/;
+function isReaderFacingServerUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  const host = url.hostname.toLowerCase();
+  if (host.startsWith("[") || /^\d+(\.\d+){3}$/.test(host)) return false;
+  const labels = host.split(".");
+  if (labels.length < 2) return false;
+  const tld = labels[labels.length - 1];
+  if (["svc", "local", "internal", "localhost", "cluster"].includes(tld)) return false;
+  if (host.endsWith(".svc.cluster.local") || host.endsWith(".cluster.local")) return false;
+  return /^[a-z]{2,63}$/.test(tld) || /^xn--[a-z0-9-]{1,59}$/.test(tld);
+}
+function docsPage(bundle, id) {
+  return bundle && Object.hasOwn(bundle.pages, id) ? bundle.pages[id] : void 0;
+}
+var pageIdSchema = z.string().regex(PAGE_ID_PATTERN, "a page id is a lower-case path under pages/, without .md");
+var docsConfigSchema = z.object({
+  title: z.string().min(1),
+  description: z.string().min(1).optional(),
+  spec: z.string().min(1).optional(),
+  pages: z.string().min(1).optional(),
+  landing: pageIdSchema.optional(),
+  serverUrl: z.string().url().refine(isReaderFacingServerUrl, "serverUrl must be a reader-facing http(s) URL, never an in-cluster or local address").optional(),
+  nav: z.array(z.object({ group: z.string().min(1), pages: z.array(pageIdSchema).min(1) }).strict()).optional(),
+  reference: z.union([z.object({ label: z.string().min(1).optional() }).strict(), z.literal(false)]).optional(),
+  events: z.string().min(1).optional()
+}).strict();
+var OPERATION_AVAILABILITY_STATES = ["available", "not_enabled", "not_implemented", "not_supported"];
+var operationAvailabilitySchema = z.object({
+  state: z.enum(OPERATION_AVAILABILITY_STATES),
+  reason: z.string().min(1).optional()
+});
+var docsEventsCatalogSchema = z.object({
+  service: z.string().min(1),
+  types: z.array(
+    z.object({
+      name: z.string().min(1),
+      description: z.string().optional(),
+      schemaVersion: z.number().int().positive().optional(),
+      payloadSchema: z.record(z.string(), z.unknown()).optional()
+    })
+  ),
+  delivery: z.object({
+    payload: z.enum(["thin", "full"]).optional(),
+    retry: z.object({ maxAttempts: z.number().int().positive().optional() }).optional(),
+    signing: z.array(z.string().min(1)).optional()
+  }).optional()
+});
+var SANDBOX_MODES = ["live", "mock", "vendor-sandbox"];
+var sandboxModeSchema = z.enum(SANDBOX_MODES);
+var DEFAULT_SANDBOX_MODE = "live";
+function tryItAllows(method, mode = DEFAULT_SANDBOX_MODE) {
+  if (["GET", "HEAD", "OPTIONS"].includes(method.toUpperCase())) return true;
+  return mode === "mock" || mode === "vendor-sandbox";
+}
+var DOCS_IMAGE_CONTENT_TYPES = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp"
+};
+var MAX_DOCS_IMAGE_BYTES = 1024 * 1024;
+var MAX_DOCS_IMAGES_TOTAL_BYTES = 4 * 1024 * 1024;
+var IMAGE_KEY_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$/;
+var BASE64_PATTERN = /^[A-Za-z0-9+/]*={0,2}$/;
+function docsImageContentType(path) {
+  const dot = path.lastIndexOf(".");
+  const ext = dot === -1 ? "" : path.slice(dot + 1).toLowerCase();
+  return Object.hasOwn(DOCS_IMAGE_CONTENT_TYPES, ext) ? DOCS_IMAGE_CONTENT_TYPES[ext] : void 0;
+}
+function docsImageKey(pageId, src) {
+  if (!src || src.startsWith("/") || /[:?#\\]/.test(src)) return null;
+  let path;
+  try {
+    path = decodeURIComponent(src);
+  } catch {
+    return null;
+  }
+  if (/[:?#\\]/.test(path)) return null;
+  const parts = pageId.split("/").slice(0, -1);
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (parts.length === 0) return null;
+      parts.pop();
+      continue;
+    }
+    parts.push(segment);
+  }
+  const key = parts.join("/");
+  return IMAGE_KEY_PATTERN.test(key) && docsImageContentType(key) ? key : null;
+}
+function docsImageUrl(bundle, pageId, src) {
+  const key = docsImageKey(pageId, src);
+  if (!key || !bundle?.images || !Object.hasOwn(bundle.images, key)) return null;
+  const image = bundle.images[key];
+  return `data:${image.contentType};base64,${image.data}`;
+}
+function docsImageRefs(markdown) {
+  const text = withoutCode(markdown);
+  const definitions = /* @__PURE__ */ new Map();
+  for (const m of text.matchAll(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(?:<([^>\n]*)>|(\S+))/gm)) {
+    const label = normalizeLabel(m[1]);
+    if (!definitions.has(label)) definitions.set(label, m[2] ?? m[3]);
+  }
+  const refs = [];
+  for (const m of text.matchAll(/!\[([^\]\n]*)\]/g)) {
+    const after = m.index + m[0].length;
+    if (text[after] === "(") {
+      const inline = /\(\s*(?:<([^>\n]*)>|([^\s)]+))/y;
+      inline.lastIndex = after;
+      const src2 = inline.exec(text);
+      if (src2) refs.push(src2[1] ?? src2[2]);
+      continue;
+    }
+    let label = m[1];
+    if (text[after] === "[") {
+      const full = /\[([^\]\n]*)\]/y;
+      full.lastIndex = after;
+      const ref = full.exec(text);
+      if (ref && ref[1]) label = ref[1];
+    }
+    const src = definitions.get(normalizeLabel(label));
+    if (src !== void 0) refs.push(src);
+  }
+  return refs;
+}
+function normalizeLabel(label) {
+  return label.trim().toLowerCase().split(/\s+/).join(" ");
+}
+function withoutCode(markdown) {
+  const out = [];
+  let fence = null;
+  for (const line of markdown.split("\n")) {
+    const opener = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      if (opener && opener[1][0] === fence.char && opener[1].length >= fence.length) fence = null;
+      out.push("");
+      continue;
+    }
+    if (opener) {
+      fence = { char: opener[1][0], length: opener[1].length };
+      out.push("");
+      continue;
+    }
+    out.push(line.replace(/`+[^`]*`+/g, ""));
+  }
+  return out.join("\n");
+}
+var DOCS_SOURCE_BUNDLE_VERSION = 1;
+var docsSourceBundleSchema = z.object({
+  bundleVersion: z.number().int().positive(),
+  config: docsConfigSchema,
+  pages: z.record(
+    pageIdSchema,
+    z.object({ title: z.string().min(1), description: z.string().optional(), markdown: z.string() })
+  ),
+  availability: z.record(z.string().min(1), operationAvailabilitySchema).optional(),
+  events: docsEventsCatalogSchema.optional(),
+  images: z.record(
+    z.string().regex(IMAGE_KEY_PATTERN, "an image key is a path under pages/"),
+    z.object({
+      contentType: z.enum(["image/png", "image/jpeg", "image/gif", "image/webp"]),
+      data: z.string().regex(BASE64_PATTERN, "image data is base64")
+    }).strict()
+  ).optional()
+});
+function docsSourceProblems(bundle, specOperationIds2) {
+  const problems = [];
+  const { config, pages } = bundle;
+  if (config.landing && !Object.hasOwn(pages, config.landing)) {
+    problems.push(`landing "${config.landing}" is not a page of this source`);
+  }
+  const listed = /* @__PURE__ */ new Set();
+  for (const group of config.nav ?? []) {
+    for (const id of group.pages) {
+      if (!Object.hasOwn(pages, id)) problems.push(`nav group "${group.group}" names "${id}", which is not a page of this source`);
+      if (listed.has(id)) problems.push(`"${id}" is listed in the nav more than once`);
+      listed.add(id);
+    }
+  }
+  if (bundle.availability) {
+    const spec = new Set(specOperationIds2);
+    for (const id of Object.keys(bundle.availability)) {
+      if (!spec.has(id)) problems.push(`availability names ${id}, which the spec has no operation for`);
+    }
+    for (const id of specOperationIds2) {
+      if (!Object.hasOwn(bundle.availability, id)) problems.push(`availability leaves out ${id}`);
+    }
+  }
+  if (bundle.events && config.events && bundle.events.service !== config.events) {
+    problems.push(`docs.yaml names events "${config.events}", but the catalog is ${bundle.events.service}'s`);
+  }
+  return problems;
+}
+function docsSourceKey(name) {
+  return `api-docs/${name}/docs-source.json`;
+}
+function splitFrontMatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m) return { frontMatter: {}, body: text };
+  const parsed = parseYaml(m[1]);
+  const frontMatter = parsed && typeof parsed === "object" ? parsed : {};
+  return { frontMatter, body: text.slice(m[0].length).replace(/^\s*\n/, "") };
+}
+var SPEC_METHODS = ["get", "put", "post", "delete", "patch", "head", "options", "trace"];
+function eachSpecOperation(spec, visit) {
+  const paths = spec?.paths;
+  if (!paths || typeof paths !== "object") return;
+  for (const [route, item] of Object.entries(paths)) {
+    if (!item || typeof item !== "object") continue;
+    for (const [method, raw] of Object.entries(item)) {
+      if (!SPEC_METHODS.includes(method) || !raw || typeof raw !== "object") continue;
+      const op = raw;
+      const native = op["x-native-operation"];
+      const oid = op.operationId;
+      visit(
+        typeof native === "string" && native ? native : typeof oid === "string" && oid ? oid : `${method.toUpperCase()} ${route}`,
+        op
+      );
+    }
+  }
+}
+function specOperationIds(spec) {
+  const ids = [];
+  eachSpecOperation(spec, (id) => ids.push(id));
+  return ids;
+}
+function referencedDocsImages(pages) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const { id, text } of pages) {
+    for (const ref of docsImageRefs(splitFrontMatter(text).body)) {
+      const key = docsImageKey(id, ref);
+      if (key) keys.add(key);
+    }
+  }
+  return [...keys].sort();
+}
+function isExternalImageRef(ref) {
+  return ref.startsWith("//") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(ref);
+}
+function base64Bytes(data) {
+  const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+  return Math.floor(data.length * 3 / 4) - padding;
+}
+function parseDocsConfig(text, label) {
+  const parsed = docsConfigSchema.safeParse(parseYaml(text) ?? {});
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ");
+    throw new Error(`${label}: invalid docs.yaml \u2014 ${detail}`);
+  }
+  return parsed.data;
+}
+function assembleDocsSource(files) {
+  const config = parseDocsConfig(files.configText, files.configLabel);
+  const problems = [];
+  if (files.pagesUnreadable && (config.landing || (config.nav ?? []).length > 0)) {
+    problems.push(`pages directory ${files.pagesUnreadable} cannot be read`);
+  }
+  for (const bad of files.invalidPages ?? []) problems.push(`page ${bad} has a path that is not a valid page id`);
+  const pages = {};
+  for (const { id, text } of [...files.pages].sort((a, b) => a.id.localeCompare(b.id))) {
+    if (!PAGE_ID_PATTERN.test(id)) {
+      problems.push(`page ${id} has a path that is not a valid page id`);
+      continue;
+    }
+    const { frontMatter, body } = splitFrontMatter(text);
+    const title = typeof frontMatter.title === "string" ? frontMatter.title.trim() : "";
+    if (!title) {
+      problems.push(`page ${id} has no front-matter title`);
+      continue;
+    }
+    if (/^#\s/.test(body.split("\n").find((l) => l.trim() !== "") ?? "")) {
+      problems.push(`page ${id} opens with a # heading; its front-matter title is already the heading`);
+    }
+    pages[id] = {
+      title,
+      ...typeof frontMatter.description === "string" ? { description: frontMatter.description } : {},
+      markdown: body
+    };
+  }
+  const referenced = /* @__PURE__ */ new Set();
+  for (const [id, page] of Object.entries(pages)) {
+    for (const ref of docsImageRefs(page.markdown)) {
+      if (isExternalImageRef(ref)) continue;
+      const key = docsImageKey(id, ref);
+      if (key) referenced.add(key);
+      else {
+        problems.push(
+          `page ${id} references image "${ref}", which is not a PNG, JPEG, GIF or WebP file inside the pages directory`
+        );
+      }
+    }
+  }
+  problems.push(...files.imageProblems ?? []);
+  const images = {};
+  let imageBytes = 0;
+  for (const key of [...referenced].sort()) {
+    if (!files.images || !Object.hasOwn(files.images, key)) continue;
+    images[key] = files.images[key];
+    imageBytes += base64Bytes(images[key].data);
+  }
+  if (imageBytes > MAX_DOCS_IMAGES_TOTAL_BYTES) {
+    problems.push(
+      `the pages' images total ${imageBytes} bytes, over the ${MAX_DOCS_IMAGES_TOTAL_BYTES}-byte limit for one source`
+    );
+  }
+  const guidesOnly = config.reference === false;
+  if (guidesOnly) {
+    if (!config.landing) problems.push("a guides-only source (reference: false) needs a landing page");
+    if (config.spec) problems.push("docs.yaml names a spec, but reference: false publishes no API reference");
+    if (files.availability) problems.push("a guides-only source (reference: false) publishes no availability");
+  }
+  let specIds = [];
+  if (guidesOnly) {
+  } else if (files.specText === void 0) problems.push(`spec ${files.specLabel} cannot be read`);
+  else {
+    try {
+      specIds = specOperationIds(JSON.parse(files.specText));
+    } catch {
+      problems.push(`spec ${files.specLabel} cannot be read as JSON`);
+    }
+  }
+  const bundle = {
+    bundleVersion: DOCS_SOURCE_BUNDLE_VERSION,
+    config,
+    pages,
+    ...files.availability ? { availability: files.availability } : {},
+    ...files.events ? { events: files.events } : {},
+    ...Object.keys(images).length > 0 ? { images } : {}
+  };
+  problems.push(...docsSourceProblems(bundle, specIds));
+  if (config.events && !files.events) {
+    problems.push(`docs.yaml names events "${config.events}", but no events catalog was supplied`);
+  }
+  return { bundle, problems };
+}
+
+// packages/api-registry/src/index.ts
+import { z as z2 } from "zod";
+
+// packages/api-registry/src/hub-roles.ts
+var HUB_STAFF_ROLES = ["ops", "admin"];
+var HUB_RESTRICTED_ROLES = ["developer", "auditor", "vendor", "docs"];
+var HUB_VENDOR_DOCS_ROLE = "vendor-docs";
+var HUB_ADDON_ROLES = [HUB_VENDOR_DOCS_ROLE];
+var HUB_TIER_ROLES = [
+  ...HUB_STAFF_ROLES,
+  ...HUB_RESTRICTED_ROLES
+];
+var HUB_BASE_ROLES = [
+  ...HUB_TIER_ROLES,
+  ...HUB_ADDON_ROLES
+];
+var HUB_ROLE_KEY_SEPARATOR = ":";
+var HUB_ROLE_APP_SEPARATOR = "/";
+var RESTRICTED = new Set(HUB_RESTRICTED_ROLES);
+var ADDONS = new Set(HUB_ADDON_ROLES);
+function restrictedRoleBase(roleKey) {
+  const sep2 = roleKey.indexOf(HUB_ROLE_KEY_SEPARATOR);
+  const base = sep2 === -1 ? roleKey : roleKey.slice(0, sep2);
+  return RESTRICTED.has(base) ? base : null;
+}
+function hubRoleKeyTenant(roleKey) {
+  const sep2 = roleKey.indexOf(HUB_ROLE_KEY_SEPARATOR);
+  if (sep2 === -1) return null;
+  const scope = roleKey.slice(sep2 + 1);
+  const appSep = scope.indexOf(HUB_ROLE_APP_SEPARATOR);
+  return appSep === -1 ? scope : scope.slice(0, appSep);
+}
+function hubOperatorRoleKeys(tenants) {
+  const cleaned = [...new Set(tenants.filter((t) => t !== ""))].sort();
+  for (const tenant of cleaned) {
+    for (const sep2 of [HUB_ROLE_KEY_SEPARATOR, HUB_ROLE_APP_SEPARATOR]) {
+      if (tenant.includes(sep2)) {
+        throw new Error(
+          `hubOperatorRoleKeys: tenant name "${tenant}" contains the role-key separator "${sep2}" \u2014 it would parse as a different tenant's or app's grant`
+        );
+      }
+    }
+  }
+  return [
+    ...HUB_BASE_ROLES,
+    ...cleaned.flatMap(
+      (tenant) => HUB_RESTRICTED_ROLES.map((role) => `${role}${HUB_ROLE_KEY_SEPARATOR}${tenant}`)
+    )
+  ];
+}
+
+// packages/api-registry/src/index.ts
+var rateLimitSpecSchema = z2.object({
+  rps: z2.number().int().min(1),
+  burst: z2.number().int().min(1)
+});
+var rateLimitDefaultsSchema = z2.record(z2.string().min(1), rateLimitSpecSchema);
+var integrationHealthSchema = z2.union([
+  z2.object({ op: z2.string().trim().min(1) }),
+  z2.object({ unavailable: z2.string().trim().min(1) })
+]);
+var apiSurfaceKindSchema = z2.enum(["app", "vendor", "events"]);
+var apiDocsSiteAudienceSchema = z2.discriminatedUnion("readers", [
+  z2.object({ readers: z2.literal("partner"), roles: z2.array(z2.string().min(1)) }),
+  z2.object({ readers: z2.literal("operator") })
+]);
+var API_REGISTRY_SCHEMA_VERSION = 8;
+var apiSurfaceSchema = z2.object({
+  http: z2.object({ url: z2.string().min(1) }).optional(),
+  nexus: z2.object({ endpoint: z2.string().min(1), taskQueue: z2.string().min(1) }).optional()
+});
+var apiRegistryEntrySchema = z2.object({
+  schemaVersion: z2.number().int().positive().default(1),
+  name: z2.string().min(1),
+  kind: apiSurfaceKindSchema.optional(),
+  provider: z2.string().optional(),
+  externalService: z2.string().min(1).optional(),
+  version: z2.string().optional(),
+  title: z2.string().optional(),
+  description: z2.string().optional(),
+  surfaces: apiSurfaceSchema,
+  credentials: z2.object({ keyedBy: z2.string().nullish() }).optional(),
+  docs: z2.object({
+    url: z2.string().min(1),
+    contentHash: z2.string().min(1),
+    trimmed: z2.object({ url: z2.string().min(1), contentHash: z2.string().min(1) }).optional(),
+    siteUrl: z2.string().min(1).optional(),
+    audience: apiDocsSiteAudienceSchema.optional(),
+    source: z2.object({ url: z2.string().min(1), contentHash: z2.string().min(1) }).optional()
+  }),
+  enabledOps: z2.array(z2.string()),
+  // The consumer schema strips unknown keys, so a producer-side field that is
+  // not mirrored here never reaches a consumer — mirror every addition.
+  status: z2.object({ url: z2.string().min(1) }).optional(),
+  actAs: z2.object({ url: z2.string().min(1), integrations: z2.array(z2.string().min(1)).optional() }).optional(),
+  appVersion: z2.string().min(1).optional(),
+  rateLimits: rateLimitDefaultsSchema.optional(),
+  health: integrationHealthSchema.optional(),
+  producedRateClasses: z2.array(z2.string().min(1)).optional(),
+  sandbox: sandboxModeSchema.optional(),
+  events: z2.object({ entry: z2.string().min(1) }).optional()
+});
+var integrationStatusSchema = z2.object({
+  contract: z2.literal("v1"),
+  name: z2.string().min(1),
+  provider: z2.string().optional(),
+  type: z2.string().optional(),
+  title: z2.string().optional(),
+  definitionVersion: z2.string().optional(),
+  packageVersion: z2.string().min(1).optional(),
+  tenant: z2.string().min(1),
+  instanceKey: z2.string().optional(),
+  surfaces: z2.array(z2.enum(["http", "nexus"])),
+  coreMode: z2.enum(["mock", "live"]),
+  coreModeSource: z2.string().optional(),
+  enabledOps: z2.array(z2.string()),
+  credentialsWired: z2.boolean(),
+  rateLimits: rateLimitDefaultsSchema.optional(),
+  health: integrationHealthSchema.optional(),
+  startedAt: z2.string().min(1)
+});
+function assertPathSegment(value, label) {
+  if (!value || value.includes("/")) {
+    throw new Error(
+      `api-registry: invalid ${label} ${JSON.stringify(value)} \u2014 SSM path segments must be non-empty and must not contain "/"`
+    );
+  }
+  return value;
+}
+function apisRegistryRoot(tenant, env) {
+  return `/mesh-platform/${assertPathSegment(tenant, "tenant")}/${assertPathSegment(env, "env")}/apis`;
+}
+function apiEntryPath(tenant, env, name) {
+  return `${apisRegistryRoot(tenant, env)}/${assertPathSegment(name, "name")}`;
+}
+function actAsAudience(tenant, env, name) {
+  return `${assertPathSegment(tenant, "tenant")}/${assertPathSegment(env, "env")}/${assertPathSegment(name, "name")}`;
+}
+var hubActAsExportsSchema = z2.object({
+  issuer: z2.string().min(1),
+  keys: z2.array(
+    z2.object({
+      kid: z2.string().min(1),
+      kty: z2.literal("RSA"),
+      n: z2.string().min(1),
+      e: z2.string().min(1),
+      alg: z2.string().optional(),
+      use: z2.string().optional()
+    })
+  ).min(1)
+});
+function parseHubActAsExports(value) {
+  const result = hubActAsExportsSchema.safeParse(value);
+  if (!result.success) {
+    const detail = result.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ");
+    throw new Error(`api-registry: invalid HubActAsExports \u2014 ${detail}`);
+  }
+  return result.data;
+}
+function hubActAsPath(tenant, env) {
+  return `/mesh-platform/${assertPathSegment(tenant, "tenant")}/${assertPathSegment(env, "env")}/hub/act-as`;
+}
+
+// packages/api-registry/src/docs-source-build.ts
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+function readPagesDir(dir) {
+  const pages = [];
+  const invalid = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = join(current, entry.name);
+      if (lstatSync(full).isSymbolicLink()) continue;
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const id = relative(dir, full).slice(0, -".md".length).split(sep).join("/");
+        if (PAGE_ID_PATTERN.test(id)) pages.push({ id, text: readFileSync(full, "utf8") });
+        else invalid.push(relative(dir, full));
+      }
+    }
+  };
+  walk(dir);
+  return { pages, invalid };
+}
+function looksLike(bytes, contentType) {
+  const ascii = (from, to) => bytes.subarray(from, to).toString("latin1");
+  switch (contentType) {
+    case "image/png":
+      return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+    case "image/jpeg":
+      return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+    case "image/gif":
+      return ascii(0, 6) === "GIF87a" || ascii(0, 6) === "GIF89a";
+    case "image/webp":
+      return ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP";
+  }
+}
+function readDocsImages(pagesDir, keys) {
+  const images = {};
+  const problems = [];
+  let root;
+  try {
+    root = realpathSync(pagesDir);
+  } catch {
+    return { images, problems: keys.map((key) => `image ${key} cannot be read: the pages directory is missing`) };
+  }
+  for (const key of keys) {
+    const contentType = docsImageContentType(key);
+    if (!contentType) continue;
+    const full = join(root, ...key.split("/"));
+    let size;
+    try {
+      if (lstatSync(full).isSymbolicLink()) {
+        problems.push(`image ${key} is a symbolic link; bundle the file itself`);
+        continue;
+      }
+      const real = realpathSync(full);
+      if (!real.startsWith(root + sep)) {
+        problems.push(`image ${key} resolves outside the pages directory`);
+        continue;
+      }
+      const stat = lstatSync(real);
+      if (!stat.isFile()) throw new Error("not a file");
+      size = stat.size;
+    } catch {
+      problems.push(`image ${key} is referenced by a page but is not in the pages directory`);
+      continue;
+    }
+    if (size > MAX_DOCS_IMAGE_BYTES) {
+      problems.push(`image ${key} is ${size} bytes, over the ${MAX_DOCS_IMAGE_BYTES}-byte limit for one image`);
+      continue;
+    }
+    const bytes = readFileSync(full);
+    if (!looksLike(bytes, contentType)) {
+      problems.push(`image ${key} is not a ${contentType} file, as its extension says`);
+      continue;
+    }
+    images[key] = { contentType, data: bytes.toString("base64") };
+  }
+  return { images, problems };
+}
+function buildDocsSource(input) {
+  const configPath = resolve(input.configPath);
+  const baseDir = dirname(configPath);
+  const configText = readFileSync(configPath, "utf8");
+  const config = parseDocsConfig(configText, configPath);
+  const pagesDir = resolve(baseDir, config.pages ?? "pages");
+  let read;
+  try {
+    read = readPagesDir(pagesDir);
+  } catch {
+    read = void 0;
+  }
+  const specPath = resolve(input.specPath ?? resolve(baseDir, config.spec ?? "openapi.json"));
+  let specText;
+  if (config.reference !== false) {
+    try {
+      specText = readFileSync(specPath, "utf8");
+    } catch {
+      specText = void 0;
+    }
+  }
+  const images = read ? readDocsImages(pagesDir, referencedDocsImages(read.pages)) : void 0;
+  const { bundle, problems } = assembleDocsSource({
+    configLabel: configPath,
+    configText,
+    pages: read?.pages ?? [],
+    ...read ? { invalidPages: read.invalid } : { pagesUnreadable: pagesDir },
+    specLabel: specPath,
+    ...specText !== void 0 ? { specText } : {},
+    ...input.availability ? { availability: input.availability } : {},
+    ...input.events ? { events: input.events } : {},
+    ...images ? { images: images.images, imageProblems: images.problems } : {}
+  });
+  const json = JSON.stringify(bundle);
+  return { bundle, json, contentHash: createHash("sha256").update(json).digest("hex"), specPath, problems };
+}
+
+export {
+  PAGE_ID_PATTERN,
+  docsPage,
+  sandboxModeSchema,
+  DEFAULT_SANDBOX_MODE,
+  tryItAllows,
+  docsImageUrl,
+  docsSourceKey,
+  splitFrontMatter,
+  parseDocsConfig,
+  restrictedRoleBase,
+  hubRoleKeyTenant,
+  hubOperatorRoleKeys,
+  API_REGISTRY_SCHEMA_VERSION,
+  apiEntryPath,
+  actAsAudience,
+  parseHubActAsExports,
+  hubActAsPath,
+  buildDocsSource
+};