@lukoweb/apitogo 0.2.39 → 0.2.41

package/src/config/v2/services.ts

@@ -1,4 +1,12 @@
-import { access, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import {
+  access,
+  mkdir,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import path from "node:path";
 import { ApitogoError } from "../../lib/util/invariant.js";
 import { docsFromPaths, starterPage } from "./init.js";
@@ -8,6 +16,7 @@ import { parseConfigV2 } from "./parse.js";
 import { type ResolvedConfigV2, resolveConfigV2 } from "./resolve.js";
 import { checkDependencies } from "./rules.js";
 import type { ConfigV2 } from "./schema.js";
+import { starterLandingPage } from "./starter-landing.js";
 
 export const SERVICES = ["portal", "gateway", "identity", "plans"] as const;
 export type ServiceName = (typeof SERVICES)[number];
@@ -49,13 +58,52 @@ const httpsProblem = (value: string) =>
     ? undefined
     : "The address must start with https://";
 
-/** The runtime version a prompt suggests; the platform lists the others. */
-const DEFAULT_RUNTIME_VERSION = {
-  nodejs: "NODE_22_LTS",
-  python: "PYTHON_312",
-  dotnet: "DOTNET_8",
+/** The runtime versions the platform runs, newest last; the first of each list is the one a prompt suggests. */
+const RUNTIME_VERSIONS = {
+  nodejs: [
+    { value: "NODE_22_LTS", label: "Node.js 22 (LTS)" },
+    { value: "NODE_24_LTS", label: "Node.js 24 (LTS)" },
+  ],
+  python: [
+    { value: "PYTHON_312", label: "Python 3.12" },
+    { value: "PYTHON_310", label: "Python 3.10" },
+    { value: "PYTHON_311", label: "Python 3.11" },
+    { value: "PYTHON_313", label: "Python 3.13" },
+    { value: "PYTHON_314", label: "Python 3.14" },
+  ],
+  dotnet: [
+    { value: "DOTNET_8", label: ".NET 8" },
+    { value: "DOTNET_9", label: ".NET 9" },
+    { value: "DOTNET_10", label: ".NET 10" },
+  ],
 } as const;
 
+type Runtime = keyof typeof RUNTIME_VERSIONS;
+
+/**
+ * The platform's name for a runtime version a user typed the short way: `22` or `v22` for Node.js, `3.12` for
+ * Python, `8` or `8.0` for .NET. A value that is not recognised is kept as it is, and `check` names the allowed ones.
+ */
+function runtimeVersionSlug(runtime: Runtime, value: string): string {
+  const upper = value.trim().toUpperCase();
+  const known = RUNTIME_VERSIONS[runtime].map(
+    (choice) => choice.value as string,
+  );
+  if (known.includes(upper)) return upper;
+  const digits = value
+    .trim()
+    .toLowerCase()
+    .replace(/^(v|python|\.net|dotnet|node(js)?)[ _-]?/, "")
+    .replace(/(\.x|_lts| lts)$/, "");
+  const candidate =
+    runtime === "nodejs"
+      ? `NODE_${digits.split(".")[0]}_LTS`
+      : runtime === "python"
+        ? `PYTHON_${digits.replace(".", "")}`
+        : `DOTNET_${digits.split(".")[0]}`;
+  return known.includes(candidate) ? candidate : value;
+}
+
 /** What users read first (decision 28); the technical name follows in brackets. */
 export const SERVICE_LABELS: Record<ServiceName, string> = {
   portal: "Developer website",
@@ -174,7 +222,10 @@ paths:
           description: The service is up.
 `;
 
-const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
+const PLAN_TEMPLATES: Record<
+  "free" | "tiered" | "starter" | "none",
+  unknown[]
+> = {
   none: [],
   free: [
     {
@@ -188,6 +239,31 @@ const PLAN_TEMPLATES: Record<"free" | "tiered" | "none", unknown[]> = {
       },
     },
   ],
+  // Sample plans for the starter: a free plan and two with a price on request, so they show on the pricing page and
+  // the home page and still deploy on a Free project (a plan with a price needs a paid platform plan and billing).
+  starter: [
+    {
+      sku: "free",
+      displayName: "Free",
+      default: true,
+      limits: {
+        rateLimit: { calls: 3, periodSeconds: 60 },
+        quota: { calls: 1000, periodDays: 30 },
+      },
+    },
+    {
+      sku: "pro",
+      displayName: "Pro",
+      pricingModel: "custom",
+      priceLabel: "Contact us",
+    },
+    {
+      sku: "enterprise",
+      displayName: "Enterprise",
+      pricingModel: "custom",
+      priceLabel: "Contact us",
+    },
+  ],
   tiered: [
     {
       sku: "free",
@@ -284,6 +360,7 @@ async function buildPortal(
   const name = o.name?.trim() || resolved.project.name;
 
   let content: string[] = [];
+  let landing: string | undefined;
   if (!external) {
     if (Array.isArray(o.docs) && o.docs.length > 0) {
       content = await docsFromPaths(dir, o.docs);
@@ -320,7 +397,31 @@ async function buildPortal(
       const pages = path.join(resolved.root, "portal", "pages");
       if (template === "blank")
         await addFile(context, path.join(pages, ".gitkeep"), "");
-      else
+      else if (options.template === "starter") {
+        // The starter has a full home page of its own, so the docs start at /introduction, where the page links to.
+        await addFile(
+          context,
+          path.join(pages, "introduction.mdx"),
+          starterPage(name),
+        );
+        const landingFile = path.join(
+          resolved.root,
+          "portal",
+          "landing",
+          "LandingPage.tsx",
+        );
+        await addFile(
+          context,
+          landingFile,
+          starterLandingPage({
+            name,
+            withPlans:
+              context.config.plans !== undefined &&
+              context.config.plans.enabled !== false,
+          }),
+        );
+        landing = rel(dir, landingFile);
+      } else
         await addFile(
           context,
           path.join(pages, "index.mdx"),
@@ -337,12 +438,31 @@ async function buildPortal(
       : content.length > 0
         ? { docs: { content } }
         : {}),
+    ...(landing ? { landing } : {}),
     ...(o.noConsole ? { console: { enabled: false } } : {}),
     ...(o.requireAuth ? { requireAuth: true } : {}),
     ...(o.search && !external ? { search: o.search } : {}),
   };
 }
 
+/**
+ * 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.
+ */
+async function createSourceFolder(
+  context: Context,
+  sourcePath: string,
+): Promise<void> {
+  const folder = path.join(context.dir, sourcePath);
+  const entries = await readdir(folder).catch(() => [] as string[]);
+  if (entries.some((name) => name !== ".gitkeep")) return;
+  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.`,
+  );
+}
+
 async function buildGateway(
   context: Context,
 ): Promise<NonNullable<ConfigV2["gateway"]>> {
@@ -401,25 +521,35 @@ async function buildGateway(
           ])
         : undefined);
     const runtimeVersion =
-      o.runtimeVersion ??
-      (ask && runtime
-        ? await ask.text("Runtime version", {
-            default: DEFAULT_RUNTIME_VERSION[runtime],
-          })
-        : undefined);
+      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;
     if (!source || !runtime || !runtimeVersion) {
       throw new ServiceEditError(
         "--origin managed needs --source, --runtime and --runtime-version.",
-        "For example: --source server --runtime nodejs --runtime-version NODE_22_LTS.",
+        runtime
+          ? `For ${runtime}, --runtime-version is one of: ${RUNTIME_VERSIONS[runtime].map((choice) => choice.value).join(", ")} (a short form such as ${runtime === "nodejs" ? "22" : runtime === "python" ? "3.12" : "8"} works too).`
+          : "For example: --source server --runtime nodejs --runtime-version NODE_22_LTS.",
       );
     }
+    const sourcePath = insideProject(dir, source, "Source folder");
     origin = {
       mode,
-      source: insideProject(dir, source, "Source folder"),
+      source: sourcePath,
       runtime,
       runtimeVersion,
       ...(o.exclude?.length ? { exclude: o.exclude } : {}),
     };
+    await createSourceFolder(context, sourcePath);
   }
 
   let specs: string[];
