@starci/hfs 1.0.1 → 2.0.0

package/templates/fe/skeleton-shared/packages/__family__-i18n/src/request.ts

@@ -0,0 +1,15 @@
+import { hasLocale } from "next-intl"
+import type { defineRouting } from "next-intl/routing"
+import { getRequestConfig } from "next-intl/server"
+
+type Routing = ReturnType<typeof defineRouting>
+
+/** The requested locale when the app serves it, else the default one. */
+export const resolveLocale = (routing: Routing, requested: string | undefined): string => (hasLocale(routing.locales, requested) ? requested : routing.defaultLocale)
+
+/** The request config of an app: the resolved locale and the catalog the app loads for it. */
+export const createRequestConfig = (routing: Routing, loadMessages: (locale: string) => Promise<Record<string, unknown>>) =>
+    getRequestConfig(async ({ requestLocale }) => {
+        const locale = resolveLocale(routing, await requestLocale)
+        return { locale, messages: await loadMessages(locale) }
+    })

package/templates/fe/skeleton-shared/packages/__family__-i18n/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@starci/tsconfig/next.json",
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules"]
+}

package/templates/fe/tool-config/eslint.config.mjs

@@ -0,0 +1,3 @@
+import { loadHfs, starciFeConfig } from "@starci/eslint-canon-fe"
+
+export default starciFeConfig({ hfs: loadHfs(import.meta.url) })

package/templates/fe/tool-config/prettierignore

