npm - @lukoweb/apitogo - Versions diffs - 0.2.46 → 0.2.47 - Mend

@lukoweb/apitogo 0.2.46 → 0.2.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/cli/cli.js +949 -2977
package/docs/cli/overview.md +91 -91
package/docs/cli/shape.md +126 -127
package/docs/configuration/make-config.mdx +96 -124
package/docs/configuration/manifest.md +129 -128
package/docs/configuration/navigation.mdx +415 -421
package/docs/configuration/plans.md +154 -153
package/docs/guides/custom-pages.md +111 -110
package/package.json +1 -1
package/src/config/v2/services.ts +1 -1

package/docs/cli/overview.md CHANGED Viewed

@@ -1,91 +1,91 @@
----
-title: CLI overview
-description:
-  Use the APItoGo CLI to scaffold, shape, preview, and publish API products without an AI agent.
-sidebar_icon: terminal
----
-The **`apitogo`** CLI lets you manage developer portals from the terminal. You scaffold and shape
-local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
-`npx apitogo deploy`.
-**First time?** Install and wire credentials → **[Install the CLI](./setup.md)**. Then follow
-[Shape](./shape.md) and [Go live](./go-live.md).
-## What you get
-- Scaffold a local portal site (`npx @lukoweb/apitogo@latest init`)
-- Shape backend, OpenAPI, plans, and docs pages via `npx apitogo config` and file edits
-- Preview locally (`npx apitogo run`)
-- Publish to APItoGo hosting (`npx apitogo deploy`) with platform plans **Free**, **Starter**, or
-  **Professional**
-- Check live status (`npx apitogo status`) and tear down (`npx apitogo teardown --yes`)
-## Prerequisites
-### Shell environment (for deploy / status / teardown)
-| Variable             | Required | Purpose           |
-| -------------------- | -------- | ----------------- |
-| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
-| `APITOGO_API_SECRET` | Yes      | Platform API auth |
-### Local machine
-- Node.js 20+ (scaffold, build, preview)
-- Network access to the npm registry during install/build
-- OIDC credentials at publish time (site `.env` only — never in shell history for sharing)
-- Stripe secrets at publish only when you have **paid** project plans
-## Changing your site
-| Approach                 | When it helps                                                                                                                     |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
-| **`npx apitogo config`** | Wire OpenAPI, custom pages, gateway plans, and site title from the terminal. See [Make config](../configuration/make-config.mdx). |
-| **Edit files directly**  | Full control — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.                                                 |
-Common CLI shape tasks:
-| Change                            | How                                               |
-| --------------------------------- | ------------------------------------------------- |
-| Backend runtime                   | `npx apitogo config` (backend)                    |
-| OpenAPI + API Reference nav       | `npx apitogo config` (openapi)                    |
-| Custom docs pages                 | `npx apitogo config` (page) or add under `pages/` |
-| Gateway / API plans               | `npx apitogo config` (plan) or edit manifest      |
-| Site title                        | `--title` or edit `apitogo.config.json`           |
-| Theme, fonts, branding, projectId | Edit `apitogo.config.json`                        |
-Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
-`modules.landing.content.footer` in `apitogo.config.json`.
-## Config model (local site)
-| File                  | Role                                  |
-| --------------------- | ------------------------------------- |
-| `apitogo.config.json` | Site, modules, plans, auth type, apis |
-| `.env`                | `VITE_*` + `APITOGO_CONFIG_*` secrets |
-Details: [Manifest](../configuration/manifest.md).
-## CLI vs MCP
-Both paths use the same config-first model. `npx apitogo deploy` runs the same engine as MCP
-`publish_dev_portal`.
-| Task              | CLI                                           | MCP (agent)                                   |
-| ----------------- | --------------------------------------------- | --------------------------------------------- |
-| Scaffold          | `npx @lukoweb/apitogo@latest init`            | `create_dev_portal`                           |
-| Shape config      | `npx apitogo config` + file edits             | `apply_product_intent` (shape)                |
-| Preview           | `npx apitogo run`                             | `npm run dev` / preview tool                  |
-| Publish           | `npx apitogo deploy`                          | `publish_dev_portal`                          |
-| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `verify_dev_portal_live` / `teardown_project` |
-Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
-workflows.
-## Next
-- [Install the CLI](./setup.md)
-- [Shape](./shape.md) · [Go live](./go-live.md) · [Commands](./commands.md)
-- [MCP overview](../mcp/overview.md) — agent-driven workflow
-- [Manifest](../configuration/manifest.md)
+---
+title: CLI overview
+description:
+  Use the APItoGo CLI to scaffold, shape, preview, and publish API products without an AI agent.
+sidebar_icon: terminal
+---
+The **`apitogo`** CLI lets you manage developer portals from the terminal. You scaffold and shape
+local files, preview with `npx apitogo run`, and publish to APItoGo hosting with
+`npx apitogo deploy`.
+**First time?** Install and wire credentials → **[Install the CLI](./setup.md)**. Then follow
+[Shape](./shape.md) and [Go live](./go-live.md).
+## What you get
+- Scaffold a local portal site (`npx @lukoweb/apitogo@latest init`)
+- Shape backend, OpenAPI, plans, and docs pages via `npx apitogo config` and file edits
+- Preview locally (`npx apitogo run`)
+- Publish to APItoGo hosting (`npx apitogo deploy`) with platform plans **Free**, **Starter**, or
+  **Professional**
+- Check live status (`npx apitogo status`) and tear down (`npx apitogo teardown --yes`)
+## Prerequisites
+### Shell environment (for deploy / status / teardown)
+| Variable             | Required | Purpose           |
+| -------------------- | -------- | ----------------- |
+| `APITOGO_API_KEY_ID` | Yes      | Platform API auth |
+| `APITOGO_API_SECRET` | Yes      | Platform API auth |
+### Local machine
+- Node.js 20+ (scaffold, build, preview)
+- Network access to the npm registry during install/build
+- OIDC credentials at publish time (site `.env` only — never in shell history for sharing)
+- Stripe secrets at publish only when you have **paid** project plans
+## Changing your site
+| Approach                 | When it helps                                                                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| **`npx apitogo config`** | Wire OpenAPI, custom pages, gateway plans, and site title from the terminal. See [Make config](../configuration/make-config.mdx). |
+| **Edit files directly**  | Full control — `apitogo.config.json`, `pages/**`, `landing/LandingPage.tsx`, etc.                                                 |
+Common CLI shape tasks:
+| Change                            | How                                                              |
+| --------------------------------- | ---------------------------------------------------------------- |
+| Backend runtime                   | `npx apitogo config` (backend)                                   |
+| OpenAPI files (`gateway.specs`)   | `npx apitogo config` (openapi)                                   |
+| Custom docs pages                 | `npx apitogo config` (page) or add under `apitogo/portal/pages/` |
+| Gateway / API plans               | `npx apitogo config` (plan) or edit `apitogo/plans.json`         |
+| Site title                        | `--title` or edit `apitogo.config.json`                          |
+| Theme, fonts, branding, projectId | Edit `apitogo.config.json`                                       |
+Home page content often lives in `landing/LandingPage.tsx`. Site footer can live under
+`modules.landing.content.footer` in `apitogo.config.json`.
+## Config model (local site)
+| File                  | Role                                  |
+| --------------------- | ------------------------------------- |
+| `apitogo.config.json` | Site, modules, plans, auth type, apis |
+| `.env`                | `VITE_*` + `APITOGO_CONFIG_*` secrets |
+Details: [Manifest](../configuration/manifest.md).
+## CLI vs MCP
+Both paths use the same config-first model. `npx apitogo deploy` runs the same engine as MCP
+`publish_dev_portal`.
+| Task              | CLI                                           | MCP (agent)                                   |
+| ----------------- | --------------------------------------------- | --------------------------------------------- |
+| Scaffold          | `npx @lukoweb/apitogo@latest init`            | `create_dev_portal`                           |
+| Shape config      | `npx apitogo config` + file edits             | `apply_product_intent` (shape)                |
+| Preview           | `npx apitogo run`                             | `npm run dev` / preview tool                  |
+| Publish           | `npx apitogo deploy`                          | `publish_dev_portal`                          |
+| Status / teardown | `npx apitogo status` / `npx apitogo teardown` | `verify_dev_portal_live` / `teardown_project` |
+Prefer MCP when an agent should drive changes. Prefer CLI for CI, scripts, or terminal-only
+workflows.
+## Next
+- [Install the CLI](./setup.md)
+- [Shape](./shape.md) · [Go live](./go-live.md) · [Commands](./commands.md)
+- [MCP overview](../mcp/overview.md) — agent-driven workflow
+- [Manifest](../configuration/manifest.md)

