docs/misc

2026-06-01 17:14:28 +07:00
parent bd190a5547
commit d05da78847
7 changed files with 4218 additions and 5 deletions
@@ -0,0 +1,229 @@
+# wf_api Extraction Mapping Prompt
+
+You are investigating the codebase only. Do not edit files.
+
+Goal: map how the current workflow application surface is implemented so we can extract a protocol-neutral `wf_api` package without breaking MCP, CLI, stores, or tests.
+
+The current suspicion:
+
+- `src/wf_mcp/workflow_surface/handlers.py` is a large application-service class.
+- It depends on `WfMcpService`, which is also broad.
+- We need to understand whether to move the class first, split it first, or introduce smaller services/facades.
+
+## Required Output
+
+Write your findings to:
+
+```text
+random shit/wf_api_extraction_map.md
+```
+
+Keep it structured and link-heavy. Do not paste huge code blocks. Use file paths, symbol names, and short notes.
+
+## Investigation Scope
+
+Focus on these files/symbols first:
+
+```text
+src/wf_mcp/workflow_surface/handlers.py
+  WorkflowSurfaceHandlers
+
+src/wf_mcp/broker/service/core.py
+  WfMcpService
+
+src/wf_mcp/workflow_surface/tools.py
+  register_workflow_tools
+
+src/wf_cli/context.py
+  CliContext
+  load_cli_context
+
+src/wf_cli/commands/*.py
+
+src/wf_artifacts/
+src/wf_platform/
+src/wf_core/
+```
+
+Use ripgrep/symbol search. Prefer precise symbol references over broad file dumps.
+
+## Questions To Answer
+
+### 1. What are the public operations?
+
+List every `WorkflowSurfaceHandlers` public method and classify it:
+
+```text
+capabilities
+drafts
+artifacts
+deployments
+runs
+explain/next-actions
+internal helper accidentally public
+```
+
+For each method, record:
+
+- method name
+- input parameters
+- return shape summary
+- direct dependencies
+- current callers/tests
+
+### 2. What parts of `WfMcpService` does it actually use?
+
+For each access from `WorkflowSurfaceHandlers` to `self.service`, record the member:
+
+```text
+self.service.artifact_store
+self.service.draft_workspace_store
+self.service.capability_sources
+self.service._get_qualified_spec(...)
+self.service._record_event(...)
+...
+```
+
+Classify each dependency:
+
+```text
+artifact storage
+draft storage
+run storage
+source/capability inventory
+MCP connection/catalog
+event bus
+private helper currently being used
+```
+
+Flag private-method dependencies such as `_get_qualified_spec` or `_record_event`.
+
+### 3. Which dependencies are MCP-specific vs protocol-neutral?
+
+Create a table:
+
+```text
+Dependency | Package today | MCP-specific? | Should live in wf_artifacts/wf_platform/wf_api/wf_mcp?
+```
+
+Examples:
+
+- artifact store likely protocol-neutral
+- draft workspace store likely protocol-neutral
+- source/capability refs likely protocol-neutral
+- MCP connection config/adapters likely MCP-specific for now
+- event bus may be platform-neutral
+
+### 4. What is the safest extraction seam?
+
+Compare these options:
+
+#### Option A: Move class first
+
+Move `WorkflowSurfaceHandlers` to `wf_api.service.WorkflowApi`, keep same constructor accepting `WfMcpService`.
+
+Pros/cons.
+
+#### Option B: Introduce API facade with ports
+
+Create `WorkflowApi` that depends on a smaller `WorkflowApiBackend`/ports object instead of all `WfMcpService`, then adapt `WfMcpService` into that backend.
+
+Pros/cons.
+
+#### Option C: Split handlers by domain first
+
+Split capabilities/drafts/artifacts/deployments/runs into separate classes before moving packages.
+
+Pros/cons.
+
+Recommend one first slice and explain why.
+
+### 5. What should the target package shape be?
+
+Propose a concrete package layout, for example:
+
+```text
+src/wf_api/
+  __init__.py
+  service.py
+  backend.py
+  capabilities.py
+  drafts.py
+  artifacts.py
+  deployments.py
+  runs.py
+  models.py
+```
+
+Do not overdesign. Identify which files are needed in the first slice vs later.
+
+### 6. What tests protect the extraction?
+
+List existing tests that must continue to pass, grouped by package:
+
+```text
+tests/wf_mcp/workflow_surface/*
+tests/wf_cli/*
+tests/wf_mcp/test_server.py
+...
+```
+
+Identify any missing tests needed before extraction.
+
+### 7. What code should not move yet?
+
+Explicitly list things that should stay in `wf_mcp` for now:
+
+- MCP transport/proxy/runtime/session code
+- FastMCP registration tools
+- connection adapters if not protocol-neutral yet
+- broker server construction
+
+### 8. Risks and weirdness
+
+Call out:
+
+- circular import risks
+- private method dependencies
+- store ownership ambiguity
+- naming confusion
+- tests that monkeypatch `wf_cli.commands.*.load_cli_context`
+- anything that would make FastAPI later harder or easier
+
+## Output Format
+
+Use this exact outline:
+
+```markdown
+# wf_api Extraction Map
+
+## Executive Summary
+
+## Public Operation Inventory
+
+## WfMcpService Dependency Inventory
+
+## Protocol-Neutral vs MCP-Specific Dependencies
+
+## Extraction Options
+
+## Recommended First Slice
+
+## Proposed Package Shape
+
+## Test Coverage
+
+## Things To Keep In wf_mcp For Now
+
+## Risks And Open Questions
+
+## Suggested Next Plan
+```
+
+## Constraints
+
+- Do not edit code.
+- Do not propose FastAPI implementation yet.
+- Keep current process-local behavior as the default.
+- Assume `wf_mcp` and `wf_cli` should become adapters over the same process-local API.
+- Prefer small, behavior-preserving extraction steps over a large rewrite.