yaze/docs/release-notes-draft.md

yaze Release Notes (Draft)

Release Version: v0.2.0 (Proposed) Release Date: 2025-11-20 (Target) Branch: feat/http-api-phase2 → develop → master PR: #49

---

Overview

This release focuses on build system stabilization across all three major platforms (Windows, Linux, macOS), introduces a groundbreaking HTTP REST API for external agent access, and delivers major improvements to the AI infrastructure. After resolving 2+ weeks of Windows build blockers and implementing comprehensive testing infrastructure, yaze is ready for broader adoption.

Key Highlights:

• HTTP REST API server for automation and external tools
• Complete Windows build fixes (std::filesystem, exception handling)
• Unified AI model registry supporting multiple providers
• Comprehensive testing infrastructure with release checklists
• Symbol conflict resolution across all platforms
• Enhanced build system with 11 new CMake presets

---

New Features

HTTP REST API Server (Phase 2)

The z3ed CLI tool now includes an optional HTTP REST API server for external automation and integration:

Features:

• Optional at build time: Controlled via YAZE_ENABLE_HTTP_API CMake flag
• Secure by default: Defaults to localhost binding, opt-in for remote access
• Conditional compilation: Zero overhead when disabled
• Well-documented: Comprehensive API docs at src/cli/service/api/README.md

Initial Endpoints:

• GET /api/v1/health - Server health check
• GET /api/v1/models - List available AI models from all providers

Usage:

# Enable HTTP API at build time
cmake --preset mac-ai -DYAZE_ENABLE_HTTP_API=ON
cmake --build --preset mac-ai --target z3ed

# Launch with HTTP server
./build_ai/bin/z3ed --http-port=8080 --http-host=localhost

# Test endpoints
curl http://localhost:8080/api/v1/health
curl http://localhost:8080/api/v1/models

CLI Flags:

• --http-port=<port> - Port to listen on (default: 8080)
• --http-host=<host> - Host to bind to (default: localhost)

Unified Model Registry

Cross-provider AI model management for consistent model discovery:

Features:

• Singleton ModelRegistry class for centralized model tracking
• Support for Ollama and Gemini providers (extensible design)
• Unified ListAllModels() API for all providers
• Model information caching for performance
• Foundation for future UI unification

Developer API:

#include "cli/service/ai/model_registry.h"

// Get all models from all providers
auto all_models = ModelRegistry::Get().ListAllModels();

// Get models from specific provider
auto ollama_models = ModelRegistry::Get().ListModelsByProvider("ollama");

Enhanced Build System

11 New CMake Presets across all platforms:

macOS:

• mac-dbg, mac-dbg-v - Debug builds (verbose variant)
• mac-rel - Release build
• mac-dev - Development build with ROM tests
• mac-ai - AI-enabled build with gRPC
• mac-uni - Universal binary (ARM64 + x86_64)

Linux:

• lin-dbg, lin-dbg-v - Debug builds (verbose variant)
• lin-rel - Release build
• lin-dev - Development build with ROM tests
• lin-ai - AI-enabled build with gRPC

Windows:

• Existing presets enhanced with better compiler detection

Key Improvements:

• Platform-specific optimization flags
• Consistent build directory naming
• Verbose variants for debugging build issues
• AI presets bundle gRPC, agent UI, and HTTP API support

Comprehensive Testing Infrastructure

New Documentation:

• docs/internal/testing/README.md - Master testing guide
• docs/public/developer/testing-quick-start.md - 5-minute pre-push checklist
• docs/internal/testing/integration-plan.md - 6-week rollout plan
• docs/internal/release-checklist-template.md - Release validation template

New Scripts:

• scripts/pre-push.sh - Fast local validation (<2 minutes)
• scripts/install-git-hooks.sh - Easy git hook installation
• scripts/agents/run-tests.sh - Agent-friendly test runner
• scripts/agents/smoke-build.sh - Quick build verification
• scripts/agents/test-http-api.sh - HTTP API endpoint testing
• scripts/agents/get-gh-workflow-status.sh - CLI-based CI monitoring
• scripts/agents/windows-smoke-build.ps1 - Windows smoke test helper

CI/CD Enhancements:

• workflow_dispatch trigger with enable_http_api_tests parameter
• Platform-specific build and test jobs
• Conditional HTTP API testing in CI
• Improved artifact uploads on failures

Agent Collaboration Framework

New Documentation:

• docs/internal/agents/coordination-board.md - Multi-agent coordination protocol
• docs/internal/agents/personas.md - Agent role definitions
• docs/internal/agents/initiative-template.md - Task planning template
• docs/internal/agents/claude-gemini-collaboration.md - Team structures
• docs/internal/agents/agent-leaderboard.md - Contribution tracking
• docs/internal/agents/gh-actions-remote.md - Remote CI triggers

