@starci/hfs 5.3.0 → 5.5.0

package/templates/be/auth-lite/src/modules/domain/identity/persistence/account-doors.port.ts

@@ -1,6 +1,7 @@
 // Managed by starci app sync (slot be.identity.sign-in); do not edit: run "npx starci app sync --execute".
 import type { EntityManager } from "typeorm"
 import { callDbFunction, returnedRows, rowShape } from "@modules/platform/database"
+import { isRecord } from "@modules/platform/primitives"
 
 /** The account an address stands for, with the stored hash the password is checked against. */
 export interface AccountByEmail {
@@ -22,10 +23,16 @@ export interface AccountById {
     readonly id: string
     /** The sign-in address, or null. */
     readonly email: string | null
+    /** The profile keys of the account (raw_user_meta_data), as the door returns them. */
+    readonly meta: unknown
     /** True when the account is deleted or banned at the database's now(). */
     readonly disabled: boolean
 }
 
+/** The full name the profile keys of an account hold (`full_name`, written by the sign-up and the Google sign-in), or undefined. */
+export const fullNameOf = (meta: unknown): string | undefined =>
+    isRecord(meta) && typeof meta.full_name === "string" && meta.full_name !== "" ? meta.full_name : undefined
+
 /** An account to create: the id, the address, the profile keys as JSON text and the instant. */
 export interface NewAccount {
     /** The account id. */
@@ -49,7 +56,12 @@ const isAccountByEmail: (value: unknown) => value is AccountByEmail = rowShape({
     email_confirmed_at: "date?",
     disabled: "boolean",
 })
-const isAccountById: (value: unknown) => value is AccountById = rowShape({ id: "string", email: "string?", disabled: "boolean" })
+const isAccountById: (value: unknown) => value is AccountById = rowShape({
+    id: "string",
+    email: "string?",
+    meta: "json",
+    disabled: "boolean",
+})
 const isLinkedAccount = rowShape({ be_auth_user_by_google: "string?" })
 const isCreatedAccount = rowShape({ be_auth_create_user: "string" })
 
@@ -60,7 +72,10 @@ const isCreatedAccount = rowShape({ be_auth_create_user: "string" })
 export const accountDoors = {
     /** The account of an exact address, or undefined. */
     async userByEmail(manager: EntityManager, email: string): Promise<AccountByEmail | undefined> {
-        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_user_by_email", [email]), isAccountByEmail)
+        const [row] = returnedRows(
+            await callDbFunction(manager, "public.be_auth_user_by_email", [email]),
+            isAccountByEmail,
+        )
         return row
     },
     /** The standing of an account by id, or undefined. */
@@ -70,7 +85,10 @@ export const accountDoors = {
     },
     /** The account a Google subject is linked to, or null. */
     async userByGoogle(manager: EntityManager, subject: string): Promise<string | null> {
-        const [row] = returnedRows(await callDbFunction(manager, "public.be_auth_user_by_google", [subject]), isLinkedAccount)
+        const [row] = returnedRows(
+            await callDbFunction(manager, "public.be_auth_user_by_google", [subject]),
+            isLinkedAccount,
+        )
         return row?.be_auth_user_by_google ?? null
     },
     /** Creates an account and answers its id. */
@@ -88,7 +106,13 @@ export const accountDoors = {
         await callDbFunction(manager, "public.be_auth_confirm_user", [userId, now])
     },
     /** Sets the password hash of an account; `confirm` also confirms the mailbox, as a spent reset link proves it. */
-    async setPassword(manager: EntityManager, userId: string, hash: string, confirm: boolean, now: Date): Promise<void> {
+    async setPassword(
+        manager: EntityManager,
+        userId: string,
+        hash: string,
+        confirm: boolean,
+        now: Date,
+    ): Promise<void> {
         await callDbFunction(manager, "public.be_auth_set_password", [userId, hash, confirm, now])
     },
     /** Records a sign-in, confirms the mailbox when asked, and fills the profile keys the person has not set. */

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts

@@ -31,4 +31,8 @@ export class IdentityRefreshTokenEntity {
     /** When the token was rotated away, or null while it is the live one. */
     @Column({ name: "used_at", type: "timestamptz", nullable: true })
     usedAt!: Date | null
+
+    /** How many successors replays of this token obtained within the grace window after its rotation (bounded). */
+    @Column({ name: "raced_count", type: "integer", default: 0 })
+    racedCount!: number
 }

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/index.ts

@@ -7,4 +7,9 @@ import { IdentitySessionEntity } from "./identity-session.entity"
 export { IdentityAttemptEntity, IdentityEmailTokenEntity, IdentityRefreshTokenEntity, IdentitySessionEntity }
 
 /** The entities of the identity capability, named in PRIMARY_ENTITIES of platform/database/entities.ts. */
-export const identityEntities: ReadonlyArray<new () => object> = [IdentityAttemptEntity, IdentityEmailTokenEntity, IdentityRefreshTokenEntity, IdentitySessionEntity]
+export const identityEntities: ReadonlyArray<new () => object> = [
+    IdentityAttemptEntity,
+    IdentityEmailTokenEntity,
+    IdentityRefreshTokenEntity,
+    IdentitySessionEntity,
+]

package/templates/be/auth-lite/src/modules/domain/identity/rate-counter.service.spec.ts

@@ -31,7 +31,10 @@ const build = async (entityManager: MockEntityManager) => {
 describe("IdentityRateCounterService.consume", () => {
     it("counts a hit in the live window and compares it with the limit", async () => {
         const entityManager = mockEntityManager()
-        const [counting] = queueQueryBuilders(entityManager, [{ execute: { raw: [{ hits: 3 }] } }, { execute: { raw: [{ hits: 4 }] } }])
+        const [counting] = queueQueryBuilders(entityManager, [
+            { execute: { raw: [{ hits: 3 }] } },
+            { execute: { raw: [{ hits: 4 }] } },
+        ])
         const subject = await build(entityManager)
 
         expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(true)
@@ -50,7 +53,11 @@ describe("IdentityRateCounterService.consume", () => {
 
         expect(await subject.consume("login:abc", WINDOW_MS, 3)).toBe(true)
 
-        expect(entityManager.update).toHaveBeenCalledWith(IdentityAttemptEntity, { key: "login:abc", resetAt: LessThanOrEqual(NOW) }, { hits: 1, resetAt: RESET_AT })
+        expect(entityManager.update).toHaveBeenCalledWith(
+            IdentityAttemptEntity,
+            { key: "login:abc", resetAt: LessThanOrEqual(NOW) },
+            { hits: 1, resetAt: RESET_AT },
+        )
     })
 
     it("opens a window when the restart reports no affected count", async () => {

package/templates/be/auth-lite/src/modules/domain/identity/rate-counter.service.ts

@@ -31,9 +31,18 @@ export class IdentityRateCounterService implements RateCounter {
         const [live] = returnedRows(counted.raw, isCountedWindow)
         if (live !== undefined) return live.hits <= limit
         const resetAt = new Date(now.getTime() + windowMs)
-        const restarted = await this.entityManager.update(IdentityAttemptEntity, { key, resetAt: LessThanOrEqual(now) }, { hits: 1, resetAt })
+        const restarted = await this.entityManager.update(
+            IdentityAttemptEntity,
+            { key, resetAt: LessThanOrEqual(now) },
+            { hits: 1, resetAt },
+        )
         if ((restarted.affected ?? 0) === 0) {
-            await this.entityManager.createQueryBuilder(IdentityAttemptEntity, "attempt").insert().values({ key, hits: 1, resetAt }).orIgnore().execute()
+            await this.entityManager
+                .createQueryBuilder(IdentityAttemptEntity, "attempt")
+                .insert()
+                .values({ key, hits: 1, resetAt })
+                .orIgnore()
+                .execute()
         }
         return limit >= 1
     }

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.spec.ts

@@ -19,6 +19,7 @@ const row = (usedAt: Date | null): IdentityRefreshTokenEntity => ({
     createdAt: NOW,
     expiresAt: LATER,
     usedAt,
+    racedCount: 0,
 })
 
 const build = async (entityManager: MockEntityManager = mockEntityManager()) => {
@@ -31,22 +32,49 @@ const build = async (entityManager: MockEntityManager = mockEntityManager()) =>
 
 describe("IdentitySessionStoreService.transaction", () => {
     it("opens a session and stores a live token in one transaction", async () => {
-        const { subject, entityManager, transaction } = await build(mockEntityManager({ insert: [[IdentitySessionEntity, {}], [IdentityRefreshTokenEntity, {}]] }))
+        const { subject, entityManager, transaction } = await build(
+            mockEntityManager({
+                insert: [
+                    [IdentitySessionEntity, {}],
+                    [IdentityRefreshTokenEntity, {}],
+                ],
+            }),
+        )
 
         await subject.transaction(async (tx) => {
             await tx.openSession({ id: "s-1", userId: "u-1", now: NOW, userAgent: "agent", ip: "203.0.113.9" })
             await tx.insertToken({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER })
         })
 
-        expect(entityManager.insert).toHaveBeenCalledWith(IdentitySessionEntity, { id: "s-1", userId: "u-1", createdAt: NOW, refreshedAt: NOW, userAgent: "agent", ip: "203.0.113.9" })
-        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: null })
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentitySessionEntity, {
+            id: "s-1",
+            userId: "u-1",
+            createdAt: NOW,
+            refreshedAt: NOW,
+            userAgent: "agent",
+            ip: "203.0.113.9",
+        })
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, {
+            id: "t-1",
+            sessionId: "s-1",
+            userId: "u-1",
+            tokenHash: "h-1",
+            expiresAt: LATER,
+            usedAt: null,
+            racedCount: 0,
+        })
         expect(transaction.commits).toBe(1)
     })
+})
 
-    it("reads the token for update, marks it used and drops the expired ones", async () => {
+describe("IdentitySessionStoreService.transaction (a rotation)", () => {
+    it("reads the token for update, marks it used or raced and drops the expired ones", async () => {
         const { subject, entityManager } = await build(
             mockEntityManager({
-                findOne: [[IdentityRefreshTokenEntity, row(NOW)], [IdentityRefreshTokenEntity, null]],
+                findOne: [
+                    [IdentityRefreshTokenEntity, row(NOW)],
+                    [IdentityRefreshTokenEntity, null],
+                ],
                 update: [IdentityRefreshTokenEntity, {}],
                 delete: [IdentityRefreshTokenEntity, {}],
             }),
@@ -56,14 +84,30 @@ describe("IdentitySessionStoreService.transaction", () => {
         const missing = await subject.transaction((tx) => tx.findTokenForUpdate("h-2"))
         await subject.transaction(async (tx) => {
             await tx.markTokenUsed("t-1", NOW)
+            await tx.markTokenRaced("t-1", 2)
             await tx.deleteExpiredTokens("u-1", NOW)
         })
 
-        expect(found).toEqual({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: NOW })
+        expect(found).toEqual({
+            id: "t-1",
+            sessionId: "s-1",
+            userId: "u-1",
+            tokenHash: "h-1",
+            expiresAt: LATER,
+            usedAt: NOW,
+            racedCount: 0,
+        })
         expect(missing).toBeNull()
-        expect(entityManager.findOne).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { where: { tokenHash: "h-1" }, lock: { mode: "pessimistic_write" } })
+        expect(entityManager.findOne).toHaveBeenCalledWith(IdentityRefreshTokenEntity, {
+            where: { tokenHash: "h-1" },
+            lock: { mode: "pessimistic_write" },
+        })
         expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { usedAt: NOW })
-        expect(entityManager.delete).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { userId: "u-1", expiresAt: LessThan(NOW) })
+        expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { racedCount: 2 })
+        expect(entityManager.delete).toHaveBeenCalledWith(IdentityRefreshTokenEntity, {
+            userId: "u-1",
+            expiresAt: LessThan(NOW),
+        })
     })
 
     it("rolls the transaction back when the work throws", async () => {
@@ -77,14 +121,23 @@ describe("IdentitySessionStoreService.transaction", () => {
 
 describe("IdentitySessionStoreService", () => {
     it("finds a token outside a transaction, or none", async () => {
-        const { subject } = await build(mockEntityManager({ findOne: [[IdentityRefreshTokenEntity, row(null)], [IdentityRefreshTokenEntity, null]] }))
+        const { subject } = await build(
+            mockEntityManager({
+                findOne: [
+                    [IdentityRefreshTokenEntity, row(null)],
+                    [IdentityRefreshTokenEntity, null],
+                ],
+            }),
+        )
 
         expect(await subject.findToken("h-1")).toMatchObject({ id: "t-1", usedAt: null })
         expect(await subject.findToken("h-2")).toBeNull()
     })
 
     it("touches, closes and closes the others of a session", async () => {
-        const { subject, entityManager } = await build(mockEntityManager({ update: [IdentitySessionEntity, {}], delete: [IdentitySessionEntity, {}] }))
+        const { subject, entityManager } = await build(
+            mockEntityManager({ update: [IdentitySessionEntity, {}], delete: [IdentitySessionEntity, {}] }),
+        )
 
         await subject.touchSession("s-1", NOW)
         await subject.closeSession("s-1")

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.ts

@@ -13,6 +13,7 @@ const recordOf = (row: IdentityRefreshTokenEntity): RefreshTokenRecord => ({
     tokenHash: row.tokenHash,
     expiresAt: row.expiresAt,
     usedAt: row.usedAt,
+    racedCount: row.racedCount,
 })
 
 const transactionOf = (scoped: EntityManager): SessionTransaction => ({
@@ -34,15 +35,22 @@ const transactionOf = (scoped: EntityManager): SessionTransaction => ({
             tokenHash: token.tokenHash,
             expiresAt: token.expiresAt,
             usedAt: null,
+            racedCount: 0,
         })
     },
     findTokenForUpdate: async (tokenHash) => {
-        const row = await scoped.findOne(IdentityRefreshTokenEntity, { where: { tokenHash }, lock: { mode: "pessimistic_write" } })
+        const row = await scoped.findOne(IdentityRefreshTokenEntity, {
+            where: { tokenHash },
+            lock: { mode: "pessimistic_write" },
+        })
         return row === null ? null : recordOf(row)
     },
     markTokenUsed: async (tokenId, at) => {
         await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { usedAt: at })
     },
+    markTokenRaced: async (tokenId, racedCount) => {
+        await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { racedCount })
+    },
     deleteExpiredTokens: async (userId, before) => {
         await scoped.delete(IdentityRefreshTokenEntity, { userId, expiresAt: LessThan(before) })
     },
@@ -69,7 +77,7 @@ export class IdentitySessionStoreService implements SessionStore {
         await this.entityManager.update(IdentitySessionEntity, { id: sessionId }, { refreshedAt: now })
     }
 
-    /** Ends one session; its tokens go with it (the foreign key cascades). */
+    /** Ends one session and revokes every token of it (the foreign key cascades). */
     async closeSession(sessionId: string): Promise<void> {
         await this.entityManager.delete(IdentitySessionEntity, { id: sessionId })
     }

package/templates/be/auth-lite/src/modules/domain/identity/sign-in.service.spec.ts

@@ -8,7 +8,12 @@ import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import { IDENTITY_AUTH_DOORS, IDENTITY_AUTH_SESSIONS } from "./identity.decorators"
 import { IdentitySignInService } from "./sign-in.service"
 
-const GRANT: AccessGrant = { accessToken: "token", expiresIn: 900, expiresAt: "2026-02-03T04:20:06.000Z", user: { id: "u-1", email: "a@example.test" } }
+const GRANT: AccessGrant = {
+    accessToken: "token",
+    expiresIn: 900,
+    expiresAt: "2026-02-03T04:20:06.000Z",
+    user: { id: "u-1", email: "a@example.test" },
+}
 const REDIRECT: GoogleRedirect = { url: "https://app.example.test/", statusCode: 303 }
 const EXCHANGE = mock<HttpExchange>()
 
@@ -16,7 +21,11 @@ const build = async () => {
     const doors = mock<AuthDoors>()
     const sessions = mock<AuthSessions>()
     const moduleRef = await Test.createTestingModule({
-        providers: [IdentitySignInService, { provide: IDENTITY_AUTH_DOORS, useValue: doors }, { provide: IDENTITY_AUTH_SESSIONS, useValue: sessions }],
+        providers: [
+            IdentitySignInService,
+            { provide: IDENTITY_AUTH_DOORS, useValue: doors },
+            { provide: IDENTITY_AUTH_SESSIONS, useValue: sessions },
+        ],
     }).compile()
     return { subject: moduleRef.get(IdentitySignInService), doors, sessions }
 }
@@ -38,7 +47,15 @@ describe("IdentitySignInService", () => {
         await subject.beginGoogle(EXCHANGE)
         expect(await subject.completeGoogle(EXCHANGE)).toBe(REDIRECT)
 
-        for (const door of [doors.login, doors.refresh, doors.session, doors.logout, doors.beginGoogle, doors.completeGoogle]) expect(door).toHaveBeenCalledWith(EXCHANGE)
+        for (const door of [
+            doors.login,
+            doors.refresh,
+            doors.session,
+            doors.logout,
+            doors.beginGoogle,
+            doors.completeGoogle,
+        ])
+            expect(door).toHaveBeenCalledWith(EXCHANGE)
     })
 
     it("serves the public keys", async () => {
@@ -61,10 +78,14 @@ describe("IdentitySignInService", () => {
         const { subject, sessions } = await build()
         sessions.endOthers.mockRejectedValue(new AuthError("IDENTITY_UNAUTHENTICATED"))
 
-        await expect(subject.endOthers({ id: "u-1", role: "authenticated" })).rejects.toMatchObject({ code: IdentityErrorCode.Unauthenticated })
+        await expect(subject.endOthers({ id: "u-1", role: "authenticated" })).rejects.toMatchObject({
+            code: IdentityErrorCode.Unauthenticated,
+        })
         expect(sessions.endOthers).toHaveBeenCalledWith("u-1", undefined)
     })
+})
 
+describe("IdentitySignInService refusals", () => {
     it("turns a refusal of the package into the error family that owns its code", async () => {
         const { subject, doors } = await build()
         doors.refresh.mockRejectedValue(new AuthError("IDENTITY_REFRESH_REUSED"))

package/templates/be/auth-lite/src/modules/domain/identity/sign-in.service.ts

@@ -4,7 +4,14 @@ import { AuthError, PassportError, PassportErrorCode } from "@modules/integratio
 import type { Principal } from "@modules/platform/cqrs"
 import { IdentityError, IdentityErrorCode } from "./errors/identity.error"
 import { InjectAuthDoors, InjectAuthSessions } from "./identity.decorators"
-import type { AccessGrant, AuthDoors, AuthSessions, GoogleRedirect, HttpExchange, JwksDocument } from "@modules/integrations/passport"
+import type {
+    AccessGrant,
+    AuthDoors,
+    AuthSessions,
+    GoogleRedirect,
+    HttpExchange,
+    JwksDocument,
+} from "@modules/integrations/passport"
 
 /** The wire codes of the package that belong to the passport family (the token, key and Google legs). */
 const PASSPORT_CODES: ReadonlyArray<PassportErrorCode> = [

package/templates/be/auth-lite/src/tests/fixtures/builders/identity.builder.ts

@@ -5,7 +5,7 @@ const BEFORE = new Date("2026-02-03T04:00:00.000Z")
 export type AccountByEmailVariant = "live" | "disabled" | "unconfirmed" | "passwordless" | "invited"
 
 /** The kinds of account the sign-in reads by id. */
-export type AccountByIdVariant = "live" | "disabled" | "addressless"
+export type AccountByIdVariant = "live" | "disabled" | "addressless" | "named"
 
 /** A row of the by-address door: `disabled` is what the database decided at its own now(). */
 export interface AccountByEmailRow {
@@ -20,6 +20,7 @@ export interface AccountByEmailRow {
 export interface AccountByIdRow {
     id: string
     email: string | null
+    meta: Record<string, string>
     disabled: boolean
 }
 
@@ -36,5 +37,6 @@ export const accountByEmailRow = (variant: AccountByEmailVariant = "live"): Acco
 export const accountByIdRow = (variant: AccountByIdVariant = "live", id = "u-1"): AccountByIdRow => ({
     id,
     email: variant === "addressless" ? null : "a@example.test",
+    meta: variant === "named" ? { full_name: "Ada Lovelace", name: "Ada Lovelace" } : {},
     disabled: variant === "disabled",
 })

package/templates/be/skeleton/src/features/cli/seed/subs/run.cli.ts

@@ -3,15 +3,15 @@ import { DEFAULT_SEED_ENV, SeedRunnerService } from "@modules/platform/database"
 
 /** The options of `cli seed run`. */
 export interface SeedRunOptions {
-    /** The stack environment whose `.starcistacks/<env>/seeds` run. */
+    /** The stack environment whose `.starcistacks/<env>/seeds/sql` runs after `.starcistacks/seeds/sql`. */
     readonly env?: string
 }
 
 @SubCommand({
     name: "run",
-    description: "Run every seed file of a stack environment on the connection it names",
+    description: "Run the shared seed files, then those of a stack environment, each on the connection it names",
 })
-/** `cli seed run [--env <name>]`: seeds every connection of the back end from `.starcistacks/<env>/seeds` and logs what it ran. */
+/** `cli seed run [--env <name>]`: seeds every connection of the back end from `.starcistacks/seeds/sql`, then `.starcistacks/<env>/seeds/sql`, and logs what it ran. */
 export class RunSeedsCli extends CommandRunner {
     constructor(private readonly seeds: SeedRunnerService) {
         super()

package/templates/be/skeleton/src/modules/platform/database/database.sql.ts

@@ -38,7 +38,7 @@ function assertSqlIdent(_value: string): asserts _value is SqlIdent {
 {{> be/common/sql-ident.ts.partial}}
 
 /**
- * Brands the statements of one tracked seed file (`.starcistacks/<env>/seeds/<connection>-<name>.sql`) as SQL text. A seed file
+ * Brands the statements of one tracked seed file (`.starcistacks/seeds/sql/<connection>-<name>.sql` or `.starcistacks/<env>/seeds/sql/<connection>-<name>.sql`) as SQL text. A seed file
  * is source reviewed like a migration and run as written by the cli seed command; no value is ever spliced into it.
  */
 export const seedText = (text: string): SqlText => {

package/templates/be/skeleton/src/modules/platform/database/seed-connections.client.spec.ts

@@ -36,9 +36,10 @@ const file = (name: string, text: string): SeedFile => ({
 })
 
 describe("seedDirectoryOf", () => {
-    it("is the seeds folder of the environment under .starcistacks, relative to the app root", async () => {
+    it("is the SQL folder of the shared seed level or of an environment, relative to the app root", async () => {
         const client = await setup()
-        expect(client.seedDirectoryOf("dev")).toBe(join(".starcistacks", "dev", "seeds"))
+        expect(client.seedDirectoryOf()).toBe(join(".starcistacks", "seeds", "sql"))
+        expect(client.seedDirectoryOf("dev")).toBe(join(".starcistacks", "dev", "seeds", "sql"))
     })
 })
 

package/templates/be/skeleton/src/modules/platform/database/seed-connections.client.ts

@@ -27,8 +27,12 @@ export interface SeedReport {
     readonly unmatched: ReadonlyArray<string>
 }
 
-/** The seed directory of a stack environment, relative to the working directory of the run: the app root. */
-export const seedDirectoryOf = (env: string): string => join(".starcistacks", env, "seeds")
+/**
+ * The SQL seed folder of a seed level, relative to the working directory of the run (the app root): the shared level every environment runs
+ * first (`.starcistacks/seeds/sql`) when no environment is named, else the environment's own (`.starcistacks/<env>/seeds/sql`).
+ */
+export const seedDirectoryOf = (env?: string): string =>
+    env === undefined ? join(".starcistacks", "seeds", "sql") : join(".starcistacks", env, "seeds", "sql")
 
 /** Reads every `*.sql` file of the seed directory, sorted by name; a missing directory fails the run. */
 export const readSeedFiles = async (directory: string): Promise<ReadonlyArray<SeedFile>> => {

package/templates/be/skeleton/src/modules/platform/database/seed-runner.service.spec.ts

@@ -48,24 +48,28 @@ const build = async (
 }
 
 describe("SeedRunnerService", () => {
-    it("reads the seeds of the named environment, runs them on their connections and logs the report", async () => {
+    it("reads the shared seeds and then those of the named environment, runs them on their connections and logs the report", async () => {
         const primary = mock<ConnectionSource>()
         const { runner, logger, reader } = await build(
             () => primary,
-            () =>
-                Promise.resolve([
-                    file("primary-notes.sql", "INSERT INTO notes (body) VALUES ('a')"),
-                    file("legacy-users.sql", "INSERT INTO users DEFAULT VALUES"),
-                ]),
+            (directory) =>
+                Promise.resolve(
+                    directory === seedDirectoryOf()
+                        ? [file("primary-plans.sql", "INSERT INTO plans (code) VALUES ('free')")]
+                        : [
+                              file("primary-notes.sql", "INSERT INTO notes (body) VALUES ('a')"),
+                              file("legacy-users.sql", "INSERT INTO users DEFAULT VALUES"),
+                          ],
+                ),
         )
 
         await expect(runner.run("staging")).resolves.toBeUndefined()
 
-        expect(reader.read).toHaveBeenCalledWith(seedDirectoryOf("staging"))
-        expect(primary.query).toHaveBeenCalledWith("INSERT INTO notes (body) VALUES ('a')")
+        expect(reader.read.mock.calls).toEqual([[seedDirectoryOf()], [seedDirectoryOf("staging")]])
+        expect(primary.query.mock.calls).toEqual([["INSERT INTO plans (code) VALUES ('free')"], ["INSERT INTO notes (body) VALUES ('a')"]])
         expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.SeedsApplied, {
             env: "staging",
-            applied: { primary: ["primary-notes.sql"] },
+            applied: { primary: ["primary-plans.sql", "primary-notes.sql"] },
             unmatched: ["legacy-users.sql"],
         })
     })
@@ -78,6 +82,7 @@ describe("SeedRunnerService", () => {
 
         await expect(runner.run()).resolves.toBeUndefined()
 
+        expect(reader.read).toHaveBeenCalledWith(seedDirectoryOf())
         expect(reader.read).toHaveBeenCalledWith(seedDirectoryOf("dev"))
         expect(logger.info).toHaveBeenCalledWith(LoggingLogEvent.SeedsApplied, {
             env: "dev",

package/templates/be/skeleton/src/modules/platform/database/seed-runner.service.ts

@@ -7,7 +7,7 @@ import type { ConnectionOpener, SeedFileReader } from "./database.port"
 import { DEFAULT_SEED_ENV, seedConnections, seedDirectoryOf } from "./seed-connections.client"
 
 @Injectable()
-/** The one seed runner: reads the seed files of a stack environment, runs them on the connections they name and logs the report. */
+/** The one seed runner: reads the shared seed files and then those of a stack environment, runs them on the connections they name and logs the report. */
 export class SeedRunnerService {
     constructor(
         @InjectDatabaseOptions() private readonly options: DatabaseOptions,
@@ -16,9 +16,9 @@ export class SeedRunnerService {
         @InjectLogger() private readonly logger: Logger,
     ) {}
 
-    /** Reads the seed files of the environment (the dev seeds when none is named), runs them on their connections and logs the report. */
+    /** Reads the shared SQL seeds, then those of the environment (dev when none is named), runs them on their connections and logs the report. */
     async run(env: string = DEFAULT_SEED_ENV): Promise<void> {
-        const files = await this.reader.read(seedDirectoryOf(env))
+        const files = [...(await this.reader.read(seedDirectoryOf())), ...(await this.reader.read(seedDirectoryOf(env)))]
         const report = await seedConnections(this.options.connections, files, this.opener)
         this.logger.info(LoggingLogEvent.SeedsApplied, {
             env,

package/templates/be/skeleton-lite/src/modules/platform/database/seed-runner.service.ts

@@ -1,13 +1,22 @@
-import { readFile } from "node:fs/promises"
+import { readFile, readdir } from "node:fs/promises"
+import { join } from "node:path"
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import type { SqlText } from "./database.sql"
 import { InjectPrimaryEntityManager } from "./primary.decorators"
 
-const SEED_FILE = "db/seed.sql"
+/** The stack environment whose seed runs when `--env` is not given. */
+export const DEFAULT_SEED_ENV = "dev"
+
+/**
+ * The SQL seed folder of a seed level, relative to the app root the run starts from: the shared level every environment runs first
+ * (`.starcistacks/seeds/sql`) when no environment is named, else the environment's own (`.starcistacks/<env>/seeds/sql`).
+ */
+export const seedDirectoryOf = (env?: string): string =>
+    env === undefined ? join(".starcistacks", "seeds", "sql") : join(".starcistacks", env, "seeds", "sql")
 
 function assertSeedText(_text: string): asserts _text is SqlText {
-    // The brand is compile-time only; this function's caller reads the tracked seed file verbatim.
+    // The brand is compile-time only; this function's caller reads a tracked seed file verbatim.
 }
 
 const seedText = (text: string): SqlText => {
@@ -15,14 +24,30 @@ const seedText = (text: string): SqlText => {
     return text
 }
 
+/** The `*.sql` files of a seed folder in name order; a folder that is absent holds none. */
+const seedFilesOf = async (directory: string): Promise<ReadonlyArray<string>> => {
+    try {
+        const names = await readdir(directory)
+        return names.filter((name) => name.endsWith(".sql")).sort((a, b) => a.localeCompare(b)).map((name) => join(directory, name))
+    } catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") return []
+        throw error
+    }
+}
+
 @Injectable()
-/** Executes the one tracked seed through the shared least-privilege EntityManager. */
+/** Executes the tracked SQL seeds, the shared level and then the environment's own, through the shared least-privilege EntityManager. */
 export class SeedRunnerService {
     constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
 
-    /** Reads and executes the tracked seed when it contains at least one statement. */
-    async run(): Promise<void> {
-        const text = seedText(await readFile(SEED_FILE, "utf8"))
+    /** Runs every SQL seed of the shared level, then of the environment (dev when none is named), in name order; an empty file runs nothing. */
+    async run(env: string = DEFAULT_SEED_ENV): Promise<void> {
+        const files = [...(await seedFilesOf(seedDirectoryOf())), ...(await seedFilesOf(seedDirectoryOf(env)))]
+        await files.reduce<Promise<void>>((done, file) => done.then(() => this.apply(file)), Promise.resolve())
+    }
+
+    private async apply(file: string): Promise<void> {
+        const text = seedText(await readFile(file, "utf8"))
         if (text.trim() !== "") await this.entityManager.query(text)
     }
 }

package/templates/be/tool-config/jest.config.js

@@ -1,3 +1,3 @@
 module.exports = require("@starci/jest-preset").starciJestConfig({
-    coverage: {{jestCoverage}},
+    coverage: {{jestCoverage}},{{jestPackages}}
 })

package/templates/fe/auth-lite/apps/web/src/modules/auth/email-doors.ts

@@ -10,7 +10,10 @@ export type EmailDoorName = "signup" | "resend" | "confirm" | "forgot" | "reset"
 const doors = createAuthClient({ apiOrigin: () => apiUrl() })
 
 /** Calls one email door with its posted fields; answers its failure (the wire code and its kind), or undefined when the back end accepted it. */
-export const sendEmailDoor = async (door: EmailDoorName, body: Readonly<Record<string, string | undefined>>): Promise<AuthFailure | undefined> => {
+export const sendEmailDoor = async (
+    door: EmailDoorName,
+    body: Readonly<Record<string, string | undefined>>,
+): Promise<AuthFailure | undefined> => {
     const outcome = await doors.send(door, body)
     return outcome.success ? undefined : { code: outcome.error, kind: outcome.message, message: "" }
 }

package/templates/fe/skeleton-lite/apps/web/src/components/blocks/EmailDoorForm/component.tsx

@@ -11,6 +11,8 @@ export interface EmailDoorFormBaseProps {
     readonly props: {
         readonly title: string
         readonly description: string
+        /** The label of the optional full-name field, or undefined when the door takes none. */
+        readonly nameLabel: string | undefined
         /** The label of the email field, or undefined when the door takes none. */
         readonly emailLabel: string | undefined
         /** The label of the password field, or undefined when the door takes none. */
@@ -32,6 +34,7 @@ export const EmailDoorFormBase = (props: EmailDoorFormBaseProps) => (
         {props.props.doneMessage === undefined ? (
             <Form label={props.props.title} isPending={props.props.pending} onSubmit={props.on.submit}>
                 <Text>{props.props.description}</Text>
+                {props.props.nameLabel === undefined ? null : <Input id="email-door-name" name="name" label={props.props.nameLabel} kind="text" />}
                 {props.props.emailLabel === undefined ? null : <Input id="email-door-email" name="email" label={props.props.emailLabel} kind="email" isRequired />}
                 {props.props.passwordLabel === undefined ? null : <Input id="email-door-password" name="password" label={props.props.passwordLabel} kind="password" isRequired />}
                 {props.props.errorMessage === undefined ? null : <Text live="assertive">{props.props.errorMessage}</Text>}