saturndocs 0.1.0

package/dist/chunk-R3X2DPFF.js

@@ -0,0 +1,568 @@
+// ../config/dist/index.js
+import { z } from "zod";
+import { parse as parseToml } from "smol-toml";
+import { readFile } from "fs/promises";
+var DEFAULT_BACKGROUND_PRESET = "linear-wash";
+var CODE_THEMES = [
+  "andromeeda",
+  "aurora-x",
+  "ayu-dark",
+  "ayu-light",
+  "ayu-mirage",
+  "catppuccin-frappe",
+  "catppuccin-latte",
+  "catppuccin-macchiato",
+  "catppuccin-mocha",
+  "dark-plus",
+  "dracula",
+  "dracula-soft",
+  "everforest-dark",
+  "everforest-light",
+  "github-dark",
+  "github-dark-default",
+  "github-dark-dimmed",
+  "github-dark-high-contrast",
+  "github-light",
+  "github-light-default",
+  "github-light-high-contrast",
+  "gruvbox-dark-hard",
+  "gruvbox-dark-medium",
+  "gruvbox-dark-soft",
+  "gruvbox-light-hard",
+  "gruvbox-light-medium",
+  "gruvbox-light-soft",
+  "horizon",
+  "horizon-bright",
+  "houston",
+  "kanagawa-dragon",
+  "kanagawa-lotus",
+  "kanagawa-wave",
+  "laserwave",
+  "light-plus",
+  "material-theme",
+  "material-theme-darker",
+  "material-theme-lighter",
+  "material-theme-ocean",
+  "material-theme-palenight",
+  "min-dark",
+  "min-light",
+  "monokai",
+  "night-owl",
+  "night-owl-light",
+  "nord",
+  "one-dark-pro",
+  "one-light",
+  "plastic",
+  "poimandres",
+  "red",
+  "rose-pine",
+  "rose-pine-dawn",
+  "rose-pine-moon",
+  "slack-dark",
+  "slack-ochin",
+  "snazzy-light",
+  "solarized-dark",
+  "solarized-light",
+  "synthwave-84",
+  "tokyo-night",
+  "vesper",
+  "vitesse-black",
+  "vitesse-dark",
+  "vitesse-light"
+];
+var MAX_ASSISTANT_GREETING_CHARS = 200;
+var MAX_ASSISTANT_SUGGESTED_QUESTIONS = 6;
+var MAX_ASSISTANT_SUGGESTED_QUESTION_CHARS = 160;
+var MAX_ASSISTANT_INSTRUCTIONS_CHARS = 4e3;
+var docsColorsSchema = z.object({
+  primary: z.string(),
+  light: z.string().optional(),
+  dark: z.string().optional()
+}).strict();
+var appearanceSchema = z.object({
+  default: z.enum(["light", "dark", "system"]).optional(),
+  strict: z.boolean().optional()
+}).strict().superRefine((appearance, ctx) => {
+  if (appearance.strict === true && (appearance.default ?? "system") === "system") {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["strict"],
+      message: 'strict appearance requires default to be "light" or "dark"'
+    });
+  }
+});
+var fontFamilySchema = z.string().min(1).regex(/^[A-Za-z0-9 +-]+$/, {
+  message: "Font family may only contain letters, numbers, spaces, plus signs, and hyphens"
+});
+var fontSpecSchema = z.union([
+  fontFamilySchema,
+  z.object({
+    family: fontFamilySchema,
+    source: z.enum(["google", "system"]).optional(),
+    weights: z.array(z.number().int().min(1).max(1e3)).min(1).optional()
+  }).strict()
+]);
+var fontsSchema = z.object({
+  body: fontSpecSchema.optional(),
+  heading: fontSpecSchema.optional(),
+  mono: fontSpecSchema.optional()
+}).strict();
+var stylingSchema = z.object({
+  radius: z.enum(["none", "small", "medium", "large"]).optional(),
+  accentStrength: z.enum(["subtle", "medium", "strong"]).optional()
+}).strict();
+var nonEmptyThemeValueSchema = z.string().min(1);
+var modePairSchema = z.object({
+  light: nonEmptyThemeValueSchema.optional(),
+  dark: nonEmptyThemeValueSchema.optional()
+}).strict();
+var themeObjectSchema = z.object({
+  base: z.enum(["default", "minimal", "soft", "bold"]).optional(),
+  code: z.object({
+    light: z.enum(CODE_THEMES).optional(),
+    dark: z.enum(CODE_THEMES).optional()
+  }).strict().optional(),
+  seeds: z.object({
+    background: modePairSchema.optional(),
+    surface: modePairSchema.optional(),
+    text: modePairSchema.optional(),
+    accent: modePairSchema.optional()
+  }).strict().optional(),
+  radius: z.enum(["none", "small", "medium", "large"]).optional(),
+  shadow: z.enum(["none", "soft", "soft-large", "strong"]).optional(),
+  accentStrength: z.enum(["subtle", "medium", "strong"]).optional(),
+  tokens: z.object({
+    light: z.record(z.string(), nonEmptyThemeValueSchema).optional(),
+    dark: z.record(z.string(), nonEmptyThemeValueSchema).optional()
+  }).strict().optional()
+}).strict();
+var navigationLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  external: z.literal(true).optional()
+}).strict();
+var navigationPageSchema = z.object({
+  page: z.string().min(1, "Page paths must not be empty"),
+  label: z.string().min(1, "Page labels must not be empty")
+}).strict();
+var navigationEntrySchema = z.lazy(
+  () => z.union([
+    z.string(),
+    navigationPageSchema,
+    navigationLinkSchema,
+    navigationGroupSchema,
+    navigationSectionSchema
+  ])
+);
+var navigationGroupSchema = z.lazy(
+  () => z.object({
+    group: z.string(),
+    pages: z.array(navigationEntrySchema),
+    openapi: z.string().optional(),
+    collapsed: z.boolean().optional()
+  }).strict()
+);
+var navigationSectionSchema = z.lazy(
+  () => z.object({
+    section: z.string(),
+    pages: z.array(navigationEntrySchema)
+  }).strict()
+);
+var navigationContainerSchema = z.union([
+  navigationGroupSchema,
+  navigationSectionSchema
+]);
+var navigationVersionSchema = z.object({
+  version: z.string().min(1).regex(/^[a-zA-Z0-9._-]+$/, {
+    message: "Version must be URL-safe: letters, numbers, dot, underscore, and hyphen only"
+  }),
+  default: z.boolean().optional(),
+  groups: z.array(navigationContainerSchema)
+}).strict();
+var navigationTabSchema = z.object({
+  tab: z.string().min(1, "Tab labels must not be empty"),
+  groups: z.array(navigationContainerSchema)
+}).strict();
+var navigationSchema = z.union([
+  z.object({
+    groups: z.array(navigationContainerSchema)
+  }).strict(),
+  z.object({
+    tabs: z.array(navigationTabSchema).min(1, "At least one tab is required")
+  }).strict().superRefine((navigation, ctx) => {
+    const seen = /* @__PURE__ */ new Set();
+    for (let index = 0; index < navigation.tabs.length; index++) {
+      const entry = navigation.tabs[index];
+      if (seen.has(entry.tab)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["tabs", index, "tab"],
+          message: `Duplicate tab "${entry.tab}"`
+        });
+      }
+      seen.add(entry.tab);
+      if (entry.groups.every(
+        (group) => group.pages.length === 0 && (!isNavigationGroup(group) || !group.openapi)
+      )) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["tabs", index, "groups"],
+          message: `Tab "${entry.tab}" has no pages; every tab needs a landing page`
+        });
+      }
+    }
+  }),
+  z.object({
+    versions: z.array(navigationVersionSchema).min(1, "At least one version is required")
+  }).strict().superRefine((navigation, ctx) => {
+    const seen = /* @__PURE__ */ new Set();
+    let defaults = 0;
+    for (let index = 0; index < navigation.versions.length; index++) {
+      const entry = navigation.versions[index];
+      if (seen.has(entry.version)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["versions", index, "version"],
+          message: `Duplicate version "${entry.version}"`
+        });
+      }
+      seen.add(entry.version);
+      if (entry.default === true) defaults++;
+    }
+    if (defaults > 1) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["versions"],
+        message: "At most one version may set default: true"
+      });
+    }
+  })
+]).superRefine((navigation, ctx) => {
+  const value = navigation;
+  if ("groups" in value && "versions" in value) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "Navigation must define exactly one of groups or versions"
+    });
+  }
+});
+var logoSchema = z.union([
+  z.string(),
+  z.object({
+    light: z.string().optional(),
+    dark: z.string().optional()
+  }).strict()
+]);
+var docsAiConfigSchema = z.object({
+  assistant: z.boolean().optional(),
+  graphEnrichment: z.boolean().optional(),
+  home: z.boolean().default(false),
+  greeting: z.string().trim().min(1).max(MAX_ASSISTANT_GREETING_CHARS).optional(),
+  suggestedQuestions: z.array(z.string().refine((question) => !/[\r\n]/u.test(question), { message: "a suggested question is one line" }).trim().min(1).max(MAX_ASSISTANT_SUGGESTED_QUESTION_CHARS)).max(MAX_ASSISTANT_SUGGESTED_QUESTIONS).optional(),
+  instructions: z.string().trim().min(1).max(MAX_ASSISTANT_INSTRUCTIONS_CHARS).optional()
+}).strict().superRefine((ai, ctx) => {
+  if (ai.home === true && ai.assistant === false) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["home"],
+      message: "ai.home cannot be true when ai.assistant is false"
+    });
+  }
+});
+var docsAgentsConfigSchema = z.object({
+  contentSignals: z.object({
+    search: z.boolean().optional(),
+    aiInput: z.boolean().optional(),
+    aiTrain: z.boolean().optional()
+  }).strict().optional(),
+  openapi: z.boolean().optional(),
+  webmcp: z.boolean().optional(),
+  a2a: z.boolean().optional()
+}).strict();
+var docsAnalyticsConfigSchema = z.object({
+  posthog: z.object({
+    api_host: z.string().url().optional(),
+    key: z.string()
+  }).strict().optional()
+}).strict();
+var LOCAL_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var httpsUrlSchema = z.string().url().refine((value) => {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:" && LOCAL_HOSTNAMES.has(url.hostname);
+  } catch {
+    return false;
+  }
+}, "Must be an https URL (plain http is allowed for localhost only)");
+var docsAuthOidcConfigSchema = z.object({
+  issuer: httpsUrlSchema,
+  client_id: z.string(),
+  groups_claim: z.string().optional()
+}).strict();
+var docsAuthConfigSchema = z.object({
+  oidc: docsAuthOidcConfigSchema.optional()
+}).strict();
+var socialLinkSchema = z.object({
+  icon: z.string(),
+  label: z.string(),
+  href: z.string()
+}).strict();
+var navigationHrefSchema = z.string().refine((value) => {
+  if (value.startsWith("/")) return !value.startsWith("//");
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}, "Must start with / or be an absolute http(s) URL");
+var docsHeaderConfigSchema = z.object({
+  website: httpsUrlSchema.optional(),
+  showName: z.boolean().optional(),
+  cta: z.object({
+    label: z.string().trim().min(1),
+    href: navigationHrefSchema
+  }).strict().optional()
+}).strict();
+var editLinkSchema = z.object({
+  baseUrl: z.string()
+}).strict();
+var siteUrlSchema = z.string().url().refine((value) => {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}, "Must be an https URL");
+var redirectSchema = z.object({
+  source: z.string().refine((value) => value.startsWith("/"), "Must start with /").refine((value) => !value.startsWith("//"), "Must not start with //"),
+  destination: z.string().refine((value) => {
+    if (value.startsWith("/")) return !value.startsWith("//");
+    try {
+      const url = new URL(value);
+      return url.protocol === "http:" || url.protocol === "https:";
+    } catch {
+      return false;
+    }
+  }, "Must start with / or be an absolute http(s) URL"),
+  permanent: z.boolean().optional()
+}).strict();
+var docsConfigSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  type: z.enum(["docs", "hub", "portal"]).default("docs"),
+  theme: z.union([
+    themeObjectSchema,
+    z.enum(["default", "minimal", "soft", "bold"])
+  ]).optional(),
+  background: z.enum(["none", "linear-wash", "radial-grid", "soft-grain"]).default(DEFAULT_BACKGROUND_PRESET),
+  appearance: appearanceSchema.optional(),
+  fonts: fontsSchema.optional(),
+  styling: stylingSchema.optional(),
+  siteUrl: siteUrlSchema.optional(),
+  colors: docsColorsSchema,
+  logo: logoSchema.optional(),
+  favicon: z.string().optional(),
+  social: z.array(socialLinkSchema).optional(),
+  header: docsHeaderConfigSchema.optional(),
+  editLink: editLinkSchema.optional(),
+  lastUpdated: z.boolean().default(false),
+  contextMenu: z.union([
+    z.boolean(),
+    z.object({ thirdParty: z.boolean().optional() }).strict()
+  ]).default(true),
+  navigation: navigationSchema,
+  footer: z.object({
+    text: z.string().optional()
+  }).strict().optional(),
+  instructions: z.string().optional(),
+  ai: docsAiConfigSchema.optional(),
+  analytics: docsAnalyticsConfigSchema.optional(),
+  auth: docsAuthConfigSchema.optional(),
+  agents: docsAgentsConfigSchema.optional(),
+  redirects: z.array(redirectSchema).optional()
+}).strict().superRefine((config, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (let index = 0; index < (config.redirects ?? []).length; index++) {
+    const redirect = config.redirects?.[index];
+    if (!redirect) continue;
+    if (seen.has(redirect.source)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["redirects", index, "source"],
+        message: `Duplicate redirect source "${redirect.source}"`
+      });
+    }
+    seen.add(redirect.source);
+  }
+});
+var modelsConfigSchema = z.object({
+  models: z.object({
+    synthesis: z.string(),
+    suggestion: z.string().optional()
+  }).strict(),
+  endpoint: z.object({
+    api_base: z.string().optional(),
+    api_key_env: z.string().optional()
+  }).strict().optional(),
+  behavior: z.object({
+    cache: z.boolean().optional(),
+    max_iterations: z.number().int().min(1).max(8).optional()
+  }).strict().optional()
+}).strict();
+function formatPath(path) {
+  let out = "";
+  for (const segment of path) {
+    if (typeof segment === "number") {
+      out += `[${segment}]`;
+    } else {
+      out += out === "" ? String(segment) : `.${String(segment)}`;
+    }
+  }
+  return out;
+}
+function formatZodError(error, label) {
+  const lines = renderIssues(error.issues);
+  return `Invalid ${label}:
+${lines.map((l) => `  - ${l}`).join("\n")}`;
+}
+function renderIssues(issues) {
+  return issues.flatMap((issue) => {
+    if (issue.code === "unrecognized_keys") {
+      return issue.keys.map((key) => {
+        const path2 = formatPath([...issue.path, key]);
+        const where2 = path2 === "" ? "(root)" : path2;
+        return `${where2}: Unrecognized key`;
+      });
+    }
+    if (issue.code === "invalid_union") {
+      const branches = issue.errors.map(
+        (branch) => renderIssues(
+          branch.map((branchIssue) => ({
+            ...branchIssue,
+            path: [...issue.path, ...branchIssue.path]
+          }))
+        )
+      );
+      const best = branches.filter((branch) => branch.length > 0).sort((a, b) => a.length - b.length)[0];
+      if (best) return best;
+    }
+    const path = formatPath(issue.path);
+    const where = path === "" ? "(root)" : path;
+    return `${where}: ${issue.message}`;
+  });
+}
+function parseDocsConfig(data) {
+  const result = docsConfigSchema.safeParse(data);
+  if (!result.success) {
+    throw new Error(formatZodError(result.error, "docs.json"));
+  }
+  return result.data;
+}
+function topLevelNavigationGroups(config) {
+  if ("groups" in config.navigation) return config.navigation.groups;
+  if ("tabs" in config.navigation) return config.navigation.tabs.flatMap((tab) => tab.groups);
+  return config.navigation.versions.flatMap((version) => version.groups);
+}
+function isNavigationGroup(entry) {
+  return typeof entry === "object" && entry !== null && "group" in entry;
+}
+function isNavigationSection(entry) {
+  return typeof entry === "object" && entry !== null && "section" in entry;
+}
+function isNavigationContainer(entry) {
+  return isNavigationGroup(entry) || isNavigationSection(entry);
+}
+function isNavigationPage(entry) {
+  return typeof entry === "object" && entry !== null && "page" in entry;
+}
+function authoredNavigationGroups(groups) {
+  return groups.flatMap((group) => [
+    {
+      group: isNavigationGroup(group) ? group.group : group.section,
+      pages: group.pages.flatMap(
+        (entry) => typeof entry === "string" ? [entry] : isNavigationPage(entry) ? [entry.page] : []
+      ),
+      ...isNavigationGroup(group) && group.openapi ? { openapi: group.openapi } : {},
+      ...isNavigationGroup(group) && group.collapsed !== void 0 ? { collapsed: group.collapsed } : {}
+    },
+    ...authoredNavigationGroups(group.pages.filter(isNavigationContainer))
+  ]);
+}
+function navigationGroups(config) {
+  return authoredNavigationGroups(topLevelNavigationGroups(config));
+}
+async function loadDocsConfig(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (cause) {
+    throw new Error(`Could not read docs.json at ${filePath}: ${errorMessage(cause)}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new Error(`docs.json at ${filePath} is not valid JSON: ${errorMessage(cause)}`);
+  }
+  return parseDocsConfig(parsed);
+}
+async function loadModelsConfig(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (cause) {
+    throw new Error(`Could not read models.toml at ${filePath}: ${errorMessage(cause)}`);
+  }
+  return parseModelsConfigValue(raw, `models.toml at ${filePath}`);
+}
+function parseModelsConfig(toml, platformApiBase) {
+  return parseModelsConfigValue(toml, "models.toml", platformApiBase);
+}
+function parseModelsConfigValue(toml, label, platformApiBase) {
+  let parsed;
+  try {
+    parsed = parseToml(toml);
+  } catch (cause) {
+    throw new Error(`${label} is not valid TOML: ${errorMessage(cause)}`);
+  }
+  const result = modelsConfigSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(formatZodError(result.error, "models.toml"));
+  }
+  return applyModelsDefaults(result.data, platformApiBase);
+}
+function applyModelsDefaults(config, platformApiBase) {
+  const endpoint = config.endpoint ?? {};
+  const behavior = config.behavior ?? {};
+  return {
+    ...config,
+    models: {
+      synthesis: config.models.synthesis,
+      suggestion: config.models.suggestion ?? config.models.synthesis
+    },
+    endpoint: {
+      api_base: endpoint.api_base ?? platformBase(platformApiBase),
+      api_key_env: endpoint.api_key_env ?? "OPENROUTER_API_KEY"
+    },
+    behavior: {
+      cache: behavior.cache ?? true,
+      max_iterations: behavior.max_iterations ?? 4
+    }
+  };
+}
+function platformBase(platformApiBase) {
+  const trimmed = platformApiBase?.trim() ?? "";
+  return trimmed === "" ? "https://openrouter.ai/api/v1" : trimmed;
+}
+function errorMessage(cause) {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+export {
+  parseDocsConfig,
+  navigationGroups,
+  loadDocsConfig,
+  loadModelsConfig,
+  parseModelsConfig
+};