@lukoweb/apitogo 0.1.49 → 0.1.51

package/docs/configuration/manifest.md

@@ -1,68 +1,50 @@
 ---
-title: Manifest (apitogo.json)
+title: Site configuration (apitogo.config.json)
 sidebar_icon: file-json
 ---
 
-Dev portal sites provisioned through APItoGo use JSON manifest files for plans, branding, backend
-paths, and gateway settings. Shared defaults live in **`apitogo.json`**; optional per-environment
-files override values without duplicating the full config.
+Dev portal sites use a single JSON configuration file for site settings, plans,
+branding, backend paths, and gateway metadata. Code-only pieces (plugins, custom
+components) stay in `apitogo.config.tsx`.
 
 ## Files
 
-| File                         | When used        | Purpose                                                                   |
-| ---------------------------- | ---------------- | ------------------------------------------------------------------------- |
-| `apitogo.json`               | Always (base)    | Committed defaults: `siteName`, `branding`, `plans`, `backend`, `gateway` |
-| `apitogo.local.json`         | `npm run dev`    | Local-only overrides (optional)                                           |
-| `apitogo.prod.json`          | `npm run build`  | Production build overrides (optional)                                     |
-| `apitogo.local.secrets.json` | MCP publish only | OIDC and Stripe credentials — never loaded by the dev server              |
-
-New scaffolds ship `apitogo.json` plus `apitogo.local.example.json` and `apitogo.prod.example.json`
-to show how overrides work. Copy or rename the examples when you need environment-specific values.
-
-## Resolution
-
-At dev and build time the tooling merges the base file with the environment override:
-
-```mermaid
-flowchart LR
-  base["apitogo.json"]
-  local["apitogo.local.json"]
-  prod["apitogo.prod.json"]
-  devMerge["merge"]
-  buildMerge["merge"]
-  viteDev["npm run dev"]
-  viteBuild["npm run build"]
-
-  base --> devMerge
-  local --> devMerge
-  base --> buildMerge
-  prod --> buildMerge
-  viteDev --> devMerge
-  buildMerge --> viteBuild
-```
+| File | Purpose |
+| --- | --- |
+| `apitogo.config.json` | Committed defaults: site, modules, plans, branding, backend, gateway |
+| `apitogo.config.tsx` | Plugins and other non-JSON configuration |
+| `.env` / `.env.local` / `.env.production` | Per-environment overrides via `APITOGO_CONFIG_*` and `VITE_*` vars |
+
+## Environment overrides
 
-- **Local preview** (`npm run dev`): `apitogo.json` + `apitogo.local.json`
-- **Production build** (`npm run build`): `apitogo.json` + `apitogo.prod.json`
-- **Deployed site**: plans are served from the live dev-portal API (`GET /api/v1/plans`), not from
-  JSON files in the browser bundle
+Use `APITOGO_CONFIG_<path>` with double underscores for nested paths:
+
+```sh
+APITOGO_CONFIG_site__title=My Local Site
+APITOGO_CONFIG_pricing__enabled=true
+APITOGO_CONFIG_projectId=your-local-project-id
+APITOGO_CONFIG_backend__sourceDirectory=../my-api
+```
 
-If `apitogo.json` is missing but `apitogo.local.json` exists, the local file is used as the full
-manifest (legacy single-file projects).
+Values are parsed as JSON when possible (`true`, `false`, numbers, objects).
 
-## Merge rules
+For the live dev-portal API URL (client-visible):
 
-Override files patch the base manifest:
+```sh
+VITE_APITOGO_DEV_PORTAL_API_URL=https://your-dev-portal-api.example.com
+```
 
-- Top-level keys: override wins
-- `branding`, `backend`, `gateway`: deep-merged (override fields patch nested objects)
-- `plans`: merged by `sku` — an override plan with the same SKU updates only the fields you specify
+Keep secrets (OIDC client secret, Stripe keys, etc.) in `.env.local` using the
+same `APITOGO_CONFIG_*` pattern — never commit them.
 