Build Environment Improvements

Sandbox/Offline Support:

• Homebrew fallback for yaml-cpp (already existed, documented)
• Homebrew fallback for googletest (newly added)
• Better handling of network-restricted environments
• Updated docs/public/build/build-from-source.md with offline instructions

Usage:

# macOS: Install dependencies locally
brew install yaml-cpp googletest

# Configure with local dependencies
cmake --preset mac-dbg

---

Bug Fixes

Windows Platform Fixes

1. std::filesystem Compilation Errors (2+ Week Blocker)

Commits: b556b155a5, 19196ca87c, cbdc6670a1, 84cdb09a5b, 43118254e6

Problem: Windows builds failing with error: 'filesystem' file not found

• clang-cl on GitHub Actions Windows Server 2022 couldn't find std::filesystem
• Compiler defaulted to pre-C++17 mode, exposing only std::experimental::filesystem
• Build logs showed -std=c++23 (Unix-style) instead of /std:c++latest (MSVC-style)

Root Cause:

• clang-cl requires MSVC-style /std:c++latest flag to access modern MSVC STL
• Detection logic using CMAKE_CXX_SIMULATE_ID and CMAKE_CXX_COMPILER_FRONTEND_VARIANT wasn't triggering in CI

Solution:

• Apply /std:c++latest unconditionally on Windows (safe for both MSVC and clang-cl)
• Simplified approach after multiple detection attempts failed

Impact: Resolves all Windows std::filesystem compilation errors in:

• src/util/platform_paths.h
• src/util/platform_paths.cc
• src/util/file_util.cc
• All other files using <filesystem>

2. Exception Handling Disabled (Critical)

Commit: 0835555d04

Problem: Windows build failing with error: cannot use 'throw' with exceptions disabled

• Code in file_util.cc and platform_paths.cc uses C++ exception handling
• clang-cl wasn't enabling exceptions by default

Solution:

• Add /EHsc compiler flag for clang-cl on Windows
• Flag enables C++ exception handling with standard semantics

Impact: Resolves compilation errors in all files using throw, try, catch

3. Abseil Include Path Issues

Commit: c2bb90a3f1

Problem: clang-cl couldn't find Abseil headers like absl/status/status.h

• When YAZE_ENABLE_GRPC=ON, Abseil comes bundled with gRPC via CPM
• Include paths from bundled targets weren't propagating correctly with Ninja + clang-cl

Solution:

• Explicitly add Abseil source directory to yaze_util include paths on Windows
• Ensures clang-cl can find all Abseil headers

Impact: Fixes Windows build failures for all Abseil-dependent code

Linux Platform Fixes

1. FLAGS Symbol Conflicts (Critical Blocker)

Commits: eb77bbeaff, 43a0e5e314

Problem: Linux build failing with multiple definition errors

• FLAGS_rom and FLAGS_norom defined in both flags.cc and emu_test.cc
• FLAGS_quiet undefined reference errors
• ODR (One Definition Rule) violations

Root Cause:

• yaze_emu_test linked to yaze_editor → yaze_agent → flags.cc
• Emulator test defined its own flags conflicting with agent flags
• FLAGS_quiet was defined in cli_main.cc instead of shared flags.cc

Solutions:

1. Move FLAGS_quiet definition to flags.cc (shared location)
2. Change cli_main.cc to use ABSL_DECLARE_FLAG (declaration only)
3. Rename emu_test.cc flags to unique names (FLAGS_emu_test_rom)
4. Remove yaze_editor and yaze_app_core_lib dependencies from yaze_emu_test

Impact: Resolves all Linux symbol conflict errors, clean builds on Ubuntu 22.04

2. Circular Dependency in Graphics Libraries

Commit: 0812a84a22

Problem: Circular dependency between yaze_gfx_render, yaze_gfx_core, and yaze_gfx_debug

• AtlasRenderer (in render) depends on Bitmap (core) and PerformanceProfiler (debug)
• PerformanceDashboard (in debug) calls AtlasRenderer::Get()
• Circular dependency chain: render → core → debug → render

Solution:

• Move atlas_renderer.cc from GFX_RENDER_SRC to GFX_CORE_SRC
• atlas_renderer now lives in layer 4 (core) where it can access both debug and render
• Eliminates circular dependency while preserving functionality

Impact: Clean dependency graph, faster link times

3. Missing yaze_gfx_render Dependency

Commit: e36d81f357

Problem: Linker error where yaze_gfx_debug.a called AtlasRenderer methods but wasn't linking against yaze_gfx_render