@@ -0,0 +1,10 @@
+{{header}}
+node_modules/
+.next/
+dist/
+coverage/
+reports/
+.starci/
+package-lock.json
+**/__generated__/
+**/messages/**

package/templates/fe/tool-config/prettierrc

@@ -0,0 +1 @@
+"@starci/prettier-config"

package/templates/fe/tool-config/stylelint.config.mjs

@@ -0,0 +1,3 @@
+import { loadAppTokens, starciStylelintConfig } from "@starci/stylelint-canon"
+
+export default starciStylelintConfig({ appTokens: loadAppTokens(import.meta.url) })

package/templates/fe/tool-config/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@starci/tsconfig/next.json",
+  "exclude": ["node_modules"]
+}

package/templates/be/pre-commit

@@ -1,8 +0,0 @@
-# Commit gate: staged lint, types, the unit specs the staged files touch, work hygiene. Never e2e.
-npx lint-staged
-npm run typecheck
-staged=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.tsx' | grep -v -E '(^|/)e2e/|\.e2e-spec\.ts$' || true)
-if [ -n "$staged" ]; then
-  npx jest --selectProjects unit --passWithNoTests --findRelatedTests $staged
-fi
-npx hfs work-hygiene

package/templates/be/skeleton/apps/__app__/src/__app__.composition.spec.ts

@@ -1,31 +0,0 @@
-import { INestApplication } from "@nestjs/common"
-import { Test } from "@nestjs/testing"
-import request from "supertest"
-import { SERVER_OPTIONS } from "@modules/platform/config"
-import { Logger } from "@modules/platform/logging"
-import { AppModule } from "./app.module"
-
-describe("{{app}} composition", () => {
-    let app: INestApplication
-
-    beforeAll(async () => {
-        const moduleRef = await Test.createTestingModule({ imports: [AppModule.register({ server: { port: 3000 } })] }).compile()
-        app = moduleRef.createNestApplication()
-        await app.init()
-    })
-
-    afterAll(async () => {
-        await app.close()
-    })
-
-    it("boots the real AppModule and resolves its providers", () => {
-        expect(app.get(Logger)).toBeInstanceOf(Logger)
-        expect(app.get(SERVER_OPTIONS)).toEqual({ port: 3000 })
-    })
-
-    it("answers GET /health/live with the { status, info, error, details } shape", async () => {
-        const response = await request(app.getHttpServer()).get("/health/live")
-        expect(response.status).toBe(200)
-        expect(response.body).toEqual({ status: "ok", info: {}, error: {}, details: {} })
-    })
-})

package/templates/be/skeleton/src/features/system-health/transport/http/live.controller.spec.ts

@@ -1,13 +0,0 @@
-import { HealthCheckService } from "@nestjs/terminus"
-import { mock } from "@starci/jest-preset/mock"
-import { LiveController } from "./live.controller"
-
-describe("LiveController", () => {
-    it("runs Terminus with no indicator, so liveness never depends on a dependency", async () => {
-        const health = mock<HealthCheckService>()
-        const result = { status: "ok" as const, info: {}, error: {}, details: {} }
-        health.check.mockResolvedValue(result)
-        await expect(new LiveController(health).live()).resolves.toEqual(result)
-        expect(health.check).toHaveBeenCalledWith([])
-    })
-})

package/templates/be/skeleton/src/modules/platform/config/env-source.spec.ts

@@ -1,36 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { join } from "node:path"
-import { EnvSource } from "./env-source"
-import { ConfigError } from "./errors/config.error"
-
-describe("EnvSource", () => {
-    it("reads a key and treats an empty value as unset", () => {
-        const env = EnvSource.of({ PORT: "8080", EMPTY: "" })
-        expect(env.optional("PORT")).toBe("8080")
-        expect(env.optional("EMPTY")).toBeUndefined()
-        expect(env.optional("ABSENT")).toBeUndefined()
-    })
-
-    it("refuses a missing required key by naming it", () => {
-        const failure = () => EnvSource.of({}).required("DATABASE_URL")
-        expect(failure).toThrow(ConfigError)
-        expect(failure).toThrow("Configuration key DATABASE_URL is required and has no default.")
-    })
-
-    it("resolves <KEY>_FILE to the trimmed content of the file", () => {
-        const dir = mkdtempSync(join(tmpdir(), "env-source-"))
-        try {
-            const path = join(dir, "token")
-            writeFileSync(path, "value-from-file\n")
-            expect(EnvSource.of({ API_TOKEN_FILE: path }).required("API_TOKEN")).toBe("value-from-file")
-        } finally {
-            rmSync(dir, { recursive: true, force: true })
-        }
-    })
-
-    it("names the _FILE key, not a path or a value, when the file cannot be read", () => {
-        const failure = () => EnvSource.of({ API_TOKEN_FILE: join(tmpdir(), "no-such-dir", "token") }).optional("API_TOKEN")
-        expect(failure).toThrow("Configuration key API_TOKEN_FILE points at a file that cannot be read.")
-    })
-})

package/templates/be/skeleton/src/modules/platform/config/server.config.spec.ts

@@ -1,19 +0,0 @@
-import { EnvSource } from "./env-source"
-import { ConfigError } from "./errors/config.error"
-import { parseServerConfig } from "./server.config"
-
-describe("parseServerConfig", () => {
-    it("falls back to port 3000 when PORT is unset", () => {
-        expect(parseServerConfig(EnvSource.of({}))).toEqual({ port: 3000 })
-    })
-
-    it("accepts an integer PORT inside the TCP range", () => {
-        expect(parseServerConfig(EnvSource.of({ PORT: "8080" }))).toEqual({ port: 8080 })
-    })
-
-    it.each(["80a", "0", "70000", "1.5"])("refuses PORT=%s by naming the key only", (port) => {
-        const failure = () => parseServerConfig(EnvSource.of({ PORT: port }))
-        expect(failure).toThrow(ConfigError)
-        expect(failure).toThrow("Configuration key PORT does not hold a valid value.")
-    })
-})

package/templates/be/skeleton/src/modules/platform/errors/domain-error.spec.ts

@@ -1,15 +0,0 @@
-import { DomainError } from "./domain-error"
-
-class SampleError extends DomainError {}
-
-describe("DomainError", () => {
-    it("carries the code, the message and the cause, and is named after its subclass", () => {
-        const cause = new SyntaxError("bad input")
-        const error = new SampleError("SAMPLE_FAILED", "The sample failed.", { cause })
-        expect(error.code).toBe("SAMPLE_FAILED")
-        expect(error.message).toBe("The sample failed.")
-        expect(error.cause).toBe(cause)
-        expect(error.name).toBe("SampleError")
-        expect(error).toBeInstanceOf(Error)
-    })
-})

package/templates/be/skeleton/src/modules/platform/errors/error.filter.spec.ts

@@ -1,38 +0,0 @@
-import { ArgumentsHost, HttpException, HttpStatus } from "@nestjs/common"
-import { HttpArgumentsHost } from "@nestjs/common/interfaces"
-import { mock } from "@starci/jest-preset/mock"
-import type { Response } from "express"
-import { Logger, LogId } from "@modules/platform/logging"
-import { ErrorFilter } from "./error.filter"
-
-const arrange = () => {
-    const response = mock<Response>()
-    response.status.mockReturnValue(response)
-    const http = mock<HttpArgumentsHost>()
-    http.getResponse.mockReturnValue(response)
-    const host = mock<ArgumentsHost>()
-    host.switchToHttp.mockReturnValue(http)
-    const logger = mock<Logger>()
-    return { response, host, logger, filter: new ErrorFilter(logger) }
-}
-
-describe("ErrorFilter", () => {
-    it("answers an unknown failure with a 500 that names no detail, and logs it once", () => {
-        const { response, host, logger, filter } = arrange()
-        filter.catch(new TypeError("secret detail"), host)
-        expect(response.status).toHaveBeenCalledWith(HttpStatus.INTERNAL_SERVER_ERROR)
-        expect(response.json).toHaveBeenCalledWith({ code: "internal_error" })
-        expect(logger.error).toHaveBeenCalledTimes(1)
-        expect(logger.error).toHaveBeenCalledWith(LogId.RequestFailed, {
-            status: HttpStatus.INTERNAL_SERVER_ERROR,
-            failure: { name: "TypeError" },
-        })
-    })
-
-    it("keeps the status of a framework exception and answers with its status code only", () => {
-        const { response, host, filter } = arrange()
-        filter.catch(new HttpException("Not Found", HttpStatus.NOT_FOUND), host)
-        expect(response.status).toHaveBeenCalledWith(HttpStatus.NOT_FOUND)
-        expect(response.json).toHaveBeenCalledWith({ code: "http_404" })
-    })
-})

package/templates/be/skeleton/src/modules/platform/logging/json-logger.spec.ts

@@ -1,33 +0,0 @@
-import { Writable } from "node:stream"
-import { createJsonLogger } from "./json-logger"
-import { LogId } from "./log-id"
-
-const capture = () => {
-    const lines: string[] = []
-    const sink = new Writable({
-        write(chunk: Buffer, _encoding, done) {
-            lines.push(chunk.toString())
-            done()
-        },
-    })
-    return { lines, logger: createJsonLogger(sink) }
-}
-
-describe("createJsonLogger", () => {
-    it("writes one JSON line carrying the level, the enum identity, a timestamp and the payload", () => {
-        const { lines, logger } = capture()
-        logger.error(LogId.StartupFailed, { code: "CONFIG_KEY_MISSING" })
-        expect(lines).toHaveLength(1)
-        expect(lines[0].endsWith("\n")).toBe(true)
-        expect(JSON.parse(lines[0])).toMatchObject({ level: "error", id: "server.startup_failed", code: "CONFIG_KEY_MISSING" })
-        expect(JSON.parse(lines[0]).time).toEqual(expect.any(String))
-    })
-
-    it("maps every level to its own name", () => {
-        const { lines, logger } = capture()
-        logger.debug(LogId.ServerStarted)
-        logger.info(LogId.ServerStarted)
-        logger.warn(LogId.ServerStarted)
-        expect(lines.map((line) => JSON.parse(line).level)).toEqual(["debug", "info", "warn"])
-    })
-})

package/templates/be/skeleton/src/modules/platform/logging/json-logger.ts

@@ -1,35 +0,0 @@
-import type { Writable } from "node:stream"
-import type { LogId } from "./log-id"
-import { Logger, LogPayload } from "./logger.port"
-
-type Level = "debug" | "info" | "warn" | "error"
-
-/** The default adapter: one JSON object per line on a stream, so a collector reads it without parsing prose. */
-class JsonLogger extends Logger {
-    constructor(private readonly sink: Writable) {
-        super()
-    }
-
-    debug(id: LogId, payload?: LogPayload): void {
-        this.write("debug", id, payload)
-    }
-
-    info(id: LogId, payload?: LogPayload): void {
-        this.write("info", id, payload)
-    }
-
-    warn(id: LogId, payload?: LogPayload): void {
-        this.write("warn", id, payload)
-    }
-
-    error(id: LogId, payload?: LogPayload): void {
-        this.write("error", id, payload)
-    }
-
-    private write(level: Level, id: LogId, payload?: LogPayload): void {
-        this.sink.write(`${JSON.stringify({ level, id, time: new Date().toISOString(), ...payload })}\n`)
-    }
-}
-
-/** Builds the JSON logger; `sink` is stdout unless a caller (a spec, a process manager) supplies its own stream. */
-export const createJsonLogger = (sink: Writable = process.stdout): Logger => new JsonLogger(sink)

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

