create-ailk 0.22.0 → 0.24.0

package/templates/apps/api/src/routes/content/get-page.ts

@@ -28,50 +28,36 @@
  * composed from the deployment's `_site.mdx` identity (identity node, optional
  * secondary, WebSite) rather than the page title. Every other type's body is
  * the page's own JSON-LD, spread at the root, as before.
+ *
+ * #7169: the document is built by `readContentDocument` in
+ * `@working-theory/content-adapters` — the shared seam the `read_content` MCP
+ * tool answers through, parsing the same `@working-theory/validation` exports —
+ * over the `_site.mdx` this route still reads (the package may not import
+ * `@working-theory/site-config`).
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import {
-  SCHEMA_ORG_TYPES,
+  readContentDocument,
   type ContentAdapter,
-  type ContentPage,
   type MdxContentAdapter,
-  type MdxPageSource,
-  type SchemaOrgType,
 } from "@working-theory/content-adapters";
-import {
-  buildJsonLd,
-  composeGraph,
-  graphNodes,
-  type ContentPageInput,
-  type JsonLdObject,
-  type SitewideIdentityInput,
-} from "@working-theory/schema";
 import {
   SiteConfigSchema,
   type SiteConfig,
 } from "@working-theory/site-config/schema";
+import {
+  contentPageParamsSchema,
+  contentPageQuerySchema,
+} from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
 import { parse as parseYaml } from "yaml";
-import { z } from "zod";
 
 import { getContentRoot } from "../../lib/content-adapter.js";
 import { resolveLocale } from "../../lib/locales.js";
 import { resolvePublicContentAdapter } from "../../services/public-site-resolver.js";
 
