@lukoweb/apitogo 0.2.57 → 0.2.59

package/docs/mcp/tools.md

@@ -1,101 +1,57 @@
 ---
 title: MCP tools
-description: APItoGo MCP tool catalog by category and hand-edit exceptions.
+description: Every tool of the APItoGo MCP server and the CLI command it runs.
 sidebar_icon: wrench
 ---
 
-Tools are exposed by the APItoGo MCP server. Prefer **`apply_product_intent`** for create / shape /
-go-live. Use granular tools for advanced edits, debugging, or CI.
-
-## Lifecycle (prefer these)
-
-| Tool                                 | Role                                           |
-| ------------------------------------ | ---------------------------------------------- |
-| `apply_product_intent`               | Shape or goLive from a product intent          |
-| `create_dev_portal`                  | Scaffold site (+ optional project bootstrap)   |
-| `check_dev_portal_publish_readiness` | Pre-publish checklist                          |
-| `publish_dev_portal`                 | Publish portal + plans (+ optional backend)    |
-| `verify_dev_portal_live`             | Post-publish verification                      |
-| `bootstrap_dev_portal`               | CI one-shot provision + deploy                 |
-| `bootstrap_project`                  | Create platform project only (plan unselected) |
-| `teardown_project`                   | Tear down a project                            |
-
-## Site shaping
-
-| Tool                               | Role                                                                      |
-| ---------------------------------- | ------------------------------------------------------------------------- |
-| `update_dev_portal_manifest`       | Plans, branding, backend, projectId                                       |
-| `set_dev_portal_openapi`           | OpenAPI / API reference                                                   |
-| `set_dev_portal_theme`             | Colors and fonts                                                          |
-| `add_dev_portal_page`              | Add a TSX docs page (site components; `template`: docs\|guide\|marketing) |
-| `update_dev_portal_page`           | Edit a docs page                                                          |
-| `scaffold_dev_portal_landing_page` | Scaffold missing landing file                                             |
-| `get_dev_portal_landing_guide`     | Landing component catalog                                                 |
-| `preview_dev_portal_site`          | Start / restart local preview                                             |
-| `build_dev_portal_site`            | Production build                                                          |
-
-Hosted page CRUD also exists (`list/create/delete/rename/reorder_dev_portal_pages`) for the platform
-API surface.
-
-## Projects and platform billing
-
-| Tool                                        | Role                                  |
-| ------------------------------------------- | ------------------------------------- |
-| `whoami`, `list_projects`, `get_project`, … | Tenant / project CRUD                 |
-| `list_platform_plans`                       | Free / Starter / Professional + quota |
-| `ensure_platform_plan`                      | Select or checkout platform plan      |
-| `wait_for_platform_plan`                    | Poll until active                     |
-| `get_subscription`                          | Current subscription                  |
-| `select_free_plan`                          | Free hosting                          |
-| `create_checkout_session`                   | Stripe checkout for paid hosting      |
-
-## Backend and OpenAPI
-
-| Tool                    | Role                     |
-| ----------------------- | ------------------------ |
-| `validate_openapi`      | Validate OpenAPI         |
-| `update_openapi`        | Update stored OpenAPI    |
-| `package_backend`       | Package backend artifact |
-| `deploy_backend`        | Deploy API hub           |
-| `get_backend_summary`   | Backend status           |
-| `get_deployment_status` | Deployment job status    |
-| `get_gateway_readiness` | Gateway readiness        |
-
-## Gateway
-
-| Tool                                                               | Role                     |
-| ------------------------------------------------------------------ | ------------------------ |
-| `list/get/create/update/patch_gateway_plan`                        | Plan CRUD                |
-| `add_actions_to_gateway_plan` / `remove_actions_from_gateway_plan` | Attach ops               |
-| `set_action_public`                                                | Public routes            |
-| `upsert_entitlement`                                               | Entitlements             |
-| `configure_gateway_baseline`                                       | Baseline policies        |
-| `get/update_gateway_settings`                                      | Settings                 |
-| `get/update_gateway_auth`                                          | Gateway auth             |
-| `sync_gateway_plans_from_manifest`                                 | Post-publish action sync |
-| `reorder_gateway_plans_from_manifest`                              | Plan order               |
-
-## Infrastructure and deploy
-
-| Tool                                                   | Role             |
-| ------------------------------------------------------ | ---------------- |
-| `activate_module`                                      | Activate modules |
-| `get_infrastructure_status` / Azure variants           | Infra status     |
-| `list_provisioning_jobs`, `wait_for_job`               | Jobs             |
-| `get/set/delete_custom_domain`                         | Custom domain    |
-| `get_dev_portal_deploy_config`, `deploy_dev_portal`, … | SWA deploy       |
-
-## Hand-edit exceptions
-
-| Change            | Where                                                    |
-| ----------------- | -------------------------------------------------------- |
-| Home page content | `landing/LandingPage.tsx`                                |
-| Site footer       | `apitogo.config.json` → `modules.landing.content.footer` |
-
-There is **no** `update_dev_portal_landing` tool for arbitrary home content.
-
-## Related
-
-- [Overview](./overview.md)
-- [Shape](./shape.md)
-- [Go live](./go-live.md)
+Each tool runs one `apitogo` command with `--json` in the project folder and answers with its JSON.
+Every tool takes `directory`: the project folder, absolute or relative to where the server runs
+(default: that folder).
+
+## Make and shape a project
+
+| Tool             | Runs                       | What it does                                                            |
+| ---------------- | -------------------------- | ----------------------------------------------------------------------- |
+| `apitogo_create` | `apitogo create`           | A new project folder; `template` `full` or `blank`, optional `services` |
+| `apitogo_init`   | `apitogo init`             | Prepares an existing folder: `apitogo.config.json` and `apitogo/` only  |
+| `apitogo_add`    | `apitogo add <service>`    | Adds `portal`, `gateway`, `identity` or `plans`; settings in `options`  |
+| `apitogo_remove` | `apitogo remove <service>` | Takes a service out of the config; `deleteFiles` also deletes its files |
+| `apitogo_config` | `apitogo config`           | Portal name, OpenAPI, docs pages, plans, or a `patch` of the config     |
+
+`options` of `apitogo_add` and `apitogo_config` are the command's flags in camelCase, for example
+`{"planSku":"pro","planPrice":"19"}` for `--plan-sku pro --plan-price 19`. A flag the command does
+not have is refused before anything runs. `true` and `false` are `--flag` and `--no-flag`; a list
+repeats the flag.
+
+## Check, preview, deploy
+
+| Tool             | Runs             | What it does                                                 |
+| ---------------- | ---------------- | ------------------------------------------------------------ |
+| `apitogo_check`  | `apitogo check`  | Checks the config and its files; `offline`, `validateBuild`  |
+| `apitogo_plan`   | `apitogo plan`   | What a deploy would do for each service; changes nothing     |
+| `apitogo_deploy` | `apitogo deploy` | Deploys what changed; `only`, `force`, `confirmIrreversible` |
+| `apitogo_status` | `apitogo status` | Each service's state and addresses; `skipLive` is faster     |
+
+## Platform project
+
+| Tool                     | Runs                       | What it does                                                                                   |
+| ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------- |
+| `apitogo_project_create` | `apitogo project create`   | Creates the project; `plan` free, starter or professional                                      |
+| `apitogo_project_use`    | `apitogo project use <id>` | Points the folder at another existing project                                                  |
+| `apitogo_secrets_list`   | `apitogo secrets list`     | The names of the project's secrets, never their values                                         |
+| `apitogo_secrets_remove` | `apitogo secrets rm`       | Removes a secret                                                                               |
+| `apitogo_teardown`       | `apitogo teardown`         | Deletes the project, or with `only` its gateway, identity or plans; needs `confirmProjectName` |
+
+## Not a tool, on purpose
+
+| Command               | Why                                                       |
+| --------------------- | --------------------------------------------------------- |
+| `apitogo login`       | Opens a browser to sign you in; run it once in a terminal |
+| `apitogo secrets set` | A secret's value must not pass through the agent          |
+| `apitogo run`         | The local preview keeps running; start it yourself        |
+
+## Safety hints
+
+Tools carry MCP hints so hosts can ask before running them: `apitogo_check`, `apitogo_plan`,
+`apitogo_status` and `apitogo_secrets_list` are read-only; `apitogo_remove`,
+`apitogo_secrets_remove` and `apitogo_teardown` are marked destructive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.57",
+  "version": "0.2.59",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/gateway-request.ts