@@ -1,9 +0,0 @@
-/** Every log line is named by a member of this enum, so a line can be found from the code that wrote it. */
-export enum LogId {
-    /** The HTTP listener is bound and the app serves requests. */
-    ServerStarted = "server.started",
-    /** The app failed before it could serve; the process exits non-zero. */
-    StartupFailed = "server.startup_failed",
-    /** A request ended in a failure the app's filter answered. */
-    RequestFailed = "http.request_failed",
-}

package/templates/be/skeleton/src/modules/platform/logging/logger.port.ts

@@ -1,19 +0,0 @@
-import type { LogId } from "./log-id"
-
-/** The structured data of one log line; values are plain data, never a request, a token or a secret. */
-export type LogPayload = Readonly<Record<string, unknown>>
-
-/** The logging port: capabilities log through it with an enum identity and a structured payload, never `console`. */
-export abstract class Logger {
-    /** Detail for people debugging one environment. */
-    abstract debug(id: LogId, payload?: LogPayload): void
-
-    /** A normal event worth keeping. */
-    abstract info(id: LogId, payload?: LogPayload): void
-
-    /** Something unexpected the app recovered from. */
-    abstract warn(id: LogId, payload?: LogPayload): void
-
-    /** A failure the app could not recover from in place. */
-    abstract error(id: LogId, payload?: LogPayload): void
-}

