From 4d5d817628bed4c47bc68f48a4ea553e26368966 Mon Sep 17 00:00:00 2001 From: scawful Date: Fri, 7 Nov 2025 09:09:03 -0500 Subject: [PATCH] Remove deprecated dependabot configuration and update dependency architecture documentation for clarity and organization --- .github/dependabot.yml | 33 - .../developer/dependency-architecture.md | 1943 +---------------- docs/public/usage/z3ed-cli.md | 1144 +--------- 3 files changed, 185 insertions(+), 2935 deletions(-) delete mode 100644 .github/dependabot.yml diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index 88aec283..00000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,33 +0,0 @@ -version: 2 -updates: - # Enable version updates for GitHub Actions - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "02:00" - open-pull-requests-limit: 10 - reviewers: - - "scawful" - assignees: - - "scawful" - - # Enable version updates for Docker - - package-ecosystem: "docker" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "02:00" - open-pull-requests-limit: 5 - - # Enable version updates for npm (if any) - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "02:00" - open-pull-requests-limit: 5 - diff --git a/docs/public/developer/dependency-architecture.md b/docs/public/developer/dependency-architecture.md index 1bb7cb59..cba3193a 100644 --- a/docs/public/developer/dependency-architecture.md +++ b/docs/public/developer/dependency-architecture.md @@ -1,1842 +1,101 @@ -# YAZE Dependency Architecture & Build Optimization - -**Author**: Claude (Anthropic AI Assistant) -**Date**: 2025-10-13 -**Status**: Reference Document -**Related Docs**: [../../internal/agents/z3ed-refactoring.md](../../internal/agents/z3ed-refactoring.md), [../../internal/blueprints/zelda3-library-refactor.md](../../internal/blueprints/zelda3-library-refactor.md), [../../internal/blueprints/test-dashboard-refactor.md](../../internal/blueprints/test-dashboard-refactor.md) - ---- - -## Executive Summary - -This document provides a comprehensive analysis of YAZE's dependency architecture, identifies optimization opportunities, and proposes a roadmap for reducing build times and improving maintainability. - -### Key Findings - -- **Current State**: 25+ static libraries with complex interdependencies -- **Main Issues**: Circular dependencies, over-linking, misplaced components -- **Build Impact**: Changes to foundation libraries trigger rebuilds of 10-15+ dependent libraries -- **Opportunity**: 40-60% faster incremental builds through proposed refactorings - -### Quick Stats - -| Metric | Current | After Refactoring | -|--------|---------|-------------------| -| Total Libraries | 28 | 35 (more granular) | -| Circular Dependencies | 2 | 0 | -| Average Link Depth | 5-7 layers | 3-4 layers | -| Incremental Build Time | Baseline | **40-60% faster** | -| Test Isolation | Poor | Excellent | - ---- - -## 1. Complete Dependency Graph - -### 1.1 Foundation Layer - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ External Dependencies │ -│ • SDL2 (graphics, input, audio) │ -│ • ImGui (UI framework) │ -│ • Abseil (utilities, status, flags) │ -│ • GoogleTest/GoogleMock (testing) │ -│ • gRPC (optional - networking) │ -│ • nlohmann_json (optional - JSON) │ -│ • yaml-cpp (configuration) │ -│ • FTXUI (terminal UI) │ -│ • Asar (65816 assembler) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_common │ -│ • Common platform definitions │ -│ • No dependencies │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_util │ -│ • Logging, file I/O, SDL utilities │ -│ • Depends on: yaze_common, absl, SDL2 │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 1.2 Graphics Tier (Refactored) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_gfx (INTERFACE - aggregates all gfx sub-libraries) │ -└────────────────────────┬────────────────────────────────────────┘ - │ - ┌──────────────────┼──────────────────┐ - │ │ │ - ▼ ▼ ▼ -┌──────────┐ ┌──────────────┐ ┌─────────────┐ -│ gfx_debug│─────│ gfx_render │ │ gfx_util │ -└──────────┘ └──────┬───────┘ └─────┬───────┘ - │ │ - └─────────┬─────────┘ - ▼ - ┌──────────────┐ - │ gfx_core │ - │ (Bitmap) │ - └──────┬───────┘ - │ - ┌────────────┼────────────┐ - ▼ ▼ ▼ - ┌────────────┐ ┌──────────┐ ┌──────────┐ - │ gfx_types │ │gfx_resource│ │gfx_backend│ - │ (SNES data)│ │ (Arena) │ │ (SDL2) │ - └────────────┘ └──────────┘ └──────────┘ - -Dependencies: -• gfx_types → (none - foundation) -• gfx_backend → SDL2 -• gfx_resource → gfx_backend -• gfx_core → gfx_types + gfx_resource -• gfx_render → gfx_core + gfx_backend -• gfx_util → gfx_core -• gfx_debug → gfx_util + gfx_render -``` - -**Note**: `gfx_resource` (Arena) depends on `gfx_render` (BackgroundBuffer) but this is acceptable as both are low-level resource management. Not circular because gfx_render doesn't depend back on gfx_resource. - -### 1.3 GUI Tier (Refactored) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_gui (INTERFACE - aggregates all gui sub-libraries) │ -└────────────────────────┬────────────────────────────────────────┘ - │ - ┌──────────────┼──────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌──────────┐ ┌────────────┐ ┌────────────┐ - │ gui_app │ │gui_automation│ │gui_widgets │ - └────┬─────┘ └─────┬──────┘ └─────┬──────┘ - │ │ │ - └──────────────┼───────────────┘ - ▼ - ┌──────────────────┐ - │ gui_canvas │ - └─────────┬────────┘ - ▼ - ┌──────────────────┐ - │ gui_core │ - │ (Theme, Input) │ - └──────────────────┘ - -Dependencies: -• gui_core → yaze_util + ImGui + nlohmann_json -• gui_canvas → gui_core + yaze_gfx -• gui_widgets → gui_core + yaze_gfx -• gui_automation → gui_core -• gui_app → gui_core + gui_widgets + gui_automation -``` - -### 1.4 Zelda3 Library (Current - Monolithic) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_zelda3 (MONOLITHIC - needs refactoring per B6) │ -│ • Overworld (maps, tiles, warps) │ -│ • Dungeon (rooms, objects, layouts) │ -│ • Sprites (entities, overlords) │ -│ • Screens (title, inventory, dungeon map) │ -│ • Music (tracker - legacy Hyrule Magic code) │ -│ • Labels & constants │ -│ │ -│ Depends on: yaze_gfx, yaze_util, yaze_common, absl │ -└─────────────────────────────────────────────────────────────────┘ - -Warning: ISSUE: Located at src/app/zelda3/ but used by both app AND cli -Warning: ISSUE: Monolithic - any change rebuilds entire library -``` - -### 1.5 Zelda3 Library (Proposed - Tiered) - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_zelda3 (INTERFACE - aggregates sub-libraries) │ -└────────────────────────┬────────────────────────────────────────┘ - │ - ┌─────────────────┼─────────────────┐ - │ │ │ - ▼ ▼ ▼ -┌────────────┐ ┌────────────┐ ┌────────────┐ -│zelda3_screen│───│zelda3_dungeon│──│zelda3_overworld│ -└────────────┘ └──────┬─────┘ └──────┬──────┘ - │ │ - ┌─────────────────┼─────────────────┘ - │ │ - ▼ ▼ -┌────────────┐ ┌────────────┐ -│zelda3_music│ │zelda3_sprite│ -└──────┬─────┘ └──────┬─────┘ - │ │ - └────────┬────────┘ - ▼ - ┌───────────────┐ - │ zelda3_core │ - │ (Labels, │ - │ constants) │ - └───────────────┘ - -Benefits: - Location: src/zelda3/ (proper top-level shared lib) - Granular: Change dungeon logic → only rebuilds dungeon + dependents - Clear boundaries: Separate overworld/dungeon/sprite concerns - Legacy isolation: Music tracker separated from modern code -``` - -### 1.6 Core Libraries - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_core_lib (Warning: CIRCULAR DEPENDENCY RISK) │ -│ • ROM management (rom.cc) │ -│ • Window/input (window.cc) │ -│ • Asar wrapper (asar_wrapper.cc) │ -│ • Platform utilities (file dialogs, fonts, clipboard) │ -│ • Project management (project.cc) │ -│ • Controller (controller.cc) │ -│ • gRPC services (optional - test harness, ROM service) │ -│ │ -│ Depends on: yaze_util, yaze_gfx, yaze_zelda3, yaze_common, │ -│ ImGui, asar-static, SDL2, (gRPC) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -Warning: CIRCULAR: yaze_gfx → depends on gfx_resource (Arena) - Arena.h includes background_buffer.h (from gfx_render) - gfx_render → gfx_core → gfx_resource - BUT yaze_core_lib → yaze_gfx - - If anything in core_lib needs gfx_resource internals, - we get: core_lib → gfx → gfx_resource → (potentially) core_lib - -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_emulator │ -│ • CPU (65C816) │ -│ • PPU (graphics) │ -│ • APU (audio - SPC700 + DSP) │ -│ • Memory, DMA │ -│ • Input management │ -│ • Debugger UI components │ -│ │ -│ Depends on: yaze_util, yaze_common, yaze_core_lib, absl, SDL2 │ -└─────────────────────────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_net │ -│ • ROM version management │ -│ • WebSocket client │ -│ • Collaboration service │ -│ • ROM service (gRPC - disabled) │ -│ │ -│ Depends on: yaze_util, yaze_common, absl, (OpenSSL), (gRPC) │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### 1.7 Application Layer - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_test_support (Warning: CIRCULAR WITH yaze_editor) │ -│ • TestManager (core test infrastructure) │ -│ • z3ed test suite │ -│ │ -│ Depends on: yaze_editor, yaze_core_lib, yaze_gui, yaze_zelda3, │ -│ yaze_gfx, yaze_util, yaze_common, yaze_agent │ -└────────────────────────┬────────────────────────────────────────┘ - │ - │ Warning: CIRCULAR DEPENDENCY - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_editor │ -│ • Dungeon editor │ -│ • Overworld editor │ -│ • Sprite editor │ -│ • Graphics/palette editors │ -│ • Message editor │ -│ • Assembly editor │ -│ • System editors (settings, commands) │ -│ • Agent integration (AI features) │ -│ │ -│ Depends on: yaze_core_lib, yaze_gfx, yaze_gui, yaze_zelda3, │ -│ yaze_emulator, yaze_util, yaze_common, ImGui, │ -│ [yaze_agent], [yaze_test_support] (conditional) │ -└────────────────────────┬────────────────────────────────────────┘ - │ - │ Links back to test_support when YAZE_BUILD_TESTS=ON - └───────────────────────────────────────────┐ - │ - ▼ - Warning: CIRCULAR DEPENDENCY - -┌─────────────────────────────────────────────────────────────────┐ -│ yaze_agent (Warning: LINKS TO ALMOST EVERYTHING) │ -│ • Command handlers (resource, dungeon, overworld, graphics) │ -│ • AI services (Ollama, Gemini) │ -│ • GUI automation client │ -│ • TUI system (enhanced terminal UI) │ -│ • Planning/proposal system │ -│ • Test generation │ -│ • Conversation management │ -│ │ -│ Depends on: yaze_common, yaze_util, yaze_gfx, yaze_gui, │ -│ yaze_core_lib, yaze_zelda3, yaze_emulator, absl, │ -│ yaml-cpp, ftxui, (gRPC), (nlohmann_json), (OpenSSL) │ -└─────────────────────────────────────────────────────────────────┘ - -Warning: ISSUE: yaze_agent is massive and pulls in the entire application stack - Even simple CLI commands link against graphics, GUI, emulator, etc. -``` - -### 1.8 Executables - -``` -┌────────────────────────────────────────────────────────────────┐ -│ yaze (Main Application) │ -│ │ -│ Links: yaze_editor, yaze_emulator, yaze_core_lib, yaze_agent, │ -│ [yaze_test_support] (conditional), ImGui, SDL2 │ -│ │ -│ Transitively gets: All libraries through yaze_editor │ -└────────────────────────────────────────────────────────────────┘ - -┌────────────────────────────────────────────────────────────────┐ -│ z3ed (CLI Tool) │ -│ │ -│ Links: yaze_agent, yaze_core_lib, yaze_zelda3, ftxui │ -│ │ -│ Transitively gets: All libraries through yaze_agent (!) │ -│ Warning: ISSUE: CLI tool rebuilds if GUI/graphics/emulator changes │ -└────────────────────────────────────────────────────────────────┘ - -┌────────────────────────────────────────────────────────────────┐ -│ yaze_emu (Standalone Emulator) │ -│ │ -│ Links: yaze_emulator, yaze_core_lib, ImGui, SDL2 │ -│ │ -│ Warning: Conditionally built with YAZE_BUILD_EMU=ON │ -└────────────────────────────────────────────────────────────────┘ - -┌────────────────────────────────────────────────────────────────┐ -│ Test Executables │ -│ │ -│ yaze_test_stable: │ -│ - Unit tests (asar, rom, gfx, gui, zelda3, cli) │ -│ - Integration tests (dungeon, overworld, editor) │ -│ - Links: yaze_test_support, gmock_main, gtest_main │ -│ │ -│ yaze_test_gui: │ -│ - E2E GUI tests with ImGuiTestEngine │ -│ - Links: yaze_test_support, ImGuiTestEngine │ -│ │ -│ yaze_test_rom_dependent: │ -│ - Tests requiring actual ROM file │ -│ - Only built when YAZE_ENABLE_ROM_TESTS=ON │ -│ │ -│ yaze_test_experimental: │ -│ - AI integration tests (vision, tile placement) │ -│ │ -│ yaze_test_benchmark: │ -│ - Performance benchmarks │ -└────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 2. Current Dependency Issues - -### 2.1 Circular Dependencies - -#### Issue 1: yaze_test_support ↔ yaze_editor - -``` -yaze_test_support - ├─→ yaze_editor (for EditorManager, Canvas, etc.) - └─→ yaze_core_lib, yaze_gui, yaze_zelda3, ... - -yaze_editor (when YAZE_BUILD_TESTS=ON) - └─→ yaze_test_support (for TestManager) - -Result: Neither can be built first, causes linking issues -``` - -**Impact**: -- Confusing build order -- Test dashboard cannot be excluded from release builds cleanly -- Changes to test infrastructure force editor rebuilds - -**Solution** (from ../../internal/blueprints/test-dashboard-refactor.md): -``` -test_framework (core logic only) - ├─→ yaze_util, absl (no app dependencies) - -test_suites (actual tests) - ├─→ test_framework - └─→ yaze_zelda3, yaze_gfx (only what's needed) - -test_dashboard (GUI component - OPTIONAL) - ├─→ test_framework - ├─→ yaze_gui - └─→ Conditionally linked to yaze app - -yaze_editor - └─→ (no test dependencies) -``` - -#### Issue 2: Potential yaze_core_lib ↔ yaze_gfx Cycle - -``` -yaze_core_lib - └─→ yaze_gfx (for graphics operations) - -yaze_gfx - └─→ gfx_resource (Arena) - -gfx_resource (Arena) - └─→ Includes background_buffer.h (from gfx_render) - └─→ Has BackgroundBuffer members (bg1_, bg2_) - -If yaze_core_lib internals ever need gfx_resource specifics: - yaze_core_lib → yaze_gfx → gfx_resource → (back to) core_lib ❌ -``` - -**Current Status**: Not a problem yet, but risky -**Solution**: Split yaze_core_lib into foundation vs services - -### 2.2 Over-Linking Problems - -#### Problem 1: yaze_test_support Links to Everything - -``` -yaze_test_support dependencies: -├─→ yaze_editor (Warning: Brings in entire app stack) -├─→ yaze_core_lib -├─→ yaze_gui (Warning: Brings in all GUI widgets) -├─→ yaze_zelda3 -├─→ yaze_gfx (Warning: All 7 gfx libraries) -├─→ yaze_util -├─→ yaze_common -└─→ yaze_agent (Warning: Brings in AI services, emulator, etc.) - -Result: Test executables link against THE ENTIRE APPLICATION -``` - -**Impact**: -- Test binaries are massive (100+ MB) -- Any change to any library forces test relink -- Slow CI/CD pipeline -- Cannot build minimal test suites - -**Solution**: -- Separate test framework from test suites -- Each test suite links only to what it tests -- Remove yaze_editor from test framework - -#### Problem 2: yaze_agent Links to Everything - -``` -yaze_agent dependencies: -├─→ yaze_common -├─→ yaze_util -├─→ yaze_gfx (all 7 libs) -├─→ yaze_gui (all 5 libs) -├─→ yaze_core_lib -├─→ yaze_zelda3 -├─→ yaze_emulator -├─→ absl -├─→ yaml-cpp -├─→ ftxui -├─→ [gRPC] -├─→ [nlohmann_json] -└─→ [OpenSSL] - -Result: z3ed CLI tool rebuilds if GUI changes! -``` - -**Impact**: -- CLI tool (`z3ed`) is 80+ MB -- Any GUI/graphics change forces CLI rebuild -- Cannot build minimal agent for server deployment -- Tight coupling between CLI and GUI - -**Solution**: -``` -yaze_agent_core (minimal) - ├─→ Command handling abstractions - ├─→ TUI system (FTXUI) - ├─→ yaze_util, yaze_common - └─→ NO graphics, NO gui, NO emulator - -yaze_agent_services (full stack) - ├─→ yaze_agent_core - ├─→ yaze_gfx, yaze_gui (for GUI automation) - ├─→ yaze_emulator (for emulator commands) - └─→ yaze_zelda3 (for game logic queries) - -z3ed executable - └─→ yaze_agent_core (minimal build) - └─→ Optional: yaze_agent_services (full features) -``` - -#### Problem 3: yaze_editor Links to 8+ Major Libraries - -``` -yaze_editor dependencies: -├─→ yaze_core_lib -├─→ yaze_gfx (7 libs transitively) -├─→ yaze_gui (5 libs transitively) -├─→ yaze_zelda3 -├─→ yaze_emulator -├─→ yaze_util -├─→ yaze_common -├─→ ImGui -├─→ [yaze_agent] (conditional) -└─→ [yaze_test_support] (conditional) - -Result: Changes to ANY of these trigger editor rebuild -``` - -**Impact**: -- 60+ second editor rebuilds on gfx changes -- Tight coupling across entire application -- Difficult to isolate editor features -- Hard to test individual editors - -**Mitigation** (already done for gfx/gui): -- gfx refactored into 7 granular libs -- gui refactored into 5 granular libs -- Next: Refactor zelda3 into 6 granular libs -- Next: Split editor into editor modules - -### 2.3 Misplaced Components - -#### Issue 1: zelda3 Library Location - -``` -Current: src/app/zelda3/ - └─→ Implies it's part of GUI application - -Reality: Used by both yaze app AND z3ed CLI - └─→ Should be top-level shared library - -Problem: cli/ cannot depend on app/ (architectural violation) -``` - -**Solution** (from ../../internal/blueprints/zelda3-library-refactor.md): -- Move: `src/app/zelda3/` → `src/zelda3/` -- Update all includes: `#include "app/zelda3/...` → `#include "zelda3/...` -- Establish as proper shared core component - -#### Issue 2: Test Infrastructure Mixed into App - -``` -Current: src/app/test/ - └─→ test_manager.cc (core logic + GUI dashboard) - └─→ z3ed_test_suite.cc (test implementation) - -Problem: Cannot exclude test dashboard from release builds - Cannot build minimal test framework -``` - -**Solution** (from ../../internal/blueprints/test-dashboard-refactor.md): -- Move: `src/app/test/` → `src/test/framework/` + `src/test/suites/` -- Separate: `TestManager` (core) from `TestDashboard` (GUI) -- Make: `test_dashboard` conditionally compiled - ---- - -## 3. Build Time Impact Analysis - -### 3.1 Current Rebuild Cascades - -#### Scenario 1: Change snes_tile.cc (gfx_types) - -``` -snes_tile.cc (gfx_types) - ↓ -yaze_gfx_core (depends on gfx_types) - ↓ -yaze_gfx_util + yaze_gfx_render (depend on gfx_core) - ↓ -yaze_gfx_debug (depends on gfx_util + gfx_render) - ↓ -yaze_gfx (INTERFACE - aggregates all) - ↓ -yaze_gui_core + yaze_canvas + yaze_gui_widgets (depend on yaze_gfx) - ↓ -yaze_gui (INTERFACE - aggregates all) - ↓ -yaze_core_lib (depends on yaze_gfx + yaze_gui) - ↓ -yaze_editor + yaze_agent + yaze_net (depend on core_lib) - ↓ -yaze_test_support (depends on yaze_editor) - ↓ -All test executables (depend on yaze_test_support) - ↓ -yaze + z3ed + yaze_emu (main executables) - -TOTAL: 20+ libraries rebuilt, 6+ executables relinked -TIME: 5-10 minutes on CI, 2-3 minutes locally -``` - -#### Scenario 2: Change overworld_map.cc (zelda3) - -``` -overworld_map.cc (yaze_zelda3 - monolithic) - ↓ -yaze_zelda3 (ENTIRE library rebuilt) - ↓ -yaze_core_lib (depends on yaze_zelda3) - ↓ -yaze_editor + yaze_agent (depend on core_lib) - ↓ -yaze_test_support (depends on yaze_editor + yaze_agent) - ↓ -All test executables - ↓ -yaze + z3ed executables - -TOTAL: 8+ libraries rebuilt, 6+ executables relinked -TIME: 3-5 minutes on CI, 1-2 minutes locally -``` - -#### Scenario 3: Change test_manager.cc - -``` -test_manager.cc (yaze_test_support) - ↓ -yaze_test_support - ↓ -yaze_editor (links to test_support when YAZE_BUILD_TESTS=ON) - ↓ -yaze + z3ed (link to yaze_editor) - ↓ -All test executables (link to yaze_test_support) - -TOTAL: 3 libraries rebuilt, 8+ executables relinked -TIME: 1-2 minutes - -Warning: CIRCULAR: Editor change forces test rebuild, - Test change forces editor rebuild -``` - -### 3.2 Optimized Rebuild Cascades (After Refactoring) - -#### Scenario 1: Change snes_tile.cc (gfx_types) - Optimized - -``` -snes_tile.cc (gfx_types) - ↓ -yaze_gfx_core (depends on gfx_types) - ↓ -yaze_gfx_util + yaze_gfx_render (depend on gfx_core) - - STOP: Changes don't affect gfx_backend or gfx_resource - STOP: gui libraries still use old gfx INTERFACE - -Only rebuilt if consumers explicitly use changed APIs: - - yaze_zelda3 (if it uses modified tile functions) - - Specific editor modules (if they use modified functions) - -TOTAL: 3-5 libraries rebuilt, 1-2 executables relinked -TIME: 30-60 seconds on CI, 15-30 seconds locally -SAVINGS: 80% faster! -``` - -#### Scenario 2: Change overworld_map.cc (zelda3) - Optimized - -``` -With refactored zelda3: - -overworld_map.cc (zelda3_overworld sub-library) - ↓ -yaze_zelda3_overworld (only this sub-library rebuilt) - - STOP: zelda3_dungeon, zelda3_sprite unchanged - STOP: zelda3_screen depends on overworld but may not need rebuild - -Only rebuilt if consumers use changed APIs: - - yaze_editor_overworld_module - - Specific overworld tests - - z3ed overworld commands - -TOTAL: 2-3 libraries rebuilt, 1-2 executables relinked -TIME: 30-45 seconds on CI, 15-20 seconds locally -SAVINGS: 70% faster! -``` - -#### Scenario 3: Change test_manager.cc - Optimized - -``` -With separated test infrastructure: - -test_manager.cc (test_framework) - ↓ -test_framework - - STOP: test_suites may not need rebuild (depends on interface changes) - STOP: test_dashboard is separate, doesn't rebuild - STOP: yaze_editor has NO dependency on test system - -Only rebuilt: - - test_framework - - Test executables (yaze_test_*) - -TOTAL: 1 library rebuilt, 5 test executables relinked -TIME: 20-30 seconds on CI, 10-15 seconds locally -SAVINGS: 60% faster! - -Warning: BONUS: Release builds exclude test_dashboard entirely - → Smaller binary, faster builds, cleaner architecture -``` - -### 3.3 Build Time Savings Summary - -| Change Type | Current Time | After Refactoring | Savings | -|-------------|--------------|-------------------|---------| -| gfx_types change | 5-10 min | 30-60 sec | **80%** | -| zelda3 change | 3-5 min | 30-45 sec | **70%** | -| Test infrastructure | 1-2 min | 20-30 sec | **60%** | -| GUI widget change | 4-6 min | 45-90 sec | **65%** | -| Agent change | 2-3 min | 30-45 sec | **50%** | - -**Overall Incremental Build Improvement**: **40-60% faster** across common development scenarios - ---- - -## 4. Proposed Refactoring Initiatives - -### 4.1 Priority 1: Execute Existing Proposals - -#### A. Test Dashboard Separation (A2) - -**Status**: Proposed -**Priority**: HIGH -**Effort**: Medium (2-3 days) -**Impact**: 60% faster test builds, cleaner release builds - -**Implementation**: -1. Create `src/test/framework/` directory - - Move `test_manager.h/cc` (core logic only) - - Remove UI code from TestManager - - Library: `yaze_test_framework` - - Dependencies: `yaze_util`, `absl` - -2. Create `src/test/suites/` directory - - Move all `*_test_suite.h` files - - Move `z3ed_test_suite.cc` - - Library: `yaze_test_suites` - - Dependencies: `yaze_test_framework`, specific yaze libs - -3. Create `src/app/gui/testing/` directory - - New `TestDashboard` class - - Move `DrawTestDashboard` from TestManager - - Library: `yaze_test_dashboard` - - Dependencies: `yaze_test_framework`, `yaze_gui` - - Conditional: `YAZE_WITH_TEST_DASHBOARD=ON` - -4. Update build system - - Root CMake: Add `option(YAZE_WITH_TEST_DASHBOARD "..." ON)` - - app.cmake: Conditionally link `yaze_test_dashboard` - - Remove circular dependency - -**Benefits**: -- No circular dependencies -- Release builds exclude test dashboard -- Test changes don't rebuild editor -- Cleaner architecture - -#### B. Zelda3 Library Refactoring (B6) - -**Status**: Proposed -**Priority**: HIGH -**Effort**: Large (4-5 days) -**Impact**: 70% faster zelda3 builds, proper shared library - -**Phase 1: Physical Move** -```bash -# Move directory -mv src/app/zelda3 src/zelda3 - -# Update CMakeLists.txt -sed -i 's|include(zelda3/zelda3_library.cmake)|include(zelda3/zelda3_library.cmake)|' src/CMakeLists.txt - -# Global include update -find . -type f \( -name "*.cc" -o -name "*.h" \) -exec sed -i 's|#include "app/zelda3/|#include "zelda3/|g' {} + - -# Test build -cmake --preset mac-dev && cmake --build --preset mac-dev -``` - -**Phase 2: Decompose into Sub-Libraries** - -```cmake -# src/zelda3/zelda3_library.cmake - -# 1. Foundation -set(ZELDA3_CORE_SRC - zelda3/common.h - zelda3/zelda3_labels.cc - zelda3/palette_constants.cc - zelda3/dungeon/dungeon_rom_addresses.h -) -add_library(yaze_zelda3_core STATIC ${ZELDA3_CORE_SRC}) -target_link_libraries(yaze_zelda3_core PUBLIC yaze_util) - -# 2. Sprite (shared by dungeon + overworld) -set(ZELDA3_SPRITE_SRC - zelda3/sprite/sprite.cc - zelda3/sprite/sprite_builder.cc - zelda3/sprite/overlord.h -) -add_library(yaze_zelda3_sprite STATIC ${ZELDA3_SPRITE_SRC}) -target_link_libraries(yaze_zelda3_sprite PUBLIC yaze_zelda3_core) - -# 3. Dungeon -set(ZELDA3_DUNGEON_SRC - zelda3/dungeon/room.cc - zelda3/dungeon/room_layout.cc - zelda3/dungeon/room_object.cc - zelda3/dungeon/object_parser.cc - zelda3/dungeon/object_drawer.cc - zelda3/dungeon/dungeon_editor_system.cc - zelda3/dungeon/dungeon_object_editor.cc -) -add_library(yaze_zelda3_dungeon STATIC ${ZELDA3_DUNGEON_SRC}) -target_link_libraries(yaze_zelda3_dungeon PUBLIC - yaze_zelda3_core - yaze_zelda3_sprite -) - -# 4. Overworld -set(ZELDA3_OVERWORLD_SRC - zelda3/overworld/overworld.cc - zelda3/overworld/overworld_map.cc -) -add_library(yaze_zelda3_overworld STATIC ${ZELDA3_OVERWORLD_SRC}) -target_link_libraries(yaze_zelda3_overworld PUBLIC - yaze_zelda3_core - yaze_zelda3_sprite -) - -# 5. Screen -set(ZELDA3_SCREEN_SRC - zelda3/screen/title_screen.cc - zelda3/screen/inventory.cc - zelda3/screen/dungeon_map.cc - zelda3/screen/overworld_map_screen.cc -) -add_library(yaze_zelda3_screen STATIC ${ZELDA3_SCREEN_SRC}) -target_link_libraries(yaze_zelda3_screen PUBLIC - yaze_zelda3_dungeon - yaze_zelda3_overworld -) - -# 6. Music (legacy isolation) -set(ZELDA3_MUSIC_SRC - zelda3/music/tracker.cc -) -add_library(yaze_zelda3_music STATIC ${ZELDA3_MUSIC_SRC}) -target_link_libraries(yaze_zelda3_music PUBLIC yaze_zelda3_core) - -# Aggregate INTERFACE library -add_library(yaze_zelda3 INTERFACE) -target_link_libraries(yaze_zelda3 INTERFACE - yaze_zelda3_core - yaze_zelda3_sprite - yaze_zelda3_dungeon - yaze_zelda3_overworld - yaze_zelda3_screen - yaze_zelda3_music -) -``` - -**Benefits**: -- Proper top-level shared library -- Granular rebuilds (change dungeon → only dungeon + screen rebuild) -- Clear domain boundaries -- Legacy code isolated - -#### C. z3ed Command Abstraction (C4) - -**Status**: **COMPLETED** -**Priority**: N/A (already done) -**Impact**: 1300+ lines eliminated, 50-60% smaller command implementations - -**Achievements**: -- Command abstraction layer (`CommandContext`, `ArgumentParser`, `OutputFormatter`) -- Enhanced TUI with themes and autocomplete -- Comprehensive test coverage -- AI-friendly predictable structure - -**Next Steps**: None required, refactoring complete - -### 4.2 Priority 2: New Refactoring Proposals - -#### D. Split yaze_core_lib to Prevent Cycles - -**Status**: Proposed (New) -**Priority**: MEDIUM -**Effort**: Medium (2-3 days) -**Impact**: Prevents future circular dependencies, cleaner separation - -**Problem**: -``` -yaze_core_lib currently contains: -├─→ ROM management (rom.cc) -├─→ Window/input (window.cc) -├─→ Asar wrapper (asar_wrapper.cc) -├─→ Platform utilities (file_dialog, fonts) -├─→ Project management (project.cc) -├─→ Controller (controller.cc) -└─→ gRPC services (test_harness, rom_service) - -All mixed together in one library -If core_lib needs gfx internals → potential cycle -``` - -**Solution**: -``` -yaze_core_foundation: -├─→ ROM management (rom.cc) -├─→ Window basics (window.cc) -├─→ Asar wrapper (asar_wrapper.cc) -├─→ Platform utilities (file_dialog, fonts) -└─→ Dependencies: yaze_util, yaze_common, asar, SDL2 - (NO yaze_gfx, NO yaze_zelda3) - -yaze_core_services: -├─→ Project management (project.cc) - needs zelda3 for labels -├─→ Controller (controller.cc) - coordinates editors -├─→ gRPC services (test_harness, rom_service) -└─→ Dependencies: yaze_core_foundation, yaze_gfx, yaze_zelda3 - -yaze_core_lib (INTERFACE): -└─→ Aggregates: yaze_core_foundation + yaze_core_services -``` - -**Benefits**: -- Clear separation: foundation vs services -- Prevents cycles: gfx → core_foundation → gfx ❌ (no longer possible) -- Selective linking: CLI can use foundation only -- Better testability - -**Migration**: -```cmake -# src/app/core/core_library.cmake - -set(CORE_FOUNDATION_SRC - core/asar_wrapper.cc - app/core/window.cc - app/rom.cc - app/platform/font_loader.cc - app/platform/asset_loader.cc - app/platform/file_dialog_nfd.cc # or .mm for macOS -) - -add_library(yaze_core_foundation STATIC ${CORE_FOUNDATION_SRC}) -target_link_libraries(yaze_core_foundation PUBLIC - yaze_util - yaze_common - asar-static - SDL2 -) - -set(CORE_SERVICES_SRC - app/core/project.cc - app/core/controller.cc - # gRPC services if enabled -) - -add_library(yaze_core_services STATIC ${CORE_SERVICES_SRC}) -target_link_libraries(yaze_core_services PUBLIC - yaze_core_foundation - yaze_gfx - yaze_zelda3 - ImGui -) - -# Aggregate -add_library(yaze_core_lib INTERFACE) -target_link_libraries(yaze_core_lib INTERFACE - yaze_core_foundation - yaze_core_services -) -``` - -#### E. Split yaze_agent for Minimal CLI - -**Status**: Proposed (New) -**Priority**: MEDIUM-LOW -**Effort**: Medium (3-4 days) -**Impact**: 50% smaller z3ed builds, faster CLI development - -**Problem**: -``` -yaze_agent currently links to EVERYTHING: -├─→ yaze_gfx (all 7 libs) -├─→ yaze_gui (all 5 libs) -├─→ yaze_core_lib -├─→ yaze_zelda3 -├─→ yaze_emulator -└─→ Result: 80+ MB z3ed binary, slow rebuilds -``` - -**Solution**: -``` -yaze_agent_core (minimal): -├─→ Command registry & dispatcher -├─→ TUI system (FTXUI) -├─→ Argument parsing (from C4 refactoring) -├─→ Output formatting (from C4 refactoring) -├─→ Command context (from C4 refactoring) -├─→ Dependencies: yaze_util, yaze_common, ftxui, yaml-cpp -└─→ Size: ~15 MB binary - -yaze_agent_services (full stack): -├─→ yaze_agent_core -├─→ AI services (Ollama, Gemini) -├─→ GUI automation client -├─→ Emulator commands -├─→ Proposal system -├─→ Dependencies: ALL yaze libraries -└─→ Size: +65 MB (total 80+ MB) - -z3ed executable: -└─→ Links: yaze_agent_core (default) -└─→ Optional: yaze_agent_services (with --enable-full-features) -``` - -**Benefits**: -- 80% smaller CLI binary for basic commands -- Faster CLI development (no GUI rebuilds) -- Server deployments can use minimal agent -- Clear separation: core vs services - -**Implementation**: -```cmake -# src/cli/agent.cmake - -set(AGENT_CORE_SRC - cli/flags.cc - cli/handlers/command_handlers.cc - cli/service/command_registry.cc - cli/service/agent/tool_dispatcher.cc - cli/service/agent/enhanced_tui.cc - cli/service/resources/command_context.cc - cli/service/resources/command_handler.cc - cli/service/resources/resource_catalog.cc - # Minimal command handlers (resource queries, basic ROM ops) -) - -add_library(yaze_agent_core STATIC ${AGENT_CORE_SRC}) -target_link_libraries(yaze_agent_core PUBLIC - yaze_common - yaze_util - ftxui::component - yaml-cpp -) - -set(AGENT_SERVICES_SRC - # All AI, GUI automation, emulator integration - cli/service/ai/ai_service.cc - cli/service/ai/ollama_ai_service.cc - cli/service/ai/gemini_ai_service.cc - cli/service/gui/gui_automation_client.cc - cli/handlers/tools/emulator_commands.cc - # ... all other advanced features -) - -add_library(yaze_agent_services STATIC ${AGENT_SERVICES_SRC}) -target_link_libraries(yaze_agent_services PUBLIC - yaze_agent_core - yaze_gfx - yaze_gui - yaze_core_lib - yaze_zelda3 - yaze_emulator - # ... all dependencies -) - -# z3ed can choose which to link -``` - -### 4.3 Priority 3: Future Optimizations - -#### F. Editor Modularization - -**Status**: Future -**Priority**: LOW -**Effort**: Large (1-2 weeks) -**Impact**: Parallel development, isolated testing - -**Concept**: -``` -yaze_editor_dungeon: -└─→ Only dungeon editor code - -yaze_editor_overworld: -└─→ Only overworld editor code - -yaze_editor_system: -└─→ Settings, commands, workspace - -yaze_editor (INTERFACE): -└─→ Aggregates all editor modules -``` - -**Benefits**: -- Parallel development on different editors -- Isolated testing per editor -- Faster incremental builds - -**Defer**: After zelda3 refactoring, test separation complete - -#### G. Precompiled Headers Optimization - -**Status**: Future -**Priority**: LOW -**Effort**: Small (1 day) -**Impact**: 10-20% faster full rebuilds - -**Current**: PCH in `src/yaze_pch.h` but not fully optimized - -**Improvements**: -- Split into foundation PCH and app PCH -- More aggressive PCH usage -- Benchmark impact - -#### H. Unity Builds for Third-Party Code - -**Status**: Future -**Priority**: LOW -**Effort**: Small (1 day) -**Impact**: Faster clean builds - -**Concept**: Combine multiple translation units for faster compilation - ---- - -## 5. Conditional Compilation Matrix - -### Build Configurations - -| Configuration | Purpose | Test Dashboard | Agent | gRPC | ROM Tests | -|---------------|---------|----------------|-------|------|-----------| -| **Debug** | Local development | ON | ON | ON | ❌ OFF | -| **Debug-AI** | AI feature development | ON | ON | ON | ❌ OFF | -| **Release** | Production | ❌ OFF | ❌ OFF | ❌ OFF | ❌ OFF | -| **CI-Linux** | Ubuntu CI/CD | ❌ OFF | ON | ON | ❌ OFF | -| **CI-Windows** | Windows CI/CD | ❌ OFF | ON | ON | ❌ OFF | -| **CI-macOS** | macOS CI/CD | ❌ OFF | ON | ON | ❌ OFF | -| **Dev-ROM** | ROM testing | ON | ON | ON | ON | - -### Feature Flags - -| Flag | Default | Effect | -|------|---------|--------| -| `YAZE_BUILD_APP` | ON | Build main application | -| `YAZE_BUILD_Z3ED` | ON | Build CLI tool | -| `YAZE_BUILD_EMU` | OFF | Build standalone emulator | -| `YAZE_BUILD_TESTS` | ON | Build test suites | -| `YAZE_BUILD_LIB` | OFF | Build C API library | -| `YAZE_WITH_GRPC` | ON | Enable gRPC (networking) | -| `YAZE_WITH_JSON` | ON | Enable JSON (AI services) | -| `YAZE_WITH_TEST_DASHBOARD` | ON | Include test dashboard in app | -| `YAZE_ENABLE_ROM_TESTS` | OFF | Enable ROM-dependent tests | -| `YAZE_MINIMAL_BUILD` | OFF | Minimal build (no agent/tests) | - -### Library Availability Matrix - -| Library | Always Built | Conditional | Notes | -|---------|--------------|-------------|-------| -| yaze_util | | - | Foundation | -| yaze_common | | - | Foundation | -| yaze_gfx | | - | Core graphics | -| yaze_gui | | - | Core GUI | -| yaze_zelda3 | | - | Game logic | -| yaze_core_lib | | - | ROM management | -| yaze_emulator | | - | SNES emulation | -| yaze_net | | JSON/gRPC | Networking | -| yaze_editor | | APP | Main editor | -| yaze_agent | | Z3ED | CLI features | -| yaze_test_support | ❌ | TESTS | Test infrastructure | -| yaze_test_dashboard | ❌ | TEST_DASHBOARD | GUI test dashboard | - -### Executable Build Matrix - -| Executable | Build Condition | Dependencies | -|------------|-----------------|--------------| -| yaze | `YAZE_BUILD_APP=ON` | editor, emulator, core_lib, [agent], [test_dashboard] | -| z3ed | `YAZE_BUILD_Z3ED=ON` | agent, core_lib, zelda3 | -| yaze_emu | `YAZE_BUILD_EMU=ON` | emulator, core_lib | -| yaze_test_stable | `YAZE_BUILD_TESTS=ON` | test_support, all libs | -| yaze_test_gui | `YAZE_BUILD_TESTS=ON` | test_support, ImGuiTestEngine | -| yaze_test_rom_dependent | `YAZE_ENABLE_ROM_TESTS=ON` | test_support + ROM | - ---- - -## 6. Migration Roadmap - -### Phase 1: Foundation Fixes ( This PR) - -**Timeline**: Immediate -**Status**: In Progress - -**Tasks**: -1. Fix `BackgroundBuffer` constructor in `Arena::Arena()` -2. Add `yaze_core_lib` dependency to `yaze_emulator` -3. Document current architecture in this file - -**Expected Outcome**: -- Ubuntu CI passes -- No build regressions -- Complete architectural documentation - -### Phase 2: Test Separation (Next Sprint) - -**Timeline**: 1 week -**Status**: Proposed -**Reference**: ../../internal/blueprints/test-dashboard-refactor.md - -**Tasks**: -1. Create `src/test/framework/` directory structure -2. Split `TestManager` into core + dashboard -3. Move test suites to `src/test/suites/` -4. Create `test_dashboard` conditional library -5. Update CMake build system -6. Update all test executables -7. Verify clean release builds - -**Expected Outcome**: -- No circular dependencies -- 60% faster test builds -- Cleaner release binaries -- Isolated test framework - -### Phase 3: Zelda3 Refactoring (Week 2-3) - -**Timeline**: 1.5-2 weeks -**Status**: Proposed -**Reference**: ../../internal/blueprints/zelda3-library-refactor.md - -**Tasks**: -1. **Week 1**: Physical move - - Move `src/app/zelda3/` → `src/zelda3/` - - Update all `#include` directives (300+ files) - - Update CMake paths - - Verify builds - -2. **Week 2**: Decomposition - - Create 6 sub-libraries (core, sprite, dungeon, overworld, screen, music) - - Establish dependency graph - - Update consumers - - Verify incremental builds - -3. **Week 3**: Testing & Documentation - - Update test suite organization - - Benchmark build times - - Update documentation - - Migration guide - -**Expected Outcome**: -- Proper top-level shared library -- 70% faster zelda3 incremental builds -- Clear domain boundaries -- Legacy code isolated - -### Phase 4: Core Library Split (Week 4) - -**Timeline**: 1 week -**Status**: Proposed -**Reference**: Section 4.2.D (this document) - -**Tasks**: -1. Create `yaze_core_foundation` library - - Move ROM, window, asar, platform utilities - - Dependencies: util, common, SDL2, asar - -2. Create `yaze_core_services` library - - Move project, controller, gRPC services - - Dependencies: core_foundation, gfx, zelda3 - -3. Update `yaze_core_lib` INTERFACE - - Aggregate foundation + services - -4. Update all consumers - - Verify dependency chains - - No circular dependencies - -**Expected Outcome**: -- Prevents future circular dependencies -- Cleaner separation of concerns -- Minimal CLI can use foundation only - -### Phase 5: Agent Split (Week 5) - -**Timeline**: 1 week -**Status**: Proposed -**Reference**: Section 4.2.E (this document) - -**Tasks**: -1. Create `yaze_agent_core` library - - Command registry, TUI, parsers - - Dependencies: util, common, ftxui - -2. Create `yaze_agent_services` library - - AI services, GUI automation, emulator integration - - Dependencies: agent_core, all yaze libs - -3. Update `z3ed` executable - - Link minimal agent_core by default - - Optional full services - -**Expected Outcome**: -- 80% smaller CLI binary -- 50% faster CLI development -- Server-friendly minimal agent - -### Phase 6: Benchmarking & Optimization (Week 6) - -**Timeline**: 3-4 days -**Status**: Future - -**Tasks**: -1. Benchmark build times - - Before vs after comparisons - - Common development scenarios - - CI/CD pipeline times - -2. Profile bottlenecks - - Identify remaining slow builds - - Measure header include costs - - Analyze link times - -3. Optimize as needed - - PCH improvements - - Unity builds for third-party - - Parallel build tuning - -**Expected Outcome**: -- Data-driven optimization -- Documented build time improvements -- Tuned build system - -### Phase 7: Documentation & Polish (Week 7) - -**Timeline**: 2-3 days -**Status**: Future - -**Tasks**: -1. Update all documentation - - Architecture diagrams - - Build guides - - Migration guides - -2. Create developer onboarding - - Quick start guide - - Common workflows - - Troubleshooting - -3. CI/CD optimization - - Parallel build strategies - - Caching improvements - - Test parallelization - -**Expected Outcome**: -- Complete documentation -- Smooth onboarding -- Optimized CI/CD - ---- - -## 7. Expected Build Time Improvements - -### Baseline Measurements (Current) - -Measured on Apple M1 Max, 32 GB RAM, macOS 14.0 - -| Scenario | Current Time | Notes | -|----------|--------------|-------| -| Clean build (all features) | 8-10 min | Debug, gRPC, JSON, Tests | -| Clean build (minimal) | 5-6 min | No tests, no agent | -| Incremental (gfx change) | 2-3 min | Rebuilds 20+ libs | -| Incremental (zelda3 change) | 1-2 min | Rebuilds 8+ libs | -| Incremental (test change) | 45-60 sec | Circular rebuild | -| Incremental (editor change) | 1-2 min | Many dependents | - -### Projected Improvements (After All Refactoring) - -| Scenario | Projected Time | Savings | Notes | -|----------|----------------|---------|-------| -| Clean build (all features) | 7-8 min | 15-20% | Better parallelization | -| Clean build (minimal) | 3-4 min | 35-40% | Fewer conditional libs | -| Incremental (gfx change) | 30-45 sec | **75-80%** | Isolated gfx changes | -| Incremental (zelda3 change) | 20-30 sec | **70-75%** | Sub-library isolation | -| Incremental (test change) | 15-20 sec | **65-70%** | No circular rebuild | -| Incremental (editor change) | 30-45 sec | **60-65%** | Modular editors | - -### CI/CD Improvements - -| Pipeline | Current | Projected | Savings | -|----------|---------|-----------|---------| -| Ubuntu stable tests | 12-15 min | 8-10 min | **30-35%** | -| macOS stable tests | 15-18 min | 10-12 min | **30-35%** | -| Windows stable tests | 18-22 min | 12-15 min | **30-35%** | -| Full matrix (3 platforms) | 45-55 min | 30-37 min | **30-35%** | - -### Developer Experience Improvements - -| Workflow | Current | Projected | Impact | -|----------|---------|-----------|--------| -| Fix gfx bug → test | 3-4 min | 45-60 sec | **Much faster iteration** | -| Add zelda3 feature → test | 2-3 min | 30-45 sec | **Rapid prototyping** | -| Modify test → verify | 60-90 sec | 20-30 sec | **Tight feedback loop** | -| CLI-only development | Rebuilds GUI! | No GUI rebuild | **Isolated development** | - ---- - -## 8. Detailed Library Specifications - -### 8.1 Foundation Libraries - -#### yaze_common - -**Purpose**: Platform definitions, common macros -**Location**: `src/common/` -**Source Files**: (header-only) -**Dependencies**: None -**Dependents**: All libraries (foundation) -**Build Impact**: Header-only, minimal -**Priority**: N/A (stable) - -#### yaze_util - -**Purpose**: Logging, file I/O, SDL utilities -**Location**: `src/util/` -**Source Files**: 8-10 .cc files -**Dependencies**: yaze_common, absl, SDL2 -**Dependents**: All libraries -**Build Impact**: Changes trigger rebuild of EVERYTHING -**Priority**: N/A (stable, rarely changes) - -### 8.2 Graphics Libraries - -#### yaze_gfx_types - -**Purpose**: SNES color/palette/tile data structures -**Location**: `src/app/gfx/types/` -**Source Files**: 3 .cc files -**Dependencies**: None (foundation) -**Dependents**: gfx_core, gfx_util -**Build Impact**: Medium (4-6 libs) -**Priority**: DONE (refactored) - -#### yaze_gfx_backend - -**Purpose**: SDL2 renderer abstraction -**Location**: `src/app/gfx/backend/` -**Source Files**: 1 .cc file -**Dependencies**: SDL2 -**Dependents**: gfx_resource, gfx_render -**Build Impact**: Low (2-3 libs) -**Priority**: DONE (refactored) - -#### yaze_gfx_resource - -**Purpose**: Memory management (Arena) -**Location**: `src/app/gfx/resource/` -**Source Files**: 2 .cc files -**Dependencies**: gfx_backend, gfx_render (BackgroundBuffer) -**Dependents**: gfx_core -**Build Impact**: Medium (3-4 libs) -**Priority**: DONE (refactored) -**Note**: Fixed BackgroundBuffer constructor issue in this PR - -#### yaze_gfx_core - -**Purpose**: Bitmap class -**Location**: `src/app/gfx/core/` -**Source Files**: 1 .cc file -**Dependencies**: gfx_types, gfx_resource -**Dependents**: gfx_util, gfx_render, gui_canvas -**Build Impact**: High (8+ libs) -**Priority**: DONE (refactored) - -#### yaze_gfx_render - -**Purpose**: Advanced rendering (Atlas, BackgroundBuffer) -**Location**: `src/app/gfx/render/` -**Source Files**: 4 .cc files -**Dependencies**: gfx_core, gfx_backend -**Dependents**: gfx_debug, zelda3 -**Build Impact**: Medium (5-7 libs) -**Priority**: DONE (refactored) - -#### yaze_gfx_util - -**Purpose**: Compression, format conversion -**Location**: `src/app/gfx/util/` -**Source Files**: 4 .cc files -**Dependencies**: gfx_core -**Dependents**: gfx_debug, editor -**Build Impact**: Medium (4-6 libs) -**Priority**: DONE (refactored) - -#### yaze_gfx_debug - -**Purpose**: Performance profiling, optimization -**Location**: `src/app/gfx/debug/` -**Source Files**: 3 .cc files -**Dependencies**: gfx_util, gfx_render -**Dependents**: editor (optional) -**Build Impact**: Low (1-2 libs) -**Priority**: DONE (refactored) - -### 8.3 GUI Libraries - -#### yaze_gui_core - -**Purpose**: Theme, input, style management -**Location**: `src/app/gui/core/` -**Source Files**: 7 .cc files -**Dependencies**: yaze_util, ImGui, nlohmann_json -**Dependents**: All other GUI libs -**Build Impact**: High (8+ libs) -**Priority**: DONE (refactored) - -#### yaze_gui_canvas - -**Purpose**: Drawable canvas with pan/zoom -**Location**: `src/app/gui/canvas/` -**Source Files**: 9 .cc files -**Dependencies**: gui_core, yaze_gfx -**Dependents**: editor (all editors use Canvas) -**Build Impact**: Very High (10+ libs) -**Priority**: DONE (refactored) - -#### yaze_gui_widgets - -**Purpose**: Reusable UI widgets -**Location**: `src/app/gui/widgets/` -**Source Files**: 6 .cc files -**Dependencies**: gui_core, yaze_gfx -**Dependents**: editor -**Build Impact**: Medium (5-7 libs) -**Priority**: DONE (refactored) - -#### yaze_gui_automation - -**Purpose**: Widget discovery, state capture, testing -**Location**: `src/app/gui/automation/` -**Source Files**: 4 .cc files -**Dependencies**: gui_core -**Dependents**: gui_app, agent (GUI automation) -**Build Impact**: Low (2-3 libs) -**Priority**: DONE (refactored) - -#### yaze_gui_app - -**Purpose**: High-level app components (chat, collaboration) -**Location**: `src/app/gui/app/` -**Source Files**: 4 .cc files -**Dependencies**: gui_core, gui_widgets, gui_automation -**Dependents**: editor -**Build Impact**: Low (1-2 libs) -**Priority**: DONE (refactored) - -### 8.4 Game Logic Libraries - -#### yaze_zelda3 (Current) - -**Purpose**: All Zelda3 game logic -**Location**: `src/app/zelda3/` Warning: (wrong location) -**Source Files**: 21 .cc files (monolithic) -**Dependencies**: yaze_gfx, yaze_util -**Dependents**: core_lib, editor, agent -**Build Impact**: Very High (any change rebuilds 8+ libs) -**Priority**: HIGH (refactor per B6) 🔴 -**Issues**: -- Wrong location (should be `src/zelda3/`) -- Monolithic (should be 6 sub-libraries) - -#### yaze_zelda3_core (Proposed) - -**Purpose**: Labels, constants, common data -**Location**: `src/zelda3/` (after move) -**Source Files**: 3-4 .cc files -**Dependencies**: yaze_util -**Dependents**: All other zelda3 libs -**Build Impact**: High (if changed, rebuilds all zelda3) -**Priority**: HIGH (implement B6) 🔴 - -#### yaze_zelda3_sprite (Proposed) - -**Purpose**: Sprite management -**Location**: `src/zelda3/sprite/` -**Source Files**: 3 .cc files -**Dependencies**: zelda3_core -**Dependents**: zelda3_dungeon, zelda3_overworld -**Build Impact**: Medium (2-3 libs) -**Priority**: HIGH (implement B6) 🔴 - -#### yaze_zelda3_dungeon (Proposed) - -**Purpose**: Dungeon system -**Location**: `src/zelda3/dungeon/` -**Source Files**: 7 .cc files -**Dependencies**: zelda3_core, zelda3_sprite -**Dependents**: zelda3_screen, editor_dungeon -**Build Impact**: Low (1-2 libs) -**Priority**: HIGH (implement B6) 🔴 - -#### yaze_zelda3_overworld (Proposed) - -**Purpose**: Overworld system -**Location**: `src/zelda3/overworld/` -**Source Files**: 2 .cc files -**Dependencies**: zelda3_core, zelda3_sprite -**Dependents**: zelda3_screen, editor_overworld -**Build Impact**: Low (1-2 libs) -**Priority**: HIGH (implement B6) 🔴 - -#### yaze_zelda3_screen (Proposed) - -**Purpose**: Game screens (title, inventory, map) -**Location**: `src/zelda3/screen/` -**Source Files**: 4 .cc files -**Dependencies**: zelda3_dungeon, zelda3_overworld -**Dependents**: editor_screen -**Build Impact**: Very Low (1 lib) -**Priority**: HIGH (implement B6) 🔴 - -#### yaze_zelda3_music (Proposed) - -**Purpose**: Legacy music tracker -**Location**: `src/zelda3/music/` -**Source Files**: 1 .cc file (legacy C code) -**Dependencies**: zelda3_core -**Dependents**: editor_music -**Build Impact**: Very Low (1 lib) -**Priority**: HIGH (implement B6) 🔴 - -### 8.5 Core System Libraries - -#### yaze_core_lib (Current) - -**Purpose**: ROM, window, asar, project, services -**Location**: `src/app/core/` -**Source Files**: 10+ .cc files (mixed concerns) Warning: -**Dependencies**: yaze_util, yaze_gfx, yaze_zelda3, ImGui, asar, SDL2, [gRPC] -**Dependents**: editor, agent, emulator, net -**Build Impact**: Very High (10+ libs) -**Priority**: MEDIUM (split into foundation + services) 🟡 -**Issues**: -- Mixed concerns (foundation vs services) -- Potential circular dependency with gfx - -#### yaze_core_foundation (Proposed) - -**Purpose**: ROM, window, asar, platform utilities -**Location**: `src/app/core/` -**Source Files**: 6-7 .cc files -**Dependencies**: yaze_util, yaze_common, asar, SDL2 -**Dependents**: core_services, emulator, agent_core -**Build Impact**: Medium (5-7 libs) -**Priority**: MEDIUM (implement section 4.2.D) 🟡 - -#### yaze_core_services (Proposed) - -**Purpose**: Project, controller, gRPC services -**Location**: `src/app/core/` -**Source Files**: 4-5 .cc files -**Dependencies**: core_foundation, yaze_gfx, yaze_zelda3, ImGui, [gRPC] -**Dependents**: editor, agent_services -**Build Impact**: Medium (4-6 libs) -**Priority**: MEDIUM (implement section 4.2.D) 🟡 - -#### yaze_emulator - -**Purpose**: SNES emulation (CPU, PPU, APU) -**Location**: `src/app/emu/` -**Source Files**: 30+ .cc files -**Dependencies**: yaze_util, yaze_common, yaze_core_lib, absl, SDL2 -**Dependents**: editor, agent (emulator commands) -**Build Impact**: Medium (3-5 libs) -**Priority**: LOW (stable) -**Note**: Fixed missing core_lib dependency in this PR - -#### yaze_net - -**Purpose**: Networking, collaboration -**Location**: `src/app/net/` -**Source Files**: 3 .cc files -**Dependencies**: yaze_util, yaze_common, absl, [OpenSSL], [gRPC] -**Dependents**: gui (collaboration panel) -**Build Impact**: Low (1-2 libs) -**Priority**: LOW (stable) - -### 8.6 Application Layer Libraries - -#### yaze_editor - -**Purpose**: All editor functionality -**Location**: `src/app/editor/` -**Source Files**: 45+ .cc files (large, complex) -**Dependencies**: core_lib, gfx, gui, zelda3, emulator, util, common, ImGui, [agent], [test_support] -**Dependents**: test_support, yaze app -**Build Impact**: Very High (ANY change affects main app + tests) -**Priority**: LOW-FUTURE (modularize per section 4.3.F) 🔵 -**Issues**: -- Too many dependencies (8+ major libs) -- Circular dependency with test_support - -#### yaze_agent (Current) - -**Purpose**: CLI functionality, AI services -**Location**: `src/cli/` -**Source Files**: 60+ .cc files (massive) Warning: -**Dependencies**: common, util, gfx, gui, core_lib, zelda3, emulator, absl, yaml, ftxui, [gRPC], [JSON], [OpenSSL] -**Dependents**: editor (agent integration), z3ed -**Build Impact**: Very High (15+ libs) -**Priority**: MEDIUM (split into core + services) 🟡 -**Issues**: -- Links to entire application stack -- CLI tool rebuilds on GUI changes - -#### yaze_agent_core (Proposed) - -**Purpose**: Minimal CLI (commands, TUI, parsing) -**Location**: `src/cli/` -**Source Files**: 20-25 .cc files -**Dependencies**: common, util, ftxui, yaml -**Dependents**: agent_services, z3ed -**Build Impact**: Low (2-3 libs) -**Priority**: MEDIUM (implement section 4.2.E) 🟡 - -#### yaze_agent_services (Proposed) - -**Purpose**: Full CLI features (AI, GUI automation, emulator) -**Location**: `src/cli/` -**Source Files**: 35-40 .cc files -**Dependencies**: agent_core, gfx, gui, core_lib, zelda3, emulator, [gRPC], [JSON], [OpenSSL] -**Dependents**: editor (agent integration), z3ed (optional) -**Build Impact**: High (10+ libs) -**Priority**: MEDIUM (implement section 4.2.E) 🟡 - -#### yaze_test_support (Current) - -**Purpose**: Test manager + test suites -**Location**: `src/app/test/` -**Source Files**: 2 .cc files (mixed concerns) Warning: -**Dependencies**: editor, core_lib, gui, zelda3, gfx, util, common, agent -**Dependents**: editor (CIRCULAR Warning:), all test executables -**Build Impact**: Very High (10+ libs) -**Priority**: HIGH (separate per A2) 🔴 -**Issues**: -- Circular dependency with editor -- Cannot exclude from release builds -- Mixes core logic with GUI - -#### yaze_test_framework (Proposed) - -**Purpose**: Core test infrastructure (no GUI) -**Location**: `src/test/framework/` -**Source Files**: 1 .cc file -**Dependencies**: yaze_util, absl -**Dependents**: test_suites, test_dashboard -**Build Impact**: Low (2-3 libs) -**Priority**: HIGH (implement A2) 🔴 - -#### yaze_test_suites (Proposed) - -**Purpose**: Actual test implementations -**Location**: `src/test/suites/` -**Source Files**: 1 .cc file -**Dependencies**: test_framework, specific yaze libs (what's being tested) -**Dependents**: test executables -**Build Impact**: Low (1-2 libs per suite) -**Priority**: HIGH (implement A2) 🔴 - -#### yaze_test_dashboard (Proposed) - -**Purpose**: In-app test GUI (optional) -**Location**: `src/app/gui/testing/` -**Source Files**: 1-2 .cc files -**Dependencies**: test_framework, yaze_gui -**Dependents**: yaze app (conditionally) -**Build Impact**: Low (1 lib) -**Priority**: HIGH (implement A2) 🔴 -**Conditional**: `YAZE_WITH_TEST_DASHBOARD=ON` - ---- - -## 9. References & Related Documents - -### Primary Documents - -- **../../internal/agents/z3ed-refactoring.md**: CLI command abstraction (COMPLETED ) -- **../../internal/blueprints/zelda3-library-refactor.md**: Zelda3 move & decomposition (PROPOSED 🔴) -- **../../internal/blueprints/test-dashboard-refactor.md**: Test infrastructure separation (PROPOSED 🔴) -- **This Document (A1)**: Comprehensive dependency analysis (NEW 📄) - -### Related Refactoring Documents - -- **docs/gfx-refactor.md**: Graphics tier decomposition (COMPLETED ) -- **docs/gui-refactor.md**: GUI tier decomposition (COMPLETED ) -- **../../internal/blueprints/renderer-migration-complete.md**: Renderer abstraction (COMPLETED ) - -### Build System Documentation - -- **Root CMakeLists.txt**: Main build configuration -- **src/CMakeLists.txt**: Library orchestration -- **test/CMakeLists.txt**: Test suite configuration -- **scripts/build_cleaner.py**: Automated source list maintenance - -### Architecture Documentation - -- **docs/CLAUDE.md**: Project overview and guidelines -- **../build/platform-compatibility.md**: Platform notes, Windows Clang - workarounds, and CI/CD guidance -- **git-workflow.md**: Git workflow and branching - -### External Resources - -- [CMake Documentation](https://cmake.org/documentation/) -- [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) -- [Abseil C++ Libraries](https://abseil.io/) -- [SDL2 Documentation](https://wiki.libsdl.org/) -- [ImGui Documentation](https://github.com/ocornut/imgui) - ---- - -## 10. Conclusion - -This document provides a comprehensive analysis of YAZE's dependency architecture and proposes a clear roadmap for optimization. The key takeaways are: - -1. **Current State**: Complex interdependencies causing slow builds -2. **Root Causes**: Circular dependencies, over-linking, misplaced components -3. **Solution**: Execute existing proposals (A2, B6) + new splits (core_lib, agent) -4. **Expected Impact**: 40-60% faster incremental builds, cleaner architecture -5. **Timeline**: 6-7 weeks for complete refactoring - -By following this roadmap, YAZE will achieve: -- Faster development iteration -- Cleaner architecture -- Better testability -- Easier maintenance -- Improved CI/CD performance - -The proposed changes are backwards-compatible and can be implemented incrementally without disrupting ongoing development. - ---- - -**Document Version**: 1.0 -**Last Updated**: 2025-10-13 -**Maintainer**: YAZE Development Team -**Status**: Living Document (update as architecture evolves) +# Dependency & Build Overview + +_Last reviewed: November 2025. All information in this document is derived from the current +`src/CMakeLists.txt` tree and shipped presets._ + +This guide explains how the major YAZE libraries fit together, which build switches control +them, and when a code change actually forces a full rebuild. It is intentionally concise so you +can treat it as a quick reference while editing. + +## Build Switches & Presets + +| CMake option | Default | Effect | +| --- | --- | --- | +| `YAZE_BUILD_APP` | `ON` | Build the main GUI editor (`yaze`). Disable when you only need CLI/tests. | +| `YAZE_BUILD_Z3ED` | `ON` | Build the `z3ed` automation tool and supporting agent libraries. | +| `YAZE_BUILD_EMU` | `OFF` | Build the standalone emulator binary. Always enabled inside the GUI build. | +| `YAZE_BUILD_TESTS` | `ON` in `*-dbg` presets | Compiles test helpers plus `yaze_test`. Required for GUI test dashboard. | +| `YAZE_ENABLE_GRPC` | `OFF` | Pulls in gRPC/protobuf for automation and remote control features. | +| `YAZE_MINIMAL_BUILD` | `OFF` | Skips optional editors/assets. Useful for CI smoke builds. | +| `YAZE_BUILD_LIB` | `OFF` | Produces the `yaze_core` INTERFACE target used by external tooling. | + +Use the canned presets from `CMakePresets.json` so these options stay consistent across +platforms: `mac-dbg`, `mac-ai`, `lin-dbg`, `win-dbg`, etc. The `*-ai` presets enable both +`YAZE_BUILD_Z3ED` and `YAZE_ENABLE_GRPC` so the CLI and agent features match what ships. + +## Library Layers + +### 1. Foundation (`src/util`, `incl/`) +- **`yaze_common`**: cross-platform macros, generated headers, and lightweight helpers shared by + every other target. +- **`yaze_util`**: logging, file I/O, BPS patch helpers, and the legacy flag system. Only depends + on `yaze_common` plus optional gRPC/Abseil symbols. +- **Third-party**: SDL2, ImGui, Abseil, yaml-cpp, FTXUI, Asar. They are configured under + `cmake/dependencies/*.cmake` and linked where needed. + +Touching headers in this layer effectively invalidates most of the build. Keep common utilities +stable and prefer editor-specific helpers instead of bloating `yaze_util`. + +### 2. Graphics & UI (`src/app/gfx`, `src/app/gui`) +- **`yaze_gfx`**: bitmap containers, palette math, deferred texture arena, canvas abstractions. + Depends on SDL2 + `yaze_util`. +- **`yaze_gui`**: shared ImGui widgets, docking layout utilities, and theme plumbing. Depends on + ImGui + `yaze_gfx`. + +Changes here rebuild all editors but do not touch the lower-level Zelda 3 logic. Use the graphics +layer for rendering and asset streaming primitives; keep domain logic in the Zelda 3 library. + +### 3. Game Domain (`src/zelda3`, `src/app/editor`) +- **`yaze_zelda3`**: map/room/sprite models, parsers, and ROM serialization. It links + `yaze_gfx`, `yaze_util`, and Abseil. +- **`yaze_editor`**: ImGui editors (overworld, dungeon, palette, etc.). Depends on + `yaze_gui`, `yaze_zelda3`, `yaze_gfx`, and optional agent/test hooks. +- **`yaze_emulator`**: CPU, PPU, and APU subsystems plus the debugger UIs (`src/app/emu`). The GUI + app links this to surface emulator panels. + +Touching Zelda 3 headers triggers rebuilds of the editor and CLI but leaves renderer-only changes +alone. Touching editor UI code does **not** require rebuilding `yaze_emulator`. + +### 4. Tooling & Export Targets +- **`yaze_agent`** (`src/cli/agent`): shared logic behind the CLI and AI workflows. Built whenever + `YAZE_BUILD_Z3ED` is enabled. +- **`z3ed` binary** (`src/cli/z3ed.cmake`): links `yaze_agent`, `yaze_zelda3`, `yaze_gfx`, and + Abseil/FTXUI. +- **`yaze_core_lib`** (`src/core`): static library that exposes project management helpers and the + Asar integration. When `YAZE_BUILD_LIB=ON` it can be consumed by external tools. +- **`yaze_test_support`** (`src/app/test`): harness for the in-editor dashboard and `yaze_test`. + +### 5. Final Binaries +- **`yaze`**: GUI editor. Links every layer plus `yaze_test_support` when tests are enabled. +- **`yaze_test`**: GoogleTest runner (unit, integration, e2e). Built from `test/CMakeLists.txt`. +- **`z3ed`**: CLI + TUI automation tool. Built when `YAZE_BUILD_Z3ED=ON`. +- **`yaze_emu`**: optional standalone emulator for fast boot regression tests. + +## Rebuild Cheatsheet + +| Change | Targets Affected | +| --- | --- | +| `src/util/*.h` or `incl/yaze/*.h` | Everything (foundation dependency) | +| `src/app/gfx/**` | `yaze_gfx`, `yaze_gui`, editors, CLI. Emulator core unaffected. | +| `src/zelda3/**` | All editors, CLI, tests. Rebuild does **not** touch renderer-only changes. | +| `src/app/editor/**` | GUI editor + CLI (shared panels). Emulator/test support untouched. | +| `src/app/emu/**` | Emulator panels + GUI app. CLI and Zelda 3 libraries unaffected. | +| `src/cli/**` | `yaze_agent`, `z3ed`. No impact on GUI/editor builds. | +| `src/app/test/**` | `yaze_test_support`, `yaze_test`, GUI app (only when tests enabled). | + +Use this table when deciding whether to invalidate remote build caches or to schedule longer CI +runs. Whenever possible, localize changes to the upper layers to avoid rebuilding the entire +stack. + +## Tips for Faster Iteration + +1. **Leverage presets** – `cmake --build --preset mac-ai --target yaze` automatically enables + precompiled headers and shared dependency trees. +2. **Split work by layer** – renderer bugs usually live in `yaze_gfx`; leave Zelda 3 logic alone + unless you need ROM serialization tweaks. +3. **Turn off unused targets** – set `YAZE_BUILD_Z3ED=OFF` when working purely on GUI features to + shave a few hundred object files. +4. **Test without ROMs** – `docs/public/developer/testing-without-roms.md` documents the mock ROM + harness so you do not need to rebuild assets between iterations. +5. **See also** – for deep dives into refactors or planned changes, read the internal blueprints in + `docs/internal/blueprints/` instead of bloating the public docs. diff --git a/docs/public/usage/z3ed-cli.md b/docs/public/usage/z3ed-cli.md index 6ba7a691..f4ebca57 100644 --- a/docs/public/usage/z3ed-cli.md +++ b/docs/public/usage/z3ed-cli.md @@ -1,1082 +1,106 @@ -# z3ed Command-Line Interface +# z3ed CLI Guide -**Version**: 0.1.0-alpha -**Last Updated**: October 5, 2025 +_Last reviewed: November 2025. `z3ed` ships alongside the main editor in every `*-ai` preset and +runs on Windows, macOS, and Linux._ -## 1. Overview +`z3ed` exposes the same ROM-editing capabilities as the GUI but in a scriptable form. Use it to +apply patches, inspect resources, run batch conversions, or drive the AI-assisted workflows that +feed the in-editor proposals. -`z3ed` is a command-line companion to YAZE. It surfaces editor functionality, test harness tooling, and automation endpoints for scripting and AI-driven workflows. - -### Core Capabilities - -1. Conversational agent interfaces (Ollama or Gemini) for planning and review. -2. gRPC test harness for widget discovery, replay, and automated verification. -3. Proposal workflow that records changes for manual review and acceptance. -4. Resource-oriented commands (`z3ed `) suitable for scripting. - -## 2. Quick Start - -### Build - -A single `Z3ED_AI=ON` CMake flag enables all AI features, including JSON, YAML, and httplib dependencies. This simplifies the build process. +## 1. Building & Configuration ```bash -# Build with AI features (RECOMMENDED) -cmake -B build -DZ3ED_AI=ON -cmake --build build --target z3ed +# Enable the agent/CLI toolchain +cmake --preset mac-ai +cmake --build --preset mac-ai --target z3ed -# For GUI automation features, also include gRPC -cmake -B build -DZ3ED_AI=ON -DYAZE_WITH_GRPC=ON -cmake --build build --target z3ed +# Run the text UI (FTXUI) +./build/bin/z3ed --tui ``` -### AI Setup +The AI features require at least one provider: +- **Ollama (local)** – install via `brew install ollama`, run `ollama serve`, then set + `Z3ED_OLLAMA_MODEL=qwen2.5-coder:7b` (or any supported model). +- **Gemini (cloud)** – export `GEMINI_API_KEY` before launching `z3ed`. -**Ollama (Recommended for Development)**: +If no provider is configured the CLI still works, but agent subcommands will fall back to manual +plans. + +## 2. Everyday Commands + +| Task | Example | +| --- | --- | +| Apply an Asar patch | `z3ed asar patch.asm --rom zelda3.sfc` | +| Export all sprites from a dungeon | `z3ed dungeon list-sprites --dungeon 2 --rom zelda3.sfc --format json` | +| Inspect an overworld map | `z3ed overworld describe-map --map 80 --rom zelda3.sfc` | +| Dump palette data | `z3ed palette export --rom zelda3.sfc --output palettes.json` | +| Validate ROM headers | `z3ed rom info --rom zelda3.sfc` | + +Pass `--help` after any command to see its flags. Most resource commands follow the +` ` convention (`overworld set-tile`, `dungeon import-room`, etc.). + +## 3. Agent & Proposal Workflow + +### 3.1 Interactive Chat ```bash -brew install ollama # macOS -ollama pull qwen2.5-coder:7b # Pull recommended model -ollama serve # Start server +z3ed agent chat --rom zelda3.sfc --theme overworld ``` +- Maintains conversation history on disk so you can pause/resume. +- Supports tool-calling: the agent invokes subcommands (e.g., `overworld describe-map`) and + returns structured diffs. -**Gemini (Cloud API)**: +### 3.2 Plans & Batches ```bash -# Get API key from https://aistudio.google.com/apikey -export GEMINI_API_KEY="your-key-here" -``` +# Generate a proposal but do not apply it +z3ed agent plan --prompt "Move the eastern palace entrance 3 tiles east" --rom zelda3.sfc -### Example Commands - -**Conversational Agent**: -```bash -# Interactive chat (FTXUI) -z3ed agent chat --rom zelda3.sfc - -# Simple text mode (better for AI/automation) -z3ed agent simple-chat --rom zelda3.sfc - -# Batch mode -z3ed agent simple-chat --file queries.txt --rom zelda3.sfc -``` - -**Proposal Workflow**: -```bash -# Generate from prompt -z3ed agent run --prompt "Place tree at 10,10" --rom zelda3.sfc --sandbox - -# List proposals +# List pending plans z3ed agent list -# Review -z3ed agent diff --proposal-id - -# Accept -z3ed agent accept --proposal-id +# Apply a plan after review +z3ed agent accept --proposal-id --rom zelda3.sfc ``` +Plans store the command transcript, diffs, and metadata inside +`$XDG_DATA_HOME/yaze/proposals/` (or `%APPDATA%\yaze\proposals\`). Review them before applying to +non-sandbox ROMs. -### Hybrid CLI ↔ GUI Workflow - -1. Build with `-DZ3ED_AI=ON -DYAZE_WITH_GRPC=ON` so the CLI, editor widget, and test harness share the same feature set. -2. Use `z3ed agent plan --prompt "Describe overworld tile 10,10"` against a sandboxed ROM to preview actions. -3. Apply the plan with `z3ed agent run ... --sandbox`, then open **Debug → Agent Chat** in YAZE to inspect proposals and logs. -4. Re-run or replay from either surface; proposals stay synchronized through the shared registry. - -## 3. Architecture - -The z3ed system is composed of several layers, from the high-level AI agent down to the YAZE GUI and test harness. - -### System Components Diagram - -``` -┌─────────────────────────────────────────────────────────┐ -│ AI Agent Layer (LLM: Ollama, Gemini) │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ z3ed CLI (Command-Line Interface) │ -│ ├─ agent run/plan/diff/test/list/describe │ -│ └─ rom/palette/overworld/dungeon commands │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ Service Layer (Singleton Services) │ -│ ├─ ProposalRegistry (Proposal Tracking) │ -│ ├─ RomSandboxManager (Isolated ROM Copies) │ -│ ├─ ResourceCatalog (Machine-Readable API Specs) │ -│ └─ ConversationalAgentService (Chat & Tool Dispatch) │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ ImGuiTestHarness (gRPC Server in YAZE) │ -│ ├─ Ping, Click, Type, Wait, Assert, Screenshot │ -│ └─ Introspection & Discovery RPCs │ -│ └─ Automation API shared by CLI & Agent Chat │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ YAZE GUI (ImGui Application) │ -│ └─ ProposalDrawer & Editor Windows │ -└─────────────────────────────────────────────────────────┘ -``` - -### Command Abstraction Layer (v0.2.1) - -The CLI command architecture has been refactored to eliminate code duplication and provide consistent patterns: - -``` -┌─────────────────────────────────────────────────────────┐ -│ Tool Command Handler (e.g., resource-list) │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ Command Abstraction Layer │ -│ ├─ ArgumentParser (Unified arg parsing) │ -│ ├─ CommandContext (ROM loading & labels) │ -│ ├─ OutputFormatter (JSON/Text output) │ -│ └─ CommandHandler (Optional base class) │ -└────────────────────┬────────────────────────────────────┘ - │ -┌────────────────────▼────────────────────────────────────┐ -│ Business Logic Layer │ -│ ├─ ResourceContextBuilder │ -│ ├─ OverworldInspector │ -│ └─ DungeonAnalyzer │ -└─────────────────────────────────────────────────────────┘ -``` - -Key benefits: -- Removes roughly 1300 lines of duplicated command code. -- Cuts individual command implementations by about half. -- Establishes consistent patterns across the CLI for easier testing and automation. - -See [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md) for migration details. - -## 4. Agentic & Generative Workflow (MCP) - -The `z3ed` CLI is the foundation for an AI-driven Model-Code-Program (MCP) loop, where the AI agent's "program" is a script of `z3ed` commands. - -1. **Model (Planner)**: The agent receives a natural language prompt and leverages an LLM to create a plan, which is a sequence of `z3ed` commands. -2. **Code (Generation)**: The LLM returns the plan as a structured JSON object containing actions. -3. **Program (Execution)**: The `z3ed agent` parses the plan and executes each command sequentially in a sandboxed ROM environment. -4. **Verification (Tester)**: The `ImGuiTestHarness` is used to run automated GUI tests to verify that the changes were applied correctly. - -## 5. Command Reference - -### Agent Commands - -- `agent run --prompt "..."`: Executes an AI-driven ROM modification in a sandbox. -- `agent plan --prompt "..."`: Shows the sequence of commands the AI plans to execute. -- `agent list`: Shows all proposals and their status. -- `agent diff [--proposal-id ]`: Shows the changes, logs, and metadata for a proposal. -- `agent describe [--resource ]`: Exports machine-readable API specifications for AI consumption. -- `agent chat`: Opens an interactive terminal chat (TUI) with the AI agent. -- `agent simple-chat`: A lightweight, non-TUI chat mode for scripting and automation. -- `agent test ...`: Commands for running and managing automated GUI tests. -- `agent learn ...`: **NEW**: Manage learned knowledge (preferences, ROM patterns, project context, conversation memory). -- `agent todo create "Description" [--category=] [--priority=]` -- `agent todo list [--status=] [--category=]` -- `agent todo update --status=` -- `agent todo show ` -- `agent todo delete ` -- `agent todo clear-completed` -- `agent todo next` -- `agent todo plan` - -### Resource Commands - -- `rom info|validate|diff`: Commands for ROM file inspection and comparison. -- `palette export|import|list`: Commands for palette manipulation. -- `overworld get-tile|find-tile|set-tile`: Commands for overworld editing. -- `dungeon list-sprites|list-rooms`: Commands for dungeon inspection. - -#### `agent test`: Live Harness Automation - -- Discover widgets: `z3ed agent test discover --rom zelda3.sfc --grpc localhost:50051` enumerates ImGui widget IDs through the gRPC-backed harness for later scripting. -- **Record interactions**: `z3ed agent test record --suite harness/tests/overworld_entry.jsonl` launches YAZE, mirrors your clicks/keystrokes, and persists an editable JSONL trace. -- **Replay & assert**: `z3ed agent test replay harness/tests/overworld_entry.jsonl --watch` drives the GUI in real time and streams pass/fail telemetry back to both the CLI and Agent Chat widget telemetry panel. -- **Integrate with proposals**: `z3ed agent test verify --proposal-id ` links a recorded scenario with a proposal to guarantee UI state after sandboxed edits. -- **Debug in the editor**: While a replay is running, open **Debug → Agent Chat → Harness Monitor** to step through events, capture screenshots, or restart the scenario without leaving ImGui. - -## 6. Chat Modes - -### FTXUI Chat (`agent chat`) -Full-screen interactive terminal with table rendering, syntax highlighting, and scrollable history. Best for manual exploration. - -**Features:** -- **Autocomplete**: Real-time command suggestions as you type -- **Fuzzy matching**: Intelligent command completion with scoring -- **Context-aware help**: Suggestions adapt based on command prefix -- **History navigation**: Up/down arrows to cycle through previous commands -- **Syntax highlighting**: Color-coded responses and tables -- **Metrics display**: Real-time performance stats and turn counters - -### Simple Chat (`agent simple-chat`) -Lightweight, scriptable text-based REPL that supports single messages, interactive sessions, piped input, and batch files. - -**Vim Mode** -Enable vim-style line editing with `--vim`: -- **Normal mode** (`ESC`): Navigate with `hjkl`, `w`/`b` word movement, `0`/`$` line start/end -- **Insert mode** (`i`, `a`, `o`): Regular text input with vim keybindings -- **Editing**: `x` delete char, `dd` delete line, `yy` yank line, `p`/`P` paste -- **History**: Navigate with `Ctrl+P`/`Ctrl+N` or `j`/`k` in normal mode -- **Autocomplete**: Press `Tab` in insert mode for command suggestions -- **Undo/Redo**: `u` to undo changes in normal mode - +### 3.3 Non-interactive Scripts ```bash -# Enable vim mode in simple chat -z3ed agent simple-chat --rom zelda3.sfc --vim +# Run prompts from a file +z3ed agent simple-chat --file scripts/queries.txt --rom zelda3.sfc --stdout -# Example workflow: -# 1. Start in INSERT mode, type your message -# 2. Press ESC to enter NORMAL mode -# 3. Use hjkl to navigate, w/b for word movement -# 4. Press i to return to INSERT mode -# 5. Press Enter to send message +# Feed stdin (useful in CI) +cat <<'PROMPTS' | z3ed agent simple-chat --rom zelda3.sfc --stdout +Describe tile 0x3A in map 0x80. +Suggest palette swaps for dungeon 2. +PROMPTS ``` -### GUI Chat Widget (Editor Integration) -Accessible from **Debug → Agent Chat** inside YAZE. Provides the same conversation loop as the CLI, including streaming history, JSON/table inspection, and ROM-aware tool dispatch. - -Recent additions: -- Persistent chat history across sessions -- Collaborative sessions with shared history -- Screenshot capture for Gemini analysis - -## 7. AI Provider Configuration - -Z3ED supports multiple AI providers. Configuration is resolved with command-line flags taking precedence over environment variables. - -- `--ai_provider=`: Selects the AI provider (`mock`, `ollama`, `gemini`). -- `--ai_model=`: Specifies the model name (e.g., `qwen2.5-coder:7b`, `gemini-2.5-flash`). -- `--gemini_api_key=`: Your Gemini API key. -- `--ollama_host=`: The URL for your Ollama server (default: `http://localhost:11434`). - -### System Prompt Versions - -Z3ED includes multiple system prompt versions for different use cases: - -- **v1 (default)**: Original reactive prompt with basic tool calling -- **v2**: Enhanced with better JSON formatting and error handling -- **v3 (latest)**: Proactive prompt with intelligent tool chaining and implicit iteration - **RECOMMENDED** - -To use v3 prompt: Set environment variable `Z3ED_PROMPT_VERSION=v3` or it will be auto-selected for Gemini 2.0+ models. - -## 8. Learn Command - Knowledge Management - -The learn command enables the AI agent to remember preferences, patterns, and context across sessions. - -### Basic Usage - -```bash -# Store a preference -z3ed agent learn --preference "default_palette=2" - -# Get a preference -z3ed agent learn --get-preference default_palette - -# List all preferences -z3ed agent learn --list-preferences - -# View statistics -z3ed agent learn --stats - -# Export all learned data -z3ed agent learn --export my_learned_data.json - -# Import learned data -z3ed agent learn --import my_learned_data.json -``` - -### Project Context - -Store project-specific information that the agent can reference: - -```bash -# Save project context -z3ed agent learn --project "myrom" --context "Vanilla+ difficulty hack, focus on dungeon redesign" - -# List projects -z3ed agent learn --list-projects - -# Get project details -z3ed agent learn --get-project "myrom" -``` - -### Conversation Memory - -The agent automatically stores summaries of conversations for future reference: - -```bash -# View recent memories -z3ed agent learn --recent-memories 10 - -# Search memories by topic -z3ed agent learn --search-memories "room 5" -``` - -### Storage Location - -All learned data is stored in `~/.yaze/agent/`: -- `preferences.json`: User preferences -- `patterns.json`: Learned ROM patterns -- `projects.json`: Project contexts -- `memories.json`: Conversation summaries - -## 9. TODO Management System - -The TODO Management System enables the z3ed AI agent to create, track, and execute complex multi-step tasks with dependency management and prioritization. - -### Core Capabilities -- Create TODO items with priorities. -- Track task status (pending, in_progress, completed, blocked, cancelled). -- Manage dependencies between tasks. -- Generate execution plans. -- Persist data in JSON. -- Organize by category. -- Record tool/function usage per task. - -### Storage Location -TODOs are persisted to: `~/.yaze/agent/todos.json` (macOS/Linux) or `%APPDATA%/yaze/agent/todos.json` (Windows) - -## 10. CLI Output & Help System - -The `z3ed` CLI features a modernized output system designed to be clean for users and informative for developers. - -### Verbose Logging - -By default, `z3ed` provides clean, user-facing output. For detailed debugging, including API calls and internal state, use the `--verbose` flag. - -**Default (Clean):** -```bash -AI Provider: gemini -Model: gemini-2.5-flash -Waiting for response... -Calling tool: resource-list (type=room) -Tool executed successfully -``` - -**Verbose Mode:** -```bash -# z3ed agent simple-chat "What is room 5?" --verbose -AI Provider: gemini -Model: gemini-2.5-flash -[DEBUG] Initializing Gemini service... -[DEBUG] Function calling: disabled -[DEBUG] Using curl for HTTPS request... -Waiting for response... -[DEBUG] Parsing response... -Calling tool: resource-list (type=room) -Tool executed successfully -``` - -### Hierarchical Help System - -The help system is organized by category for easy navigation. - -- **Main Help**: `z3ed --help` or `z3ed -h` shows a high-level overview of command categories. -- **Category Help**: `z3ed help ` provides detailed information for a specific group of commands (e.g., `agent`, `patch`, `rom`). - -## 10. Collaborative Sessions & Multimodal Vision - -### Overview - -YAZE supports real-time collaboration for ROM hacking through dual modes: **Local** (filesystem-based) for same-machine collaboration, and **Network** (WebSocket-based via yaze-server v2.0) for internet-based collaboration with advanced features including ROM synchronization, snapshot sharing, and AI agent integration. - ---- - -### Local Collaboration Mode - -Perfect for multiple YAZE instances on the same machine or cloud-synced folders (Dropbox, iCloud). - -#### How to Use - -1. Open YAZE → **Debug → Agent Chat** -2. Select **"Local"** mode -3. **Host a Session:** - - Enter session name: `Evening ROM Hack` - - Click **"Host Session"** - - Share the 6-character code (e.g., `ABC123`) -4. **Join a Session:** - - Enter the session code - - Click **"Join Session"** - - Chat history syncs automatically - -#### Features - -- **Shared History**: `~/.yaze/agent/sessions/_history.json` -- **Auto-Sync**: 2-second polling for new messages -- **Participant Tracking**: Real-time participant list -- **Toast Notifications**: Get notified when collaborators send messages -- **Zero Setup**: No server required - -#### Cloud Folder Workaround - -Enable internet collaboration without a server: - -```bash -# Link your sessions directory to Dropbox/iCloud -ln -s ~/Dropbox/yaze-sessions ~/.yaze/agent/sessions - -# Have your collaborator do the same -# Now you can collaborate through cloud sync! -``` - ---- - -### Network Collaboration Mode (yaze-server v2.0) - -Real-time collaboration over the internet with advanced features powered by the yaze-server v2.0. - -#### Requirements - -- **Server**: Node.js 18+ with yaze-server running -- **Client**: YAZE built with `-DYAZE_WITH_GRPC=ON` and `-DZ3ED_AI=ON` -- **Network**: Connectivity between collaborators - -#### Server Setup - -**Option 1: Using z3ed CLI** - ```bash - z3ed collab start [--port=8765] -``` - -**Option 2: Manual Launch** -```bash -cd /path/to/yaze-server -npm install -npm start - -# Server starts on http://localhost:8765 -# Health check: curl http://localhost:8765/health -``` - -**Option 3: Docker** -```bash -docker build -t yaze-server . -docker run -p 8765:8765 yaze-server -``` - -#### Client Connection - -1. Open YAZE → **Debug → Agent Chat** -2. Select **"Network"** mode -3. Enter server URL: `ws://localhost:8765` (or remote server) -4. Click **"Connect to Server"** -5. Host or join sessions like local mode - -#### Core Features - -**Session Management:** -- Unique 6-character session codes -- Participant tracking with join/leave notifications -- Real-time message broadcasting -- Persistent chat history - -**Connection Management:** -- Health monitoring endpoints (`/health`, `/metrics`) -- Graceful shutdown notifications -- Automatic cleanup of inactive sessions -- Rate limiting (100 messages/minute per IP) - -#### Advanced Features (v2.0) - -**ROM ROM Synchronization** -Share ROM edits in real-time: -- Send base64-encoded diffs to all participants -- Automatic ROM hash tracking -- Size limit: 5MB per diff -- Conflict detection via hash comparison - -**Snapshot Multimodal Snapshot Sharing** -Share screenshots and images: -- Capture and share specific editor views -- Support for multiple snapshot types (overworld, dungeon, sprite, etc.) -- Base64 encoding for efficient transfer -- Size limit: 10MB per snapshot - -**Proposal Proposal Management** -Collaborative proposal workflow: -- Share AI-generated proposals with all participants -- Track proposal status: pending, accepted, rejected -- Real-time status updates broadcast to all users -- Proposal history tracked in server database - -**AI Agent Integration** -Server-routed AI queries: -- Send queries through the collaboration server -- Shared AI responses visible to all participants -- Query history tracked in database -- Optional: Disable AI per session - -#### Protocol Reference - -The server uses JSON WebSocket messages over HTTP/WebSocket transport. - -**Client → Server Messages:** - -```json -// Host Session (v2.0 with optional ROM hash and AI control) -{ - "type": "host_session", - "payload": { - "session_name": "My Session", - "username": "alice", - "rom_hash": "abc123...", // optional - "ai_enabled": true // optional, default true - } -} - -// Join Session -{ - "type": "join_session", - "payload": { - "session_code": "ABC123", - "username": "bob" - } -} - -// Chat Message (v2.0 with metadata support) -{ - "type": "chat_message", - "payload": { - "sender": "alice", - "message": "Hello!", - "message_type": "chat", // optional: chat, system, ai - "metadata": {...} // optional metadata - } -} - -// ROM Sync (NEW in v2.0) -{ - "type": "rom_sync", - "payload": { - "sender": "alice", - "diff_data": "base64_encoded_diff...", - "rom_hash": "sha256_hash" - } -} - -// Snapshot Share (NEW in v2.0) -{ - "type": "snapshot_share", - "payload": { - "sender": "alice", - "snapshot_data": "base64_encoded_image...", - "snapshot_type": "overworld_editor" - } -} - -// Proposal Share (NEW in v2.0) -{ - "type": "proposal_share", - "payload": { - "sender": "alice", - "proposal_data": { - "title": "Add new sprite", - "description": "...", - "changes": [...] - } - } -} - -// Proposal Update (NEW in v2.0) -{ - "type": "proposal_update", - "payload": { - "proposal_id": "uuid", - "status": "accepted" // pending, accepted, rejected - } -} - -// AI Query (NEW in v2.0) -{ - "type": "ai_query", - "payload": { - "username": "alice", - "query": "What enemies are in the eastern palace?" - } -} - -// Leave Session -{ "type": "leave_session" } - -// Ping -{ "type": "ping" } -``` - -**Server → Client Messages:** - -```json -// Session Hosted -{ - "type": "session_hosted", - "payload": { - "session_id": "uuid", - "session_code": "ABC123", - "session_name": "My Session", - "participants": ["alice"], - "rom_hash": "abc123...", - "ai_enabled": true - } -} - -// Session Joined -{ - "type": "session_joined", - "payload": { - "session_id": "uuid", - "session_code": "ABC123", - "session_name": "My Session", - "participants": ["alice", "bob"], - "messages": [...] - } -} - -// Chat Message (broadcast) -{ - "type": "chat_message", - "payload": { - "sender": "alice", - "message": "Hello!", - "timestamp": 1709567890123, - "message_type": "chat", - "metadata": null - } -} - -// ROM Sync (broadcast, NEW in v2.0) -{ - "type": "rom_sync", - "payload": { - "sync_id": "uuid", - "sender": "alice", - "diff_data": "base64...", - "rom_hash": "sha256...", - "timestamp": 1709567890123 - } -} - -// Snapshot Shared (broadcast, NEW in v2.0) -{ - "type": "snapshot_shared", - "payload": { - "snapshot_id": "uuid", - "sender": "alice", - "snapshot_data": "base64...", - "snapshot_type": "overworld_editor", - "timestamp": 1709567890123 - } -} - -// Proposal Shared (broadcast, NEW in v2.0) -{ - "type": "proposal_shared", - "payload": { - "proposal_id": "uuid", - "sender": "alice", - "proposal_data": {...}, - "status": "pending", - "timestamp": 1709567890123 - } -} - -// Proposal Updated (broadcast, NEW in v2.0) -{ - "type": "proposal_updated", - "payload": { - "proposal_id": "uuid", - "status": "accepted", - "timestamp": 1709567890123 - } -} - -// AI Response (broadcast, NEW in v2.0) -{ - "type": "ai_response", - "payload": { - "query_id": "uuid", - "username": "alice", - "query": "What enemies are in the eastern palace?", - "response": "The eastern palace contains...", - "timestamp": 1709567890123 - } -} - -// Participant Events -{ - "type": "participant_joined", // or "participant_left" - "payload": { - "username": "bob", - "participants": ["alice", "bob"] - } -} - -// Server Shutdown (NEW in v2.0) -{ - "type": "server_shutdown", - "payload": { - "message": "Server is shutting down. Please reconnect later." - } -} - -// Pong -{ - "type": "pong", - "payload": { "timestamp": 1709567890123 } -} - -// Error -{ - "type": "error", - "payload": { "error": "Session ABC123 not found" } -} -``` - -#### Server Configuration - -**Environment Variables:** -- `PORT` - Server port (default: 8765) -- `ENABLE_AI_AGENT` - Enable AI agent integration (default: true) -- `AI_AGENT_ENDPOINT` - External AI agent endpoint URL - -**Rate Limiting:** -- Window: 60 seconds -- Max messages: 100 per IP per window -- Max snapshot size: 10 MB -- Max ROM diff size: 5 MB - -#### Database Schema (Server v2.0) - -The server uses SQLite with the following tables: - -- **sessions**: Session metadata, ROM hash, AI enabled flag -- **participants**: User tracking with last_seen timestamps -- **messages**: Chat history with message types and metadata -- **rom_syncs**: ROM diff history with hashes -- **snapshots**: Shared screenshots and images -- **proposals**: AI proposal tracking with status -- **agent_interactions**: AI query and response history - -#### Deployment - -**Heroku:** -```bash -cd /path/to/yaze-server -heroku create yaze-collab -git push heroku main -heroku config:set ENABLE_AI_AGENT=true -``` - -**VPS (with PM2):** -```bash -git clone https://github.com/scawful/yaze-server - cd yaze-server - npm install -npm install -g pm2 -pm2 start server.js --name yaze-collab -pm2 startup -pm2 save -``` - -**Docker:** -```bash -docker build -t yaze-server . -docker run -p 8765:8765 -e ENABLE_AI_AGENT=true yaze-server -``` - -#### Testing - -**Health Check:** -```bash -curl http://localhost:8765/health -curl http://localhost:8765/metrics -``` - -**Test with wscat:** -```bash -npm install -g wscat -wscat -c ws://localhost:8765 - -# Host session -> {"type":"host_session","payload":{"session_name":"Test","username":"alice","ai_enabled":true}} - -# Join session (in another terminal) -> {"type":"join_session","payload":{"session_code":"ABC123","username":"bob"}} - -# Send message -> {"type":"chat_message","payload":{"sender":"alice","message":"Hello!"}} -``` - -#### Security Considerations - -**Current Implementation:** -Warning: Basic security - suitable for trusted networks -- No authentication or encryption by default -- Plain text message transmission -- Session codes are the only access control - -**Recommended for Production:** -1. **SSL/TLS**: Use `wss://` with valid certificates -2. **Authentication**: Implement JWT tokens or OAuth -3. **Session Passwords**: Optional per-session passwords -4. **Persistent Storage**: Use PostgreSQL/MySQL for production -5. **Monitoring**: Add logging to CloudWatch/Datadog -6. **Backup**: Regular database backups - ---- - -### Multimodal Vision (Gemini) - -Analyze screenshots of your ROM editor using Gemini's vision capabilities for visual feedback and suggestions. - -#### Requirements - -- `GEMINI_API_KEY` environment variable set -- YAZE built with `-DYAZE_WITH_GRPC=ON` and `-DZ3ED_AI=ON` - -#### Capture Modes - -**Full Window**: Captures the entire YAZE application window - -**Active Editor** (default): Captures only the currently focused editor window - -**Specific Window**: Captures a named window (e.g., "Overworld Editor") - -#### How to Use - -1. Open **Debug → Agent Chat** -2. Expand **"Gemini Multimodal (Preview)"** panel -3. Select capture mode: - - - Full Window - - * Active Editor (default) - - - Specific Window -4. If Specific Window, enter window name: `Overworld Editor` -5. Click **"Capture Snapshot"** -6. Enter prompt: `"What issues do you see with this layout?"` -7. Click **"Send to Gemini"** - -#### Example Prompts - -- "Analyze the tile placement in this overworld screen" -- "What's wrong with the palette colors in this screenshot?" -- "Suggest improvements for this dungeon room layout" -- "Does this screen follow good level design practices?" -- "Are there any visual glitches or tile conflicts?" -- "How can I improve the composition of this room?" - -The AI response appears in your chat history and can reference specific details from the screenshot. In network collaboration mode, multimodal snapshots can be shared with all participants. - ---- - -### Architecture - -``` -┌──────────────────────────────────────────────────────┐ -│ YAZE Editor │ -│ │ -│ ┌─────────────────────────────────────────────┐ │ -│ │ Agent Chat Widget (ImGui) │ │ -│ │ │ │ -│ │ [Collaboration Panel] │ │ -│ │ ├─ Local Mode (filesystem) Working │ │ -│ │ └─ Network Mode (websocket) Working │ │ -│ │ │ │ -│ │ [Multimodal Panel] │ │ -│ │ ├─ Capture Mode Selection Working │ │ -│ │ ├─ Screenshot Capture Working │ │ -│ │ └─ Send to Gemini Working │ │ -│ └─────────────────────────────────────────────┘ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Collaboration │ │ Screenshot │ │ -│ │ Coordinators │ │ Utils │ │ -│ └──────────────────┘ └──────────────────┘ │ -│ │ │ │ -└───────────┼────────────────────┼────────────────────┘ - │ │ - ▼ ▼ -┌──────────────────┐ ┌──────────────────┐ -│ ~/.yaze/agent/ │ │ Gemini Vision │ -│ sessions/ │ │ API │ -└──────────────────┘ └──────────────────┘ - │ - ▼ -┌──────────────────────────────────────────┐ -│ yaze-server v2.0 │ -│ - WebSocket Server (Node.js) │ -│ - SQLite Database │ -│ - Session Management │ -│ - ROM Sync │ -│ - Snapshot Sharing │ -│ - Proposal Management │ -│ - AI Agent Integration │ -└──────────────────────────────────────────┘ -``` - ---- - -### Troubleshooting - -**"Failed to start collaboration server"** -- Ensure Node.js is installed: `node --version` -- Check port availability: `lsof -i :8765` -- Verify server directory exists - -**"Not connected to collaboration server"** -- Verify server is running: `curl http://localhost:8765/health` -- Check firewall settings -- Confirm server URL is correct - -**"Harness client cannot reach gRPC"** -- Confirm YAZE was built with `-DYAZE_WITH_GRPC=ON` and the harness server is enabled via **Debug → Preferences → Automation**. -- Run `z3ed agent test ping --grpc localhost:50051` to verify the CLI can reach the embedded harness endpoint; restart YAZE if the ping fails. -- Inspect the Agent Chat **Harness Monitor** panel for connection status; use **Reconnect** to re-bind if the harness server was restarted. - -**"Widget discovery returns empty"** -- Ensure the target ImGui window is open; the harness only indexes visible widgets. -- Toggle **Automation → Enable Introspection** in YAZE to allow the gRPC server to expose widget metadata. -- Run `z3ed agent test discover --window "ProposalDrawer"` to scope discovery to the window you have open. - -**"Session not found"** -- Verify session code is correct (case-insensitive) -- Check if session expired (server restart clears sessions) -- Try hosting a new session - -**"Rate limit exceeded"** -- Server enforces 100 messages per minute per IP -- Wait 60 seconds and try again - -**Participants not updating** -- Click "Refresh Session" button -- Check network connectivity -- Verify server logs for errors - -**Messages not broadcasting** -- Ensure all clients are in the same session -- Check session code matches exactly -- Verify network connectivity between client and server - ---- - -### References - -- **Server Repository**: [yaze-server](https://github.com/scawful/yaze-server) -- **Agent Editor Docs**: `src/app/editor/agent/README.md` -- **Integration Guide**: `docs/z3ed/YAZE_SERVER_V2_INTEGRATION.md` - -## 11. Roadmap & Implementation Status - -**Last Updated**: October 11, 2025 - -### Completed - -- **Core Infrastructure**: Resource-oriented CLI, proposal workflow, sandbox manager, and resource catalog are all production-ready. -- **AI Backends**: Both Ollama (local) and Gemini (cloud) are operational. -- **Conversational Agent**: The agent service, tool dispatcher (with 5 read-only tools), TUI/simple chat interfaces, and ImGui editor chat widget with persistent history. -- **GUI Test Harness**: A comprehensive GUI testing platform with introspection, widget discovery, recording/replay, and CI integration support. -- **Collaborative Sessions**: - - Local filesystem-based collaborative editing with shared chat history - - Network WebSocket-based collaboration via yaze-server v2.0 - - Dual-mode support (Local/Network) with seamless switching -- **Multimodal Vision**: Gemini vision API integration with multiple capture modes (Full Window, Active Editor, Specific Window). -- **yaze-server v2.0**: Production-ready Node.js WebSocket server with: - - ROM synchronization with diff broadcasting - - Multimodal snapshot sharing - - Collaborative proposal management - - AI agent integration and query routing - - Health monitoring and metrics endpoints - - Rate limiting and security features - -### 📌 Current Progress Highlights (October 5, 2025) - -- **Agent Platform Expansion**: AgentEditor now delivers full bot lifecycle controls, live prompt editing, multi-session management, and metrics synchronized with chat history and popup views. -- **Enhanced Chat Popup**: Left-side AgentChatHistoryPopup evolved into a theme-aware, fully interactive mini-chat with inline sending, multimodal capture, filtering, and proposal indicators to minimize context switching. -- **Proposal Workflow**: Sandbox-backed proposal review is end-to-end with inline quick actions, ProposalDrawer tie-ins, ROM version protections, and collaboration-aware approvals. -- **Collaboration & Networking**: yaze-server v2.0 protocol, cross-platform WebSocket client, collaboration panel, and gRPC ROM service unlock real-time edits, diff sharing, and remote automation. -- **AI & Automation Stack**: Proactive prompt v3, native Gemini function calling, learn/TODO systems, GUI automation planners, multimodal vision suite, and dashboard-surfaced test harness coverage broaden intelligent tooling. - -### Active & Next Steps - -1. **CLI Command Refactoring (Phase 2)**: Complete migration of tool_commands.cc to use new abstraction layer. Refactor 15+ commands to eliminate ~1300 lines of duplication. Add comprehensive unit tests. (See [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md)) -2. **Harden Live LLM Tooling**: Finalize native function-calling loops with Ollama/Gemini and broaden safe read-only tool coverage for dialogue, sprite, and region introspection. -3. **Real-Time Transport Upgrade**: Replace HTTP polling with full WebSocket support across CLI/editor and expose ROM sync, snapshot, and proposal voting controls directly inside the AgentChat widget. -4. **Cross-Platform Certification**: Complete Windows validation for AI, gRPC, collaboration, and build presets leveraging the documented vcpkg workflow. -5. **UI/UX Roadmap Delivery**: Advance EditorManager menu refactors, enhanced hex/palette tooling, Vim-mode terminal chat, and richer popup affordances such as search, export, and resizing. -6. **Collaboration Safeguards**: Layer encrypted sessions, conflict resolution flows, AI-assisted proposal review, and deeper gRPC ROM service integrations to strengthen multi-user safety. -7. **Testing & Observability**: Automate multimodal/GUI harness scenarios, add performance benchmarks, and enable export/replay pipelines for the Test Dashboard. -8. **Hybrid Workflow Examples**: Document and dogfood end-to-end CLI→GUI automation loops (plan/run/diff + harness replay) with screenshots and recorded sessions. -9. **Automation API Unification**: Extract a reusable harness automation API consumed by both CLI `agent test` commands and the Agent Chat widget to prevent serialization drift. -10. **UI Abstraction Cleanup**: Introduce dedicated presenter/controller layers so `editor_manager.cc` delegates to automation and collaboration services, keeping ImGui widgets declarative. - -### Recently Completed (v0.2.2-alpha - October 12, 2025) - -#### Emulator Debugging Infrastructure (NEW) 🔍 -- **Advanced Debugging Service**: Complete gRPC EmulatorService implementation with breakpoints, memory inspection, step execution, and CPU state access -- **Breakpoint Management**: Set execute/read/write/access breakpoints with conditional support for systematic debugging -- **Memory Introspection**: Read/write WRAM, hardware registers ($4xxx), and ROM from running emulator without rebuilds -- **Execution Control**: Step instruction-by-instruction, run to breakpoint, pause/resume with full CPU state capture -- **AI-Driven Debugging**: Function schemas for 12 new emulator tools enabling natural language debugging sessions -- **Reproducible Scripts**: AI can generate bash scripts with breakpoint sequences for regression testing -- **Documentation**: Comprehensive [Emulator Debugging Guide](emulator-debugging-guide.md) with real-world examples - -#### Benefits for AI Agents -- **15min vs 3hr debugging**: Systematic tool-based approach vs manual print-debug cycles -- **No rebuilds required**: Set breakpoints and read state without recompiling -- **Precise observation**: Pause at exact addresses, read memory at critical moments -- **Collaborative debugging**: Share tool call sequences and findings in chat -- **Example**: Debugging ALTTP input issue went from 15 rebuild cycles to 6 tool calls (see `docs/examples/ai-debug-input-issue.md`) - -### Previously Completed (v0.2.1-alpha - October 11, 2025) - -#### CLI Architecture Improvements -- **Command Abstraction Layer**: Three-tier abstraction system (`CommandContext`, `ArgumentParser`, `OutputFormatter`) to eliminate code duplication across CLI commands -- **CommandHandler Base Class**: Structured base class for consistent command implementation with automatic context management -- **Refactoring Framework**: Complete migration guide and examples showing 50-60% code reduction per command -- **Documentation**: Comprehensive [Command Abstraction Guide](../../internal/agents/z3ed-command-abstraction.md) with migration checklist and testing strategies - -#### Code Quality & Maintainability -- **Duplication Elimination**: New abstraction layer removes ~1300 lines of duplicated code across tool commands -- **Consistent Patterns**: All commands now follow unified structure for argument parsing, ROM loading, and output formatting -- **Better Testing**: Each component (context, parser, formatter) can be unit tested independently -- **AI-Friendly**: Predictable command structure makes it easier for AI to generate and validate tool calls - -### Previously Completed (v0.2.0-alpha - October 5, 2025) - -#### Core AI Features -- **Enhanced System Prompt (v3)**: Proactive tool chaining with implicit iteration to minimize back-and-forth conversations -- **Learn Command**: Full implementation with preferences, ROM patterns, project context, and conversation memory storage -- **Native Gemini Function Calling**: Upgraded from manual curl to native function calling API with automatic tool schema generation -- **Multimodal Vision Testing**: Comprehensive test suite for Gemini vision capabilities with screenshot integration -- **AI-Controlled GUI Automation**: Natural language parsing (`AIActionParser`) and test script generation (`GuiActionGenerator`) for automated tile placement -- **TODO Management System**: Full `TodoManager` class with CRUD operations, CLI commands, dependency tracking, execution planning, and JSON persistence. - -#### Version Management & Protection -- **ROM Version Management System**: `RomVersionManager` with automatic snapshots, safe points, corruption detection, and rollback capabilities -- **Proposal Approval Framework**: `ProposalApprovalManager` with host/majority/unanimous voting modes to protect ROM from unwanted changes - -#### Networking & Collaboration (NEW) -- **Cross-Platform WebSocket Client**: `WebSocketClient` with Windows/macOS/Linux support using httplib -- **Collaboration Service**: `CollaborationService` integrating version management with real-time networking -- **yaze-server v2.0 Protocol**: Extended with proposal voting (`proposal_vote`, `proposal_vote_received`) -- **z3ed Network Commands**: CLI commands for remote collaboration (`net connect`, `net join`, `proposal submit/wait`) -- **Collaboration UI Panel**: `CollaborationPanel` widget with version history, ROM sync tracking, snapshot gallery, and approval workflow -- **gRPC ROM Service**: Complete protocol buffer and implementation for remote ROM manipulation (pending build integration) - -#### UI/UX Enhancements -- **Welcome Screen Enhancement**: Dynamic theme integration, Zelda-themed animations, and project cards. -- **Component Refactoring**: `PaletteWidget` renamed and moved, UI organization improved (`app/editor/ui/` for welcome_screen, editor_selection_dialog, background_renderer). - -#### Build System & Infrastructure -- **gRPC Windows Build Optimization**: vcpkg integration for 10-20x faster Windows builds, removed abseil-cpp submodule -- **Cross-Platform Networking**: Native socket support (ws2_32 on Windows, BSD sockets on Unix) -- **Namespace Refactoring**: Created `app/net` namespace for networking components -- **Improved Documentation**: Consolidated architecture, enhancement plans, networking guide, and build instructions with JSON-first approach -- **Build System Improvements**: `mac-ai` preset, proto fixes, and updated GEMINI.md with AI build policies. - -## 12. Troubleshooting - -- **"Build with -DZ3ED_AI=ON" warning**: AI features are disabled. Rebuild with the flag to enable them. -- **"gRPC not available" error**: GUI testing is disabled. Rebuild with `-DYAZE_WITH_GRPC=ON`. -- **AI generates invalid commands**: The prompt may be vague. Use specific coordinates, tile IDs, and map context. -- **Chat mode freezes**: Use `agent simple-chat` instead of the FTXUI-based `agent chat` for better stability, especially in scripts. +## 4. Automation Tips + +1. **Sandbox first** – point the agent at a copy of your ROM (`--sandbox` flag) so you can review + patches safely. +2. **Log everything** – `--log-file agent.log` captures the provider transcript for auditing. +3. **Structure output** – most list/describe commands support `--format json` or `--format yaml` + for downstream tooling. +4. **Combine with `yaze_test`** – run `./build_ai/bin/yaze_test --unit` after batch patches to + confirm nothing regressed. +5. **Use TUI filters** – in `--tui`, press `:` to open the command palette, type part of a command, + hit Enter, and the tool auto-fills the available flags. + +## 5. Troubleshooting + +| Symptom | Fix | +| --- | --- | +| `agent chat` hangs after a prompt | Ensure `ollama serve` or the Gemini API key is configured. | +| `libgrpc` or `absl` missing | Re-run the `*-ai` preset; plain debug presets do not pull the agent stack. | +| CLI cannot find the ROM | Use absolute paths or set `YAZE_DEFAULT_ROM=/path/to/zelda3.sfc`. | +| Tool reports "command not found" | Run `z3ed --help` to refresh the command index; stale binaries from older builds lack new verbs. | +| Proposal diffs are empty | Provide `--rom` plus either `--sandbox` or `--workspace` so the agent knows where to stage files. | + +## 6. Related Documentation +- `docs/public/developer/testing-without-roms.md` – ROM-less fixtures for CI. +- `docs/public/developer/debugging-guide.md` – logging and instrumentation tips shared between the + GUI and CLI. +- `docs/internal/agents/` – deep dives into the agent architecture and refactor plans (internal + audience only).