186 lines
7 KiB
Markdown
186 lines
7 KiB
Markdown
---
|
|
phase: 01-dev-environment
|
|
plan: 02
|
|
type: execute
|
|
wave: 2
|
|
depends_on:
|
|
- 01-01
|
|
files_modified:
|
|
- KimaiHeatmapBundle.php
|
|
- composer.json
|
|
autonomous: false
|
|
requirements:
|
|
- DEV-02
|
|
- DEV-03
|
|
must_haves:
|
|
truths:
|
|
- "Running dev/setup.sh bootstraps a working Kimai instance with seeded timesheet data"
|
|
- "The Kimai instance has timesheet entries spanning multiple months"
|
|
- "Kimai recognizes KimaiHeatmapBundle as a loaded plugin"
|
|
- "The Kimai dashboard is accessible in the browser at localhost:8010"
|
|
artifacts:
|
|
- path: "KimaiHeatmapBundle.php"
|
|
provides: "Symfony bundle class implementing Kimai PluginInterface"
|
|
contains: "implements PluginInterface"
|
|
- path: "composer.json"
|
|
provides: "Plugin metadata with kimai-plugin type and autoload config"
|
|
contains: "kimai-plugin"
|
|
key_links:
|
|
- from: "dev/kimai/var/plugins/KimaiHeatmapBundle"
|
|
to: "project root"
|
|
via: "symlink"
|
|
pattern: "KimaiHeatmapBundle"
|
|
- from: "KimaiHeatmapBundle.php"
|
|
to: "Kimai plugin loader"
|
|
via: "PluginInterface implementation"
|
|
pattern: "PluginInterface"
|
|
---
|
|
|
|
<objective>
|
|
Run the setup script to bootstrap Kimai, create the minimal plugin scaffold, and verify the full dev environment works end-to-end.
|
|
|
|
Purpose: Validate that the dev environment from Plan 01 actually produces a working Kimai instance with test data and a recognized plugin.
|
|
Output: Working Kimai instance, minimal plugin bundle class and composer.json, human-verified browser access.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
|
|
@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/phase-1/RESEARCH.md
|
|
@.planning/phases/01-dev-environment/01-01-SUMMARY.md
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Create plugin scaffold and run setup</name>
|
|
<files>KimaiHeatmapBundle.php, composer.json</files>
|
|
<action>
|
|
**Step 1: Create the minimal plugin bundle class** at project root `KimaiHeatmapBundle.php`:
|
|
|
|
```php
|
|
<?php
|
|
|
|
namespace KimaiPlugin\KimaiHeatmapBundle;
|
|
|
|
use App\Plugin\PluginInterface;
|
|
use Symfony\Component\HttpKernel\Bundle\Bundle;
|
|
|
|
class KimaiHeatmapBundle extends Bundle implements PluginInterface
|
|
{
|
|
}
|
|
```
|
|
|
|
**Step 2: Create `composer.json`** at project root:
|
|
|
|
```json
|
|
{
|
|
"name": "kimai-plugin/heatmap-bundle",
|
|
"type": "kimai-plugin",
|
|
"description": "GitHub-style activity heatmap dashboard widget for Kimai",
|
|
"license": "MIT",
|
|
"autoload": {
|
|
"psr-4": {
|
|
"KimaiPlugin\\KimaiHeatmapBundle\\": ""
|
|
}
|
|
},
|
|
"extra": {
|
|
"kimai": {
|
|
"require": 25200,
|
|
"name": "Activity Heatmap"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 3: Run the setup script** (from within `nix develop`):
|
|
|
|
```bash
|
|
cd /home/toph/code/toph/kimai-heatmap
|
|
bash dev/setup.sh
|
|
```
|
|
|
|
This will clone Kimai, install deps, init the database, load fixtures, symlink the plugin, and clear cache. If any step fails, debug and fix the setup script or flake.nix as needed.
|
|
|
|
**Troubleshooting guidance:**
|
|
- If MariaDB fails to start: check that `dev/.mariadb-data` was initialized. Run `mysql_install_db --datadir=./dev/.mariadb-data --auth-root-authentication-method=normal` manually.
|
|
- If Composer fails with extension errors: check `php -m` output and adjust the `php.buildEnv` extensions in flake.nix.
|
|
- If `kimai:install` fails with DB connection error: verify DATABASE_URL uses `127.0.0.1` not `localhost`, and MariaDB is running on port 3307.
|
|
- If plugin symlink issues: verify the link is `dev/kimai/var/plugins/KimaiHeatmapBundle -> /home/toph/code/toph/kimai-heatmap` (absolute path, directory name matches bundle class).
|
|
|
|
**Step 4: Verify seeded data exists:**
|
|
|
|
```bash
|
|
cd dev/kimai && bin/console doctrine:query:sql "SELECT COUNT(*) as cnt FROM kimai2_timesheet"
|
|
```
|
|
|
|
Should return a count of several hundred entries minimum.
|
|
|
|
**Step 5: Verify plugin is loaded:**
|
|
|
|
```bash
|
|
cd dev/kimai && bin/console kimai:plugins
|
|
```
|
|
|
|
Should list "Activity Heatmap" (the plugin name from composer.json extra.kimai.name).
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/toph/code/toph/kimai-heatmap/dev/kimai && bin/console kimai:plugins 2>&1 | grep -i "heatmap" && bin/console doctrine:query:sql "SELECT COUNT(*) as cnt FROM kimai2_timesheet" 2>&1</automated>
|
|
</verify>
|
|
<done>Kimai instance running with seeded data. Plugin listed in kimai:plugins output. Database contains timesheet entries.</done>
|
|
</task>
|
|
|
|
<task type="checkpoint:human-verify" gate="blocking">
|
|
<name>Task 2: Verify dev environment in browser</name>
|
|
<action>Human verifies the complete dev environment works end-to-end by accessing Kimai in the browser and confirming the plugin is loaded.</action>
|
|
<what-built>Complete dev environment: Nix devshell with local Kimai instance, seeded test data, and plugin recognized by Kimai.</what-built>
|
|
<how-to-verify>
|
|
1. From the project root, run: `process-compose -f dev/process-compose.yaml up`
|
|
2. Wait for both MariaDB and Kimai to show as healthy/running
|
|
3. Open browser to http://127.0.0.1:8010
|
|
4. Log in with username `susan_super` password `password` (super admin from fixtures)
|
|
5. Verify the dashboard loads (no errors)
|
|
6. Navigate to System > Plugins -- verify "Activity Heatmap" appears in the list
|
|
7. Stop process-compose with Ctrl+C
|
|
</how-to-verify>
|
|
<verify>Human confirms Kimai dashboard loads and plugin is listed</verify>
|
|
<done>Dashboard accessible, plugin visible in admin, seeded data present</done>
|
|
<resume-signal>Type "approved" or describe issues</resume-signal>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<threat_model>
|
|
## Trust Boundaries
|
|
|
|
| Boundary | Description |
|
|
|----------|-------------|
|
|
| Plugin -> Kimai | Plugin runs inside Kimai's PHP process with full access to Kimai internals |
|
|
|
|
## STRIDE Threat Register
|
|
|
|
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
|
|-----------|----------|-----------|-------------|-----------------|
|
|
| T-01-03 | Elevation of Privilege | PluginInterface | accept | Plugin runs with same privileges as Kimai itself. This is by design in Kimai's plugin architecture. Personal use, single user. |
|
|
| T-01-04 | Information Disclosure | Fixture credentials (password: "password") | accept | Dev environment only. Fixtures create test users with known passwords. Not exposed beyond localhost. |
|
|
</threat_model>
|
|
|
|
<verification>
|
|
1. `bin/console kimai:plugins` lists "Activity Heatmap"
|
|
2. `SELECT COUNT(*) FROM kimai2_timesheet` returns > 100 entries
|
|
3. Kimai dashboard loads in browser at http://127.0.0.1:8010
|
|
4. Plugin appears in System > Plugins admin page
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
Developer can run `nix develop`, execute `dev/setup.sh` once, then `process-compose -f dev/process-compose.yaml up` to get a working Kimai instance with seeded data and the heatmap plugin recognized. Dashboard accessible in browser, plugin listed in admin.
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/01-dev-environment/01-02-SUMMARY.md`
|
|
</output>
|