package/docs/cli/shape.md CHANGED Viewed

@@ -1,127 +1,126 @@
----
-title: Shape with CLI
-description:
-  Scaffold and customize a developer portal locally with npx apitogo init, config, and run.
-sidebar_icon: pencil-ruler
----
-**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without
-publishing. You preview with `npx apitogo run`.
-Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed it yet, see
-[Install the CLI](./setup.md).
-## Happy path
-`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name or
-`--name` to override), installs dependencies, and wires nearby OpenAPI / docs. Then run config via
-`npx`:
-```bash
-npx @lukoweb/apitogo@latest init
-cd dev-portal
-npx apitogo config         # backend, OpenAPI, pages, plans (apply each immediately)
-npx apitogo run            # http://localhost:3000
-```
-Named folder:
-```bash
-npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
-cd ./my-portal
-npx apitogo config
-npx apitogo run
-```
-`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
-ready to go live.
-## Interactive config (`npx apitogo config`)
-On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
-continues until you type `done`:
-| Choice    | What it does                                                            |
-| --------- | ----------------------------------------------------------------------- |
-| `backend` | Set `backend.sourceDirectory`, `runtime`, and platform `runtimeVersion` |
-| `openapi` | Link an OpenAPI file by **relative path** in `apitogo.config.json`      |
-| `page`    | Create `pages/<slug>.tsx` and wire it in navigation                     |
-| `plan`    | Add a gateway plan (title, price, rate limit, monthly quota)            |
-Authentication is **on by default** — the wizard does not ask for an auth API URL.
-`npx apitogo deploy` fills `VITE_APITOGO_AUTHENTICATION_API_BASE_URL` after the portal backend
-exists.
-Fonts and colors are **not** prompted — edit `apitogo.config.json` or see
-[Colors & theme](../customization/colors-theme.mdx).
-**Paid plans:** if any plan has `priceAmount > 0`, you need **Starter** or **Professional** platform
-hosting on deploy. **Free** cannot publish paid gateway plans or custom domains.
-Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
-[Gateway plans](../configuration/plans.md)
-## Configure with flags
-Writes or updates **`apitogo.config.json`**. Can create `package.json`, `tsconfig.json`, and portal
-stubs when missing. Scans `pages/` for navigation and wires OpenAPI when a spec is found.
-```bash
-npx apitogo config
-npx apitogo config --title "Books API"
-npx apitogo config --theme '{"light":{"primary":"#111111"}}'
-npx apitogo config --no-interactive
-```
-Common flags:
-| Flag                                    | Purpose                                                    |
-| --------------------------------------- | ---------------------------------------------------------- |
-| `--interactive` / `-i`                  | Force wizard (default on TTY). `--no-interactive` skips it |
-| `--title`                               | Set `site.title`                                           |
-| `--theme`, `--site`, `--authentication` | Deep-merge JSON into config                                |
-| `--pages-dir`                           | Folder to scan (default: `pages`)                          |
-| `--force`                               | Rebuild Documentation nav from disk                        |
-## Shape by editing files
-After `npx apitogo config`, edit the manifest and site files directly:
-- **Plans, branding, backend, projectId** — `apitogo.config.json`
-- **Docs pages** — `pages/**/*.mdx` or `.tsx`
-- **Home page** — `landing/LandingPage.tsx`
-- **Footer** — `modules.landing.content.footer` in `apitogo.config.json`
-Never put OIDC or Stripe secrets in `apitogo.config.json`. Use `.env` with
-`APITOGO_CONFIG_AUTHENTICATION__*` before publish.
-## Preview locally
-```bash
-npx apitogo run
-npx apitogo run --port 4000 --open
-```
-Production build check:
-```bash
-npx apitogo build
-npx apitogo build --preview
-```
-Shape-phase edits hot-reload when the dev server is running.
-## Existing docs + OpenAPI folder
-If you already have `pages/` and an OpenAPI spec:
-```bash
-npx @lukoweb/apitogo@latest init
-cd dev-portal
-npx apitogo config
-npx apitogo run
-```
-## Next
-When the site looks right, [go live](./go-live.md) with `npx apitogo deploy`.
+---
+title: Shape with CLI
+description:
+  Scaffold and customize a developer portal locally with npx apitogo init, config, and run.
+sidebar_icon: pencil-ruler
+---
+**Shape** means: create or update a local portal site (OpenAPI, plans, docs pages, auth) without
+publishing. You preview with `npx apitogo run`.
+Requires the **`apitogo`** CLI (`@lukoweb/apitogo`). If you have not installed it yet, see
+[Install the CLI](./setup.md).
+## Happy path
+`npx @lukoweb/apitogo@latest init` scaffolds into `./dev-portal` by default (pass a folder name or
+`--name` to override), installs dependencies, and wires nearby OpenAPI / docs. Then run config via
+`npx`:
+```bash
+npx @lukoweb/apitogo@latest init
+cd dev-portal
+npx apitogo config         # backend, OpenAPI, pages, plans (apply each immediately)
+npx apitogo run            # http://localhost:3000
+```
+Named folder:
+```bash
+npx @lukoweb/apitogo@latest init ./my-portal --name "Books API"
+cd ./my-portal
+npx apitogo config
+npx apitogo run
+```
+`npx @lukoweb/apitogo init` does **not** call the platform. Run `npx apitogo deploy` when you are
+ready to go live.
+## Interactive config (`npx apitogo config`)
+On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
+continues until you type `done`:
+| Choice    | What it does                                                             |
+| --------- | ------------------------------------------------------------------------ |
+| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version       |
+| `openapi` | Add an OpenAPI file to `gateway.specs`                                   |
+| `page`    | Create `apitogo/portal/pages/<slug>.mdx` (the sidebar follows the files) |
+| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)     |
+Fonts and colors are **not** prompted. See [Colors & theme](../customization/colors-theme.mdx).
+**Paid plans:** a plan with a price needs `plans.billing.provider: "stripe"`, and **Starter** or
+**Professional** platform hosting on deploy. **Free** cannot publish paid gateway plans or custom
+domains.
+Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
+[Gateway plans](../configuration/plans.md)
+## Configure with flags
+Changes a config version 2 project. Every change to `apitogo.config.json` is checked before it is
+written. The command does not create a project: use `init` or `create` for that.
+```bash
+npx apitogo config --title "Books API"
+npx apitogo config --page-slug guides/quickstart --page-title "Quickstart"
+npx apitogo config --plan '{"sku":"free","displayName":"Free"}'
+npx apitogo config --no-interactive
+```
+Common flags:
+| Flag                                         | Purpose                                                    |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| `--interactive` / `-i`                       | Force wizard (default on TTY). `--no-interactive` skips it |
+| `--title`                                    | Set `portal.name`                                          |
+| `--source`, `--runtime`, `--runtime-version` | Set `gateway.origin`                                       |
+| `--openapi`                                  | Add a file to `gateway.specs`                              |
+| `--page-slug`, `--page-title`                | Add a docs page                                            |
+| `--plan`                                     | Add or replace a plan in `plans.json`                      |
+| `--patch`                                    | Deep-merge JSON into `apitogo.config.json`                 |
+## Shape by editing files
+After `npx apitogo config`, edit the manifest and site files directly:
+- **Services, backend, OpenAPI files** — `apitogo.config.json`
+- **Plans** — `apitogo/plans.json`
+- **Docs pages** — `apitogo/portal/pages/**/*.mdx`
+- **Home page** — the file in `portal.landing` (for example
+  `apitogo/portal/landing/LandingPage.tsx`)
+Never put OIDC or Stripe secrets in `apitogo.config.json`. Use `.env` with
+`APITOGO_CONFIG_AUTHENTICATION__*` before publish.
+## Preview locally
+```bash
+npx apitogo run
+npx apitogo run --port 4000 --open
+```
+Production build check:
+```bash
+npx apitogo build
+npx apitogo build --preview
+```
+Shape-phase edits hot-reload when the dev server is running.
+## Existing docs + OpenAPI folder
+If you already have `pages/` and an OpenAPI spec:
+```bash
+npx @lukoweb/apitogo@latest init
+cd dev-portal
+npx apitogo config
+npx apitogo run
+```
+## Next
+When the site looks right, [go live](./go-live.md) with `npx apitogo deploy`.