saqib mirandClaude Sonnet 5
414f336704
/speckit-specify + /speckit-plan output for 001-ci-pipeline: feature spec with 2 user stories and 10 functional requirements, requirements quality checklist, implementation plan with constitution gate check, Phase 0 research (6 decisions incl. secrets-from-credentials-store), Phase 1 data model, pipeline stage contract, and a 5-scenario quickstart validation guide. No Jenkinsfile yet — that's the implementation step after /speckit-tasks. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
114 lines
6.7 KiB
Markdown
114 lines
6.7 KiB
Markdown
# Implementation Plan: Continuous Integration Pipeline
|
|
|
|
**Branch**: `001-ci-pipeline` | **Date**: 2026-08-21 | **Spec**: [spec.md](./spec.md)
|
|
|
|
**Input**: Feature specification from `specs/001-ci-pipeline/spec.md`
|
|
|
|
## Summary
|
|
|
|
Add an automated CI/CD pipeline (Jenkins, per the constitution's Technology & Platform
|
|
Constraints and `docs/09-testing-observability-cicd.md` §3) that runs on every proposed change:
|
|
checkout → install → environment validation → typecheck → lint → format check → unit test →
|
|
integration test → E2E test → build → Docker build → publish → deploy. It wires together
|
|
quality gates and npm scripts that already exist in the repo — it does not introduce new checks,
|
|
only automates and sequences the ones already defined in `package.json`.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Groovy (Jenkins declarative pipeline) driving Node.js 20 (per `engines` in
|
|
`package.json`) / TypeScript 5.4 build steps.
|
|
|
|
**Primary Dependencies**: Jenkins (declarative pipeline, `Jenkinsfile` at repo root), Docker /
|
|
Docker Compose (already present as `docker-compose.development.yml`, `docker-compose.test.yml`,
|
|
`docker-compose.prod.yml`), the existing npm scripts (`typecheck`, `lint`, `format:check`,
|
|
`test:unit`, `test:integration`, `test:e2e`, `build`), Prisma CLI (`prisma:generate`,
|
|
`prisma:deploy`) for schema/client generation before build.
|
|
|
|
**Storage**: N/A for the pipeline itself — it depends on ephemeral PostgreSQL/Redis instances
|
|
(brought up via `docker-compose.test.yml`) to run integration/E2E tests against.
|
|
|
|
**Testing**: Vitest (`test:unit`, `test:integration`, `test:e2e`) — already configured; the
|
|
pipeline invokes these, it does not define new test tooling.
|
|
|
|
**Target Platform**: Linux CI agent (Jenkins), producing a Linux container image; deploy targets
|
|
are the `development`, `test`, and `prod` environments already defined via
|
|
`docker-compose.*.yml` + `.env.*` files.
|
|
|
|
**Project Type**: Backend service (single Fastify modular monolith) — this feature only adds
|
|
CI/CD tooling around the existing `supporthub-api` project; no new application code paths.
|
|
|
|
**Performance Goals**: N/A (process/tooling feature, not a runtime performance concern). Informal
|
|
target: full validate→build pipeline completes in a time that keeps PR feedback fast (not
|
|
formally measured by this feature).
|
|
|
|
**Constraints**: MUST NOT read production secrets from the repository (constitution Principle
|
|
governance + FR-008); MUST fail fast on missing/invalid environment configuration before running
|
|
expensive test stages; MUST isolate concurrent runs (FR-009) — Jenkins agent workspace-per-build
|
|
satisfies this natively.
|
|
|
|
**Scale/Scope**: One `Jenkinsfile` at repo root for `supporthub-api`. Out of scope: the sibling
|
|
`supporthub-web` frontend pipeline (separate repo/feature if/when needed), flaky-test
|
|
retry/quarantine policy (explicitly deferred in spec.md Edge Cases).
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
| Principle / Section | Check | Result |
|
|
|---|---|---|
|
|
| III. Layered Architecture With Enforced Module Boundaries | This feature adds no application code — no controllers/services/repositories touched. | PASS — N/A |
|
|
| VI. Durable Audit & History | Not directly applicable to CI itself; pipeline run history is retained by Jenkins (build history), satisfying FR-010's "visible without server/log access" via the Jenkins UI. | PASS |
|
|
| VII. Concurrency-Safe, Durable Job Handling | Not applicable — no SLA timers or job handlers introduced. | PASS — N/A |
|
|
| Technology & Platform Constraints | Constitution names Jenkins explicitly for CI/CD; this plan uses Jenkins declarative pipeline, not an alternative CI tool. | PASS |
|
|
| Testing, Observability & CI/CD Gates | Constitution requires exactly this stage order: checkout → install → env validation → typecheck → lint → format check → unit → integration → E2E → build → Docker build → publish → deploy. Plan matches verbatim. | PASS |
|
|
| Governance ("secrets never committed") | Plan requires Jenkins-managed credentials store for all env/prod secrets. Verified in Phase 0 (research.md): `.env.*` files were found committed with real dev credentials, fixed out-of-band (commit `2093898` — untracked, `.env.example` added); pipeline generates `.env.<target>` from Jenkins credentials at runtime, never reads the repo copy. | PASS (post-design) |
|
|
|
|
No violations requiring Complexity Tracking justification.
|
|
|
|
## Post-Design Constitution Re-check
|
|
|
|
All gates above remain PASS after Phase 1 design (data-model.md, contracts/, quickstart.md). No
|
|
new violations introduced — this feature adds zero application code, only pipeline
|
|
configuration, so Principles I, II, IV, V, VIII (identity boundary, config-over-hardcode, AI
|
|
policy, evidence-based verification, ticket/problem separation) are not applicable and were
|
|
correctly excluded from the gate table above.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/001-ci-pipeline/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0 output
|
|
├── data-model.md # Phase 1 output (minimal — see note)
|
|
├── quickstart.md # Phase 1 output
|
|
├── contracts/ # Phase 1 output (pipeline stage contract)
|
|
└── tasks.md # Phase 2 output (/speckit-tasks — not created here)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
supporthub-api/
|
|
├── Jenkinsfile # NEW — declarative pipeline, stages per Constitution
|
|
├── package.json # EXISTING — source of truth for script names each stage calls
|
|
├── docker-compose.development.yml # EXISTING — used for local/dev parity, not directly by CI
|
|
├── docker-compose.test.yml # EXISTING — brings up ephemeral Postgres/Redis for CI test stages
|
|
├── docker-compose.prod.yml # EXISTING — referenced by the deploy stage for prod rollout
|
|
├── .env.development / .env.test / .env.prod # EXISTING — env files; secrets injected by Jenkins
|
|
│ credentials at pipeline runtime, not read from repo
|
|
└── scripts/
|
|
└── check-architecture.ts # EXISTING — architecture boundary check; candidate addition to
|
|
the lint/typecheck stage (confirmed in research.md)
|
|
```
|
|
|
|
**Structure Decision**: Single project (this is the existing `supporthub-api` backend). No new
|
|
application source directories are introduced — the only new artifact is a root-level
|
|
`Jenkinsfile` plus its supporting CI documentation under `specs/001-ci-pipeline/`. The sibling
|
|
`supporthub-web` repository is explicitly out of scope (see Technical Context → Scale/Scope).
|
|
|
|
## Complexity Tracking
|
|
|
|
*No constitution violations — table intentionally omitted.*
|