@lukoweb/apitogo 0.2.42 → 0.2.43

package/src/config/v2/services.ts

@@ -9,6 +9,14 @@ import {
 } from "node:fs/promises";
 import path from "node:path";
 import { ApitogoError } from "../../lib/util/invariant.js";
+import {
+  FULL_SERVER_HEALTH_PATH,
+  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 +137,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 +187,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 +412,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 +462,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 +494,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 +519,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 +535,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 +543,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 +554,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 +575,15 @@ 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 } : {}),
     };
-    await createSourceFolder(context, sourcePath);
   }
 
   let specs: string[];
@@ -591,7 +625,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 +742,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,

package/src/vite/watch-ignore.ts

@@ -1,70 +1,80 @@
-import { lstatSync, realpathSync } from "node:fs";
-import path from "node:path";
-
-/**
- * A config version 2 portal builds from `<state>/generated/`, where `content` is a link to the project folder.
- * That folder holds the state folder itself (`.apitogo/` or `apitogo/.state/`), which holds `generated/content`
- * again, so a file watcher that follows the link goes round forever (ENAMETOOLONG).
- */
-const STATE_INSIDE_CONTENT =
-  /[\\/]content[\\/](?:\.apitogo|apitogo[\\/]\.state)(?:[\\/]|$)/;
-
-const within = (base: string, file: string) =>
-  file === base || file.startsWith(base + path.sep);
-
-const unique = (paths: string[]) => [...new Set(paths)];
-
-/** Whether `root` is the site root (`<state>/generated`) of a config version 2 workspace: it has the `content` link. */
-function isWorkspace(root: string): boolean {
-  try {
-    return (
-      path.basename(root) === "generated" &&
-      lstatSync(path.join(root, "content")).isSymbolicLink()
-    );
-  } catch {
-    return false;
-  }
-}
-
-/**
- * The tenant's own folder of a config version 2 workspace (what `content` links to), or `undefined` for any other
- * project. The site root sits inside the state folder, so the folder that holds `node_modules` and the pages is
- * outside it and the dev server has to be told it may serve files from there.
- */
-export function tenantDir(root: string): string | undefined {
-  return isWorkspace(root)
-    ? realpathSync(path.join(root, "content"))
-    : undefined;
-}
-
-/**
- * What the dev server's watcher must leave alone in a config version 2 workspace, or `undefined` for any other
- * project. The watcher meets the state folder twice: below the `content` link and, after resolving the link,
- * by its real path. So the whole state folder is skipped, except `generated/` itself (the site root) and the
- * tenant's own files.
- */
-export function stateIgnore(
-  root: string,
-): ((file: string) => boolean) | undefined {
-  if (!isWorkspace(root)) return undefined;
-
-  const state = path.dirname(root);
-  const states = unique([state, realpathSync(state)]);
-  const roots = unique([root, realpathSync(root)]);
-
-  return (file) => {
-    if (!states.some((base) => within(base, file))) return false;
-    if (!roots.some((base) => within(base, file))) return true;
-    return STATE_INSIDE_CONTENT.test(file);
-  };
-}
-
-/**
- * The folders the dev server may serve files from. The site root of a config version 2 workspace sits inside the
- * state folder, so the package (`node_modules`) and the tenant's pages are outside it. Without them the page's main
- * script fails with "Failed to load url ... Does the file exist?" and the server stops.
- */
-export function devServerAllow(root: string, moduleDir: string): string[] {
-  const tenant = tenantDir(root);
-  return [root, path.dirname(root), moduleDir, ...(tenant ? [tenant] : [])];
-}
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * A config version 2 portal builds from `<state>/generated/`, where `content` is a link to the project folder.
+ * That folder holds the state folder itself (`.apitogo/` or `apitogo/.state/`), which holds `generated/content`
+ * again, so a file watcher that follows the link goes round forever (ENAMETOOLONG).
+ */
+const STATE_INSIDE_CONTENT =
+  /[\\/]content[\\/](?:\.apitogo|apitogo[\\/]\.state)(?:[\\/]|$)/;
+
+/**
+ * On Windows the site root can arrive as `C:/...` while the watcher reports `C:\...`, so both sides are resolved to
+ * the platform's form first; otherwise nothing matched and the watcher followed `content` until ELOOP.
+ */
+const within = (base: string, file: string) => {
+  const resolvedBase = path.resolve(base);
+  const resolvedFile = path.resolve(file);
+  return (
+    resolvedFile === resolvedBase ||
+    resolvedFile.startsWith(resolvedBase + path.sep)
+  );
+};
+
+const unique = (paths: string[]) => [...new Set(paths)];
+
+/** Whether `root` is the site root (`<state>/generated`) of a config version 2 workspace: it has the `content` link. */
+function isWorkspace(root: string): boolean {
+  try {
+    return (
+      path.basename(root) === "generated" &&
+      lstatSync(path.join(root, "content")).isSymbolicLink()
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The tenant's own folder of a config version 2 workspace (what `content` links to), or `undefined` for any other
+ * project. The site root sits inside the state folder, so the folder that holds `node_modules` and the pages is
+ * outside it and the dev server has to be told it may serve files from there.
+ */
+export function tenantDir(root: string): string | undefined {
+  return isWorkspace(root)
+    ? realpathSync(path.join(root, "content"))
+    : undefined;
+}
+
+/**
+ * What the dev server's watcher must leave alone in a config version 2 workspace, or `undefined` for any other
+ * project. The watcher meets the state folder twice: below the `content` link and, after resolving the link,
+ * by its real path. So the whole state folder is skipped, except `generated/` itself (the site root) and the
+ * tenant's own files.
+ */
+export function stateIgnore(
+  root: string,
+): ((file: string) => boolean) | undefined {
+  if (!isWorkspace(root)) return undefined;
+
+  const state = path.dirname(root);
+  const states = unique([state, realpathSync(state)]);
+  const roots = unique([root, realpathSync(root)]);
+
+  return (file) => {
+    if (!states.some((base) => within(base, file))) return false;
+    if (!roots.some((base) => within(base, file))) return true;
+    return STATE_INSIDE_CONTENT.test(file);
+  };
+}
+
+/**
+ * The folders the dev server may serve files from. The site root of a config version 2 workspace sits inside the
+ * state folder, so the package (`node_modules`) and the tenant's pages are outside it. Without them the page's main
+ * script fails with "Failed to load url ... Does the file exist?" and the server stops.
+ */
+export function devServerAllow(root: string, moduleDir: string): string[] {
+  const tenant = tenantDir(root);
+  return [root, path.dirname(root), moduleDir, ...(tenant ? [tenant] : [])];
+}