package/templates/common/codecov.yml

@@ -1,13 +0,0 @@
-coverage:
-  status:
-    project:
-      default:
-        target: 80%
-        informational: false
-    patch:
-      default:
-        target: 90%
-        informational: false
-comment: false
-ignore:
-  - {{codecovIgnore}}

package/templates/common/pre-push

@@ -1,5 +0,0 @@
-# Push gate: types, lint, the architecture check on the owners this push touches, unit specs affected since main. Never e2e.
-npm run typecheck
-npm run lint:check
-npx hfs check --fast
-npm run test:affected

package/templates/fe/e2e.yml

@@ -1,22 +0,0 @@
-# End-to-end runs are manual: nothing triggers this workflow but a person dispatching it.
-name: e2e
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  e2e:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: {{nodeMajor}}
-          cache: npm
-      - run: npm ci
-      - run: npx playwright install --with-deps chromium
-      - name: e2e
-        run: npm run test:e2e

package/templates/fe/pre-commit

@@ -1,7 +0,0 @@
-# Commit gate: staged lint, types, the unit specs the staged files touch. Never e2e.
-npx lint-staged
-npm run typecheck
-staged=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.tsx' | grep -v -E '(^|/)e2e/|\.e2e-spec\.ts$' || true)
-if [ -n "$staged" ]; then
-  npx vitest related --run --passWithNoTests $staged
-fi

package/templates/fe/skeleton/apps/__app__/src/app/health/live/route.spec.ts

@@ -1,10 +0,0 @@
-import { describe, expect, it } from "vitest"
-import { GET } from "./route"
-
-describe("GET /health/live", () => {
-    it("answers the { status, info, error, details } shape from process-local state", async () => {
-        const response = GET()
-        expect(response.status).toBe(200)
-        await expect(response.json()).resolves.toEqual({ status: "ok", info: {}, error: {}, details: {} })
-    })
-})

package/templates/fe/skeleton/apps/__app__/src/modules/i18n/messages.spec.ts

@@ -1,27 +0,0 @@
-import { describe, expect, it } from "vitest"
-import vi from "./messages/vi.json"
-
-const leaves = (value: unknown, path = ""): string[] =>
-    typeof value === "object" && value !== null
-        ? Object.entries(value).flatMap(([key, child]) => leaves(child, path ? `${path}.${key}` : key))
-        : [path]
-
-const valueAt = (path: string): unknown => path.split(".").reduce<unknown>((node, key) => (node as Record<string, unknown>)[key], vi)
-
-describe("messages/vi.json", () => {
-    it("carries the strings the error, not-found and home routes render", () => {
-        expect(leaves(vi).sort()).toEqual([
-            "errors.global.retry",
-            "errors.global.title",
-            "errors.page.retry",
-            "errors.page.title",
-            "home.title",
-            "notFound.home",
-            "notFound.title",
-        ])
-    })
-
-    it("has no empty string", () => {
-        for (const path of leaves(vi)) expect(valueAt(path)).not.toBe("")
-    })
-})

package/templates/fe/skeleton/apps/__app__/src/modules/i18n/routing.spec.ts

@@ -1,10 +0,0 @@
-import { describe, expect, it } from "vitest"
-import { routing } from "./routing"
-
-describe("routing", () => {
-    it("serves vi by default, without a prefix", () => {
-        expect(routing.defaultLocale).toBe("vi")
-        expect(routing.localePrefix).toBe("as-needed")
-        expect(routing.locales).toContain("vi")
-    })
-})

package/templates/fe/sonar-project.properties

@@ -1,11 +0,0 @@
-sonar.projectKey={{sonarKey}}
-sonar.host.url=https://sonar.starci.org
-sonar.sourceEncoding=UTF-8
-sonar.sources=apps
-sonar.tests=apps
-sonar.exclusions={{sonarExclusions}}
-sonar.test.inclusions=**/*.spec.ts,**/*.spec.tsx
-sonar.coverage.exclusions={{sonarCoverageExclusions}}
-sonar.javascript.lcov.reportPaths=coverage/lcov.info
-sonar.typescript.tsconfigPaths={{tsconfigPaths}}
-sonar.nodejs.maxspace=8192