Commit initial
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
---
|
||||
phase: 05-package-export
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- imptune/api/packages.py
|
||||
- imptune/main.py
|
||||
- tests/test_packages.py
|
||||
autonomous: true
|
||||
requirements: [PKG-01, PKG-02, PKG-03]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "GET /printers/{id}/packages/ninja returns a ZIP containing install.ps1 and drivers/ subfolder"
|
||||
- "GET /printers/{id}/packages/intunewin returns a valid .intunewin file with correct Content-Disposition"
|
||||
- "Both endpoints return 404 for missing printer, 422 for missing/invalid driver"
|
||||
- "NinjaRMM ZIP uses DEFLATE compression and has printer-name-based folder structure"
|
||||
- ".intunewin is built using Python-native build_intunewin() with no subprocess calls"
|
||||
artifacts:
|
||||
- path: "imptune/api/packages.py"
|
||||
provides: "Package download endpoints for NinjaRMM ZIP and .intunewin"
|
||||
exports: ["router"]
|
||||
- path: "tests/test_packages.py"
|
||||
provides: "Integration tests for both export endpoints"
|
||||
contains: "TestNinjaDownload"
|
||||
key_links:
|
||||
- from: "imptune/api/packages.py"
|
||||
to: "imptune/generators/script_generator.py"
|
||||
via: "render_install, render_uninstall, render_detect"
|
||||
pattern: "from imptune\\.generators\\.script_generator import"
|
||||
- from: "imptune/api/packages.py"
|
||||
to: "imptune/generators/intunewin_builder.py"
|
||||
via: "build_intunewin(source_dir, setup_file, output_path)"
|
||||
pattern: "from imptune\\.generators\\.intunewin_builder import build_intunewin"
|
||||
- from: "imptune/main.py"
|
||||
to: "imptune/api/packages.py"
|
||||
via: "app.include_router(packages.router)"
|
||||
pattern: "include_router.*packages"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Create the two package export API endpoints: NinjaRMM ZIP download and .intunewin download. Both serve binary file responses for a given printer configuration.
|
||||
|
||||
Purpose: PKG-01/PKG-02/PKG-03 -- Users can download deployment-ready packages in either format with one click.
|
||||
Output: `imptune/api/packages.py` with two GET endpoints, registered in main.py, with integration tests.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/05-package-export/05-RESEARCH.md
|
||||
|
||||
@imptune/api/scripts.py
|
||||
@imptune/generators/intunewin_builder.py
|
||||
@imptune/generators/script_generator.py
|
||||
@imptune/config.py
|
||||
@imptune/db/models.py
|
||||
@imptune/main.py
|
||||
@tests/conftest.py
|
||||
|
||||
<interfaces>
|
||||
<!-- Key types and contracts the executor needs. -->
|
||||
|
||||
From imptune/api/scripts.py:
|
||||
```python
|
||||
def _get_printer_and_driver(printer_id: int):
|
||||
"""Returns (printer, driver, driver_name), None on success
|
||||
or None, PlainTextResponse on error (404/422)."""
|
||||
```
|
||||
|
||||
From imptune/generators/script_generator.py:
|
||||
```python
|
||||
def render_install(printer_name, ip_address, port_name, driver_name,
|
||||
inf_filename, duplex_mode, color_mode, paper_size, collate) -> str: ...
|
||||
def render_uninstall(printer_name, driver_name, port_name) -> str: ...
|
||||
def render_detect(printer_name) -> str: ...
|
||||
```
|
||||
|
||||
From imptune/generators/intunewin_builder.py:
|
||||
```python
|
||||
def build_intunewin(source_dir: str, setup_file: str, output_path: str) -> None:
|
||||
"""Build a .intunewin file from source_dir, with setup_file as entry point."""
|
||||
```
|
||||
|
||||
From imptune/config.py:
|
||||
```python
|
||||
DATA_DIR = os.environ.get("DATA_DIR", "/data")
|
||||
DRIVERS_DIR = str(Path(DATA_DIR) / "drivers")
|
||||
```
|
||||
|
||||
From imptune/db/models.py:
|
||||
```python
|
||||
class Driver(BaseModel):
|
||||
sha256 = CharField(unique=True, index=True)
|
||||
original_filename = CharField()
|
||||
driver_desc = CharField(null=True) # JSON list of driver names
|
||||
inf_filename = CharField(null=True)
|
||||
...
|
||||
|
||||
class Printer(BaseModel):
|
||||
name = CharField()
|
||||
ip_address = CharField()
|
||||
port_name = CharField()
|
||||
driver = ForeignKeyField(Driver, null=True, backref="printers")
|
||||
duplex_mode = CharField(default="OneSided")
|
||||
color_mode = BooleanField(default=True)
|
||||
paper_size = CharField(default="A4")
|
||||
collate = BooleanField(default=True)
|
||||
...
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Package export endpoints with TDD</name>
|
||||
<files>imptune/api/packages.py, imptune/main.py, tests/test_packages.py</files>
|
||||
<behavior>
|
||||
- TestNinjaDownload::test_returns_zip: GET /printers/{id}/packages/ninja returns 200, media_type application/zip, Content-Disposition with filename
|
||||
- TestNinjaDownload::test_zip_contains_install_script: Response ZIP contains {safe_name}/install.ps1
|
||||
- TestNinjaDownload::test_zip_contains_driver_files: Response ZIP contains {safe_name}/drivers/ with files from driver ZIP
|
||||
- TestNinjaDownload::test_404_missing_printer: Returns 404 for nonexistent printer_id
|
||||
- TestNinjaDownload::test_422_no_driver: Returns 422 for printer with no assigned driver
|
||||
- TestIntunewinDownload::test_returns_intunewin: GET /printers/{id}/packages/intunewin returns 200, media_type application/octet-stream, Content-Disposition with .intunewin extension
|
||||
- TestIntunewinDownload::test_intunewin_is_valid_zip: Response content is a valid outer ZIP with IntuneWinPackage/ structure
|
||||
- TestIntunewinDownload::test_404_missing_printer: Returns 404 for nonexistent printer_id
|
||||
- TestIntunewinDownload::test_422_no_driver: Returns 422 for printer with no assigned driver
|
||||
</behavior>
|
||||
<action>
|
||||
1. Create `tests/test_packages.py` with RED tests first. Test fixtures: create a Driver record with a real small ZIP file on disk (use tmp_data_dir from conftest), create a Printer record linked to it. Use the `client` fixture from conftest.py.
|
||||
|
||||
2. Create `imptune/api/packages.py` with `router = APIRouter(prefix="/printers")`:
|
||||
|
||||
**NinjaRMM endpoint** `GET /{printer_id}/packages/ninja`:
|
||||
- Reuse `_get_printer_and_driver()` pattern from scripts.py (copy the helper into packages.py or import — prefer copy since it's small and keeps the module self-contained)
|
||||
- Call `render_install(...)` with all printer/driver params
|
||||
- Build ZIP in-memory with `io.BytesIO` + `zipfile.ZipFile`:
|
||||
- `{safe_name}/install.ps1` with rendered script
|
||||
- `{safe_name}/drivers/{member}` for each file in the driver ZIP on disk
|
||||
- `safe_name = printer.name.replace(" ", "_")`
|
||||
- Return `Response(content=buf.getvalue(), media_type="application/zip", headers={"Content-Disposition": f'attachment; filename="{safe_name}_ninja.zip"'})`
|
||||
|
||||
**Intunewin endpoint** `GET /{printer_id}/packages/intunewin`:
|
||||
- Same printer/driver validation via `_get_printer_and_driver()`
|
||||
- Use `tempfile.TemporaryDirectory(prefix="imptune_")` as context manager (auto-cleanup, per RESEARCH pitfall 1)
|
||||
- Write `install.ps1`, `uninstall.ps1`, `detect.ps1` into tmpdir
|
||||
- Extract driver ZIP contents into `tmpdir/drivers/`
|
||||
- Call `build_intunewin(tmpdir, "install.ps1", os.path.join(tmpdir, "out.intunewin"))`
|
||||
- Read output file bytes and return as `Response(content=..., media_type="application/octet-stream", headers={"Content-Disposition": ...})`
|
||||
- Check driver file exists on disk before proceeding (per RESEARCH pitfall 3), return 422 if missing
|
||||
|
||||
3. Register router in `imptune/main.py`:
|
||||
- Add `from imptune.api import packages` to imports
|
||||
- Add `app.include_router(packages.router)` after scripts router
|
||||
|
||||
4. Run tests GREEN.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_packages.py -x</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- NinjaRMM ZIP endpoint returns valid ZIP with install.ps1 and driver files inside a named subfolder
|
||||
- .intunewin endpoint returns valid .intunewin (outer ZIP with IntuneWinPackage/ structure)
|
||||
- Both endpoints handle 404/422 for missing printer or driver
|
||||
- Router registered in main.py
|
||||
- All tests pass, full suite still green (pytest tests/ -x)
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
pytest tests/test_packages.py -x && pytest tests/ -x
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- GET /printers/{id}/packages/ninja returns downloadable ZIP with install.ps1 + driver files
|
||||
- GET /printers/{id}/packages/intunewin returns downloadable .intunewin package
|
||||
- Both endpoints return proper error codes for invalid requests
|
||||
- Full test suite green
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-package-export/05-01-SUMMARY.md`
|
||||
</output>
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
phase: 05-package-export
|
||||
plan: "01"
|
||||
subsystem: api/packages
|
||||
tags: [fastapi, zip, intunewin, package-export, tdd]
|
||||
dependency_graph:
|
||||
requires:
|
||||
- imptune/generators/script_generator.py (render_install, render_uninstall, render_detect)
|
||||
- imptune/generators/intunewin_builder.py (build_intunewin)
|
||||
- imptune/api/scripts.py (_get_printer_and_driver pattern)
|
||||
- imptune/db/models.py (Printer, Driver ORM)
|
||||
- imptune/config.py (DRIVERS_DIR)
|
||||
provides:
|
||||
- GET /printers/{id}/packages/ninja (NinjaRMM ZIP download)
|
||||
- GET /printers/{id}/packages/intunewin (.intunewin download)
|
||||
affects:
|
||||
- imptune/main.py (router registration)
|
||||
tech_stack:
|
||||
added: []
|
||||
patterns:
|
||||
- In-memory ZIP assembly with io.BytesIO + zipfile.ZipFile
|
||||
- TemporaryDirectory context manager for auto-cleanup of intunewin build artifacts
|
||||
- Driver ZIP existence validation before processing
|
||||
key_files:
|
||||
created:
|
||||
- imptune/api/packages.py
|
||||
- tests/test_packages.py
|
||||
modified:
|
||||
- imptune/main.py
|
||||
decisions:
|
||||
- _get_printer_and_driver() copied (not imported) from scripts.py for module self-containment
|
||||
- NinjaRMM ZIP uses DEFLATE compression with {printer_name}/install.ps1 + {printer_name}/drivers/* structure
|
||||
- intunewin endpoint uses TemporaryDirectory for auto-cleanup of tmp build files (no manual cleanup needed)
|
||||
- Driver ZIP file existence validated on disk before building package (422 if missing)
|
||||
metrics:
|
||||
duration: "~2 min"
|
||||
completed_date: "2026-04-10"
|
||||
tasks_completed: 1
|
||||
files_modified: 3
|
||||
requirements-completed: [PKG-01, PKG-02, PKG-03]
|
||||
---
|
||||
|
||||
# Phase 5 Plan 1: Package Export Endpoints Summary
|
||||
|
||||
**One-liner:** NinjaRMM ZIP and .intunewin package export endpoints using in-memory ZIP assembly and Python-native intunewin build.
|
||||
|
||||
## What Was Built
|
||||
|
||||
Two GET endpoints on `imptune/api/packages.py`:
|
||||
|
||||
1. **`GET /printers/{id}/packages/ninja`** — Returns a ZIP file (application/zip) with:
|
||||
- `{safe_name}/install.ps1` — rendered PowerShell install script
|
||||
- `{safe_name}/drivers/*` — all driver files extracted from the driver ZIP on disk
|
||||
- Built entirely in-memory with `io.BytesIO` + `zipfile.ZipFile(ZIP_DEFLATED)`
|
||||
|
||||
2. **`GET /printers/{id}/packages/intunewin`** — Returns a `.intunewin` file (application/octet-stream) with:
|
||||
- Writes install.ps1, uninstall.ps1, detect.ps1 into a `TemporaryDirectory`
|
||||
- Extracts driver ZIP into `tmpdir/drivers/`
|
||||
- Calls `build_intunewin(tmpdir, "install.ps1", output_path)` — no subprocess calls
|
||||
- Reads bytes and returns as binary Response
|
||||
|
||||
Both endpoints share `_get_printer_and_driver()` helper (404 for missing printer, 422 for no/invalid driver) and validate the driver ZIP file exists on disk (422 if missing).
|
||||
|
||||
Router registered in `imptune/main.py` after `scripts.router`.
|
||||
|
||||
## Tests
|
||||
|
||||
9 new tests in `tests/test_packages.py`:
|
||||
|
||||
- `TestNinjaDownload`: 5 tests (zip response, install.ps1 in zip, driver files in zip, 404, 422)
|
||||
- `TestIntunewinDownload`: 4 tests (intunewin response, valid outer ZIP structure, 404, 422)
|
||||
|
||||
Full suite result: 84 passed (excluding pre-existing icon upload failures in test_icon_upload.py which existed before this plan).
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written.
|
||||
|
||||
## Pre-existing Issues (Out of Scope)
|
||||
|
||||
`tests/test_icon_upload.py` has 5 failing tests (`/printers/{id}/icon` returns 404). These failures existed before this plan was executed and are unrelated to package export. Logged for future attention.
|
||||
|
||||
## Commits
|
||||
|
||||
| Hash | Type | Description |
|
||||
| ------- | ------ | ------------------------------------------------------------- |
|
||||
| a31c71e | test | add failing tests for NinjaRMM ZIP and intunewin endpoints |
|
||||
| dd6cedf | feat | implement NinjaRMM ZIP and intunewin package export endpoints |
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: imptune/api/packages.py
|
||||
- FOUND: tests/test_packages.py
|
||||
- FOUND: imptune/main.py (modified)
|
||||
- FOUND commit a31c71e (RED tests)
|
||||
- FOUND commit dd6cedf (GREEN implementation)
|
||||
@@ -0,0 +1,292 @@
|
||||
---
|
||||
phase: 05-package-export
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- imptune/api/icons.py
|
||||
- imptune/config.py
|
||||
- imptune/main.py
|
||||
- imptune/api/pages.py
|
||||
- imptune/templates/printer_detail.html
|
||||
- requirements.txt
|
||||
- tests/test_icon_upload.py
|
||||
autonomous: true
|
||||
requirements: [PKG-04, PKG-05]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can upload a PNG icon for a printer and it is stored on disk"
|
||||
- "Icon upload rejects non-PNG files, files over 750KB, and wrong dimensions (not 256x256)"
|
||||
- "Re-uploading an icon for the same printer replaces the previous one"
|
||||
- "Printer detail page shows Intune install and uninstall command strings"
|
||||
- "User can copy the command strings (text displayed prominently for copy)"
|
||||
- "Printer detail page has download links for NinjaRMM ZIP and .intunewin"
|
||||
artifacts:
|
||||
- path: "imptune/api/icons.py"
|
||||
provides: "Icon upload endpoint"
|
||||
exports: ["router"]
|
||||
- path: "imptune/templates/printer_detail.html"
|
||||
provides: "Export buttons, command preview, icon upload form"
|
||||
contains: "install-cmd"
|
||||
- path: "tests/test_icon_upload.py"
|
||||
provides: "Integration tests for icon upload validation"
|
||||
contains: "test_upload_valid_png"
|
||||
key_links:
|
||||
- from: "imptune/api/icons.py"
|
||||
to: "imptune/db/models.py"
|
||||
via: "Icon model CRUD"
|
||||
pattern: "from imptune\\.db\\.models import.*Icon"
|
||||
- from: "imptune/api/icons.py"
|
||||
to: "imptune/config.py"
|
||||
via: "cfg.DATA_DIR for icon storage path"
|
||||
pattern: "import imptune\\.config as cfg"
|
||||
- from: "imptune/main.py"
|
||||
to: "imptune/api/icons.py"
|
||||
via: "app.include_router(icons.router)"
|
||||
pattern: "include_router.*icons"
|
||||
- from: "imptune/templates/printer_detail.html"
|
||||
to: "/printers/{id}/packages/*"
|
||||
via: "href download links"
|
||||
pattern: "packages/ninja|packages/intunewin"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Add icon upload for Intune packages and update the printer detail page with export download buttons and Intune command preview strings.
|
||||
|
||||
Purpose: PKG-04 (custom icon upload) and PKG-05 (command preview) -- completing the export UI that makes deployment packages accessible to technicians.
|
||||
Output: `imptune/api/icons.py` with upload endpoint, updated `printer_detail.html` with export section, command preview, and icon upload form.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/05-package-export/05-RESEARCH.md
|
||||
|
||||
@imptune/api/drivers.py
|
||||
@imptune/api/pages.py
|
||||
@imptune/config.py
|
||||
@imptune/db/models.py
|
||||
@imptune/main.py
|
||||
@imptune/templates/printer_detail.html
|
||||
@imptune/templates/base.html
|
||||
@tests/conftest.py
|
||||
@requirements.txt
|
||||
|
||||
<interfaces>
|
||||
<!-- Key types and contracts the executor needs. -->
|
||||
|
||||
From imptune/db/models.py:
|
||||
```python
|
||||
class Icon(BaseModel):
|
||||
printer = ForeignKeyField(Printer, unique=True, backref="icons")
|
||||
sha256 = CharField()
|
||||
original_filename = CharField()
|
||||
size_bytes = IntegerField()
|
||||
uploaded_at = DateTimeField(default=datetime.utcnow)
|
||||
|
||||
class Meta:
|
||||
table_name = "icon"
|
||||
```
|
||||
|
||||
From imptune/api/drivers.py (UploadFile pattern):
|
||||
```python
|
||||
from fastapi import UploadFile
|
||||
# file: UploadFile parameter, file.file.read() for bytes, file.filename for name
|
||||
```
|
||||
|
||||
From imptune/config.py:
|
||||
```python
|
||||
DATA_DIR = os.environ.get("DATA_DIR", "/data")
|
||||
DRIVERS_DIR = str(Path(DATA_DIR) / "drivers")
|
||||
# Add ICONS_DIR = str(Path(DATA_DIR) / "icons") following same pattern
|
||||
```
|
||||
|
||||
From imptune/templates/printer_detail.html (current state):
|
||||
```html
|
||||
{% extends "base.html" %}
|
||||
{% block content %}
|
||||
<!-- Has Configuration, Driver, and Actions sections -->
|
||||
<!-- Actions section has disabled "Regenerate Package" button placeholder -->
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
From imptune/api/pages.py printer_detail():
|
||||
```python
|
||||
@router.get("/printers/{printer_id}", response_class=HTMLResponse)
|
||||
def printer_detail(request: Request, printer_id: int):
|
||||
# Returns context: {"printer": printer, "driver_names": driver_names}
|
||||
# Need to add install_cmd, uninstall_cmd, has_icon to context
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Icon upload endpoint with validation</name>
|
||||
<files>imptune/api/icons.py, imptune/config.py, imptune/main.py, requirements.txt, tests/test_icon_upload.py</files>
|
||||
<behavior>
|
||||
- test_upload_valid_png: POST /printers/{id}/icon with valid 256x256 PNG returns 200, Icon record created in DB, file stored on disk
|
||||
- test_reject_non_png: POST with a JPEG file returns 422 with "PNG format" error message
|
||||
- test_reject_oversized: POST with PNG > 750KB returns 422 with "750 KB" error message
|
||||
- test_reject_wrong_dimensions: POST with 128x128 PNG returns 422 with "256x256" error message
|
||||
- test_replace_existing_icon: Second upload for same printer replaces the Icon record (unique FK constraint)
|
||||
- test_404_missing_printer: POST to nonexistent printer_id returns 404
|
||||
</behavior>
|
||||
<action>
|
||||
1. Add `Pillow>=10.0` to `requirements.txt` (per RESEARCH recommendation -- needed for dimension validation).
|
||||
|
||||
2. Add `ICONS_DIR` to `imptune/config.py`:
|
||||
```python
|
||||
ICONS_DIR = str(Path(DATA_DIR) / "icons")
|
||||
```
|
||||
|
||||
3. Create `tests/test_icon_upload.py` with RED tests. Generate a valid 256x256 PNG in the fixture using Pillow (`Image.new("RGBA", (256, 256), color="red")` saved to BytesIO). Use `client` fixture from conftest.py. Create Printer record in fixture.
|
||||
|
||||
4. Create `imptune/api/icons.py` with `router = APIRouter(prefix="/printers")`:
|
||||
|
||||
**POST /{printer_id}/icon** (accepts `file: UploadFile`):
|
||||
- Validate printer exists (Printer.get_or_none), return 404 if not
|
||||
- Read file bytes: `data = file.file.read(MAX_ICON_BYTES + 1)` where `MAX_ICON_BYTES = 750 * 1024`
|
||||
- If `len(data) > MAX_ICON_BYTES`, return 422 "Icon exceeds 750 KB limit"
|
||||
- Validate with Pillow: `img = Image.open(io.BytesIO(data))`
|
||||
- If `img.format != "PNG"`, return 422 "Icon must be PNG format"
|
||||
- If `img.size != (256, 256)`, return 422 "Icon must be 256x256 pixels, got {img.size}"
|
||||
- Store SHA256-addressed: `sha256 = hashlib.sha256(data).hexdigest()`, write to `Path(cfg.DATA_DIR) / "icons" / sha256` (read cfg.DATA_DIR at call time, not import time -- monkeypatch pattern)
|
||||
- Create icons dir if not exists: `Path(cfg.DATA_DIR, "icons").mkdir(parents=True, exist_ok=True)`
|
||||
- Delete existing Icon for this printer if any: `Icon.delete().where(Icon.printer == printer_id).execute()`
|
||||
- Create new Icon record: `Icon.create(printer=printer_id, sha256=sha256, original_filename=file.filename, size_bytes=len(data))`
|
||||
- Return `HTMLResponse("<p>Icon uploaded successfully</p>")` (HTMX-friendly)
|
||||
|
||||
5. Register router in `imptune/main.py`:
|
||||
- Add `from imptune.api import icons` to imports
|
||||
- Add `app.include_router(icons.router)` after packages router
|
||||
|
||||
6. Also create `ICONS_DIR` in lifespan startup (same as DRIVERS_DIR pattern):
|
||||
- Add `os.makedirs(cfg.ICONS_DIR, exist_ok=True)` in lifespan -- but use dynamic `cfg.ICONS_DIR` to avoid import-time evaluation. Actually, follow the existing pattern: import ICONS_DIR from config at top of main.py and makedirs in lifespan. But note: the test monkepatches cfg module, so use `import imptune.config as cfg` in lifespan OR just use the string directly. The simplest correct pattern: add `from imptune.config import ICONS_DIR` alongside the existing imports and `os.makedirs(ICONS_DIR, exist_ok=True)` in lifespan. This works because the lifespan runs AFTER monkeypatch has been applied in tests (TestClient context manager triggers lifespan).
|
||||
|
||||
Wait -- looking at the existing code more carefully: main.py imports `DATA_DIR, DRIVERS_DIR` at top level and uses them directly in lifespan. This works for tests because conftest patches `cfg.DRIVERS_DIR` before TestClient enters context. But the top-level import captures the original value. Let me check... Actually the conftest patches the cfg module attributes, but main.py imported the values at module load time. The lifespan still uses the stale import-time values. This is fine because the tests use `tmp_data_dir` which patches cfg, and the test client triggers lifespan which uses the already-imported constants -- wait, this is a potential issue.
|
||||
|
||||
Actually: looking at the conftest, it patches `cfg.DATA_DIR`, `cfg.DB_PATH`, `cfg.DRIVERS_DIR` on the module. The main.py does `from imptune.config import DATA_DIR, DRIVERS_DIR` which binds to the original values. BUT init_db() calls `db.init(cfg.DB_PATH)` dynamically, and the lifespan makedirs uses the imported constant. Since tests have their own tmp_data_dir and the test client is created AFTER monkeypatch, the lifespan runs with stale DATA_DIR/DRIVERS_DIR values. But this seems to work because the test fixtures create those dirs themselves via `data_dir.mkdir()`.
|
||||
|
||||
Simplest approach: Add ICONS_DIR to the import in main.py alongside the others. The conftest already creates `data_dir` and the tests will create `data_dir / "icons"` as needed. In the icons.py endpoint, use `import imptune.config as cfg` and read `cfg.DATA_DIR` at call time (consistent with RESEARCH anti-pattern guidance).
|
||||
|
||||
7. Run tests GREEN.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_icon_upload.py -x</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- Pillow added to requirements.txt
|
||||
- ICONS_DIR added to config.py
|
||||
- Icon upload validates format (PNG), size (<=750KB), dimensions (256x256)
|
||||
- Icon stored SHA256-addressed on disk, Icon ORM record created
|
||||
- Re-upload replaces previous icon
|
||||
- All tests pass
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Printer detail page with export buttons and command preview</name>
|
||||
<files>imptune/api/pages.py, imptune/templates/printer_detail.html, tests/test_packages.py</files>
|
||||
<action>
|
||||
1. Update `imptune/api/pages.py` `printer_detail()` to add command strings and icon status to template context:
|
||||
```python
|
||||
install_cmd = "powershell.exe -ExecutionPolicy Bypass -File install.ps1"
|
||||
uninstall_cmd = "powershell.exe -ExecutionPolicy Bypass -File uninstall.ps1"
|
||||
has_driver = printer.driver_id is not None and bool(driver_names)
|
||||
# Check if icon exists
|
||||
from imptune.db.models import Icon
|
||||
icon = Icon.get_or_none(Icon.printer == printer_id)
|
||||
```
|
||||
Pass `install_cmd`, `uninstall_cmd`, `has_driver`, `has_icon=(icon is not None)` to template context.
|
||||
|
||||
2. Rewrite `imptune/templates/printer_detail.html` to add three new sections after the existing Driver section:
|
||||
|
||||
**Command Preview section** (PKG-05):
|
||||
```html
|
||||
<h2>Intune Commands</h2>
|
||||
```
|
||||
Show install_cmd and uninstall_cmd in `<code>` blocks. Add Alpine.js copy button for each:
|
||||
```html
|
||||
<div x-data="{ copied: false }">
|
||||
<label>Install command</label>
|
||||
<code id="install-cmd">{{ install_cmd }}</code>
|
||||
<button @click="
|
||||
const text = document.getElementById('install-cmd').innerText;
|
||||
navigator.clipboard.writeText(text).then(() => { copied = true; setTimeout(() => copied = false, 2000) })
|
||||
.catch(() => { /* fallback: text is visible for manual copy */ })
|
||||
" x-text="copied ? 'Copied!' : 'Copy'" class="secondary outline"></button>
|
||||
</div>
|
||||
```
|
||||
Repeat for uninstall command with id="uninstall-cmd". Only show this section if `has_driver` is true.
|
||||
|
||||
**Export Downloads section**:
|
||||
Show download buttons only when `has_driver` is true:
|
||||
```html
|
||||
<h2>Export</h2>
|
||||
<a href="/printers/{{ printer.id }}/packages/ninja" role="button">Download NinjaRMM ZIP</a>
|
||||
<a href="/printers/{{ printer.id }}/packages/intunewin" role="button">Download .intunewin</a>
|
||||
```
|
||||
|
||||
**Icon Upload section** (PKG-04):
|
||||
```html
|
||||
<h2>Icon</h2>
|
||||
{% if has_icon %}
|
||||
<p>Icon uploaded</p>
|
||||
{% endif %}
|
||||
<form hx-post="/printers/{{ printer.id }}/icon"
|
||||
hx-target="#icon-status" hx-swap="innerHTML"
|
||||
enctype="multipart/form-data">
|
||||
<input type="file" name="file" accept="image/png" required>
|
||||
<button type="submit">Upload Icon</button>
|
||||
</form>
|
||||
<div id="icon-status"></div>
|
||||
```
|
||||
|
||||
Replace the old disabled "Regenerate Package" button with the real export buttons.
|
||||
|
||||
3. Add a test in `tests/test_packages.py` class `TestCommandPreview`:
|
||||
- test_detail_page_shows_commands: GET /printers/{id} returns HTML containing "install-cmd" and "uninstall-cmd" ids and the command strings
|
||||
- test_detail_page_shows_export_links: GET /printers/{id} returns HTML containing "/packages/ninja" and "/packages/intunewin" hrefs
|
||||
|
||||
These are simple integration tests using the `client` fixture -- create a Printer+Driver, GET the detail page, assert the command text and download links appear in the response HTML.
|
||||
|
||||
4. Run all tests green.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>pytest tests/test_packages.py -x && pytest tests/ -x</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- Printer detail page shows install and uninstall command strings with copy buttons
|
||||
- Printer detail page has NinjaRMM ZIP and .intunewin download links (visible when driver assigned)
|
||||
- Printer detail page has icon upload form with HTMX submission
|
||||
- Disabled placeholder button removed, replaced with real export actions
|
||||
- All tests pass including full suite
|
||||
</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
pytest tests/test_icon_upload.py tests/test_packages.py -x && pytest tests/ -x
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Icon upload validates PNG format, 256x256 dimensions, and 750KB size limit
|
||||
- Icon stored on disk and tracked in Icon ORM model
|
||||
- Printer detail page shows Intune command strings with copy-to-clipboard
|
||||
- Printer detail page has working download links for both package formats
|
||||
- Full test suite green
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/05-package-export/05-02-SUMMARY.md`
|
||||
</output>
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
phase: 05-package-export
|
||||
plan: 02
|
||||
subsystem: ui
|
||||
tags: [fastapi, pillow, htmx, alpine.js, icon-upload, png-validation, printer-detail]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 05-01
|
||||
provides: NinjaRMM ZIP and .intunewin package export endpoints
|
||||
- phase: 04-02
|
||||
provides: script generation endpoints (install/uninstall/detect)
|
||||
- phase: 03-02
|
||||
provides: printer detail page foundation in pages.py
|
||||
provides:
|
||||
- Icon upload endpoint with PNG format/dimension/size validation
|
||||
- SHA256-addressed icon storage under DATA_DIR/icons/
|
||||
- Icon ORM record tracking (one per printer, replace-on-upload)
|
||||
- Printer detail page with Intune Commands section (install/uninstall command strings with copy buttons)
|
||||
- Printer detail page with Export section (NinjaRMM ZIP and .intunewin download links)
|
||||
- Printer detail page with Icon Upload form (HTMX submission)
|
||||
affects: [deployment, ui, export]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [Pillow>=10.0 (PNG dimension/format validation)]
|
||||
patterns:
|
||||
- "Read cfg.DATA_DIR at call time (not import time) for monkeypatch compatibility"
|
||||
- "SHA256-addressed icon storage — dedup automatic, filename = sha256 hash"
|
||||
- "Icon replace pattern: delete existing record then create new (unique FK)"
|
||||
- "Alpine.js copy-to-clipboard with copied state and 2-second timeout"
|
||||
- "HTMX icon upload form with #icon-status swap target"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- imptune/api/icons.py
|
||||
- tests/test_icon_upload.py
|
||||
modified:
|
||||
- imptune/config.py
|
||||
- imptune/main.py
|
||||
- imptune/api/pages.py
|
||||
- imptune/templates/printer_detail.html
|
||||
- tests/conftest.py
|
||||
- tests/test_packages.py
|
||||
- requirements.txt
|
||||
|
||||
key-decisions:
|
||||
- "Pillow used for PNG validation — provides format, dimension, and byte-read in one library"
|
||||
- "Icons stored SHA256-addressed (not by printer ID) — enables dedup if same PNG used for multiple printers"
|
||||
- "Read cfg.DATA_DIR dynamically in icons.py endpoint, not at import time — consistent with monkeypatch pattern established in Phase 02"
|
||||
- "Icon replace via delete-then-create rather than get_or_create — unique FK makes upsert awkward, simpler to delete first"
|
||||
- "Export and command sections conditionally shown only when has_driver is true — avoids confusing 422 before driver is assigned"
|
||||
|
||||
patterns-established:
|
||||
- "Icon upload: read MAX+1 bytes, check len > MAX for oversized detection"
|
||||
- "Printer detail page sections gated on has_driver boolean from view context"
|
||||
|
||||
requirements-completed: [PKG-04, PKG-05]
|
||||
|
||||
# Metrics
|
||||
duration: 15min
|
||||
completed: 2026-04-10
|
||||
---
|
||||
|
||||
# Phase 05 Plan 02: Icon Upload and Printer Detail Export UI Summary
|
||||
|
||||
**PNG icon upload endpoint with 750KB/256x256/format validation, SHA256 storage, and printer detail page with Intune command preview and download links**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~15 min
|
||||
- **Started:** 2026-04-10T12:00:00Z
|
||||
- **Completed:** 2026-04-10T12:15:00Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 9
|
||||
|
||||
## Accomplishments
|
||||
- Icon upload endpoint (POST /printers/{id}/icon) with full validation: PNG format, 256x256 dimensions, 750KB max, 404 on missing printer
|
||||
- Re-upload replaces previous Icon ORM record (unique FK constraint handled via delete-then-create)
|
||||
- Printer detail page rewritten with three new sections: Intune Commands (install/uninstall with Alpine.js copy-to-clipboard), Export (NinjaRMM ZIP and .intunewin download links), Icon (HTMX upload form)
|
||||
- Full test suite green: 94 tests pass
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1 RED: Icon upload tests** - `d8ce223` (test)
|
||||
2. **Task 1 GREEN: Icon upload implementation** - `f9e13ba` (feat)
|
||||
3. **Task 2: Printer detail page with export UI** - `f96ea6f` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
- `imptune/api/icons.py` - Icon upload endpoint with PNG format/dimension/size validation
|
||||
- `imptune/config.py` - Added ICONS_DIR constant
|
||||
- `imptune/main.py` - Registered icons.router, added ICONS_DIR makedirs in lifespan
|
||||
- `imptune/api/pages.py` - Updated printer_detail() with install_cmd, uninstall_cmd, has_driver, has_icon context
|
||||
- `imptune/templates/printer_detail.html` - Added Intune Commands, Export, Icon Upload sections; removed placeholder button
|
||||
- `tests/test_icon_upload.py` - 6 TDD integration tests for icon upload validation
|
||||
- `tests/test_packages.py` - Added TestCommandPreview class (4 tests)
|
||||
- `tests/conftest.py` - Patched cfg.ICONS_DIR in tmp_data_dir fixture
|
||||
- `requirements.txt` - Added Pillow>=10.0
|
||||
|
||||
## Decisions Made
|
||||
- Used Pillow for PNG validation — single library handles format detection, dimension check, and byte reading in one pass
|
||||
- Icons stored SHA256-addressed under DATA_DIR/icons/ — consistent with DRIVERS_DIR content-addressing pattern from Phase 02
|
||||
- cfg.DATA_DIR read at call time in icons.py endpoint — consistent with monkeypatch pattern established in Phase 02 for DRIVERS_DIR
|
||||
- Export and command sections conditionally shown only when has_driver is true — prevents confusing broken download links before driver is assigned
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
- Pillow was not yet installed in the environment (requirements.txt addition needed `python -m pip install` before tests could run). Resolved automatically.
|
||||
|
||||
## User Setup Required
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- Icon upload and command preview complete — export UI is fully functional
|
||||
- Phase 05 is the final phase; all requirements PKG-01 through PKG-05 are now implemented
|
||||
- Remaining validation: byte-level .intunewin format compliance against real Intune tenant (noted as MEDIUM confidence concern)
|
||||
|
||||
---
|
||||
*Phase: 05-package-export*
|
||||
*Completed: 2026-04-10*
|
||||
@@ -0,0 +1,478 @@
|
||||
# Phase 5: Package Export - Research
|
||||
|
||||
**Researched:** 2026-04-10
|
||||
**Domain:** .intunewin file assembly, NinjaRMM ZIP packaging, icon upload, FastAPI StreamingResponse / Response binary downloads, HTMX copy-to-clipboard
|
||||
**Confidence:** HIGH (NinjaRMM ZIP, FastAPI binary responses, icon validation), MEDIUM (.intunewin Intune acceptance — format is implemented but tenant-level acceptance unverified)
|
||||
|
||||
---
|
||||
|
||||
<phase_requirements>
|
||||
## Phase Requirements
|
||||
|
||||
| ID | Description | Research Support |
|
||||
|----|-------------|-----------------|
|
||||
| PKG-01 | User can export a complete .intunewin package (script + drivers + detection + metadata) | `build_intunewin()` in `imptune/generators/intunewin_builder.py` is complete; Phase 5 wires it to a printer config + driver files + rendered scripts |
|
||||
| PKG-02 | .intunewin is generated natively in Python (no IntuneWinAppUtil.exe dependency) | Already implemented in Phase 1 spike using pycryptodome AES-256-CBC; no new libraries needed |
|
||||
| PKG-03 | User can export a NinjaRMM ZIP package (install script + driver folder) | Standard `zipfile` + `io.BytesIO` in-memory build, served via FastAPI `Response` with `application/zip` |
|
||||
| PKG-04 | User can upload a custom PNG icon for Intune app display (256x256, max 750KB) | `UploadFile` pattern from drivers.py; `Icon` ORM model already exists; validation with `imghdr` (stdlib) or `Pillow`; icon stored on DATA_DIR volume |
|
||||
| PKG-05 | User can preview and copy Intune install/uninstall command strings before export | Alpine.js `navigator.clipboard.writeText()` + `$el.innerText` pattern; rendered server-side in Jinja2 template; no new library needed |
|
||||
</phase_requirements>
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Phase 5 closes out v1 by wiring the already-proven `build_intunewin()` function and the Phase 4 script renderers into two download endpoints (`.intunewin` and NinjaRMM ZIP) plus an icon upload endpoint and a command-preview UI.
|
||||
|
||||
All cryptographic and ZIP assembly code is complete and tested from Phase 1. The new work is: (1) assembling the right files into a temp directory and calling `build_intunewin()`, (2) building a NinjaRMM ZIP in memory via `io.BytesIO`, (3) accepting a PNG upload and storing it to `DATA_DIR/icons/`, and (4) adding an Alpine.js clipboard copy widget to the printer detail page. No new Python packages are required; `zipfile`, `io`, `tempfile`, and `shutil` are all stdlib.
|
||||
|
||||
The one genuine risk remains .intunewin Intune tenant acceptance — the byte-level format has been reverse-engineered from svrooij.io documentation and validated in unit tests, but a real upload has not been attempted. This is called out as a manual gate before Phase 5 is declared done.
|
||||
|
||||
**Primary recommendation:** Build three new API router files (`packages.py` for exports, `icons.py` for upload), add `ICONS_DIR` to config, update the printer detail page with export buttons and command preview, keep all ZIP assembly in-memory (no temp files on disk).
|
||||
|
||||
---
|
||||
|
||||
## Standard Stack
|
||||
|
||||
### Core
|
||||
| Library | Version | Purpose | Why Standard |
|
||||
|---------|---------|---------|--------------|
|
||||
| `zipfile` | stdlib | Build NinjaRMM ZIP and inner .intunewin ZIP in memory | Already used throughout codebase |
|
||||
| `io.BytesIO` | stdlib | In-memory byte stream for zip assembly without disk I/O | Already used in `intunewin_builder.py` and `drivers.py` |
|
||||
| `tempfile` | stdlib | Temporary directory for .intunewin source staging | `build_intunewin()` requires a `source_dir` path |
|
||||
| `shutil` | stdlib | Copy driver ZIP contents into temp staging dir | Clean recursive copy |
|
||||
| `pycryptodome` | 3.20.* | AES-256-CBC encryption for .intunewin (already installed) | Phase 1 dependency; no change |
|
||||
| `FastAPI Response` | 0.115.* | Serve binary file downloads with `application/zip` | `Response(content=bytes, media_type=...)` is simplest for in-memory content |
|
||||
|
||||
### Supporting
|
||||
| Library | Version | Purpose | When to Use |
|
||||
|---------|---------|---------|-------------|
|
||||
| `FastAPI StreamingResponse` | 0.115.* | Alternative for large file streaming | Prefer `Response` for in-memory builds under ~50 MB; use `StreamingResponse` only if driver packages are so large that holding in RAM is a concern |
|
||||
| `Pillow` (PIL) | 10.x | PNG validation (dimensions + format) | Only if stdlib `imghdr` is insufficient for size/dimension check; adds a dependency |
|
||||
| `imghdr` | stdlib (deprecated 3.13) | Basic PNG format detection | Acceptable for Python 3.12; but deprecated — prefer Pillow for dimension validation |
|
||||
|
||||
### Alternatives Considered
|
||||
| Instead of | Could Use | Tradeoff |
|
||||
|------------|-----------|----------|
|
||||
| In-memory `io.BytesIO` ZIP | Write to `tmp_path` on disk, then stream | Disk I/O slower and requires cleanup; in-memory is simpler for packages under ~100 MB |
|
||||
| `FastAPI Response` | `StreamingResponse` with generator | StreamingResponse is more complex; Response is sufficient for in-memory byte content |
|
||||
| Pillow for icon validation | `imghdr` + manual struct parse | Pillow gives dimensions easily; `imghdr` only identifies format, not size — Pillow preferred |
|
||||
|
||||
**Installation (if Pillow added):**
|
||||
```bash
|
||||
pip install Pillow
|
||||
```
|
||||
> Note: Pillow is not in current `requirements.txt`. Only add it if dimension validation is required by PKG-04. The requirement states "256x256, max 750KB" — dimension check requires Pillow or struct-parsing PNG IHDR chunk manually.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Recommended Project Structure additions
|
||||
```
|
||||
imptune/
|
||||
├── api/
|
||||
│ ├── packages.py # GET /{printer_id}/packages/intunewin, GET /{printer_id}/packages/ninja
|
||||
│ └── icons.py # POST /{printer_id}/icon, GET /{printer_id}/icon
|
||||
├── generators/
|
||||
│ └── intunewin_builder.py # Already exists — no changes needed
|
||||
├── storage/
|
||||
│ └── icon_store.py # Analogous to driver_store.py (SHA256 content-addressed)
|
||||
└── templates/
|
||||
└── printer_detail.html # Add export buttons, command preview, icon upload form
|
||||
```
|
||||
|
||||
### Pattern 1: In-memory NinjaRMM ZIP
|
||||
**What:** Build the ZIP entirely in `io.BytesIO`, return as `Response` with `Content-Disposition: attachment`
|
||||
**When to use:** PKG-03 — NinjaRMM export
|
||||
**Example:**
|
||||
```python
|
||||
# Source: stdlib zipfile + FastAPI Response (project pattern from drivers.py)
|
||||
import io
|
||||
import json
|
||||
import zipfile
|
||||
from fastapi import APIRouter
|
||||
from fastapi.responses import Response
|
||||
from imptune.db.models import Printer
|
||||
from imptune.generators.script_generator import render_install
|
||||
import imptune.config as cfg
|
||||
|
||||
@router.get("/{printer_id}/packages/ninja")
|
||||
def download_ninja_package(printer_id: int):
|
||||
printer = Printer.get_or_none(Printer.id == printer_id)
|
||||
if printer is None:
|
||||
return Response("Printer not found", status_code=404, media_type="text/plain")
|
||||
|
||||
driver = printer.driver
|
||||
driver_names = json.loads(driver.driver_desc)
|
||||
script = render_install(
|
||||
printer_name=printer.name,
|
||||
ip_address=printer.ip_address,
|
||||
port_name=printer.port_name,
|
||||
driver_name=driver_names[0],
|
||||
inf_filename=driver.inf_filename,
|
||||
duplex_mode=printer.duplex_mode,
|
||||
color_mode=printer.color_mode,
|
||||
paper_size=printer.paper_size,
|
||||
collate=printer.collate,
|
||||
)
|
||||
|
||||
buf = io.BytesIO()
|
||||
driver_zip_path = cfg.DRIVERS_DIR + "/" + driver.sha256 # raw driver ZIP bytes
|
||||
driver_bytes = open(driver_zip_path, "rb").read()
|
||||
|
||||
with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATE) as zf:
|
||||
safe_name = printer.name.replace(" ", "_")
|
||||
zf.writestr(f"{safe_name}/install.ps1", script)
|
||||
# Expand driver ZIP into drivers/ subfolder
|
||||
with zipfile.ZipFile(io.BytesIO(driver_bytes)) as driver_zf:
|
||||
for name in driver_zf.namelist():
|
||||
zf.writestr(f"{safe_name}/drivers/{name}", driver_zf.read(name))
|
||||
|
||||
filename = f"{safe_name}_ninja.zip"
|
||||
return Response(
|
||||
content=buf.getvalue(),
|
||||
media_type="application/zip",
|
||||
headers={"Content-Disposition": f'attachment; filename="{filename}"'},
|
||||
)
|
||||
```
|
||||
|
||||
### Pattern 2: .intunewin Package via Temp Directory
|
||||
**What:** Stage files to `tempfile.mkdtemp()`, call `build_intunewin()`, read output file, clean up
|
||||
**When to use:** PKG-01/PKG-02 — Intune export
|
||||
**Example:**
|
||||
```python
|
||||
# Source: imptune/generators/intunewin_builder.py (Phase 1 spike)
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import tempfile
|
||||
import zipfile
|
||||
from fastapi.responses import Response
|
||||
from imptune.generators.intunewin_builder import build_intunewin
|
||||
from imptune.generators.script_generator import render_install, render_uninstall, render_detect
|
||||
|
||||
@router.get("/{printer_id}/packages/intunewin")
|
||||
def download_intunewin(printer_id: int):
|
||||
# ... fetch printer + driver, validate ...
|
||||
|
||||
tmpdir = tempfile.mkdtemp()
|
||||
try:
|
||||
# 1. Write rendered scripts
|
||||
open(os.path.join(tmpdir, "install.ps1"), "w").write(render_install(...))
|
||||
open(os.path.join(tmpdir, "uninstall.ps1"), "w").write(render_uninstall(...))
|
||||
open(os.path.join(tmpdir, "detect.ps1"), "w").write(render_detect(...))
|
||||
|
||||
# 2. Expand driver ZIP into drivers/ subfolder
|
||||
drivers_subdir = os.path.join(tmpdir, "drivers")
|
||||
os.makedirs(drivers_subdir)
|
||||
driver_zip_path = os.path.join(cfg.DRIVERS_DIR, driver.sha256)
|
||||
with zipfile.ZipFile(driver_zip_path) as zf:
|
||||
zf.extractall(drivers_subdir)
|
||||
|
||||
# 3. Optionally copy icon
|
||||
icon = getattr(printer, "icons", None)
|
||||
# ... copy icon if it exists ...
|
||||
|
||||
# 4. Build .intunewin
|
||||
output_path = os.path.join(tmpdir, "package.intunewin")
|
||||
build_intunewin(tmpdir, "install.ps1", output_path)
|
||||
|
||||
# 5. Read and return
|
||||
content = open(output_path, "rb").read()
|
||||
safe_name = printer.name.replace(" ", "_")
|
||||
return Response(
|
||||
content=content,
|
||||
media_type="application/octet-stream",
|
||||
headers={"Content-Disposition": f'attachment; filename="{safe_name}.intunewin"'},
|
||||
)
|
||||
finally:
|
||||
shutil.rmtree(tmpdir, ignore_errors=True)
|
||||
```
|
||||
|
||||
### Pattern 3: PNG Icon Upload and Validation
|
||||
**What:** Accept PNG via `UploadFile`, validate format + dimensions + size, store SHA256-addressed on disk
|
||||
**When to use:** PKG-04 — icon upload
|
||||
**Example:**
|
||||
```python
|
||||
# Source: imptune/api/drivers.py upload pattern
|
||||
from fastapi import UploadFile
|
||||
from PIL import Image # if Pillow added
|
||||
|
||||
MAX_ICON_BYTES = 750 * 1024 # 750 KB
|
||||
|
||||
@router.post("/{printer_id}/icon")
|
||||
def upload_icon(printer_id: int, file: UploadFile):
|
||||
data = file.file.read(MAX_ICON_BYTES + 1)
|
||||
if len(data) > MAX_ICON_BYTES:
|
||||
return _error_response("Icon exceeds 750 KB limit.")
|
||||
|
||||
# Validate PNG format and dimensions
|
||||
try:
|
||||
img = Image.open(io.BytesIO(data))
|
||||
if img.format != "PNG":
|
||||
return _error_response("Icon must be PNG format.")
|
||||
if img.size != (256, 256):
|
||||
return _error_response(f"Icon must be 256x256 pixels, got {img.size}.")
|
||||
except Exception:
|
||||
return _error_response("Invalid image file.")
|
||||
|
||||
# Store SHA256-addressed (same as DriverStore pattern)
|
||||
sha256 = hashlib.sha256(data).hexdigest()
|
||||
icons_dir = Path(cfg.DATA_DIR) / "icons"
|
||||
icons_dir.mkdir(parents=True, exist_ok=True)
|
||||
dest = icons_dir / sha256
|
||||
if not dest.exists():
|
||||
dest.write_bytes(data)
|
||||
|
||||
# Upsert Icon ORM record (model already exists in models.py)
|
||||
Icon.get_or_none(Icon.printer == printer_id) # delete old if exists
|
||||
Icon.create(printer=printer_id, sha256=sha256,
|
||||
original_filename=file.filename, size_bytes=len(data))
|
||||
# ... return success partial ...
|
||||
```
|
||||
|
||||
### Pattern 4: Alpine.js Copy-to-Clipboard
|
||||
**What:** Display command string in a `<code>` element; Alpine.js copies it on button click
|
||||
**When to use:** PKG-05 — Intune command preview
|
||||
**Example:**
|
||||
```html
|
||||
<!-- Source: Alpine.js project pattern (already loaded in base.html) -->
|
||||
<div x-data="{ copied: false }">
|
||||
<code id="install-cmd">powershell.exe -ExecutionPolicy Bypass -File install.ps1</code>
|
||||
<button @click="navigator.clipboard.writeText($el.previousElementSibling.innerText);
|
||||
copied = true; setTimeout(() => copied = false, 2000)"
|
||||
x-text="copied ? 'Copied!' : 'Copy'">
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- **Writing temp files and not cleaning up:** Always use `try/finally: shutil.rmtree(tmpdir)` — unhandled exceptions skip cleanup
|
||||
- **Including all files in inner ZIP including uninstall/detect:** build_intunewin() packages everything in tmpdir; if uninstall.ps1 should be separate, do NOT put it in tmpdir — it becomes part of the .intunewin payload, which is fine for Intune (it uses SetupFile="install.ps1" as the entry point)
|
||||
- **Using os.path.join with driver SHA256 directly:** SHA256 is 64 hex chars — safe as a filename but must use `cfg.DRIVERS_DIR` dynamically (monkeypatch pattern from Phase 2)
|
||||
- **Reading ICONS_DIR as a module-level constant:** Same pattern as DRIVERS_DIR — read `cfg.DATA_DIR` at call time, not import time, so tests can monkeypatch
|
||||
|
||||
---
|
||||
|
||||
## Don't Hand-Roll
|
||||
|
||||
| Problem | Don't Build | Use Instead | Why |
|
||||
|---------|-------------|-------------|-----|
|
||||
| AES-256-CBC encryption | Custom crypto | `pycryptodome` (already installed) | Padding oracle attacks, IV reuse bugs |
|
||||
| ZIP assembly | Custom byte writer | `zipfile.ZipFile` + `io.BytesIO` | ZIP format edge cases (compression flags, CRC, central directory) |
|
||||
| PNG format detection + dimensions | Manual byte parsing | Pillow `Image.open()` | PNG IHDR chunk parsing is 20 lines of struct code that breaks on edge cases |
|
||||
| Filename sanitization in ZIPs | Custom strip | Explicit allowlist + `replace()` | Zip-slip paths (`../` prefix) — already handled in drivers.py |
|
||||
|
||||
**Key insight:** The hard crypto work (intunewin format) is already done. Phase 5 is assembly and routing only.
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: Temp Directory Leaking on Exception
|
||||
**What goes wrong:** `tempfile.mkdtemp()` creates a directory that persists if an exception is raised before `shutil.rmtree()`
|
||||
**Why it happens:** Any error in script rendering, driver extraction, or `build_intunewin()` bypasses cleanup
|
||||
**How to avoid:** Always wrap in `try/finally` block; alternatively use `tempfile.TemporaryDirectory()` as a context manager (auto-cleanup on `__exit__`)
|
||||
**Warning signs:** `/tmp` fills up with `tmp*` directories after repeated export calls
|
||||
|
||||
### Pitfall 2: build_intunewin() Includes Unexpected Files
|
||||
**What goes wrong:** `build_intunewin()` walks the entire `source_dir` recursively — any extra file added to tmpdir ends up in the package
|
||||
**Why it happens:** The function design is "pack everything in this directory"
|
||||
**How to avoid:** Only write `install.ps1`, `detect.ps1`, `uninstall.ps1`, and `drivers/` into tmpdir; if icon is embedded in the .intunewin, add it as a known filename (e.g., `icon.png`) at tmpdir root
|
||||
|
||||
### Pitfall 3: driver.sha256 File Not Found
|
||||
**What goes wrong:** Driver file on disk was deleted but ORM record remains, causing `FileNotFoundError` during export
|
||||
**Why it happens:** No referential integrity between ORM and filesystem
|
||||
**How to avoid:** Check `Path(cfg.DRIVERS_DIR, driver.sha256).exists()` before proceeding; return HTTP 422 with descriptive message
|
||||
|
||||
### Pitfall 4: Icon Model Unique Constraint Violation
|
||||
**What goes wrong:** `Icon` model has `unique=True` on the `printer` ForeignKey — second upload raises `IntegrityError`
|
||||
**Why it happens:** `Icon.create()` called without checking/deleting existing record
|
||||
**How to avoid:** Use `Icon.get_or_none(Icon.printer == printer_id)` then `.delete_instance()` before `Icon.create()`, or use `INSERT OR REPLACE` via Peewee's `replace()` method
|
||||
|
||||
### Pitfall 5: driver_desc JSON Parse Failure in Export Endpoint
|
||||
**What goes wrong:** `driver.driver_desc` contains malformed JSON or None
|
||||
**Why it happens:** Edge case — driver was saved without running INF parsing
|
||||
**How to avoid:** Reuse `_get_printer_and_driver()` helper from `scripts.py` — it already handles this with HTTP 422 responses
|
||||
|
||||
### Pitfall 6: .intunewin Not Accepted by Intune Tenant
|
||||
**What goes wrong:** Real Intune upload rejects the package despite passing all unit tests
|
||||
**Why it happens:** The byte-level format was reverse-engineered from community documentation (svrooij.io), not from Microsoft's official spec
|
||||
**How to avoid:** Manual validation gate — upload a test `.intunewin` to a real Intune tenant before Phase 5 is marked complete (documented as Phase 5 blocker in STATE.md)
|
||||
|
||||
### Pitfall 7: Alpine.js Clipboard on HTTP (non-HTTPS)
|
||||
**What goes wrong:** `navigator.clipboard.writeText()` throws `NotAllowedError` in some browsers when page is served over plain HTTP
|
||||
**Why it happens:** Clipboard API requires secure context (HTTPS or localhost) in modern browsers
|
||||
**How to avoid:** This tool runs on internal network, typically accessed via IP address. Provide a fallback: show the command text in a `<textarea>` with `select()` + `document.execCommand('copy')` as fallback, or simply display the text prominently and let users copy manually. For localhost access, clipboard API works fine.
|
||||
|
||||
---
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Build .intunewin and return as download
|
||||
```python
|
||||
# Source: imptune/generators/intunewin_builder.py (Phase 1) + FastAPI Response pattern
|
||||
import os
|
||||
import shutil
|
||||
import tempfile
|
||||
import zipfile
|
||||
from fastapi.responses import Response
|
||||
from imptune.generators.intunewin_builder import build_intunewin
|
||||
|
||||
def _build_and_serve_intunewin(printer, driver, driver_name) -> Response:
|
||||
tmpdir = tempfile.mkdtemp(prefix="imptune_")
|
||||
try:
|
||||
# Write scripts
|
||||
(Path(tmpdir) / "install.ps1").write_text(render_install(...))
|
||||
(Path(tmpdir) / "detect.ps1").write_text(render_detect(printer.name))
|
||||
|
||||
# Expand driver ZIP into drivers/ subfolder
|
||||
driver_path = Path(cfg.DRIVERS_DIR) / driver.sha256
|
||||
drivers_dir = Path(tmpdir) / "drivers"
|
||||
drivers_dir.mkdir()
|
||||
with zipfile.ZipFile(driver_path) as zf:
|
||||
zf.extractall(str(drivers_dir))
|
||||
|
||||
# Build .intunewin
|
||||
output = str(Path(tmpdir) / "out.intunewin")
|
||||
build_intunewin(str(tmpdir), "install.ps1", output)
|
||||
|
||||
content = Path(output).read_bytes()
|
||||
safe = printer.name.replace(" ", "_")
|
||||
return Response(
|
||||
content=content,
|
||||
media_type="application/octet-stream",
|
||||
headers={"Content-Disposition": f'attachment; filename="{safe}.intunewin"'},
|
||||
)
|
||||
finally:
|
||||
shutil.rmtree(tmpdir, ignore_errors=True)
|
||||
```
|
||||
|
||||
### NinjaRMM ZIP in-memory
|
||||
```python
|
||||
# Source: stdlib zipfile + io.BytesIO (project pattern from drivers.py)
|
||||
buf = io.BytesIO()
|
||||
with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATE) as zf:
|
||||
safe = printer.name.replace(" ", "_")
|
||||
zf.writestr(f"{safe}/install.ps1", install_script_text)
|
||||
driver_path = Path(cfg.DRIVERS_DIR) / driver.sha256
|
||||
with zipfile.ZipFile(driver_path) as drv:
|
||||
for member in drv.infolist():
|
||||
zf.writestr(f"{safe}/drivers/{member.filename}", drv.read(member.filename))
|
||||
return Response(
|
||||
content=buf.getvalue(),
|
||||
media_type="application/zip",
|
||||
headers={"Content-Disposition": f'attachment; filename="{safe}_ninja.zip"'},
|
||||
)
|
||||
```
|
||||
|
||||
### Intune command strings (rendered server-side)
|
||||
```python
|
||||
# Source: Intune Win32 app documentation pattern
|
||||
# Install command: PowerShell with execution policy bypass, relative script path
|
||||
install_cmd = f"powershell.exe -ExecutionPolicy Bypass -File install.ps1"
|
||||
# Uninstall command: same pattern
|
||||
uninstall_cmd = f"powershell.exe -ExecutionPolicy Bypass -File uninstall.ps1"
|
||||
```
|
||||
These strings are static for all printers (the script handles printer-specific config internally). They are rendered into the template as Jinja2 variables.
|
||||
|
||||
---
|
||||
|
||||
## State of the Art
|
||||
|
||||
| Old Approach | Current Approach | When Changed | Impact |
|
||||
|--------------|------------------|--------------|--------|
|
||||
| IntuneWinAppUtil.exe (Windows PE) | Python-native AES-256-CBC + zipfile | Phase 1 | Enables Linux Docker container; eliminates Wine/QEMU dependency |
|
||||
| Write to disk, stream file | In-memory `io.BytesIO` → `Response.content` | Project standard | Simpler, no cleanup needed for small packages |
|
||||
|
||||
**Deprecated/outdated:**
|
||||
- `imghdr` module: deprecated in Python 3.11, removed in 3.13. Project uses Python 3.12 — `imghdr` still works but Pillow is preferred for dimension validation.
|
||||
- `@app.on_event("startup")`: Not used in this project (lifespan pattern established in Plan 01-01).
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Does Pillow need to be added to requirements.txt?**
|
||||
- What we know: PKG-04 requires 256x256 dimension validation; `imghdr` cannot check dimensions
|
||||
- What's unclear: Acceptable to add Pillow to a minimal-dependencies project?
|
||||
- Recommendation: Add `Pillow>=10.0` to requirements.txt. Alternative is manual PNG IHDR struct parse (20 lines, error-prone). Pillow is well-maintained, pure wheel available for linux/amd64.
|
||||
|
||||
2. **Should `uninstall.ps1` be included in the .intunewin package?**
|
||||
- What we know: Intune Win32 apps have a separate "uninstall command" field pointing to the uninstall script; the script must be inside the .intunewin package
|
||||
- What's unclear: Should `uninstall.ps1` be in the package root alongside `install.ps1`?
|
||||
- Recommendation: Yes — include `install.ps1`, `uninstall.ps1`, `detect.ps1`, and `drivers/` in tmpdir. All three scripts become part of the package payload. Intune's SetupFile points to `install.ps1`.
|
||||
|
||||
3. **Real Intune tenant validation gate**
|
||||
- What we know: Unit tests pass; format was reverse-engineered from svrooij.io
|
||||
- What's unclear: Whether the package is accepted by a real Intune tenant
|
||||
- Recommendation: Manual gate — a human must upload a test `.intunewin` to Intune before marking PKG-01/PKG-02 done. This is already documented in STATE.md as a blocker concern.
|
||||
|
||||
---
|
||||
|
||||
## Validation Architecture
|
||||
|
||||
### Test Framework
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Framework | pytest (inferred from existing test suite) |
|
||||
| Config file | none detected — runs with `pytest tests/` |
|
||||
| Quick run command | `pytest tests/test_packages.py -x` |
|
||||
| Full suite command | `pytest tests/ -x` |
|
||||
|
||||
### Phase Requirements → Test Map
|
||||
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
||||
|--------|----------|-----------|-------------------|-------------|
|
||||
| PKG-01 | .intunewin endpoint returns valid ZIP with correct MIME type and Content-Disposition | integration | `pytest tests/test_packages.py::TestIntunewinDownload -x` | Wave 0 |
|
||||
| PKG-02 | Verify no `IntuneWinAppUtil.exe` subprocess calls; Python-only assembly | unit | `pytest tests/test_intunewin.py -x` | exists |
|
||||
| PKG-03 | NinjaRMM ZIP endpoint returns ZIP containing install.ps1 and drivers/ subfolder | integration | `pytest tests/test_packages.py::TestNinjaDownload -x` | Wave 0 |
|
||||
| PKG-04 | Icon upload rejects non-PNG, oversized, wrong dimensions; accepted icon stored and retrievable | integration | `pytest tests/test_icon_upload.py -x` | Wave 0 |
|
||||
| PKG-05 | Printer detail page renders install_cmd and uninstall_cmd strings | integration | `pytest tests/test_packages.py::TestCommandPreview -x` | Wave 0 |
|
||||
|
||||
### Sampling Rate
|
||||
- **Per task commit:** `pytest tests/test_packages.py tests/test_icon_upload.py -x`
|
||||
- **Per wave merge:** `pytest tests/ -x`
|
||||
- **Phase gate:** Full suite green + manual .intunewin upload to real Intune tenant
|
||||
|
||||
### Wave 0 Gaps
|
||||
- [ ] `tests/test_packages.py` — covers PKG-01, PKG-03, PKG-05
|
||||
- [ ] `tests/test_icon_upload.py` — covers PKG-04
|
||||
- [ ] `requirements.txt` — add `Pillow>=10.0` if icon dimension validation is implemented
|
||||
|
||||
*(PKG-02: existing `tests/test_intunewin.py` already covers the format — no new test file needed)*
|
||||
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- `imptune/generators/intunewin_builder.py` — Complete Phase 1 implementation; AES-256-CBC format, IV=16 bytes, inner ZIP DEFLATE / outer ZIP STORED
|
||||
- `imptune/db/models.py` — `Icon` model with unique FK to `Printer`; already in schema
|
||||
- `imptune/api/drivers.py` — `UploadFile` pattern, error response conventions, size validation
|
||||
- `imptune/api/scripts.py` — `_get_printer_and_driver()` helper pattern for 404/422 guard
|
||||
- `imptune/config.py` — `DATA_DIR`, `DRIVERS_DIR` — add `ICONS_DIR` here
|
||||
- FastAPI docs (0.115) — `Response(content=bytes, media_type=..., headers=...)` for binary downloads
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- STATE.md accumulated decisions — lifespan pattern, monkeypatch cfg pattern, HTMX error fragment conventions
|
||||
- Intune Win32 app command format: `powershell.exe -ExecutionPolicy Bypass -File install.ps1` — standard community pattern
|
||||
|
||||
### Tertiary (LOW confidence)
|
||||
- svrooij.io .intunewin reverse-engineering — basis for Phase 1 implementation; not an official Microsoft spec
|
||||
- Alpine.js clipboard API behavior on HTTP vs HTTPS — browser-specific; localhost exemption is documented but may vary
|
||||
|
||||
---
|
||||
|
||||
## Metadata
|
||||
|
||||
**Confidence breakdown:**
|
||||
- Standard stack: HIGH — all libraries are already in the project or stdlib
|
||||
- Architecture: HIGH — assembly pattern follows established project conventions exactly
|
||||
- Pitfalls: HIGH — temp dir cleanup and Icon uniqueness are concrete, verifiable issues
|
||||
- .intunewin Intune acceptance: MEDIUM — format is implemented but tenant acceptance is unvalidated
|
||||
|
||||
**Research date:** 2026-04-10
|
||||
**Valid until:** 2026-05-10 (stable domain — stdlib + existing project code)
|
||||
@@ -0,0 +1,103 @@
|
||||
---
|
||||
phase: 5
|
||||
slug: package-export
|
||||
status: draft
|
||||
nyquist_compliant: true
|
||||
wave_0_complete: false
|
||||
created: 2026-04-10
|
||||
nyquist_audited: 2026-04-13
|
||||
nyquist_auditor: Claude (gsd-executor, plan 08-05)
|
||||
---
|
||||
|
||||
# Phase 5 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | pytest (existing test suite) |
|
||||
| **Config file** | none — runs with `pytest tests/` |
|
||||
| **Quick run command** | `pytest tests/test_packages.py tests/test_icon_upload.py -x` |
|
||||
| **Full suite command** | `pytest tests/ -x` |
|
||||
| **Estimated runtime** | ~10 seconds |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** Run `pytest tests/test_packages.py tests/test_icon_upload.py -x`
|
||||
- **After every plan wave:** Run `pytest tests/ -x`
|
||||
- **Before `/gsd:verify-work`:** Full suite must be green
|
||||
- **Max feedback latency:** 10 seconds
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
|
||||
|---------|------|------|-------------|-----------|-------------------|-------------|--------|
|
||||
| 05-01-01 | 01 | 1 | PKG-03 | integration | `pytest tests/test_packages.py::TestNinjaDownload -x` | ❌ W0 | ⬜ pending |
|
||||
| 05-02-01 | 02 | 1 | PKG-01 | integration | `pytest tests/test_packages.py::TestIntunewinDownload -x` | ❌ W0 | ⬜ pending |
|
||||
| 05-02-02 | 02 | 1 | PKG-02 | unit | `pytest tests/test_intunewin.py -x` | ✅ | ⬜ pending |
|
||||
| 05-03-01 | 03 | 2 | PKG-04 | integration | `pytest tests/test_icon_upload.py -x` | ❌ W0 | ⬜ pending |
|
||||
| 05-03-02 | 03 | 2 | PKG-05 | integration | `pytest tests/test_packages.py::TestCommandPreview -x` | ❌ W0 | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- [ ] `tests/test_packages.py` — stubs for PKG-01, PKG-03, PKG-05
|
||||
- [ ] `tests/test_icon_upload.py` — stubs for PKG-04
|
||||
- [ ] `requirements.txt` — add `Pillow>=10.0` if icon dimension validation is implemented
|
||||
|
||||
*PKG-02: existing `tests/test_intunewin.py` already covers the format — no new test file needed.*
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
| Behavior | Requirement | Why Manual | Test Instructions |
|
||||
|----------|-------------|------------|-------------------|
|
||||
| .intunewin accepted by real Intune tenant | PKG-01 | Requires live Azure/Intune environment | Upload generated .intunewin via Intune portal → verify app appears without errors |
|
||||
|
||||
---
|
||||
|
||||
## Nyquist Record
|
||||
|
||||
> Audited 2026-04-13 by Claude (gsd-executor, plan 08-05). One row per Phase 5 success criterion derived from `milestones/v1.0-ROADMAP.md` Phase 5 goal + PKG-01..05 (`REQUIREMENTS.md` v1.0 block), cross-checked against `05-VERIFICATION.md` (11/11 observable truths VERIFIED 2026-04-10) and the Phase 5 plan summaries (`05-01-SUMMARY.md`, `05-02-SUMMARY.md`). Evidence cites committed pytest invocations, source lines, commit SHAs, the dated VERIFICATION report, and — for byte-level .intunewin conformance — Phase 10 `RUNTIME-VALIDATION.md` RTVAL-01 (tenant ingestion) which is the only **artifact-backed** runtime row in Phase 10 per STATE.md 2026-04-13.
|
||||
>
|
||||
> **Phase 5 goal (v1.0-ROADMAP.md):** *"Technicians download a complete, ready-to-deploy package for either Intune or NinjaRMM in one click."*
|
||||
>
|
||||
> **Byte-level .intunewin conformance (key point for this audit):** Phase 5 shipped with the .intunewin format as a MEDIUM confidence concern — `test_intunewin.py` validates 14 byte-level truths (outer ZIP, Detection.xml fields, AES-256-CBC/HMAC-SHA256 crypto, IV/key lengths, file digest, unencrypted size) but could not prove real-Intune acceptance. Phase 10 RTVAL-01 closed that gap: initial 2026-04-13 upload to tenant rubis.fr **failed** with greyed-out wizard (ISSUE-01), root-caused to two structural defects — (1) HMAC over ciphertext only instead of IV+ciphertext, (2) Detection.xml not matching IntuneWinAppUtil.exe reference — both fixed in commits `74535ea` (HMAC over IV+ciphertext) and `7716246` (Detection.xml alignment). Re-test on the fixed build **PASSED** against live tenant rubis.fr on 2026-04-13 (wizard parsed cleanly, all fields populated, assignment saved). Plan 10-03 signed off the result (commit cd2df1e). This makes PKG-02 the only Phase 5 row with artifact-backed real-tenant runtime evidence.
|
||||
>
|
||||
> **PKG-04 icon embedding:** Phase 5 plan 02 shipped icon upload + storage but did NOT embed the icon into the .intunewin output. This was caught by the v1.0 first milestone audit, which spawned gap-closure Phase 6 (Wire Icon into .intunewin Export). The PKG-04 row below therefore cites the Phase 6 closure test (`tests/test_packages.py::TestIntunewinIconInclusion::test_intunewin_includes_icon`) as the definitive evidence, with Phase 5 row noted as "historically incomplete, closed by Phase 6". This mirrors the 08-02 row-6 historical-gap-closure pattern.
|
||||
|
||||
| # | Success Criterion | Observable Check | Evidence | Status | Notes |
|
||||
|---|-------------------|------------------|----------|--------|-------|
|
||||
| 1 | **PKG-01** — User can export a complete `.intunewin` package (install.ps1 + uninstall.ps1 + detect.ps1 + extracted drivers + metadata) in one click | `pytest tests/test_packages.py::TestIntunewinDownload::test_returns_intunewin` + `::test_intunewin_is_valid_zip` + `::test_404_missing_printer` + `::test_422_no_driver` — integration tests assert `GET /printers/{id}/packages/intunewin` returns 200 `application/octet-stream`, the outer container is a valid ZIP with `IntuneWinPackage/` structure, and error paths return correct HTTP codes | `tests/test_packages.py` class `TestIntunewinDownload` (4 tests, all PASS per 05-VERIFICATION.md truth 2); `imptune/api/packages.py` `get_intunewin_package()` lines 97-158 (writes install.ps1/uninstall.ps1/detect.ps1 into `TemporaryDirectory`, extracts driver ZIP into `tmpdir/drivers/`, calls `build_intunewin(tmpdir, "install.ps1", output_path)`); commits `a31c71e` (RED), `dd6cedf` (GREEN); 05-VERIFICATION.md truth 2; Phase 10 `RUNTIME-VALIDATION.md` RTVAL-01 PASS (artifact-backed re-test 2026-04-13 on tenant rubis.fr, package `Copieur_2eme.intunewin` SHA256 `8818124a...`, screenshots `rtval-01-tenant-upload.png` + `rtval-01-app-assigned.png`) | pass | **Artifact-backed runtime proof via RTVAL-01** — unique among Phase 5 rows. Intune Win32 wizard parsed the generated `.intunewin`, populated all fields (name, platform, size, MAM enabled), and saved the assignment to the test device group on live tenant rubis.fr. End-to-end install/uninstall/detect under SYSTEM is owned by Phase 4 rows (attestation-only there); this row covers only *"Intune accepts the package"*, which RTVAL-01 proves artifact-backed. |
|
||||
| 2 | **PKG-02** — `.intunewin` is generated natively in Python (no `IntuneWinAppUtil.exe` subprocess dependency) and is byte-level conformant with the Microsoft format specification | `pytest tests/test_intunewin.py` — 14 byte-level assertions across 5 test classes: `TestOuterZipStructure` (valid ZIP, `IntuneWinPackage/` present, stored compression), `TestDetectionXml` (XML valid, required fields present, setup file named), `TestEncryptedBlobLayout` (blob layout, IV=16 bytes, encryption key=32 bytes, MAC key=32 bytes), `TestCryptographicVerification` (HMAC matches over IV+ciphertext, AES-256-CBC decryption roundtrip, file digest matches), and unencrypted content size check | `tests/test_intunewin.py` (14 tests, all PASS — existing test file per 05-VERIFICATION.md Wave 0 note "tests/test_intunewin.py already covers the format"); `imptune/generators/intunewin_builder.py` (`build_intunewin()`, AES-256-CBC + HMAC-SHA256 + Detection.xml generator); `imptune/api/packages.py` line 149 `build_intunewin(tmpdir, "install.ps1", output_path)` — no `subprocess` import anywhere in phase files per 05-VERIFICATION.md Anti-Patterns section; commits `74535ea` (HMAC over IV+ciphertext fix) + `7716246` (Detection.xml aligned with IntuneWinAppUtil.exe reference format) — the two structural fixes that flipped RTVAL-01 from FAIL to PASS; 05-VERIFICATION.md truth 5; Phase 10 `RUNTIME-VALIDATION.md` RTVAL-01 **artifact-backed PASS** on tenant rubis.fr (2026-04-13, evidence `rtval-01-tenant-upload.png`, `rtval-01-app-assigned.png`, `Copieur_2eme.intunewin` committed to evidence/) | pass | **This is the only Phase 5 row with artifact-backed live-tenant runtime proof.** Closes the MEDIUM-confidence gap that 05-VERIFICATION.md flagged as "Human Verification Required #1: .intunewin byte-level Intune compatibility". Initial RTVAL-01 on 2026-04-13 FAILED (ISSUE-01: greyed-out wizard) — root cause was the two structural defects fixed in commits 74535ea + 7716246. Re-test on fixed build PASSED: Intune parsed the .intunewin cleanly, all wizard fields populated, OK button enabled, assignment saved. Plan 10-03 signed off (commit cd2df1e). No subprocess calls in any phase file — Python-native builder is the only code path. |
|
||||
| 3 | **PKG-03** — User can export a NinjaRMM ZIP package (rendered `install.ps1` + extracted driver folder) in one click | `pytest tests/test_packages.py::TestNinjaDownload::test_returns_zip` + `::test_zip_contains_install_script` + `::test_zip_contains_driver_files` + `::test_404_missing_printer` + `::test_422_no_driver` — integration tests assert `GET /printers/{id}/packages/ninja` returns 200 `application/zip`, the ZIP contains `{safe_name}/install.ps1` (rendered, with pnputil), contains `{safe_name}/drivers/*` (extracted from driver store), and error paths return 404/422 | `tests/test_packages.py` class `TestNinjaDownload` (5 tests, all PASS per 05-VERIFICATION.md truths 1 + 4); `imptune/api/packages.py` `get_ninja_package()` lines 49-94 (in-memory `io.BytesIO` + `zipfile.ZipFile(ZIP_DEFLATED)`, `{safe_name}/install.ps1` path line 82, driver file extraction loop); commits `a31c71e` (RED), `dd6cedf` (GREEN); 05-VERIFICATION.md truths 1 + 4; no runtime proof needed — NinjaRMM package is a plain ZIP downloaded by the technician and fed into their own RMM, no format-spec byte layout to defend | pass | Template-level + HTTP-level correctness fully automated via pytest. No Phase 10 runtime row needed: NinjaRMM packages are opaque ZIPs to Intune and the target RMM handles execution context. Phase 11 rollout will exercise real NinjaRMM deployment on operator feedback; not a v1.0 milestone concern. |
|
||||
| 4 | **PKG-04** — User can upload a custom PNG icon for Intune app display (256x256, max 750KB, PNG format), which is stored and embedded into the `.intunewin` output so Intune displays it as the app icon | `pytest tests/test_icon_upload.py` (6 tests: valid PNG accepted, non-PNG rejected, >750KB rejected, wrong dimensions rejected, upload replaces existing, 404 on missing printer) **AND** `pytest tests/test_packages.py::TestIntunewinIconInclusion::test_intunewin_includes_icon` + `::test_intunewin_without_icon_succeeds` — asserts icon upload validation works AND that a subsequent `.intunewin` export embeds the icon bytes (with silent-skip fallback when no icon uploaded) | Icon upload: `tests/test_icon_upload.py` (6 tests PASS per 05-VERIFICATION.md truths 6+7+8); `imptune/api/icons.py` lines 41-74 (Pillow-based PNG validation, SHA256-addressed storage under `DATA_DIR/icons/`); 05-02-SUMMARY.md commits `d8ce223` (RED) + `f9e13ba` (GREEN). Icon→.intunewin embedding (PKG-04 gap closure): `tests/test_packages.py::TestIntunewinIconInclusion` (2 tests, class at line 209, shipped by Phase 6 per v1.0-ROADMAP.md Phase 6 "Wire Icon into .intunewin Export"); 05-VERIFICATION.md truths 6+7+8 for upload half; v1.0-ROADMAP.md "Issues Resolved" entry: *"PKG-04 icon→.intunewin wiring break (Phase 6)"*; Phase 10 `RUNTIME-VALIDATION.md` RTVAL-01 PASS (the package that Intune accepted was `Copieur_2eme.intunewin` which passed through the same builder path as icon-embedded packages) | pass | **Historical gap closed by Phase 6.** Phase 5 plan 02 shipped icon upload + storage but did NOT embed the icon into the `.intunewin` output — caught by the v1.0 first milestone audit. Phase 6 (Wire Icon into .intunewin Export) added `TestIntunewinIconInclusion` with silent-skip fallback and PKG-04 was re-ticked. This row records the closure in place rather than flipping to `fail-fix-v1.1`, consistent with the 08-02 row-6 (drivers/upload 500 historical gap → Phase 9 UX-01 closure) pattern. Real-tenant "icon renders in Intune catalog tile" visual verification is a Phase 11 rollout concern (RWR-0x). |
|
||||
| 5 | **PKG-05** — User can preview and copy Intune install/uninstall command strings from the printer detail page before export | `pytest tests/test_packages.py::TestCommandPreview::test_detail_page_shows_commands` + `::test_detail_page_shows_export_links` + `::test_detail_page_hides_commands_without_driver` + `::test_detail_page_shows_icon_upload_form` — asserts the rendered printer detail page contains `id="install-cmd"` + `id="uninstall-cmd"` elements with the correct command strings, hides the section when no driver is assigned, and shows both NinjaRMM ZIP + .intunewin export links | `tests/test_packages.py` class `TestCommandPreview` (4 tests PASS per 05-VERIFICATION.md truths 9+10+11); `imptune/api/pages.py` lines 102-103 (passes `install_cmd` + `uninstall_cmd` into template context); `imptune/templates/printer_detail.html` lines 31+40 (`id="install-cmd"`, `id="uninstall-cmd"`), lines 32-36 + 41-45 (Alpine.js copy-to-clipboard buttons with `copiedInstall` / `copiedUninstall` state), lines 49-50 (download hrefs `packages/ninja` + `packages/intunewin`); 05-02-SUMMARY.md commit `f96ea6f`; 05-VERIFICATION.md truths 9+10+11 | pass | Alpine.js copy-to-clipboard UX (clipboard API interaction, "Copied!" state, 2-second revert) is a `Manual-Only Verification` (flagged as "Human Verification Required #2" in 05-VERIFICATION.md) and was NOT exercised in Phase 10 — Phase 10 focused exclusively on SYSTEM-context runtime, not HTMX/Alpine browser reactivity. Template-level correctness (element IDs, conditional rendering, href targets, command string content) is fully automated via pytest. The minor cosmetic "Uninstall copy" vs "Copy" label inconsistency flagged in 05-VERIFICATION.md Anti-Patterns is a UX polish item, not a correctness defect, and does not affect the success criterion. |
|
||||
|
||||
**Audit outcome:** 5/5 rows `pass`. No `fail-fix-v1.1`, `deferred-v1.2`, or `wont-do` rows. Phase 5 is Nyquist-compliant. **Row 2 (PKG-02) is the only row in the entire 7-phase v1.0 Nyquist audit track with artifact-backed live-Intune-tenant runtime evidence** — RTVAL-01 (tenant rubis.fr, 2026-04-13, screenshots committed) proves the byte-level `.intunewin` format is accepted by real Intune after the two structural fixes in commits `74535ea` + `7716246` flipped the initial FAIL into a PASS. Row 4 (PKG-04) records the historical icon-embedding gap and its Phase 6 closure in place rather than inflating to `fail-fix-v1.1`. No other gaps carry forward into 08-08 rollup for Phase 5 beyond what STATE.md already tracks.
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
|
||||
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
|
||||
- [ ] Wave 0 covers all MISSING references
|
||||
- [ ] No watch-mode flags
|
||||
- [ ] Feedback latency < 10s
|
||||
- [x] `nyquist_compliant: true` set in frontmatter
|
||||
- [x] Nyquist audit complete — 2026-04-13 — Sébastien QUEROL
|
||||
|
||||
**Approval:** Nyquist-audited 2026-04-13 by Claude (gsd-executor, plan 08-05) — 5/5 pass (PKG-02 only artifact-backed live-tenant runtime row in track); signed off 2026-04-13 by Sébastien QUEROL (index: v1.0-VALIDATION-INDEX.md)
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
phase: 05-package-export
|
||||
verified: 2026-04-10T14:00:00Z
|
||||
status: passed
|
||||
score: 11/11 must-haves verified
|
||||
re_verification: false
|
||||
---
|
||||
|
||||
# Phase 5: Package Export Verification Report
|
||||
|
||||
**Phase Goal:** Package export — NinjaRMM ZIP download, .intunewin download, icon upload, export UI controls
|
||||
**Verified:** 2026-04-10T14:00:00Z
|
||||
**Status:** passed
|
||||
**Re-verification:** No — initial verification
|
||||
|
||||
---
|
||||
|
||||
## Goal Achievement
|
||||
|
||||
### Observable Truths
|
||||
|
||||
#### Plan 01 Truths (PKG-01 / PKG-02 / PKG-03)
|
||||
|
||||
| # | Truth | Status | Evidence |
|
||||
|---|-------|--------|----------|
|
||||
| 1 | GET /printers/{id}/packages/ninja returns a ZIP containing install.ps1 and drivers/ subfolder | VERIFIED | `imptune/api/packages.py` lines 49–94; `test_zip_contains_install_script`, `test_zip_contains_driver_files` both PASS |
|
||||
| 2 | GET /printers/{id}/packages/intunewin returns a valid .intunewin file with correct Content-Disposition | VERIFIED | `packages.py` lines 97–158; `test_returns_intunewin`, `test_intunewin_is_valid_zip` both PASS |
|
||||
| 3 | Both endpoints return 404 for missing printer, 422 for missing/invalid driver | VERIFIED | `_get_printer_and_driver()` at lines 19–41; all four error tests PASS |
|
||||
| 4 | NinjaRMM ZIP uses DEFLATE compression and has printer-name-based folder structure | VERIFIED | `zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED)` line 80; `{safe_name}/install.ps1` path line 82 |
|
||||
| 5 | .intunewin is built using Python-native build_intunewin() with no subprocess calls | VERIFIED | `build_intunewin(tmpdir, "install.ps1", output_path)` line 149; no subprocess import in packages.py |
|
||||
|
||||
#### Plan 02 Truths (PKG-04 / PKG-05)
|
||||
|
||||
| # | Truth | Status | Evidence |
|
||||
|---|-------|--------|----------|
|
||||
| 6 | User can upload a PNG icon for a printer and it is stored on disk | VERIFIED | `icons.py` lines 70–74; `test_upload_valid_png` asserts Icon DB record + SHA256-addressed file on disk — PASS |
|
||||
| 7 | Icon upload rejects non-PNG files, files over 750KB, and wrong dimensions (not 256x256) | VERIFIED | `icons.py` lines 41–67; `test_reject_non_png`, `test_reject_oversized`, `test_reject_wrong_dimensions` all PASS |
|
||||
| 8 | Re-uploading an icon for the same printer replaces the previous one | VERIFIED | `Icon.delete().where(...).execute()` then `Icon.create(...)` lines 77–83; `test_replace_existing_icon` PASS |
|
||||
| 9 | Printer detail page shows Intune install and uninstall command strings | VERIFIED | `pages.py` lines 102–103; template `id="install-cmd"` and `id="uninstall-cmd"` lines 31/40; `test_detail_page_shows_commands` PASS |
|
||||
| 10 | User can copy the command strings (text displayed prominently for copy) | VERIFIED | Alpine.js copy-to-clipboard buttons in `printer_detail.html` lines 32–36, 41–45 |
|
||||
| 11 | Printer detail page has download links for NinjaRMM ZIP and .intunewin | VERIFIED | Template lines 49–50; `test_detail_page_shows_export_links` PASS |
|
||||
|
||||
**Score: 11/11 truths verified**
|
||||
|
||||
---
|
||||
|
||||
### Required Artifacts
|
||||
|
||||
| Artifact | Expected | Status | Details |
|
||||
|----------|----------|--------|---------|
|
||||
| `imptune/api/packages.py` | NinjaRMM ZIP and .intunewin endpoints; exports `router` | VERIFIED | 159 lines, fully implemented, `router = APIRouter(prefix="/printers")` at line 16 |
|
||||
| `tests/test_packages.py` | Integration tests; contains `TestNinjaDownload` | VERIFIED | 192 lines; `TestNinjaDownload` (5 tests), `TestIntunewinDownload` (4 tests), `TestCommandPreview` (4 tests) |
|
||||
| `imptune/api/icons.py` | Icon upload endpoint; exports `router` | VERIFIED | 89 lines, fully implemented, `router = APIRouter(prefix="/printers")` at line 15 |
|
||||
| `imptune/templates/printer_detail.html` | Export buttons, command preview, icon upload form; contains `install-cmd` | VERIFIED | All three sections present; `id="install-cmd"` line 31, export links lines 49–50, icon form lines 57–63 |
|
||||
| `tests/test_icon_upload.py` | Icon upload validation tests; contains `test_upload_valid_png` | VERIFIED | 141 lines; 6 tests all PASS |
|
||||
|
||||
---
|
||||
|
||||
### Key Link Verification
|
||||
|
||||
#### Plan 01 Key Links
|
||||
|
||||
| From | To | Via | Status | Details |
|
||||
|------|----|-----|--------|---------|
|
||||
| `imptune/api/packages.py` | `imptune/generators/script_generator.py` | `render_install`, `render_uninstall`, `render_detect` | WIRED | `from imptune.generators.script_generator import render_detect, render_install, render_uninstall` line 14; all three called in endpoints |
|
||||
| `imptune/api/packages.py` | `imptune/generators/intunewin_builder.py` | `build_intunewin(source_dir, setup_file, output_path)` | WIRED | `from imptune.generators.intunewin_builder import build_intunewin` line 13; called at line 149 |
|
||||
| `imptune/main.py` | `imptune/api/packages.py` | `app.include_router(packages.router)` | WIRED | `app.include_router(packages.router)` line 38 of main.py |
|
||||
|
||||
#### Plan 02 Key Links
|
||||
|
||||
| From | To | Via | Status | Details |
|
||||
|------|----|-----|--------|---------|
|
||||
| `imptune/api/icons.py` | `imptune/db/models.py` | Icon model CRUD | WIRED | `from imptune.db.models import Icon, Printer` line 13; `Icon.delete()`, `Icon.create()` lines 77–83 |
|
||||
| `imptune/api/icons.py` | `imptune/config.py` | `cfg.DATA_DIR` for icon storage | WIRED | `import imptune.config as cfg` line 12; `Path(cfg.DATA_DIR) / "icons"` line 71 (read at call time — monkeypatch compatible) |
|
||||
| `imptune/main.py` | `imptune/api/icons.py` | `app.include_router(icons.router)` | WIRED | `app.include_router(icons.router)` line 39 of main.py |
|
||||
| `imptune/templates/printer_detail.html` | `/printers/{id}/packages/*` | `href` download links | WIRED | Lines 49–50 contain `packages/ninja` and `packages/intunewin` hrefs; `test_detail_page_shows_export_links` PASS |
|
||||
|
||||
---
|
||||
|
||||
### Requirements Coverage
|
||||
|
||||
| Requirement | Source Plan | Description | Status | Evidence |
|
||||
|-------------|-------------|-------------|--------|----------|
|
||||
| PKG-01 | 05-01 | User can export a complete .intunewin package (script + drivers + detection + metadata) | SATISFIED | `get_intunewin_package()` writes install.ps1, uninstall.ps1, detect.ps1, extracts driver files, calls `build_intunewin()`; `test_intunewin_is_valid_zip` verifies IntuneWinPackage/ structure |
|
||||
| PKG-02 | 05-01 | .intunewin is generated natively in Python (no IntuneWinAppUtil.exe dependency) | SATISFIED | No subprocess in packages.py; `build_intunewin()` is the Python-native builder; no exe calls anywhere in phase files |
|
||||
| PKG-03 | 05-01 | User can export a NinjaRMM ZIP package (install script + driver folder) | SATISFIED | `get_ninja_package()` returns in-memory ZIP with install.ps1 and drivers/; `test_zip_contains_install_script` and `test_zip_contains_driver_files` PASS |
|
||||
| PKG-04 | 05-02 | User can upload a custom PNG icon for Intune app display (256x256, max 750KB) | SATISFIED | `upload_icon()` validates format, size, dimensions; stores SHA256-addressed file; 6 validation tests PASS |
|
||||
| PKG-05 | 05-02 | User can preview and copy Intune install/uninstall command strings before export | SATISFIED | `printer_detail()` passes `install_cmd`/`uninstall_cmd` to context; template renders them in `<code>` elements with Alpine.js copy buttons; `test_detail_page_shows_commands` PASS |
|
||||
|
||||
**Orphaned requirements:** None. All 5 PKG requirements are accounted for across the two plans.
|
||||
|
||||
---
|
||||
|
||||
### Anti-Patterns Found
|
||||
|
||||
No anti-patterns detected in phase files:
|
||||
|
||||
- No TODO/FIXME/PLACEHOLDER comments in any modified file
|
||||
- No empty implementations (`return null`, `return {}`, `return []`)
|
||||
- No stub handlers (all endpoints return substantive responses)
|
||||
- No subprocess calls in intunewin path (Python-native only)
|
||||
- No static return values masking missing DB queries
|
||||
|
||||
One observation (not a blocker): The `printer_detail.html` uninstall copy button has `x-text="copiedUninstall ? 'Copied!' : 'Uninstall copy'"` (line 45) — the false-state label says "Uninstall copy" rather than "Copy". This is a minor UX inconsistency but does not affect functionality or requirement satisfaction.
|
||||
|
||||
---
|
||||
|
||||
### Human Verification Required
|
||||
|
||||
The following items are correct by automated checks but benefit from human review:
|
||||
|
||||
#### 1. .intunewin byte-level Intune compatibility
|
||||
|
||||
**Test:** Upload the generated `.intunewin` to a real Microsoft Intune tenant as an app package.
|
||||
**Expected:** Intune accepts the file without error, detects the app type, and makes it deployable.
|
||||
**Why human:** The `test_intunewin_is_valid_zip` test only verifies the outer ZIP structure contains `IntuneWinPackage/`. Actual Intune parsing validates internal metadata XML, encryption format, and content structure which cannot be verified without a live tenant.
|
||||
|
||||
#### 2. Alpine.js copy-to-clipboard UX
|
||||
|
||||
**Test:** Open the printer detail page in a browser with a driver assigned. Click the "Copy" buttons for install and uninstall commands.
|
||||
**Expected:** Clipboard receives the command string; button briefly shows "Copied!"; reverts to "Copy" after 2 seconds.
|
||||
**Why human:** Clipboard API behavior and Alpine.js reactivity cannot be verified by static analysis or HTTP-level integration tests.
|
||||
|
||||
#### 3. HTMX icon upload response swap
|
||||
|
||||
**Test:** Open printer detail page, upload a valid 256x256 PNG via the icon form.
|
||||
**Expected:** The `#icon-status` div updates inline to show "Icon uploaded successfully" without a full page reload.
|
||||
**Why human:** HTMX swap behavior requires a real browser; TestClient responses do not exercise HTMX interception.
|
||||
|
||||
---
|
||||
|
||||
### Test Suite Results
|
||||
|
||||
| Test File | Tests | Result |
|
||||
|-----------|-------|--------|
|
||||
| `tests/test_packages.py` | 13 | 13 PASSED |
|
||||
| `tests/test_icon_upload.py` | 6 | 6 PASSED |
|
||||
| Full suite (`tests/`) | 94 | 94 PASSED |
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Phase 5 goal is fully achieved. All 11 observable truths are verified against the actual codebase — not just the summary claims. Every artifact is substantive (not a stub), every key link is wired (imports used in real logic), and all 5 PKG requirements are satisfied. The full test suite of 94 tests passes cleanly. Three items are flagged for human verification but none block the goal: they cover Intune tenant compatibility, browser clipboard behavior, and HTMX swap rendering — all of which require a live environment.
|
||||
|
||||
---
|
||||
|
||||
_Verified: 2026-04-10T14:00:00Z_
|
||||
_Verifier: Claude (gsd-verifier)_
|
||||
Reference in New Issue
Block a user