@@ -577,7 +707,7 @@ async function buildPlans(
     (options.template === "blank"
       ? "none"
       : options.template === "starter"
-        ? "free"
+        ? "starter"
         : "free");
   // Only paid plans need a billing provider. A catalog of free plans takes no payment, so its default is `none` and the
   // config checks clean right away; the tiered template (paid plans) defaults to Stripe, whose key is set with `secrets set`.

package/src/config/v2/starter-landing.ts

@@ -0,0 +1,150 @@
+/**
+ * The home page of the starter portal: hero, features, steps, an API showcase, the plans and a closing call to action,
+ * built from the sections of `@lukoweb/apitogo-module-landing`. The project owns the file and edits it freely.
+ */
+export function starterLandingPage(options: {
+  name: string;
+  /** The plans service is on, so the page can show the plans (they come from the same catalog as the pricing page). */
+  withPlans: boolean;
+}): string {
+  const name = JSON.stringify(options.name);
+  const plansImport = options.withPlans
+    ? 'import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
+    : "";
+  const plansHook = options.withPlans
+    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n\n"
+    : "";
+  const plansSection = options.withPlans
+    ? "      <PlansPreviewSection plans={plans} />\n"
+    : "";
+  return `import {
+  ApiShowcaseSection,
+  FeaturesSection,
+  HeroSection,
+  LandingShell,
+  ${options.withPlans ? "PlansPreviewSection,\n  " : ""}PricingCtaSection,
+  StepsSection,
+} from "@lukoweb/apitogo-module-landing";
+${plansImport}
+const NAME = ${name};
+
+export default function LandingPage() {
+${plansHook}  return (
+    <LandingShell
+      title={NAME}
+      description="Documentation, an API reference, sign-in, API keys and plans for your API, in one place."
+    >
+      <HeroSection
+        hero={{
+          badge: "API PORTAL",
+          title: NAME,
+          description:
+            "Everything your developers need to use your API: documentation, an interactive reference, sign-in, API keys and plans.",
+        }}
+        primaryAction={{ label: "Get started", href: "/signup" }}
+        secondaryAction={{ label: "Read the docs", href: "/introduction" }}
+        codeExamples={[
+          {
+            filename: "Call the API",
+            language: "bash",
+            code: \`$ curl https://your-api.example.com/health \\\\
+  -H "x-api-key: YOUR_API_KEY"
+# { "status": "ok" }\`,
+          },
+        ]}
+      />
+      <FeaturesSection
+        section={{
+          label: "What you get",
+          title: "A developer portal that is ready on day one",
+          description:
+            "Edit this page in apitogo/portal/landing/LandingPage.tsx to make it yours.",
+        }}
+        features={[
+          {
+            title: "Documentation",
+            description:
+              "Write pages in Markdown or MDX and they appear in the portal with a sidebar and search.",
+            icon: "book-open",
+          },
+          {
+            title: "API reference",
+            description:
+              "An interactive reference built from your OpenAPI file, with a try-it console.",
+            icon: "code",
+          },
+          {
+            title: "API keys",
+            description:
+              "People sign up, pick a plan and create keys themselves, with no work for you.",
+            icon: "shield-check",
+          },
+          {
+            title: "Plans and limits",
+            description:
+              "Rate limits and monthly quotas per plan, enforced at the gateway.",
+            icon: "gauge",
+          },
+          {
+            title: "Usage",
+            description:
+              "Each developer sees their own request counts and how much of the plan is left.",
+            icon: "activity",
+          },
+          {
+            title: "Sign-in",
+            description:
+              "Accounts and login pages that carry your name and theme.",
+            icon: "boxes",
+          },
+        ]}
+      />
+      <StepsSection
+        steps={[
+          {
+            step: "01",
+            title: "Create an account",
+            description: "Sign up in a minute, no approval queue.",
+          },
+          {
+            step: "02",
+            title: "Pick a plan",
+            description: "Start on the free plan and move up when you need more.",
+          },
+          {
+            step: "03",
+            title: "Call the API",
+            description: "Create a key and make your first request.",
+          },
+        ]}
+      />
+      <ApiShowcaseSection
+        apiShowcase={{
+          title: "Sample endpoints",
+          subtitle: "A slice of what is available. The full list is in the API reference.",
+          browseAllHref: "/api",
+          browseAllLabel: "Browse all APIs",
+          layout: "list",
+          items: [
+            {
+              name: "Health check",
+              path: "/health",
+              method: "GET",
+              summary: "Tells you the service is up.",
+            },
+          ],
+        }}
+      />
+${plansSection}      <PricingCtaSection
+        variant="banner"
+        pricingCta={{
+          title: "Start building today",
+          description: "Create an account and get your API key in minutes.",
+          primaryAction: { label: "Get started", href: "/signup" },
+        }}
+      />
+    </LandingShell>
+  );
+}
+`;
+}

package/src/config/v2/wrapper.ts

@@ -6,7 +6,12 @@ import {
   ReferenceSpecError,
   renderReferenceSpec,
 } from "./gateway-reference.js";
-import { docRoutes, type HomeRedirect, homeRedirect } from "./home-redirect.js";
+import {
+  docRoutes,
+  type HomeRedirect,
+  homeRedirect,
+  pickLandingRoute,
+} from "./home-redirect.js";
 import {
   hasCapability,
   missingManifestServices,
@@ -234,11 +239,11 @@ export function planPortal(
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
       links: {
-        ...(profile.modules.docs
-          ? { docs: "/introduction" }
-          : profile.docs.url
-            ? { docs: profile.docs.url }
-            : {}),
+        // Hosted docs are linked once their pages are known (see `buildPortalWorkspace`): there is no page to
+        // name before that, and a guessed one was a 404 on every portal whose first page is not called `introduction`.
+        ...(!profile.modules.docs && profile.docs.url
+          ? { docs: profile.docs.url }
+          : {}),
         ...(plan.apiReference ? { api: `/${API_REFERENCE_PATH}` } : {}),
       },
     };
@@ -296,6 +301,17 @@ export function buildSiteConfig(
     },
     modules: {
       docs: { enabled: plan.docs },
+      // A custom home page (`portal.landing`) is served at `/`; the build imports the component from its absolute path.
+      ...(portal?.landing
+        ? {
+            landing: {
+              enabled: true,
+              path: "/",
+              layout: "landing",
+              page: portal.landing.split(path.sep).join("/"),
+            },
+          }
+        : {}),
       // The plans pages (pricing, choosing a plan) exist only when billing is on, and the plans service is what makes it so.
       // Switching billing on also makes the user panel register its own placeholder plans page, at `/account/<path>`.
       // Its default path is `plans`, which is where the billing plugin puts the real page (subscribe, switch, cancel),
@@ -330,6 +346,16 @@ export function buildSiteConfig(
         }
       : {}),
     ...(navigation.length > 0 ? { navigation } : {}),
+    // The sidebar link above is only seen inside the docs; the header is what every page shows.
+    ...(plan.apiReference
+      ? {
+          header: {
+            navigation: [
+              { label: "API Reference", to: `/${API_REFERENCE_PATH}` },
+            ],
+          },
+        }
+      : {}),
     ...(redirects.length > 0 ? { redirects } : {}),
     ...(extras.protectedRoutes?.length
       ? { protectedRoutes: extras.protectedRoutes }
@@ -508,17 +534,32 @@ export async function preparePortal(
         includeDrafts: mode === "development",
       })
     : [];
-  const home = homeRedirect({
-    hostsDocs: plan.docs,
-    docRoutes: hostedDocRoutes,
-    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,
-  });
+  // The account pages' "Documentation" link goes to a page the portal really has, or is left out.
+  if (plan.plansPlugin && plan.docs) {
+    const landing = hostedDocRoutes.some(
+      (route) => route === "/" || route === "/index",
+    )
+      ? "/"
+      : pickLandingRoute(hostedDocRoutes);
+    if (landing)
+      plan.plansPlugin.links = { ...plan.plansPlugin.links, docs: landing };
+  }
+  // A portal with its own home page needs no redirect from `/`.
+  const home = resolved.portal?.landing
+    ? undefined
+    : homeRedirect({
+        hostsDocs: plan.docs,
+        docRoutes: hostedDocRoutes,
+        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,
     plan,