@starci/hfs 4.2.13 → 4.2.15

package/templates/app/package-scripts/core.json

@@ -1,6 +1,7 @@
     "build:be": "cd be && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "build:fe": "{{buildFe}}",
     "codegen": "node scripts/codegen.mjs",
+    "codegen:graphql": "node scripts/codegen.mjs --graphql",
     "typecheck": "{{typecheck}}",
     "lint": "{{lintPrefix}}{{appBinary}} lint",
     "lint:fix": "{{lintPrefix}}{{appBinary}} lint --fix",

package/templates/app/package-scripts-lite/package.json

@@ -3,6 +3,10 @@
     "prepare": "husky",
     {{appScripts}}
 {{> app/package-scripts/core.json}}
+    "typecheck:tests": "tsc -p be/src/tests/tsconfig.json",
+    "test": "cd be && jest --selectProjects unit --coverage",
+    "test:affected": "cd be && jest --selectProjects unit --passWithNoTests",
+    "test:integration": "npm run typecheck:tests && cd be && jest --selectProjects integration",
     "db:start": "supabase start",
     "db:stop": "supabase stop",
     "db:reset": "supabase db reset",

package/templates/app/skeleton/README.md

@@ -31,7 +31,7 @@ The core api app reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS` (comma-separated
 requests) and `PRIMARY_DB_URL` at boot; every door is closed until it is marked public or sign-in is designed. The cli app reads
 `PRIMARY_DB_URL`: `npm run migrate` applies the migrations of the primary database before the api starts, and
 `npm run cli -- seed run` runs the dev seeds of `.starcistacks/dev/seeds` (run both from the app root). The product app reads
-`NEXT_PUBLIC_SITE_URL`, the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
+`NEXT_PUBLIC_SITE_URL` and `NEXT_PUBLIC_GRAPHQL_URL` (the back end it calls through `src/modules/api`, read once the first GraphQL operation exists), the landing `NEXT_PUBLIC_APP_URL` (the product app it hands the reader over to). A missing key stops the process with an error that names it.
 
 ## Work
 

package/templates/app/skeleton/scripts/codegen.mjs

@@ -1,4 +1,7 @@
 // codegen.mjs - the app's generated code, the one step behind `npm run codegen` (lint, typecheck, dev and build run it first).
 // The front end reads the back end's committed contracts in place (be/contracts/, hfs.json sides.fe.reads) and generates its
 // client from them into a gitignored __generated__/ folder. A new app has no contract yet, so there is nothing to generate.
-process.stdout.write("codegen: no contract under be/contracts yet\n")
+import fs from "node:fs"
+import path from "node:path"
+
+// {{> app/codegen-graphql.mjs.partial}}

package/templates/app/skeleton-lite/README.md

@@ -4,7 +4,7 @@ One StarCi lite app: a Nest API in `be/`, one Next web app in `fe/`, and Supabas
 
 ## Overview
 
-The starter keeps one deployable API and one web app. The browser uses only the public Supabase client under row-level security; privileged Auth and Storage operations stay behind the API.
+The starter keeps one deployable API and one web app, with the same code structure as a full app: the web app calls the API over GraphQL (`src/modules/api`, SWR hooks under `src/hooks/swr`) and uses Supabase only for Auth in the browser (`src/modules/auth`); every data read and write goes through the API, which verifies the access token.
 
 ## Stack
 
@@ -14,7 +14,7 @@ TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Supabas
 
 - `supabase/`: local configuration, forward-only SQL migrations, seed data, and generated database types.
 - `be/`: the API, shared platform capabilities, verified identity admission, and privileged Supabase integrations.
-- `fe/`: the web app; all Supabase access is owned by `src/modules/db`.
+- `fe/`: the web app; the only Supabase client is the Auth client of `src/modules/auth`, data goes through `src/modules/api`.
 - `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
 - `.starciwork/`: product workspace, brand, and shell records.
 
@@ -25,15 +25,18 @@ npm install
 npm run contract:emit
 npm run typecheck
 npm run lint
