kimai-plugin-heatmap/.planning/milestones/v1.0-phases/01-dev-environment/01-02-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
01-dev-environment	02	execute	2	01-01	KimaiHeatmapBundle.php composer.json	false	DEV-02 DEV-03	truths artifacts key_links 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 path provides contains KimaiHeatmapBundle.php Symfony bundle class implementing Kimai PluginInterface implements PluginInterface path provides contains composer.json Plugin metadata with kimai-plugin type and autoload config kimai-plugin from to via pattern dev/kimai/var/plugins/KimaiHeatmapBundle project root symlink KimaiHeatmapBundle from to via pattern KimaiHeatmapBundle.php Kimai plugin loader PluginInterface implementation PluginInterface

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.

<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>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/phase-1/RESEARCH.md @.planning/phases/01-dev-environment/01-01-SUMMARY.md Task 1: Create plugin scaffold and run setup KimaiHeatmapBundle.php, composer.json **Step 1: Create the minimal plugin bundle class** at project root `KimaiHeatmapBundle.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:

{
    "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):

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:

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:

cd dev/kimai && bin/console kimai:plugins

Should list "Activity Heatmap" (the plugin name from composer.json extra.kimai.name). 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 Kimai instance running with seeded data. Plugin listed in kimai:plugins output. Database contains timesheet entries.

Task 2: Verify dev environment in browser Human verifies the complete dev environment works end-to-end by accessing Kimai in the browser and confirming the plugin is loaded. Complete dev environment: Nix devshell with local Kimai instance, seeded test data, and plugin recognized by Kimai. 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 Human confirms Kimai dashboard loads and plugin is listed Dashboard accessible, plugin visible in admin, seeded data present Type "approved" or describe issues

<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>

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

<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>

After completion, create `.planning/phases/01-dev-environment/01-02-SUMMARY.md`