c64bridge 1.0.6 → 1.1.0

package/doc/plans/tool-consolidation/plan.md

@@ -1,169 +0,0 @@
-# LLM Prompt: C64 Bridge MCP Tool Surface Consolidation
-
-You are refactoring the **C64 Bridge MCP server** (TypeScript, using `@modelcontextprotocol/sdk`) to reduce the exposed tool count from ~88 to a clean, discoverable set of **12 grouped multi-operation tools**, while preserving full functionality, LLM discoverability, and TypeScript type safety.
-
-This plan incorporates the latest refinements: **splitting storage tools, dissolving meta workflows, adding verification flags, tightening schema discrimination, and renaming all prefixes to `c64.*`**.
-
----
-
-## 1. Objective
-
-Transform all existing tools into **12 grouped multi-operation tools** with the following goals:
-
-- Preserve *every* endpoint, parameter, and capability.
-- Make the entire surface fully discoverable by LLMs via discriminated JSON Schema.
-- Maintain compatibility with all MCP clients (VS Code, Cursor, Windsurf, Claude Desktop, Copilot Agents).
-Each grouped tool must:
-
-- Define an `op` property (`enum` or `const` in `oneOf` discriminators).
-- Implement one handler dispatching internally based on `args.op`.
-- Keep per-op descriptions concise (≤2 sentences).
-- Include `verify: boolean` for ops where verification was previously separate.
-- Be listed in the documentation generator as a grouped tool with nested operations.
-
----
-
-## 2. Grouped Tool Mapping
-
-| Tool | Consolidated Operations | Selector | Notes |
-|------|-------------------------|-----------|--------|
-| **`c64_program`** | `load_prg_file` → `load_prg` • `run_prg_file` → `run_prg` • `run_crt_file` → `run_crt` • `upload_and_run_basic` → `upload_run_basic` • `upload_and_run_asm` → `upload_run_asm` • `batch_run_with_assertions` → `batch_run` • `bundle_run_artifacts` → `bundle_run` | `op` | `upload_run_*` ops gain optional `verify: boolean` |
-| **`c64_memory`** | `read_memory` → `read` • `write_memory` → `write` (`verify: boolean`) • `read_screen` → `read_screen` • `wait_for_screen_text` → `wait_for_text` | `op` | `wait_for_text` covers polling-based screen matching |
-| **`c64_sound`** | `sid_note_on` → `note_on` • `sid_note_off` → `note_off` • `sid_reset` → `reset` • `sid_silence_all` → `silence_all` (`verify: boolean`) • `sid_volume` → `set_volume` • `sidplay_file` → `play_sid_file` • `modplay_file` → `play_mod_file` • `music_compile_and_play` → `compile_play` • `music_generate` → `generate` • `music_compile_play_analyze` → `pipeline` • `analyze_audio` → `analyze` • `record_and_analyze_audio` → `record_analyze` | `op` | Includes the dissolved meta pipeline |
-| **`c64_system`** | `pause` → `pause` • `resume` → `resume` • `reset_c64` → `reset` • `reboot_c64` → `reboot` • `poweroff` → `poweroff` • `menu_button` → `menu` • `start_background_task` → `start_task` • `stop_background_task` → `stop_task` • `stop_all_background_tasks` → `stop_all_tasks` • `list_background_tasks` → `list_tasks` | `op` | Combines system control with background task orchestration |
-| **`c64_graphics`** | `create_petscii_image` → `create_petscii` • `render_petscii_screen` → `render_petscii` • `generate_sprite_prg` → `generate_sprite` • *(planned)* hires bitmap generator → `generate_bitmap` | `op` | PETSCII, sprite, and future bitmap helpers |
-| **`c64_rag`** | `rag_retrieve_basic` → `basic` • `rag_retrieve_asm` → `asm` | `op` | Lightweight retrieval API |
-| **`c64_disk`** | `create_d64/d71/d81/dnp` → `create_image` (`format` param) • `drive_mount`/`drive_mount_and_verify` → `mount` (`verify: boolean`) • `drive_remove` → `unmount` • `drives_list` → `list_drives` • `file_info` → `file_info` • `find_and_run_program_by_name` → `find_and_run` | `op` (`format`) | Consolidates disk image and file workflows |
-| **`c64_drive`** | `drive_load_rom` → `load_rom` • `drive_mode` → `set_mode` • `drive_reset` → `reset` • `drive_on` → `power_on` • `drive_off` → `power_off` | `op` | Physical and virtual drive state |
-| **`c64_printer`** | `define_printer_chars` → `define_chars` • `print_bitmap_commodore` → `print_bitmap` (`printer="commodore"`) • `print_bitmap_epson` → `print_bitmap` (`printer="epson"`) • `print_text` → `print_text` | `op` | `print_bitmap` requires the `printer` selector |
-| **`c64_config`** | `config_get` → `get` • `config_set` → `set` • `config_list` → `list` • `config_batch_update` → `batch_update` • `config_load_from_flash` → `load_flash` • `config_save_to_flash` → `save_flash` • `config_reset_to_default` → `reset_defaults` • `debugreg_read` → `read_debugreg` • `debugreg_write` → `write_debugreg` • `info` → `info` • `version` → `version` • `config_snapshot_and_restore` → `snapshot` / `restore` • `program_shuffle` → `shuffle` | `op` | Configuration, firmware, and snapshot management |
-| **`c64_extract`** | `extract_sprites_from_ram` → `sprites` • `rip_charset_from_ram` → `charset` • `memory_dump_to_file` → `memory_dump` • `filesystem_stats_by_extension` → `fs_stats` • `firmware_info_and_healthcheck` → `firmware_health` | `op` | Diagnostics and asset extraction |
-| **`c64_stream`** | `stream_start` → `start` • `stream_stop` → `stop` | `op` | Streaming and monitoring APIs |
-
----
-
-## 3. Verification Integration
-
-Remove separate verification tools. Instead, add `verify?: boolean` parameter to:
-
-| Tool | Operation | Previous Tool |
-|------|------------|----------------|
-| `c64_memory` | `write` | `verify_and_write_memory` |
-| `c64_sound` | `silence_all` | `silence_and_verify` |
-| `c64_disk` | `mount` | `drive_mount_and_verify` |
-| `c64_program` | `upload_run_basic`, `upload_run_asm` | `compile_run_verify_cycle` |
-
-Each operation should check `args.verify === true` to trigger post-action verification.
-
----
-
-## 4. Schema Specification
-
-All grouped tools must define discriminated unions using `const` for clarity and LLM reliability.
-
-Example:
-
-```ts
-parameters: {
-  oneOf: [
-    {
-      properties: {
-        op: { const: "read" },
-        address: { type: "integer" },
-        length: { type: "integer" }
-      },
-      required: ["op", "address", "length"]
-    },
-    {
-      properties: {
-        op: { const: "write" },
-        address: { type: "integer" },
-        data: { type: "string" },
-        verify: { type: "boolean", default: false }
-      },
-      required: ["op", "address", "data"]
-    },
-    {
-      properties: {
-        op: { const: "wait_for_text" },
-        pattern: { type: "string" },
-        timeout: { type: "integer", default: 2000 }
-      },
-      required: ["op", "pattern"]
-    }
-  ]
-}
-```
-
----
-
-## 5. Documentation Generation
-
-Update `scripts/generate-docs.ts` to:
-
-- Detect grouped tools and list sub-operations in nested tables.
-- Present the grouped tool suite in a single consolidated section.
-- Add total summary line:
-  > “This MCP server exposes **12 grouped tools** (≈81 operations), **25 resources**, and **7 prompts**.”
-- Show verification-enabled ops with `(verify)` suffix or a column note.
-- Include per-tool schema references (`op` values) in the generated README.
-
----
-
-## 6. Discoverability and LLM Behavior
-
-All LLM clients (OpenAI GPT-5, Anthropic Claude, Copilot Agents, MCP servers, etc.) automatically receive each tool’s full JSON schema.
-
-- `enum` and `const` values for `op` make all operations **visible** in context.
-- The LLM naturally selects the correct `op` based on intent.
-- Discriminated `oneOf` schemas and `description` fields maximize precision.
-- Verification and optional arguments remain self-documenting in schema.
-
-This design conforms to **MCP JSON Schema 2020-12**, ensuring interoperability and zero regression in LLM comprehension.
-
----
-
-## 7. Implementation Checklist
-
-- [ ] Add grouped tool definitions to `registry.ts`.
-- [ ] Implement `dispatch` functions per tool based on `args.op`.
-- [ ] Integrate `verify` parameter logic.
-- [ ] Refactor and reuse existing validation code.
-- [ ] Adjust `generate-docs.ts` to support grouped ops.
-- [ ] Update README auto-generation section (`<!-- AUTO-GENERATED:MCP-DOCS-START -->`).
-- [ ] Verify tests cover all grouped operations and shared validators.
-- [ ] Add a changelog entry:
-
-  ```markdown
-  ## 0.x.x – MCP Tool Consolidation and Refactor
-  - Reduced 88 single-purpose tools to 12 grouped multi-operation tools.
-  - Dissolved meta category, redistributed operations contextually.
-  - Added verification parameters and discriminated JSON schemas.
-  - Split storage into c64_disk and c64_drive.
-  - Added c64_extract category and integrated background task operations into c64_system.
-  - Improved LLM discoverability and documentation generation.
-  ```
-
----
-
-## 8. Final Tool Summary
-
-| Tool | Purpose |
-|------|----------|
-| `c64_program` | Program upload, run, and batch workflows |
-| `c64_memory` | Memory I/O, screen reading, and verification |
-| `c64_sound` | SID synthesis, playback, and analysis |
-| `c64_system` | Reset, reboot, power control, menu button, and background tasks |
-| `c64_graphics` | PETSCII, sprite, and bitmap generation |
-| `c64_rag` | BASIC and assembly reference retrieval |
-| `c64_disk` | Disk and image management |
-| `c64_drive` | Drive configuration and power control |
-| `c64_printer` | Commodore and Epson printer workflows |
-| `c64_config` | Configuration, debug register, firmware info, and snapshots |
-| `c64_extract` | Sprite, charset, memory, and diagnostics extraction |
-| `c64_stream` | Streaming and monitoring APIs |
-
----
-
-**Deliverable:**  
-A fully functioning TypeScript MCP server exposing 12 grouped tools with discriminated schemas, `verify` parameters, and automatic documentation, fully aligned with the Model Context Protocol SDK and discoverable by all LLM-based MCP clients.

