workutils/docs/superpowers/plans/2026-07-30-api-doc-refactor-phase-3.md

API Doc Refactor Phase 3 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Give API document export one immutable request, one async operation owner, an explicit debug-proxy option, and the shared history UI.

Architecture: Capture all JavaFX form values into ApiDocExportRequest on the UI thread, then execute from AsyncOperationController. Inject the debug endpoint into ApiDocGenerator; only the export use case may decide whether to start the local proxy. Adapt existing history rows to HistoryItem without changing persistence.

Tech Stack: Java 17, JavaFX, JUnit 5, Maven.

Global Constraints

• Work only on codex/plugin-ui-refactor in the existing isolated worktree.
• Preserve generated HTML structure and history-file format.
• Do not introduce new Thread.
• File and directory choosers must not enter loading state.
• Local debug proxy is a visible option and defaults to disabled.
• Write and observe a failing test before production behavior.

---

Task 1: Immutable API export request

Files:

• Create: src/main/java/com/example/workutils/biz/apidoc/application/ApiDocExportRequest.java
• Test: src/test/java/com/example/workutils/biz/apidoc/application/ApiDocExportRequestTest.java

Interfaces:

• Produces: Mode { PATH, FQN, BATCH }.

• Produces validated factories path, fqn, and batch.

• Carries debug-proxy opt-in and batch filters.

• Test mode-specific validation and immutable project-path copying.

• Observe focused test failure.

• Implement the minimal request record.

• Confirm focused test passes.

Task 2: Explicit debug endpoint injection

Files:

• Modify: src/main/java/com/example/workutils/biz/apidoc/generator/ApiDocGenerator.java
• Test: src/test/java/com/example/workutils/biz/apidoc/generator/ApiDocGeneratorProxyTest.java

Interfaces:

• Produces constructor ApiDocGenerator(WorkUtilsProperties, Supplier<String>).

• Existing constructor supplies an empty endpoint and never starts a proxy.

• Test that generated HTML receives the supplied endpoint and the default constructor does not instantiate the proxy.

• Observe focused test failure.

• Inject endpoint supplier and remove DubboDebugProxy.getInstance() from HTML rendering.

• Confirm focused test passes.

Task 3: Single async export operation

Files:

• Create: src/main/java/com/example/workutils/biz/apidoc/application/RunApiDocExportUseCase.java
• Modify: src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java
• Test: src/test/java/com/example/workutils/biz/apidoc/application/RunApiDocExportUseCaseTest.java

Interfaces:

• Consumes ApiDocExportRequest.

• Produces Result(Path output, int moduleCount, int classCount, int methodCount).

• Reports progress through OperationContext.

• Test proxy-disabled execution does not resolve a local endpoint and proxy-enabled execution resolves it once.

• Observe focused test failure.

• Move export orchestration behind the use case and connect it to AsyncOperationController.

• Bind the button through LoadingButtonBinder and status through OperationStatusPane.

• Confirm focused and existing tests pass.

Task 4: Shared history UI

Files:

• Modify: src/main/java/com/example/workutils/biz/apidoc/ApiDocWindow.java
• Test: src/test/java/com/example/workutils/biz/apidoc/ApiDocHistoryMappingTest.java

Interfaces:

• Produces package-visible toHistoryItem(HistoryRow).

• Consumes ExportHistoryPane and HistoryFileCommands.

• Test history mapping.

• Observe focused test failure.

• Replace duplicated table and action cell.

• Confirm focused test passes.

Task 5: Verification

• Run all tests.
• Compile with JDK 17.
• Run git diff --check.
• Confirm ApiDocWindow contains no new Thread, buildActionCell, or direct export-button state mutations.
• Inspect PATH, FQN, and BATCH panels without invoking export or file choosers.