Installer pattern extraction — plan-execute as DazzleLib candidate

[djdarcy]

Installer pattern extraction — plan-execute as DazzleLib candidate

Problem

ghtraf and comfyui-triton-sageattention-installer have independently evolved the same architectural pattern: detect current state → build a plan → display the plan → execute the plan → verify results. Both are "installer tools" operating across different axes:

Project	Installs	Axes
comfyui-triton	Python packages (PyTorch, Triton, SA)	CUDA ver, Python ver, PyTorch ver, env type, OS
ghtraf	Gists, secrets, variables, templates, config	owner, repo, gist type, templates, workflow files

comfyui-triton has a mature, production-proven implementation (EnvironmentState, ComponentAction, InstallPlan, PythonEnvironment, InstallationTarget). ghtraf has the architecture designed (#53) but not yet built.

The shared pattern is the same lifecycle that motivated the plan-execute epic:

State Detection → Plan Building → Display (dry-run) → Execution → Verification

This is the third DazzleLib candidate alongside log_lib (THAC0 verbosity) and help_lib (help text management).

Vision: ghtraf as a two-part application

This issue also captures the framing of ghtraf as two distinct parts:

Part 1: Dashboard & Metric Collection (the product users consume)

• traffic-badges.yml workflow — daily data collection
• docs/stats/index.html — client-side dashboard
• Badge JSON endpoints — shields.io integration
• Data quality: organic clones, dedup, projections

Part 2: ghtraf CLI (the installer/manager for Part 1)

• create → cloud-side installer (gists, variables, secrets)
• init → local-side installer (templates)
• upgrade → schema migration runner
• verify → installation health check
• status/list → view/enumerate installs
• backfill → data recovery
• config → settings management

Every Part 2 command follows the plan-execute lifecycle. The CLI is an installer, manager, and diagnostic tool for Part 1 — the same relationship comfyui-triton's installer has to the ComfyUI node ecosystem.

Proposed approach

Design-for-extraction, don't extract yet. Per the copy-first rule, build GTT's plan.py (#54) with clean interfaces knowing extraction is the goal:

1. Keep Action, ActionResult, Plan free of GTT-specific imports
2. Use composition for display (pluggable renderer) rather than hardcoding THAC0
3. Put dependency resolution in the Plan class (portable), not in subcommands
4. Keep category/operation vocabularies as strings (not enums)

Extraction evaluation point: After 2–3 ghtraf subcommands use plan-execute, compare GTT's plan.py against comfyui-triton's InstallPlan and extract the shared core to https://github.com/DazzleLib/ as dazzle-plan or plan_lib.

Shared concepts (extractable to DazzleLib)

Concept	comfyui-triton	ghtraf	Library name
Current state snapshot	EnvironmentState	config dict	State protocol
Atomic planned operation	ComponentAction	Action	Action
Full plan container	InstallPlan	Plan	Plan
Plan warnings	warnings: list[str]	warnings: list[str]	Identical
Plan display	_display_plan()	plan.display(renderer)	PlanRenderer
Action result	not tracked	ActionResult	ActionResult
Dependency resolution	sequential (implicit)	depends_on: list[int]	depends_on
Plan-based testing	matrix tests on plan objects	same approach	Same strategy

Domain-specific (stays in each project)

• comfyui-triton: CUDA detection, wheel URL resolution, PythonEnvironment, build tools
• ghtraf: gist creation, gh CLI calls, template copying, .ghtraf.json config, THAC0 verbosity

Implementation sequence

Phase 0: Build plan.py in GTT (#54) — design with extraction in mind
Phase 1: Retrofit create (#55) — prove pattern for cloud-side install
Phase 2: Retrofit init (#56) — prove pattern for local-side install
Phase 3: New subcommands use plan-execute from start
────── Evaluation point ──────
Phase 4: Extract shared core to DazzleLib
Phase 5: Retrofit comfyui-triton to use shared library

Acceptance criteria

• GTT's plan.py is designed with clean interfaces (no GTT-specific imports in core classes)
• Plan display uses composition (pluggable renderer, not hardcoded output)
• After 2–3 subcommands use plan-execute, extraction evaluation is performed
• Two-part application framing is documented and reflected in project architecture
• Extraction checkpoint is tracked (compare GTT plan.py vs comfyui-triton InstallPlan)

Related issues

• Parent: Plan-Execute architecture — trustworthy --dry-run across all subcommands #53 — Plan-Execute architecture epic
• Refs Plan-Execute Phase 0: core infrastructure — plan.py dataclasses and display #54 — Plan-Execute Phase 0 (where extraction-aware design happens)
• Refs Plan-Execute Phase 1: retrofit ghtraf create with plan-execute pattern #55, Plan-Execute Phase 2: retrofit ghtraf init with plan-execute pattern #56 — Phases 1–2 (where the pattern is proven)
• Refs ghtraf verify — state.json validation and consistency checks #38 — ghtraf verify (natural consumer of plan objects for health checks)
• Refs ghtraf upgrade — run schema migrations on gist state.json #30 — ghtraf upgrade (schema migrations as plans)
• Cross-repo: DazzleML/comfyui-triton-and-sageattention-installer (reference architecture)
• Ecosystem: https://github.com/DazzleLib/ (extraction target alongside log_lib, help_lib)

Analysis

See 2026-03-01__01-43-38__dev-workflow-process_installer-pattern-extraction-dazzlelib.md for the full DEV WORKFLOW PROCESS analysis including four solution approaches evaluated.