Solution: Add yaze_gfx_render to yaze_gfx_debug dependencies

Impact: Fixes undefined reference errors on Linux

macOS Platform Fixes

1. z3ed Linker Error

Commit: 9c562df277

Problem: z3ed CLI tool failing to link with library 'yaze_app_core_lib' not found

• z3ed (via yaze_agent) depends on yaze_app_core_lib
• Library only created when YAZE_BUILD_APP=ON (which doesn't exist)
• Standalone z3ed builds failed

Root Cause:

• yaze_app_core_lib creation guarded by incorrect condition
• Should be available whenever agent features needed

Solution:

1. Create src/app/app_core.cmake with yaze_app_core_lib creation
2. Modify src/app/app.cmake to include app_core.cmake, then conditionally build yaze executable
3. Include app/app.cmake whenever YAZE_BUILD_GUI OR YAZE_BUILD_Z3ED OR YAZE_BUILD_TESTS

Impact: z3ed builds successfully on macOS, clean separation of library vs executable

Code Quality Fixes

1. clang-format Violations (CI Blocker)

Commits: bb5e2002c2, fa3da8fc27, 14d1f5de4c

Problem: CI failing with 38+ formatting violations

• TUI files had indentation issues
• Third-party libraries (src/lib/*) were being formatted

Solutions:

1. Update CMakeLists.txt to exclude src/lib/* from format targets
2. Apply clang-format to all source files
3. Fix specific violations in chat_tui.cc, tui.cc, unified_layout.cc

Impact: Clean code formatting, CI Code Quality job passes

2. Flag Parsing Error Handling

Commit: 99e6106721

Problem: Inconsistent error handling during flag parsing

Solution:

• Add detail::FlagParseFatal utility function for fatal errors
• Replace runtime error throws with consistent FlagParseFatal calls
• Improve error reporting and program termination

Impact: Better error messages, consistent failure handling

---

Infrastructure Improvements

Build System Enhancements

CMake Configuration:

• Add YAZE_ENABLE_HTTP_API option (defaults to ${YAZE_ENABLE_AGENT_CLI})
• Add YAZE_HTTP_API_ENABLED compile definition when enabled
• Add YAZE_AI_RUNTIME_AVAILABLE flag for conditional AI features
• Enhanced conditional compilation support

Abseil Linking Fix (Critical):

• Fix Abseil linking bug in src/util/util.cmake
• Abseil targets now properly linked when YAZE_ENABLE_GRPC=OFF
• Resolves undefined reference errors on all platforms

Submodule Reorganization:

• Moved all third-party libraries from src/lib/ and third_party/ to unified ext/ directory
• Better organization and clarity in dependency management
• Updated all CMake paths to point to ext/

Libraries moved:

• ext/SDL (was src/lib/SDL)
• ext/imgui (was src/lib/imgui)
• ext/asar (was src/lib/asar)
• ext/httplib (was third_party/httplib)
• ext/json (was third_party/json)
• ext/nativefiledialog-extended (was src/lib/nativefiledialog-extended)

Documentation Overhaul

New User Documentation:

• docs/public/build/quick-reference.md - Single source of truth for build commands
• docs/public/developer/testing-quick-start.md - 5-minute pre-push guide
• docs/public/examples/README.md - Usage examples

New Internal Documentation:

• Complete agent coordination framework (6 documents)
• Comprehensive testing infrastructure (3 documents)
• Release process documentation (2 documents)
• AI infrastructure handoff documents (2 documents)

Updated Documentation:

• docs/public/build/build-from-source.md - macOS offline build instructions
• README.md - Updated version, features, and build instructions
• CLAUDE.md - Enhanced with build quick reference links
• GEMINI.md - Added for Gemini-specific guidance

New Project Documentation:

• CONTRIBUTING.md - Contribution guidelines
• AGENTS.md - Agent coordination requirements
• Agent-specific guidance files

CI/CD Pipeline Improvements

GitHub Actions Enhancements:

• Add workflow_dispatch trigger with enable_http_api_tests boolean input
• Conditional HTTP API test step in test job
• Platform-specific test execution (stable, unit, integration)
• Improved artifact uploads on build/test failures
• CPM dependency caching for faster builds
• sccache/ccache for incremental compilation

New Workflows:

• Remote CI triggering via gh workflow run
• Optional HTTP API testing in CI
• Better status monitoring for agents

Testing Infrastructure

Test Organization:

• Clear separation: unit (fast), integration (ROM), e2e (GUI), benchmarks
• Platform-specific test execution
• ROM-dependent test gating
• Environment variable configuration support

Test Helpers:

• scripts/pre-push.sh - Fast local validation
• scripts/agents/run-tests.sh - Consistent test execution
• Cross-platform test preset support
• Visual Studio generator detection

CI Integration:

• Platform matrix testing (Ubuntu 22.04, macOS 14, Windows 2022)
• Test result uploads
• Failure artifact collection
• Performance regression tracking

---

Breaking Changes

None - This release maintains full backward compatibility with existing ROMs, save files, configuration files, and plugin APIs.

---

Known Issues

gRPC Network Fetch in Sandboxed Environments

Issue: Smoke builds fail in network-restricted environments (e.g., Claude Code sandbox) due to gRPC GitHub fetch Workaround: Use GitHub Actions CI for validation instead of local builds Status: Won't fix - gRPC is too large for Homebrew fallback approach

Platform-Specific Considerations

Windows:

• Requires Visual Studio 2022 with "Desktop development with C++" workload
• gRPC builds take 15-20 minutes first time (use vcpkg for faster builds)
• Watch for path length limits: Enable long paths with git config --global core.longpaths true

macOS:

• gRPC v1.67.1 is the tested stable version for ARM64
• Bundled Abseil used by default to avoid deployment target mismatches

Linux:

• Requires GCC 12+ or Clang 16+
• Install dependencies: libgtk-3-dev, libdbus-1-dev, pkg-config

---

Migration Guide

No migration required - this release is fully backward compatible.

---

Upgrade Instructions

For Users

1. Download the latest release from GitHub Releases (when available)
2. Extract the archive to your preferred location
3. Run the application:
   • Windows: yaze.exe
   • macOS: yaze.app
   • Linux: ./yaze

For Developers

Updating from Previous Version

# Update your repository
git checkout develop
git pull origin develop

# Update submodules (important - new ext/ structure)
git submodule update --init --recursive

# Clean old build (recommended due to submodule moves)
rm -rf build build_test

# Verify build environment
./scripts/verify-build-environment.sh --fix  # macOS/Linux
.\scripts\verify-build-environment.ps1 -FixIssues  # Windows

# Build with new presets
cmake --preset mac-dbg  # or lin-dbg, win-dbg
cmake --build --preset mac-dbg --target yaze

Testing HTTP API Features

# Build with HTTP API enabled
cmake --preset mac-ai -DYAZE_ENABLE_HTTP_API=ON
cmake --build --preset mac-ai --target z3ed

# Launch with HTTP server
./build/bin/z3ed --http-port=8080

# Test in another terminal
curl http://localhost:8080/api/v1/health
curl http://localhost:8080/api/v1/models

---

Credits

This release was made possible through collaboration between multiple AI agents and human oversight:

Development:

• CLAUDE_AIINF - Windows build fixes, Linux symbol resolution, HTTP API implementation
• CLAUDE_CORE - Code quality fixes, UI infrastructure
• CLAUDE_TEST_COORD - Testing infrastructure, release checklists
• GEMINI_AUTOM - CI/CD enhancements, Windows exception handling fix
• CODEX - Documentation coordination, release preparation

Platform Testing:

• CLAUDE_MAC_BUILD - macOS platform validation
• CLAUDE_LIN_BUILD - Linux platform validation
• CLAUDE_WIN_BUILD - Windows platform validation

Project Maintainer:

• scawful - Project oversight, requirements, and direction

---

Statistics

Commits: 31 commits on feat/http-api-phase2 branch Files Changed: 400+ files modified Lines Changed: ~50,000 lines (additions + deletions) Build Fixes: 8 critical platform-specific fixes New Features: 2 major (HTTP API, Model Registry) New Documentation: 15+ new docs, 10+ updated New Scripts: 7 helper scripts for testing and CI Test Infrastructure: Complete overhaul with 6-week rollout plan

---

Looking Forward

Next Release (v0.3.0)

Planned Features:

• UI unification using ModelRegistry (Phase 3)
• Additional HTTP API endpoints (ROM operations, dungeon/overworld editing)
• Enhanced agent collaboration features
• Performance optimizations
• More comprehensive test coverage

Infrastructure Goals:

• Phase 2-5 testing infrastructure rollout (12 weeks remaining)
• Symbol conflict detection automation
• CMake configuration validation
• Platform matrix testing expansion

Long-Term Roadmap

See docs/internal/roadmaps/2025-11-modernization.md for detailed plans.

---

Release Notes History

• v0.2.0 (2025-11-20): HTTP API, build system stabilization, testing infrastructure
• v0.1.0 (Previous): Initial release with GUI editor, Asar integration, ZSCustomOverworld support

---

Prepared by: CODEX_RELEASE_PREP Date: 2025-11-20 Status: DRAFT - Ready for review