@lukoweb/apitogo 0.2.35 → 0.2.37

package/src/config/v2/services.ts

@@ -56,6 +56,18 @@ const DEFAULT_RUNTIME_VERSION = {
   dotnet: "DOTNET_8",
 } as const;
 
+/** What users read first (decision 28); the technical name follows in brackets. */
+export const SERVICE_LABELS: Record<ServiceName, string> = {
+  portal: "Developer website",
+  gateway: "API protection",
+  identity: "Login for API users",
+  plans: "Pricing and API keys",
+};
+
+/** For example `API protection (gateway)`. */
+export const serviceLabel = (service: ServiceName): string =>
+  `${SERVICE_LABELS[service]} (${service})`;
+
 export function isServiceName(value: string): value is ServiceName {
   return (SERVICES as readonly string[]).includes(value);
 }
@@ -69,6 +81,8 @@ export type AddOptions = {
   disabled?: boolean;
   /** Include every docs folder found instead of asking. */
   acceptAllDocs?: boolean;
+  /** Content to create: `blank` is an empty shell, `starter` a filled example (portal, gateway and plans). */
+  template?: "blank" | "starter";
   portal?: {
     name?: string;
     docs?: string[] | false;
@@ -124,6 +138,8 @@ export type ServiceEdit = {
   /** Files created by an add; files that already exist are listed in `keep` and never overwritten. */
   files: PlannedFile[];
   keep: string[];
+  /** Files and folders a `remove --delete-files` will delete (absolute paths). */
+  deletes: string[];
   /** Human-readable follow-ups: secrets to set, files left behind after a remove. */
   notes: string[];
 };
@@ -137,6 +153,13 @@ const exists = (target: string) =>
 const rel = (dir: string, target: string) =>
   path.relative(dir, target).split(path.sep).join("/") || ".";
 
+const BLANK_SPEC = (name: string) => `openapi: 3.1.0
+info:
+  title: ${JSON.stringify(name)}
+  version: 1.0.0
+paths: {}
+`;
+
 const STARTER_SPEC = (name: string) => `openapi: 3.1.0
 info:
   title: ${JSON.stringify(name)}
@@ -288,11 +311,21 @@ async function buildPortal(
       }
     }
     if (content.length === 0) {
-      await addFile(
-        context,
-        path.join(resolved.root, "portal", "pages", "index.mdx"),
-        starterPage(name),
-      );
+      let template = options.template;
+      if (!template && options.ask)
+        template = await options.ask.choose("Content of the new site", [
+          { value: "starter", label: "A starter page I can edit" },
+          { value: "blank", label: "An empty pages folder" },
+        ]);
+      const pages = path.join(resolved.root, "portal", "pages");
+      if (template === "blank")
+        await addFile(context, path.join(pages, ".gitkeep"), "");
+      else
+        await addFile(
+          context,
+          path.join(pages, "index.mdx"),
+          starterPage(name),
+        );
     }
   }
 
@@ -391,7 +424,9 @@ async function buildGateway(
 
   let specs: string[];
   let requestedSpecs = o.spec ?? [];
-  let createSpec = o.createSpec === true;
+  let createSpec =
+    o.createSpec === true ||
+    (requestedSpecs.length === 0 && options.template !== undefined);
   if (requestedSpecs.length === 0 && !createSpec && ask) {
     const answer = await ask.choose("OpenAPI file of your API", [
       { value: "create", label: "Start from a small file the command creates" },
@@ -421,7 +456,13 @@ async function buildGateway(
     }
   } else if (createSpec) {
     const target = path.join(resolved.apisDir, "openapi.yaml");
-    await addFile(context, target, STARTER_SPEC(resolved.project.name));
+    await addFile(
+      context,
+      target,
+      options.template === "blank"
+        ? BLANK_SPEC(resolved.project.name)
+        : STARTER_SPEC(resolved.project.name),
+    );
     specs = [rel(dir, target)];
   } else {
     throw new ServiceEditError(
@@ -531,7 +572,13 @@ async function buildPlans(
 ): Promise<NonNullable<ConfigV2["plans"]>> {
   const { options, dir, resolved } = context;
   const o = options.plans ?? {};
-  const template = o.template ?? "free";
+  const template =
+    o.template ??
+    (options.template === "blank"
+      ? "none"
+      : options.template === "starter"
+        ? "free"
+        : "free");
   const billing = o.billing ?? "stripe";
   if (template === "tiered" && billing === "none") {
     throw new ServiceEditError(
@@ -655,6 +702,7 @@ export async function planAddService(
     config: next,
     files: context.files,
     keep: context.keep,
+    deletes: [],
     notes: context.notes,
   };
 }
@@ -665,7 +713,7 @@ export async function planAddService(
  */
 export async function planRemoveService(
   service: ServiceName,
-  options: { dir: string },
+  options: { dir: string; deleteFiles?: boolean },
 ): Promise<ServiceEdit> {
   const dir = path.resolve(options.dir);
   const { config, resolved } = loadConfigV2(dir);
@@ -690,14 +738,31 @@ export async function planRemoveService(
     );
   }
 
-  const left: string[] = [];
   const r = resolved;
-  if (service === "portal" && r.portal) left.push(rel(dir, r.portal.dir));
-  if (service === "plans" && r.plans) left.push(rel(dir, r.plans.file));
-  if (service === "gateway" && r.gateway)
-    left.push(...r.gateway.specs.map((s) => rel(dir, s)));
+  const owned: string[] = [];
+  if (service === "portal" && r.portal) owned.push(r.portal.dir);
+  if (service === "plans" && r.plans) owned.push(r.plans.file);
+  if (service === "gateway" && r.gateway) owned.push(...r.gateway.specs);
   void removed;
 
+  // `--delete-files` only deletes what lives inside the project's own `apitogo/` folder. A docs folder, a backend
+  // or a spec that the tenant pointed the config at is theirs and is always kept.
+  const inside = (target: string) => {
+    const relative = path.relative(resolved.root, target);
+    return (
+      relative !== "" &&
+      !relative.startsWith("..") &&
+      !path.isAbsolute(relative)
+    );
+  };
+  const deletes: string[] = [];
+  const left: string[] = [];
+  for (const target of owned) {
+    if (options.deleteFiles && inside(target) && (await exists(target)))
+      deletes.push(target);
+    else left.push(rel(dir, target));
+  }
+
   return {
     service,
     action: "remove",
@@ -706,7 +771,16 @@ export async function planRemoveService(
     config: next,
     files: [],
     keep: [],
-    notes: left.length > 0 ? [`Files are kept: ${left.join(", ")}.`] : [],
+    deletes,
+    notes: [
+      ...(left.length > 0
+        ? [
+            options.deleteFiles
+              ? `Files outside ${rel(dir, resolved.root)}/ are kept: ${left.join(", ")}.`
+              : `Files are kept: ${left.join(", ")}. Use --delete-files to delete the ones APItoGo created.`,
+          ]
+        : []),
+    ],
   };
 }
 
@@ -740,6 +814,8 @@ export async function applyServiceEdit(
     }
   }
   await writeConfig(edit.configPath, edit.config);
+  for (const target of edit.deletes)
+    await rm(target, { recursive: true, force: true });
   return { created };
 }
 
@@ -754,6 +830,12 @@ export function formatServiceEdit(edit: ServiceEdit): string[] {
           ...edit.files.map((file) => `  ${rel(edit.dir, file.path)}`),
         ]
       : []),
+    ...(edit.deletes.length > 0
+      ? [
+          "Will delete:",
+          ...edit.deletes.map((file) => `  ${rel(edit.dir, file)}`),
+        ]
+      : []),
     ...(edit.keep.length > 0
       ? [
           `Already there, left alone: ${edit.keep.map((file) => rel(edit.dir, file)).join(", ")}`,

package/src/config/v2/test-project.ts

@@ -0,0 +1,31 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { applyInitPlan, planInit } from "./init.js";
+import type { Layout } from "./schema.js";
+import { applyServiceEdit, planAddService } from "./services.js";
+
+/**
+ * A project as the tests of `add`, `check` and `deploy` expect to find it: `init`, then the portal with its starter
+ * page. `layout: "standalone"` is the legacy layout, kept so older projects still load.
+ */
+export async function makeProject(
+  dir: string,
+  options: { layout?: Layout; portal?: boolean; name?: string } = {},
+): Promise<void> {
+  await applyInitPlan(await planInit({ dir, name: options.name }));
+  const configPath = path.join(dir, "apitogo.config.json");
+  const config = JSON.parse(await readFile(configPath, "utf8"));
+  const layout = options.layout ?? "standalone";
+  await writeFile(
+    configPath,
+    `${JSON.stringify({ ...config, layout }, null, 2)}\n`,
+  );
+  if (options.portal !== false)
+    await applyServiceEdit(
+      await planAddService("portal", {
+        dir,
+        template: "starter",
+        portal: { docs: false },
+      }),
+    );
+}

package/src/config/v2/wrapper.ts

@@ -16,6 +16,7 @@ import {
   stubManifest,
 } from "./manifest.js";
 import { type PortalProfile, portalProfile } from "./portal-profile.js";
+import { protectedRoutesFor } from "./protected-routes.js";
 import type { ResolvedConfigV2 } from "./resolve.js";
 
 export const WRAPPER_FILE = "apitogo.config.tsx";
@@ -62,7 +63,12 @@ export type PortalPlan = {
     audience?: string;
   };
   /** Pricing, subscriptions, API keys and usage pages. */
-  plansPlugin?: { apiBaseUrl: string; keysApiBaseUrl?: string };
+  plansPlugin?: {
+    apiBaseUrl: string;
+    keysApiBaseUrl?: string;
+    /** The billing provider of the plans service (`none`, `stripe`, ...). `none`: the pages offer no payment. */
+    billing?: string;
+  };
   /** Account pages. */
   userPanel: boolean;
   /** Public sign-up page; only when identity declares `nativeSignup`. */
@@ -224,6 +230,7 @@ export function planPortal(
     plan.plansPlugin = {
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
+      billing: plans.billing,
     };
   }
 
@@ -249,7 +256,11 @@ export function buildSiteConfig(
   resolved: ResolvedConfigV2,
   plan: PortalPlan,
   theme?: unknown,
-  extras: { redirects?: HomeRedirect[]; docsNavigation?: unknown[] } = {},
+  extras: {
+    redirects?: HomeRedirect[];
+    docsNavigation?: unknown[];
+    protectedRoutes?: string[];
+  } = {},
 ): Record<string, unknown> {
   const portal = resolved.portal;
   const redirects = extras.redirects ?? [];
@@ -310,6 +321,9 @@ export function buildSiteConfig(
       : {}),
     ...(navigation.length > 0 ? { navigation } : {}),
     ...(redirects.length > 0 ? { redirects } : {}),
+    ...(extras.protectedRoutes?.length
+      ? { protectedRoutes: extras.protectedRoutes }
+      : {}),
     ...(theme !== undefined ? { theme } : {}),
     ...(plan.auth ? { authentication: authenticationFor(plan) } : {}),
     ...(plan.preview ? { preview: true } : {}),
@@ -490,6 +504,10 @@ export async function preparePortal(
     externalDocsUrl: profile.docs.url,
     apiReferencePath: plan.apiReference ? `/${API_REFERENCE_PATH}` : undefined,
     userPanel: plan.userPanel,
+    pricingPath:
+      plan.plansPlugin && hasCapability(effective.services.plans, "catalog")
+        ? CONSOLE_ROUTES.pricing
+        : undefined,
   });
   const siteConfig = buildSiteConfig(
     resolved,
@@ -498,6 +516,14 @@ export async function preparePortal(
     {
       redirects: home ? [home] : [],
       docsNavigation: docsNavigation(hostedDocRoutes),
+      protectedRoutes: protectedRoutesFor({
+        requireAuth: resolved.portal?.requireAuth,
+        hasAuth: !!plan.auth,
+        docRoutes: hostedDocRoutes,
+        apiReferencePath: plan.apiReference
+          ? `/${API_REFERENCE_PATH}`
+          : undefined,
+      }),
     },
   );
   const wrapper = renderWrapper(plan);