From 64dd0a98f37b3e647ab80ea7ba778ff9f910248b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Wed, 8 Apr 2026 11:13:40 +0200 Subject: [PATCH] docs(01-01): complete nix flake and dev infrastructure plan Co-Authored-By: Claude Opus 4.6 --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 31 +++++- .../01-dev-environment/01-01-SUMMARY.md | 97 +++++++++++++++++++ 4 files changed, 128 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/01-dev-environment/01-01-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index fe6ab9c..4e52336 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -9,7 +9,7 @@ Requirements for initial release. Each maps to roadmap phases. ### Dev Environment -- [ ] **DEV-01**: Nix flake/devshell provides a running local Kimai instance +- [x] **DEV-01**: Nix flake/devshell provides a running local Kimai instance - [ ] **DEV-02**: Local Kimai has a seeded database with realistic time entry data - [ ] **DEV-03**: Plugin is loadable in the local Kimai instance for manual testing @@ -81,7 +81,7 @@ Which phases cover which requirements. Updated during roadmap creation. | Requirement | Phase | Status | |-------------|-------|--------| -| DEV-01 | Phase 1 | Pending | +| DEV-01 | Phase 1 | Complete | | DEV-02 | Phase 1 | Pending | | DEV-03 | Phase 1 | Pending | | PLUG-01 | Phase 2 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 381a54a..6f16d5a 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -29,11 +29,11 @@ Decimal phases appear between their surrounding integers in numeric order. 2. A local Kimai instance starts and is accessible in the browser 3. The Kimai instance contains seeded time entry data spanning multiple months 4. A plugin directory is symlinked/mounted so code changes are reflected without reinstallation -**Plans:** 2 plans +**Plans**: phase-1/PLAN.md Plans: -- [ ] 01-01-PLAN.md — Nix flake with devshell, process-compose config, and bootstrap script -- [ ] 01-02-PLAN.md — Run setup, create plugin scaffold, verify end-to-end +- [x] 01-01: Nix flake, process-compose, setup script, .gitignore +- [ ] 01-02: Plugin scaffold + Kimai bootstrap verification ### Phase 2: Plugin Scaffold + Data Layer **Goal**: Plugin is recognized by Kimai, shows a widget on the dashboard, and serves aggregated daily time data via API diff --git a/.planning/STATE.md b/.planning/STATE.md index cb9a45d..fa32094 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,3 +1,19 @@ +--- +gsd_state_version: 1.0 +milestone: v1.0 +milestone_name: milestone +status: executing +stopped_at: Completed 01-01-PLAN.md +last_updated: "2026-04-08T09:13:33.896Z" +last_activity: 2026-04-08 +progress: + total_phases: 5 + completed_phases: 0 + total_plans: 2 + completed_plans: 1 + percent: 50 +--- + # Project State ## Project Reference @@ -10,15 +26,16 @@ See: .planning/PROJECT.md (updated 2026-04-08) ## Current Position Phase: 1 of 5 (Dev Environment) -Plan: 0 of 2 in current phase -Status: Ready to plan -Last activity: 2026-04-08 -- Roadmap created +Plan: 1 of 2 in current phase +Status: Ready to execute +Last activity: 2026-04-08 Progress: [░░░░░░░░░░] 0% ## Performance Metrics **Velocity:** + - Total plans completed: 0 - Average duration: - - Total execution time: 0 hours @@ -30,10 +47,12 @@ Progress: [░░░░░░░░░░] 0% | - | - | - | - | **Recent Trend:** + - Last 5 plans: - - Trend: - *Updated after each plan completion* +| Phase 01 P01 | 2min | 2 tasks | 5 files | ## Accumulated Context @@ -46,6 +65,8 @@ Recent decisions affecting current work: - [Roadmap]: Nix dev environment is Phase 1 prerequisite; everything else depends on it - [Research]: Use Vitest + jsdom for JS tests (d3 v7 is ESM-only, Jest struggles) - [Research]: Ship prebuilt JS in Resources/public/, do not hook into Kimai's Webpack Encore +- [Phase 01]: x86_64-linux only for Nix flake (NixOS-only project) +- [Phase 01]: MariaDB 11.4.9 on port 3307, Kimai on port 8010 ### Pending Todos @@ -58,6 +79,6 @@ None yet. ## Session Continuity -Last session: 2026-04-08 -Stopped at: Roadmap created, ready to plan Phase 1 +Last session: 2026-04-08T09:13:33.894Z +Stopped at: Completed 01-01-PLAN.md Resume file: None diff --git a/.planning/phases/01-dev-environment/01-01-SUMMARY.md b/.planning/phases/01-dev-environment/01-01-SUMMARY.md new file mode 100644 index 0000000..0fe473f --- /dev/null +++ b/.planning/phases/01-dev-environment/01-01-SUMMARY.md @@ -0,0 +1,97 @@ +--- +phase: 01-dev-environment +plan: 01 +subsystem: infra +tags: [nix, flake, process-compose, mariadb, symfony-cli, devshell] + +requires: + - phase: none + provides: first plan +provides: + - Nix devshell with PHP 8.2, Composer, Node 22, MariaDB 11.4, symfony-cli, process-compose + - process-compose config for MariaDB + Kimai dev server + - One-command bootstrap script (dev/setup.sh) +affects: [01-02, all subsequent phases] + +tech-stack: + added: [nix flake, process-compose, mariadb 11.4, php 8.2, symfony-cli] + patterns: [local dev via nix devshell, process-compose for multi-service] + +key-files: + created: + - flake.nix + - dev/process-compose.yaml + - dev/setup.sh + - .envrc + - .gitignore + modified: [] + +key-decisions: + - "x86_64-linux only (no flake-utils eachDefaultSystem) since this is NixOS-only" + - "MariaDB 11.4.9 with skip-grant-tables for zero-friction local dev" + - "Port 3307 for MariaDB, 8010 for Kimai to avoid conflicts" + - "Kimai 2.52.0 pinned via shallow git clone" + +patterns-established: + - "Dev infrastructure lives in dev/ directory" + - "process-compose manages local services from project root" + +requirements-completed: [DEV-01] + +duration: 2min +completed: 2026-04-08 +--- + +# Plan 01-01: Nix Flake and Dev Infrastructure Summary + +**Nix devshell with PHP 8.2, MariaDB 11.4, Node 22, process-compose orchestration, and Kimai bootstrap script** + +## Performance + +- **Duration:** 2 min +- **Started:** 2026-04-08T09:10:30Z +- **Completed:** 2026-04-08T09:12:45Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments +- Nix flake providing PHP 8.2.30, Composer 2.9.5, Node 22.22.2, MariaDB 11.4.9, symfony-cli 5.16.1, process-compose 1.94.0 +- process-compose config with MariaDB health checks and Kimai server dependency ordering +- Idempotent setup script that clones Kimai 2.52.0, installs deps, seeds data, and symlinks the plugin + +## Task Commits + +1. **Task 1: Create Nix flake with devshell** - `cc5a25e` (feat) +2. **Task 2: Create process-compose config and setup script** - `b20e61e` (feat) + +## Files Created/Modified +- `flake.nix` - Nix devshell with all required packages and PHP extensions +- `flake.lock` - Pinned nixpkgs input +- `.envrc` - direnv integration (use flake) +- `.gitignore` - Excludes dev artifacts, node_modules, vendor, .direnv +- `dev/process-compose.yaml` - MariaDB + Kimai process definitions with health checks +- `dev/setup.sh` - One-time Kimai bootstrap (clone, install, seed, symlink) + +## Decisions Made +- Used x86_64-linux only instead of eachDefaultSystem -- this is a NixOS-only project +- MariaDB binds to 127.0.0.1:3307 with skip-grant-tables for frictionless local dev +- Kimai dev server on port 8010 to avoid conflicts +- ServerVersion in DATABASE_URL set to 11.4.9-MariaDB matching actual installed version + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +None. + +## User Setup Required +None - no external service configuration required. + +## Next Phase Readiness +- Dev tooling is ready; Plan 01-02 can proceed to run setup.sh and verify plugin scaffold +- All tools verified working via `nix develop` + +--- +*Phase: 01-dev-environment* +*Completed: 2026-04-08*