Phase 4 PR Specs — Env/Config + Scripts/Build/Test + Docs Hygiene

Last Updated: 2026-02-28
Content-Type: How-to (implementation-ready PR specs)
Audience: Engineering

---

Goal of Phase 4

Make the repository reproducible and onboarding-safe by standardizing:

• env loading + validation (single source of truth)
• scripts/build (one blessed path)
• tests (predictable runner strategy)
• docs/setup (no references to untracked or secret-like files)

---

PR4.1 — Typed env module + early validation + forbid service-local dotenv

Why (problem)

Env is currently loaded and consumed in multiple places:

• backend/src/server.ts calls validateEnv() after importing modules that already read env.
• backend/src/config/database.ts calls dotenv.config() internally.
• backend/src/services/embedding.service.ts calls dotenv.config() internally.
• Many modules read process.env.* directly (DB pool flags, feature flags), bypassing validation.

Standardization target

1. Env is loaded once.
2. Env is validated once, before other modules consume it.
3. Modules import typed env object rather than using process.env directly.

Implementation plan

1. Add backend/src/config/env.ts
   • calls dotenv.config() once
   • calls schema validation (env.validation.ts) and exports env
2. Update server.ts startup order so env is validated before importing:
   • database module
   • app module
   • any services that read env on import
3. Remove dotenv.config() calls from:
   • backend/src/config/database.ts
   • backend/src/services/embedding.service.ts
4. Incrementally replace direct process.env.* reads with env.*.

Acceptance criteria

• Running backend with missing required env fails early with clear validation output.
• No module performs dotenv.config() besides the env module.

Primary files

• backend/src/config/env.ts (new)
• backend/src/config/env.validation.ts
• backend/src/server.ts
• backend/src/config/database.ts
• backend/src/services/embedding.service.ts

---

PR4.2 — Replace “env copy” committed files with .env.example templates

Why (problem)

Repo currently tracks env-like files named “.env copy ...”, which:

• are not covered by .gitignore patterns for .env / .env.*
• can accidentally contain secrets
• are referenced by SETUP-GUIDE.md, reinforcing the pattern

Standardization target

• Only commit .env.example (and similar explicitly safe templates).
• Setup guide references .env.example only.
• .gitignore defends against future “env copy” variants.

Implementation plan

1. Replace:
   • backend/.env copy backend → backend/.env.example
   • aso-portal/.env copy - aso-portal → aso-portal/.env.example
   • (and any other “env copy” variants in the repo)
2. Update SETUP-GUIDE.md:
   • fix the cd ${Extracted_Zip_Folder}t typo
   • update env steps to: copy .env.example → .env
3. Update .gitignore to ignore common “copy” patterns (defense in depth):
   • e.g. *.env copy*, *.env.copy*, or a safer explicit list of known variants

Acceptance criteria

• No committed “env copy” files remain.
• Setup guide on a fresh clone is coherent and standard.

Primary files

• SETUP-GUIDE.md
• .gitignore
• .env.example files in each app folder

---

PR4.3 — One blessed build path; fail fast on TypeScript errors

Why (problem)

Backend has duplicate scripts:

• build1 uses scripts/build.js which continues even if tsc fails.
• build uses tsc && copy-assets.

Continuing after TS failure can produce broken deploy artifacts.

Standardization target

• Only one build command (npm run build) is supported.
• Build fails on TS errors.

Implementation plan

1. Remove or alias build1/copy-assets1 to the canonical scripts.
2. Retire or harden backend/scripts/build.js so it fails on non-zero tsc exit.

Acceptance criteria

• npm run build fails when TypeScript fails.
• No alternative build commands are used in docs/deploy instructions.

Primary files

• backend/package.json
• backend/scripts/build.js

---

PR4.4 — Normalize test runner strategy and npm scripts

Why (problem)

Tests are fragmented:

• Jest is limited to *.jest.test.ts
• Mocha/Chai exists under backend/tests/**
• many tests are invoked via ts-node scripts (not part of npm test)

Standardization options

Option A (recommended): Jest-only

• Migrate Mocha/Chai tests to Jest.
• Use a single naming convention (e.g. *.test.ts).

Option B: Keep both, hard-separated

• Create explicit commands:
  • test:jest
  • test:mocha
• Separate directories:
  • backend/tests/jest/**
  • backend/tests/mocha/**
• Ensure CI runs both (or intentionally only one).

Acceptance criteria

• A new contributor can run npm test and get a meaningful result without hunting for hidden commands.
• Test tree layout makes runner boundaries obvious.

Primary files

• backend/jest.config.cjs
• backend/package.json
• test directories under backend/tests/**

---

Docs hygiene add-on (can be PR4.2 or PR5.3 depending on scope)

1. Remove or update references to ignored sources like docs/project_status.md if docs/ remains gitignored.
2. Add ignores for docs build caches (e.g. docs-site/.vitepress/cache/**) to prevent accidental commits.