136 lines
9.4 KiB
Markdown
136 lines
9.4 KiB
Markdown
# Boilerplate Readiness
|
|
|
|
This page enumerates the verification gates that protect the boilerplate's
|
|
"safe to fork and build on" contract. The default CI lane is asserted by
|
|
`.gitea/workflows/ci.yml`; heavier gates such as coverage, Lighthouse,
|
|
Storybook, a11y, and deploy verification may live in dedicated workflow files.
|
|
Failing a required gate blocks the PR or deployment lane that owns it — there
|
|
is no silent override mode.
|
|
|
|
## How to read this page
|
|
|
|
Each section names a gate, what it enforces, the canonical command, and the
|
|
file(s) that contain the contract. Gates marked **anti-regression** keep the
|
|
current floor; they only allow improvements, never regressions. Gates marked
|
|
**hard contract** assert structural invariants that must always hold.
|
|
|
|
## Onboarding & branding
|
|
|
|
| Gate | Contract | Command |
|
|
| --- | --- | --- |
|
|
| Brand env layer (hard) | All user-facing brand strings are overridable via `BRAND_*` env vars in `packages/config/src/catalog.ts`. `packages/brand/src/env.ts` is the source-of-truth loader. | `pnpm --filter @hivegrid/brand test` |
|
|
| Infra-host parametrization (hard) | Gitea runner label, registry host, image prefix, DB user/name read from `scripts/infra-config.mjs` with `HIVEGRID_*` env overrides — forks can sed-replace strings and set vars without rewriting `verify-gitea-*-workflow.mjs`. | `pnpm run verify:gitea-ci-workflow && pnpm run verify:deploy-workflow` |
|
|
| `.env.example` drift (hard) | Every key in `.env.{example,local.example,production.example,fly.example,test}` exists in the catalog. | `pnpm exec vitest run packages/config/src/env-examples.test.ts` |
|
|
|
|
## Internationalization
|
|
|
|
| Gate | Contract | Command |
|
|
| --- | --- | --- |
|
|
| DE/EN namespace parity (hard) | All registered `i18nNamespaces` stay in lockstep across `de` and `en`, including app, auth, billing, CRM, settings, email marketing, mail, and error namespaces. | `pnpm run verify:i18n` |
|
|
| Hardcoded user-facing strings (anti-regression) | `brand-literal`, `jsx-text`, `user-facing-prop-literal`, and `user-facing-response-literal` counts may only decrease over the ratcheted baseline; current zero-floor categories must stay at zero. | `node scripts/verify-hardcoded-strings.mjs` |
|
|
| RTL/direction (hard) | `getDirection(locale)` covers known RTL languages; `isRTL` matches. | `pnpm --filter @hivegrid/i18n test` |
|
|
| Mail templates (hard) | `renderTransactionalEmail(template, props)` (React-Email) renders subject + body for every supported template. Host-app translator hooks are reserved for a future i18n pass; templates emit English copy directly. | `pnpm --filter @hivegrid/mail test` |
|
|
|
|
## Security
|
|
|
|
| Gate | Contract | Command |
|
|
| --- | --- | --- |
|
|
| Secret scanning (hard) | 10 secret-shaped patterns (GitHub PAT, AWS, Legacy-Provider `sk_live_*`, Slack, PEM, JWT, generic) scanned across `apps/packages/scripts/prisma/docs/`. Allowlist for `.env.example` variants and test fixtures. | `pnpm run verify:secrets` |
|
|
| CSRF inventory (hard) | Every mutating `POST/PATCH/DELETE` route is classified in `docs/security/csrf-inventory.md`. | `pnpm exec vitest run apps/api/src/csrf-inventory.test.ts apps/web/app/utils/session-csrf-sweep.test.ts` |
|
|
| Route access inventory (hard) | Every API route has an access class (`tenant-api-key`, `service-token`, `public-health`, …) documented + matching OpenAPI security. | `pnpm run verify:api-inventory && pnpm run verify:openapi-security` |
|
|
| Tenant isolation (hard) | 1115 lines of runtime tests in `apps/api/src/isolation/` + `apps/web/app/test/isolation/` exercise cross-tenant mutations and assert 403/401. | `pnpm exec vitest run apps/api/src/isolation apps/web/app/test/isolation` |
|
|
| Permission matrix (hard) | Role/permission seed is the source-of-truth, docs and tests stay aligned. | `pnpm run verify:permission-matrix` |
|
|
| Auth error envelope (hard) | Auth middleware throws `{ error: { code, messageKey } }` envelopes, never free strings. | `pnpm exec vitest run apps/web/app/utils/loaders.middleware.test.ts` |
|
|
| STRIDE threat model (doc) | `docs/security/threat-model.md` lists Spoofing/Tampering/Repudiation/Information-disclosure/DoS/Elevation threats and links each to a gate. | (review) |
|
|
|
|
## Quality & code hygiene
|
|
|
|
| Gate | Contract | Command |
|
|
| --- | --- | --- |
|
|
| Phase-C boundaries (hard) | UI packages cannot import `@hivegrid/db`; runtime separation enforced. | `pnpm run verify:phase-c-boundaries` |
|
|
| ESLint baseline (anti-regression) | `eslint-disable`, `@ts-ignore`, `@ts-expect-error` counts only decrease from the ratcheted baseline. | `pnpm run verify:eslint-baseline` |
|
|
| Test density (anti-regression) | 12 workspace dirs maintain a minimum test-file-per-source-file ratio. | `pnpm run verify:test-density` |
|
|
| Test coverage (anti-regression) | `scripts/coverage-targets.json` defines active per-path thresholds and release-floor sprint targets; `@vitest/coverage-v8` emits `coverage-summary.json` for the gate. The latest backlog has no critical-path positive gaps. | `pnpm run verify:test-coverage` |
|
|
| Hot-swap mock visual (hard) | `verify:ui-visual` + `test:hot-swap` keep mock-driven surface stable. | `pnpm run verify:ui-visual && pnpm run test:hot-swap` |
|
|
|
|
## Operations & runtime
|
|
|
|
| Gate | Contract | Command |
|
|
| --- | --- | --- |
|
|
| Docker non-root (hard) | All runtime stages (`web`, `api`, `worker`) drop to `USER node` before `CMD/ENTRYPOINT`. | `pnpm run verify:docker-non-root` |
|
|
| Docker baseline (hard) | Dockerfile stage layout + healthchecks per stage stable. | `pnpm run verify:docker-baseline` |
|
|
| Bundle-size budget (anti-regression) | JS chunks (root/route/vendor/other) and CSS stay under the +20% headroom budget from current state. | `pnpm run verify:bundle-size` |
|
|
| Production seed artifact (hard) | The compiled production seed bundle is present and idempotent. | `pnpm run verify:production-seed-artifact` |
|
|
| Migration rollback drill (manual) | `scripts/drill-migration-rollback.sh` replays forward chain + seed against an ephemeral postgres and asserts a re-apply is a no-op. | `./scripts/drill-migration-rollback.sh` |
|
|
| Health baseline (hard) | `/healthz` and `/readyz` shapes are stable. | `pnpm run verify:health-baseline` |
|
|
|
|
## Supply chain
|
|
|
|
| Mechanism | Coverage | File |
|
|
| --- | --- | --- |
|
|
| Dependabot | weekly npm (grouped: ai-providers / react-stack / test / lint), weekly github-actions, monthly docker | `.github/dependabot.yml` |
|
|
| Renovate (Gitea) | same group config for self-hosted Gitea forks | `.gitea/renovate.json` |
|
|
| SBOM | `scripts/generate-sbom.mjs` writes `sbom-pnpm.json` during the build stage; every runtime image carries the SBOM at `/myapp/sbom-pnpm.json` and labels it via `org.opencontainers.image.sbom`. | `Dockerfile`, `scripts/generate-sbom.mjs` |
|
|
| Production seed bootstrap | `SEED_ADMIN_EMAIL`/`SEED_ADMIN_PASSWORD` required for prod seed; rejects the local default. | `packages/db/src/production-seed.server.ts` |
|
|
|
|
## Documentation
|
|
|
|
| Doc | Purpose |
|
|
| --- | --- |
|
|
| `docs/quickstart.md` | Install-to-first-local-run path |
|
|
| `docs/new-project.md` | Adapting the boilerplate to a new project |
|
|
| `docs/deployment-porting.md` | Gitea infra-string fork procedure |
|
|
| `docs/security/threat-model.md` | STRIDE per subsystem with mitigation links |
|
|
| `docs/operations/database-rollback.md` | Forward-only rollback runbook + drill script reference |
|
|
| `docs/ui-inventory/hot-swap-status.md` | UI registry activation state |
|
|
|
|
## Optional gates (opt-in)
|
|
|
|
Some verification surfaces require a deployed environment or an external
|
|
binary and are therefore not wired into the default CI lane. They SKIP
|
|
cleanly (exit 0) when their prerequisites are missing, so they are safe to
|
|
run locally or to enable in a downstream pipeline.
|
|
|
|
| Gate | Contract | Command | Prerequisites |
|
|
| --- | --- | --- | --- |
|
|
| Load tests (opt-in) | k6 scripts in `tests/load/` exercise login, tenant-scoped read, and tenant-scoped mutating paths against a deployed target. Thresholds: `http_req_failed: rate<0.05`, login `p(95)<400ms` / `p(99)<800ms`, read `p(99)<300ms` and `>200 req/s`, mutating `p(99)<600ms`. | `pnpm run verify:load` | `k6` binary on PATH (`brew install k6` or <https://k6.io/docs/getting-started/installation/>); reachable `K6_TARGET_URL` (default `http://localhost:3000`); `LOAD_TENANT_API_KEY` for the read/mutating scripts. See `tests/load/README.md` for the full env contract. |
|
|
|
|
To activate the load suite in a release lane, set `K6_TARGET_URL` and
|
|
`LOAD_TENANT_API_KEY` for that lane and add `pnpm run verify:load` to the
|
|
job. The runner SKIPs when k6 is missing or the target is offline — the
|
|
gate never blocks a CI run on environments that cannot satisfy its
|
|
prerequisites.
|
|
|
|
## Composite "all gates" run
|
|
|
|
There is no single mega-script — gates are intentionally separate so CI can
|
|
parallelise. The canonical CI order is asserted by
|
|
`verify:gitea-ci-workflow` against `.gitea/workflows/ci.yml`. To dry-run the
|
|
local subset:
|
|
|
|
```sh
|
|
pnpm run verify:ci-baseline
|
|
pnpm run verify:env-drift
|
|
pnpm run verify:health-baseline
|
|
pnpm run verify:i18n
|
|
pnpm run verify:hardcoded-strings
|
|
pnpm run verify:phase-c-boundaries
|
|
pnpm run verify:api-inventory
|
|
pnpm run verify:openapi-security
|
|
pnpm run verify:tenant-isolation-report
|
|
pnpm run verify:docker-baseline
|
|
pnpm run verify:docker-non-root
|
|
pnpm run verify:secrets
|
|
pnpm run verify:eslint-baseline
|
|
pnpm run verify:test-density
|
|
pnpm run verify:bundle-size
|
|
pnpm run verify:test-coverage
|
|
pnpm typecheck
|
|
pnpm lint
|
|
pnpm test
|
|
```
|
|
|
|
Any failure here is a CI failure. Anti-regression gates lock the current
|
|
ratchet; hard contracts assert immutable structural invariants. Adopt and
|
|
extend gates rather than disable them.
|