+npm test
 npm run build:be
 npm run build:fe
 ```
 
-The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, `SUPABASE_URL`, and `SUPABASE_SERVICE_ROLE_KEY`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, and `NEXT_PUBLIC_SUPABASE_ANON_KEY`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
+The API reads `PORT`, `HTTP_SECURITY_ALLOWED_ORIGINS`, `PRIMARY_DB_URL`, `PRIMARY_DB_SCHEMA`, `SUPABASE_URL`, and `SUPABASE_SERVICE_ROLE_KEY`. The web app reads `NEXT_PUBLIC_SITE_URL`, `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY`, and, once the first GraphQL operation exists, `NEXT_PUBLIC_GRAPHQL_URL`. Missing configuration stops the relevant process with a named error; no template supplies credential defaults.
+
+`npm test` runs the back end's unit specs with per-file coverage. Optional integration specs run with `npm run test:integration` against the local Supabase stack (`npm run db:start`); a lite app has no e2e world.
 
 ## Database changes
 
-Create a forward-only migration under `supabase/migrations`, keep each table's RLS policies and grants beside the table, and run `npm run contract:emit` to refresh `supabase/types/database.types.ts`.
+Create a forward-only migration under `supabase/migrations`, keep each table's RLS policies and grants beside the table, and run `npm run contract:emit` to refresh `supabase/types/database.types.ts`. `starci app add table <name> --fe` adds the table with its GraphQL feature on the API and its operations and SWR hooks in the web app; `npm run codegen:graphql` regenerates the web app's wire types from `be/contracts/<app>/schema.graphql`.
 
 ## Work
 

package/templates/app/skeleton-lite/supabase/config.toml

@@ -28,7 +28,7 @@ port = {{supabasePortAnalytics}}
 [auth]
 enabled = true
 site_url = "http://127.0.0.1:3000"
-additional_redirect_urls = ["http://127.0.0.1:3000/auth/callback"]
+additional_redirect_urls = ["http://127.0.0.1:3000/"]
 enable_signup = false
 jwt_expiry = 3600
 

package/templates/app/skeleton-lite/supabase/migrations/__timestamp___baseline.sql

@@ -30,27 +30,26 @@ before update on public.profiles
 for each row
 execute function private.set_updated_at();
 
-create policy profiles_authenticated_select
+create policy profiles_app_be_select
 on public.profiles
 for select
-to authenticated
-using ((select auth.uid()) = id);
+to app_be
+using (id is not null);
 
-create policy profiles_authenticated_insert
+create policy profiles_app_be_insert
 on public.profiles
 for insert
-to authenticated
-with check ((select auth.uid()) = id);
+to app_be
+with check (id is not null);
 
-create policy profiles_authenticated_update
+create policy profiles_app_be_update
 on public.profiles
 for update
-to authenticated
-using ((select auth.uid()) = id)
-with check ((select auth.uid()) = id);
+to app_be
+using (id is not null)
+with check (id is not null);
 
-grant usage on schema public to authenticated;
 grant usage on schema public to app_be;
-revoke all on table public.profiles from public, anon;
-grant select, insert on table public.profiles to authenticated;
-grant update (display_name) on table public.profiles to authenticated;
+revoke all on table public.profiles from public, anon, authenticated;
+grant select, insert on table public.profiles to app_be;
+grant update (display_name) on table public.profiles to app_be;

package/templates/be/inbox/database-client.spec.ts.tpl

@@ -0,0 +1,47 @@
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import type { EntityManager } from "typeorm"
+import { sql } from "./database.sql"
+import { DatabaseErrorCode } from "./errors/database.error"
+import { acceptWebhookDelivery } from "./webhook-inbox.client"
+
+// The client runs whatever claim and completion statements its caller owns; opaque function calls stand in for them here.
+const INSERT = sql`SELECT id FROM claim_spec_inbox($1, $2, $3::jsonb)`
+const COMPLETE = sql`SELECT id FROM complete_spec_inbox($1)`
+const PAYLOAD = { id: "delivery-1" }
+
+const accept = (entityManager: EntityManager, deliveryId: string | undefined, process: (manager: EntityManager) => Promise<void>) =>
+    acceptWebhookDelivery({ entityManager, insert: INSERT, complete: COMPLETE, provider: "spec", deliveryId, payload: PAYLOAD, process })
+
+describe("acceptWebhookDelivery", () => {
+    it("claims a new delivery, processes it and marks it complete in one committed transaction", async () => {
+        const transaction = fakeTransaction(mockEntityManager({ query: [[INSERT, [{ id: "inbox-1" }]], [COMPLETE, [{ id: "inbox-1" }]]] }))
+        const process = jest.fn<Promise<void>, [EntityManager]>().mockResolvedValue(undefined)
+
+        await accept(transaction.em, "  delivery-1  ", process)
+
+        expect(process).toHaveBeenCalledTimes(1)
+        expect(transaction.em.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
+        expect(transaction.em.query).toHaveBeenCalledWith(COMPLETE, ["inbox-1"])
+        expect(transaction.commits).toBe(1)
+    })
+
+    it("acknowledges a duplicate without processing it again", async () => {
+        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, []] }))
+        const process = jest.fn<Promise<void>, [EntityManager]>()
+
+        await accept(transaction.em, "delivery-1", process)
+
+        expect(process).not.toHaveBeenCalled()
+        expect(transaction.em.query).toHaveBeenCalledTimes(1)
+    })
+
+    it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before opening a transaction", async (_label, deliveryId) => {
+        const transaction = fakeTransaction(mockEntityManager())
+        const process = jest.fn<Promise<void>, [EntityManager]>()
+
+        await expect(accept(transaction.em, deliveryId, process)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+
+        expect(transaction.outcomes).toEqual([])
+        expect(process).not.toHaveBeenCalled()
+    })
+})

package/templates/be/inbox/service.spec.ts.tpl

@@ -0,0 +1,46 @@
+import { fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import { Test } from "@nestjs/testing"
+import { @@service@@ } from "@@serviceModule@@"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { COMPLETE_@@providerUpper@@_INBOX, INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
+import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
+
+const DELIVERY = { id: "delivery-1" }
+
+const build = async (claimed: ReadonlyArray<{ readonly id: string }>) => {
+    const entityManager = mockEntityManager({
+        query: [[INSERT_@@providerUpper@@_INBOX, claimed], [COMPLETE_@@providerUpper@@_INBOX, claimed]],
+    })
+    const transaction = fakeTransaction(entityManager)
+    const deliveries = mock<@@service@@>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            @@Provider@@InboxService,
+            { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
+            { provide: @@service@@, useValue: deliveries },
+        ],
+    }).compile()
+    return { inbox: moduleRef.get(@@Provider@@InboxService), deliveries, transaction }
+}
+
+describe("@@Provider@@InboxService", () => {
+    describe("accept@@Provider@@Delivery", () => {
+        it("claims a new @@provider@@ delivery and runs the domain intake inside the claiming transaction", async () => {
+            const { inbox, deliveries, transaction } = await build([{ id: "inbox-1" }])
+
+            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY, expect.anything())
+            expect(transaction.commits).toBe(1)
+        })
+
+        it("acknowledges a duplicate @@provider@@ delivery without running the domain intake again", async () => {
+            const { inbox, deliveries } = await build([])
+
+            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+
+            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+        })
+    })
+})

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -0,0 +1,76 @@
+import { createHmac } from "node:crypto"
+import { FakeClock, mock } from "@starci/jest-preset"
+import type { RawBodyRequest } from "@nestjs/common"
+import { Test } from "@nestjs/testing"
+import type { Request } from "express"
+import { @@Provider@@InboxService } from "@modules/domain/@@provider@@-inbox"
+import { CLOCK, ClockModule } from "@modules/platform/clock"
+import { Secret } from "@modules/platform/config"
+import { HttpSecurityModule } from "@modules/platform/http-security"
+import { @@Event@@Request } from "./dto/@@event@@.request"
+import { @@Provider@@Webhook } from "./@@provider@@.webhook"
+
+const AT = "2026-01-02T03:04:05.000Z"
+const SECRET = "spec-webhook-secret"
+const SIGNED_AT = String(new Date(AT).getTime())
+const DELIVERY_ID = "delivery-1"
+
+/** The delivery the notifier sends: the validated request class, as the pipe builds it. */
+const deliveryOf = (): @@Event@@Request => {
+    const delivery = new @@Event@@Request()
+    delivery.id = DELIVERY_ID
+    return delivery
+}
+
+const DELIVERY = deliveryOf()
+const RAW_BODY = Buffer.from(JSON.stringify(DELIVERY))
+const REQUEST = mock<RawBodyRequest<Request>>({ rawBody: RAW_BODY })
+
+const sign = (rawBody: Buffer, timestamp: string): string =>
+    `sha256=${createHmac("sha256", SECRET).update(`${timestamp}.`).update(rawBody).digest("hex")}`
+
+const build = async (deliveries: @@Provider@@InboxService) => {
+    const moduleRef = await Test.createTestingModule({
+        imports: [
+            ClockModule.register({ isGlobal: true }),
+            HttpSecurityModule.register({
+                allowedOrigins: [],
+                rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
+                webhooks: { "@@provider@@": { secret: new Secret(SECRET), toleranceMs: 300_000 } },
+            }),
+        ],
+        controllers: [@@Provider@@Webhook],
+        providers: [
+            { provide: @@Provider@@InboxService, useValue: deliveries },
+        ],
+    })
+        .overrideProvider(CLOCK)
+        .useValue(new FakeClock(AT))
+        .compile()
+    return moduleRef.get(@@Provider@@Webhook)
+}
+
+describe("@@Provider@@Webhook", () => {
+    describe("receive", () => {
+        it("proves the delivery on its raw body and headers, then hands it and its delivery id to the inbox once", async () => {
+            const deliveries = mock<@@Provider@@InboxService>()
+            const door = await build(deliveries)
+
+            await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY)
+
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY_ID, DELIVERY)
+        })
+
+        it("never reaches the inbox when the signature is not the provider's", async () => {
+            const deliveries = mock<@@Provider@@InboxService>()
+            const door = await build(deliveries)
+
+            await expect(
+                door.receive(REQUEST, sign(Buffer.from("other body"), SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY),
+            ).rejects.toMatchObject({ code: "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID" })
+
+            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+        })
+    })
+})

package/templates/be/patterns/api/graphql.module.ts.tpl

@@ -1,7 +1,7 @@
 import { Module } from "@nestjs/common"
-import { @@Feature@@Module } from "../../@@feature@@.module"
+import { @@Feature@@ApiModule } from "../../@@feature@@.module"
 import { @@Action@@Resolver } from "./@@action@@.resolver"
 
-@Module({ imports: [@@Feature@@Module], providers: [@@Action@@Resolver] })
+@Module({ imports: [@@Feature@@ApiModule], providers: [@@Action@@Resolver] })
 /** The GraphQL transport of the @@feature@@ feature. */
 export class @@Feature@@GraphqlModule {}

package/templates/be/patterns/webhooks/webhook.door.spec.ts.tpl

@@ -4,7 +4,7 @@ import type { RawBodyRequest } from "@nestjs/common"
 import { Test } from "@nestjs/testing"
 import type { Request } from "express"
 import { @@service@@ } from "@@serviceModule@@"
-import { CLOCK } from "@modules/platform/clock"
+import { CLOCK, ClockModule } from "@modules/platform/clock"
 import { Secret } from "@modules/platform/config"
 import { HttpSecurityModule } from "@modules/platform/http-security"
 import { @@Event@@Request } from "./dto/@@event@@.request"
@@ -31,6 +31,7 @@ const sign = (rawBody: Buffer, timestamp: string): string =>
 const build = async (deliveries: @@service@@) => {
     const moduleRef = await Test.createTestingModule({
         imports: [
+            ClockModule.register({ isGlobal: true }),
             HttpSecurityModule.register({
                 allowedOrigins: [],
                 rateLimit: { windowMs: 60_000, defaultLimit: 100, strictLimit: 100 },
@@ -39,10 +40,12 @@ const build = async (deliveries: @@service@@) => {
         ],
         controllers: [@@Provider@@Webhook],
         providers: [
-            { provide: CLOCK, useValue: new FakeClock(AT) },
             { provide: @@service@@, useValue: deliveries },
         ],
-    }).compile()
+    })
+        .overrideProvider(CLOCK)
+        .useValue(new FakeClock(AT))
+        .compile()
     return moduleRef.get(@@Provider@@Webhook)
 }
 

package/templates/be/platform/errors-graphql/graphql-error.mapper.spec.ts

@@ -0,0 +1,52 @@
+import { mock } from "@starci/jest-preset"
+import { GraphQLError } from "graphql"
+import type { ErrorsService } from "./errors.service"
+import { formatGraphqlError } from "./graphql-error.mapper"
+
+const formatted = { message: "raw", path: ["item"], locations: [{ line: 1, column: 3 }] }
+
+describe("formatGraphqlError", () => {
+    it("keeps the message of a malformed operation and marks it invalid without describing it", () => {
+        const errors = mock<ErrorsService>()
+
+        expect(formatGraphqlError(errors, formatted, new GraphQLError("Cannot query field"))).toEqual({
+            message: "raw",
+            path: ["item"],
+            locations: [{ line: 1, column: 3 }],
+            extensions: { kind: "invalid" },
+        })
+        expect(errors.describe).not.toHaveBeenCalled()
+    })
+
+    it("describes the original failure of a resolver and travels its code, kind and params", () => {
+        const errors = mock<ErrorsService>()
+        const cause = new Error("not found")
+        errors.describe.mockReturnValue({
+            code: "ITEM_NOT_FOUND",
+            kind: "not-found",
+            status: 404,
+            params: { id: "i-1" },
+        })
+
+        expect(formatGraphqlError(errors, formatted, new GraphQLError("wrapped", { originalError: cause }))).toEqual({
+            message: "ITEM_NOT_FOUND",
+            path: ["item"],
+            locations: [{ line: 1, column: 3 }],
+            extensions: { code: "ITEM_NOT_FOUND", kind: "not-found", params: { id: "i-1" } },
+        })
+        expect(errors.describe).toHaveBeenCalledWith(cause)
+    })
+
+    it("describes a failure that is not a GraphQL error as it is", () => {
+        const errors = mock<ErrorsService>()
+        const cause = new Error("boom")
+        errors.describe.mockReturnValue({ code: "ERRORS_INTERNAL", kind: "internal", status: 500, params: {} })
+
+        expect(formatGraphqlError(errors, formatted, cause).extensions).toEqual({
+            code: "ERRORS_INTERNAL",
+            kind: "internal",
+            params: {},
+        })
+        expect(errors.describe).toHaveBeenCalledWith(cause)
+    })
+})

package/templates/be/platform/errors-graphql/graphql-error.mapper.ts

@@ -0,0 +1,31 @@
+import { GraphQLError } from "graphql"
+import type { GraphQLFormattedError } from "graphql"
+import type { ErrorsService } from "./errors.service"
+
+/**
+ * The one GraphQL error formatter: a failure thrown by a resolver or a guard becomes `errors[].extensions.{code,kind,params}`
+ * through the errors service (a declared code keeps its code, anything else is masked as internal); a malformed operation
+ * (syntax or validation, no original error) keeps its message with kind `invalid`. The message of a coded error is the code
+ * until the localize plugin replaces it with the catalog text.
+ */
+export const formatGraphqlError = (
+    errors: ErrorsService,
+    formatted: GraphQLFormattedError,
+    error: unknown,
+): GraphQLFormattedError => {
+    if (error instanceof GraphQLError && error.originalError === undefined) {
+        return {
+            message: formatted.message,
+            locations: formatted.locations,
+            path: formatted.path,
+            extensions: { kind: "invalid" },
+        }
+    }
+    const description = errors.describe(error instanceof GraphQLError ? error.originalError : error)
+    return {
+        message: description.code,
+        locations: formatted.locations,
+        path: formatted.path,
+        extensions: { code: description.code, kind: description.kind, params: description.params },
+    }
+}

package/templates/be/platform/graphql/graphql-depth.policy.spec.ts

@@ -0,0 +1,43 @@
+import { buildSchema, parse, validate } from "graphql"
+import { depthLimitRule } from "./graphql-depth.policy"
+
+const schema = buildSchema(`
+    type Query {
+        item: Item
+    }
+
+    type Item {
+        value: String
+        child: Item
+    }
+`)
+
+const validateDepth = (source: string, maxDepth = 2) => validate(schema, parse(source), [depthLimitRule(maxDepth)])
+
+describe("depthLimitRule", () => {
+    it("accepts an operation nested exactly to the depth limit", () => {
+        const errors = validateDepth(`
+            query {
+                item {
+                    value
+                }
+            }
+        `)
+
+        expect(errors).toEqual([])
+    })
+
+    it("rejects the first selection set deeper than the limit", () => {
+        const errors = validateDepth(`
+            query {
+                item {
+                    child {
+                        value
+                    }
+                }
+            }
+        `)
+
+        expect(errors.map((error) => error.message)).toEqual(["Selection depth exceeds 2."])
+    })
+})

package/templates/be/platform/graphql/graphql-depth.policy.ts

@@ -0,0 +1,21 @@
+import { GraphQLError } from "graphql"
+import type { ASTVisitor, ValidationContext } from "graphql"
+
+/** A validation rule that refuses an operation whose selection sets nest deeper than `maxDepth` (each fragment counts on its own). */
+export const depthLimitRule =
+    (maxDepth: number) =>
+    (context: ValidationContext): ASTVisitor => {
+        let depth = 0
+        return {
+            SelectionSet: {
+                enter: () => {
+                    depth += 1
+                    if (depth === maxDepth + 1)
+                        context.reportError(new GraphQLError(`Selection depth exceeds ${maxDepth}.`))
+                },
+                leave: () => {
+                    depth -= 1
+                },
+            },
+        }
+    }

package/templates/be/platform/graphql/graphql.contracts.ts

@@ -0,0 +1,12 @@
+import type { Request, Response } from "express"
+
+/** The GraphQL context every operation runs with: the HTTP request it arrived on and its response. */
+export interface GraphqlContext {
+    /** The HTTP request: the guards read its headers and the principal they establish on it. */
+    readonly req: Request
+    /** The HTTP response. */
+    readonly res: Response
+}
+
+/** The deepest selection nesting an operation may have. */
+export const GRAPHQL_DEPTH_MAX = 10

package/templates/be/platform/graphql/graphql.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { GraphqlOptions } from "./graphql.options"
+
+/** The configurable-module base of the graphql capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<GraphqlOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/platform/graphql/graphql.module.ts

@@ -0,0 +1,49 @@
+import { ApolloDriver } from "@nestjs/apollo"
+import type { ApolloDriverConfig } from "@nestjs/apollo"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { GraphQLModule as NestGraphQLModule } from "@nestjs/graphql"
+import type { Request, Response } from "express"
+import { ERRORS_SERVICE, formatGraphqlError } from "@modules/platform/errors"
+import type { ErrorsService } from "@modules/platform/errors"
+import { REQUEST_LOCALE } from "@modules/platform/i18n"
+import type { RequestLocale } from "@modules/platform/i18n"
+import { GRAPHQL_DEPTH_MAX } from "./graphql.contracts"
+import type { GraphqlContext } from "./graphql.contracts"
+import { depthLimitRule } from "./graphql-depth.policy"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./graphql.module-definition"
+import { localizeErrorsPlugin } from "./localize-errors.mapper"
+
+@Module({})
+/**
+ * The one code-first Apollo server of the api app, the same in both editions: the schema from the resolvers the feature
+ * transports provide, the shared error formatter, a depth limit and the localize plugin. The schema snapshot is
+ * `npm run contract:emit` (contracts/<app>/schema.graphql), never written at boot.
+ */
+export class GraphqlModule extends ConfigurableModuleClass {
+    /** Registers the capability once in the api app; a feature's resolvers join the schema by being providers. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            imports: [
+                ...(base.imports ?? []),
+                NestGraphQLModule.forRootAsync<ApolloDriverConfig>({
+                    driver: ApolloDriver,
+                    inject: [ERRORS_SERVICE, REQUEST_LOCALE],
+                    useFactory: (errors: ErrorsService, requestLocale: RequestLocale) => ({
+                        autoSchemaFile: true,
+                        sortSchema: true,
+                        path: "/graphql",
+                        playground: false,
+                        introspection: true,
+                        context: ({ req, res }: { req: Request; res: Response }): GraphqlContext => ({ req, res }),
+                        formatError: (formatted, error) => formatGraphqlError(errors, formatted, error),
+                        validationRules: [depthLimitRule(GRAPHQL_DEPTH_MAX)],
+                        plugins: [localizeErrorsPlugin(errors, requestLocale)],
+                    }),
+                }),
+            ],
+        }
+    }
+}

package/templates/be/platform/graphql/graphql.options.ts

@@ -0,0 +1,2 @@
+/** The graphql capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type GraphqlOptions = Record<never, never>

package/templates/be/platform/graphql/index.ts

@@ -0,0 +1 @@
+export { GraphqlModule } from "./graphql.module"