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>
6.7 KiB
Implementation Plan: Continuous Integration Pipeline
Branch: 001-ci-pipeline | Date: 2026-08-21 | Spec: 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)
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)
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.