@@ -39,11 +39,13 @@ export type GatewayConfigBody = {
 export type DerivedCorsSite = { origin: string; source: "portal" | "docs" };
 
 /**
- * The browser origins of this project's own sites: the portal (from `services.json`) and an external docs site
- * (from the config). Only the origin is kept, never a path. Sorted, so the same sites always give the same body.
+ * The browser origins of this project's own sites: the portal and its custom domain (from `services.json`) and an
+ * external docs site (from the config). Only the origin is kept, never a path. Sorted, so the same sites always give the same body.
  */
 export function derivedCorsSites(sites: {
   portalUrl?: string;
+  /** The portal's custom domain, once it is ready (API-130). */
+  portalCustomDomain?: string;
   docsUrl?: string;
 }): DerivedCorsSite[] {
   const originOf = (url?: string) => {
@@ -58,6 +60,7 @@ export function derivedCorsSites(sites: {
   const found = [
     { origin: originOf(sites.docsUrl), source: "docs" as const },
     { origin: originOf(sites.portalUrl), source: "portal" as const },
+    { origin: originOf(sites.portalCustomDomain), source: "portal" as const },
   ].flatMap((site) => (site.origin ? [{ ...site, origin: site.origin }] : []));
   const seen = new Set<string>();
   return found

package/src/config/v2/index.ts

@@ -70,6 +70,7 @@ export {
   withGatewayEntry,
   withIdentityEntry,
   withPlansEntry,
+  withPortalCustomDomain,
   withPortalEntry,
   writeManifest,
 } from "./manifest.js";

package/src/config/v2/manifest.ts

@@ -29,6 +29,8 @@ const ServiceManifestSchema = z.looseObject({
       portal: z
         .looseObject({
           url: z.string().optional(),
+          /** The portal's custom domain once it is ready, such as `https://docs.acme.com` (API-130). */
+          customDomain: z.string().optional(),
           docs: z
             .looseObject({ provider: z.string(), url: z.string().optional() })
             .optional(),
@@ -291,6 +293,29 @@ export function withPortalEntry(
   };
 }
 
+/**
+ * Records the portal's custom domain (an https origin), or removes it when undefined (API-130). The gateway lets the
+ * browser call it from there, and `plan` reads it from here, so it agrees with deploy without asking the platform.
+ * Returns undefined when nothing changes, so an unchanged deploy leaves the file (and the portal's build hash) alone.
+ */
+export function withPortalCustomDomain(
+  existing: ServiceManifest | undefined,
+  customDomain: string | undefined,
+): ServiceManifest | undefined {
+  if (!existing) return undefined;
+  const portal = existing.services.portal;
+  if (portal?.customDomain === customDomain) return undefined;
+  if (!portal && customDomain === undefined) return undefined;
+  const { customDomain: _previous, ...rest } = portal ?? {};
+  return {
+    ...existing,
+    services: {
+      ...existing.services,
+      portal: customDomain === undefined ? rest : { ...rest, customDomain },
+    },
+  };
+}
+
 /**
  * Adds the gateway entry a gateway deploy learned. Only public values: the base URL and what the platform says the
  * gateway can do. Entries of other services are kept as they are.

package/src/config/v2/resolve.ts

@@ -169,7 +169,11 @@ export function resolveConfigV2(
                   }
                 : {
                     light: logoSource(configDir, portal.logo.light),
-                    dark: logoSource(configDir, portal.logo.dark),
+                    // Without a dark image, the light one is used in both color schemes.
+                    dark: logoSource(
+                      configDir,
+                      portal.logo.dark ?? portal.logo.light,
+                    ),
                     ...(portal.logo.alt ? { alt: portal.logo.alt } : {}),
                   },
           }

package/src/config/v2/schema.ts

@@ -49,12 +49,25 @@ export const PortalSchema = z.strictObject({
   landing: path.optional(),
   /** The footer: a React component file shown under every page except the console's (API-129). */
   footer: path.optional(),
-  /** The logo in the portal header: one image, or one per color scheme (API-129). */
+  /**
+   * The logo in the portal header: one image, or one per color scheme (API-129). `dark` is optional; without it the
+   * light image is used in both.
+   */
   logo: z
-    .union([
-      path,
-      z.strictObject({ light: path, dark: path, alt: z.string().optional() }),
-    ])
+    .union(
+      [
+        path,
+        z.strictObject({
+          light: path,
+          dark: path.optional(),
+          alt: z.string().optional(),
+        }),
+      ],
+      {
+        error:
+          'must be an image path or https address, or { "light": "...", "dark": "...", "alt": "..." } (dark and alt are optional)',
+      },
+    )
     .optional(),
   requireAuth: z
     .union([z.boolean(), z.strictObject({ exclude: pathList })], {

package/src/vite/prerender/utils.ts

@@ -1,76 +1,89 @@
-import type { RouteObject } from "react-router";
-import { joinUrl } from "../../lib/util/joinUrl.js";
-
-const resolveRoutePath = (path: string): string | undefined => {
-  const segments = path.split("/");
-  if (segments.some((s) => s.startsWith(":") && !s.endsWith("?"))) {
-    return undefined;
-  }
-  return segments.filter((s) => !s.startsWith(":")).join("/") || undefined;
-};
-
-const isSkipped = (path: string) => path.includes("*") || /^\d+$/.test(path);
-
-export type RouteRewrite = { source: string; destination: string };
-
-type ResolvedRoute = {
-  path: string;
-  hasStrippedParams: boolean;
-  children: ResolvedRoute[];
-};
-
-const resolveRoutes = (
-  routes: RouteObject[],
-  parentPath = "",
-): ResolvedRoute[] =>
-  routes.flatMap((route) => {
-    if (route.path && isSkipped(route.path)) return [];
-
-    const routePath = route.path ? resolveRoutePath(route.path) : undefined;
-    if (route.path && !routePath) return [];
-
-    const fullPath = routePath
-      ? routePath.startsWith("/")
-        ? routePath
-        : joinUrl(parentPath, routePath)
-      : parentPath;
-
-    const hasStrippedParams =
-      route.path?.split("/").some((s) => s.startsWith(":")) ?? false;
-
-    return [
-      {
-        path: fullPath,
-        hasStrippedParams,
-        children: resolveRoutes(route.children ?? [], fullPath),
-      },
-    ];
-  });
-
-const collectPaths = (
-  resolved: ResolvedRoute[],
-  parentPath: string,
-): string[] =>
-  resolved.flatMap((r) => [
-    ...(r.path !== parentPath ? [r.path] : []),
-    ...collectPaths(r.children, r.path),
-  ]);
-
-const collectRewrites = (resolved: ResolvedRoute[]): RouteRewrite[] =>
-  resolved.flatMap((r) => [
-    ...(r.hasStrippedParams && r.path
-      ? [
-          {
-            source: `${r.path}/(.+)`,
-            destination: r.path === "/" ? "/index.html" : `${r.path}.html`,
-          },
-        ]
-      : []),
-    ...collectRewrites(r.children),
-  ]);
-
-export const routesToPaths = (routes: RouteObject[]): string[] =>
-  collectPaths(resolveRoutes(routes), "");
-
-export const routesToRewrites = (routes: RouteObject[]): RouteRewrite[] =>
-  collectRewrites(resolveRoutes(routes));
+import type { RouteObject } from "react-router";
+import { joinUrl } from "../../lib/util/joinUrl.js";
+
+const resolveRoutePath = (path: string): string | undefined => {
+  const segments = path.split("/");
+  if (segments.some((s) => s.startsWith(":") && !s.endsWith("?"))) {
+    return undefined;
+  }
+  return segments.filter((s) => !s.startsWith(":")).join("/") || undefined;
+};
+
+const isSkipped = (path: string) => path.includes("*") || /^\d+$/.test(path);
+
+export type RouteRewrite = { source: string; destination: string };
+
+type ResolvedRoute = {
+  path: string;
+  hasStrippedParams: boolean;
+  children: ResolvedRoute[];
+};
+
+const resolveRoutes = (
+  routes: RouteObject[],
+  parentPath = "",
+): ResolvedRoute[] =>
+  routes.flatMap((route) => {
+    if (route.path && isSkipped(route.path)) return [];
+
+    const routePath = route.path ? resolveRoutePath(route.path) : undefined;
+    if (route.path && !routePath) return [];
+
+    const fullPath = routePath
+      ? routePath.startsWith("/")
+        ? routePath
+        : joinUrl(parentPath, routePath)
+      : parentPath;
+
+    const hasStrippedParams =
+      route.path?.split("/").some((s) => s.startsWith(":")) ?? false;
+
+    return [
+      {
+        path: fullPath,
+        hasStrippedParams,
+        children: resolveRoutes(route.children ?? [], fullPath),
+      },
+    ];
+  });
+
+const collectPaths = (
+  resolved: ResolvedRoute[],
+  parentPath: string,
+): string[] =>
+  resolved.flatMap((r) => [
+    ...(r.path !== parentPath ? [r.path] : []),
+    ...collectPaths(r.children, r.path),
+  ]);
+
+/**
+ * The file a prerendered page is written to. `/` is `index.html`; any other page is `<path>.html`, except a page whose
+ * last segment is `index`: `/index.html` is the home page's file, and a docs page at `/index` (kept off `/` when the
+ * portal has a home page) overwrote it, so the home page was served as the docs page until the browser took over
+ * (API-130). Such a page gets a folder of its own instead.
+ */
+export const prerenderFileFor = (urlPath: string): string =>
+  urlPath === "/"
+    ? "/index.html"
+    : urlPath.endsWith("/index")
+      ? `${urlPath}/index.html`
+      : `${urlPath}.html`;
+
+const collectRewrites = (resolved: ResolvedRoute[]): RouteRewrite[] =>
+  resolved.flatMap((r) => [
+    ...(r.hasStrippedParams && r.path
+      ? [
+          {
+            source: `${r.path}/(.+)`,
+            destination: prerenderFileFor(r.path),
+          },
+        ]
+      : []),
+    ...collectRewrites(r.children),
+  ]);
+
+export const routesToPaths = (routes: RouteObject[]): string[] =>
+  collectPaths(resolveRoutes(routes), "");
+
+export const routesToRewrites = (routes: RouteObject[]): RouteRewrite[] =>
+  collectRewrites(resolveRoutes(routes));

package/src/vite/prerender/worker.ts

@@ -7,6 +7,7 @@ import type { ZudokuConfig } from "../../config/validators/ZudokuConfig.js";
 import { runPluginTransformConfig } from "../../lib/core/transform-config.js";
 import { joinUrl } from "../../lib/util/joinUrl.js";
 import type { WorkerResult } from "./prerender.js";
+import { prerenderFileFor } from "./utils.js";
 
 type EntryServer = typeof import("../../app/entry.server.js");
 
@@ -47,7 +48,7 @@ const routes = server.getRoutesByConfig(config);
 const { basePath } = config;
 
 const renderPage = async ({ urlPath }: WorkerData): Promise<WorkerResult> => {
-  const filename = urlPath === "/" ? "/index.html" : `${urlPath}.html`;
+  const filename = prerenderFileFor(urlPath);
   const pathname = joinUrl(basePath, urlPath);
   const url = joinUrl("http://localhost", pathname);
   const outputPath = path.join(distDir, filename);