@starci/hfs 4.2.17 → 4.4.0

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.decorators.ts

@@ -5,6 +5,7 @@ import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
 import { requestOf } from "@modules/platform/http-security"
 import type { Principal } from "@modules/platform/cqrs"
+import type { CredentialAuthenticator, CredentialMetadata } from "./credential.contracts"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import type { PublicMetadata } from "./identity.contracts"
 
@@ -18,9 +19,23 @@ export const InjectAccessTokenVerifier = (): TypedParameterDecorator<VerifySupab
 /** Metadata key of `@Public`. */
 export const PUBLIC_KEY = "domain.identity.public"
 
-/** Opens a door to anonymous callers, stating why; every other door needs a verified Supabase session. */
+/** Opens a door to anonymous callers, stating why; every other door needs a credential or a verified Supabase session. */
 export const Public = (metadata: PublicMetadata): ReturnType<typeof SetMetadata> => SetMetadata(PUBLIC_KEY, metadata)
 
+/** Metadata key of `@Credential`. */
+export const CREDENTIAL_KEY: unique symbol = Symbol("domain.identity.credential")
+
+/** Token of the identity-owned port that authenticates an API key, run token, tool token or link token. */
+export const CREDENTIAL_AUTHENTICATOR: unique symbol = Symbol("domain.identity.credential-authenticator")
+
+/** Injects the credential authenticator identity was registered with. Parameter type: CredentialAuthenticator. */
+export const InjectCredentialAuthenticator = (): TypedParameterDecorator<CredentialAuthenticator> =>
+    injector<CredentialAuthenticator>(CREDENTIAL_AUTHENTICATOR)
+
+/** Marks a door authenticated by its own credential; `CredentialGuard` authenticates it and `AuthGuard` admits it. */
+export const Credential = (metadata: CredentialMetadata): ReturnType<typeof SetMetadata> =>
+    SetMetadata(CREDENTIAL_KEY, metadata)
+
 /** The authenticated Supabase caller established by the default-deny guard. */
 export const CurrentPrincipal = createParamDecorator((_data: unknown, context: ExecutionContext): Principal => {
     const principal = requestOf(context).principal

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.module.ts

@@ -1,15 +1,28 @@
 import { Module } from "@nestjs/common"
-import type { DynamicModule } from "@nestjs/common"
+import type { DynamicModule, Provider } from "@nestjs/common"
 import { AuthGuard } from "./auth.guard"
-import { ACCESS_TOKEN_VERIFIER } from "./identity.decorators"
+import { CredentialGuard } from "./credential.guard"
+import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
+import { ACCESS_TOKEN_VERIFIER, CREDENTIAL_AUTHENTICATOR } from "./identity.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./identity.module-definition"
 
+const refusingAuthenticator: Provider = {
+    provide: CREDENTIAL_AUTHENTICATOR,
+    useValue: {
+        authenticate: () => Promise.reject(new IdentityError({ code: IdentityErrorCode.Unauthenticated })),
+    },
+}
+
 @Module({})
-/** The identity capability: its default-deny guard admits only public doors or a verified Supabase principal. */
+/** The identity capability: the app registers its credential and default-deny guards after the throttler and origin guard. */
 export class IdentityModule extends ConfigurableModuleClass {
     /** Registers identity once per app with the verifier parsed at the composition root. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
+        const authenticator: Provider =
+            options.credentialAuthenticator === undefined
+                ? refusingAuthenticator
+                : { provide: CREDENTIAL_AUTHENTICATOR, useClass: options.credentialAuthenticator }
         return {
             ...base,
             providers: [
@@ -18,9 +31,11 @@ export class IdentityModule extends ConfigurableModuleClass {
                     provide: ACCESS_TOKEN_VERIFIER,
                     useValue: options.verifyAccessToken,
                 },
+                authenticator,
+                CredentialGuard,
                 AuthGuard,
             ],
-            exports: [AuthGuard],
+            exports: [CredentialGuard, CREDENTIAL_AUTHENTICATOR, AuthGuard, ACCESS_TOKEN_VERIFIER],
         }
     }
 }

package/templates/be/skeleton-lite/src/modules/domain/identity/identity.options.ts

@@ -1,7 +1,11 @@
+import type { Type } from "@nestjs/common"
 import type { VerifySupabaseAccessToken } from "@modules/integrations/supabase"
+import type { CredentialAuthenticator } from "./credential.contracts"
 
-/** The verified identity source used by the default-deny guard. */
+/** The identity capability's credential and session verification options. */
 export interface IdentityOptions {
+    /** The app-owned authenticator of alternate credentials; a credential door fails closed while it is absent. */
+    readonly credentialAuthenticator?: Type<CredentialAuthenticator>
     /** Cryptographically verifies a Supabase access token before it can become a principal. */
     readonly verifyAccessToken: VerifySupabaseAccessToken
 }

package/templates/be/skeleton-lite/src/modules/domain/identity/index.ts

@@ -1,6 +1,7 @@
 export { AuthGuard } from "./auth.guard"
+export { CredentialGuard } from "./credential.guard"
 export { IDENTITY_ERROR_KINDS } from "./errors/identity.error"
 export { IDENTITY_MESSAGES } from "./messages/identity.messages"
 export { PublicReason } from "./identity.contracts"
-export { Public } from "./identity.decorators"
+export { ACCESS_TOKEN_VERIFIER, Public } from "./identity.decorators"
 export { IdentityModule } from "./identity.module"

package/templates/be/skeleton-lite/src/modules/integrations/supabase/errors/supabase.error.ts

@@ -5,14 +5,11 @@ import type { ErrorKind } from "@modules/platform/errors"
 export enum SupabaseErrorCode {
     /** The access token failed signature or required-claim verification. */
     AccessTokenInvalid = "SUPABASE_ACCESS_TOKEN_INVALID",
-    /** A privileged Auth or Storage operation could not reach Supabase. */
-    ProviderUnavailable = "SUPABASE_PROVIDER_UNAVAILABLE",
 }
 
 /** How each Supabase integration code travels. */
 export const SUPABASE_ERROR_KINDS: Record<SupabaseErrorCode, ErrorKind> = {
     [SupabaseErrorCode.AccessTokenInvalid]: "unauthenticated",
-    [SupabaseErrorCode.ProviderUnavailable]: "unavailable",
 }
 
 /** The one error class of the Supabase integration. */

package/templates/be/skeleton-lite/src/modules/integrations/supabase/supabase.client.spec.ts

@@ -1,12 +1,24 @@
+import { Test } from "@nestjs/testing"
 import { Secret } from "@modules/platform/config"
 import { createSupabaseAdminClient } from "./supabase.client"
+import type { SupabaseAdminClient } from "./supabase.client"
+import { SUPABASE_ADMIN_CLIENT } from "./supabase.decorators"
 
 describe("createSupabaseAdminClient", () => {
-    it("exposes only the Auth administration and Storage surfaces of a session-less service client", () => {
-        const client = createSupabaseAdminClient({
-            url: "http://127.0.0.1:54321",
-            serviceRoleKey: new Secret("service-role"),
-        })
+    it("exposes only the Auth administration and Storage surfaces of a session-less service client", async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [
+                {
+                    provide: SUPABASE_ADMIN_CLIENT,
+                    useFactory: () =>
+                        createSupabaseAdminClient({
+                            url: "http://127.0.0.1:54321",
+                            serviceRoleKey: new Secret("service-role"),
+                        }),
+                },
+            ],
+        }).compile()
+        const client = moduleRef.get<SupabaseAdminClient>(SUPABASE_ADMIN_CLIENT)
 
         expect(Object.keys(client).sort()).toEqual(["auth", "storage"])
         expect(typeof client.auth.createUser).toBe("function")

package/templates/be/skeleton-lite/src/modules/platform/database/database.module.ts

@@ -2,10 +2,12 @@ import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { TypeOrmModule, getDataSourceToken } from "@nestjs/typeorm"
 import type { DataSource } from "typeorm"
+import { DatabaseProbeService } from "./database-probe.service"
 import { DATABASE_OPTIONS } from "./database.port"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./database.module-definition"
+import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 import { PRIMARY_CONNECTION } from "./primary.connection"
-import { PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
+import { DATABASE_PROBE, PRIMARY_ENTITY_MANAGER } from "./primary.decorators"
 
 /** The token each declared connection provides its shared EntityManager under. */
 type EntityManagerToken = typeof PRIMARY_ENTITY_MANAGER
@@ -20,18 +22,23 @@ export class DatabaseModule extends ConfigurableModuleClass {
     /** Registers the capability once per app with the connections it opens. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
-        const managers = options.connections.flatMap((connection) => {
+        const managers = options.connections.map((connection) => {
             const token = ENTITY_MANAGER_TOKENS.get(connection.name)
-            return token === undefined
-                ? []
-                : [
-                      {
-                          provide: token,
-                          inject: [getDataSourceToken(connection.name)],
-                          useFactory: (source: DataSource) => source.manager,
-                      },
-                  ]
+            if (token === undefined) {
+                throw new DatabaseError({
+                    code: DatabaseErrorCode.ConnectionUndeclared,
+                    params: { name: connection.name },
+                })
+            }
+            return {
+                provide: token,
+                inject: [getDataSourceToken(connection.name)],
+                useFactory: (source: DataSource) => source.manager,
+            }
         })
+        const probes = options.connections.some((connection) => connection.name === PRIMARY_CONNECTION)
+            ? [{ provide: DATABASE_PROBE, useClass: DatabaseProbeService }]
+            : []
         return {
             ...base,
             imports: [
@@ -47,8 +54,12 @@ export class DatabaseModule extends ConfigurableModuleClass {
                     }),
                 ),
             ],
-            providers: [...(base.providers ?? []), ...managers],
-            exports: [DATABASE_OPTIONS, ...managers.map((manager) => manager.provide)],
+            providers: [...(base.providers ?? []), ...managers, ...probes],
+            exports: [
+                DATABASE_OPTIONS,
+                ...probes.map((probe) => probe.provide),
+                ...managers.map((manager) => manager.provide),
+            ],
         }
     }
 }

package/templates/be/skeleton-lite/src/modules/platform/database/database.port.ts

@@ -1,6 +1,11 @@
+import { getDataSourceToken } from "@nestjs/typeorm"
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
 import type { DatabaseOptions } from "./database.options"
+import { PRIMARY_CONNECTION } from "./primary.connection"
+
+/** The primary pool's override token for infrastructure fixtures; TypeORM tokens stay owned by this capability. */
+export const PRIMARY_DATA_SOURCE = getDataSourceToken(PRIMARY_CONNECTION)
 
 /** Token of the options of the database capability. */
 export const DATABASE_OPTIONS: unique symbol = Symbol("platform.database.options")

package/templates/be/skeleton-lite/src/modules/platform/database/errors/database.error.ts

@@ -0,0 +1,16 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the database capability. */
+export enum DatabaseErrorCode {
+    /** A configured connection has no declared EntityManager injection token. */
+    ConnectionUndeclared = "DATABASE_CONNECTION_UNDECLARED",
+}
+
+/** How each database code travels. */
+export const DATABASE_ERROR_KINDS: Record<DatabaseErrorCode, ErrorKind> = {
+    [DatabaseErrorCode.ConnectionUndeclared]: "internal",
+}
+
+/** The one error class of the database capability. */
+export class DatabaseError extends DomainError<DatabaseErrorCode> {}

package/templates/be/skeleton-lite/src/modules/platform/database/index.ts

@@ -1,4 +1,7 @@
 export { DatabaseModule } from "./database.module"
+export { DATABASE_PROBE, InjectDatabaseProbe } from "./primary.decorators"
+export { DatabaseProbeService } from "./database-probe.service"
 export type { DatabaseConnectionOptions } from "./database.options"
+export { PRIMARY_DATA_SOURCE } from "./database.port"
 export { DATABASE_ERROR_KINDS } from "./errors/database.error"
 export { parsePrimaryDatabaseConfig } from "./primary.config"

package/templates/be/skeleton-lite/src/modules/platform/http-security/http-security.module.ts

@@ -1,7 +1,9 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
+import { APP_PIPE } from "@nestjs/core"
 import { WEBHOOK_SIGNATURE } from "./http-security.decorators"
 import { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } from "./http-security.module-definition"
+import { ReadinessService } from "./readiness.service"
 import { RequestValidationService } from "./request-validation.service"
 import { WebhookSignatureService } from "./webhook-signature.service"
 
@@ -15,11 +17,12 @@ export class HttpSecurityModule extends ConfigurableModuleClass {
             ...base,
             providers: [
                 ...(base.providers ?? []),
-                RequestValidationService,
+                { provide: APP_PIPE, useClass: RequestValidationService },
                 WebhookSignatureService,
+                ReadinessService,
                 { provide: WEBHOOK_SIGNATURE, useExisting: WebhookSignatureService },
             ],
-            exports: [MODULE_OPTIONS_TOKEN, RequestValidationService, WebhookSignatureService, WEBHOOK_SIGNATURE],
+            exports: [MODULE_OPTIONS_TOKEN, WebhookSignatureService, WEBHOOK_SIGNATURE, ReadinessService],
         }
     }
 }

package/templates/be/skeleton-lite/src/modules/platform/http-security/index.ts

@@ -6,4 +6,7 @@ export type { HttpSecurityOptions } from "./http-security.options"
 export { HTTP_SECURITY_MESSAGES } from "./messages/http-security.messages"
 export { OriginGuard } from "./origin.guard"
 export { RateLimitGuard } from "./rate-limit.guard"
-export { RequestValidationService } from "./request-validation.service"
+export { applyHttpSecurity } from "./edge-security.service"
+export { ReadinessService } from "./readiness.service"
+export { InjectReadiness } from "./readiness.decorators"
+export type { ReadinessReport } from "./readiness.contracts"

package/templates/be/skeleton-lite/src/modules/platform/i18n/index.ts

@@ -1,4 +1,4 @@
 export type { Locale, MessageBundle } from "./i18n.contracts"
-export { InjectMessageCatalog, InjectRequestLocale, MESSAGE_CATALOG } from "./i18n.decorators"
+export { InjectMessageCatalog, InjectRequestLocale, MESSAGE_CATALOG, REQUEST_LOCALE } from "./i18n.decorators"
 export { I18nModule } from "./i18n.module"
 export type { MessageCatalog, RequestLocale } from "./i18n.port"

package/templates/be/skeleton-lite/src/modules/platform/logging/logging.log-events.ts

@@ -0,0 +1,7 @@
+/** Log events of the process lifecycle: the entry points log these. */
+export enum LoggingLogEvent {
+    /** The HTTP listener is bound and the service answers requests. */
+    ServerStarted = "server.started",
+    /** The service failed before it could serve; the process exits non-zero. */
+    StartupFailed = "server.startup_failed",
+}

package/templates/be/skeleton-lite/src/tests/fixtures/builders/api.builder.ts

@@ -0,0 +1,29 @@
+import { Secret } from "@modules/platform/config"
+import { PRIMARY_DATA_SOURCE } from "@modules/platform/database"
+import { ACCESS_TOKEN_VERIFIER } from "@modules/domain/identity"
+import { SUPABASE_ACCESS_TOKEN_VERIFIER, SUPABASE_ADMIN_CLIENT } from "@modules/integrations/supabase"
+
+/** Compiles the real API root with public configuration and explicit infrastructure doubles. */
+export const buildWiringProof = () => ({
+    options: {
+        server: { port: 3000 },
+        httpSecurity: {
+            allowedOrigins: ["https://fixture.example"],
+            rateLimit: { windowMs: 60000, defaultLimit: 100, strictLimit: 10 },
+            webhooks: {},
+        },
+        database: {
+            name: "primary",
+            provider: "supabase",
+            url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
+            schema: "public",
+        },
+        supabase: { url: "https://fixture.supabase.co", serviceRoleKey: new Secret("fixture-only") },
+    },
+    overrides: [
+        { token: PRIMARY_DATA_SOURCE, value: { manager: {} } },
+        { token: SUPABASE_ADMIN_CLIENT, value: { auth: {}, storage: {} } },
+        { token: SUPABASE_ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
+        { token: ACCESS_TOKEN_VERIFIER, value: () => ({ ok: false }) },
+    ],
+})

package/templates/be/skeleton-lite/src/tests/fixtures/builders/cli.builder.ts

@@ -0,0 +1,16 @@
+import { getDataSourceToken } from "@nestjs/typeorm"
+import { Secret } from "@modules/platform/config"
+import { PRIMARY_CONNECTION } from "@modules/platform/database"
+
+/** Public fixture options and the database double for compiling the real CLI AppModule without network access. */
+export const buildWiringProof = () => ({
+    options: {
+        connections: [{
+            name: PRIMARY_CONNECTION,
+            provider: "supabase",
+            url: new Secret("postgresql://app_be@127.0.0.1:5432/postgres"),
+            schema: "public",
+        }],
+    },
+    overrides: [{ token: getDataSourceToken(PRIMARY_CONNECTION), value: { manager: {} } }],
+})

package/templates/be/table/api/feature.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { {{Name}}ApiOptions } from "./{{name}}.options"
+
+/** The configurable-module base of the {{name}} module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<{{Name}}ApiOptions>().setClassMethodName("register").build()

package/templates/be/table/api/feature.module.ts.tpl

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { Create{{Singular}}Handler } from "./application/create-{{singular}}.handler"
 import { Get{{Singular}}Handler } from "./application/get-{{singular}}.handler"
+import { ConfigurableModuleClass } from "./{{name}}.module-definition"
 
 @Module({ providers: [Get{{Singular}}Handler, Create{{Singular}}Handler] })
 /** The {{name}} feature: the handlers of its application. */
-export class {{Name}}ApiModule {}
+export class {{Name}}ApiModule extends ConfigurableModuleClass {}

package/templates/be/table/api/feature.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The {{name}} module takes no options yet. */
+export type {{Name}}ApiOptions = Record<string, never>

package/templates/be/table/api/graphql.module-definition.ts.tpl

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { {{Name}}GraphqlOptions } from "./{{name}}-graphql.options"
+
+/** The configurable-module base of the {{name}}-graphql module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<{{Name}}GraphqlOptions>().setClassMethodName("register").build()

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

@@ -2,7 +2,8 @@ import { Module } from "@nestjs/common"
 import { {{Name}}ApiModule } from "../../{{name}}.module"
 import { Create{{Singular}}Resolver } from "./create-{{singular}}.resolver"
 import { Get{{Singular}}Resolver } from "./get-{{singular}}.resolver"
+import { ConfigurableModuleClass } from "./{{name}}-graphql.module-definition"
 
-@Module({ imports: [{{Name}}ApiModule], providers: [Get{{Singular}}Resolver, Create{{Singular}}Resolver] })
+@Module({ imports: [{{Name}}ApiModule.register({})], providers: [Get{{Singular}}Resolver, Create{{Singular}}Resolver] })
 /** The GraphQL transport of the {{name}} feature. */
-export class {{Name}}GraphqlModule {}
+export class {{Name}}GraphqlModule extends ConfigurableModuleClass {}

package/templates/be/table/api/graphql.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The {{name}}-graphql module takes no options yet. */
+export type {{Name}}GraphqlOptions = Record<string, never>

package/templates/be/table/migration.sql.tpl

@@ -8,6 +8,7 @@ create table public.{{tableSql}} (
 create index {{table}}_owner_id_idx on public.{{tableSql}} (owner_id);
 
 alter table public.{{tableSql}} enable row level security;
+alter table public.{{tableSql}} force row level security;
 
 create trigger {{table}}_set_updated_at
 before update on public.{{tableSql}}

package/templates/be/upgrade-full/apps/cli/src/app.module.ts

@@ -1,13 +1,11 @@
 import { Module } from "@nestjs/common";
-import { CliModule } from "@features/cli";
-import { ClockModule } from "@modules/platform/clock";
-import { LoggingModule } from "@modules/platform/logging";
+import { cliModules } from "./compose/cli";
+import { platformModules } from "./compose/platform";
 
 @Module({
   imports: [
-    ClockModule.register({ isGlobal: true }),
-    LoggingModule.register({ isGlobal: true }),
-    CliModule,
+    ...platformModules(),
+    ...cliModules(),
   ],
 })
 /** The cli composition root; database schema changes remain delegated to the Supabase CLI. */

package/templates/be/upgrade-full/apps/cli/src/cli.env.ts

@@ -0,0 +1,7 @@
+import type { EnvSource } from "@modules/platform/config"
+
+/** This command app delegates migration configuration to the managed Supabase CLI. */
+export interface CliEnv {}
+
+/** Keeps the command app's environment boundary explicit while no command needs app configuration. */
+export const readCliEnv = (_env: EnvSource): CliEnv => ({})

package/templates/be/upgrade-full/apps/cli/src/compose/cli.ts

@@ -0,0 +1,5 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+import { CliModule } from "@features/cli"
+
+/** The command groups of the upgraded CLI app. */
+export const cliModules = (): Array<Type<unknown> | DynamicModule> => [CliModule.register({})]

package/templates/be/upgrade-full/apps/cli/src/compose/platform.ts

@@ -0,0 +1,9 @@
+import type { DynamicModule } from "@nestjs/common"
+import { ClockModule } from "@modules/platform/clock"
+import { LoggingModule } from "@modules/platform/logging"
+
+/** The shared clock and logger; migrations retain their Supabase CLI authority. */
+export const platformModules = (): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+]

package/templates/be/upgrade-full/apps/cli/src/main.ts

@@ -1,11 +1,14 @@
 import "reflect-metadata";
 import { CommandFactory } from "nest-commander";
 import { SystemClockService } from "@modules/platform/clock";
+import { EnvSource } from "@modules/platform/config";
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging";
 import { AppModule } from "./app.module";
+import { readCliEnv } from "./cli.env";
 
 /** The one-off command app. Its migrate command delegates schema authority to the Supabase CLI. */
 async function bootstrap(): Promise<void> {
+  readCliEnv(EnvSource.fromProcess());
   const logger = createJsonLogger(new SystemClockService());
   await CommandFactory.run(AppModule, {
     logger: false,

package/templates/be/upgrade-full/src/features/cli/cli.module.ts

@@ -1,6 +1,7 @@
 import { Module } from "@nestjs/common";
+import { ConfigurableModuleClass } from "./cli.module-definition";
 import { MigrateModule } from "./migrate/migrate.module";
 
-@Module({ imports: [MigrateModule] })
+@Module({ imports: [MigrateModule.register({})] })
 /** The cli feature root of the upgraded app. */
-export class CliModule {}
+export class CliModule extends ConfigurableModuleClass {}

package/templates/fe/auth/supabase-client.ts.tpl

@@ -0,0 +1,34 @@
+const sessionOf = (session: Session | null): AuthSession | undefined =>
+    session === null
+        ? undefined
+        : { userId: session.user.id, ...(session.user.email === undefined ? {} : { email: session.user.email }) }
+
+/** A Supabase Auth error as the provider reports it: its HTTP status, its code and its message. */
+type ProviderError = { readonly status?: number; readonly code?: string; readonly message: string }
+
+/** The failure kind of a Supabase Auth error: refused credentials, rejected input, or the provider unavailable. */
+const kindOf = (status: number | undefined): string => {
+    if (status === 400 || status === 401 || status === 403) return "refused"
+    return status === 422 ? "invalid" : "unavailable"
+}
+
+/** The failure of a Supabase Auth call, or undefined when it succeeded. */
+const failureOf = (error: ProviderError | null): AuthFailure | undefined =>
+    error === null
+        ? undefined
+        : { code: error.code ?? String(error.status ?? "auth"), kind: kindOf(error.status), message: error.message }
+
+/** The Supabase Auth adapter shared by browser and cookie-backed PKCE flows. */
+export const authClient: AuthClient = {
+    session: async () => sessionOf((await supabase().auth.getSession()).data.session),
+    accessToken: async () => (await supabase().auth.getSession()).data.session?.access_token,
+    refreshAccessToken: async () => (await supabase().auth.refreshSession()).data.session?.access_token,
+    signInWithPassword: async (email, password) =>
+        failureOf((await supabase().auth.signInWithPassword({ email, password })).error),
+    signOut: async () => failureOf((await supabase().auth.signOut()).error),
+    // Supabase reports INITIAL_SESSION on subscribe, then every change: the subscription alone keeps the session current.
+    onChange: (listener) => {
+        const { data } = supabase().auth.onAuthStateChange((_event, session) => listener(sessionOf(session)))
+        return () => data.subscription.unsubscribe()
+    },
+}

package/templates/fe/skeleton/apps/__app__/src/app/auth/callback/route.ts

@@ -0,0 +1,11 @@
+import { NextResponse } from "next/server"
+import { exchangeAuthCode } from "@/modules/auth/server"
+import { APP_ROUTES } from "@/modules/routes"
+
+/** The opt-in Supabase PKCE callback only exchanges the code and redirects home. */
+export async function GET(request: Request): Promise<NextResponse> {
+    const url = new URL(request.url)
+    const code = url.searchParams.get("code")
+    if (code) await exchangeAuthCode(code)
+    return NextResponse.redirect(new URL(APP_ROUTES.home, url.origin))
+}

package/templates/fe/skeleton/apps/__app__/src/components/blocks/SignInForm/index.tsx

@@ -24,6 +24,11 @@ export const SignInForm = () => {
     const t = useTranslations("app.signIn")
     const { failure, pending, signIn, reject } = useSignIn()
     if (session.status !== "signed-out") return null
+    const failureMessages = {
+        refused: t("refused"),
+        invalid: t("invalid"),
+        unavailable: t("unavailable"),
+    } satisfies Record<SignInFailure, string>
     const submit = (input: FormData) => {
         const credentials = credentialsOf(input)
         if (credentials === undefined) reject()
@@ -37,7 +42,7 @@ export const SignInForm = () => {
                 emailLabel: t("email"),
                 passwordLabel: t("password"),
                 submitLabel: pending ? t("working") : t("submit"),
-                failure: failure === undefined ? undefined : t(failure),
+                failure: failure === undefined ? undefined : failureMessages[failure],
             }}
             on={{ submit }}
         />

package/templates/fe/skeleton/apps/__app__/src/components/leaves/Icon/index.tsx

@@ -0,0 +1,4 @@
+import { CircleIcon } from "@starci/heroicons/24/outline"
+
+/** The decorative completion ring, delegated to the custom Heroicons cut. Visible copy supplies its meaning. */
+export const Icon = () => <CircleIcon width={24} height={24} aria-hidden="true" />

package/templates/fe/skeleton/apps/__app__/src/features/overlays/AppGuideOverlay/component.tsx

@@ -0,0 +1,31 @@
+import { Button, Dialog, Text } from "@starci/grammar/common"
+import { Icon } from "@/components/leaves/Icon"
+
+/** The guide's copy, local open state and action supplied by the connected overlay. */
+export type AppGuideOverlayBaseProps = {
+    readonly props: {
+        readonly isOpen: boolean
+        readonly triggerLabel: string
+        readonly title: string
+        readonly description: string
+        readonly closeLabel: string
+    }
+    readonly on: { readonly openChange: (isOpen: boolean) => void }
+}
+
+/** A keyboard-accessible grammar dialog whose trigger and dismiss actions update the same local state. */
+export const AppGuideOverlayBase = (props: AppGuideOverlayBaseProps) => (
+    <Dialog
+        isOpen={props.props.isOpen}
+        onOpenChange={props.on.openChange}
+        title={props.props.title}
+        closeLabel={props.props.closeLabel}
+        trigger={
+            <Button variant="secondary" startContent={<Icon />}>
+                {props.props.triggerLabel}
+            </Button>
+        }
+    >
+        <Text>{props.props.description}</Text>
+    </Dialog>
+)

package/templates/fe/skeleton/apps/__app__/src/features/overlays/AppGuideOverlay/index.tsx

@@ -0,0 +1,24 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { useAppGuideStore } from "@/hooks/zustand/appGuide"
+import { AppGuideOverlayBase } from "./component"
+
+/** The home guide connects localized copy to its feature-local zustand store. */
+export const AppGuideOverlay = () => {
+    const t = useTranslations("app.guide")
+    const isOpen = useAppGuideStore((state) => state.isOpen)
+    const setOpen = useAppGuideStore((state) => state.setOpen)
+    return (
+        <AppGuideOverlayBase
+            props={{
+                isOpen,
+                triggerLabel: t("open"),
+                title: t("title"),
+                description: t("description"),
+                closeLabel: t("close"),
+            }}
+            on={{ openChange: setOpen }}
+        />
+    )
+}

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSession.ts

@@ -1,6 +1,11 @@
 "use client"
 
+import { useDebugValue } from "react"
 import { useAppSelector } from "@/redux"
 
 /** The reader's session as the app shares it (redux, kept by the auth session effect): unknown, signed in or signed out. */
-export const useSession = () => useAppSelector((state) => state.session)
+export const useSession = () => {
+    const session = useAppSelector((state) => state.session)
+    useDebugValue(session.status)
+    return session
+}