create-ailk 0.24.0 → 0.26.0

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

@@ -1,391 +0,0 @@
-/**
- * @file openapi.test.ts
- * GET /api/openapi.json — OpenAPI 3.x spec describing the public content API.
- */
-import { openapiRoutes } from "../index";
-import { buildOpenApiSpec } from "../spec";
-
-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",
-    );
-  });
-
-  // #9285 AC-3 — the Stripe connection read's three answers are documented, and
-  // only on a build that registers the billing routes (multi-tenant).
-  describe("Inbox message and Person record reads (#9349 DD8, AC-10)", () => {
-    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
-    const LIST_PATH = "/v1/workspaces/{workspaceId}/messages";
-    const ITEM_PATH = "/v1/workspaces/{workspaceId}/messages/{leadId}";
-    const PERSON_PATH = "/v1/workspaces/{workspaceId}/people/{personId}";
-
-    afterEach(() => {
-      if (PRIOR_ENABLED_MODULES === undefined) {
-        delete process.env.AILK_ENABLED_MODULES;
-      } else {
-        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
-      }
-    });
-
-    const dataRef = (op: { responses: Record<string, unknown> }) =>
-      (op.responses["200"] as {
-        content: {
-          "application/json": { schema: { properties: { data: { $ref: string } } } };
-        };
-      }).content["application/json"].schema.properties.data.$ref;
-
-    it("documents the two message GETs and the Person record on a multi-tenant build", async () => {
-      process.env.AILK_ENABLED_MODULES = "multi-tenant";
-      const spec = JSON.parse(
-        (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
-      );
-
-      expect(spec.paths[LIST_PATH].get.operationId).toBe("listInboxMessages");
-      expect(dataRef(spec.paths[LIST_PATH].get)).toBe("#/components/schemas/InboxMessageList");
-      expect(spec.paths[ITEM_PATH].get.operationId).toBe("getInboxMessage");
-      expect(dataRef(spec.paths[ITEM_PATH].get)).toBe("#/components/schemas/InboxMessage");
-      expect(spec.paths[PERSON_PATH].get.operationId).toBe("getPersonRecord");
-      expect(dataRef(spec.paths[PERSON_PATH].get)).toBe("#/components/schemas/PersonRecord");
-
-      const message = spec.components.schemas.InboxMessage;
-      expect(Object.keys(message.properties).sort()).toEqual([
-        "body",
-        "createdAt",
-        "email",
-        "excerpt",
-        "handledAt",
-        "id",
-        "name",
-        "personId",
-        "source",
-      ]);
-      expect(message.additionalProperties).toBe(false);
-      expect(
-        Object.keys(spec.components.schemas.PersonRecord.properties.person.properties),
-      ).toContain("stripeCustomerUrl");
-    });
-
-    it("the PATCH on the item path stays the derived operation beside the hand-authored GET", () => {
-      process.env.AILK_ENABLED_MODULES = "multi-tenant";
-      const url = "/v1/workspaces/:workspaceId/messages/:leadId";
-      const spec = buildOpenApiSpec({}, [
-        { method: "GET", url },
-        { method: "PATCH", url },
-      ]);
-      const item = spec.paths[ITEM_PATH] as Record<
-        string,
-        { operationId: string; description: string }
-      >;
-      expect(item.get!.operationId).toBe("getInboxMessage");
-      expect(item.patch!.description).toContain(
-        "Derived from this deployment's route table",
-      );
-    });
-
-    it("advertises none of the three where the routes do not register", async () => {
-      process.env.AILK_ENABLED_MODULES = "commerce";
-      const spec = JSON.parse(
-        (await app.inject({ method: "GET", url: "/v1/openapi.json" })).body,
-      );
-      for (const path of [LIST_PATH, ITEM_PATH, PERSON_PATH]) {
-        expect(spec.paths[path]).toBeUndefined();
-      }
-    });
-  });
-
-  describe("stripe-connection read (#9285)", () => {
-    const PRIOR_ENABLED_MODULES = process.env.AILK_ENABLED_MODULES;
-
-    afterEach(() => {
-      if (PRIOR_ENABLED_MODULES === undefined) {
-        delete process.env.AILK_ENABLED_MODULES;
-      } else {
-        process.env.AILK_ENABLED_MODULES = PRIOR_ENABLED_MODULES;
-      }
-    });
-
-    it("documents the stored view, the environment source and null on a multi-tenant build", async () => {
-      process.env.AILK_ENABLED_MODULES = "multi-tenant";
-      const res = await app.inject({ method: "GET", url: "/v1/openapi.json" });
-      const spec = JSON.parse(res.body);
-
-      const get = spec.paths["/v1/billing/stripe-connection"].get;
-      expect(get.operationId).toBe("getStripeConnection");
-      expect(get.responses["200"].content["application/json"].schema.$ref).toBe(
-        "#/components/schemas/StripeConnectionReadResponse",
-      );
-
-      const { data } = spec.components.schemas.StripeConnectionReadResponse.properties;
-      expect(data.nullable).toBe(true);
-      expect(data.oneOf).toEqual([
-        { $ref: "#/components/schemas/StripeConnectionView" },
-        { $ref: "#/components/schemas/StripeEnvironmentSource" },
-      ]);
-
-      // The environment source carries the mode and nothing else.
-      const env = spec.components.schemas.StripeEnvironmentSource;
-      expect(Object.keys(env.properties).sort()).toEqual(["mode", "source"]);
-      expect(env.properties.source.enum).toEqual(["environment"]);
-      expect(env.additionalProperties).toBe(false);
-    });
-
-    it("does not advertise it where the billing routes do not register", async () => {
-      process.env.AILK_ENABLED_MODULES = "commerce";
-      const res = await app.inject({ method: "GET", url: "/v1/openapi.json" });
-      const spec = JSON.parse(res.body);
-      expect(spec.paths["/v1/billing/stripe-connection"]).toBeUndefined();
-    });
-  });
-
-  // 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)),
-    );
-  });
-};