@lukoweb/apitogo 0.2.22 → 0.2.24

package/src/config/local-manifest.ts

@@ -1,545 +1,545 @@
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import {
-  APITOGO_CONFIG_FILENAME,
-  extractManifest,
-  isBillingEnabled,
-  loadApitogoConfig,
-  readPlanCatalogItems,
-} from "./apitogo-config-loader.js";
-import {
-  type GatewayLimits,
-  coerceGatewayLimits,
-  planForConfig,
-  gatewayForConfig,
-  mergeLimitsSource,
-  planLimitsForPlatform,
-} from "./gateway-limits.js";
-import {
-  type LandingManifestInput,
-  LandingManifestContentSchema,
-} from "./landing-manifest.js";
-
-/** @deprecated Legacy manifest filenames — apitogo.config.json is the only supported source. */
-export const APITOGO_MANIFEST_BASE_FILENAME = "apitogo.json";
-
-/** @deprecated Legacy per-environment manifest overrides. */
-export const APITOGO_MANIFEST_ENV_FILES = {
-  development: "apitogo.local.json",
-  production: "apitogo.prod.json",
-} as const;
-
-export { APITOGO_CONFIG_FILENAME };
-
-export type ApitogoManifestEnv = keyof typeof APITOGO_MANIFEST_ENV_FILES;
-
-const BillingPeriodSchema = z.enum(["month", "year", "monthly", "annual"]);
-
-export const PlanPricingModelSchema = z.enum(["fixed", "custom"]);
-
-export type PlanPricingModel = z.infer<typeof PlanPricingModelSchema>;
-
-const GatewayLimitsSchema = z
-  .object({
-    rateLimit: z
-      .object({
-        calls: z.number(),
-        renewalPeriodSeconds: z.number().optional(),
-      })
-      .passthrough()
-      .optional(),
-    quota: z
-      .object({
-        calls: z.number(),
-        renewalPeriodDays: z.number().optional(),
-      })
-      .passthrough()
-      .optional(),
-  })
-  .passthrough();
-
-const PriceCurrencySchema = z
-  .string()
-  .trim()
-  .toLowerCase()
-  .regex(
-    /^[a-z]{3}$/,
-    "priceCurrency must be a 3-letter ISO 4217 code (lowercase)",
-  );
-
-export const ALLOWED_RUNTIME_VERSIONS = [
-  "DOTNET_10",
-  "DOTNET_9",
-  "DOTNET_8",
-  "NODE_24_LTS",
-  "NODE_22_LTS",
-  "PYTHON_314",
-  "PYTHON_313",
-  "PYTHON_312",
-  "PYTHON_311",
-  "PYTHON_310",
-] as const;
-
-export const ManifestPlanInputSchema = z.object({
-  sku: z.string().min(1),
-  displayName: z.string().min(1),
-  priceAmount: z.number().default(0),
-  /** `custom` plans show a contact-sales form instead of checkout. */
-  pricingModel: PlanPricingModelSchema.optional(),
-  priceLabel: z.string().max(64).optional(),
-  priceCurrency: PriceCurrencySchema.optional(),
-  billingPeriod: BillingPeriodSchema.optional(),
-  limits: GatewayLimitsSchema.optional(),
-  /** @deprecated Use `limits`. Encoded string still accepted on load. */
-  limitsJson: z.string().optional(),
-  includedActionKeys: z.array(z.string()).optional(),
-});
-
-export function isPlanCustomPriced(plan: {
-  pricingModel?: string | null;
-}): boolean {
-  return plan.pricingModel === "custom";
-}
-
-/** Free plans have zero price; paid plans have priceAmount greater than zero. */
-export function isPlanFree(plan: { priceAmount?: number }): boolean {
-  return (plan.priceAmount ?? 0) <= 0;
-}
-
-export const DevPortalLocalManifestSchema = z.object({
-  siteName: z.string().optional(),
-  branding: z
-    .object({
-      title: z.string().optional(),
-      logoUrl: z.string().optional(),
-    })
-    .optional(),
-  pricing: z
-    .object({
-      enabled: z.boolean().optional(),
-    })
-    .optional(),
-  authentication: z
-    .object({
-      enabled: z.boolean().optional(),
-      apiBaseUrl: z.string().optional(),
-      native: z
-        .object({
-          enabled: z.boolean().optional(),
-        })
-        .optional(),
-      email: z
-        .object({
-          provider: z.string().optional(),
-          from: z.string().optional(),
-        })
-        .optional(),
-      providers: z
-        .array(
-          z.object({
-            id: z.string().min(1),
-            displayName: z.string().optional(),
-            authority: z.string().optional(),
-            clientId: z.string().optional(),
-            scopes: z.string().optional(),
-          }),
-        )
-        .optional(),
-    })
-    .optional(),
-  plans: z.array(ManifestPlanInputSchema).optional(),
-  backend: z
-    .object({
-      sourceDirectory: z.string().optional(),
-      publishDirectory: z.string().optional(),
-      openApiPath: z.string().optional(),
-      runtime: z.enum(["dotnet", "nodejs", "python"]).or(z.string()).optional(),
-      runtimeVersion: z
-        .string()
-        .optional()
-        .refine(
-          (value) =>
-            value === undefined ||
-            (ALLOWED_RUNTIME_VERSIONS as readonly string[]).includes(
-              value.toUpperCase(),
-            ) ||
-            /^(8(\.0)?|9(\.0)?|10(\.0)?|net8\.0|net9\.0|net10\.0|24|22|3\.(10|11|12|13|14))$/i.test(
-              value,
-            ),
-          {
-            message: `runtimeVersion must be a platform slug (${ALLOWED_RUNTIME_VERSIONS.join(", ")}) or a known alias such as 8.0`,
-          },
-        ),
-      deployed: z.boolean().optional(),
-    })
-    .optional(),
-  gateway: z
-    .object({
-      authMode: z.enum(["platformManagedEntra", "bringYourOwnOidc"]).optional(),
-      oidcMetadataUrl: z.string().optional(),
-      oidcAllowedIssuers: z.array(z.string()).optional(),
-      oidcAudiences: z.array(z.string()).optional(),
-      limits: GatewayLimitsSchema.optional(),
-      /** @deprecated Use `limits`. Encoded string still accepted on load. */
-      limitsJson: z.string().optional(),
-      publicHealthActionKey: z.string().optional(),
-      publicRoutes: z.array(z.string()).optional(),
-      cors: z
-        .object({
-          allowedOrigins: z.array(z.string()).optional(),
-        })
-        .optional(),
-    })
-    .optional(),
-  projectId: z.string().optional(),
-  landing: z
-    .object({
-      enabled: z.boolean().optional(),
-      content: LandingManifestContentSchema,
-    })
-    .optional(),
-});
-
-export type ManifestPlanInput = z.infer<typeof ManifestPlanInputSchema>;
-export type DevPortalLocalManifest = z.infer<
-  typeof DevPortalLocalManifestSchema
->;
-export type { LandingManifestInput };
-
-export type DevPortalPreviewPlan = {
-  sku: string;
-  displayName: string;
-  priceAmount: number;
-  pricingModel: PlanPricingModel;
-  priceLabel?: string;
-  priceCurrency: string;
-  billingPeriod: string;
-  limits: GatewayLimits | null;
-  limitsJson: string | null;
-  includedActionKeys: string[];
-};
-
-export type DevPortalPreviewPlanCatalog = {
-  pricingEnabled: boolean;
-  authenticationEnabled: boolean;
-  plans: DevPortalPreviewPlan[];
-};
-
-export function isPricingEnabled(
-  manifest: DevPortalLocalManifest | null | undefined,
-): boolean {
-  return manifest?.pricing?.enabled === true;
-}
-
-export function isAuthenticationEnabled(
-  manifest: DevPortalLocalManifest | null | undefined,
-): boolean {
-  return manifest?.authentication?.enabled === true;
-}
-
-export function isNativeAuthEnabledInManifest(
-  manifest: DevPortalLocalManifest | null | undefined,
-): boolean {
-  if (!isAuthenticationEnabled(manifest)) {
-    return false;
-  }
-
-  return manifest?.authentication?.native?.enabled !== false;
-}
-
-export function manifestToPreviewCatalog(
-  manifest: DevPortalLocalManifest | null | undefined,
-): DevPortalPreviewPlanCatalog {
-  const plans = manifest?.plans;
-  const catalog = plansToPreviewCatalog(plans);
-  return {
-    pricingEnabled: isPricingEnabled(manifest),
-    authenticationEnabled: isAuthenticationEnabled(manifest),
-    plans: catalog.plans,
-  };
-}
-
-export function normalizeBillingPeriod(period?: string): string {
-  if (!period) {
-    return "monthly";
-  }
-
-  const normalized = period.toLowerCase();
-  if (normalized === "month") {
-    return "monthly";
-  }
-  if (normalized === "year") {
-    return "annual";
-  }
-  return normalized;
-}
-
-export function plansToPreviewCatalog(
-  plans: ManifestPlanInput[] | undefined,
-): Pick<DevPortalPreviewPlanCatalog, "plans"> {
-  if (!plans?.length) {
-    return { plans: [] };
-  }
-
-  return {
-    plans: plans.map((plan) => ({
-      sku: plan.sku,
-      displayName: plan.displayName,
-      priceAmount: plan.priceAmount ?? 0,
-      pricingModel: plan.pricingModel ?? "fixed",
-      ...(plan.priceLabel ? { priceLabel: plan.priceLabel } : {}),
-      priceCurrency: plan.priceCurrency ?? "usd",
-      billingPeriod: normalizeBillingPeriod(plan.billingPeriod),
-      limits: coerceGatewayLimits(plan) ?? null,
-      limitsJson: planLimitsForPlatform(plan) ?? null,
-      includedActionKeys: plan.includedActionKeys ?? [],
-    })),
-  };
-}
-
-export function resolveManifestEnv(viteMode: string): ApitogoManifestEnv {
-  return viteMode === "production" ? "production" : "development";
-}
-
-export function mergePlansBySku(
-  existing: ManifestPlanInput[] | undefined,
-  patch: ManifestPlanInput[],
-): ManifestPlanInput[] {
-  const bySku = new Map<string, ManifestPlanInput>();
-  for (const plan of existing ?? []) {
-    bySku.set(plan.sku, plan);
-  }
-  for (const plan of patch) {
-    const prior = bySku.get(plan.sku);
-    bySku.set(plan.sku, mergeLimitsSource(prior, plan));
-  }
-  return Array.from(bySku.values());
-}
-
-export function mergeLandingContent(
-  existing: LandingManifestInput["content"] | undefined,
-  patch: LandingManifestInput["content"] | undefined,
-): LandingManifestInput["content"] | undefined {
-  if (!patch) {
-    return existing;
-  }
-  if (!existing) {
-    return patch;
-  }
-
-  const merged = { ...existing, ...patch };
-
-  if (patch.hero) {
-    merged.hero = { ...existing.hero, ...patch.hero };
-    if (patch.hero.codeExample) {
-      merged.hero = {
-        ...merged.hero,
-        codeExample: {
-          ...existing.hero?.codeExample,
-          ...patch.hero.codeExample,
-        },
-      };
-    }
-  }
-
-  if (patch.features) {
-    const byTitle = new Map(
-      (existing.features ?? []).map((feature) => [feature.title, feature]),
-    );
-    for (const feature of patch.features) {
-      const prior = byTitle.get(feature.title);
-      byTitle.set(feature.title, prior ? { ...prior, ...feature } : feature);
-    }
-    merged.features = Array.from(byTitle.values());
-  }
-
-  if (patch.trust) {
-    merged.trust = { ...existing.trust, ...patch.trust };
-    if (patch.trust.logos) {
-      merged.trust.logos = patch.trust.logos;
-    }
-  }
-
-  if (patch.apiShowcase) {
-    merged.apiShowcase = { ...existing.apiShowcase, ...patch.apiShowcase };
-    if (patch.apiShowcase.items) {
-      const byPath = new Map(
-        (existing.apiShowcase?.items ?? []).map((item) => [item.path, item]),
-      );
-      for (const item of patch.apiShowcase.items) {
-        const prior = byPath.get(item.path);
-        byPath.set(item.path, prior ? { ...prior, ...item } : item);
-      }
-      merged.apiShowcase.items = Array.from(byPath.values());
-    }
-  }
-
-  if (patch.pricingCta) {
-    merged.pricingCta = { ...existing.pricingCta, ...patch.pricingCta };
-  }
-
-  if (patch.primaryAction) {
-    merged.primaryAction = {
-      ...existing.primaryAction,
-      ...patch.primaryAction,
-    };
-  }
-  if (patch.secondaryAction) {
-    merged.secondaryAction = {
-      ...existing.secondaryAction,
-      ...patch.secondaryAction,
-    };
-  }
-
-  return merged;
-}
-
-export function mergeLandingManifest(
-  existing: LandingManifestInput | undefined,
-  patch: LandingManifestInput | undefined,
-): LandingManifestInput | undefined {
-  if (!patch) {
-    return existing;
-  }
-  if (!existing) {
-    return patch;
-  }
-
-  return {
-    enabled: patch.enabled ?? existing.enabled,
-    content: mergeLandingContent(existing.content, patch.content),
-  };
-}
-
-export function mergeManifest(
-  base: DevPortalLocalManifest,
-  override: DevPortalLocalManifest,
-): DevPortalLocalManifest {
-  const merged: DevPortalLocalManifest = { ...base, ...override };
-
-  if (override.branding) {
-    merged.branding = { ...base.branding, ...override.branding };
-  }
-  if (override.pricing) {
-    merged.pricing = { ...base.pricing, ...override.pricing };
-  }
-  if (override.authentication) {
-    merged.authentication = {
-      ...base.authentication,
-      ...override.authentication,
-    };
-  }
-  if (override.backend) {
-    merged.backend = { ...base.backend, ...override.backend };
-  }
-  if (override.gateway) {
-    merged.gateway = mergeLimitsSource(base.gateway, override.gateway);
-  }
-  if (override.plans) {
-    merged.plans = mergePlansBySku(base.plans, override.plans);
-  }
-  if (override.landing) {
-    merged.landing = mergeLandingManifest(base.landing, override.landing);
-  }
-
-  return merged;
-}
-
-export function manifestFilePath(rootDir: string, filename?: string): string {
-  return path.join(path.resolve(rootDir), filename ?? APITOGO_CONFIG_FILENAME);
-}
-
-export function manifestPathsForEnv(
-  rootDir: string,
-  _env: ApitogoManifestEnv,
-): { basePath: string; overridePath: string; watchPaths: string[] } {
-  const resolvedRoot = path.resolve(rootDir);
-  const configPath = path.join(resolvedRoot, APITOGO_CONFIG_FILENAME);
-
-  return {
-    basePath: configPath,
-    overridePath: configPath,
-    watchPaths: [configPath],
-  };
-}
-
-export function parseLocalManifestJson(
-  raw: string,
-): DevPortalLocalManifest | null {
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    const result = DevPortalLocalManifestSchema.safeParse(parsed);
-    if (!result.success) {
-      return null;
-    }
-    const data = result.data;
-    if (data.plans) {
-      data.plans = data.plans.map((plan) => planForConfig(plan));
-    }
-    if (data.gateway) {
-      data.gateway = gatewayForConfig(data.gateway);
-    }
-    return data;
-  } catch {
-    return null;
-  }
-}
-
-export async function readManifestFile(
-  rootDir: string,
-  filename: string,
-): Promise<DevPortalLocalManifest | null> {
-  const filePath = manifestFilePath(rootDir, filename);
-
-  try {
-    const raw = await readFile(filePath, "utf8");
-    return parseLocalManifestJson(raw);
-  } catch {
-    return null;
-  }
-}
-
-function parseManifestRecord(
-  manifest: ReturnType<typeof extractManifest>,
-): DevPortalLocalManifest | null {
-  if (!manifest) {
-    return null;
-  }
-
-  const result = DevPortalLocalManifestSchema.safeParse(manifest);
-  return result.success ? result.data : null;
-}
-
-export async function readEffectiveManifest(
-  rootDir: string,
-  _env: ApitogoManifestEnv,
-): Promise<DevPortalLocalManifest | null> {
-  try {
-    const config = loadApitogoConfig(rootDir);
-    const manifest = parseManifestRecord(extractManifest(config));
-    if (!manifest) {
-      return null;
-    }
-
-    if (!manifest.plans?.length) {
-      const items = readPlanCatalogItems(config);
-      if (items.length) {
-        manifest.plans = items as ManifestPlanInput[];
-      }
-    }
-
-    return {
-      ...manifest,
-      pricing: { ...manifest.pricing, enabled: isBillingEnabled(config) },
-    };
-  } catch {
-    return null;
-  }
-}
-
-export async function readLocalManifest(
-  rootDir: string,
-): Promise<DevPortalLocalManifest | null> {
-  return readEffectiveManifest(rootDir, "development");
-}
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import {
+  APITOGO_CONFIG_FILENAME,
+  extractManifest,
+  isBillingEnabled,
+  loadApitogoConfig,
+  readPlanCatalogItems,
+} from "./apitogo-config-loader.js";
+import {
+  type GatewayLimits,
+  coerceGatewayLimits,
+  planForConfig,
+  gatewayForConfig,
+  mergeLimitsSource,
+  planLimitsForPlatform,
+} from "./gateway-limits.js";
+import {
+  type LandingManifestInput,
+  LandingManifestContentSchema,
+} from "./landing-manifest.js";
+
+/** @deprecated Legacy manifest filenames — apitogo.config.json is the only supported source. */
+export const APITOGO_MANIFEST_BASE_FILENAME = "apitogo.json";
+
+/** @deprecated Legacy per-environment manifest overrides. */
+export const APITOGO_MANIFEST_ENV_FILES = {
+  development: "apitogo.local.json",
+  production: "apitogo.prod.json",
+} as const;
+
+export { APITOGO_CONFIG_FILENAME };
+
+export type ApitogoManifestEnv = keyof typeof APITOGO_MANIFEST_ENV_FILES;
+
+const BillingPeriodSchema = z.enum(["month", "year", "monthly", "annual"]);
+
+export const PlanPricingModelSchema = z.enum(["fixed", "custom"]);
+
+export type PlanPricingModel = z.infer<typeof PlanPricingModelSchema>;
+
+const GatewayLimitsSchema = z
+  .object({
+    rateLimit: z
+      .object({
+        calls: z.number(),
+        renewalPeriodSeconds: z.number().optional(),
+      })
+      .passthrough()
+      .optional(),
+    quota: z
+      .object({
+        calls: z.number(),
+        renewalPeriodDays: z.number().optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+const PriceCurrencySchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .regex(
+    /^[a-z]{3}$/,
+    "priceCurrency must be a 3-letter ISO 4217 code (lowercase)",
+  );
+
+export const ALLOWED_RUNTIME_VERSIONS = [
+  "DOTNET_10",
+  "DOTNET_9",
+  "DOTNET_8",
+  "NODE_24_LTS",
+  "NODE_22_LTS",
+  "PYTHON_314",
+  "PYTHON_313",
+  "PYTHON_312",
+  "PYTHON_311",
+  "PYTHON_310",
+] as const;
+
+export const ManifestPlanInputSchema = z.object({
+  sku: z.string().min(1),
+  displayName: z.string().min(1),
+  priceAmount: z.number().default(0),
+  /** `custom` plans show a contact-sales form instead of checkout. */
+  pricingModel: PlanPricingModelSchema.optional(),
+  priceLabel: z.string().max(64).optional(),
+  priceCurrency: PriceCurrencySchema.optional(),
+  billingPeriod: BillingPeriodSchema.optional(),
+  limits: GatewayLimitsSchema.optional(),
+  /** @deprecated Use `limits`. Encoded string still accepted on load. */
+  limitsJson: z.string().optional(),
+  includedActionKeys: z.array(z.string()).optional(),
+});
+
+export function isPlanCustomPriced(plan: {
+  pricingModel?: string | null;
+}): boolean {
+  return plan.pricingModel === "custom";
+}
+
+/** Free plans have zero price; paid plans have priceAmount greater than zero. */
+export function isPlanFree(plan: { priceAmount?: number }): boolean {
+  return (plan.priceAmount ?? 0) <= 0;
+}
+
+export const DevPortalLocalManifestSchema = z.object({
+  siteName: z.string().optional(),
+  branding: z
+    .object({
+      title: z.string().optional(),
+      logoUrl: z.string().optional(),
+    })
+    .optional(),
+  pricing: z
+    .object({
+      enabled: z.boolean().optional(),
+    })
+    .optional(),
+  authentication: z
+    .object({
+      enabled: z.boolean().optional(),
+      apiBaseUrl: z.string().optional(),
+      native: z
+        .object({
+          enabled: z.boolean().optional(),
+        })
+        .optional(),
+      email: z
+        .object({
+          provider: z.string().optional(),
+          from: z.string().optional(),
+        })
+        .optional(),
+      providers: z
+        .array(
+          z.object({
+            id: z.string().min(1),
+            displayName: z.string().optional(),
+            authority: z.string().optional(),
+            clientId: z.string().optional(),
+            scopes: z.string().optional(),
+          }),
+        )
+        .optional(),
+    })
+    .optional(),
+  plans: z.array(ManifestPlanInputSchema).optional(),
+  backend: z
+    .object({
+      sourceDirectory: z.string().optional(),
+      publishDirectory: z.string().optional(),
+      openApiPath: z.string().optional(),
+      runtime: z.enum(["dotnet", "nodejs", "python"]).or(z.string()).optional(),
+      runtimeVersion: z
+        .string()
+        .optional()
+        .refine(
+          (value) =>
+            value === undefined ||
+            (ALLOWED_RUNTIME_VERSIONS as readonly string[]).includes(
+              value.toUpperCase(),
+            ) ||
+            /^(8(\.0)?|9(\.0)?|10(\.0)?|net8\.0|net9\.0|net10\.0|24|22|3\.(10|11|12|13|14))$/i.test(
+              value,
+            ),
+          {
+            message: `runtimeVersion must be a platform slug (${ALLOWED_RUNTIME_VERSIONS.join(", ")}) or a known alias such as 8.0`,
+          },
+        ),
+      deployed: z.boolean().optional(),
+    })
+    .optional(),
+  gateway: z
+    .object({
+      authMode: z.enum(["platformManagedEntra", "bringYourOwnOidc"]).optional(),
+      oidcMetadataUrl: z.string().optional(),
+      oidcAllowedIssuers: z.array(z.string()).optional(),
+      oidcAudiences: z.array(z.string()).optional(),
+      limits: GatewayLimitsSchema.optional(),
+      /** @deprecated Use `limits`. Encoded string still accepted on load. */
+      limitsJson: z.string().optional(),
+      publicHealthActionKey: z.string().optional(),
+      publicRoutes: z.array(z.string()).optional(),
+      cors: z
+        .object({
+          allowedOrigins: z.array(z.string()).optional(),
+        })
+        .optional(),
+    })
+    .optional(),
+  projectId: z.string().optional(),
+  landing: z
+    .object({
+      enabled: z.boolean().optional(),
+      content: LandingManifestContentSchema,
+    })
+    .optional(),
+});
+
+export type ManifestPlanInput = z.infer<typeof ManifestPlanInputSchema>;
+export type DevPortalLocalManifest = z.infer<
+  typeof DevPortalLocalManifestSchema
+>;
+export type { LandingManifestInput };
+
+export type DevPortalPreviewPlan = {
+  sku: string;
+  displayName: string;
+  priceAmount: number;
+  pricingModel: PlanPricingModel;
+  priceLabel?: string;
+  priceCurrency: string;
+  billingPeriod: string;
+  limits: GatewayLimits | null;
+  limitsJson: string | null;
+  includedActionKeys: string[];
+};
+
+export type DevPortalPreviewPlanCatalog = {
+  pricingEnabled: boolean;
+  authenticationEnabled: boolean;
+  plans: DevPortalPreviewPlan[];
+};
+
+export function isPricingEnabled(
+  manifest: DevPortalLocalManifest | null | undefined,
+): boolean {
+  return manifest?.pricing?.enabled === true;
+}
+
+export function isAuthenticationEnabled(
+  manifest: DevPortalLocalManifest | null | undefined,
+): boolean {
+  return manifest?.authentication?.enabled === true;
+}
+
+export function isNativeAuthEnabledInManifest(
+  manifest: DevPortalLocalManifest | null | undefined,
+): boolean {
+  if (!isAuthenticationEnabled(manifest)) {
+    return false;
+  }
+
+  return manifest?.authentication?.native?.enabled !== false;
+}
+
+export function manifestToPreviewCatalog(
+  manifest: DevPortalLocalManifest | null | undefined,
+): DevPortalPreviewPlanCatalog {
+  const plans = manifest?.plans;
+  const catalog = plansToPreviewCatalog(plans);
+  return {
+    pricingEnabled: isPricingEnabled(manifest),
+    authenticationEnabled: isAuthenticationEnabled(manifest),
+    plans: catalog.plans,
+  };
+}
+
+export function normalizeBillingPeriod(period?: string): string {
+  if (!period) {
+    return "monthly";
+  }
+
+  const normalized = period.toLowerCase();
+  if (normalized === "month") {
+    return "monthly";
+  }
+  if (normalized === "year") {
+    return "annual";
+  }
+  return normalized;
+}
+
+export function plansToPreviewCatalog(
+  plans: ManifestPlanInput[] | undefined,
+): Pick<DevPortalPreviewPlanCatalog, "plans"> {
+  if (!plans?.length) {
+    return { plans: [] };
+  }
+
+  return {
+    plans: plans.map((plan) => ({
+      sku: plan.sku,
+      displayName: plan.displayName,
+      priceAmount: plan.priceAmount ?? 0,
+      pricingModel: plan.pricingModel ?? "fixed",
+      ...(plan.priceLabel ? { priceLabel: plan.priceLabel } : {}),
+      priceCurrency: plan.priceCurrency ?? "usd",
+      billingPeriod: normalizeBillingPeriod(plan.billingPeriod),
+      limits: coerceGatewayLimits(plan) ?? null,
+      limitsJson: planLimitsForPlatform(plan) ?? null,
+      includedActionKeys: plan.includedActionKeys ?? [],
+    })),
+  };
+}
+
+export function resolveManifestEnv(viteMode: string): ApitogoManifestEnv {
+  return viteMode === "production" ? "production" : "development";
+}
+
+export function mergePlansBySku(
+  existing: ManifestPlanInput[] | undefined,
+  patch: ManifestPlanInput[],
+): ManifestPlanInput[] {
+  const bySku = new Map<string, ManifestPlanInput>();
+  for (const plan of existing ?? []) {
+    bySku.set(plan.sku, plan);
+  }
+  for (const plan of patch) {
+    const prior = bySku.get(plan.sku);
+    bySku.set(plan.sku, mergeLimitsSource(prior, plan));
+  }
+  return Array.from(bySku.values());
+}
+
+export function mergeLandingContent(
+  existing: LandingManifestInput["content"] | undefined,
+  patch: LandingManifestInput["content"] | undefined,
+): LandingManifestInput["content"] | undefined {
+  if (!patch) {
+    return existing;
+  }
+  if (!existing) {
+    return patch;
+  }
+
+  const merged = { ...existing, ...patch };
+
+  if (patch.hero) {
+    merged.hero = { ...existing.hero, ...patch.hero };
+    if (patch.hero.codeExample) {
+      merged.hero = {
+        ...merged.hero,
+        codeExample: {
+          ...existing.hero?.codeExample,
+          ...patch.hero.codeExample,
+        },
+      };
+    }
+  }
+
+  if (patch.features) {
+    const byTitle = new Map(
+      (existing.features ?? []).map((feature) => [feature.title, feature]),
+    );
+    for (const feature of patch.features) {
+      const prior = byTitle.get(feature.title);
+      byTitle.set(feature.title, prior ? { ...prior, ...feature } : feature);
+    }
+    merged.features = Array.from(byTitle.values());
+  }
+
+  if (patch.trust) {
+    merged.trust = { ...existing.trust, ...patch.trust };
+    if (patch.trust.logos) {
+      merged.trust.logos = patch.trust.logos;
+    }
+  }
+
+  if (patch.apiShowcase) {
+    merged.apiShowcase = { ...existing.apiShowcase, ...patch.apiShowcase };
+    if (patch.apiShowcase.items) {
+      const byPath = new Map(
+        (existing.apiShowcase?.items ?? []).map((item) => [item.path, item]),
+      );
+      for (const item of patch.apiShowcase.items) {
+        const prior = byPath.get(item.path);
+        byPath.set(item.path, prior ? { ...prior, ...item } : item);
+      }
+      merged.apiShowcase.items = Array.from(byPath.values());
+    }
+  }
+
+  if (patch.pricingCta) {
+    merged.pricingCta = { ...existing.pricingCta, ...patch.pricingCta };
+  }
+
+  if (patch.primaryAction) {
+    merged.primaryAction = {
+      ...existing.primaryAction,
+      ...patch.primaryAction,
+    };
+  }
+  if (patch.secondaryAction) {
+    merged.secondaryAction = {
+      ...existing.secondaryAction,
+      ...patch.secondaryAction,
+    };
+  }
+
+  return merged;
+}
+
+export function mergeLandingManifest(
+  existing: LandingManifestInput | undefined,
+  patch: LandingManifestInput | undefined,
+): LandingManifestInput | undefined {
+  if (!patch) {
+    return existing;
+  }
+  if (!existing) {
+    return patch;
+  }
+
+  return {
+    enabled: patch.enabled ?? existing.enabled,
+    content: mergeLandingContent(existing.content, patch.content),
+  };
+}
+
+export function mergeManifest(
+  base: DevPortalLocalManifest,
+  override: DevPortalLocalManifest,
+): DevPortalLocalManifest {
+  const merged: DevPortalLocalManifest = { ...base, ...override };
+
+  if (override.branding) {
+    merged.branding = { ...base.branding, ...override.branding };
+  }
+  if (override.pricing) {
+    merged.pricing = { ...base.pricing, ...override.pricing };
+  }
+  if (override.authentication) {
+    merged.authentication = {
+      ...base.authentication,
+      ...override.authentication,
+    };
+  }
+  if (override.backend) {
+    merged.backend = { ...base.backend, ...override.backend };
+  }
+  if (override.gateway) {
+    merged.gateway = mergeLimitsSource(base.gateway, override.gateway);
+  }
+  if (override.plans) {
+    merged.plans = mergePlansBySku(base.plans, override.plans);
+  }
+  if (override.landing) {
+    merged.landing = mergeLandingManifest(base.landing, override.landing);
+  }
+
+  return merged;
+}
+
+export function manifestFilePath(rootDir: string, filename?: string): string {
+  return path.join(path.resolve(rootDir), filename ?? APITOGO_CONFIG_FILENAME);
+}
+
+export function manifestPathsForEnv(
+  rootDir: string,
+  _env: ApitogoManifestEnv,
+): { basePath: string; overridePath: string; watchPaths: string[] } {
+  const resolvedRoot = path.resolve(rootDir);
+  const configPath = path.join(resolvedRoot, APITOGO_CONFIG_FILENAME);
+
+  return {
+    basePath: configPath,
+    overridePath: configPath,
+    watchPaths: [configPath],
+  };
+}
+
+export function parseLocalManifestJson(
+  raw: string,
+): DevPortalLocalManifest | null {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    const result = DevPortalLocalManifestSchema.safeParse(parsed);
+    if (!result.success) {
+      return null;
+    }
+    const data = result.data;
+    if (data.plans) {
+      data.plans = data.plans.map((plan) => planForConfig(plan));
+    }
+    if (data.gateway) {
+      data.gateway = gatewayForConfig(data.gateway);
+    }
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export async function readManifestFile(
+  rootDir: string,
+  filename: string,
+): Promise<DevPortalLocalManifest | null> {
+  const filePath = manifestFilePath(rootDir, filename);
+
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return parseLocalManifestJson(raw);
+  } catch {
+    return null;
+  }
+}
+
+function parseManifestRecord(
+  manifest: ReturnType<typeof extractManifest>,
+): DevPortalLocalManifest | null {
+  if (!manifest) {
+    return null;
+  }
+
+  const result = DevPortalLocalManifestSchema.safeParse(manifest);
+  return result.success ? result.data : null;
+}
+
+export async function readEffectiveManifest(
+  rootDir: string,
+  _env: ApitogoManifestEnv,
+): Promise<DevPortalLocalManifest | null> {
+  try {
+    const config = loadApitogoConfig(rootDir);
+    const manifest = parseManifestRecord(extractManifest(config));
+    if (!manifest) {
+      return null;
+    }
+
+    if (!manifest.plans?.length) {
+      const items = readPlanCatalogItems(config);
+      if (items.length) {
+        manifest.plans = items as ManifestPlanInput[];
+      }
+    }
+
+    return {
+      ...manifest,
+      pricing: { ...manifest.pricing, enabled: isBillingEnabled(config) },
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function readLocalManifest(
+  rootDir: string,
+): Promise<DevPortalLocalManifest | null> {
+  return readEffectiveManifest(rootDir, "development");
+}