create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/openapi/spec.ts

@@ -7,104 +7,544 @@
  *
  * When this surface grows beyond a handful of routes, swap in a generator
  * and delete this file; the route handlers don't depend on the spec shape.
+ *
+ * Hand-authored does NOT mean self-described: this file is byte-synced into
+ * every consuming site, so the site's own name and the deployment's own API
+ * origin are resolved at serve time (#5306, #5307) rather than written in as
+ * literals. Everything a literal can correctly say about every deployment —
+ * route shapes, schemas — stays a literal.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import { logger } from "@working-theory/observability";
+import { parse as parseYaml } from "yaml";
+
+import { config } from "../config/index.js";
+import { isModuleEnabled } from "../config/modules.js";
+import { getContentRoot } from "../lib/content-adapter.js";
 
+import { toOpenApiPath, type RegisteredRoute } from "./surface-drift.js";
+
+/**
+ * The version of the PUBLIC API CONTRACT — the `/v1` route prefix this spec
+ * documents — and deliberately not the version of any npm package (#5307
+ * AC-4). The `@working-theory/*` packages move on their own 0.x line and are
+ * released per-change; the contract an agent codes against moves only when a
+ * route's shape does. Syncing this to a package version would make every
+ * package release look like an API change to a caller that pins on it.
+ *
+ * Bump the major only alongside a new `/vN` prefix.
+ */
 export const API_VERSION = "1.0.0";
 
-export function buildOpenApiSpec() {
+/** Name used when the site's own identity cannot be resolved (#5307 AC-3). */
+const NEUTRAL_DISPLAY_NAME = "Content API";
+
+/** Spec title used when the site's own name cannot be resolved (#5307 AC-3). */
+const NEUTRAL_SPEC_TITLE = "Public Content API";
+
+/** Root-index description used when `_site.mdx` carries none. */
+const NEUTRAL_DESCRIPTION = "Local auth + session backend + public content API";
+
+/**
+ * How this deployment describes itself — resolved from the site's own config
+ * and this deployment's own env, never from a literal naming the kit.
+ */
+export interface ApiIdentity {
+  /** `siteName` from `_site.mdx`. Absent when the file is missing/unreadable. */
+  siteName?: string;
+  /** `siteIdentity.description` from `_site.mdx`, when present. */
+  siteDescription?: string;
+  /**
+   * The public origin this API is reachable at, from `AILK_PUBLIC_API_URL`.
+   *
+   * NOT `_site.mdx`'s `baseUrl` (#5306 AC-3). `baseUrl` is the SITE origin;
+   * the API is deployed on a different host — `samhenry.org` serves the site
+   * and `api.samhenry.org` serves this API. Pointing `servers` at `baseUrl`
+   * would look right in review, pass every test that does not deploy, and
+   * send agents to the site's web origin instead of its API. The two are
+   * separate facts and only the deployment knows the second one.
+   */
+  publicApiUrl?: string;
+}
+
+let cachedIdentity: ApiIdentity | undefined;
+
+/**
+ * Resolve this deployment's identity, reading `_site.mdx` once per process.
+ *
+ * Deliberately synchronous, and deliberately a local frontmatter read rather
+ * than `@working-theory/site-config`'s async `loadSiteConfig`: the spec is
+ * built inside a sync route handler, and only two scalar fields are needed.
+ * This mirrors `lib/locales.ts`, which reads `project.yaml` the same way and
+ * for the same boundary reason.
+ *
+ * Every failure path degrades to the neutral default (#5307 AC-3) — a missing
+ * or malformed `_site.mdx` must never take the API down, and must never fall
+ * back to the kit's name.
+ */
+export function resolveApiIdentity(): ApiIdentity {
+  if (!cachedIdentity) cachedIdentity = readApiIdentity();
+  return cachedIdentity;
+}
+
+/** Test/utility helper — drop the cached identity so the next call re-reads. */
+export function resetApiIdentity(): void {
+  cachedIdentity = undefined;
+}
+
+function readApiIdentity(): ApiIdentity {
+  const identity: ApiIdentity = {};
+
+  const publicApiUrl = normaliseOrigin(config.AILK_PUBLIC_API_URL);
+  if (publicApiUrl) identity.publicApiUrl = publicApiUrl;
+
+  const frontmatter = readSiteFrontmatter();
+  const siteName = frontmatter?.["siteName"];
+  if (typeof siteName === "string" && siteName.trim()) {
+    identity.siteName = siteName.trim();
+  }
+
+  const siteIdentity = frontmatter?.["siteIdentity"];
+  const description =
+    siteIdentity && typeof siteIdentity === "object"
+      ? (siteIdentity as Record<string, unknown>)["description"]
+      : undefined;
+  if (typeof description === "string" && description.trim()) {
+    identity.siteDescription = description.trim();
+  }
+
+  if (!identity.siteName) {
+    logger.warn(
+      { neutralName: NEUTRAL_DISPLAY_NAME },
+      "No readable siteName in _site.mdx — the API will describe itself with a neutral default",
+    );
+  }
+
+  return identity;
+}
+
+/** Read and parse `_site.mdx` frontmatter, or `undefined` on any failure. */
+function readSiteFrontmatter(): Record<string, unknown> | undefined {
+  const path = join(getContentRoot(), "_site.mdx");
+  if (!existsSync(path)) return undefined;
+
+  try {
+    const raw = readFileSync(path, "utf8");
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+    if (!match?.[1]) return undefined;
+
+    const parsed: unknown = parseYaml(match[1]);
+    return parsed && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Accept an absolute http(s) origin and strip a trailing slash. Anything else
+ * resolves to `undefined` so the caller degrades to a document-relative
+ * server rather than publishing a malformed absolute URL (#5306 AC-2).
+ */
+function normaliseOrigin(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      logger.warn(
+        { AILK_PUBLIC_API_URL: trimmed },
+        "AILK_PUBLIC_API_URL is not an http(s) URL — the OpenAPI servers block will fall back to a document-relative origin",
+      );
+      return undefined;
+    }
+    return trimmed.replace(/\/+$/, "");
+  } catch {
+    logger.warn(
+      { AILK_PUBLIC_API_URL: trimmed },
+      "AILK_PUBLIC_API_URL is not a parseable URL — the OpenAPI servers block will fall back to a document-relative origin",
+    );
+    return undefined;
+  }
+}
+
+/** The name this API introduces itself by on the root index. */
+export function apiDisplayName(identity: ApiIdentity): string {
+  return identity.siteName ? `${identity.siteName} API` : NEUTRAL_DISPLAY_NAME;
+}
+
+/** The description this API introduces itself by on the root index. */
+export function apiDescription(identity: ApiIdentity): string {
+  return identity.siteDescription ?? NEUTRAL_DESCRIPTION;
+}
+
+/**
+ * Resolve the `servers` block.
+ *
+ * With an origin configured, one entry naming this deployment. Without one,
+ * a single document-relative entry: per OpenAPI 3.1 a `/` server resolves
+ * against the origin the document was served from, so an agent that fetched
+ * this spec from `https://api.example.com/v1/openapi.json` still reaches the
+ * right host. That makes absence a correct-by-construction degradation rather
+ * than a silently wrong URL (#5306 AC-2), and the entry's own description
+ * names the unset variable so the reason travels with the served document.
+ */
+function resolveServers(
+  publicApiUrl: string | undefined,
+): Array<{ url: string; description: string }> {
+  const origin = normaliseOrigin(publicApiUrl);
+  if (origin) {
+    return [{ url: origin, description: "This deployment" }];
+  }
+  return [
+    {
+      url: "/",
+      description:
+        "This deployment — relative to the origin that served this document " +
+        "(AILK_PUBLIC_API_URL is unset)",
+    },
+  ];
+}
+
+/**
+ * The route table a built server registered (#5314).
+ *
+ * Carried on the Fastify instance (`server.decorate`) and threaded into the
+ * two surfaces as an argument — deliberately NOT module-level state. A
+ * module-level array is shared by every server built in one process, and
+ * `apps/api/src/vercel-handler.ts`'s `getServer()` is a check-then-set: it
+ * tests `!serverInstance`, then awaits twice before assigning, so two
+ * concurrent invocations can both call `build()`. With shared state, one
+ * build's reset would land mid-fill of the other and leave a truncated or
+ * doubled table — the surfaces would then silently misreport, which is the
+ * exact failure this card exists to remove. Per-instance state makes that
+ * unreachable whether or not the race fires.
+ *
+ * Registration is CONDITIONAL — `isModuleEnabled()` gates paid-module routes
+ * and `shouldMountTestAuth()` gates the test-auth route — so this is what THIS
+ * deployment serves, not a catalogue of what the build could serve (spec D1).
+ * A route absent because its module is off is absent from both surfaces too,
+ * which is why a disabled slice never reads as drift.
+ */
+
+/** The decorator key both surfaces read the route table from. */
+export const REGISTERED_ROUTES_DECORATOR = "registeredRoutes";
+
+/**
+ * Read the route table off a Fastify instance (or anything carrying the
+ * decorator), returning `[]` when it is absent.
+ *
+ * Empty is a supported state, not a bug: `buildOpenApiSpec()` is called
+ * directly by unit tests with no server in play, and this file is byte-synced
+ * into every consuming site. `paths` degrades to its hand-authored entries
+ * rather than publishing an empty document.
+ */
+export function readRegisteredRoutes(source: unknown): RegisteredRoute[] {
+  const routes = (source as Record<string, unknown> | null | undefined)?.[
+    REGISTERED_ROUTES_DECORATOR
+  ];
+  return Array.isArray(routes) ? (routes as RegisteredRoute[]) : [];
+}
+
+/**
+ * Root-index keys this API has already published, by Fastify path (#5314 D6).
+ *
+ * Deriving the root index without this overlay would rename all eleven keys a
+ * consumer may already read, which ADR-0020 counts as a breaking change and
+ * would owe a `/v2`. With it, every published key keeps its name and only new
+ * keys appear, so the change is purely additive.
+ *
+ * `billing` and `billingPortalSession` become CONDITIONAL rather than
+ * disappearing: they are emitted exactly when their routes register, which is
+ * the fix for a root index that advertised both on a build where neither
+ * registers and both 404.
+ */
+const CURATED_ROOT_INDEX_KEYS: Record<string, string> = {
+  "/health": "health",
+  "/v1/openapi.json": "openapi",
+  "/v1/auth/tokens": "tokens",
+  "/v1/user/profile": "profile",
+  "/v1/user/data/:key": "userData",
+  "/v1/content/types": "contentTypes",
+  "/v1/content/:type": "contentList",
+  "/v1/content/:type/:slug": "contentPage",
+  "/v1/checkout/sessions": "checkoutSessions",
+  "/v1/billing": "billing",
+  "/v1/billing/portal-session": "billingPortalSession",
+};
+
+/**
+ * Canonical method order for a root-index value, so `GET/POST /v1/x` is
+ * stable across runs rather than following registration order.
+ */
+const METHOD_ORDER = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+
+function byCanonicalMethod(a: string, b: string): number {
+  const ai = METHOD_ORDER.indexOf(a);
+  const bi = METHOD_ORDER.indexOf(b);
+  return (
+    (ai === -1 ? METHOD_ORDER.length : ai) -
+      (bi === -1 ? METHOD_ORDER.length : bi) || a.localeCompare(b)
+  );
+}
+
+/**
+ * A deterministic root-index key for a path with no curated name:
+ * `/v1/project-listings/public` becomes `projectListingsPublic`, and a
+ * `:param` segment contributes its bare name.
+ */
+function generatedRootIndexKey(path: string): string {
+  const segments = path
+    .replace(/^\/v1\//, "/")
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => segment.replace(/^:/, ""));
+  if (segments.length === 0) return "root";
+
+  return segments
+    .map((segment, index) => {
+      const camel = segment
+        .replace(/[^a-zA-Z0-9]+(.)/g, (_m, c: string) => c.toUpperCase())
+        .replace(/[^a-zA-Z0-9]/g, "");
+      return index === 0
+        ? camel.charAt(0).toLowerCase() + camel.slice(1)
+        : camel.charAt(0).toUpperCase() + camel.slice(1);
+    })
+    .join("");
+}
+
+/**
+ * The root index `endpoints` object, derived from the routes this process
+ * registered (#5314 AC-1).
+ *
+ * One entry per PATH, valued `"METHOD[/METHOD...] /path"` — the shape this
+ * surface has always published (`"GET/PATCH /v1/user/profile"`). The SHAPE is
+ * preserved, not every value: `tokens` goes from `"POST/GET/DELETE
+ * /v1/auth/tokens"` to `"GET/POST /v1/auth/tokens"`, because `DELETE` was
+ * never served at that path (it is `/v1/auth/tokens/:id`, now its own entry).
+ * Key NAMES are preserved outright, which is what keeps this additive under
+ * ADR-0020; the value corrections are the drift being fixed. Curated keys win; everything else gets a
+ * generated one, de-duplicated by suffix so two paths can never collapse onto
+ * one key and silently hide a route.
+ *
+ * An empty route table yields an empty object rather than a stale literal: the
+ * only caller is the `GET /` handler on a built server, whose own route is in
+ * the table by request time, so an empty result would mean the hook had failed
+ * and is better surfaced than papered over.
+ */
+export function deriveRootEndpoints(
+  routes: RegisteredRoute[],
+): Record<string, string> {
+  const methodsByPath = new Map<string, string[]>();
+  for (const { method, url } of routes) {
+    const methods = methodsByPath.get(url) ?? [];
+    if (!methods.includes(method)) methods.push(method);
+    methodsByPath.set(url, methods);
+  }
+
+  const endpoints: Record<string, string> = {};
+  const used = new Set<string>();
+  for (const [path, methods] of methodsByPath) {
+    const base = CURATED_ROOT_INDEX_KEYS[path] ?? generatedRootIndexKey(path);
+    let key = base;
+    for (let n = 2; used.has(key); n += 1) key = `${base}${n}`;
+    used.add(key);
+    endpoints[key] =
+      `${[...methods].sort(byCanonicalMethod).join("/")} ${path}`;
+  }
+  return endpoints;
+}
+
+/** An OpenAPI `operationId` for a route with no hand-authored operation. */
+function derivedOperationId(method: string, path: string): string {
+  const suffix = generatedRootIndexKey(path);
+  return `${method.toLowerCase()}${suffix.charAt(0).toUpperCase()}${suffix.slice(1)}`;
+}
+
+/**
+ * The minimal OpenAPI 3.1 operation a route table can honestly produce.
+ *
+ * No route in this app carries a Fastify `schema` — validation is Zod inside
+ * the handler — so the route table knows a route's method and path and
+ * nothing else (#5314 D2). Inventing a request or response schema here would
+ * be worse than omitting one: an agent codes against what the document says.
+ */
+function derivedOperation(method: string, fastifyPath: string) {
+  const parameters = fastifyPath
+    .split("/")
+    .filter((segment) => segment.startsWith(":"))
+    .map((segment) => ({
+      name: segment.slice(1),
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    }));
+
+  return {
+    operationId: derivedOperationId(method, fastifyPath),
+    summary: `${method.toUpperCase()} ${toOpenApiPath(fastifyPath)}`,
+    description:
+      "Derived from this deployment's route table (#5314). Request and " +
+      "response shapes are not described: this route carries no schema the " +
+      "route table can read.",
+    ...(parameters.length > 0 && { parameters }),
+    responses: { "200": { description: "OK" } },
+  };
+}
+
+/**
+ * `paths` = every registered route, overlaid with the hand-authored operations.
+ *
+ * The derived half makes the endpoint SET complete and correct by construction
+ * (#5314 AC-1/AC-4); the overlay keeps every hand-authored schema, example and
+ * description exactly as written (#5314 D2). Hand-authored wins per method, and
+ * path-level keys on a hand-authored item are preserved.
+ *
+ * With an EMPTY registry the hand-authored object is returned untouched. That
+ * is the byte-sync degradation floor (#5314 FR7): `buildOpenApiSpec()` is
+ * called directly by unit tests with no server in play, and a consuming site
+ * that somehow builds no route table still serves the seven documented paths
+ * rather than an empty document.
+ */
+function mergeDerivedPaths(
+  routes: RegisteredRoute[],
+  handAuthored: Record<string, Record<string, unknown>>,
+): Record<string, Record<string, unknown>> {
+  if (routes.length === 0) return handAuthored;
+
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const { method, url } of routes) {
+    const path = toOpenApiPath(url);
+    paths[path] = {
+      ...paths[path],
+      [method.toLowerCase()]: derivedOperation(method, url),
+    };
+  }
+
+  for (const [path, item] of Object.entries(handAuthored)) {
+    paths[path] = { ...paths[path], ...item };
+  }
+  return paths;
+}
+
+export function buildOpenApiSpec(
+  identity: ApiIdentity = resolveApiIdentity(),
+  registeredRoutes: RegisteredRoute[] = [],
+) {
   const typeEnum = [...SCHEMA_ORG_TYPES];
 
   return {
     openapi: "3.1.0",
     info: {
-      title: "AI Launch Kit — Public Content API",
+      title: identity.siteName
+        ? `${identity.siteName} — ${NEUTRAL_SPEC_TITLE}`
+        : NEUTRAL_SPEC_TITLE,
       version: API_VERSION,
       description:
-        "HTTP API exposing AILK content as schema.org JSON-LD, plus a small set " +
-        "of anonymous write routes (lead capture, checkout). Designed for agent " +
-        "consumption (AX) — every content response carries `@context` and " +
-        "`@type` at the document root.",
-      license: { name: "MIT" },
+        "HTTP API exposing this site's content as schema.org JSON-LD, plus a " +
+        "small set of anonymous write routes (lead capture, checkout). Designed " +
+        "for agent consumption (AX) — every content response carries `@context` " +
+        "and `@type` at the document root.",
+      // No `license`: this file is byte-synced into every consuming site, so a
+      // literal here would assert a licence over a deployment that never chose
+      // one (#5307 AC-2). OpenAPI 3.1 makes `info.license` optional; a site
+      // that wants to publish one declares it where its own licence lives.
     },
-    servers: [
-      { url: "http://localhost:3002", description: "Local development" },
-      { url: "https://api.ailaunchkit.ai", description: "Production" },
-    ],
-    paths: {
-      "/v1/checkout/sessions": {
-        post: {
-          operationId: "createCheckoutSession",
-          summary: "Create a Stripe hosted-page checkout session",
-          description:
-            "Resolves a productCode to a Stripe price via lookup_key and creates a " +
-            "hosted-page checkout session. Returns the session ID and redirect URL. " +
-            "Sandbox-only: live Stripe keys are rejected at runtime.",
-          requestBody: {
-            required: true,
-            content: {
-              "application/json": {
-                schema: {
-                  $ref: "#/components/schemas/CheckoutSessionRequest",
-                },
-              },
-            },
-          },
-          responses: {
-            "201": {
-              description: "Checkout session created",
+    servers: resolveServers(identity.publicApiUrl),
+    paths: mergeDerivedPaths(registeredRoutes, {
+      // Module-conditional (commerce, D-47 / #5364) — mirroring the CONDITIONAL
+      // treatment `CURATED_ROOT_INDEX_KEYS`'s doc comment above already
+      // describes for `billing`/`billingPortalSession`. Those two have no
+      // hand-authored `paths` entry here at all (mergeDerivedPaths's DERIVED
+      // half is what publishes them, so they only ever appear when actually
+      // registered); `/v1/checkout/sessions` is the one hand-authored entry
+      // in this object, and mergeDerivedPaths always merges hand-authored
+      // paths in regardless of registration — so without this gate, a build
+      // with commerce off still advertises the operation while `registeredRoutes`
+      // has no matching entry, which is exactly the orphaned-surface drift
+      // surface-drift.test.ts exists to catch (#5314).
+      ...(isModuleEnabled("commerce") && {
+        "/v1/checkout/sessions": {
+          post: {
+            operationId: "createCheckoutSession",
+            summary: "Create a Stripe hosted-page checkout session",
+            description:
+              "Resolves a productCode to a Stripe price via lookup_key and creates a " +
+              "hosted-page checkout session. Returns the session ID and redirect URL. " +
+              "Sandbox-only: live Stripe keys are rejected at runtime.",
+            requestBody: {
+              required: true,
               content: {
                 "application/json": {
                   schema: {
-                    $ref: "#/components/schemas/CheckoutSessionResponse",
+                    $ref: "#/components/schemas/CheckoutSessionRequest",
                   },
                 },
               },
             },
-            "400": {
-              description: "Validation error — invalid request body",
-              content: {
-                "application/json": {
-                  schema: { $ref: "#/components/schemas/ValidationErrorResponse" },
+            responses: {
+              "201": {
+                description: "Checkout session created",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/CheckoutSessionResponse",
+                    },
+                  },
                 },
               },
-            },
-            "404": {
-              description:
-                "Unknown product code — no active Stripe price for the given productCode",
-              content: {
-                "application/json": {
-                  schema: {
-                    $ref: "#/components/schemas/UnknownProductCodeResponse",
+              "400": {
+                description: "Validation error — invalid request body",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/ValidationErrorResponse",
+                    },
                   },
                 },
               },
-            },
-            "500": {
-              description:
-                "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
-              content: {
-                "application/json": {
-                  schema: {
-                    $ref: "#/components/schemas/LiveModeForbiddenResponse",
+              "404": {
+                description:
+                  "Unknown product code — no active Stripe price for the given productCode",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/UnknownProductCodeResponse",
+                    },
                   },
                 },
               },
-            },
-            "502": {
-              description:
-                "Checkout unavailable — Stripe returned an unexpected error",
-              content: {
-                "application/json": {
-                  schema: {
-                    $ref: "#/components/schemas/CheckoutUnavailableResponse",
+              "500": {
+                description:
+                  "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/LiveModeForbiddenResponse",
+                    },
+                  },
+                },
+              },
+              "502": {
+                description:
+                  "Checkout unavailable — Stripe returned an unexpected error",
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: "#/components/schemas/CheckoutUnavailableResponse",
+                    },
                   },
                 },
               },
             },
           },
         },
-      },
+      }),
       "/v1/leads/submit": {
         post: {
           operationId: "submitLead",
@@ -391,7 +831,7 @@ export function buildOpenApiSpec() {
           },
         },
       },
-    },
+    }),
     components: {
       schemas: {
         CheckoutSessionRequest: {