package/doc/plans/tool-consolidation/rollout.md

@@ -1,104 +0,0 @@
-# Tool Consolidation Rollout Plan
-
-Purpose: Execute the grouped-tool refactor captured in `doc/tool-consolidation/plan.md`, reducing 88 single-purpose tools to 12 discriminated `c64.*` tools without disrupting the running MCP server. Follow this rollout sequentially; each checkbox item must succeed (code + docs + tests) before moving to the next.
-
-## Required Reading (complete before any checkbox work)
-
-- `doc/tool-consolidation/plan.md` — Grouped tool mapping, verification strategy, documentation updates.
-- `doc/tool-consolidation/notes.md` — Working assumptions and acceptance criteria summary.
-- `doc/developer.md` — Contribution workflow, test commands, documentation conventions.
-- `scripts/generate-docs.ts` and `src/tools/registry/index.ts` — Current implementation details that will be refactored.
-
-## Operator Rules (follow throughout)
-
-- Process checklists strictly in order; do not tick an item until all preceding items are completed and green.
-- After every checklist item, run `npm run check`. Proceed only if it passes.
-- If `npm run check` fails:
-  - Attempt one focused fix.
-  - If still failing, revert the latest change, capture notes in a status log, and halt the rollout.
-- Keep changes minimal and scoped to the current item; avoid opportunistic refactors unless explicitly required.
-- When new behavior is introduced, add or update tests that cover both happy path and at least one error path.
-- Update documentation concurrently with code so README/schemas never lag behind.
-- Preserve MCP uptime: keep legacy tool names available (via shims) until the full consolidation is complete.
-
-## Global Implementation Template (apply to every checklist item)
-
-1. Review the referenced code paths and confirm prerequisites are in place.
-2. Implement the minimal change set to satisfy the checklist item.
-3. Extend or add tests that cover the updated functionality.
-4. Refresh documentation, schemas, and TypeScript definitions as needed.
-5. Run `npm run check` and ensure success before ticking the checkbox.
-
-## Phase 0 — Rollout Initialization
-
-- [x] Confirm all documents listed under “Required Reading” are reviewed and capture acceptance criteria in your own log or the shared notes file.
-
-## Phase 1 — Foundation (Types, Registry, and Doc Scaffold)
-
-- [x] Introduce shared discriminated-union types (`op`, `verify?`) and validation helpers in `src/tools/types.ts` (or adjacent modules); add unit tests covering schema construction.
-- [x] Add grouped tool descriptors to `src/tools/registry/index.ts`, returning shims that still call the existing single-purpose handlers (no behavior change yet).
-- [x] Update `scripts/update-readme.ts` to understand grouped tools and refresh the README so each `c64.*` entry lists its operations in a clear, structured table; add snapshot-style tests guarding the new output.
-
-## Phase 2 — High-traffic Tool Migration (Program & Memory)
-
-- [x] Implement `c64_program` dispatch logic, migrate legacy program runner handlers, and ensure compatibility stubs continue to export old tool IDs until rollout completion.
-- [x] Implement `c64_memory` dispatch logic, integrating the `verify` option and consolidating screen read/wait operations; update associated tests.
-- [x] Remove direct registration of legacy program/memory tools once grouped variants pass all tests and docs reference the new schema.
-
-## Phase 3 — Audio, System, Graphics, Retrieval
-
-- [x] Migrate SID/music operations into `c64_sound`, covering pipeline/analysis flows and the `verify` flag on `silence_all`; refresh audio tests. *(2025-10-31)*
-- [x] Expand `c64_system` to include power/menu controls plus background task operations, ensuring pause/resume semantics remain unchanged. *(2025-11-01)*
-- [x] Consolidate PETSCII/sprite helpers into `c64_graphics` (including the forthcoming bitmap generator hook) and move BASIC/ASM retrieval to `c64_rag`; update prompts/tests referencing these tools. *(2025-10-31)*
-
-## Phase 4 — Storage & Peripheral Tools
-
-- [x] Fold disk image/file workflows into `c64_disk`, unify mount verification, and update drive-mount tests. *(2025-11-02)*
-- [x] Move drive ROM/mode/power handling into `c64_drive` with new dispatch tests ensuring IEC state remains stable. *(2025-11-02)*
-- [x] Group printer helpers into `c64_printer`, validating datapath differences between Commodore and Epson flows. *(2025-11-02)*
-
-## Phase 5 — Configuration, Extraction, Streaming
-
-- [x] Combine config, debug register, info/version, snapshot, and shuffle operations into `c64_config`; refresh config integration tests. *(2025-10-31)*
-- [x] Implement `c64_extract` for sprites, charset rips, memory dumps, filesystem stats, and firmware health; ensure outputs remain byte-for-byte compatible. *(2025-10-31)*
-- [x] Port streaming operations into `c64_stream` and re-run streaming integration tests (or mocks) to confirm UDP setup remains intact. *(2025-10-31)*
-
-## Phase 6 — Documentation, Schema, and Cleanup
-
-- [x] Regenerate documentation so README and related markdown list the 12 grouped tools with nested operations and summary counts; verify `scripts/generate-docs.ts` remains idempotent. *(2025-10-31)*
-- [x] Remove temporary compatibility shims and legacy tool exports; confirm MCP `list_tools` shows only the grouped suite. *(2025-10-31)*
-- [x] Perform a manual MCP smoke test (`npm start`, `list_tools`, sample ops) to validate runtime behavior. *(2025-10-31 — executed with `timeout 8 npm start` for auto-shutdown)*
-
-## Phase 7 — Release Polish
-
-- [x] Add the consolidation changelog entry and update version metadata if required.
-- [x] Run the full verification stack (`npm run check`, targeted e2e flows, documentation generation) and capture results for review.
-- [x] Update any remaining prompts or resource cross-links that reference retired tool names.
-
-## Done Definition
-
-A checkbox may be ticked only when all of the following hold for that item:
-
-- TypeScript builds without new errors.
-- New or updated tests pass locally.
-- `npm run check` has succeeded immediately after the change.
-- Documentation and schemas reflect the change set.
-- No subsequent checklist item has been started.
-
-## Notes on Sequencing
-
-- If a prerequisite gap is discovered, pause the rollout and document the issue rather than reordering tasks.
-- Within each phase, tasks are ordered by dependency and expected impact; do not parallelize unless explicitly stated.
-
-## Status Log
-
-- *2025-10-31*: Phase 6 cleanup approved to proceed. Begin with documentation regeneration, then retire legacy shims, running `npm run check` after each focused change.
-- *2025-10-31*: README regeneration rerun via `node scripts/invoke-bun.mjs scripts/update-readme.ts`; no diffs observed, doc automation confirmed idempotent.
-- *2025-10-31*: Manual MCP smoke test completed via `timeout 8 npm start`; connectivity checks passed and timeout exit confirmed non-blocking workflow.
-- *2025-10-31*: Legacy grouped-tool shims removed; registry now delegates via explicit handlers and no longer references legacy tool exports. `npm run test` and `npm run check` must remain green after this change.
-- *2025-10-31*: Phase 7 release polish complete — added v0.7.0 changelog entry, bumped `package.json`/`mcp.json`, reran `npm run check`, rebuilt docs (`node scripts/invoke-bun.mjs scripts/update-readme.ts`), executed `LOGFILE=/tmp/mcp-check-local.log bash scripts/run-mcp-check.sh local 5`, and regenerated embeddings to ensure prompts/resources reference the grouped tool suite only.
-
-## Post-Rollout Wrap-Up
-
-- Record a short retrospective summarizing lessons learned, risks, and follow-up work (format/location at operator discretion).
-- Share the retrospective with maintainers alongside the final change set to inform future MCP refactors.