Plan-Execute Phase 2: retrofit ghtraf init with plan-execute pattern

[djdarcy]

Retrofit ghtraf init with plan-execute pattern

Problem

init.py has 4+ if dry_run: branches for file copying and conflict detection. The dry-run path for existing files shows "Would prompt" but the real path prompts interactively — a divergence that could mislead users about what will happen.

Proposed solution

Extract plan_init(args) -> Plan that scans the template directory and produces actions:

• COPY_FILE — new file, no conflict
• SKIP_FILE — file exists + --skip-existing
• PROMPT_OVERWRITE — file exists, needs user decision (requires_input=True)
• FORCE_OVERWRITE — file exists + --force

Remove dry_run from configure.py functions — they become pure executors.

Acceptance criteria

• plan_init() returns a Plan with per-file actions
• Conflict detection (existing files) is part of planning, not execution
• configure.py functions no longer accept dry_run parameter
• --skip-existing and --force flags affect plan contents, not execution branches
• Tests verify plan for empty target, existing files, and force mode

Related issues

• Parent: Plan-Execute epic
• Depends on: Core plan infrastructure sub-issue
• Refs ghtraf init — copy workflow and dashboard templates into target repo #28 — ghtraf init (the command being retrofitted)

[djdarcy]

Depends on #54 (core plan infrastructure must exist before retrofitting commands).

[djdarcy]

Spec update: locked design decisions from Collaborate3 (#53 Phase 2)

The original spec for this issue was written before the Collaborate3 consultation locked several design decisions. The init retrofit should follow these updated specifications:

Key changes from the locked design

1. String Action IDs (same as #55 update)

# OLD (from original spec)
Action(step=1, category="file", ...)

# NEW (locked)
Action(id="file:copy:workflow", category="file", operation="copy",
       target=".github/workflows/traffic-badges.yml", ...)

2. scan_destination() as the natural entry point

plan_lib/file_ops.py provides scan_destination() which is init's natural starting point:

from ghtraf.lib.plan_lib.file_ops import scan_destination

def plan_init(target_dir: Path, template_dir: Path, force: bool = False) -> Plan:
    """Build init plan by scanning what files need copying."""
    scan_result = scan_destination(target_dir, template_dir)

    actions = []
    for file_info in scan_result.files:
        if file_info.exists and not force:
            action = Action(
                id=f"file:skip:{file_info.relative_path}",
                operation="skip",
                details={"reason": "already exists, use --force to overwrite"},
            )
        else:
            action = Action(
                id=f"file:copy:{file_info.relative_path}",
                operation="copy",
                details={"source": str(file_info.source), "dest": str(file_info.dest)},
            )
        actions.append(action)

    return Plan(name="init", actions=actions)

3. executor_fn wrapping preserve_lib

For init, the executor_fn closure wraps preserve_lib file operations:

def make_init_executor(manifest_path: Path | None = None):
    """Closure over preserve_lib for file-centric operations."""
    def executor_fn(action: Action) -> ActionResult:
        if action.operation == "copy":
            # Use preserve_lib for manifest-tracked copy
            operations.copy_with_manifest(
                source=action.details["source"],
                dest=action.details["dest"],
                manifest=manifest,
            )
            return ActionResult(action_id=action.id, success=True, output={})
        elif action.operation == "skip":
            return ActionResult(action_id=action.id, success=True, skipped=True,
                              skip_reason=action.details.get("reason"))
    return executor_fn

This is the first proof of the PEV lifecycle's pluggable stages 4-6: plan_lib handles scan/render/approve (stages 1-3), preserve_lib provides the executor implementation (stage 4), and preserve_lib/verification.py handles post-execution verification (stage 5).

4. Interactive prompt bridge for conflict resolution

When --force is not set and files already exist, the plan should use ConflictResolution.ASK:

# In interactive mode: ask user per-file
action = Action(
    id=f"file:conflict:{file_info.relative_path}",
    operation="resolve_conflict",
    requires_input=True,
    details={"existing": str(file_info.dest), "source": str(file_info.source)},
)

In --non-interactive mode, conflicts are skipped (existing files preserved).

5. --skip-existing affects plan contents, not execution

The --skip-existing flag should modify the plan (mark conflict files as skip actions), not add execution-time branching. This preserves the single-decision-path principle.

Recommended implementation order

This issue (#56, init) should be implemented before #55 (create) because:

• Init is file-centric (simpler than create's API-centric operations)
• Init uses scan_destination() directly (already in plan_lib)
• Init proves the preserve_lib → executor_fn bridge pattern
• Create can then follow the proven pattern with its more complex API operations

Updated acceptance criteria

In addition to the original criteria:

• Use Action(id="category:operation:target", ...) string IDs
• Use scan_destination() from plan_lib as entry point for plan building
• Implement executor_fn closure wrapping preserve_lib operations
• Handle file conflicts via ConflictResolution.ASK in interactive mode
• --skip-existing and --force modify plan contents, not execution-time branching
• --dry-run calls render_plan() from plan_lib
• Return ActionResult from every execution step

Reference

• Locked design: 2026-03-02__18-05-16__DISCUSS_Rnd4_FINAL_ASSESSMENT_dazzlelib-installer-ecosystem.md
• scan_destination: src/ghtraf/lib/plan_lib/file_ops.py
• preserve_lib bridge: src/ghtraf/lib/preserve_lib/operations.py
• Ordering rationale: 2026-03-02__21-48-45__dev-workflow-process_missing-issues-and-plan-gaps.md (Gap 7)