@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/configuration/make-config.mdx

@@ -1,124 +1,124 @@
----
-title: Make config (CLI)
-navigation_label: Make config
-sidebar_icon: file-cog
-description:
-  Create or update apitogo.config.json from your pages folder, OpenAPI, gateway plans, and optional
-  site settings.
----
-
-The **`npx apitogo config`** command writes **`apitogo.config.json`**. It can scaffold a portal
-project (package.json, tsconfig, landing and user-panel stubs, thin `apitogo.config.tsx`) when those
-files are missing, merge **site / theme / authentication** from flags, run an **interactive wizard**
-on a TTY (apply each change immediately), scan `pages/` for navigation, and wire OpenAPI plus an
-**API Reference** link.
-
-Landing and user panel are **always enabled** on new configs. **Authentication is enabled by
-default** on new scaffolds. The command does **not** change `redirects`.
-
-## Prerequisites
-
-Install the CLI first — see [Install the CLI](../cli/setup.md). In short:
-
-- **New site:** `npx @lukoweb/apitogo@latest init` (scaffolds into `./dev-portal` by default)
-
-Run config from the project root with `npx apitogo config`.
-
-## What it does
-
-1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and
-   **`tsconfig.json`** when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing
-   packages.
-2. **Creates `apitogo.config.json`** when missing, using the current portal template (`site`,
-   `theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**).
-   Creates a thin **`apitogo.config.tsx`** wrapper only if that file does not already exist
-   (existing TSX is left alone).
-3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or the
-   interactive wizard.
-4. **Merges `navigation`** from `.md` / `.mdx` / `.tsx` files under your pages directory into a
-   Documentation category when those files exist. **Missing or empty `pages/` is fine** (common for
-   portal-only sites) — existing navigation is left alone. Other nav items are kept. Use
-   **`--force`** to rebuild Documentation items from disk when pages are present (API Reference is
-   still kept when OpenAPI is wired).
-5. **Wires OpenAPI** when a spec is found (non-interactive) or when you enter a path in the wizard:
-   `apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api`
-   if that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
-   example `./openapi.yaml` or `../api/openapi.yaml`).
-6. **Interactive only** — can set **backend** (`sourceDirectory`, `runtime`, `runtimeVersion`),
-   scaffold **custom pages** under `pages/`, and append **gateway plans** to
-   `modules.userPanel.plans.items`. Each choice is written immediately.
-
-## Interactive wizard
-
-On a TTY, bare `npx apitogo config` opens the wizard (no `-i` required). `-i` still works as an
-alias. Use `--no-interactive` (or pass flags like `--title`) for CI / non-TTY.
-
-```bash
-npx apitogo config
-```
-
-1. **Loop** until you type `done` (default):
-   - **`backend`** — source directory, runtime (`dotnet` / `nodejs` / `python`), platform
-     `runtimeVersion` (writes `backend` in `apitogo.config.json` immediately)
-   - **`openapi`** — path to your OpenAPI file (relative link in config; empty skips)
-   - **`page`** — page title + URL path (writes `pages/<slug>.tsx` and wires navigation immediately)
-   - **`plan`** — plan title, price (USD/month), rate limit (calls/min), monthly quota (writes
-     immediately)
-2. **Wrap-up** — links to [docs.apitogo.com](https://docs.apitogo.com) for further configuration
-
-The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL.
-Authentication stays **enabled**; `npx apitogo deploy` writes
-`VITE_APITOGO_AUTHENTICATION_API_BASE_URL` to `.env` after the portal backend is provisioned.
-
-If you add a **paid** plan (`priceAmount > 0`), the CLI warns that **Free platform hosting cannot
-publish paid gateway plans or custom domains** — use Starter or Professional on deploy.
-
-See [Gateway plans](./plans.md) and [Shape with CLI](../cli/shape.md).
-
-## Usage
-
-Run from your project root (where `apitogo.config.json` and `package.json` live):
-
-```bash
-npx apitogo config
-```
-
-### Options
-
-| Option                    | Description                                                             |
-| ------------------------- | ----------------------------------------------------------------------- |
-| `--pages-dir <dir>`       | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`)           |
-| `--dir <path>`            | Project root (default: current directory)                               |
-| `--interactive` / `-i`    | Force the wizard (default on TTY). Use `--no-interactive` to skip.      |
-| `--title <string>`        | Set `site.title` (non-interactive)                                      |
-| `--site <json>`           | Deep-merge a JSON object into `site`                                    |
-| `--theme <json>`          | Deep-merge a JSON object into `theme`                                   |
-| `--authentication <json>` | Deep-merge a JSON object into `authentication` (secrets stay in `.env`) |
-| `--force`                 | Replace Documentation nav items from disk                               |
-
-Examples:
-
-```bash
-npx apitogo config
-npx apitogo config --title "Books API"
-npx apitogo config --theme '{"light":{"primary":"#111111"}}'
-npx apitogo config --no-interactive
-```
-
-Theme and fonts are edited in `apitogo.config.json` or via MCP — not in the interactive wizard. See
-[Colors & theme](../customization/colors-theme.mdx) and [Fonts](../customization/fonts.md).
-
-There is **no `--modules` flag** for landing or user-panel toggles. Interactive mode **does** update
-`modules.userPanel.plans` when you add plans.
-
-## When not to use it
-
-- You need a fully custom navigation order — skip `--force` or maintain navigation by hand.
-- You want to change landing module home content — edit `landing/LandingPage.tsx`.
-
-## See also
-
-- [Manifest (`apitogo.config.json`)](./manifest.md)
-- [Gateway plans](./plans.md)
-- [Navigation](./navigation.md)
-- [Shape with CLI](../cli/shape.md)
+---
+title: Make config (CLI)
+navigation_label: Make config
+sidebar_icon: file-cog
+description:
+  Create or update apitogo.config.json from your pages folder, OpenAPI, gateway plans, and optional
+  site settings.
+---
+
+The **`npx apitogo config`** command writes **`apitogo.config.json`**. It can scaffold a portal
+project (package.json, tsconfig, landing and user-panel stubs, thin `apitogo.config.tsx`) when those
+files are missing, merge **site / theme / authentication** from flags, run an **interactive wizard**
+on a TTY (apply each change immediately), scan `pages/` for navigation, and wire OpenAPI plus an
+**API Reference** link.
+
+Landing and user panel are **always enabled** on new configs. **Authentication is enabled by
+default** on new scaffolds. The command does **not** change `redirects`.
+
+## Prerequisites
+
+Install the CLI first — see [Install the CLI](../cli/setup.md). In short:
+
+- **New site:** `npx @lukoweb/apitogo@latest init` (scaffolds into `./dev-portal` by default)
+
+Run config from the project root with `npx apitogo config`.
+
+## What it does
+
+1. **Ensures npm scripts** — Creates **`package.json`** (dev / build / preview) and
+   **`tsconfig.json`** when missing, including `@lukoweb/apitogo`, landing, user-panel, and billing
+   packages.
+2. **Creates `apitogo.config.json`** when missing, using the current portal template (`site`,
+   `theme`, `authentication` **enabled**, `modules.docs`, **landing on**, **user panel on**).
+   Creates a thin **`apitogo.config.tsx`** wrapper only if that file does not already exist
+   (existing TSX is left alone).
+3. **Patches site, theme, and auth** from `--site`, `--theme`, `--authentication`, `--title`, or the
+   interactive wizard.
+4. **Merges `navigation`** from `.md` / `.mdx` / `.tsx` files under your pages directory into a
+   Documentation category when those files exist. **Missing or empty `pages/` is fine** (common for
+   portal-only sites) — existing navigation is left alone. Other nav items are kept. Use
+   **`--force`** to rebuild Documentation items from disk when pages are present (API Reference is
+   still kept when OpenAPI is wired).
+5. **Wires OpenAPI** when a spec is found (non-interactive) or when you enter a path in the wizard:
+   `apis: [{ type: "file", input, path: "api" }]` and a top-level **API Reference** link to `/api`
+   if that link is missing. Interactive mode stores a **relative file path** in `apis[0].input` (for
+   example `./openapi.yaml` or `../api/openapi.yaml`).
+6. **Interactive only** — can set **backend** (`sourceDirectory`, `runtime`, `runtimeVersion`),
+   scaffold **custom pages** under `pages/`, and append **gateway plans** to
+   `modules.userPanel.plans.items`. Each choice is written immediately.
+
+## Interactive wizard
+
+On a TTY, bare `npx apitogo config` opens the wizard (no `-i` required). `-i` still works as an
+alias. Use `--no-interactive` (or pass flags like `--title`) for CI / non-TTY.
+
+```bash
+npx apitogo config
+```
+
+1. **Loop** until you type `done` (default):
+   - **`backend`** — source directory, runtime (`dotnet` / `nodejs` / `python`), platform
+     `runtimeVersion` (writes `backend` in `apitogo.config.json` immediately)
+   - **`openapi`** — path to your OpenAPI file (relative link in config; empty skips)
+   - **`page`** — page title + URL path (writes `pages/<slug>.tsx` and wires navigation immediately)
+   - **`plan`** — plan title, price (USD/month), rate limit (calls/min), monthly quota (writes
+     immediately)
+2. **Wrap-up** — links to [docs.apitogo.com](https://docs.apitogo.com) for further configuration
+
+The wizard does **not** ask for fonts, colors, logo alt text, or the auth API base URL.
+Authentication stays **enabled**; `npx apitogo deploy` writes
+`VITE_APITOGO_AUTHENTICATION_API_BASE_URL` to `.env` after the portal backend is provisioned.
+
+If you add a **paid** plan (`priceAmount > 0`), the CLI warns that **Free platform hosting cannot
+publish paid gateway plans or custom domains** — use Starter or Professional on deploy.
+
+See [Gateway plans](./plans.md) and [Shape with CLI](../cli/shape.md).
+
+## Usage
+
+Run from your project root (where `apitogo.config.json` and `package.json` live):
+
+```bash
+npx apitogo config
+```
+
+### Options
+
+| Option                    | Description                                                             |
+| ------------------------- | ----------------------------------------------------------------------- |
+| `--pages-dir <dir>`       | Folder to scan for `.md` / `.mdx` / `.tsx` (default: `pages`)           |
+| `--dir <path>`            | Project root (default: current directory)                               |
+| `--interactive` / `-i`    | Force the wizard (default on TTY). Use `--no-interactive` to skip.      |
+| `--title <string>`        | Set `site.title` (non-interactive)                                      |
+| `--site <json>`           | Deep-merge a JSON object into `site`                                    |
+| `--theme <json>`          | Deep-merge a JSON object into `theme`                                   |
+| `--authentication <json>` | Deep-merge a JSON object into `authentication` (secrets stay in `.env`) |
+| `--force`                 | Replace Documentation nav items from disk                               |
+
+Examples:
+
+```bash
+npx apitogo config
+npx apitogo config --title "Books API"
+npx apitogo config --theme '{"light":{"primary":"#111111"}}'
+npx apitogo config --no-interactive
+```
+
+Theme and fonts are edited in `apitogo.config.json` or via MCP — not in the interactive wizard. See
+[Colors & theme](../customization/colors-theme.mdx) and [Fonts](../customization/fonts.md).
+
+There is **no `--modules` flag** for landing or user-panel toggles. Interactive mode **does** update
+`modules.userPanel.plans` when you add plans.
+
+## When not to use it
+
+- You need a fully custom navigation order — skip `--force` or maintain navigation by hand.
+- You want to change landing module home content — edit `landing/LandingPage.tsx`.
+
+## See also
+
+- [Manifest (`apitogo.config.json`)](./manifest.md)
+- [Gateway plans](./plans.md)
+- [Navigation](./navigation.md)
+- [Shape with CLI](../cli/shape.md)

package/docs/configuration/manifest.md

@@ -1,128 +1,128 @@
-# Site configuration (apitogo.config.json)
-
-Dev portal sites use `apitogo.config.json` for site settings, plans, authentication, and backend
-metadata, with optional `.env` overrides for secrets and local tweaks.
-
-## Files
-
-| File                  | Purpose                                                     |
-| --------------------- | ----------------------------------------------------------- |
-| `apitogo.config.json` | Committed defaults: site, modules, authentication, backend  |
-| `.env`                | Public client vars + publish secrets via `APITOGO_CONFIG_*` |
-
-## Canonical shape
-
-```json
-{
-  "site": {
-    "title": "My API",
-    "logo": {
-      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
-      "alt": "My API",
-      "width": "130px"
-    }
-  },
-  "authentication": {
-    "enabled": true,
-    "type": "dev-portal",
-    "apiBaseUrl": "https://your-dev-portal-api.example.com"
-  },
-  "gateway": {
-    "authMode": "bringYourOwnOidc",
-    "oidcMetadataUrl": "https://login.example.com/.well-known/openid-configuration",
-    "publicRoutes": ["/health"],
-    "cors": {
-      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
-    }
-  },
-  "modules": {
-    "docs": { "files": "/pages/**/*.{md,mdx}" },
-    "landing": { "enabled": true, "path": "/", "layout": "landing" },
-    "userPanel": {
-      "enabled": true,
-      "dashboard": { "enabled": true },
-      "userManagement": { "enabled": true },
-      "plans": {
-        "enabled": true,
-        "items": [
-          {
-            "sku": "free",
-            "displayName": "Free",
-            "priceAmount": 0
-          }
-        ]
-      }
-    }
-  },
-  "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
-}
-```
-
-- **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
-- **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
-- **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
-  `modules.userPanel.plans.items`. Add plans with `npx apitogo config` or edit the manifest by hand.
-  See [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
-- **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
-- **Gateway:** top-level `gateway` (not under `authentication`). See [Gateway CORS](#gateway-cors)
-  and [Gateway plans](./plans.md).
-
-## Gateway CORS
-
-Browser calls from your developer portal (and any other SPA) to the API gateway are cross-origin.
-APItoGo always allows the portal site origin. Add extra origins under `gateway.cors.allowedOrigins`
-when tenant apps or local frontends call the gateway:
-
-```json
-{
-  "gateway": {
-    "cors": {
-      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
-    }
-  }
-}
-```
-
-| Rule            | Detail                                                                              |
-| --------------- | ----------------------------------------------------------------------------------- |
-| Portal origin   | Always allowed by the platform (`https://{your-portal-host}`). Do not list it here. |
-| Extra origins   | Absolute `http://` or `https://` origins only — no path, query, or fragment.        |
-| Wildcard        | `"*"` is allowed (replaces the list; credentials stay off).                         |
-| Empty / omitted | Portal playground still works; only extras are missing.                             |
-
-Apply with `npx apitogo deploy` / `publish_dev_portal` so APIM policies pick up the change.
-
-## Environment variables
-
-Public client URL (mirrors `authentication.apiBaseUrl`):
-
-```sh
-VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-Nested config overrides (uppercase SCREAMING_SNAKE path segments; camelCase still accepted):
-
-```sh
-APITOGO_CONFIG_SITE__TITLE=My Local Site
-APITOGO_CONFIG_PRICING__ENABLED=true
-APITOGO_CONFIG_PROJECT_ID=your-local-project-id
-APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL=https://your-dev-portal-api.example.com
-```
-
-Publish secrets (uncomment in `.env`, never commit):
-
-```sh
-APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
-APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
-APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
-APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
-```
-
-## Related
-
-- [Gateway plans](./plans.md)
-- [Authentication](./authentication.md)
-- [Overview](./overview.md)
-- [MCP overview](../mcp/overview.md)
-- [Environment variables](../guides/environment-variables.md)
+# Site configuration (apitogo.config.json)
+
+Dev portal sites use `apitogo.config.json` for site settings, plans, authentication, and backend
+metadata, with optional `.env` overrides for secrets and local tweaks.
+
+## Files
+
+| File                  | Purpose                                                     |
+| --------------------- | ----------------------------------------------------------- |
+| `apitogo.config.json` | Committed defaults: site, modules, authentication, backend  |
+| `.env`                | Public client vars + publish secrets via `APITOGO_CONFIG_*` |
+
+## Canonical shape
+
+```json
+{
+  "site": {
+    "title": "My API",
+    "logo": {
+      "src": { "light": "/logo-light.png", "dark": "/logo-dark.png" },
+      "alt": "My API",
+      "width": "130px"
+    }
+  },
+  "authentication": {
+    "enabled": true,
+    "type": "dev-portal",
+    "apiBaseUrl": "https://your-dev-portal-api.example.com"
+  },
+  "gateway": {
+    "authMode": "bringYourOwnOidc",
+    "oidcMetadataUrl": "https://login.example.com/.well-known/openid-configuration",
+    "publicRoutes": ["/health"],
+    "cors": {
+      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
+    }
+  },
+  "modules": {
+    "docs": { "files": "/pages/**/*.{md,mdx}" },
+    "landing": { "enabled": true, "path": "/", "layout": "landing" },
+    "userPanel": {
+      "enabled": true,
+      "dashboard": { "enabled": true },
+      "userManagement": { "enabled": true },
+      "plans": {
+        "enabled": true,
+        "items": [
+          {
+            "sku": "free",
+            "displayName": "Free",
+            "priceAmount": 0
+          }
+        ]
+      }
+    }
+  },
+  "apis": [{ "type": "file", "input": "./apis/openapi.yaml", "path": "api" }]
+}
+```
+
+- **Site name / logo:** only `site.title` and `site.logo` (platform branding is derived at publish).
+- **OpenAPI path:** `backend.openApiPath` is derived from `apis[0].input`.
+- **Billing / account plans:** use `modules.userPanel.plans.enabled` and store the plan catalog in
+  `modules.userPanel.plans.items`. Add plans with `npx apitogo config` or edit the manifest by hand.
+  See [Gateway plans](./plans.md). Legacy root `plans` is migrated on load.
+- **Docs / API keys:** configure under `modules.docs` and `modules.userPanel.apiKeys` only.
+- **Gateway:** top-level `gateway` (not under `authentication`). See [Gateway CORS](#gateway-cors)
+  and [Gateway plans](./plans.md).
+
+## Gateway CORS
+
+Browser calls from your developer portal (and any other SPA) to the API gateway are cross-origin.
+APItoGo always allows the portal site origin. Add extra origins under `gateway.cors.allowedOrigins`
+when tenant apps or local frontends call the gateway:
+
+```json
+{
+  "gateway": {
+    "cors": {
+      "allowedOrigins": ["https://myapp.example.com", "http://localhost:5173"]
+    }
+  }
+}
+```
+
+| Rule            | Detail                                                                              |
+| --------------- | ----------------------------------------------------------------------------------- |
+| Portal origin   | Always allowed by the platform (`https://{your-portal-host}`). Do not list it here. |
+| Extra origins   | Absolute `http://` or `https://` origins only — no path, query, or fragment.        |
+| Wildcard        | `"*"` is allowed (replaces the list; credentials stay off).                         |
+| Empty / omitted | Portal playground still works; only extras are missing.                             |
+
+Apply with `npx apitogo deploy` / `publish_dev_portal` so APIM policies pick up the change.
+
+## Environment variables
+
+Public client URL (mirrors `authentication.apiBaseUrl`):
+
+```sh
+VITE_APITOGO_AUTHENTICATION_API_BASE_URL=https://your-dev-portal-api.example.com
+```
+
+Nested config overrides (uppercase SCREAMING_SNAKE path segments; camelCase still accepted):
+
+```sh
+APITOGO_CONFIG_SITE__TITLE=My Local Site
+APITOGO_CONFIG_PRICING__ENABLED=true
+APITOGO_CONFIG_PROJECT_ID=your-local-project-id
+APITOGO_CONFIG_AUTHENTICATION__API_BASE_URL=https://your-dev-portal-api.example.com
+```
+
+Publish secrets (uncomment in `.env`, never commit):
+
+```sh
+APITOGO_CONFIG_AUTHENTICATION__OIDC__AUTHORITY=https://login.example.com
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_ID=your-client-id
+APITOGO_CONFIG_AUTHENTICATION__OIDC__CLIENT_SECRET=your-client-secret
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__SECRET_KEY=sk_test_...
+APITOGO_CONFIG_AUTHENTICATION__STRIPE__WEBHOOK_SECRET=whsec_...
+```
+
+## Related
+
+- [Gateway plans](./plans.md)
+- [Authentication](./authentication.md)
+- [Overview](./overview.md)
+- [MCP overview](../mcp/overview.md)
+- [Environment variables](../guides/environment-variables.md)