-Example base (`apitogo.json`):
+## Example `apitogo.config.json`
 
 ```json
 {
   "siteName": "My API",
   "branding": { "title": "My API" },
+  "pricing": { "enabled": true },
+  "authentication": { "enabled": true, "type": "dev-portal" },
   "plans": [
     {
       "sku": "pro",
@@ -71,45 +53,52 @@ Example base (`apitogo.json`):
       "priceAmount": 9.99,
       "billingPeriod": "month"
     }
-  ]
+  ],
+  "site": {
+    "title": "My API",
+    "logo": {
+      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
+      "alt": "My API",
+      "width": "130px"
+    }
+  },
+  "docs": { "files": "/pages/**/*.{md,mdx}" }
 }
 ```
 
-Example local override (`apitogo.local.json`):
-
-```json
-{
-  "projectId": "your-local-project-id",
-  "backend": { "sourceDirectory": "../my-api" }
-}
-```
+## Thin `apitogo.config.tsx`
 
-Example production override (`apitogo.prod.json`):
+```tsx
+import { buildApitogoConfig } from "@lukoweb/apitogo";
+import { devPortalBillingPlugin } from "@lukoweb/apitogo-plugin-dev-portal-billing";
 
-```json
-{
-  "plans": [{ "sku": "pro", "priceAmount": 19.99 }],
-  "backend": { "deployed": true }
-}
+export default buildApitogoConfig({
+  plugins: [devPortalBillingPlugin()],
+});
 ```
 
 ## What to put where
 
-| Concern                                      | Recommended file                                                         |
-| -------------------------------------------- | ------------------------------------------------------------------------ |
-| Plans, rate limits, `includedActionKeys`     | `apitogo.json` (shared)                                                  |
-| Branding, site name                          | `apitogo.json`                                                           |
-| Backend paths, OpenAPI location              | `apitogo.json`; machine-specific paths in `apitogo.local.json`           |
-| `projectId` after bootstrap                  | `apitogo.local.json` until MCP writes to the correct file                |
-| Production-only plan pricing or deploy flags | `apitogo.prod.json`                                                      |
-| OIDC / Stripe                                | `apitogo.local.secrets.json` (see [Authentication](./authentication.md)) |
+| Concern | Recommended location |
+| --- | --- |
+| Plans, rate limits, `includedActionKeys` | `apitogo.config.json` |
+| Branding, site name, modules, navigation | `apitogo.config.json` |
+| Machine-specific paths, `projectId` | `.env.local` via `APITOGO_CONFIG_*` |
+| OIDC / Stripe for publish | `.env.local` via `APITOGO_CONFIG_*` |
+| Plugins | `apitogo.config.tsx` |
 
 ## Hot reload
 
-During `npm run dev`, changes to `apitogo.json` or `apitogo.local.json` hot-reload on `/pricing`
+During `npm run dev`, changes to `apitogo.config.json` hot-reload on `/pricing`
 without restarting the server. Restart the dev server after changing
 `VITE_APITOGO_DEV_PORTAL_API_URL` in `.env`.
 
+## Legacy manifests
+
+Older projects may still have `apitogo.json` with optional
+`apitogo.local.json` / `apitogo.prod.json` overrides. The tooling falls back to
+those files when `apitogo.config.json` is missing.
+
 ## Related configuration
 
 - Site navigation, docs, and plugins: [`apitogo.config.tsx`](./overview.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "type": "module",
   "sideEffects": [
     "**/*.css",
@@ -153,6 +153,14 @@
     "./local-manifest": {
       "types": "./dist/declarations/config/local-manifest.d.ts",
       "default": "./src/config/local-manifest.ts"
+    },
+    "./build-config": {
+      "types": "./dist/declarations/config/build-apitogo-config.d.ts",
+      "default": "./src/config/build-apitogo-config.ts"
+    },
+    "./config-loader": {
+      "types": "./dist/declarations/config/apitogo-config-loader.d.ts",
+      "default": "./src/config/apitogo-config-loader.ts"
     }
   },
   "scripts": {
@@ -467,6 +475,14 @@
       "./local-manifest": {
         "types": "./dist/declarations/config/local-manifest.d.ts",
         "default": "./src/config/local-manifest.ts"
+      },
+      "./build-config": {
+        "types": "./dist/declarations/config/build-apitogo-config.d.ts",
+        "default": "./src/config/build-apitogo-config.ts"
+      },
+      "./config-loader": {
+        "types": "./dist/declarations/config/apitogo-config-loader.d.ts",
+        "default": "./src/config/apitogo-config-loader.ts"
       }
     },
     "access": "public"

package/src/config/apitogo-config-loader.ts

@@ -0,0 +1,224 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export const APITOGO_CONFIG_FILENAME = "apitogo.config.json";
+
+const ENV_PREFIX = "APITOGO_CONFIG_";
+
+const MANIFEST_KEYS = [
+  "siteName",
+  "branding",
+  "pricing",
+  "authentication",
+  "plans",
+  "backend",
+  "gateway",
+  "projectId",
+  "projectName",
+] as const;
+
+const SITE_CONFIG_KEYS = [
+  "site",
+  "metadata",
+  "docs",
+  "modules",
+  "navigation",
+  "apis",
+  "redirects",
+  "theme",
+  "footer",
+  "search",
+  "llms",
+  "protectedRoutes",
+  "slots",
+  "mdx",
+  "apiKeys",
+  "catalog",
+  "versions",
+  "options",
+] as const;
+
+export type ApitogoJsonConfig = Record<string, unknown>;
+
+function parseEnvValue(raw: string | undefined): unknown {
+  if (raw === undefined) {
+    return raw;
+  }
+
+  const trimmed = raw.trim();
+  if (trimmed === "true") {
+    return true;
+  }
+  if (trimmed === "false") {
+    return false;
+  }
+  if (trimmed === "null") {
+    return null;
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+
+  if (
+    (trimmed.startsWith("{") && trimmed.endsWith("}")) ||
+    (trimmed.startsWith("[") && trimmed.endsWith("]"))
+  ) {
+    try {
+      return JSON.parse(trimmed) as unknown;
+    } catch {
+      return trimmed;
+    }
+  }
+
+  return trimmed;
+}
+
+function setNestedValue(
+  target: Record<string, unknown>,
+  pathParts: string[],
+  value: unknown,
+): void {
+  if (pathParts.length === 0) {
+    return;
+  }
+
+  let current: Record<string, unknown> = target;
+  for (let index = 0; index < pathParts.length - 1; index += 1) {
+    const key = pathParts[index];
+    if (!key) {
+      return;
+    }
+    const next = current[key];
+    if (
+      next === undefined ||
+      next === null ||
+      typeof next !== "object" ||
+      Array.isArray(next)
+    ) {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+
+  const leafKey = pathParts[pathParts.length - 1];
+  if (!leafKey) {
+    return;
+  }
+
+  current[leafKey] = value;
+}
+
+export function applyEnvOverrides(
+  config: ApitogoJsonConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): ApitogoJsonConfig {
+  const result = structuredClone(config);
+
+  for (const [key, value] of Object.entries(env)) {
+    if (!key.startsWith(ENV_PREFIX) || value === undefined) {
+      continue;
+    }
+
+    const pathParts = key
+      .slice(ENV_PREFIX.length)
+      .split("__")
+      .filter(Boolean);
+
+    if (pathParts.length === 0) {
+      continue;
+    }
+
+    setNestedValue(result, pathParts, parseEnvValue(value));
+  }
+
+  return result;
+}
+
+export function loadApitogoConfig(rootDir = process.cwd()): ApitogoJsonConfig {
+  const configPath = path.join(path.resolve(rootDir), APITOGO_CONFIG_FILENAME);
+
+  if (!existsSync(configPath)) {
+    throw new Error(
+      `Missing ${APITOGO_CONFIG_FILENAME} in ${path.resolve(rootDir)}`,
+    );
+  }
+
+  const raw = readFileSync(configPath, "utf8");
+  const parsed = JSON.parse(raw) as ApitogoJsonConfig;
+  return applyEnvOverrides(parsed, process.env);
+}
+
+export function extractManifest(
+  config: ApitogoJsonConfig | null | undefined,
+): ApitogoJsonConfig | null {
+  if (!config || typeof config !== "object") {
+    return null;
+  }
+
+  const manifest: ApitogoJsonConfig = {};
+  for (const key of MANIFEST_KEYS) {
+    if (config[key] !== undefined) {
+      manifest[key] = config[key];
+    }
+  }
+
+  const authentication = manifest.authentication;
+  if (authentication && typeof authentication === "object") {
+    const { enabled } = authentication as { enabled?: boolean };
+    manifest.authentication =
+      enabled === undefined ? undefined : { enabled };
+  }
+
+  return Object.keys(manifest).length > 0 ? manifest : null;
+}
+
+export function extractSiteConfig(
+  config: ApitogoJsonConfig | null | undefined,
+): ApitogoJsonConfig {
+  if (!config || typeof config !== "object") {
+    return {};
+  }
+
+  const siteConfig: ApitogoJsonConfig = {};
+  for (const key of SITE_CONFIG_KEYS) {
+    if (config[key] !== undefined) {
+      siteConfig[key] = config[key];
+    }
+  }
+
+  const auth = config.authentication;
+  if (auth && typeof auth === "object") {
+    const authRecord = auth as Record<string, unknown>;
+    if (authRecord.type) {
+      const { enabled: _enabled, ...authConfig } = authRecord;
+      siteConfig.authentication = authConfig;
+    }
+  }
+
+  const site = siteConfig.site;
+  const branding = config.branding;
+  const title =
+    (site &&
+      typeof site === "object" &&
+      (site as Record<string, unknown>).title) ??
+    (branding &&
+      typeof branding === "object" &&
+      (branding as Record<string, unknown>).title) ??
+    config.siteName;
+
+  if (title) {
+    siteConfig.site = {
+      ...(site && typeof site === "object"
+        ? (site as Record<string, unknown>)
+        : {}),
+      title,
+    };
+  }
+
+  return siteConfig;
+}
+
+export function apitogoConfigPath(rootDir: string): string {
+  return path.join(path.resolve(rootDir), APITOGO_CONFIG_FILENAME);
+}

package/src/config/build-apitogo-config.ts

@@ -0,0 +1,43 @@
+import type { ApitogoConfig } from "./config.js";
+import {
+  extractSiteConfig,
+  loadApitogoConfig,
+} from "./apitogo-config-loader.js";
+
+type BuildApitogoConfigOptions = {
+  rootDir?: string;
+  overrides?: Partial<ApitogoConfig>;
+};
+
+export function buildApitogoConfig({
+  rootDir,
+  overrides = {},
+}: BuildApitogoConfigOptions = {}): ApitogoConfig {
+  const jsonConfig = loadApitogoConfig(rootDir);
+  const siteConfig = extractSiteConfig(jsonConfig);
+
+  return {
+    ...siteConfig,
+    ...overrides,
+    authentication: {
+      ...(siteConfig.authentication as ApitogoConfig["authentication"]),
+      ...overrides.authentication,
+    },
+    site: {
+      ...(siteConfig.site as ApitogoConfig["site"]),
+      ...overrides.site,
+    },
+    metadata: {
+      ...(siteConfig.metadata as ApitogoConfig["metadata"]),
+      ...overrides.metadata,
+    },
+    docs: {
+      ...(siteConfig.docs as ApitogoConfig["docs"]),
+      ...overrides.docs,
+    },
+    modules: {
+      ...(siteConfig.modules as ApitogoConfig["modules"]),
+      ...overrides.modules,
+    },
+  } as ApitogoConfig;
+}

package/src/config/loader.ts

@@ -10,9 +10,17 @@ import {
 } from "vite";
 import { logger } from "../cli/common/logger.js";
 import { getZudokuRootDir } from "../cli/common/package-json.js";
+import { applyAuthenticationHeaderNav } from "../lib/authentication/auth-header-nav.js";
 import { runPluginTransformConfig } from "../lib/core/transform-config.js";
 import invariant from "../lib/util/invariant.js";
 import { fileExists } from "./file-exists.js";
+import {
+  isAuthenticationEnabled,
+  isPricingEnabled,
+  manifestPathsForEnv,
+  readEffectiveManifest,
+  resolveManifestEnv,
+} from "./local-manifest.js";
 import { resolveModulesConfig } from "./resolve-modules.js";
 import type { ResolvedModulesConfig } from "./validators/ModulesSchema.js";
 import type { ZudokuConfig } from "./validators/ZudokuConfig.js";
@@ -25,6 +33,8 @@ export type ConfigWithMeta = ZudokuConfig & {
     configPath: string;
     mode: typeof process.env.ZUDOKU_ENV;
     dependencies: string[];
+    pricingEnabled?: boolean;
+    authenticationEnabled?: boolean;
   };
   __resolvedModules: ResolvedModulesConfig;
 };
@@ -157,8 +167,17 @@ function isWatchableConfigDependency(depPath: string): boolean {
 }
 
 function getWatchableConfigDependencies(config: ConfigWithMeta): string[] {
+  const manifestEnv = resolveManifestEnv(
+    config.__meta.mode === "production" ? "production" : "development",
+  );
+  const { watchPaths } = manifestPathsForEnv(
+    config.__meta.rootDir,
+    manifestEnv,
+  );
+
   return [
     config.__meta.configPath,
+    ...watchPaths,
     ...config.__meta.dependencies.filter(isWatchableConfigDependency),
   ];
 }
@@ -171,6 +190,10 @@ async function hasConfigChanged() {
   try {
     const hasChanged = await Promise.all(
       files.map(async (depPath) => {
+        if (!(await fileExists(depPath))) {
+          return false;
+        }
+
         const depStat = await stat(depPath);
         const cachedMtime = modifiedTimes?.get(depPath);
         return !cachedMtime || depStat.mtimeMs !== cachedMtime;
@@ -192,6 +215,10 @@ async function updateModifiedTimes() {
 
   await Promise.all(
     files.map(async (depPath) => {
+      if (!(await fileExists(depPath))) {
+        return;
+      }
+
       const depStat = await stat(depPath);
       modifiedTimes?.set(depPath, depStat.mtimeMs);
     }),
@@ -225,7 +252,19 @@ export async function loadZudokuConfig(
 
   try {
     const loadedConfig = await loadZudokuConfigWithMeta(rootDir);
-    const transformedConfig = await runPluginTransformConfig(loadedConfig);
+    const manifestEnv = resolveManifestEnv(configEnv.mode);
+    const manifest = await readEffectiveManifest(rootDir, manifestEnv);
+    const configWithManifestMeta: ConfigWithMeta = {
+      ...loadedConfig,
+      __meta: {
+        ...loadedConfig.__meta,
+        pricingEnabled: isPricingEnabled(manifest),
+        authenticationEnabled: isAuthenticationEnabled(manifest),
+      },
+    };
+    const transformedConfig = applyAuthenticationHeaderNav(
+      await runPluginTransformConfig(configWithManifestMeta),
+    );
     config = {
       ...transformedConfig,
       __resolvedModules: resolveModulesConfig(transformedConfig),