create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/openapi/__tests__/openapi.test.ts

@@ -1,264 +0,0 @@
-/**
- * @file openapi.test.ts
- * GET /api/openapi.json — OpenAPI 3.x spec describing the public content API.
- */
-import { openapiRoutes } from "../index";
-
-describe("GET /api/openapi.json", () => {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
-  let app: any;
-
-  beforeEach(async () => {
-    app = require("fastify")();
-    await app.register(openapiRoutes);
-  });
-
-  afterEach(async () => {
-    await app.close();
-  });
-
-  it("returns 200 with a valid OpenAPI 3.x document", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
-    });
-
-    expect(res.statusCode).toBe(200);
-    expect(res.headers["content-type"]).toMatch(/application\/json/);
-
-    const spec = JSON.parse(res.body);
-    expect(spec.openapi).toBe("3.1.0");
-    // The title is resolved from the serving site's own `_site.mdx` (#5307),
-    // so assert its SHAPE rather than a literal site name — the same build
-    // serves a different title on every consuming site.
-    expect(spec.info.title).toMatch(/Public Content API$/);
-    expect(spec.info.version).toBe("1.0.0");
-    expect(typeof spec.paths).toBe("object");
-  });
-
-  it("documents all three content endpoints", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
-    });
-
-    const spec = JSON.parse(res.body);
-    expect(spec.paths["/v1/content/types"].get.operationId).toBe(
-      "listContentTypes",
-    );
-    expect(spec.paths["/v1/content/{type}"].get.operationId).toBe(
-      "listPagesByType",
-    );
-    expect(spec.paths["/v1/content/{type}/{slug}"].get.operationId).toBe(
-      "getPageBySlug",
-    );
-  });
-
-  // The checkout path's OpenAPI documentation is module-conditional (commerce,
-  // D-47 / #5364) — mirroring the route's own registration gate in server.ts —
-  // so these two assertions need the module enabled, exactly as a real
-  // commerce-installed deployment would have it.
-  describe("checkout endpoint (commerce module enabled)", () => {
-    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
-
-    beforeEach(() => {
-      process.env.AILK_ENABLED_MODULES = "commerce";
-    });
-
-    afterEach(() => {
-      if (PRIOR_ENABLED_MODULES === undefined) {
-        delete process.env.AILK_ENABLED_MODULES;
-      } else {
-        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
-      }
-    });
-
-    it("documents the checkout sessions endpoint with operationId createCheckoutSession", async () => {
-      const res = await app.inject({
-        method: "GET",
-        url: "/v1/openapi.json",
-      });
-
-      const spec = JSON.parse(res.body);
-      expect(spec.paths["/v1/checkout/sessions"].post.operationId).toBe(
-        "createCheckoutSession",
-      );
-    });
-
-    it("documents 201, 400, 404, 500, 502 responses for the checkout endpoint", async () => {
-      const res = await app.inject({
-        method: "GET",
-        url: "/v1/openapi.json",
-      });
-
-      const spec = JSON.parse(res.body);
-      const responses = spec.paths["/v1/checkout/sessions"].post.responses;
-      expect(responses["201"].description).toBe("Checkout session created");
-      expect(responses["400"].description).toBe(
-        "Validation error — invalid request body",
-      );
-      expect(responses["404"].description).toBe(
-        "Unknown product code — no active Stripe price for the given productCode",
-      );
-      expect(responses["500"].description).toBe(
-        "Live-mode forbidden — STRIPE_SECRET_KEY is a live key",
-      );
-      expect(responses["502"].description).toBe(
-        "Checkout unavailable — Stripe returned an unexpected error",
-      );
-    });
-  });
-
-  it("declares query and path parameters for content endpoints", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
-    });
-
-    const spec = JSON.parse(res.body);
-    const listOp = spec.paths["/v1/content/{type}"].get;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
-    const paramNames = (listOp.parameters || []).map((p: any) => p.name);
-    expect(paramNames).toEqual(
-      expect.arrayContaining(["type", "page", "pageSize"]),
-    );
-
-    const getOp = spec.paths["/v1/content/{type}/{slug}"].get;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- #506/#507: pre-existing test-hygiene violation
-    const getParams = (getOp.parameters || []).map((p: any) => p.name);
-    expect(getParams).toEqual(expect.arrayContaining(["type", "slug"]));
-  });
-
-  it("declares 200, 400, 404 responses where appropriate", async () => {
-    const res = await app.inject({
-      method: "GET",
-      url: "/v1/openapi.json",
-    });
-
-    const spec = JSON.parse(res.body);
-    expect(
-      spec.paths["/v1/content/{type}/{slug}"].get.responses["200"].description,
-    ).toBe("OK");
-    expect(
-      spec.paths["/v1/content/{type}/{slug}"].get.responses["404"],
-    ).toMatchObject({ $ref: "#/components/responses/NotFound" });
-    expect(
-      spec.paths["/v1/content/{type}"].get.responses["400"],
-    ).toMatchObject({ $ref: "#/components/responses/BadRequest" });
-  });
-
-  describe("lead-write routes (#4991)", () => {
-    const leadPaths: Array<{
-      path: string;
-      operationId: string;
-      requiredFields: string[];
-    }> = [
-      {
-        path: "/v1/leads/submit",
-        operationId: "submitLead",
-        requiredFields: ["siteId", "source", "email", "payload"],
-      },
-      {
-        path: "/v1/leads/subscribe",
-        operationId: "subscribeLead",
-        requiredFields: ["siteId", "email", "source"],
-      },
-      {
-        path: "/v1/leads/callback",
-        operationId: "requestCallback",
-        requiredFields: ["siteId", "name", "phone", "payload"],
-      },
-    ];
-
-    it.each(leadPaths)(
-      "documents $path as a POST with a matching operationId",
-      async ({ path, operationId }) => {
-        const res = await app.inject({
-          method: "GET",
-          url: "/v1/openapi.json",
-        });
-
-        const spec = JSON.parse(res.body);
-        expect(spec.paths[path].post.operationId).toBe(operationId);
-      },
-    );
-
-    it.each(leadPaths)(
-      "documents $path's requestBody with the Zod schema's required keys",
-      async ({ path, requiredFields }) => {
-        const res = await app.inject({
-          method: "GET",
-          url: "/v1/openapi.json",
-        });
-
-        const spec = JSON.parse(res.body);
-        const requestBodySchema =
-          spec.paths[path].post.requestBody.content["application/json"]
-            .schema;
-        const resolved =
-          "$ref" in requestBodySchema
-            ? resolveRef(spec, requestBodySchema.$ref)
-            : requestBodySchema;
-
-        expect(resolved.required.slice().sort()).toEqual(
-          requiredFields.slice().sort(),
-        );
-      },
-    );
-
-    it.each(leadPaths)(
-      "documents 201, 400, and 503 responses for $path",
-      async ({ path }) => {
-        const res = await app.inject({
-          method: "GET",
-          url: "/v1/openapi.json",
-        });
-
-        const spec = JSON.parse(res.body);
-        const responses = spec.paths[path].post.responses;
-        expect(responses["201"]).toBeDefined();
-        expect(responses["400"]).toBeDefined();
-        expect(responses["503"]).toBeDefined();
-      },
-    );
-
-    it("documents /v1/leads/submit's optional Idempotency-Key header and its 422 (#7869)", async () => {
-      const res = await app.inject({
-        method: "GET",
-        url: "/v1/openapi.json",
-      });
-
-      const spec = JSON.parse(res.body);
-      const post = spec.paths["/v1/leads/submit"].post;
-      expect(post.parameters).toEqual(
-        expect.arrayContaining([
-          expect.objectContaining({
-            name: "Idempotency-Key",
-            in: "header",
-            required: false,
-          }),
-        ]),
-      );
-      expect(
-        post.responses["422"].content["application/json"].schema.properties.error
-          .enum,
-      ).toEqual(["idempotency_key_reused"]);
-    });
-
-    it("no longer describes the API as read-only", async () => {
-      const res = await app.inject({
-        method: "GET",
-        url: "/v1/openapi.json",
-      });
-
-      const spec = JSON.parse(res.body);
-      expect(spec.info.description).not.toMatch(/Read-only/i);
-    });
-  });
-});
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any -- test helper over a raw JSON document
-function resolveRef(spec: any, ref: string): any {
-  const path = ref.replace(/^#\//, "").split("/");
-  return path.reduce((node, key) => node[key], spec);
-}

package/templates/apps/api/src/openapi/__tests__/spec-identity.test.ts

@@ -1,182 +0,0 @@
-/**
- * @file spec-identity.test.ts
- *
- * The served API's self-description (#5307) and the `servers` block (#5306).
- *
- * These assert the BUILDER's output given a config rather than a deployed
- * response: the defect is that a deployed site serves the kit's identity and
- * the kit's host, and the builder is the only place that can be proved
- * without deploying.
- */
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  API_VERSION,
-  apiDescription,
-  apiDisplayName,
-  buildOpenApiSpec,
-  resetApiIdentity,
-  resolveApiIdentity,
-} from "../spec";
-
-/** Write a throwaway content root carrying the given `_site.mdx` frontmatter. */
-function withContentRoot(frontmatter: string): string {
-  const root = mkdtempSync(join(tmpdir(), "ailk-site-"));
-  mkdirSync(root, { recursive: true });
-  writeFileSync(join(root, "_site.mdx"), `---\n${frontmatter}\n---\n\nbody\n`);
-  return root;
-}
-
-describe("buildOpenApiSpec — site identity (#5307)", () => {
-  it("titles the spec after the site, not after the kit", () => {
-    const spec = buildOpenApiSpec({ siteName: "Sam Henry" });
-
-    expect(spec.info.title).toBe("Sam Henry — Public Content API");
-    expect(JSON.stringify(spec.info)).not.toMatch(/AI Launch Kit|AILK/i);
-  });
-
-  it("degrades to a named neutral title when no site name is resolvable", () => {
-    const spec = buildOpenApiSpec({});
-
-    expect(spec.info.title).toBe("Public Content API");
-    expect(spec.info.title).not.toMatch(/AI Launch Kit|AILK/i);
-  });
-
-  it("asserts no licence over a deployment that has not chosen one", () => {
-    expect(buildOpenApiSpec({ siteName: "Sam Henry" }).info).not.toHaveProperty(
-      "license",
-    );
-  });
-
-  it("keeps API_VERSION as the /v1 contract version", () => {
-    expect(API_VERSION).toBe("1.0.0");
-    expect(buildOpenApiSpec({}).info.version).toBe(API_VERSION);
-  });
-});
-
-describe("buildOpenApiSpec — servers block (#5306)", () => {
-  it("names the deployment's own API origin", () => {
-    const spec = buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org" });
-
-    expect(spec.servers).toEqual([
-      { url: "https://api.samhenry.org", description: expect.any(String) },
-    ]);
-  });
-
-  it("never serves the kit's own host", () => {
-    const spec = buildOpenApiSpec({
-      siteName: "Sam Henry",
-      publicApiUrl: "https://api.samhenry.org",
-    });
-
-    expect(JSON.stringify(spec)).not.toContain("ailaunchkit.ai");
-  });
-
-  it("normalises a trailing slash", () => {
-    expect(
-      buildOpenApiSpec({ publicApiUrl: "https://api.samhenry.org/" }).servers[0]
-        ?.url,
-    ).toBe("https://api.samhenry.org");
-  });
-
-  it("degrades to a document-relative origin when the value is unset", () => {
-    const spec = buildOpenApiSpec({});
-
-    expect(spec.servers).toHaveLength(1);
-    expect(spec.servers[0]?.url).toBe("/");
-    // The degradation is named in the served document itself, so an agent
-    // reading the spec learns why rather than following a wrong absolute URL.
-    expect(spec.servers[0]?.description).toMatch(/AILK_PUBLIC_API_URL/);
-  });
-
-  it("degrades rather than serving a malformed origin", () => {
-    expect(buildOpenApiSpec({ publicApiUrl: "not-a-url" }).servers[0]?.url).toBe(
-      "/",
-    );
-    expect(
-      buildOpenApiSpec({ publicApiUrl: "ftp://api.example.com" }).servers[0]
-        ?.url,
-    ).toBe("/");
-  });
-});
-
-describe("resolveApiIdentity — reads _site.mdx", () => {
-  const originalContentRoot = process.env.CONTENT_ROOT;
-  let root: string | undefined;
-
-  afterEach(() => {
-    if (originalContentRoot === undefined) delete process.env.CONTENT_ROOT;
-    else process.env.CONTENT_ROOT = originalContentRoot;
-    if (root) rmSync(root, { recursive: true, force: true });
-    root = undefined;
-    resetApiIdentity();
-  });
-
-  it("sources the site name and description from _site.mdx", () => {
-    root = withContentRoot(
-      [
-        'version: "1"',
-        "siteName: Sam Henry",
-        "baseUrl: https://samhenry.org",
-        "siteIdentity:",
-        "  kind: Person",
-        "  name: Sam Henry",
-        "  description: Independent software consultant.",
-      ].join("\n"),
-    );
-    process.env.CONTENT_ROOT = root;
-    resetApiIdentity();
-
-    const identity = resolveApiIdentity();
-
-    expect(identity.siteName).toBe("Sam Henry");
-    expect(identity.siteDescription).toBe("Independent software consultant.");
-    expect(apiDisplayName(identity)).toBe("Sam Henry API");
-    expect(apiDescription(identity)).toBe("Independent software consultant.");
-  });
-
-  // #5306 AC-3 — the trap this card exists to refuse.
-  it("does NOT use _site.mdx baseUrl as the API origin", () => {
-    root = withContentRoot(
-      [
-        'version: "1"',
-        "siteName: Sam Henry",
-        // The SITE origin. The API is deployed on a different host
-        // (api.samhenry.org), so this value must never reach `servers`.
-        "baseUrl: https://samhenry.org",
-      ].join("\n"),
-    );
-    process.env.CONTENT_ROOT = root;
-    resetApiIdentity();
-
-    const identity = resolveApiIdentity();
-    expect(identity.publicApiUrl).not.toBe("https://samhenry.org");
-
-    const spec = buildOpenApiSpec({ ...identity, publicApiUrl: undefined });
-    expect(JSON.stringify(spec.servers)).not.toContain("samhenry.org");
-  });
-
-  it("degrades to a named neutral default when _site.mdx is unreadable", () => {
-    root = mkdtempSync(join(tmpdir(), "ailk-empty-"));
-    process.env.CONTENT_ROOT = root;
-    resetApiIdentity();
-
-    const identity = resolveApiIdentity();
-
-    expect(identity.siteName).toBeUndefined();
-    expect(apiDisplayName(identity)).toBe("Content API");
-    expect(apiDisplayName(identity)).not.toMatch(/AI Launch Kit|AILK/i);
-    expect(buildOpenApiSpec(identity).info.title).toBe("Public Content API");
-  });
-
-  it("degrades when _site.mdx frontmatter is malformed", () => {
-    root = withContentRoot("siteName: [unclosed");
-    process.env.CONTENT_ROOT = root;
-    resetApiIdentity();
-
-    expect(resolveApiIdentity().siteName).toBeUndefined();
-    expect(apiDisplayName(resolveApiIdentity())).toBe("Content API");
-  });
-});

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

@@ -1,18 +0,0 @@
-/**
- * Mounts the OpenAPI spec at GET /v1/openapi.json.
- */
-import type { FastifyPluginAsync } from "fastify";
-
-import { buildOpenApiSpec, readRegisteredRoutes } from "./spec.js";
-
-export const openapiRoutes: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/openapi.json", async (request, reply) => {
-    // The route table comes off the instance that served this request (#5314),
-    // never from module state — two servers built concurrently in one process
-    // would otherwise share, and corrupt, one table. Absent (a bare Fastify
-    // instance with no `build()`) degrades to the hand-authored paths.
-    return reply.send(
-      buildOpenApiSpec(undefined, readRegisteredRoutes(request.server)),
-    );
-  });
-};