Skip to content

Latest commit

 

History

History
115 lines (96 loc) · 5.06 KB

MODERNIZE.md

File metadata and controls

115 lines (96 loc) · 5.06 KB

MODERNIZE.md - zebra_day Modernization Status

Status: ALL PHASES COMPLETE as of 2.0.0, extended in 2.2.0

This document tracks the modernization of zebra_day from 0.5.0 to 2.2.0.

Completed Modernization Summary

Phase 0 - Hygiene + Guardrails

  • Removed duplicate dependencies
  • Moved dev-only deps to optional extras
  • Implemented structured logging
  • Created custom exceptions
  • Added comprehensive unit tests (102 tests passing, 62% coverage)

Phase 1 - Packaging Modernization

  • Migrated to pyproject.toml (PEP 517/518)
  • Defined optional extras: dev, lint, docs, auth, all
  • Package builds correctly as wheel and sdist
  • PyPI-ready (twine check passes)

Phase 2 - XDG Filesystem Safety

  • Implemented zebra_day/paths.py with XDG Base Directory support
  • Config: ~/.config/zebra_day/ (Linux + macOS; legacy macOS path supported for migration)
  • Data: ~/.local/share/zebra_day/ (Linux) or ~/Library/Application Support/zebra_day/ (macOS)
  • Logs: ~/.local/state/zebra_day/ (Linux) or ~/Library/Logs/zebra_day/ (macOS)
  • Replaced os.system() calls with pathlib + shutil

Phase 3 - Web Stack Modernization

  • Migrated from CherryPy to FastAPI + Uvicorn
  • Implemented Jinja2 templates (13 modern templates)
  • Created versioned API (/api/v1/...)
  • Added OpenAPI documentation (/docs, /redoc)
  • Implemented optional Cognito authentication
  • Created modern UI with Ursa-inspired design system
  • Removed legacy UI (2.0.0) - modern UI only

Phase 4 - Observability

  • Added health endpoints (/healthz, /readyz)
  • Implemented request logging middleware
  • Added structured logging with timestamps

Phase 5 - CI/CD

  • GitHub Actions workflow with lint, test, build, publish jobs
  • Python version matrix (3.10, 3.11, 3.12, 3.13)
  • OS matrix (ubuntu-latest, macos-latest)
  • Ruff linting, Black formatting, mypy type checking
  • Automated PyPI publishing on release

Phase 6 - v2.0.0 Breaking Changes

  • New printer configuration schema with nested printers object
  • Added printer_name, lab_location, manufacturer, notes, default_label_style fields
  • Added lab_name, available_locations, schema_version fields
  • HTTPS by default with mkcert support
  • Removed all legacy UI and bin scripts
  • Pure Python network scanner (replaced shell scripts)

Bonus: Local ZPL Rendering

  • Replaced external Labelary API with local renderer
  • Implemented zebra_day/zpl_renderer.py using Pillow + zint-bindings

Phase 7 - v2.2.0 Enhancements

  • Added lsmc_euid field (Lab Sample Management Container Enterprise Unique ID)
  • Separated Status (network reachability) from State (operational status)
  • Live printer status querying enabled by default
  • Added printer State field: Ready, Paused, Error, Offline, Unknown
  • Fixed ~HS response parsing (pause flag at index 2)
  • Updated CLI zday printer list --live to show Status and State columns
  • Updated Web UI printers table with separate Status and State columns
  • Added 60-second caching for printer status queries
  • 152+ tests passing

Phase 8 - cli-core-yo Migration + Simulator + ZPL-First Scanner

  • Migrated CLI from raw Typer to cli-core-yo foundation (create_app(spec) + plugin system)
  • Converted all command modules to register() plugin pattern (8 modules)
  • Standardized output: console.print() → output.* primitives (heading, success, warning, error, etc.)
  • Global --json/-j flag via RuntimeContext (replaced per-command --json flags)
  • Added mock Zebra printer simulator (zday simulator start/stop/list)
    • ZPL TCP server (port 9100) + HTTP status server (port 18080)
    • Configurable model, serial, firmware, and error conditions
  • Refactored network scanner to ZPL-first discovery (port 9100 default)
    • Optional HTTP fallback via --scan-http-port
    • Discovery method tracked in notes field: "zpl", "http(port)", "zpl+http(port)"
  • Fixed 27 pre-existing mypy errors (0 remaining)
  • ruff check + ruff format clean on all modified files
  • 334 tests passing across 13 test files

Commands Reference

# Development
pytest -v                           # Run tests
pytest --cov=zebra_day              # Run tests with coverage
ruff check zebra_day tests          # Lint
ruff format --check zebra_day tests # Format check
mypy zebra_day                      # Type check

# CLI (global --json/-j flag available on all commands)
zday --help                         # Show all commands
zday info                           # Show config paths and status
zday bootstrap                      # First-time setup
zday gui start                      # Start web server (HTTPS by default)
zday gui start --no-https           # Start without HTTPS
zday gui stop                       # Stop web server
zday simulator start --foreground   # Mock printer for testing
zday printer scan --ip-stub 192.168.1  # ZPL-first scanner

# Build
python -m build                     # Build wheel and sdist
twine check dist/*                  # Verify package