@lukoweb/apitogo 0.2.42 → 0.2.44

package/src/config/v2/services.ts

@@ -9,6 +9,15 @@ import {
 } from "node:fs/promises";
 import path from "node:path";
 import { ApitogoError } from "../../lib/util/invariant.js";
+import {
+  FULL_SERVER_HEALTH_PATH,
+  FULL_SERVER_TIMEOUT_SECONDS,
+  FULL_SERVER_RUNTIME,
+  FULL_SERVER_RUNTIME_VERSION,
+  FULL_SERVER_SOURCE,
+  FULL_SPEC,
+  fullServerFiles,
+} from "./full-server.js";
 import { docsFromPaths, starterPage } from "./init.js";
 import { detectExistingDocs } from "./layout.js";
 import { loadConfigV2 } from "./load.js";
@@ -129,8 +138,11 @@ 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";
+  /**
+   * Content to create: `blank` is an empty shell, `starter` a filled example (portal, gateway and plans), and `full`
+   * the starter plus a backend the platform runs, so the first deploy works without further steps.
+   */
+  template?: "blank" | "starter" | "full";
   portal?: {
     name?: string;
     docs?: string[] | false;
@@ -176,6 +188,10 @@ export type AddOptions = {
 
 export type PlannedFile = { path: string; content: string };
 
+/** The templates that fill the new files with examples. */
+const isFilled = (template: AddOptions["template"]) =>
+  template === "starter" || template === "full";
+
 export type ServiceEdit = {
   service: ServiceName;
   action: "add" | "remove";
@@ -397,7 +413,7 @@ async function buildPortal(
       const pages = path.join(resolved.root, "portal", "pages");
       if (template === "blank")
         await addFile(context, path.join(pages, ".gitkeep"), "");
-      else if (options.template === "starter") {
+      else if (isFilled(options.template)) {
         // The starter has a full home page of its own, so the docs start at /introduction, where the page links to.
         await addFile(
           context,
@@ -447,20 +463,30 @@ async function buildPortal(
 
 /**
  * A managed gateway runs the code in its source folder, and a new project has none. The folder is made (a `.gitkeep`
- * keeps it in git) and the user is told it is empty. A folder that has files is left as it is.
+ * keeps it in git) and the user is told it is empty; the full template writes a small Node.js server there instead.
+ * A folder that has files is left as it is. Returns whether the sample server was written.
  */
 async function createSourceFolder(
   context: Context,
   sourcePath: string,
-): Promise<void> {
+  runtime: Runtime,
+): Promise<boolean> {
   const folder = path.join(context.dir, sourcePath);
   const entries = await readdir(folder).catch(() => [] as string[]);
-  if (entries.some((name) => name !== ".gitkeep")) return;
+  if (entries.some((name) => name !== ".gitkeep")) return false;
+  if (context.options.template === "full" && runtime === FULL_SERVER_RUNTIME) {
+    for (const [file, content] of Object.entries(
+      fullServerFiles(context.resolved.project.name),
+    ))
+      await addFile(context, path.join(folder, file), content);
+    return true;
+  }
   if (entries.length === 0)
     await addFile(context, path.join(folder, ".gitkeep"), "");
   context.notes.push(
     `The folder ${sourcePath}/ is empty: put your backend code there before you deploy.`,
   );
+  return false;
 }
 
 async function buildGateway(
@@ -469,9 +495,11 @@ async function buildGateway(
   const { options, dir, resolved } = context;
   const o = options.gateway ?? {};
   const ask = options.ask;
+  // The full template runs a backend of its own, so it asks nothing about the origin.
+  const full = options.template === "full" && !o.url && o.origin !== "proxy";
   let mode =
     o.origin ??
-    (o.url ? "proxy" : o.source || o.runtime ? "managed" : undefined);
+    (o.url ? "proxy" : o.source || o.runtime || full ? "managed" : undefined);
   if (!mode && ask) {
     mode = await ask.choose("How does the gateway reach your API?", [
       {
@@ -492,6 +520,8 @@ async function buildGateway(
     );
   }
   let origin: NonNullable<ConfigV2["gateway"]>["origin"];
+  // The sample server was written, so the sample OpenAPI file can describe its endpoints.
+  let sampleServer = false;
   if (mode === "proxy") {
     const url =
       o.url ??
@@ -506,6 +536,7 @@ async function buildGateway(
   } else {
     const source =
       o.source ??
+      (full ? FULL_SERVER_SOURCE : undefined) ??
       (ask
         ? await ask.text("Folder with your code, relative to the project", {
             default: "server",
@@ -513,6 +544,7 @@ async function buildGateway(
         : undefined);
     const runtime =
       o.runtime ??
+      (full ? FULL_SERVER_RUNTIME : undefined) ??
       (ask
         ? await ask.choose("Runtime of your code", [
             { value: "nodejs" as const, label: "Node.js" },
@@ -523,16 +555,18 @@ async function buildGateway(
     const runtimeVersion =
       o.runtimeVersion !== undefined && runtime
         ? runtimeVersionSlug(runtime, o.runtimeVersion)
-        : ask && runtime
-          ? await ask.choose(
-              "Runtime version",
-              RUNTIME_VERSIONS[runtime].map((choice, index) => ({
-                value: choice.value as string,
-                label:
-                  index === 0 ? `${choice.label} (suggested)` : choice.label,
-              })),
-            )
-          : undefined;
+        : full && runtime === FULL_SERVER_RUNTIME
+          ? FULL_SERVER_RUNTIME_VERSION
+          : ask && runtime
+            ? await ask.choose(
+                "Runtime version",
+                RUNTIME_VERSIONS[runtime].map((choice, index) => ({
+                  value: choice.value as string,
+                  label:
+                    index === 0 ? `${choice.label} (suggested)` : choice.label,
+                })),
+              )
+            : undefined;
     if (!source || !runtime || !runtimeVersion) {
       throw new ServiceEditError(
         "--origin managed needs --source, --runtime and --runtime-version.",
@@ -542,14 +576,17 @@ async function buildGateway(
       );
     }
     const sourcePath = insideProject(dir, source, "Source folder");
+    sampleServer = await createSourceFolder(context, sourcePath, runtime);
     origin = {
       mode,
       source: sourcePath,
       runtime,
       runtimeVersion,
       ...(o.exclude?.length ? { exclude: o.exclude } : {}),
+      ...(sampleServer ? { healthPath: FULL_SERVER_HEALTH_PATH } : {}),
+      // A full project's API is hosted by the platform and sleeps when idle; the first call must outlast its start.
+      ...(full ? { timeoutSeconds: FULL_SERVER_TIMEOUT_SECONDS } : {}),
     };
-    await createSourceFolder(context, sourcePath);
   }
 
   let specs: string[];
@@ -591,7 +628,9 @@ async function buildGateway(
       target,
       options.template === "blank"
         ? BLANK_SPEC(resolved.project.name)
-        : STARTER_SPEC(resolved.project.name),
+        : sampleServer
+          ? FULL_SPEC(resolved.project.name)
+          : STARTER_SPEC(resolved.project.name),
     );
     specs = [rel(dir, target)];
   } else {
@@ -706,7 +745,7 @@ async function buildPlans(
     o.template ??
     (options.template === "blank"
       ? "none"
-      : options.template === "starter"
+      : isFilled(options.template)
         ? "starter"
         : "free");
   // Only paid plans need a billing provider. A catalog of free plans takes no payment, so its default is `none` and the

package/src/config/v2/wrapper.ts

@@ -69,7 +69,8 @@ export type PortalPlan = {
   };
   /** Pricing, subscriptions, API keys and usage pages. */
   plansPlugin?: {
-    apiBaseUrl: string;
+    /** The plans backend; absent in a demo preview, where the pages show sample data. */
+    apiBaseUrl?: string;
     keysApiBaseUrl?: string;
     /** The billing provider of the plans service (`none`, `stripe`, ...). `none`: the pages offer no payment. */
     billing?: string;
@@ -84,6 +85,11 @@ export type PortalPlan = {
   skipped: { piece: string; reason: string }[];
   /** True only for a stub manifest. Production builds refuse it. */
   preview: boolean;
+  /**
+   * A preview with no deployed identity: the portal signs in with the demo account instead, and the account and plans
+   * pages show sample data. Never set outside a preview.
+   */
+  demo?: boolean;
 };
 
 /** npm packages the generated site needs, beyond `@lukoweb/apitogo`, for what the plan registers. */
@@ -203,6 +209,20 @@ export function planPortal(
     return plan;
   }
 
+  // Before the first deploy there is no identity to sign in with. A preview signs in with the demo account instead,
+  // and the account and plans pages show sample data, so the console can be tried locally.
+  if (plan.preview && identity && !identity.issuer) {
+    plan.demo = true;
+    plan.userPanel = true;
+    skip("sign-in", "preview: the demo account signs in");
+    if (plans)
+      plan.plansPlugin = {
+        billing: "none",
+        links: plan.apiReference ? { api: `/${API_REFERENCE_PATH}` } : {},
+      };
+    return plan;
+  }
+
   if (!identity) {
     skip("sign-in", "services.json has no identity entry");
   } else if (!serviceReady(identity)) {
@@ -274,6 +294,10 @@ export function buildSiteConfig(
   extras: {
     redirects?: HomeRedirect[];
     docsNavigation?: unknown[];
+    /** The first docs page, linked from the header next to the API reference. */
+    docsPath?: string;
+    /** A demo preview's plan catalog, from `plans.json`; the pages read it from the site config. */
+    demoPlans?: unknown[];
     protectedRoutes?: string[];
   } = {},
 ): Record<string, unknown> {
@@ -346,22 +370,29 @@ export function buildSiteConfig(
         }
       : {}),
     ...(navigation.length > 0 ? { navigation } : {}),
-    // The sidebar link above is only seen inside the docs; the header is what every page shows.
+    // The sidebar link above is only seen inside the docs; the header is what every page shows. A header navigation
+    // replaces the docs tab, so the docs get a header link of their own.
     ...(plan.apiReference
       ? {
           header: {
             navigation: [
+              ...(plan.docs && extras.docsPath
+                ? [{ label: "Documentation", to: extras.docsPath }]
+                : []),
               { label: "API Reference", to: `/${API_REFERENCE_PATH}` },
             ],
           },
         }
       : {}),
+    ...(extras.demoPlans?.length ? { plans: extras.demoPlans } : {}),
     ...(redirects.length > 0 ? { redirects } : {}),
     ...(extras.protectedRoutes?.length
       ? { protectedRoutes: extras.protectedRoutes }
       : {}),
     ...(theme !== undefined ? { theme } : {}),
-    ...(plan.auth ? { authentication: authenticationFor(plan) } : {}),
+    ...(plan.auth || plan.demo
+      ? { authentication: authenticationFor(plan) }
+      : {}),
     ...(plan.preview ? { preview: true } : {}),
   };
 }
@@ -373,6 +404,8 @@ export function buildSiteConfig(
  * form. Without the plans service there is no backend, and the portal signs in with the identity directly (OpenID).
  */
 function authenticationFor(plan: PortalPlan): Record<string, unknown> {
+  // The demo form: demo@apitogo.local / password, only in a local run.
+  if (plan.demo) return { type: "dev-portal", demoMode: true };
   if (plan.plansPlugin)
     return {
       type: "dev-portal",
@@ -389,7 +422,7 @@ function authenticationFor(plan: PortalPlan): Record<string, unknown> {
 
 /** Shown on every page of a preview run, so a stand-in manifest is never mistaken for a deployed portal. */
 export const PREVIEW_BANNER_MESSAGE =
-  "Preview mode: sign-in and plans use a stand-in manifest. Run `apitogo deploy` for the real services.";
+  "Preview mode: sign in with demo@apitogo.local / password to try the console. Run `apitogo deploy` for the real services.";
 
 /** The wrapper source. Imports exist only for what the plan registers. */
 export function renderWrapper(plan: PortalPlan): string {
@@ -423,6 +456,24 @@ export function renderWrapper(plan: PortalPlan): string {
   ].join("\n");
 }
 
+/**
+ * The plans of the project's `plans.json`, for the pricing and account pages of a demo preview: with no plans backend
+ * they read their catalog from the site config. A missing or unreadable file gives no plans; `check` reports it.
+ */
+async function readDemoPlans(
+  file: string | undefined,
+): Promise<unknown[] | undefined> {
+  if (!file) return undefined;
+  try {
+    const parsed = JSON.parse(await readFile(file, "utf8")) as {
+      plans?: unknown;
+    };
+    return Array.isArray(parsed.plans) ? parsed.plans : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** The portal theme file, when it exists and parses. `check` reports an invalid one; the build just skips it. */
 async function readTheme(resolved: ResolvedConfigV2): Promise<unknown> {
   const file = resolved.portal?.theme;
@@ -567,6 +618,11 @@ export async function preparePortal(
     {
       redirects: home ? [home] : [],
       docsNavigation: docsNavigation(hostedDocRoutes),
+      docsPath: pickLandingRoute(hostedDocRoutes),
+      demoPlans:
+        plan.demo && plan.plansPlugin
+          ? await readDemoPlans(resolved.plans?.file)
+          : undefined,
       protectedRoutes: protectedRoutesFor({
         requireAuth: resolved.portal?.requireAuth,
         hasAuth: !!plan.auth,