-import { SLUG_PATTERN } from "./slug.js";
-
-const paramsSchema = z.object({
-  type: z.enum(SCHEMA_ORG_TYPES),
-  slug: z.string().regex(SLUG_PATTERN),
-});
-
-const querySchema = z.object({
-  locale: z.string().optional(),
-  include: z.enum(["body"]).optional(),
-});
-
 /**
  * The raw-body capability, probed by the exact name the MDX adapter declares
  * and the database adapter borrows (#5874) — the same idiom, and the same
@@ -114,38 +100,6 @@ function readSiteConfig(contentRoot: string): SiteConfig | undefined {
   return siteConfigByRoot.get(contentRoot) ?? undefined;
 }
 
-/**
- * The `HomePage` body's `@graph` (#6597, spec D11): the spine plus the site's
- * sitewide identity nodes. The WebSite's `inLanguage` is the spine's own, so
- * both carry one value; the Organization falls back to the page's `image` as
- * its `logo` when the identity declares none, as the title-derived node did.
- */
-function homePageGraph(
-  primary: JsonLdObject,
-  image: string | undefined,
-): { "@context": "https://schema.org"; "@graph": JsonLdObject[] } {
-  const config = readSiteConfig(getContentRoot());
-  let site: SitewideIdentityInput | undefined;
-  if (config !== undefined) {
-    const identity = config.siteIdentity;
-    site = {
-      origin: config.baseUrl.replace(/\/+$/, ""),
-      siteName: config.siteName,
-      baseUrl: config.baseUrl,
-      inLanguage:
-        typeof primary["inLanguage"] === "string" ? primary["inLanguage"] : undefined,
-      identity:
-        identity.kind !== "Person" && identity.logo === undefined && image !== undefined
-          ? { ...identity, logo: image }
-          : identity,
-    };
-  }
-  return {
-    "@context": "https://schema.org",
-    "@graph": graphNodes(composeGraph({ primary, site, isHomePage: true })),
-  };
-}
-
 export const getPageRoute: FastifyPluginAsync = async (fastify) => {
   fastify.get<{
     Params: { type: string; slug: string };
@@ -153,7 +107,7 @@ export const getPageRoute: FastifyPluginAsync = async (fastify) => {
   }>(
     "/v1/content/:type/:slug",
     async (request, reply) => {
-      const parsed = paramsSchema.safeParse(request.params);
+      const parsed = contentPageParamsSchema.safeParse(request.params);
       if (!parsed.success) {
         return reply.status(400).send({
           error: "Invalid type or slug",
@@ -161,7 +115,7 @@ export const getPageRoute: FastifyPluginAsync = async (fastify) => {
         });
       }
 
-      const queryParsed = querySchema.safeParse(request.query);
+      const queryParsed = contentPageQuerySchema.safeParse(request.query);
       if (!queryParsed.success) {
         return reply.status(400).send({
           error: "Invalid query parameters",
@@ -191,74 +145,35 @@ export const getPageRoute: FastifyPluginAsync = async (fastify) => {
         // Refused before any content query, so a caller asking for a body this
         // deployment cannot serve is never charged a read whose result is then
         // discarded.
-        let readSource: MdxContentAdapter["getPageSource"] | undefined;
-        if (include === "body") {
-          if (!hasPageSource(adapter)) {
-            return reply.status(400).send({
-              error: "Invalid query parameters",
-              details: [
-                {
-                  path: ["include"],
-                  message: "body is not available from this content adapter",
-                },
-              ],
-            });
-          }
-          readSource = adapter.getPageSource.bind(adapter);
+        if (include === "body" && !hasPageSource(adapter)) {
+          return reply.status(400).send({
+            error: "Invalid query parameters",
+            details: [
+              {
+                path: ["include"],
+                message: "body is not available from this content adapter",
+              },
+            ],
+          });
         }
 
-        // #5927: ONE adapter call supplies everything the response sends.
-        // `readSource` (bound above, only when `include=body`) returns BOTH
-        // the frontmatter and the body from the SAME read, so the two halves
-        // can never straddle a publish that lands between two independent
-        // calls. Without the parameter, `getPageBySlug` is the only call, as
-        // it always was. `source` stays `undefined` on that path — the
-        // `source && {...}` below never attaches a body to the response.
-        let source: MdxPageSource | null | undefined;
-        let page: ContentPage | null;
-        if (readSource) {
-          source = await readSource(type as SchemaOrgType, slug, locale);
-          page = source === null ? null : source.frontmatter;
-        } else {
-          page = await adapter.getPageBySlug(type as SchemaOrgType, slug, locale);
-        }
-        if (!page) {
+        // #5927: ONE adapter call supplies everything the response sends —
+        // the builder reads `getPageSource` only when `include=body`, and
+        // `getPageBySlug` alone otherwise, so the two halves can never
+        // straddle a publish that lands between two independent calls.
+        const document = await readContentDocument(
+          adapter,
+          { type, slug, locale, include },
+          readSiteConfig(getContentRoot()),
+        );
+        if (!document) {
           return reply.status(404).send({
             error: "Page not found",
             type,
             slug,
           });
         }
-
-        // #8746 — the site's origin, from `_site.mdx`'s `baseUrl`, for a
-        // builder that needs an absolute URL (JobPosting's ApplyAction).
-        const origin = readSiteConfig(getContentRoot())?.baseUrl.replace(/\/+$/, "");
-        const input: ContentPageInput = {
-          type: page.type,
-          slug: page.slug,
-          title: page.title,
-          description: page.description,
-          ...(origin !== undefined && { origin }),
-          ...(page.publishedAt !== undefined && {
-            publishedAt: page.publishedAt,
-          }),
-          ...(page.updatedAt !== undefined && { updatedAt: page.updatedAt }),
-          ...(page.image !== undefined && { image: page.image }),
-          ...(page.schema !== undefined && { schema: page.schema }),
-          // ADR-0026: carry the page's typed sections so recipes compose entity
-          // JSON-LD from real section data (e.g. FAQPage.mainEntity from `faq`
-          // sections) rather than a hand-rolled `schema` override. The adapter
-          // now preserves `sections`; before, it was stripped at validation.
-          ...(page.sections !== undefined && { sections: page.sections }),
-        };
-        const primary = buildJsonLd(input);
-        const jsonLd =
-          page.type === "HomePage" ? homePageGraph(primary, page.image) : primary;
-        return reply.send({
-          ...jsonLd,
-          page,
-          ...(source && { body: source.body }),
-        });
+        return reply.send(document);
       } catch (error) {
         request.log.error({ err: error }, "[Content] getPage failed");
         return reply.status(500).send({ error: "Internal server error" });

package/templates/apps/api/src/routes/content/index.ts

@@ -1,9 +1,16 @@
 /**
  * Public content API.
  *
- * Read endpoints, all GET, all JSON-LD-shaped at the document root:
+ * Read endpoints, all GET, JSON-LD-shaped at the document root unless noted:
  *   GET /v1/content/types          — supported page types
  *   GET /v1/content/search         — keyword search (#5831)
+ *   GET /v1/content/offerings      — Services + Products (#7177); answers the
+ *                                    `{ ok, data }` envelope, not JSON-LD
+ *   GET /v1/content/pricing        — pricing tiers (#7178); answers the
+ *                                    `{ ok, data }` envelope, not JSON-LD
+ *   GET /v1/content/shown-offerings — the /pricing page's Offerings read
+ *                                    (#8924); answers the { ok, data }
+ *                                    envelope, not JSON-LD
  *   GET /v1/content/:type          — paginated list of pages
  *   GET /v1/content/:type/:slug    — single page with resolved JSON-LD
  *
@@ -24,12 +31,19 @@ import type { FastifyPluginAsync } from "fastify";
 import { getPageRoute } from "./get-page.js";
 import { listPagesRoute } from "./list-pages.js";
 import { listTypesRoute } from "./list-types.js";
+import { offeringsRoute } from "./offerings.js";
+import { pricingRoute } from "./pricing.js";
 import { searchContentRoute } from "./search.js";
+import { shownOfferingsRoute } from "./shown-offerings.js";
 
 export const contentRoutes: FastifyPluginAsync = async (fastify) => {
   await fastify.register(listTypesRoute);
-  // Before `listPagesRoute`: `search` must never be read as a `:type`.
+  // Before `listPagesRoute`: `search`, `offerings`, `pricing` and
+  // `shown-offerings` must never be read as a `:type`.
   await fastify.register(searchContentRoute);
+  await fastify.register(offeringsRoute);
+  await fastify.register(pricingRoute);
+  await fastify.register(shownOfferingsRoute);
   await fastify.register(listPagesRoute);
   await fastify.register(getPageRoute);
 };

package/templates/apps/api/src/routes/content/list-pages.ts

@@ -5,43 +5,32 @@
  * pageSize 20; pageSize is capped at 100 to keep response payloads bounded.
  *
  * Response envelope is an `ItemList` JSON-LD document carrying the page
- * frontmatter under `items` and pagination metadata alongside. A deployment
- * whose site cannot be resolved (#5852) answers 404, not an empty list.
+ * frontmatter under `items` and pagination metadata alongside, built by
+ * `listPagesItemList` in `@working-theory/content-adapters` — the shared seam
+ * the `list_pages` MCP tool answers through, parsing the same
+ * `@working-theory/validation` exports (#7168). A deployment whose site
+ * cannot be resolved (#5852) answers 404, not an empty list.
  *
  * Phase 3 S3: optional `?locale=<locale>` query parameter. Validated against
  * `readLocales()` allowlist; invalid or unknown locale silently falls back to
  * the project's default locale (AC-i18n-07).
  */
-import { SCHEMA_ORG_TYPES, type SchemaOrgType } from "@working-theory/content-adapters";
+import { listPagesItemList } from "@working-theory/content-adapters";
+import {
+  contentListParamsSchema,
+  contentListQuerySchema,
+} from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
-import { z } from "zod";
 
 import { resolveLocale } from "../../lib/locales.js";
 import { resolvePublicContentAdapter } from "../../services/public-site-resolver.js";
 
-const paramsSchema = z.object({
-  type: z.enum(SCHEMA_ORG_TYPES),
-});
-
-const PAGE_SIZE_MAX = 100;
-
-const querySchema = z.object({
-  page: z.coerce.number().int().min(1).default(1),
-  pageSize: z.coerce
-    .number()
-    .int()
-    .min(1)
-    .default(20)
-    .transform((v) => Math.min(v, PAGE_SIZE_MAX)),
-  locale: z.string().optional(),
-});
-
 export const listPagesRoute: FastifyPluginAsync = async (fastify) => {
   fastify.get<{
     Params: { type: string };
     Querystring: { page?: string; pageSize?: string; locale?: string };
   }>("/v1/content/:type", async (request, reply) => {
-    const params = paramsSchema.safeParse(request.params);
+    const params = contentListParamsSchema.safeParse(request.params);
     if (!params.success) {
       return reply.status(400).send({
         error: "Invalid type",
@@ -49,7 +38,7 @@ export const listPagesRoute: FastifyPluginAsync = async (fastify) => {
       });
     }
 
-    const query = querySchema.safeParse(request.query);
+    const query = contentListQuerySchema.safeParse(request.query);
     if (!query.success) {
       return reply.status(400).send({
         error: "Invalid query parameters",
@@ -74,19 +63,9 @@ export const listPagesRoute: FastifyPluginAsync = async (fastify) => {
         });
       }
 
-      const all = await adapter.listPages(type as SchemaOrgType, locale);
-      const totalItems = all.length;
-      const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
-      const start = (page - 1) * pageSize;
-      const items = all.slice(start, start + pageSize);
-
-      return reply.send({
-        "@context": "https://schema.org",
-        "@type": "ItemList",
-        type,
-        items,
-        pagination: { page, pageSize, totalItems, totalPages },
-      });
+      return reply.send(
+        await listPagesItemList(adapter, { type, page, pageSize, locale }),
+      );
     } catch (error) {
       request.log.error({ err: error }, "[Content] listPages failed");
       return reply.status(500).send({ error: "Internal server error" });

package/templates/apps/api/src/routes/content/offerings.ts

@@ -0,0 +1,184 @@
+/**
+ * GET /v1/content/offerings
+ *
+ * The site's Services and Products as one offerings list (#7177). The HTTP
+ * twin of the `get_offerings` MCP tool: same arguments, parsed with the same
+ * `@working-theory/validation` schema, and the same result, produced by the
+ * same function — `listOfferings` in `@working-theory/content-adapters`, the
+ * shared seam the tool also answers through. That is the API ↔ MCP parity
+ * contract in the root CLAUDE.md; the parity guard's `get_offerings` row is a
+ * `twin` naming this route.
+ *
+ * Query:
+ *   type    optional — `service` or `product`; omit for both
+ *   locale  optional — BCP-47 (`xx` or `xx-XX`). A well-formed tag outside the
+ *           project's allowlist silently falls back to the default locale
+ *           (AC-i18n-07), matching every other content read; a malformed one
+ *           is a 400, as the tool refuses it.
+ *
+ * Success: `{ ok: true, data: { offerings } }` — the API's documented
+ * envelope, not the JSON-LD `ItemList` the older content routes answer.
+ * Refusals: `400 validation_failed` (issues are not echoed), `404 not_found`
+ * when no public site resolves, `500 internal_error`.
+ *
+ * Registered BEFORE `/v1/content/:type` in `index.ts`. Fastify's radix router
+ * prefers a static segment over a parametric one regardless of order — the
+ * ordering is belt-and-braces, as it is for search.
+ *
+ * Rate limiting is inherited: `server.ts` registers the limiter GLOBALLY with
+ * the content ceiling, so this route is covered without one of its own.
+ *
+ * Which site this read serves is resolved BEFORE any content query (#5852)
+ * through the same `resolvePublicContentAdapter(request)` seam the sibling
+ * content reads use. The resolver reads `x-ailk-spoke-key`, so every answer
+ * past the query parse appends that header to `Vary`: a cache keyed on the
+ * URL alone must never share one site's answer — or one bad key's 404 — with
+ * another (SEC-7177-C). It appends rather than sets, because `@fastify/cors`
+ * has already written `Vary: Origin`.
+ *
+ * Offerings (#8933, spec D4): on a connected workspace with a current shown
+ * set, every read but `type=service` answers the Service pages followed by
+ * that set's Products — in place of the Product pages, since Stripe is that
+ * site's price authority — through `readShownOfferings` (#8924's read, the
+ * one code path every agent surface shares) and `listOfferingsWithShownSet`
+ * in `@working-theory/content-adapters`, the mapping the tool answers through
+ * too. Each shown Product carries `prices`: every price with its interval and
+ * full lookup key. `type=service`, and every workspace with no connection, no
+ * claim or no current set, answers page content exactly as before; a failed
+ * shown-set read takes the content path too. The read refreshes, or not,
+ * exactly as the shown-offerings route does (`options`, D5): never with the
+ * owner's override, never per request (T7).
+ *
+ * Anonymous and identity-blind: no `Authorization`, cookie, session or user
+ * id is read.
+ */
+import {
+  currentShownSet,
+  listOfferings,
+  listOfferingsWithShownSet,
+  type ContentAdapter,
+  type ListOfferingsOptions,
+} from "@working-theory/content-adapters";
+import {
+  getOfferingsInputSchema,
+  type GetOfferingsOutput,
+} from "@working-theory/validation";
+import type {
+  FastifyPluginAsync,
+  FastifyReply,
+  FastifyRequest,
+} from "fastify";
+
+import { resolveLocale } from "../../lib/locales.js";
+import { resolvePublicContentAdapter } from "../../services/public-site-resolver.js";
+
+import {
+  readShownOfferings,
+  type ShownOfferingsRouteOptions,
+} from "./shown-offerings.js";
+
+/** The request header the resolver picks the site's workspace from. */
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
+
+/** Adds the spoke-key header to `Vary`, keeping every value already there. */
+function varyOnSpokeKey(reply: FastifyReply): void {
+  const existing = reply.getHeader("vary");
+  const values = (
+    Array.isArray(existing) ? existing.join(",") : String(existing ?? "")
+  )
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value !== "");
+  if (!values.some((value) => value.toLowerCase() === SPOKE_KEY_HEADER)) {
+    values.push(SPOKE_KEY_HEADER);
+  }
+  reply.header("Vary", values.join(", "));
+}
+
+/** An error's class name only — never its message, which may carry Stripe text. */
+function errName(err: unknown): string {
+  return err instanceof Error ? err.constructor.name : typeof err;
+}
+
+/**
+ * The page Services followed by the connected workspace's shown Products, or
+ * `null` for the content path (#8933 D4). A failed read or mapping is one
+ * fixed `warn` line and the content path, never a 500 and never an `{ err }`
+ * line.
+ */
+async function shownSetOfferings(
+  request: FastifyRequest,
+  options: ShownOfferingsRouteOptions,
+  adapter: ContentAdapter,
+  listOptions: ListOfferingsOptions,
+): Promise<GetOfferingsOutput | null> {
+  try {
+    const shownSet = currentShownSet(
+      await readShownOfferings(request, options),
+    );
+    return shownSet === null
+      ? null
+      : await listOfferingsWithShownSet(adapter, listOptions, shownSet);
+  } catch (err) {
+    request.log.warn(
+      { outcome: "shown_set_failed", errName: errName(err) },
+      "[Content] offerings: shown set unavailable, answering page content",
+    );
+    return null;
+  }
+}
+
+export const offeringsRoute: FastifyPluginAsync<
+  ShownOfferingsRouteOptions
+> = async (fastify, options) => {
+  fastify.get<{
+    Querystring: { type?: string; locale?: string };
+  }>("/v1/content/offerings", async (request, reply) => {
+    const query = getOfferingsInputSchema.safeParse(request.query);
+    if (!query.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: {
+          code: "validation_failed",
+          message: "Invalid query parameters",
+        },
+      });
+    }
+
+    const locale = resolveLocale(query.data.locale);
+    // Every answer from here on depends on the spoke key — the 404 and 500
+    // included — so each carries the Vary.
+    varyOnSpokeKey(reply);
+
+    try {
+      const adapter = await resolvePublicContentAdapter(request);
+      if (adapter === null) {
+        return reply.status(404).send({
+          ok: false,
+          error: { code: "not_found", message: "Page not found" },
+        });
+      }
+
+      if (query.data.type !== "service") {
+        const shown = await shownSetOfferings(request, options, adapter, {
+          type: query.data.type,
+          locale,
+        });
+        if (shown !== null) return reply.send({ ok: true, data: shown });
+      }
+
+      const data = await listOfferings(adapter, {
+        type: query.data.type,
+        locale,
+      });
+
+      return reply.send({ ok: true, data });
+    } catch (error) {
+      request.log.error({ err: error }, "[Content] listOfferings failed");
+      return reply.status(500).send({
+        ok: false,
+        error: { code: "internal_error", message: "Internal server error" },
+      });
+    }
+  });
+};