create-ailk 0.1.0

package/templates/apps/api/src/routes/content/__tests__/update.test.ts

@@ -0,0 +1,252 @@
+/**
+ * @file update.test.ts
+ * PATCH /api/content/:type/:slug — D14a Stage 1 Unit B.
+ *
+ * Covers: Pro-tier gating (402), missing If-Match (409), stale If-Match (409
+ * with current version echoed), validation (400), happy path (200 with
+ * {page, version}), not-found (404), unknown :type (400).
+ *
+ * Issue #398 follow-up: bespoke version-probe + getPageBySlug pre-check
+ * removed; the adapter throws `AdapterWriteError("not_found" | "conflict")`
+ * and the hoisted `mapAdapterError` translates it.
+ *
+ * Uses the real content adapter backed by a per-test temp dir (Issue #507).
+ * @working-theory/license stays mocked — it is an external package boundary.
+ */
+
+import type { FastifyInstance } from "fastify";
+
+const mockCheckLicense = jest.fn();
+
+// @working-theory/license is an external package boundary — stays mocked.
+jest.mock("@working-theory/license", () => ({
+  checkLicense: (...args: unknown[]) => mockCheckLicense(...args),
+}));
+
+import { AdapterWriteError } from "@working-theory/content-adapters";
+
+import { setupContentFixture } from "../../../__tests__/factories/content-fixture";
+import { contentRoutes } from "../index";
+
+const fixture = setupContentFixture();
+
+function proLicense() {
+  return {
+    tier: "pro",
+    plan: "pro",
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+function freeLicense() {
+  return {
+    tier: "free",
+    plan: null,
+    features: [],
+    expiresAt: null,
+    revoked: false,
+  };
+}
+
+// Update body must match the slug from the URL.
+const validBody = {
+  type: "HomePage",
+  slug: "home",
+  title: "Welcome (updated)",
+  description: "Updated description",
+  body: "Updated body content",
+};
+
+describe("PATCH /api/content/:type/:slug", () => {
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    app = require("fastify")();
+    await app.register(contentRoutes);
+    jest.clearAllMocks();
+    mockCheckLicense.mockReset();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  it("returns 200 with {page, version} on success", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // The fixture writes "home" in beforeEach; PATCH it with If-Match.
+    // First POST to get the version header, then PATCH.
+    // For simplicity: the real MDX adapter returns a version on create/update.
+    // We pass a version token that matches — the adapter uses content hash.
+    // Get current version first by creating it via POST:
+    const createRes = await app.inject({
+      method: "POST",
+      url: "/v1/content/HomePage",
+      payload: {
+        type: "HomePage",
+        slug: "update-target",
+        title: "Original",
+        description: "Original description",
+        body: "Original body",
+      },
+    });
+    expect(createRes.statusCode).toBe(201);
+    const { version } = JSON.parse(createRes.body);
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/update-target",
+      headers: { "if-match": version },
+      payload: {
+        type: "HomePage",
+        slug: "update-target",
+        title: "Welcome (updated)",
+        description: "Updated description",
+        body: "Updated body",
+      },
+    });
+
+    expect(res.statusCode).toBe(200);
+    const body = JSON.parse(res.body);
+    expect(body).toHaveProperty("page");
+    expect(body).toHaveProperty("version");
+    expect(body.page).toMatchObject({ type: "HomePage", slug: "update-target" });
+  });
+
+  it("returns 402 payment_required on free tier", async () => {
+    mockCheckLicense.mockResolvedValue(freeLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(402);
+  });
+
+  it("returns 402 payment_required when license is revoked even at pro tier", async () => {
+    mockCheckLicense.mockResolvedValue({
+      tier: "pro",
+      plan: "pro",
+      features: [],
+      expiresAt: null,
+      revoked: true,
+    });
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(402);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "payment_required" });
+  });
+
+  it("returns 409 conflict when If-Match header is missing", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "conflict" });
+  });
+
+  it("returns 409 conflict when If-Match is empty string", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "" },
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "conflict" });
+  });
+
+  it("returns 409 conflict with currentVersion echoed when adapter signals stale If-Match", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    // Pass a stale version — the real adapter will reject it with a conflict.
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "stale-version-that-does-not-match" },
+      payload: validBody,
+    });
+
+    // The real adapter rejects a stale If-Match with 409 + currentVersion.
+    expect(res.statusCode).toBe(409);
+    const body = JSON.parse(res.body);
+    expect(body).toMatchObject({ error: "conflict" });
+    // currentVersion is echoed in details when the adapter provides it.
+    if (body.details) {
+      expect(body.details).toHaveProperty("currentVersion");
+    }
+  });
+
+  it("returns 404 not_found when adapter signals page missing", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/slug-that-does-not-exist",
+      headers: { "if-match": "any-version" },
+      payload: { ...validBody, slug: "slug-that-does-not-exist" },
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "not_found" });
+  });
+
+  it("returns 400 validation_failed on bad body", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+      payload: { type: "HomePage", slug: "home" }, // missing required fields
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body)).toMatchObject({ error: "validation_failed" });
+  });
+
+  it("returns 400 validation_failed on unknown :type", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/Bogus/home",
+      headers: { "if-match": "v1" },
+      payload: validBody,
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("returns 400 when path :type/:slug does not match body type/slug", async () => {
+    mockCheckLicense.mockResolvedValue(proLicense());
+
+    const res = await app.inject({
+      method: "PATCH",
+      url: "/v1/content/HomePage/home",
+      headers: { "if-match": "v1" },
+      payload: { ...validBody, slug: "different-slug" },
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+});

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

@@ -0,0 +1,114 @@
+/**
+ * POST /v1/content/:type
+ *
+ * Creates a new page of `:type` from a JSON body matching `FrontmatterSchema`
+ * (from `@working-theory/content-adapters`, the SSOT for content shape) plus a non-empty
+ * `body` string. Paid-licensed deploys only — free tier returns 402 via the
+ * `requirePaidTier` preHandler from Stage 0.
+ *
+ * Conflict semantics: if a page with this slug already exists, returns 409
+ * with the existing page's `version` echoed in `details` so the caller can
+ * pivot to PATCH without a re-read. The conflict signal is delivered by the
+ * adapter via `AdapterWriteError("conflict", ..., { version })` and translated
+ * by the hoisted `mapAdapterError` (issue #398) — the route no longer
+ * pre-checks slug existence (closes the V2-H2 TOCTOU window between the
+ * read and the write).
+ *
+ * Errors all use the canonical `{error, message, details?}` shape from
+ * `apps/api/src/lib/errors.ts`.
+ */
+import {
+  FrontmatterSchema,
+  SCHEMA_ORG_TYPES,
+  type SchemaOrgType,
+} from "@working-theory/content-adapters";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { getContentAdapter } from "../../lib/content-adapter.js";
+import {
+  adapterErrorResponse,
+  validationError,
+  type ErrorBody,
+} from "../../lib/errors.js";
+import { requirePaidTier } from "../../lib/require-paid-tier.js";
+
+import { SLUG_PATTERN } from "./slug.js";
+
+const paramsSchema = z.object({
+  type: z.enum(SCHEMA_ORG_TYPES),
+});
+
+const writeBodySchema = FrontmatterSchema.extend({ body: z.string().min(1) });
+
+function send(reply: FastifyReply, status: number, body: ErrorBody) {
+  return reply.status(status).send(body);
+}
+
+export const createPageRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.post<{
+    Params: { type: string };
+    Body: unknown;
+  }>(
+    "/v1/content/:type",
+     
+    { preHandler: requirePaidTier },
+    async (request, reply) => {
+      const params = paramsSchema.safeParse(request.params);
+      if (!params.success) {
+        const err = validationError("Invalid type", {
+          issues: params.error.issues,
+        });
+        return send(reply, err.status, err.body);
+      }
+
+      const parsed = writeBodySchema.safeParse(request.body);
+      if (!parsed.success) {
+        const err = validationError("Invalid request body", {
+          issues: parsed.error.issues,
+        });
+        return send(reply, err.status, err.body);
+      }
+
+      const { body: pageBody, ...page } = parsed.data;
+
+      if (!SLUG_PATTERN.test(page.slug)) {
+        const err = validationError("Invalid request body", {
+          issues: [
+            {
+              path: ["slug"],
+              message:
+                "slug must match /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/ (lowercase, digits, hyphens; no leading/trailing hyphen)",
+            },
+          ],
+        });
+        return send(reply, err.status, err.body);
+      }
+
+      if (page.type !== params.data.type) {
+        const err = validationError(
+          "Body `type` must match URL :type parameter",
+          { urlType: params.data.type, bodyType: page.type },
+        );
+        return send(reply, err.status, err.body);
+      }
+
+      const { type } = params.data;
+
+      try {
+        const adapter = getContentAdapter();
+        const result = await adapter.createPage(
+          type as SchemaOrgType,
+          page.slug,
+          { ...page, body: pageBody },
+        );
+        return reply.status(201).send(result);
+      } catch (error) {
+        const err = adapterErrorResponse(error, { type, slug: page.slug });
+        if (err) return send(reply, err.status, err.body);
+        request.log.error({ err: error }, "[Content] createPage failed");
+        return reply.status(500).send({ error: "Internal server error" });
+      }
+    },
+  );
+};

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

@@ -0,0 +1,81 @@
+/**
+ * DELETE /v1/content/:type/:slug
+ *
+ * Removes the page of `:type` at `:slug`. Paid-licensed deploys only.
+ *
+ * Optimistic locking is mandatory: the request MUST carry an `If-Match`
+ * header containing the `version` token from a prior read. Missing/empty →
+ * 409. Stale → 409 with `details.currentVersion` echoed.
+ *
+ * 404 when the page does not exist. Success responds 204 No Content.
+ *
+ * Adapter errors (`AdapterWriteError("not_found" | "conflict" | …)`) are
+ * translated by the hoisted `mapAdapterError` from `@working-theory/content-adapters`
+ * (issue #398) — single source of truth across the API + MCP surfaces.
+ */
+import {
+  SCHEMA_ORG_TYPES,
+  type SchemaOrgType,
+} from "@working-theory/content-adapters";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+import { z } from "zod";
+
+import { getContentAdapter } from "../../lib/content-adapter.js";
+import {
+  adapterErrorResponse,
+  conflictError,
+  validationError,
+  type ErrorBody,
+} from "../../lib/errors.js";
+import { requirePaidTier } from "../../lib/require-paid-tier.js";
+
+import { SLUG_PATTERN } from "./slug.js";
+
+const paramsSchema = z.object({
+  type: z.enum(SCHEMA_ORG_TYPES),
+  slug: z.string().regex(SLUG_PATTERN),
+});
+
+function send(reply: FastifyReply, status: number, body: ErrorBody) {
+  return reply.status(status).send(body);
+}
+
+export const deletePageRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.delete<{
+    Params: { type: string; slug: string };
+  }>(
+    "/v1/content/:type/:slug",
+     
+    { preHandler: requirePaidTier },
+    async (request, reply) => {
+      const params = paramsSchema.safeParse(request.params);
+      if (!params.success) {
+        const err = validationError("Invalid type or slug", {
+          issues: params.error.issues,
+        });
+        return send(reply, err.status, err.body);
+      }
+
+      const ifMatch = request.headers["if-match"];
+      if (typeof ifMatch !== "string" || ifMatch.length === 0) {
+        const err = conflictError(
+          "Missing required If-Match header (version token)",
+        );
+        return send(reply, err.status, err.body);
+      }
+
+      const { type, slug } = params.data;
+
+      try {
+        const adapter = getContentAdapter();
+        await adapter.deletePage(type as SchemaOrgType, slug, { ifMatch });
+        return reply.status(204).send();
+      } catch (error) {
+        const err = adapterErrorResponse(error, { type, slug });
+        if (err) return send(reply, err.status, err.body);
+        request.log.error({ err: error }, "[Content] deletePage failed");
+        return reply.status(500).send({ error: "Internal server error" });
+      }
+    },
+  );
+};

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

@@ -0,0 +1,98 @@
+/**
+ * GET /v1/content/:type/:slug
+ *
+ * Returns a single page with its resolved schema.org JSON-LD spread at the
+ * document root, plus the raw frontmatter under `page` for clients that need
+ * the unrendered shape.
+ *
+ * 404 on missing slug, 400 on unknown type.
+ *
+ * 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). The adapter applies the fallback
+ * chain (locale → default-locale → legacy non-prefixed layout).
+ */
+import { SCHEMA_ORG_TYPES, type SchemaOrgType } from "@working-theory/content-adapters";
+import { buildJsonLd, type ContentPageInput } from "@working-theory/schema";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { getContentAdapter } from "../../lib/content-adapter.js";
+import { resolveLocale } from "../../lib/locales.js";
+
+const paramsSchema = z.object({
+  type: z.enum(SCHEMA_ORG_TYPES),
+  slug: z.string().min(1),
+});
+
+const querySchema = z.object({
+  locale: z.string().optional(),
+});
+
+export const getPageRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get<{
+    Params: { type: string; slug: string };
+    Querystring: { locale?: string };
+  }>(
+    "/v1/content/:type/:slug",
+    async (request, reply) => {
+      const parsed = paramsSchema.safeParse(request.params);
+      if (!parsed.success) {
+        return reply.status(400).send({
+          error: "Invalid type or slug",
+          details: parsed.error.issues,
+        });
+      }
+
+      const queryParsed = querySchema.safeParse(request.query);
+      if (!queryParsed.success) {
+        return reply.status(400).send({
+          error: "Invalid query parameters",
+          details: queryParsed.error.issues,
+        });
+      }
+
+      const { type, slug } = parsed.data;
+      const locale = resolveLocale(queryParsed.data.locale);
+
+      try {
+        const adapter = getContentAdapter();
+        const page = await adapter.getPageBySlug(
+          type as SchemaOrgType,
+          slug,
+          locale,
+        );
+        if (!page) {
+          return reply.status(404).send({
+            error: "Page not found",
+            type,
+            slug,
+          });
+        }
+
+        const input: ContentPageInput = {
+          type: page.type,
+          slug: page.slug,
+          title: page.title,
+          description: page.description,
+          ...(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 jsonLd = buildJsonLd(input);
+        return reply.send({ ...jsonLd, page });
+      } 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

@@ -0,0 +1,32 @@
+/**
+ * Public content API.
+ *
+ * Read endpoints, all GET, all JSON-LD-shaped at the document root:
+ *   GET /v1/content/types          — supported page types
+ *   GET /v1/content/:type          — paginated list of pages
+ *   GET /v1/content/:type/:slug    — single page with resolved JSON-LD
+ *
+ * Write endpoints (D14a, Pro-tier gated via `requirePaidTier` preHandler):
+ *   POST   /v1/content/:type             — create a new page
+ *   PATCH  /v1/content/:type/:slug       — update; mandatory `If-Match`
+ *   DELETE /v1/content/:type/:slug       — delete; mandatory `If-Match`
+ *
+ * Rate-limit, CORS, and the OpenAPI spec are wired at server level.
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { createPageRoute } from "./create.js";
+import { deletePageRoute } from "./delete.js";
+import { getPageRoute } from "./get-page.js";
+import { listPagesRoute } from "./list-pages.js";
+import { listTypesRoute } from "./list-types.js";
+import { updatePageRoute } from "./update.js";
+
+export const contentRoutes: FastifyPluginAsync = async (fastify) => {
+  await fastify.register(listTypesRoute);
+  await fastify.register(listPagesRoute);
+  await fastify.register(getPageRoute);
+  await fastify.register(createPageRoute);
+  await fastify.register(updatePageRoute);
+  await fastify.register(deletePageRoute);
+};

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

@@ -0,0 +1,83 @@
+/**
+ * GET /v1/content/:type
+ *
+ * Paginated list of pages for a given schema.org type. Defaults to page 1,
+ * 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.
+ *
+ * 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 type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { getContentAdapter } from "../../lib/content-adapter.js";
+import { resolveLocale } from "../../lib/locales.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);
+    if (!params.success) {
+      return reply.status(400).send({
+        error: "Invalid type",
+        details: params.error.issues,
+      });
+    }
+
+    const query = querySchema.safeParse(request.query);
+    if (!query.success) {
+      return reply.status(400).send({
+        error: "Invalid query parameters",
+        details: query.error.issues,
+      });
+    }
+
+    const { type } = params.data;
+    const { page, pageSize } = query.data;
+    const locale = resolveLocale(query.data.locale);
+
+    try {
+      const adapter = getContentAdapter();
+      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 },
+      });
+    } 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/list-types.ts

@@ -0,0 +1,19 @@
+/**
+ * GET /v1/content/types
+ *
+ * Returns the canonical list of supported schema.org page types. Wrapped in
+ * an `ItemList` JSON-LD envelope so the response carries `@context` / `@type`
+ * at the document root, consistent with the other content endpoints.
+ */
+import { SCHEMA_ORG_TYPES } from "@working-theory/content-adapters";
+import type { FastifyPluginAsync } from "fastify";
+
+export const listTypesRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/content/types", async (_request, reply) => {
+    return reply.send({
+      "@context": "https://schema.org",
+      "@type": "ItemList",
+      types: [...SCHEMA_ORG_TYPES],
+    });
+  });
+};

package/templates/apps/api/src/routes/content/rate-limit.ts

@@ -0,0 +1,13 @@
+/**
+ * Rate-limit configuration for the public content API.
+ *
+ * v1: 60 req/min/IP for unauthenticated callers. Future: when an auth context
+ * lands on the request (e.g. an `auth` claim from the API-token middleware),
+ * the limit can be raised by reading that context inside `keyGenerator` /
+ * `max`. Until then we apply the unauth ceiling globally — agents reading the
+ * public API generally don't authenticate, and authenticated agents have
+ * their own ceiling configurable per-token.
+ */
+export const CONTENT_RATE_LIMIT_UNAUTH = 60;
+export const CONTENT_RATE_LIMIT_AUTH = 600;
+export const CONTENT_RATE_LIMIT_WINDOW = "1 minute";