@lukoweb/apitogo 0.2.53 → 0.2.54

package/dist/cli/worker.js

@@ -115,6 +115,11 @@ var ProtectedRoutesSchema = z.pipe(
 
 // src/vite/prerender/worker.ts
 var { template, distDir, serverConfigPath, entryServerPath, writeRedirects } = Piscina.workerData;
+var isStaticNavigateWarning = (args) => typeof args[0] === "string" && args[0].includes("<Navigate> must not be used on the initial render");
+var warn = console.warn.bind(console);
+console.warn = (...args) => {
+  if (!isStaticNavigateWarning(args)) warn(...args);
+};
 var server = await import(entryServerPath);
 var rawConfig = await import(serverConfigPath).then(
   (m) => m.default
@@ -186,5 +191,6 @@ var renderPage = async ({ urlPath }) => {
 };
 var worker_default = renderPage;
 export {
-  worker_default as default
+  worker_default as default,
+  isStaticNavigateWarning
 };

package/dist/declarations/cli/common/spawn-command.d.ts

@@ -0,0 +1,3 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+export declare function quoteForWindowsShell(arg: string): string;
+export declare function spawnCommand(command: string, args: readonly string[], options?: SpawnOptions): ChildProcess;

package/dist/declarations/cli/platform/helpers/progress.d.ts

@@ -42,7 +42,10 @@ export type ConsoleProgressReporter = ProgressReporter & {
     stop(): void;
 };
 export declare function friendlyModuleNames(text: string): string;
-export declare function createConsoleProgressReporter(stream?: NodeJS.WritableStream): ConsoleProgressReporter;
+export declare function isInfrastructureMessage(message: string): boolean;
+export declare function createConsoleProgressReporter(stream?: NodeJS.WritableStream, options?: {
+    verbose?: boolean;
+}): ConsoleProgressReporter;
 export interface PollableJobValue {
     status: string;
     messages?: JobLogMessage[];

package/dist/declarations/lib/components/SiteTitle.d.ts

@@ -5,6 +5,7 @@ type SiteTitleProps = {
 export declare const splitBrandWordmark: (title: string) => {
     prefix: string;
     accent: string | null;
+    spaced: boolean;
 };
 export declare const SiteTitle: ({ title, className }: SiteTitleProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/package.json

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

package/src/config/v2/docs-navigation.ts

@@ -1,4 +1,5 @@
 import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
+import { comparePages, type PageOrders } from "./page-order.js";
 
 /** Label of the one header tab that holds the sidebar made from the docs pages. */
 export const DOCS_NAVIGATION_LABEL = "Documentation";
@@ -19,9 +20,14 @@ export function folderLabel(name: string): string {
 
 const byName = (a: string, b: string) => a.localeCompare(b);
 
-const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
+const toItems = (
+  branch: Branch,
+  prefix: string,
+  orders: PageOrders,
+): InputNavigationItem[] => {
+  // Index first, then the pages' own order, then the usual first pages, then by name (API-125).
   const names = [...branch.pages.keys()].sort((a, b) =>
-    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
+    comparePages(`/${prefix}${a}`, `/${prefix}${b}`, orders),
   );
   const folders = [...branch.folders.keys()].sort(byName);
   const folderPath = prefix === "" ? "/" : `/${prefix.slice(0, -1)}`;
@@ -51,6 +57,7 @@ const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
         items: toItems(
           branch.folders.get(folder) ?? emptyBranch(),
           `${prefix}${folder}/`,
+          orders,
         ),
       }),
     ),
@@ -77,6 +84,7 @@ const branchOf = (root: Branch, route: string) => {
 export function docsNavigation(
   routes: string[],
   customPages: readonly CustomDocsPage[] = [],
+  orders: PageOrders = new Map(),
 ): InputNavigationItem[] {
   const root = emptyBranch();
   for (const route of routes) {
@@ -88,7 +96,7 @@ export function docsNavigation(
     if (page && !branch.pages.has(page))
       branch.pages.set(page, { kind: "custom", ...custom });
   }
-  const items = toItems(root, "");
+  const items = toItems(root, "", orders);
   return items.length === 0
     ? []
     : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];

package/src/config/v2/full-server.ts

@@ -49,7 +49,7 @@ const items = [
   { id: "3", name: "Third item" },
 ];
 
-// Lets the portal's API page call this server while you run it locally (\`apitogo dev\`). Once deployed, the gateway
+// Lets the portal's API page call this server while you run it locally (\`apitogo run\`). Once deployed, the gateway
 // answers browsers itself and keeps its own list of allowed sites.
 const cors = {
   "access-control-allow-origin": "*",

package/src/config/v2/home-redirect.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { glob } from "glob";
 import globParent from "glob-parent";
 import { readFrontmatter } from "../../lib/util/readFrontmatter.js";
+import { firstPage, orderValue, type PageOrders } from "./page-order.js";
 import { toGlobPath } from "./resolve.js";
 
 export type HomeRedirect = { from: string; to: string };
@@ -57,11 +58,41 @@ export async function docRoutes(
 }
 
 /** The page a visitor lands on when the site has no home page: the top-most page, then the first by name. */
-export function pickLandingRoute(routes: string[]): string | undefined {
-  const depth = (route: string) => route.split("/").length;
-  return [...routes].sort(
-    (a, b) => depth(a) - depth(b) || a.localeCompare(b),
-  )[0];
+export function pickLandingRoute(
+  routes: string[],
+  orders?: PageOrders,
+): string | undefined {
+  return firstPage(routes, orders);
+}
+
+/**
+ * The `order` each Markdown page sets in its frontmatter, by route (API-125). Pages without one are not in the map.
+ */
+export async function docPageOrders(
+  patterns: string[],
+): Promise<Map<string, number>> {
+  const globs = patterns.map(toGlobPath);
+  const excluded = globs
+    .filter((pattern) => pattern.startsWith("!"))
+    .map((pattern) => pattern.slice(1));
+  const orders = new Map<string, number>();
+  for (const pattern of globs.filter((p) => !p.startsWith("!"))) {
+    const parent = globParent(pattern);
+    const files = await glob(pattern, {
+      absolute: true,
+      posix: true,
+      ignore: [...IGNORED, ...excluded],
+    });
+    for (const raw of files) {
+      const order = orderValue((await readFrontmatter(raw)).data.order);
+      if (order === undefined) continue;
+      const route = `/${path.posix
+        .relative(parent, raw.replace(/^\/\/\?\//, ""))
+        .replace(/\.mdx?$/, "")}`;
+      if (!orders.has(route)) orders.set(route, order);
+    }
+  }
+  return orders;
 }
 
 export type HomeRedirectInput = {
@@ -77,6 +108,8 @@ export type HomeRedirectInput = {
   userPanel: boolean;
   /** The portal has a pricing page, at this path. */
   pricingPath?: string;
+  /** The pages' own order (API-125), so `/` opens the first page in the sidebar's order. */
+  pageOrders?: PageOrders;
 };
 
 /**
@@ -96,7 +129,7 @@ export function homeRedirect(
   if (input.hostsDocs) {
     if (input.docRoutes.some((route) => route === "/" || route === "/index"))
       return undefined;
-    const landing = pickLandingRoute(input.docRoutes);
+    const landing = pickLandingRoute(input.docRoutes, input.pageOrders);
     if (landing) return { from: "/", to: landing };
     return input.apiReferencePath
       ? { from: "/", to: input.apiReferencePath }

package/src/config/v2/page-order.ts

@@ -0,0 +1,73 @@
+/**
+ * The order of docs pages (API-125). A page may set it (`order: 2` in the frontmatter of a Markdown page,
+ * `export const order = 2` in a React page). Pages with an order come first, by that number; the others follow, the
+ * usual first pages (introduction, getting started, ...) before the rest, then by name. A folder's index page is
+ * always its first page. Before this the order was by name only, so "Changelog" came first and the header's
+ * "Documentation" link opened it.
+ */
+export type PageOrders = ReadonlyMap<string, number>;
+
+/** Names that usually open a set of docs, best first. */
+const FIRST_PAGE_NAMES = [
+  "introduction",
+  "intro",
+  "welcome",
+  "getting-started",
+  "get-started",
+  "overview",
+  "quickstart",
+  "quick-start",
+];
+
+const lastSegment = (route: string) =>
+  route.split("/").filter(Boolean).pop() ?? "";
+
+const rank = (route: string, orders: PageOrders) => {
+  const name = lastSegment(route).toLowerCase();
+  if (name === "index" || route === "/") return [0, 0] as const;
+  const order = orders.get(route);
+  if (order !== undefined) return [1, order] as const;
+  const preferred = FIRST_PAGE_NAMES.indexOf(name);
+  return [2, preferred === -1 ? FIRST_PAGE_NAMES.length : preferred] as const;
+};
+
+/** Sorts sibling pages: index, then by `order`, then the usual first pages, then by name. */
+export function comparePages(
+  a: string,
+  b: string,
+  orders: PageOrders = new Map(),
+): number {
+  const [groupA, valueA] = rank(a, orders);
+  const [groupB, valueB] = rank(b, orders);
+  return groupA - groupB || valueA - valueB || a.localeCompare(b);
+}
+
+/** The page a visitor lands on: the top-most page, then the first in page order. */
+export function firstPage(
+  routes: readonly string[],
+  orders: PageOrders = new Map(),
+): string | undefined {
+  const depth = (route: string) => route.split("/").length;
+  return [...routes].sort(
+    (a, b) => depth(a) - depth(b) || comparePages(a, b, orders),
+  )[0];
+}
+
+/** `order: 3` (or `order: "3"`) from a page's frontmatter; undefined when it is missing or not a whole number. */
+export function orderValue(value: unknown): number | undefined {
+  const number =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim() !== ""
+        ? Number(value)
+        : Number.NaN;
+  return Number.isInteger(number) ? number : undefined;
+}
+
+const TSX_ORDER = /export\s+const\s+order\s*(?::\s*number\s*)?=\s*(-?\d+)/;
+
+/** `export const order = 3` in a React page. */
+export function tsxPageOrder(source: string): number | undefined {
+  const match = TSX_ORDER.exec(source);
+  return match?.[1] ? Number(match[1]) : undefined;
+}

package/src/config/v2/services.ts

@@ -686,6 +686,11 @@ async function buildGateway(
       : {}),
     ...(quota ? { quota: { calls: quota[0], periodDays: quota[1] } } : {}),
     ...(o.cors?.length ? { cors: o.cors } : {}),
+    // The sample server's health check needs no key: monitors and the platform call it, and it is not something a
+    // plan sells, so it stays out of the plans' feature lists (API-126).
+    ...(sampleServer
+      ? { operations: { public: [`GET ${FULL_SERVER_HEALTH_PATH}`] } }
+      : {}),
   };
 
   return {

package/src/config/v2/tsx-pages.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { glob } from "glob";
 import globParent from "glob-parent";
 import { folderLabel } from "./docs-navigation.js";
+import { tsxPageOrder } from "./page-order.js";
 import { toGlobPath } from "./resolve.js";
 
 /**
@@ -18,6 +19,8 @@ export type TsxPage = {
   file: string;
   /** Sidebar label: `export const title = "..."` in the file, or the file name. */
   label: string;
+  /** `export const order = 2` in the file (API-125). */
+  order?: number;
 };
 
 const IGNORED = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
@@ -90,7 +93,13 @@ export async function findTsxPages(
       const route = `/${relative.replace(/\.tsx$/, "")}`;
       if (found.has(route)) continue;
       const source = await readFile(file, "utf8").catch(() => "");
-      found.set(route, { route, file, label: tsxPageLabel(source, file) });
+      const order = tsxPageOrder(source);
+      found.set(route, {
+        route,
+        file,
+        label: tsxPageLabel(source, file),
+        ...(order !== undefined ? { order } : {}),
+      });
     }
   }
   return [...found.values()].sort((a, b) => a.route.localeCompare(b.route));

package/src/config/v2/wrapper.ts

@@ -10,6 +10,7 @@ import {
   docRoutes,
   type HomeRedirect,
   homeRedirect,
+  docPageOrders,
   pickLandingRoute,
 } from "./home-redirect.js";
 import {
@@ -677,13 +678,20 @@ export async function preparePortal(
   const hostedDocRoutes = [
     ...new Set([...markdownRoutes, ...tsxPages.map((page) => page.route)]),
   ].sort();
+  // The pages' own order (API-125): the sidebar, `/` and the "Documentation" link follow it.
+  const pageOrders = plan.docs
+    ? await docPageOrders(profile.docs.content)
+    : new Map<string, number>();
+  for (const page of tsxPages)
+    if (page.order !== undefined && !pageOrders.has(page.route))
+      pageOrders.set(page.route, page.order);
   // 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);
+      : pickLandingRoute(hostedDocRoutes, pageOrders);
     if (landing)
       plan.plansPlugin.links = { ...plan.plansPlugin.links, docs: landing };
   }
@@ -702,6 +710,7 @@ export async function preparePortal(
           plan.plansPlugin && hasCapability(effective.services.plans, "catalog")
             ? CONSOLE_ROUTES.pricing
             : undefined,
+        pageOrders,
       });
   const siteConfig = buildSiteConfig(
     resolved,
@@ -716,8 +725,9 @@ export async function preparePortal(
           label: page.label,
           element: wrapperPages[index]?.id ?? "",
         })),
+        pageOrders,
       ),
-      docsPath: pickLandingRoute(hostedDocRoutes),
+      docsPath: pickLandingRoute(hostedDocRoutes, pageOrders),
       demoPlans:
         plan.demo && plan.plansPlugin
           ? await readDemoPlans(resolved.plans?.file)

package/src/lib/authentication/providers/dev-portal-auth-pages.tsx

@@ -358,6 +358,19 @@ export function DevPortalRegisterPage({
       .finally(() => setConfigLoading(false));
   }, [baseUrl]);
 
+  // With one sign-in provider and no native sign-up, the button was a needless extra step: the page goes to the
+  // provider at once, and the button stays as a fallback (API-126).
+  const onlyProvider =
+    config && !isNativeAuthEnabled(config) && config.providers.length === 1
+      ? config.providers[0]
+      : undefined;
+  useEffect(() => {
+    if (!baseUrl || !onlyProvider) return;
+    window.location.assign(
+      buildDevPortalOidcChallengeUrl(baseUrl, onlyProvider.id, returnUrl),
+    );
+  }, [baseUrl, onlyProvider, returnUrl]);
+
   const onSubmit = useCallback(
     async (event: React.FormEvent) => {
       event.preventDefault();
@@ -408,7 +421,11 @@ export function DevPortalRegisterPage({
     return (
       <AuthPageShell
         title="Create your account"
-        description="Accounts are created on our secure sign-in provider."
+        description={
+          onlyProvider
+            ? "Opening the sign-up form…"
+            : "Accounts are created on our secure sign-in provider."
+        }
       >
         {config.providers.length ? (
           <OidcProviderButtons

package/src/lib/components/SiteTitle.tsx

@@ -1,58 +1,69 @@
-import { cn } from "../util/cn.js";
-
-type SiteTitleProps = {
-  title: string;
-  className?: string;
-};
-
-export const splitBrandWordmark = (title: string) => {
-  const trimmed = title.trim();
-  if (!trimmed) {
-    return { prefix: title, accent: null as string | null };
-  }
-
-  const words = trimmed.split(/\s+/).filter(Boolean);
-  if (words.length >= 2) {
-    return {
-      prefix: words.slice(0, -1).join(" "),
-      accent: words.at(-1) ?? null,
-    };
-  }
-
-  const word = words[0] ?? trimmed;
-  const apiMatch = word.match(/^(.*)(API)$/i);
-  if (apiMatch?.[1]) {
-    return { prefix: apiMatch[1], accent: apiMatch[2] ?? "API" };
-  }
-
-  const camelMatch = word.match(/^(.*[a-z])([A-Z][a-z]*)$/);
-  if (camelMatch?.[1]) {
-    return { prefix: camelMatch[1], accent: camelMatch[2] ?? null };
-  }
-
-  if (word.length < 2) {
-    return { prefix: word, accent: null };
-  }
-
-  const splitAt = Math.floor(word.length / 2);
-  return { prefix: word.slice(0, splitAt), accent: word.slice(splitAt) };
-};
-
-export const SiteTitle = ({ title, className }: SiteTitleProps) => {
-  const { prefix, accent } = splitBrandWordmark(title);
-
-  return (
-    <span
-      className={cn(
-        "font-sans text-[1.4rem] font-extrabold tracking-[-0.03em]",
-        className,
-      )}
-      style={{ color: "var(--foreground)" }}
-    >
-      {prefix}
-      {accent ? (
-        <span style={{ color: "var(--primary)" }}>{accent}</span>
-      ) : null}
-    </span>
-  );
-};
+import { cn } from "../util/cn.js";
+
+type SiteTitleProps = {
+  title: string;
+  className?: string;
+};
+
+export const splitBrandWordmark = (title: string) => {
+  const trimmed = title.trim();
+  if (!trimmed) {
+    return { prefix: title, accent: null as string | null, spaced: false };
+  }
+
+  // A name of several words keeps its space before the accent: "full portal", not "fullportal" (API-126).
+  const words = trimmed.split(/\s+/).filter(Boolean);
+  if (words.length >= 2) {
+    return {
+      prefix: words.slice(0, -1).join(" "),
+      accent: words.at(-1) ?? null,
+      spaced: true,
+    };
+  }
+
+  const word = words[0] ?? trimmed;
+  const apiMatch = word.match(/^(.*)(API)$/i);
+  if (apiMatch?.[1]) {
+    return { prefix: apiMatch[1], accent: apiMatch[2] ?? "API", spaced: false };
+  }
+
+  const camelMatch = word.match(/^(.*[a-z])([A-Z][a-z]*)$/);
+  if (camelMatch?.[1]) {
+    return {
+      prefix: camelMatch[1],
+      accent: camelMatch[2] ?? null,
+      spaced: false,
+    };
+  }
+
+  if (word.length < 2) {
+    return { prefix: word, accent: null, spaced: false };
+  }
+
+  const splitAt = Math.floor(word.length / 2);
+  return {
+    prefix: word.slice(0, splitAt),
+    accent: word.slice(splitAt),
+    spaced: false,
+  };
+};
+
+export const SiteTitle = ({ title, className }: SiteTitleProps) => {
+  const { prefix, accent, spaced } = splitBrandWordmark(title);
+
+  return (
+    <span
+      className={cn(
+        "font-sans text-[1.4rem] font-extrabold tracking-[-0.03em]",
+        className,
+      )}
+      style={{ color: "var(--foreground)" }}
+    >
+      {prefix}
+      {accent && spaced ? " " : null}
+      {accent ? (
+        <span style={{ color: "var(--primary)" }}>{accent}</span>
+      ) : null}
+    </span>
+  );
+};