Plan-Execute Phase 1: retrofit ghtraf create with plan-execute pattern

[djdarcy]

Retrofit ghtraf create with plan-execute pattern

Problem

create.py has 6+ if dry_run: branches with separate logic for gist creation, variable setting, secret setup, file configuration, and config writing. Each branch is a potential divergence point between dry-run and real execution.

Proposed solution

Extract the decision logic from run() into plan_create(args, config) -> Plan, then implement execute_plan(plan, args, config) that iterates the plan's actions.

Key actions to model:

• CREATE_GIST (badge, archive) — returns gist ID via ActionResult.output
• SET_VARIABLE (TRAFFIC_GIST_ID, TRAFFIC_ARCHIVE_GIST_ID) — depends on gist creation
• SET_SECRET (PAT) — requires_input=True
• CONFIGURE_FILE (dashboard, readme, workflow) — regex replacements
• WRITE_CONFIG (.ghtraf.json, global config)

Remove dry_run parameter from gist.create_badge_gist(), gist.create_archive_gist(), gh.set_repo_variable(). These become pure executors called only during plan execution.

Acceptance criteria

• plan_create() returns a Plan with all actions
• ghtraf create --dry-run and ghtraf create use the same plan_create()
• gist.py functions no longer accept dry_run parameter
• gh.py functions no longer accept dry_run parameter
• Cascading gist IDs flow through plan.context
• PAT setup action flagged with requires_input=True
• Tests verify plan contents for various config scenarios

Related issues

• Parent: Plan-Execute epic
• Depends on: Core plan infrastructure sub-issue
• Refs Wire ghtraf create --init to chain template copy + cloud setup #29 — create --init (will need combined plan)

[djdarcy]

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

[djdarcy]

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

The original spec for this issue was written before the Collaborate3 consultation with Gemini 2.5 Pro locked several design decisions. The implementation should follow these updated specifications:

Key changes from the locked design

1. Action identity: string IDs, not integer steps

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

# NEW (locked)
Action(id="gist:create:badge", category="gist", ...)

String IDs use the format category:operation:target. depends_on references these string IDs, not integers. This is already implemented in core_lib (v0.3.3, commit 70b113f).

2. executor_fn closure pattern

# OLD (from original spec): Plan.execute() method
plan.execute()

# NEW (locked): executor_fn passed to execute_plan()
def make_create_executor(gh_client, config):
    """Closure over ghtraf-specific dependencies."""
    def executor_fn(action: Action) -> ActionResult:
        if action.category == "gist":
            gist_id = gh_client.create_gist(...)
            return ActionResult(action_id=action.id, success=True, output={"gist_id": gist_id})
        elif action.category == "secret":
            ...
    return executor_fn

results = execute_plan(plan, make_create_executor(gh_client, config))

The executor_fn: Callable[[Action], ActionResult] pattern keeps plan_lib domain-agnostic. The command-specific logic lives in the closure, not in the library.

3. ConflictResolution.ASK and prompt bridge

# For actions with requires_input=True (e.g., PAT setup):
ConflictResolution.ASK  # Defined in core_lib

# The prompt bridge pattern:
def prompt_bridge(action: Action) -> str:
    """Translate Action prompts to user input."""
    return input(f"{action.description}: ")

In --non-interactive mode, requires_input=True actions should use ConflictResolution.SKIP or raise an error — never silently default.

4. plan.context for cascading gist IDs

plan = Plan(
    name="create",
    actions=[...],
    context={}  # Carries cascading state
)

# During execution, gist IDs cascade:
# Step "gist:create:badge" produces gist_id → stored in plan.context
# Step "secret:set:BADGE_GIST_ID" reads from plan.context

In --dry-run, context contains placeholder IDs (e.g., "<BADGE_GIST_ID>").

5. ActionResult replaces ad-hoc return values

@dataclass
class ActionResult:
    action_id: str
    success: bool
    output: dict      # {"gist_id": "abc123", ...}
    error: str | None
    skipped: bool = False
    skip_reason: str | None = None

Every executor_fn call returns an ActionResult. execute_plan() collects these and handles depends_on failures via the error_policy parameter.

Updated acceptance criteria

In addition to the original criteria, the create retrofit should:

• Use Action(id="category:operation:target", ...) string IDs throughout
• Implement executor_fn closure pattern (not method-on-plan)
• Handle requires_input=True actions with prompt bridge in interactive mode
• Use plan.context for cascading gist IDs between actions
• Return ActionResult from every execution step
• --dry-run calls render_plan() from plan_lib (not custom display code)

Reference

• Locked design: 2026-03-02__18-05-16__DISCUSS_Rnd4_FINAL_ASSESSMENT_dazzlelib-installer-ecosystem.md
• core_lib implementation: src/ghtraf/lib/core_lib/types.py (v0.3.3, 70b113f)
• plan_lib implementation: src/ghtraf/lib/plan_lib/executor.py