ImpTune/.planning/PROJECT.md

# ImpTune

## What This Is

A self-hosted webapp (single Docker container) that lets IT technicians configure printer deployments and export ready-to-deploy packages for Microsoft Intune or NinjaRMM. It handles driver ZIP upload with INF parsing, full printer configuration with client/tenant grouping, PowerShell install/uninstall/detect generation (UAC + WOW64 guards), Python-native .intunewin assembly with embedded icon, and NinjaRMM ZIP export — all from a no-auth HTMX/Alpine.js browser UI.

**Current state:** v1.0 shipped 2026-04-13 — 27 requirements, 7 phases, 13 plans.

## Core Value

Generate a complete, working printer deployment package (script + drivers + icon) in minutes instead of manually scripting each printer setup.

Validated in v1.0: the tool produces both .intunewin and NinjaRMM artifacts from a saved printer config without re-uploading drivers.

## Requirements

### Validated (shipped in v1.0)

- ✓ Upload driver ZIP with INF parsing and DriverDesc dropdown — v1.0 (DRV-01..05)
- ✓ Configure all printer parameters (name, IP/port, duplex, color, paper, collate) — v1.0 (PRNT-01..07)
- ✓ Client/tenant grouping with SQLite persistence and regenerate-from-saved-config — v1.0 (PRNT-08..10)
- ✓ PowerShell install script with UAC self-elevation and WOW64 64-bit relaunch guard — v1.0 (SCRPT-01, SCRPT-04, SCRPT-05)
- ✓ Uninstall and Intune detection scripts — v1.0 (SCRPT-02, SCRPT-03)
- ✓ Python-native .intunewin export (no IntuneWinAppUtil.exe dependency) — v1.0 (PKG-01, PKG-02)
- ✓ NinjaRMM ZIP export — v1.0 (PKG-03)
- ✓ Custom PNG icon upload, validated and embedded in .intunewin — v1.0 (PKG-04, Phase 6 gap closure)
- ✓ Install/uninstall command preview with copy buttons — v1.0 (PKG-05)
- ✓ Single Docker container, minimal runtime dependencies — v1.0 (INFRA-01, INFRA-02)

### Active (v1.1 candidates)

- [ ] Runtime validation on a real Intune tenant (.intunewin byte-level, pnputil under SYSTEM)
- [ ] Live browser verification of PRNT-03 Alpine.js port auto-derivation
- [ ] Fix printer form driver dropdown refresh after new driver upload (no manual page reload)
- [ ] Add UI links to individual script downloads on printer detail page
- [ ] Nyquist-compliant VALIDATION.md for all 7 phases (separate validation track)
- [ ] First real-world deployment + user feedback capture

### Out of Scope

- User authentication / separate logins — internal tool on private network
- Direct Intune / NinjaRMM API push — export packages only, keeps scope contained
- Real-time printer status / monitoring — requires SNMP + per-site network access, different product
- Universal Print integration — different deployment model, requires Azure subscription
- Mobile / tablet UI — target users are at workstations; no validated demand
- Multi-language / localization — English only, no demand signal
- Full deployment history / audit log — MSPs already have Intune/RMM logs

## Context

Shipped v1.0 with ~3,924 LOC Python (incl. tests) + templates/static assets. 113 files, ~14,840 lines added from first commit to v1.0.

**Stack:** Python 3.12 · FastAPI · Jinja2 · HTMX · Alpine.js · Pico CSS · SQLite (Peewee WAL) · pycryptodome · Pillow — single Docker container, no Node.js, no external DB.

**Target users:** MSP technicians managing printers across multiple client sites in multi-brand environments (HP, Canon, Ricoh, Brother, etc.).

**Known runtime validations pending:** No real-world Intune tenant test yet — format compliance is byte-level validated against the C# reference but not end-to-end against a live tenant.

## Constraints

- **Deployment**: Single Docker container — no external database, message queue, or sidecar services
- **Dependencies**: Minimal — no Node.js, no external DB, no non-Python build tools
- **Platform**: Generated scripts target Windows endpoints (PowerShell 5.1+)
- **Persistence**: SQLite for config, Docker volume for driver packages and icons (both SHA256 content-addressed)

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| No authentication | Internal tool on private network, simplicity over security | ✓ Good — v1.0 shipped without auth, no incidents |
| Python-native .intunewin | IntuneWinAppUtil.exe is a Windows PE binary, cannot run in Linux container | ✓ Good — byte-level validated, 14 format tests |
| Single Docker container | Minimal ops burden, easy to deploy | ✓ Good — shipped in v1.0 |
| Peewee + SQLite WAL | Minimal dependency, sync ORM compatible with sync FastAPI routes in thread pool | ✓ Good |
| Full 4-table schema upfront (Phase 1) | Later phases add routes only, no schema migrations | ✓ Good — zero schema churn across phases 2–7 |
| SHA256 content-addressed storage for drivers + icons | Free deduplication, consistent pattern | ✓ Good (but caused one bug: path suffix mismatch, fixed) |
| Plain-string args for script generators (not ORM objects) | Keeps unit tests DB-free | ✓ Good |
| Silent-skip on missing icon | Export always succeeds, optional feature | ✓ Good |
| Gap-closure phases 6 & 7 (post-audit) | Cleaner than shipping with known defects | ✓ Good — all 27 requirements passed re-audit |
| HTMX + Alpine.js (no SPA) | No Node.js in container, server-rendered templates | ✓ Good |

## Current Focus

v1.0 shipped. Next up: v1.1 planning — focus on real-world runtime validation (Intune tenant, SYSTEM-context `pnputil`) and fixing carryover tech debt (driver dropdown refresh, script download UI, Nyquist validation).

---
*Last updated: 2026-04-13 after v1.0 milestone*