@lukoweb/apitogo 0.1.148 → 0.2.1

package/src/config/v2/workspace.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { access, lstat, readFile, rm, symlink } from "node:fs/promises";
+import path from "node:path";
+import { glob } from "glob";
+import { ensureStateDir } from "./layout.js";
+import type { ResolvedConfigV2 } from "./resolve.js";
+import { CONTENT_LINK, type PreparedPortal } from "./wrapper.js";
+
+const exists = (file: string) =>
+  access(file).then(
+    () => true,
+    () => false,
+  );
+
+async function relink(target: string, link: string): Promise<void> {
+  if (
+    await lstat(link).then(
+      () => true,
+      () => false,
+    )
+  )
+    await rm(link, { recursive: true, force: true });
+  await symlink(target, link, "dir");
+}
+
+/**
+ * Makes `generated/` a self-contained site root the existing build can run in: the wrapper, an empty site
+ * config, and links to the tenant's files. Tenant files are linked, never copied, edited or patched.
+ */
+export async function materializeWorkspace(
+  resolved: ResolvedConfigV2,
+  prepared: Pick<PreparedPortal, "wrapperPath">,
+): Promise<string> {
+  const root = path.dirname(prepared.wrapperPath);
+  await ensureStateDir(resolved.state);
+  await relink(resolved.configDir, path.join(root, CONTENT_LINK));
+  const publicDir = resolved.portal && path.join(resolved.portal.dir, "public");
+  const publicLink = path.join(root, "public");
+  if (publicDir && (await exists(publicDir))) {
+    await relink(publicDir, publicLink);
+  } else {
+    await rm(publicLink, { recursive: true, force: true });
+  }
+  return root;
+}
+
+/**
+ * The config as the build sees it. `project.id` links the folder to a platform project and never changes what is
+ * built, so writing it (deploy does, once) must not count as a change.
+ */
+async function configFingerprint(configPath: string): Promise<string> {
+  const text = await readFile(configPath, "utf8");
+  try {
+    const raw = JSON.parse(text) as { project?: { id?: unknown } };
+    if (raw.project) {
+      delete raw.project.id;
+      if (Object.keys(raw.project).length === 0) delete raw.project;
+    }
+    return JSON.stringify(raw);
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Hash of everything that decides the build output: config, docs content, specs, theme, assets, the manifest
+ * (without its timestamp), the generated wrapper and the CLI version. Equal hashes mean the previous build is still valid.
+ */
+export async function portalArtifactHash(
+  resolved: ResolvedConfigV2,
+  manifestText: string | undefined,
+  cliVersion: string,
+  wrapper = "",
+): Promise<string> {
+  const portal = resolved.portal;
+  const patterns = [
+    ...(portal?.docs.content ?? []),
+    ...(resolved.gateway?.specs ?? []),
+    ...(portal
+      ? [portal.theme, path.join(portal.dir, "public", "**", "*")]
+      : []),
+  ];
+  const positive = patterns.filter((p) => !p.startsWith("!"));
+  const ignore = patterns
+    .filter((p) => p.startsWith("!"))
+    .map((p) => p.slice(1));
+  const files = [
+    ...new Set(
+      (
+        await Promise.all(
+          positive.map((pattern) =>
+            glob(pattern.split(path.sep).join("/"), {
+              absolute: true,
+              nodir: true,
+              ignore: [...ignore, "**/node_modules/**"],
+            }),
+          ),
+        )
+      ).flat(),
+    ),
+  ].sort();
+
+  const hash = createHash("sha256");
+  hash.update(`cli:${cliVersion}\n`);
+  hash.update(await configFingerprint(resolved.configPath));
+  hash.update(`wrapper:${wrapper}\n`);
+  if (manifestText !== undefined) {
+    const manifest = JSON.parse(manifestText) as Record<string, unknown>;
+    delete manifest.generatedAt;
+    hash.update(`manifest:${JSON.stringify(manifest)}\n`);
+  }
+  for (const file of files) {
+    hash.update(`file:${path.relative(resolved.configDir, file)}\n`);
+    hash.update(await readFile(file));
+  }
+  return hash.digest("hex");
+}

package/src/config/v2/wrapper.ts

@@ -0,0 +1,397 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { ConfigError, type ConfigIssue } from "./errors.js";
+import {
+  hasCapability,
+  missingManifestServices,
+  type ServiceManifest,
+  serviceReady,
+  stubManifest,
+} from "./manifest.js";
+import { type PortalProfile, portalProfile } from "./portal-profile.js";
+import type { ResolvedConfigV2 } from "./resolve.js";
+
+export const WRAPPER_FILE = "apitogo.config.tsx";
+
+/** Name of the link, inside `generated/`, that points at the tenant's config directory. */
+export const CONTENT_LINK = "content";
+
+/**
+ * Turns an absolute docs glob into one the site root understands. The build globs relative to its root, so
+ * tenant content is reached through the `content` link and never copied.
+ */
+export function contentGlob(configDir: string, glob: string): string {
+  const negated = glob.startsWith("!");
+  const absolute = negated ? glob.slice(1) : glob;
+  const relative = path.relative(configDir, absolute).split(path.sep).join("/");
+  return `${negated ? "!" : ""}/${CONTENT_LINK}/${relative}`;
+}
+
+/** Capabilities of the plans service that put something on the console. Any one of them registers the plans plugin. */
+const PLANS_CONSOLE_CAPABILITIES = [
+  "catalog",
+  "checkout",
+  "subscriptions",
+  "keys",
+  "usage",
+] as const;
+
+/**
+ * What the generated wrapper registers, and why each piece is in or out. Every `false` was decided from the
+ * profile and the manifest, so a build without billing or sign-in contains no billing or sign-in code.
+ */
+export type PortalPlan = {
+  /** Docs pages, navigation and search APItoGo builds. */
+  docs: boolean;
+  /** OpenAPI reference pages and playground. */
+  apiReference: boolean;
+  /** OpenID sign-in against the identity issuer. */
+  auth?: {
+    issuer: string;
+    clientId: string;
+    scopes: string[];
+    audience?: string;
+  };
+  /** Pricing, subscriptions, API keys and usage pages. */
+  plansPlugin?: { apiBaseUrl: string; keysApiBaseUrl?: string };
+  /** Account pages. */
+  userPanel: boolean;
+  /** Public sign-up page; only when identity declares `nativeSignup`. */
+  signup: boolean;
+  /** Console pieces that were left out and the reason, for `apitogo plan` and for tests. */
+  skipped: { piece: string; reason: string }[];
+  /** True only for a stub manifest. Production builds refuse it. */
+  preview: boolean;
+};
+
+/** npm packages the generated site needs, beyond `@lukoweb/apitogo`, for what the plan registers. */
+export function requiredPackages(plan: PortalPlan): string[] {
+  return [
+    ...(plan.plansPlugin ? ["@lukoweb/apitogo-plugin-dev-portal-billing"] : []),
+    ...(plan.userPanel ? ["@lukoweb/apitogo-module-user-panel"] : []),
+  ];
+}
+
+/** Console routes the portal serves, by link name. */
+const CONSOLE_ROUTES = {
+  signup: "/signup",
+  login: "/login",
+  pricing: "/pricing",
+  keys: "/account/credentials",
+  usage: "/account/usage",
+} as const;
+
+/**
+ * Links to the console pages this build really serves, for an external docs site to point at. A link appears
+ * only when the page exists (its capability is on) and the portal URL is known; the portal never guesses a URL.
+ */
+export function consoleLinks(
+  manifest: ServiceManifest,
+  plan: PortalPlan,
+): Record<string, string> {
+  const base = manifest.services.portal?.url?.replace(/\/+$/, "");
+  if (!base || !plan.auth) return {};
+  const { plans } = manifest.services;
+  const present: Record<keyof typeof CONSOLE_ROUTES, boolean> = {
+    signup: plan.signup,
+    login: true,
+    pricing: !!plan.plansPlugin && hasCapability(plans, "catalog"),
+    keys: !!plan.plansPlugin && hasCapability(plans, "keys"),
+    usage: !!plan.plansPlugin && hasCapability(plans, "usage"),
+  };
+  return Object.fromEntries(
+    Object.entries(CONSOLE_ROUTES)
+      .filter(([name]) => present[name as keyof typeof CONSOLE_ROUTES])
+      .map(([name, route]) => [name, `${base}${route}`]),
+  );
+}
+
+/**
+ * The `services.json` shipped at the site root: the deployed manifest plus console links the manifest did not
+ * declare itself. Public values only. A stub manifest is never shipped.
+ */
+export function publishedManifest(
+  manifest: ServiceManifest,
+  plan: PortalPlan,
+): ServiceManifest | undefined {
+  if (manifest.preview) return undefined;
+  const links = {
+    ...consoleLinks(manifest, plan),
+    ...manifest.services.portal?.console?.links,
+  };
+  // Nothing to offer an external docs site: ship no manifest, so recording a URL never changes the build.
+  if (Object.keys(links).length === 0) return undefined;
+  const portal = manifest.services.portal ?? {};
+  return {
+    ...manifest,
+    services: {
+      ...manifest.services,
+      portal: { ...portal, console: { ...portal.console, links } },
+    },
+  };
+}
+
+const DEFAULT_SCOPES = ["openid", "profile", "email"];
+
+/**
+ * Pure: decides which plugins and modules the portal registers. A service contributes only when it has a manifest
+ * entry, is ready and declares the capability that the piece needs.
+ */
+export function planPortal(
+  profile: PortalProfile,
+  manifest: ServiceManifest,
+): PortalPlan {
+  const skipped: PortalPlan["skipped"] = [];
+  const skip = (piece: string, reason: string) =>
+    void skipped.push({ piece, reason });
+  const { identity, plans } = manifest.services;
+
+  const plan: PortalPlan = {
+    docs: profile.modules.docs,
+    apiReference: profile.pipelines.openapi,
+    userPanel: false,
+    signup: false,
+    skipped,
+    preview: manifest.preview === true,
+  };
+
+  if (!profile.enabled) return plan;
+
+  if (!profile.console.enabled) {
+    skip("console", "portal.console.enabled is false");
+    return plan;
+  }
+
+  if (!identity) {
+    skip("sign-in", "services.json has no identity entry");
+  } else if (!serviceReady(identity)) {
+    skip("sign-in", `identity is ${identity.status}, not ready`);
+  } else if (!identity.issuer || !identity.clientId) {
+    skip("sign-in", "identity entry has no issuer or clientId");
+  } else {
+    plan.auth = {
+      issuer: identity.issuer,
+      clientId: identity.clientId,
+      scopes: identity.scopes ?? DEFAULT_SCOPES,
+      audience: identity.audience,
+    };
+    plan.userPanel = true;
+    plan.signup = hasCapability(identity, "nativeSignup");
+    if (!plan.signup) skip("sign-up", "identity.nativeSignup is false");
+  }
+
+  if (!plans) {
+    skip("plans", "services.json has no plans entry");
+  } else if (!serviceReady(plans)) {
+    skip("plans", `plans is ${plans.status}, not ready`);
+  } else if (!plans.apiBaseUrl) {
+    skip("plans", "plans entry has no apiBaseUrl");
+  } else if (
+    !PLANS_CONSOLE_CAPABILITIES.some((name) => hasCapability(plans, name))
+  ) {
+    skip("plans", "plans declares none of the console capabilities");
+  } else if (!plan.auth) {
+    skip("plans", "plans pages need sign-in, which is not available");
+  } else {
+    plan.plansPlugin = {
+      apiBaseUrl: plans.apiBaseUrl,
+      keysApiBaseUrl: plans.keysApiBaseUrl,
+    };
+  }
+
+  return plan;
+}
+
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+
+/** Name of the site config the wrapper imports, next to it in `generated/`. */
+export const SITE_CONFIG_FILE = "apitogo.config.json";
+
+/**
+ * The site settings (title, modules, docs globs, theme, sign-in) in the shape the existing build reads from
+ * `apitogo.config.json`. It is generated, never edited, and lives in `generated/`.
+ */
+export function buildSiteConfig(
+  resolved: ResolvedConfigV2,
+  plan: PortalPlan,
+  theme?: unknown,
+): Record<string, unknown> {
+  const portal = resolved.portal;
+  return {
+    site: {
+      title: portal?.name ?? resolved.project.name,
+      ...(plan.preview
+        ? { banner: { message: PREVIEW_BANNER_MESSAGE, color: "caution" } }
+        : {}),
+    },
+    modules: {
+      docs: { enabled: plan.docs },
+      userPanel: { enabled: plan.userPanel },
+    },
+    ...(plan.docs
+      ? {
+          docs: {
+            files: portal?.docs.content.map((glob) =>
+              contentGlob(resolved.configDir, glob),
+            ),
+          },
+        }
+      : {}),
+    ...(theme !== undefined ? { theme } : {}),
+    ...(plan.auth ? { authentication: { type: "openid", ...plan.auth } } : {}),
+    ...(plan.preview ? { preview: true } : {}),
+  };
+}
+
+/** 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.";
+
+/** The wrapper source. Imports exist only for what the plan registers. */
+export function renderWrapper(plan: PortalPlan): string {
+  const imports = [
+    'import { buildApitogoConfig } from "@lukoweb/apitogo/build-config";',
+    ...(plan.plansPlugin
+      ? [
+          'import { devPortalBillingPlugin } from "@lukoweb/apitogo-plugin-dev-portal-billing";',
+        ]
+      : []),
+    `import siteConfig from "./${SITE_CONFIG_FILE}";`,
+  ];
+  const plugins = plan.plansPlugin
+    ? `[devPortalBillingPlugin(${JSON.stringify(plan.plansPlugin)})]`
+    : "[]";
+
+  return [
+    "// Generated by apitogo from apitogo.config.json and services.json. Do not edit: it is rewritten on every build.",
+    ...(plan.preview
+      ? [
+          "// PREVIEW: built from a stand-in manifest for local runs. A production build refuses this file.",
+        ]
+      : []),
+    ...imports,
+    "",
+    "export default buildApitogoConfig({",
+    "  ...siteConfig,",
+    `  plugins: ${plugins},`,
+    "});",
+    "",
+  ].join("\n");
+}
+
+/** 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;
+  if (!file) return undefined;
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export type PrepareMode = "development" | "production";
+
+export type PreparedPortal = {
+  profile: PortalProfile;
+  plan: PortalPlan;
+  wrapper: string;
+  /** Contents of the generated site config the wrapper imports. */
+  siteConfig: Record<string, unknown>;
+  /** The manifest to ship at the site root, when there is a deployed one. */
+  publishedManifest?: ServiceManifest;
+  /** Absolute path the wrapper was written to, under the state directory's `generated/`. */
+  wrapperPath: string;
+  /** Where the manifest came from: the deployed file, a stand-in for local runs, or not needed. */
+  manifestSource: "file" | "preview-stub" | "none";
+};
+
+/**
+ * `portal.prepare`: picks the manifest, plans the registrations and writes the wrapper into `generated/`.
+ *
+ * - A deployed manifest is always used when present.
+ * - Without one, a local run (`development`) falls back to a labelled stub; a `production` build fails with
+ *   PORTAL_MANIFEST_MISSING when the portal depends on a service, and needs no manifest when it does not.
+ * - A stub manifest is never accepted in `production`.
+ *
+ * With `write: false` nothing is written, so `plan` can ask what a build would do without changing anything.
+ */
+export async function preparePortal(
+  resolved: ResolvedConfigV2,
+  manifest: ServiceManifest | undefined,
+  mode: PrepareMode,
+  options: { write?: boolean } = {},
+): Promise<PreparedPortal> {
+  const profile = portalProfile(resolved);
+  const issues: ConfigIssue[] = [];
+  let effective: ServiceManifest;
+  let manifestSource: PreparedPortal["manifestSource"];
+
+  if (manifest?.preview === true && mode === "production") {
+    throw new ConfigError(resolved.configPath, [
+      {
+        code: "PORTAL_MANIFEST_PREVIEW",
+        path: "services.json",
+        message:
+          "services.json is a preview stub and cannot be used in a production build.",
+        hint: "Run `apitogo deploy` to write a real services.json.",
+      },
+    ]);
+  }
+
+  if (manifest) {
+    effective = manifest;
+    manifestSource = "file";
+    if (mode === "production") {
+      issues.push(...missingManifestServices(resolved, manifest));
+    }
+  } else if (mode === "development") {
+    effective = stubManifest(resolved);
+    manifestSource = "preview-stub";
+  } else {
+    const missing = missingManifestServices(resolved, undefined);
+    issues.push(...missing);
+    effective = stubManifest(resolved);
+    manifestSource = missing.length === 0 ? "none" : "file";
+  }
+
+  if (issues.length > 0) throw new ConfigError(resolved.configPath, issues);
+
+  // An empty manifest is what production uses when nothing is required.
+  if (manifestSource === "none") {
+    effective = { ...effective, preview: undefined, services: {} };
+  }
+
+  const plan = planPortal(profile, effective);
+  const siteConfig = buildSiteConfig(resolved, plan, await readTheme(resolved));
+  const wrapper = renderWrapper(plan);
+  const wrapperPath = path.join(resolved.state.generatedDir, WRAPPER_FILE);
+  if (options.write !== false) {
+    await mkdir(path.dirname(wrapperPath), { recursive: true });
+    await writeFile(
+      path.join(path.dirname(wrapperPath), SITE_CONFIG_FILE),
+      `${JSON.stringify(siteConfig, null, 2)}\n`,
+    );
+    const temporary = `${wrapperPath}.${process.pid}.tmp`;
+    try {
+      await writeFile(temporary, wrapper, "utf8");
+      await rename(temporary, wrapperPath);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+  return {
+    profile,
+    plan,
+    wrapper,
+    siteConfig,
+    // Without a console there are no console links to offer, so a docs-only portal ships no manifest.
+    publishedManifest:
+      manifestSource === "file" && profile.console.enabled
+        ? publishedManifest(effective, plan)
+        : undefined,
+    wrapperPath,
+    manifestSource,
+  };
+}

package/src/vite/html.ts

@@ -12,7 +12,6 @@ export function getDevHtml({
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
     <!--app-helmet-->
-    <link rel="preconnect" href="https://cdn.zudoku.dev/">
   </head>
   <body>
     <div id="root"><!--app-html--></div>
@@ -44,7 +43,6 @@ export function getBuildHtml({
     <script type="module" crossorigin src="${jsEntry}"></script>
 ${cssLinks}
     <!--app-helmet-->
-    <link rel="preconnect" href="https://cdn.zudoku.dev/">
   </head>
   <body>
     <div id="root"><!--app-html--></div>

package/src/vite/plugin-theme.ts

@@ -125,12 +125,27 @@ const processFontConfig = (fontConfig?: FontConfig) => {
   };
 };
 
+/**
+ * The default fonts ship inside the portal (Latin subset, four weights) so a first paint makes no third-party
+ * request. Fonts a tenant picks by name still load from Google Fonts: that is their explicit choice.
+ */
+const bundledFont = (pkg: string) => {
+  // Absolute paths: the CSS is compiled from the site root, which does not see this package's dependencies.
+  const dir = path.dirname(
+    createRequire(import.meta.url).resolve(`@fontsource/${pkg}/package.json`),
+  );
+  return [400, 500, 600, 700].map((weight) =>
+    path.join(dir, `latin-${weight}.css`).split(path.sep).join("/"),
+  );
+};
+
 const DEFAULT_FONT_SANS = '"IBM Plex Sans", system-ui, sans-serif';
 const DEFAULT_FONT_MONO = '"JetBrains Mono", monospace';
 const DEFAULT_FONT_HEADING = '"Space Grotesk", system-ui, sans-serif';
 
 const processFonts = async (themeConfig: ZudokuConfig["theme"]) => {
   const imports: string[] = [];
+  const bundled: string[] = [];
   const families = {
     sans: DEFAULT_FONT_SANS,
     serif: undefined as string | undefined,
@@ -193,14 +208,14 @@ const processFonts = async (themeConfig: ZudokuConfig["theme"]) => {
 
   // Add default font imports if no user or registry fonts
   if (!userFonts.sans.fontFamily && !registryFonts.sans) {
-    imports.push(getGoogleFontUrl("IBM Plex Sans"));
+    bundled.push(...bundledFont("ibm-plex-sans"));
   }
   if (!userFonts.mono.fontFamily && !registryFonts.mono) {
-    imports.push(getGoogleFontUrl("JetBrains Mono"));
+    bundled.push(...bundledFont("jetbrains-mono"));
   }
-  imports.push(getGoogleFontUrl("Space Grotesk"));
+  bundled.push(...bundledFont("space-grotesk"));
 
-  return { imports, families };
+  return { imports, bundled, families };
 };
 
 const MODULE_SOURCE_PACKAGES = [
@@ -268,9 +283,10 @@ export const viteThemePlugin = (): Plugin => {
       const fonts = await processFonts(themeConfig);
 
       // Add all font imports at once
-      if (fonts.imports.length > 0) {
-        themeCss.push(...fonts.imports.map((url) => `@import url('${url}');`));
-      }
+      themeCss.push(
+        ...fonts.bundled.map((specifier) => `@import '${specifier}';`),
+        ...fonts.imports.map((url) => `@import url('${url}');`),
+      );
 
       // Handle registry theme variables
       if (themeConfig.registryUrl) {

package/src/app/font.geist.css

@@ -1,73 +0,0 @@
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 100;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Thin.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 200;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-UltraLight.woff2")
-    format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 300;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Light.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 400;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Regular.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 500;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Medium.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 600;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-SemiBold.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 700;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Bold.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 800;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-Black.woff2") format("woff2");
-}
-
-@font-face {
-  font-family: Geist;
-  font-style: normal;
-  font-weight: 900;
-  font-display: swap;
-  src: url("https://cdn.zudoku.dev/geist/Geist-UltraBlack.woff2")
-    format("woff2");
-}