Enhance z3ed Documentation and CLI Design
- Updated E6-z3ed-cli-design.md to reflect the current state and design goals of the z3ed CLI, emphasizing its evolution into a powerful tool for ROM hacking with AI integration. - Introduced E6-z3ed-reference.md as a comprehensive technical reference, detailing command usage, implementation guides, and troubleshooting tips. - Expanded README.md to provide a clearer overview of z3ed, including documentation structure and quick start guides for users. - Enhanced the archive README.md to clarify the purpose of archived documents and their relevance to the project's history and technical decisions.
This commit is contained in:
scawful
1
Doxyfile
1
Doxyfile
@@ -1057,6 +1057,7 @@ RECURSIVE = YES
|
|||||||
EXCLUDE = assets/ \
|
EXCLUDE = assets/ \
|
||||||
build/ \
|
build/ \
|
||||||
cmake/ \
|
cmake/ \
|
||||||
|
docs/archive/ \
|
||||||
src/lib/ \
|
src/lib/ \
|
||||||
|
|
||||||
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
|
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
|
||||||
|
|||||||
313
docs/z3ed/CONSOLIDATION_SUMMARY.md
Normal file
313
docs/z3ed/CONSOLIDATION_SUMMARY.md
Normal file
@@ -0,0 +1,313 @@
|
|||||||
|
# z3ed Documentation Consolidation Summary
|
||||||
|
|
||||||
|
**Date**: October 2, 2025
|
||||||
|
**Action**: Documentation reorganization and consolidation
|
||||||
|
**Status**: Complete
|
||||||
|
|
||||||
|
## What Changed
|
||||||
|
|
||||||
|
The z3ed documentation has been reorganized into a clean, hierarchical structure that eliminates redundancy and establishes clear sources of truth.
|
||||||
|
|
||||||
|
### Before Consolidation
|
||||||
|
|
||||||
|
- **15 active documents** in main folder (many overlapping)
|
||||||
|
- **19 archived documents** mixed with current docs
|
||||||
|
- No clear hierarchy or "source of truth"
|
||||||
|
- Redundant information across multiple files
|
||||||
|
- Difficult to find current vs historical information
|
||||||
|
|
||||||
|
### After Consolidation
|
||||||
|
|
||||||
|
- **3 core documents** (design, reference, implementation plan)
|
||||||
|
- **3 quick start guides** (focused and practical)
|
||||||
|
- **4 status documents** (clear current state)
|
||||||
|
- **19 archived documents** (properly organized with README)
|
||||||
|
- Clear documentation hierarchy
|
||||||
|
- Single source of truth for each topic
|
||||||
|
|
||||||
|
## Core Documentation Structure
|
||||||
|
|
||||||
|
### 1. Source of Truth Documents
|
||||||
|
|
||||||
|
#### E6-z3ed-cli-design.md (Updated)
|
||||||
|
**Purpose**: Architecture and design decisions
|
||||||
|
**Content**:
|
||||||
|
- System overview and current state (Oct 2025)
|
||||||
|
- Design goals and architectural decisions
|
||||||
|
- Command structure
|
||||||
|
- Agentic workflow framework
|
||||||
|
- TUI architecture
|
||||||
|
- Implementation roadmap phases
|
||||||
|
|
||||||
|
**Role**: **PRIMARY SOURCE OF TRUTH** for design decisions
|
||||||
|
|
||||||
|
#### E6-z3ed-reference.md (New - Comprehensive)
|
||||||
|
**Purpose**: Technical reference for developers
|
||||||
|
**Content Consolidated From**:
|
||||||
|
- IT-01-QUICKSTART.md (test harness details)
|
||||||
|
- AGENT_TEST_QUICKREF.md (CLI command details)
|
||||||
|
- IT-01-grpc-evaluation.md (gRPC technical details)
|
||||||
|
- GRPC_TEST_SUCCESS.md (implementation details)
|
||||||
|
- IT-01-PHASE3-COMPLETE.md (API learnings)
|
||||||
|
- Various troubleshooting docs
|
||||||
|
|
||||||
|
**Sections**:
|
||||||
|
1. Architecture Overview - Component diagrams and data flow
|
||||||
|
2. Command Reference - Complete CLI command documentation
|
||||||
|
3. Implementation Guide - Building, configuring, deploying
|
||||||
|
4. Testing & Validation - E2E tests, manual workflows, benchmarks
|
||||||
|
5. Development Workflows - Adding commands, RPCs, test patterns
|
||||||
|
6. Troubleshooting - Common issues and solutions
|
||||||
|
7. API Reference - RPC schemas, resource catalog format
|
||||||
|
8. Platform Notes - macOS/Windows/Linux specifics
|
||||||
|
|
||||||
|
**Role**: **ONE-STOP TECHNICAL REFERENCE** for all implementation details
|
||||||
|
|
||||||
|
#### E6-z3ed-implementation-plan.md (Maintained)
|
||||||
|
**Purpose**: Project tracker and task backlog
|
||||||
|
**Content**:
|
||||||
|
- Current priorities with time estimates
|
||||||
|
- Task backlog with status tracking
|
||||||
|
- Implementation phases (completed/active/planned)
|
||||||
|
- Known issues and blockers
|
||||||
|
- Timeline and milestones
|
||||||
|
|
||||||
|
**Role**: **LIVING TRACKER** for development progress
|
||||||
|
|
||||||
|
### 2. Quick Start Guides (Retained)
|
||||||
|
|
||||||
|
These focused guides provide fast onboarding for specific tasks:
|
||||||
|
|
||||||
|
- **IT-01-QUICKSTART.md** - Test harness quick start
|
||||||
|
- **AGENT_TEST_QUICKREF.md** - CLI agent test command reference
|
||||||
|
- **E2E_VALIDATION_GUIDE.md** - Complete validation checklist
|
||||||
|
|
||||||
|
**Why Retained**: Quick reference cards for common workflows
|
||||||
|
|
||||||
|
### 3. Status Documents (Retained)
|
||||||
|
|
||||||
|
Current status and planning documents:
|
||||||
|
|
||||||
|
- **README.md** - Documentation index and project overview
|
||||||
|
- **PROJECT_STATUS_OCT2.md** - Current project status snapshot
|
||||||
|
- **NEXT_PRIORITIES_OCT2.md** - Detailed next steps with implementation guides
|
||||||
|
- **WORK_SUMMARY_OCT2.md** - Recent accomplishments
|
||||||
|
|
||||||
|
**Why Retained**: Track current state and progress
|
||||||
|
|
||||||
|
### 4. Archive (Organized)
|
||||||
|
|
||||||
|
All historical and superseded documents moved to `archive/` with explanatory README:
|
||||||
|
|
||||||
|
**Technical Investigations**:
|
||||||
|
- IT-01-grpc-evaluation.md
|
||||||
|
- GRPC_TECHNICAL_NOTES.md
|
||||||
|
- DEPENDENCY_MANAGEMENT.md
|
||||||
|
|
||||||
|
**Implementation Progress Logs**:
|
||||||
|
- GRPC_TEST_SUCCESS.md
|
||||||
|
- IT-01-PHASE2-IMPLEMENTATION-GUIDE.md
|
||||||
|
- IT-01-PHASE3-COMPLETE.md
|
||||||
|
- IT-01-getting-started-grpc.md
|
||||||
|
|
||||||
|
**Session Summaries**:
|
||||||
|
- STATE_SUMMARY_2025-10-01.md
|
||||||
|
- STATE_SUMMARY_2025-10-02.md
|
||||||
|
- SESSION_SUMMARY_OCT2.md
|
||||||
|
- SESSION_SUMMARY_OCT2_EVENING.md
|
||||||
|
- PROGRESS_SUMMARY_2025-10-02.md
|
||||||
|
|
||||||
|
**Implementation Status Reports**:
|
||||||
|
- IMPLEMENTATION_PROGRESS_OCT2.md
|
||||||
|
- IMPLEMENTATION_STATUS_OCT2_PM.md
|
||||||
|
- RUNTIME_FIX_COMPLETE_OCT2.md
|
||||||
|
- QUICK_TEST_RUNTIME_FIX.md
|
||||||
|
|
||||||
|
**Planning & Organization**:
|
||||||
|
- DOCUMENTATION_CONSOLIDATION_OCT2.md
|
||||||
|
- DOCUMENTATION_REVIEW_OCT2.md
|
||||||
|
- FILE_MODIFICATION_CHECKLIST.md
|
||||||
|
|
||||||
|
## Information Mapping
|
||||||
|
|
||||||
|
### Where Did Content Go?
|
||||||
|
|
||||||
|
| Original Document(s) | New Location | Notes |
|
||||||
|
|---------------------|--------------|-------|
|
||||||
|
| IT-01-grpc-evaluation.md | E6-z3ed-reference.md § Implementation Guide | gRPC setup, Windows notes |
|
||||||
|
| GRPC_TEST_SUCCESS.md | E6-z3ed-reference.md § Testing & Validation | Phase 1 completion details |
|
||||||
|
| IT-01-PHASE2-IMPLEMENTATION-GUIDE.md | archive/ | Historical - covered in reference |
|
||||||
|
| IT-01-PHASE3-COMPLETE.md | E6-z3ed-reference.md § API Reference | ImGuiTestEngine API learnings |
|
||||||
|
| GRPC_TECHNICAL_NOTES.md | E6-z3ed-reference.md § Platform Notes | Technical quirks and workarounds |
|
||||||
|
| Various troubleshooting docs | E6-z3ed-reference.md § Troubleshooting | Consolidated common issues |
|
||||||
|
| Session summaries | archive/ | Historical snapshots |
|
||||||
|
| Status reports | archive/ | Superseded by PROJECT_STATUS_OCT2.md |
|
||||||
|
|
||||||
|
### Key Content Areas in E6-z3ed-reference.md
|
||||||
|
|
||||||
|
**Architecture Overview** (New comprehensive diagrams):
|
||||||
|
- System component stack
|
||||||
|
- Proposal lifecycle flow
|
||||||
|
- Data flow diagrams
|
||||||
|
|
||||||
|
**Command Reference** (Consolidated from multiple sources):
|
||||||
|
- All agent commands with examples
|
||||||
|
- ROM, palette, overworld, dungeon commands
|
||||||
|
- Complete option documentation
|
||||||
|
|
||||||
|
**Implementation Guide** (From multiple scattered docs):
|
||||||
|
- Building with gRPC (macOS, Windows, Linux)
|
||||||
|
- Starting test harness
|
||||||
|
- Testing with grpcurl
|
||||||
|
- Platform-specific setup
|
||||||
|
|
||||||
|
**Testing & Validation** (Consolidated from E2E guide + others):
|
||||||
|
- E2E test script
|
||||||
|
- Manual workflow testing
|
||||||
|
- Performance benchmarks
|
||||||
|
|
||||||
|
**Development Workflows** (New section):
|
||||||
|
- Adding new commands
|
||||||
|
- Adding new RPCs
|
||||||
|
- Adding test patterns
|
||||||
|
- Clear step-by-step guides
|
||||||
|
|
||||||
|
**Troubleshooting** (Consolidated from ~5 docs):
|
||||||
|
- Common issues
|
||||||
|
- Debug mode
|
||||||
|
- Platform quirks
|
||||||
|
- Solutions and workarounds
|
||||||
|
|
||||||
|
**API Reference** (Consolidated proto docs):
|
||||||
|
- RPC service definitions
|
||||||
|
- Request/Response schemas
|
||||||
|
- Resource catalog format
|
||||||
|
- Example payloads
|
||||||
|
|
||||||
|
**Platform Notes** (From various sources):
|
||||||
|
- macOS status and setup
|
||||||
|
- Windows status and caveats
|
||||||
|
- Linux expectations
|
||||||
|
- Detailed platform differences
|
||||||
|
|
||||||
|
## Benefits of New Structure
|
||||||
|
|
||||||
|
### For New Contributors
|
||||||
|
|
||||||
|
**Before**: "Where do I start? What's current?"
|
||||||
|
**After**: Read README → E6-z3ed-cli-design.md → E6-z3ed-reference.md → Done
|
||||||
|
|
||||||
|
### For Developers
|
||||||
|
|
||||||
|
**Before**: Search 10+ docs for command syntax
|
||||||
|
**After**: E6-z3ed-reference.md § Command Reference → Find answer in one place
|
||||||
|
|
||||||
|
### For AI/LLM Integration
|
||||||
|
|
||||||
|
**Before**: No clear machine-readable specs
|
||||||
|
**After**: `docs/api/z3ed-resources.yaml` + E6-z3ed-reference.md § API Reference
|
||||||
|
|
||||||
|
### For Project Management
|
||||||
|
|
||||||
|
**Before**: Status scattered across session summaries
|
||||||
|
**After**: PROJECT_STATUS_OCT2.md + E6-z3ed-implementation-plan.md
|
||||||
|
|
||||||
|
### For Troubleshooting
|
||||||
|
|
||||||
|
**Before**: Search multiple docs for error messages
|
||||||
|
**After**: E6-z3ed-reference.md § Troubleshooting → All issues in one place
|
||||||
|
|
||||||
|
## Document Roles
|
||||||
|
|
||||||
|
| Document | Role | Update Frequency |
|
||||||
|
|----------|------|------------------|
|
||||||
|
| E6-z3ed-cli-design.md | Source of truth for design | When architecture changes |
|
||||||
|
| E6-z3ed-reference.md | Technical reference | When APIs/commands change |
|
||||||
|
| E6-z3ed-implementation-plan.md | Project tracker | Weekly/as needed |
|
||||||
|
| README.md | Documentation index | When structure changes |
|
||||||
|
| IT-01-QUICKSTART.md | Quick reference card | Rarely (stable API) |
|
||||||
|
| AGENT_TEST_QUICKREF.md | Quick reference card | When patterns added |
|
||||||
|
| E2E_VALIDATION_GUIDE.md | Testing checklist | When workflow changes |
|
||||||
|
| PROJECT_STATUS_OCT2.md | Status snapshot | Weekly |
|
||||||
|
| NEXT_PRIORITIES_OCT2.md | Task breakdown | Daily/weekly |
|
||||||
|
| Archive docs | Historical reference | Never (frozen) |
|
||||||
|
|
||||||
|
## Maintenance Guidelines
|
||||||
|
|
||||||
|
### When to Update Each Document
|
||||||
|
|
||||||
|
**E6-z3ed-cli-design.md**: Update when:
|
||||||
|
- Architecture changes (new components, flow changes)
|
||||||
|
- Design decisions made (document rationale)
|
||||||
|
- Major features completed (update "Current State")
|
||||||
|
|
||||||
|
**E6-z3ed-reference.md**: Update when:
|
||||||
|
- New commands added
|
||||||
|
- RPC methods added/changed
|
||||||
|
- API schemas change
|
||||||
|
- New troubleshooting issues discovered
|
||||||
|
- Platform-specific notes needed
|
||||||
|
|
||||||
|
**E6-z3ed-implementation-plan.md**: Update when:
|
||||||
|
- Tasks completed (mark ✅)
|
||||||
|
- New tasks identified (add to backlog)
|
||||||
|
- Priorities change
|
||||||
|
- Milestones reached
|
||||||
|
|
||||||
|
**Quick Start Guides**: Update when:
|
||||||
|
- Commands/flags change
|
||||||
|
- New workflows added
|
||||||
|
- Better examples found
|
||||||
|
|
||||||
|
**Status Documents**: Update on:
|
||||||
|
- Weekly basis (PROJECT_STATUS_OCT2.md)
|
||||||
|
- When priorities shift (NEXT_PRIORITIES_OCT2.md)
|
||||||
|
- After work sessions (WORK_SUMMARY_OCT2.md)
|
||||||
|
|
||||||
|
### Avoiding Future Bloat
|
||||||
|
|
||||||
|
**Don't create new docs for**:
|
||||||
|
- Session summaries → Use git commit messages or issue comments
|
||||||
|
- Progress reports → Update E6-z3ed-implementation-plan.md
|
||||||
|
- Technical investigations → Add to E6-z3ed-reference.md § relevant section
|
||||||
|
- Status snapshots → Update PROJECT_STATUS_OCT2.md
|
||||||
|
|
||||||
|
**Do create new docs for**:
|
||||||
|
- Major new subsystems (e.g., E6-policy-framework.md if complex)
|
||||||
|
- Platform-specific guides (e.g., E6-windows-setup.md if needed)
|
||||||
|
- Specialized workflows (e.g., E6-ci-cd-integration.md)
|
||||||
|
|
||||||
|
**Then consolidate** into main docs after 1-2 weeks once content stabilizes.
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Review**: Check that no critical information was lost in consolidation
|
||||||
|
2. **Test**: Try following guides as a new user would
|
||||||
|
3. **Iterate**: Update based on feedback
|
||||||
|
4. **Maintain**: Keep docs current as code evolves
|
||||||
|
|
||||||
|
## Verification Checklist
|
||||||
|
|
||||||
|
- [x] All technical content from archived docs is in E6-z3ed-reference.md
|
||||||
|
- [x] Design decisions from multiple docs consolidated in E6-z3ed-cli-design.md
|
||||||
|
- [x] Clear hierarchy established (design → reference → implementation plan)
|
||||||
|
- [x] Archive folder has explanatory README
|
||||||
|
- [x] Main README updated with new structure
|
||||||
|
- [x] Quick start guides retained for fast onboarding
|
||||||
|
- [x] Status documents reflect current state
|
||||||
|
- [x] No orphaned references to deleted/moved docs
|
||||||
|
|
||||||
|
## Questions?
|
||||||
|
|
||||||
|
If you can't find something:
|
||||||
|
|
||||||
|
1. **Check E6-z3ed-reference.md first** - Most technical info is here
|
||||||
|
2. **Check E6-z3ed-cli-design.md** - For design rationale
|
||||||
|
3. **Check archive/** - For historical context
|
||||||
|
4. **Check git history** - Content may have evolved
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Consolidation by**: GitHub Copilot
|
||||||
|
**Reviewed by**: @scawful
|
||||||
|
**Status**: Complete - Ready for team review
|
||||||
@@ -1,18 +1,57 @@
|
|||||||
|
# z3ed CLI Architecture & Design
|
||||||
|
|
||||||
## 1. Overview
|
## 1. Overview
|
||||||
|
|
||||||
This document outlines a design for the evolution of `z3ed`, the command-line interface for the YAZE project. The goal is to transform `z3ed` from a collection of utility commands into a powerful, scriptable, and extensible tool for both manual and automated ROM hacking, with a forward-looking approach to AI-driven generative development.
|
This document is the **source of truth** for the z3ed CLI architecture and design. It outlines the evolution of `z3ed`, the command-line interface for the YAZE project, from a collection of utility commands into a powerful, scriptable, and extensible tool for both manual and automated ROM hacking, with full support for AI-driven generative development.
|
||||||
|
|
||||||
### 1.1. Current State
|
**Related Documents**:
|
||||||
|
- **[E6-z3ed-implementation-plan.md](E6-z3ed-implementation-plan.md)** - Implementation tracker, task backlog, and roadmap
|
||||||
|
- **[E6-z3ed-reference.md](E6-z3ed-reference.md)** - Technical reference: commands, APIs, troubleshooting
|
||||||
|
- **[README.md](README.md)** - Quick overview and documentation index
|
||||||
|
|
||||||
`z3ed` has evolved significantly. The initial limitations regarding scope, inconsistent structure, basic TUI, and limited scriptability have largely been addressed through the implementation of resource-oriented commands, modular TUI components, and structured output. The focus has shifted towards building a robust foundation for AI-driven generative hacking.
|
### 1.1. Current State (October 2, 2025)
|
||||||
|
|
||||||
|
`z3ed` has successfully implemented its core infrastructure and is **production-ready on macOS**:
|
||||||
|
|
||||||
|
**✅ Completed Features**:
|
||||||
|
- **Resource-Oriented CLI**: Clean `z3ed <resource> <action>` command structure
|
||||||
|
- **Resource Catalogue**: Machine-readable API specs in YAML/JSON for AI consumption
|
||||||
|
- **Acceptance Workflow**: Full proposal lifecycle (create → review → accept/reject → commit)
|
||||||
|
- **ImGuiTestHarness (IT-01)**: gRPC-based GUI automation with 6 RPC methods
|
||||||
|
- **CLI Agent Test (IT-02)**: Natural language prompts → automated GUI testing
|
||||||
|
- **ProposalDrawer GUI**: Integrated review interface in YAZE editor
|
||||||
|
- **ROM Sandbox Manager**: Isolated testing environment for safe experimentation
|
||||||
|
- **Proposal Registry**: Cross-session proposal tracking with disk persistence
|
||||||
|
|
||||||
|
**🔄 In Progress**:
|
||||||
|
- **E2E Validation**: Testing complete workflow (80% done, window detection needs fix)
|
||||||
|
|
||||||
|
**📋 Planned Next**:
|
||||||
|
- **Policy Evaluation Framework (AW-04)**: YAML-based constraints for proposal acceptance
|
||||||
|
- **Windows Cross-Platform Testing**: Validate on Windows with vcpkg
|
||||||
|
- **Production Readiness**: Telemetry, screenshot implementation, expanded test coverage
|
||||||
|
|
||||||
## 2. Design Goals
|
## 2. Design Goals
|
||||||
|
|
||||||
The proposed redesign focuses on three core pillars:
|
The z3ed CLI is built on three core pillars:
|
||||||
|
|
||||||
1. **Power & Usability for ROM Hackers**: Empower users with fine-grained control over all aspects of the ROM directly from the command line.
|
1. **Power & Usability for ROM Hackers**: Empower users with fine-grained control over all aspects of the ROM directly from the command line, supporting both interactive exploration and scripted automation.
|
||||||
2. **Testability & Automation**: Provide robust commands for validating ROM integrity and automating complex testing scenarios.
|
|
||||||
3. **AI & Generative Hacking**: Establish a powerful, scriptable API that an AI agent (MCP) can use to perform complex, generative tasks on the ROM.
|
2. **Testability & Automation**: Provide robust commands for validating ROM integrity, automating complex testing scenarios, and enabling reproducible workflows through scripting.
|
||||||
|
|
||||||
|
3. **AI & Generative Hacking**: Establish a powerful, scriptable API that an AI agent (LLM/MCP) can use to perform complex, generative tasks on the ROM, with human oversight and approval workflows.
|
||||||
|
|
||||||
|
### 2.1. Key Architectural Decisions
|
||||||
|
|
||||||
|
**Resource-Oriented Command Structure**: Adopted `z3ed <resource> <action>` pattern (similar to kubectl, gcloud) for clarity and extensibility.
|
||||||
|
|
||||||
|
**Machine-Readable API**: All commands documented in `docs/api/z3ed-resources.yaml` with structured schemas for AI consumption.
|
||||||
|
|
||||||
|
**Proposal-Based Workflow**: AI-generated changes are sandboxed and tracked as "proposals" requiring human review and acceptance.
|
||||||
|
|
||||||
|
**gRPC Test Harness**: Embedded gRPC server in YAZE enables remote GUI automation for testing and AI-driven workflows.
|
||||||
|
|
||||||
|
**Cross-Platform Foundation**: Core built for macOS/Linux with Windows support planned via vcpkg.
|
||||||
|
|
||||||
## 3. Proposed CLI Architecture: Resource-Oriented Commands
|
## 3. Proposed CLI Architecture: Resource-Oriented Commands
|
||||||
|
|
||||||
|
|||||||
973
docs/z3ed/E6-z3ed-reference.md
Normal file
973
docs/z3ed/E6-z3ed-reference.md
Normal file
@@ -0,0 +1,973 @@
|
|||||||
|
# z3ed CLI Technical Reference
|
||||||
|
|
||||||
|
**Version**: 0.1.0-alpha
|
||||||
|
**Last Updated**: October 2, 2025
|
||||||
|
**Status**: Production Ready (macOS), Windows Testing Pending
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Architecture Overview](#architecture-overview)
|
||||||
|
2. [Command Reference](#command-reference)
|
||||||
|
3. [Implementation Guide](#implementation-guide)
|
||||||
|
4. [Testing & Validation](#testing--validation)
|
||||||
|
5. [Development Workflows](#development-workflows)
|
||||||
|
6. [Troubleshooting](#troubleshooting)
|
||||||
|
7. [API Reference](#api-reference)
|
||||||
|
8. [Platform Notes](#platform-notes)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
### System Components
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ AI Agent Layer (LLM) │
|
||||||
|
│ └─ Natural language prompts │
|
||||||
|
└────────────────────┬────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────▼────────────────────────────────────┐
|
||||||
|
│ z3ed CLI (Command-Line Interface) │
|
||||||
|
│ ├─ agent run --prompt "..." --sandbox │
|
||||||
|
│ ├─ agent test --prompt "..." (IT-02) │
|
||||||
|
│ ├─ agent list │
|
||||||
|
│ ├─ agent diff --proposal-id <id> │
|
||||||
|
│ ├─ agent describe [--resource <name>] │
|
||||||
|
│ ├─ rom info/validate/diff/generate-golden │
|
||||||
|
│ ├─ palette export/import/list │
|
||||||
|
│ ├─ overworld get-tile/set-tile │
|
||||||
|
│ └─ dungeon list-rooms/add-object │
|
||||||
|
└────────────────────┬────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────▼────────────────────────────────────┐
|
||||||
|
│ Service Layer (Singleton Services) │
|
||||||
|
│ ├─ ProposalRegistry (proposal tracking) │
|
||||||
|
│ ├─ RomSandboxManager (isolated ROM copies) │
|
||||||
|
│ ├─ ResourceCatalog (machine-readable API specs) │
|
||||||
|
│ ├─ GuiAutomationClient (gRPC wrapper) │
|
||||||
|
│ ├─ TestWorkflowGenerator (NL → test steps) │
|
||||||
|
│ └─ PolicyEvaluator (YAML constraints) [Planned] │
|
||||||
|
└────────────────────┬────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────▼────────────────────────────────────┐
|
||||||
|
│ ImGuiTestHarness (gRPC Server) │
|
||||||
|
│ ├─ Ping (health check) │
|
||||||
|
│ ├─ Click (button, menu, tab) │
|
||||||
|
│ ├─ Type (text input) │
|
||||||
|
│ ├─ Wait (condition polling) │
|
||||||
|
│ ├─ Assert (state validation) │
|
||||||
|
│ └─ Screenshot (capture) [Stub] │
|
||||||
|
└────────────────────┬────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────────▼────────────────────────────────────┐
|
||||||
|
│ YAZE GUI (ImGui Application) │
|
||||||
|
│ ├─ ProposalDrawer (Debug → Agent Proposals) │
|
||||||
|
│ │ ├─ List/detail views │
|
||||||
|
│ │ ├─ Accept/Reject/Delete │
|
||||||
|
│ │ └─ ROM merging │
|
||||||
|
│ └─ Editor Windows │
|
||||||
|
│ ├─ Overworld Editor │
|
||||||
|
│ ├─ Dungeon Editor │
|
||||||
|
│ ├─ Palette Editor │
|
||||||
|
│ └─ Graphics Editor │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Flow: Proposal Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
User: z3ed agent run "Make soldiers red" --sandbox
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ MockAIService │ → ["palette export sprites_aux1 4 soldier.col"]
|
||||||
|
└────────┬───────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ RomSandboxManager │ → Creates: /tmp/.../sandboxes/20251002T100000/zelda3.sfc
|
||||||
|
└────────┬───────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ Execute Commands │ → Runs: palette export on sandbox ROM
|
||||||
|
└────────┬───────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ ProposalRegistry │ → Creates: proposal-20251002T100000/
|
||||||
|
│ │ • execution.log
|
||||||
|
│ │ • diff.txt (if generated)
|
||||||
|
└────────┬───────────────┘
|
||||||
|
│
|
||||||
|
▼ (User opens YAZE GUI)
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ ProposalDrawer │ → Displays: List of proposals
|
||||||
|
└────────┬───────────────┘
|
||||||
|
│
|
||||||
|
▼ (User clicks "Accept")
|
||||||
|
┌────────────────────────┐
|
||||||
|
│ AcceptProposal() │ → 1. Load sandbox ROM
|
||||||
|
│ │ 2. rom_->WriteVector(0, sandbox_rom.vector())
|
||||||
|
│ │ 3. ROM marked dirty
|
||||||
|
│ │ 4. User saves ROM
|
||||||
|
└────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Command Reference
|
||||||
|
|
||||||
|
### Agent Commands
|
||||||
|
|
||||||
|
#### `agent run` - Execute AI-driven ROM modifications
|
||||||
|
```bash
|
||||||
|
z3ed agent run --prompt "<description>" --rom <file> [--sandbox]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--prompt <text> Natural language description of desired changes
|
||||||
|
--rom <file> Path to ROM file (default: current ROM)
|
||||||
|
--sandbox Create isolated copy for testing (recommended)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed agent run --prompt "Change soldier armor to red" \
|
||||||
|
--rom=zelda3.sfc --sandbox
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output**:
|
||||||
|
- Proposal ID
|
||||||
|
- Sandbox path
|
||||||
|
- Command execution log
|
||||||
|
- Next steps guidance
|
||||||
|
|
||||||
|
#### `agent list` - Show all proposals
|
||||||
|
```bash
|
||||||
|
z3ed agent list
|
||||||
|
|
||||||
|
Example Output:
|
||||||
|
=== Agent Proposals ===
|
||||||
|
|
||||||
|
ID: proposal-20251002T100000-1
|
||||||
|
Status: Pending
|
||||||
|
Created: 2025-10-02 10:00:00
|
||||||
|
Prompt: Change soldier armor to red
|
||||||
|
Commands: 3
|
||||||
|
Bytes Changed: 128
|
||||||
|
|
||||||
|
Total: 1 proposal(s)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `agent diff` - Show proposal changes
|
||||||
|
```bash
|
||||||
|
z3ed agent diff [--proposal-id <id>]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--proposal-id <id> View specific proposal (default: latest pending)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed agent diff --proposal-id proposal-20251002T100000-1
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output**:
|
||||||
|
- Proposal metadata
|
||||||
|
- Execution log
|
||||||
|
- Diff content
|
||||||
|
- Next steps
|
||||||
|
|
||||||
|
#### `agent describe` - Export machine-readable API specs
|
||||||
|
```bash
|
||||||
|
z3ed agent describe [--format <yaml|json>] [--resource <name>] [--output <file>]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--format <type> Output format: yaml or json (default: yaml)
|
||||||
|
--resource <name> Filter to specific resource (rom, palette, etc.)
|
||||||
|
--output <file> Write to file instead of stdout
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
z3ed agent describe --format yaml
|
||||||
|
z3ed agent describe --format json --resource rom
|
||||||
|
z3ed agent describe --output docs/api/z3ed-resources.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
**Resources Available**:
|
||||||
|
- `rom` - ROM file operations
|
||||||
|
- `patch` - Patch application
|
||||||
|
- `palette` - Palette manipulation
|
||||||
|
- `overworld` - Overworld editing
|
||||||
|
- `dungeon` - Dungeon editing
|
||||||
|
- `agent` - Agent commands
|
||||||
|
|
||||||
|
#### `agent test` - Automated GUI testing (IT-02)
|
||||||
|
```bash
|
||||||
|
z3ed agent test --prompt "<test_description>" [--host <hostname>] [--port <port>]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--prompt <text> Natural language test description
|
||||||
|
--host <hostname> Test harness hostname (default: localhost)
|
||||||
|
--port <port> Test harness port (default: 50052)
|
||||||
|
--timeout <seconds> Maximum test duration (default: 30)
|
||||||
|
|
||||||
|
Supported Prompt Patterns:
|
||||||
|
- "Open <Editor> editor"
|
||||||
|
- "Open <Editor> and verify it loads"
|
||||||
|
- "Click <Button>"
|
||||||
|
- "Type '<text>' in <input>"
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
z3ed agent test --prompt "Open Overworld editor"
|
||||||
|
z3ed agent test --prompt "Open Dungeon editor and verify it loads"
|
||||||
|
z3ed agent test --prompt "Click Save button"
|
||||||
|
z3ed agent test --prompt "Type 'zelda3.sfc' in filename input"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prerequisites**:
|
||||||
|
1. YAZE running with test harness:
|
||||||
|
```bash
|
||||||
|
./yaze --enable_test_harness --test_harness_port=50052 --rom_file=zelda3.sfc &
|
||||||
|
```
|
||||||
|
2. z3ed built with gRPC support:
|
||||||
|
```bash
|
||||||
|
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||||
|
cmake --build build-grpc-test --target z3ed
|
||||||
|
```
|
||||||
|
|
||||||
|
### ROM Commands
|
||||||
|
|
||||||
|
#### `rom info` - Display ROM metadata
|
||||||
|
```bash
|
||||||
|
z3ed rom info --rom <file>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed rom info --rom=zelda3.sfc
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `rom validate` - Verify ROM integrity
|
||||||
|
```bash
|
||||||
|
z3ed rom validate --rom <file>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed rom validate --rom=zelda3.sfc
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `rom diff` - Compare two ROMs
|
||||||
|
```bash
|
||||||
|
z3ed rom diff --rom1 <file1> --rom2 <file2>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed rom diff --rom1=zelda3.sfc --rom2=zelda3_modified.sfc
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `rom generate-golden` - Create reference checksums
|
||||||
|
```bash
|
||||||
|
z3ed rom generate-golden --rom <file> --output <json_file>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed rom generate-golden --rom=zelda3.sfc --output=golden.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Palette Commands
|
||||||
|
|
||||||
|
#### `palette export` - Export palette to file
|
||||||
|
```bash
|
||||||
|
z3ed palette export <group_name> <palette_id> <output_file>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed palette export sprites_aux1 4 soldier.col
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `palette import` - Import palette from file
|
||||||
|
```bash
|
||||||
|
z3ed palette import <group_name> <palette_id> <input_file>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed palette import sprites_aux1 4 soldier_red.col
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `palette list` - Show available palettes
|
||||||
|
```bash
|
||||||
|
z3ed palette list [--group <name>]
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed palette list --group sprites_aux1
|
||||||
|
```
|
||||||
|
|
||||||
|
### Overworld Commands
|
||||||
|
|
||||||
|
#### `overworld get-tile` - Get tile at coordinates
|
||||||
|
```bash
|
||||||
|
z3ed overworld get-tile --map <id> --x <x> --y <y>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed overworld get-tile --map=0 --x=100 --y=50
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `overworld set-tile` - Set tile at coordinates
|
||||||
|
```bash
|
||||||
|
z3ed overworld set-tile --map <id> --x <x> --y <y> --tile-id <id>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed overworld set-tile --map=0 --x=100 --y=50 --tile-id=0x1234
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dungeon Commands
|
||||||
|
|
||||||
|
#### `dungeon list-rooms` - List all dungeon rooms
|
||||||
|
```bash
|
||||||
|
z3ed dungeon list-rooms --dungeon <id>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed dungeon list-rooms --dungeon=0
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `dungeon add-object` - Add object to room
|
||||||
|
```bash
|
||||||
|
z3ed dungeon add-object --dungeon <id> --room <id> --object <type>
|
||||||
|
|
||||||
|
Example:
|
||||||
|
z3ed dungeon add-object --dungeon=0 --room=5 --object=chest
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Guide
|
||||||
|
|
||||||
|
### Building with gRPC Support
|
||||||
|
|
||||||
|
#### macOS (Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install dependencies (via vcpkg or system)
|
||||||
|
# vcpkg is handled automatically by CMake
|
||||||
|
|
||||||
|
# Configure with gRPC enabled
|
||||||
|
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||||
|
|
||||||
|
# Build YAZE and z3ed
|
||||||
|
cmake --build build-grpc-test --target yaze -j$(sysctl -n hw.ncpu)
|
||||||
|
cmake --build build-grpc-test --target z3ed -j$(sysctl -n hw.ncpu)
|
||||||
|
|
||||||
|
# First build takes 15-20 minutes (gRPC compilation)
|
||||||
|
# Incremental builds: 5-10 seconds
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Windows (Experimental)
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# Install vcpkg (one-time setup)
|
||||||
|
git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
|
||||||
|
C:\vcpkg\bootstrap-vcpkg.bat
|
||||||
|
C:\vcpkg\vcpkg integrate install
|
||||||
|
|
||||||
|
# Install dependencies
|
||||||
|
C:\vcpkg\vcpkg install grpc:x64-windows abseil:x64-windows sdl2:x64-windows
|
||||||
|
|
||||||
|
# Configure and build
|
||||||
|
cmake -B build -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake `
|
||||||
|
-DYAZE_WITH_GRPC=ON -A x64
|
||||||
|
cmake --build build --config Release --target yaze
|
||||||
|
cmake --build build --config Release --target z3ed
|
||||||
|
```
|
||||||
|
|
||||||
|
**Windows Notes**:
|
||||||
|
- Test harness not yet validated on Windows
|
||||||
|
- Use static linking to avoid DLL conflicts
|
||||||
|
- See `docs/02-build-instructions.md` for details
|
||||||
|
|
||||||
|
### Starting Test Harness
|
||||||
|
|
||||||
|
#### Basic Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start YAZE with test harness enabled
|
||||||
|
./build-grpc-test/bin/yaze.app/Contents/MacOS/yaze \
|
||||||
|
--enable_test_harness \
|
||||||
|
--test_harness_port=50052 \
|
||||||
|
--rom_file=assets/zelda3.sfc &
|
||||||
|
|
||||||
|
# Verify server is running
|
||||||
|
lsof -i :50052
|
||||||
|
# Should show yaze process listening
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Configuration Options
|
||||||
|
|
||||||
|
```bash
|
||||||
|
--enable_test_harness Enable gRPC test harness (default: false)
|
||||||
|
--test_harness_port=<port> Port number (default: 50051)
|
||||||
|
--rom_file=<file> ROM to load on startup (optional)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Testing RPCs with grpcurl
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install grpcurl
|
||||||
|
brew install grpcurl
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"message":"test"}' 127.0.0.1:50052 yaze.test.ImGuiTestHarness/Ping
|
||||||
|
|
||||||
|
# Click button
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"target":"button:Overworld","type":"LEFT"}' \
|
||||||
|
127.0.0.1:50052 yaze.test.ImGuiTestHarness/Click
|
||||||
|
|
||||||
|
# Type text
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"target":"input:Search","text":"tile16","clear_first":true}' \
|
||||||
|
127.0.0.1:50052 yaze.test.ImGuiTestHarness/Type
|
||||||
|
|
||||||
|
# Wait for condition
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"condition":"window_visible:Overworld Editor","timeout_ms":5000}' \
|
||||||
|
127.0.0.1:50052 yaze.test.ImGuiTestHarness/Wait
|
||||||
|
|
||||||
|
# Assert state
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"condition":"visible:Main Window"}' \
|
||||||
|
127.0.0.1:50052 yaze.test.ImGuiTestHarness/Assert
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing & Validation
|
||||||
|
|
||||||
|
### Automated E2E Test Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run comprehensive test suite
|
||||||
|
./scripts/test_harness_e2e.sh
|
||||||
|
|
||||||
|
# Expected: All 6 tests pass
|
||||||
|
# - Ping (health check)
|
||||||
|
# - Click (button interaction)
|
||||||
|
# - Type (text input)
|
||||||
|
# - Wait (condition polling)
|
||||||
|
# - Assert (state validation)
|
||||||
|
# - Screenshot (stub - returns not implemented)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual Testing Workflow
|
||||||
|
|
||||||
|
#### 1. Create Proposal
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/bin/z3ed agent run \
|
||||||
|
--rom=assets/zelda3.sfc \
|
||||||
|
--prompt "Test proposal" \
|
||||||
|
--sandbox
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. List Proposals
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/bin/z3ed agent list
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. View Diff
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build/bin/z3ed agent diff
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. Review in GUI
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start YAZE
|
||||||
|
./build/bin/yaze.app/Contents/MacOS/yaze
|
||||||
|
|
||||||
|
# Navigate: Debug → Agent Proposals
|
||||||
|
# Select proposal → Review → Accept/Reject/Delete
|
||||||
|
```
|
||||||
|
|
||||||
|
### Performance Benchmarks
|
||||||
|
|
||||||
|
| Operation | Typical Time | Notes |
|
||||||
|
|-----------|-------------|-------|
|
||||||
|
| Ping RPC | < 10ms | Health check overhead |
|
||||||
|
| Click RPC | 50-200ms | Widget lookup + event |
|
||||||
|
| Type RPC | 100-300ms | Focus + clear + input |
|
||||||
|
| Wait RPC | 100-5000ms | Depends on condition |
|
||||||
|
| Assert RPC | 10-100ms | State query |
|
||||||
|
| Full Workflow | 1-2s | Click + Wait + Assert |
|
||||||
|
| Proposal Creation | < 1s | Mock AI service |
|
||||||
|
| ROM Merge | < 100ms | Memory copy |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Development Workflows
|
||||||
|
|
||||||
|
### Adding New Agent Commands
|
||||||
|
|
||||||
|
1. **Create Handler** (`src/cli/handlers/<resource>.cc`)
|
||||||
|
```cpp
|
||||||
|
absl::Status HandleNewCommand(const CommandOptions& options) {
|
||||||
|
// Implementation
|
||||||
|
return absl::OkStatus();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Register Command** (`src/cli/modern_cli.cc`)
|
||||||
|
```cpp
|
||||||
|
if (absl::GetFlag(FLAGS_new_resource) == "new-action") {
|
||||||
|
return HandleNewCommand(options);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Add to Resource Catalog** (`src/cli/service/resource_catalog.cc`)
|
||||||
|
```cpp
|
||||||
|
catalog.resources.push_back({
|
||||||
|
.name = "new_resource",
|
||||||
|
.description = "Description",
|
||||||
|
.actions = {{
|
||||||
|
.name = "new-action",
|
||||||
|
.description = "Action description",
|
||||||
|
.arguments = {/* ... */},
|
||||||
|
.effects = {/* ... */},
|
||||||
|
.returns = {/* ... */}
|
||||||
|
}}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Update Documentation**
|
||||||
|
- Add to `docs/api/z3ed-resources.yaml` (regenerate via `agent describe`)
|
||||||
|
- Add examples to relevant guides
|
||||||
|
|
||||||
|
### Adding New Test Harness RPCs
|
||||||
|
|
||||||
|
1. **Update Proto** (`src/app/core/proto/imgui_test_harness.proto`)
|
||||||
|
```protobuf
|
||||||
|
service ImGuiTestHarness {
|
||||||
|
rpc NewOperation(NewRequest) returns (NewResponse);
|
||||||
|
}
|
||||||
|
|
||||||
|
message NewRequest {
|
||||||
|
string parameter = 1;
|
||||||
|
}
|
||||||
|
|
||||||
|
message NewResponse {
|
||||||
|
bool success = 1;
|
||||||
|
string message = 2;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Implement Handler** (`src/app/core/imgui_test_harness_service.cc`)
|
||||||
|
```cpp
|
||||||
|
grpc::Status ImGuiTestHarnessServiceImpl::NewOperation(
|
||||||
|
grpc::ServerContext* context,
|
||||||
|
const NewRequest* request,
|
||||||
|
NewResponse* response) {
|
||||||
|
// Implementation
|
||||||
|
response->set_success(true);
|
||||||
|
response->set_message("Operation completed");
|
||||||
|
return grpc::Status::OK;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Rebuild**
|
||||||
|
```bash
|
||||||
|
cmake --build build-grpc-test --target yaze
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Test**
|
||||||
|
```bash
|
||||||
|
grpcurl -plaintext -import-path src/app/core/proto \
|
||||||
|
-proto imgui_test_harness.proto \
|
||||||
|
-d '{"parameter":"value"}' \
|
||||||
|
127.0.0.1:50052 yaze.test.ImGuiTestHarness/NewOperation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding Test Workflow Patterns
|
||||||
|
|
||||||
|
1. **Add Pattern Matcher** (`src/cli/service/test_workflow_generator.cc`)
|
||||||
|
```cpp
|
||||||
|
bool MatchesNewPattern(const std::string& prompt, YourParams* params) {
|
||||||
|
std::regex pattern(R"(your regex pattern)");
|
||||||
|
std::smatch matches;
|
||||||
|
if (std::regex_search(prompt, matches, pattern)) {
|
||||||
|
// Extract parameters
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Add Workflow Builder**
|
||||||
|
```cpp
|
||||||
|
TestWorkflow BuildNewPatternWorkflow(const YourParams& params) {
|
||||||
|
TestWorkflow workflow;
|
||||||
|
workflow.description = "Your workflow description";
|
||||||
|
|
||||||
|
// Add steps
|
||||||
|
workflow.steps.push_back({
|
||||||
|
.type = TestStep::kClick,
|
||||||
|
.target = "button:Name",
|
||||||
|
/* ... */
|
||||||
|
});
|
||||||
|
|
||||||
|
return workflow;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Integrate into Generator**
|
||||||
|
```cpp
|
||||||
|
absl::StatusOr<TestWorkflow> TestWorkflowGenerator::GenerateFromPrompt(
|
||||||
|
const std::string& prompt) {
|
||||||
|
YourParams params;
|
||||||
|
if (MatchesNewPattern(prompt, ¶ms)) {
|
||||||
|
return BuildNewPatternWorkflow(params);
|
||||||
|
}
|
||||||
|
// ... other patterns
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
#### Port Already in Use
|
||||||
|
|
||||||
|
**Problem**: `Failed to start gRPC server: Address already in use`
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
```bash
|
||||||
|
# Find and kill existing instance
|
||||||
|
lsof -i :50052
|
||||||
|
kill <PID>
|
||||||
|
|
||||||
|
# Or use different port
|
||||||
|
./yaze --enable_test_harness --test_harness_port=50053
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Connection Refused
|
||||||
|
|
||||||
|
**Problem**: `Error connecting to server: Connection refused`
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Verify server is running: `lsof -i :50052`
|
||||||
|
2. Check firewall settings
|
||||||
|
3. Ensure correct port number
|
||||||
|
|
||||||
|
#### Widget Not Found
|
||||||
|
|
||||||
|
**Problem**: `Button 'XYZ' not found`
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
1. Verify widget label is correct (case-sensitive)
|
||||||
|
2. Check if widget is in active window
|
||||||
|
3. Wait for window to be visible first
|
||||||
|
4. Use Assert to check widget exists
|
||||||
|
|
||||||
|
#### Build Errors - Boolean Flag
|
||||||
|
|
||||||
|
**Problem**: `std::stringstream >> bool` doesn't parse "true"/"false"
|
||||||
|
|
||||||
|
**Solution**: Already fixed in `src/util/flag.h` with template specialization
|
||||||
|
|
||||||
|
#### Build Errors - Incomplete Type
|
||||||
|
|
||||||
|
**Problem**: `error: delete called on 'grpc::Server' that is incomplete`
|
||||||
|
|
||||||
|
**Solution**: Ensure destructor implementation is in `.cc` file, not header
|
||||||
|
|
||||||
|
### Debug Mode
|
||||||
|
|
||||||
|
Enable verbose logging:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In z3ed
|
||||||
|
export YAZE_LOG_LEVEL=debug
|
||||||
|
./z3ed agent test --prompt "..."
|
||||||
|
|
||||||
|
# In test harness
|
||||||
|
./yaze --enable_test_harness --log_level=debug
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Harness Diagnostics
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check server status
|
||||||
|
grpcurl -plaintext 127.0.0.1:50052 list
|
||||||
|
|
||||||
|
# Check available services
|
||||||
|
grpcurl -plaintext 127.0.0.1:50052 list yaze.test.ImGuiTestHarness
|
||||||
|
|
||||||
|
# Describe service
|
||||||
|
grpcurl -plaintext 127.0.0.1:50052 describe yaze.test.ImGuiTestHarness
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Reference
|
||||||
|
|
||||||
|
### RPC Service Definition
|
||||||
|
|
||||||
|
```protobuf
|
||||||
|
syntax = "proto3";
|
||||||
|
package yaze.test;
|
||||||
|
|
||||||
|
service ImGuiTestHarness {
|
||||||
|
rpc Ping(PingRequest) returns (PingResponse);
|
||||||
|
rpc Click(ClickRequest) returns (ClickResponse);
|
||||||
|
rpc Type(TypeRequest) returns (TypeResponse);
|
||||||
|
rpc Wait(WaitRequest) returns (WaitResponse);
|
||||||
|
rpc Assert(AssertRequest) returns (AssertResponse);
|
||||||
|
rpc Screenshot(ScreenshotRequest) returns (ScreenshotResponse);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Request/Response Schemas
|
||||||
|
|
||||||
|
#### Ping
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "string",
|
||||||
|
"timestampMs": "int64",
|
||||||
|
"yazeVersion": "string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Click
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"target": "button:Name | menu:File→Open | tab:Editor",
|
||||||
|
"type": "LEFT | RIGHT | MIDDLE | DOUBLE"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Clicked button 'Name'",
|
||||||
|
"executionTimeMs": "int32"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Type
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"target": "input:FieldName",
|
||||||
|
"text": "text to type",
|
||||||
|
"clear_first": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Typed 'text' into input 'FieldName'"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Wait
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"condition": "window_visible:WindowName | element_visible:Label | element_enabled:Label",
|
||||||
|
"timeout_ms": 5000,
|
||||||
|
"poll_interval_ms": 100
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Condition met after X ms",
|
||||||
|
"elapsedMs": "int32"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Assert
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"condition": "visible:Window | enabled:Button | exists:Element | text_contains:Input:ExpectedText"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "Assertion passed",
|
||||||
|
"actualValue": "string",
|
||||||
|
"expectedValue": "string"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Screenshot
|
||||||
|
|
||||||
|
**Request**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"region": "full | window:Name",
|
||||||
|
"format": "PNG | JPEG"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"message": "Screenshot not yet implemented",
|
||||||
|
"filePath": "",
|
||||||
|
"fileSizeBytes": 0
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Resource Catalog Schema
|
||||||
|
|
||||||
|
See `docs/api/z3ed-resources.yaml` for complete machine-readable API specification.
|
||||||
|
|
||||||
|
**Example Resource**:
|
||||||
|
```yaml
|
||||||
|
resources:
|
||||||
|
- name: rom
|
||||||
|
description: ROM file operations
|
||||||
|
actions:
|
||||||
|
- name: info
|
||||||
|
description: Display ROM metadata
|
||||||
|
arguments:
|
||||||
|
- name: rom
|
||||||
|
type: string
|
||||||
|
required: true
|
||||||
|
description: Path to ROM file
|
||||||
|
effects:
|
||||||
|
- Reads ROM file from disk
|
||||||
|
- Parses ROM header
|
||||||
|
returns:
|
||||||
|
- type: object
|
||||||
|
fields:
|
||||||
|
- title: string
|
||||||
|
- size: integer
|
||||||
|
- checksum: string
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Platform Notes
|
||||||
|
|
||||||
|
### macOS (ARM64) - Production Ready ✅
|
||||||
|
|
||||||
|
**Status**: Fully tested and operational
|
||||||
|
**Build Time**: 15-20 minutes (first build), 5-10 seconds (incremental)
|
||||||
|
**Binary Size**: ~74 MB (with gRPC)
|
||||||
|
**Known Issues**: None
|
||||||
|
|
||||||
|
**Recommended Setup**:
|
||||||
|
```bash
|
||||||
|
# Use Homebrew for dependencies
|
||||||
|
brew install cmake grpcurl
|
||||||
|
|
||||||
|
# Build with vcpkg (automatic via CMake)
|
||||||
|
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||||
|
cmake --build build-grpc-test --target yaze -j$(sysctl -n hw.ncpu)
|
||||||
|
```
|
||||||
|
|
||||||
|
### macOS (Intel) - Should Work ⚠️
|
||||||
|
|
||||||
|
**Status**: Not explicitly tested, but should work
|
||||||
|
**Expected Issues**: None (same toolchain as ARM64)
|
||||||
|
|
||||||
|
### Linux - Should Work ⚠️
|
||||||
|
|
||||||
|
**Status**: Not explicitly tested
|
||||||
|
**Expected Issues**: None (gRPC has excellent Linux support)
|
||||||
|
|
||||||
|
**Setup**:
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
sudo apt-get install cmake build-essential
|
||||||
|
|
||||||
|
# Build (same as macOS)
|
||||||
|
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||||
|
cmake --build build-grpc-test --target yaze -j$(nproc)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Windows - Experimental 🔬
|
||||||
|
|
||||||
|
**Status**: Build system ready, test harness not validated
|
||||||
|
**Known Limitations**:
|
||||||
|
- Test harness not yet tested on Windows
|
||||||
|
- May require static linking to avoid DLL conflicts
|
||||||
|
- vcpkg setup more complex than macOS
|
||||||
|
|
||||||
|
**Recommended Approach**: Use Windows Subsystem for Linux (WSL2) for now
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix
|
||||||
|
|
||||||
|
### File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/z3ed/
|
||||||
|
├── E6-z3ed-cli-design.md # Architecture & design (source of truth)
|
||||||
|
├── E6-z3ed-implementation-plan.md # Implementation tracker & roadmap
|
||||||
|
├── E6-z3ed-reference.md # This document (technical reference)
|
||||||
|
├── README.md # Quick overview & links
|
||||||
|
├── IT-01-QUICKSTART.md # Test harness quick start
|
||||||
|
├── AGENT_TEST_QUICKREF.md # CLI agent test command reference
|
||||||
|
├── E2E_VALIDATION_GUIDE.md # Complete validation checklist
|
||||||
|
├── PROJECT_STATUS_OCT2.md # Current project status
|
||||||
|
└── archive/ # Historical documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Related Documentation
|
||||||
|
|
||||||
|
- **Build Instructions**: `docs/02-build-instructions.md`
|
||||||
|
- **API Reference**: `docs/api/z3ed-resources.yaml`
|
||||||
|
- **Testing Guide**: `docs/A1-testing-guide.md`
|
||||||
|
- **Contributing**: `docs/B1-contributing.md`
|
||||||
|
|
||||||
|
### Version History
|
||||||
|
|
||||||
|
- **0.1.0-alpha** (Oct 2, 2025) - Initial release
|
||||||
|
- Resource catalogue complete
|
||||||
|
- Acceptance workflow operational
|
||||||
|
- ImGuiTestHarness (IT-01) complete
|
||||||
|
- CLI agent test (IT-02) complete
|
||||||
|
- E2E validation 80% complete
|
||||||
|
|
||||||
|
### Contributors
|
||||||
|
|
||||||
|
- @scawful (Project lead, implementation)
|
||||||
|
- GitHub Copilot (Development assistance, documentation)
|
||||||
|
|
||||||
|
### License
|
||||||
|
|
||||||
|
Same as YAZE - see `LICENSE` in repository root.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Document Status**: Living document, updated as features are added
|
||||||
|
**Last Review**: October 2, 2025
|
||||||
|
**Next Review**: After Windows testing completion
|
||||||
@@ -2,28 +2,212 @@
|
|||||||
|
|
||||||
**Status**: Active Development
|
**Status**: Active Development
|
||||||
**Version**: 0.1.0-alpha
|
**Version**: 0.1.0-alpha
|
||||||
**Last Updated**: October 2, 2025 (IT-02 Complete, E2E Validation In Progress)
|
**Last Updated**: October 2, 2025 (E2E Validation 80% Complete)
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
z3ed is a command-line interface for YAZE that enables AI-driven ROM modifications through a proposal-based workflow.
|
z3ed is a command-line interface for YAZE that enables AI-driven ROM modifications through a proposal-based workflow. It provides both human-accessible commands and machine-readable APIs for LLM integration.
|
||||||
|
|
||||||
## Documentation Index
|
## Core Documentation
|
||||||
|
|
||||||
### Essential Documents
|
### Essential Documents (Read These First)
|
||||||
1. [Next Actions](NEXT_ACTIONS_OCT3.md) - Tomorrow's implementation guide
|
|
||||||
2. [Implementation Plan](E6-z3ed-implementation-plan.md) - Master tracker
|
1. **[E6-z3ed-cli-design.md](E6-z3ed-cli-design.md)** - **SOURCE OF TRUTH**
|
||||||
3. [CLI Design](E6-z3ed-cli-design.md) - Architecture
|
- Architecture overview
|
||||||
4. [IT-01 Quickstart](IT-01-QUICKSTART.md) - Test harness reference
|
- Design goals and principles
|
||||||
|
- Command structure
|
||||||
|
- Agentic workflow framework
|
||||||
|
|
||||||
|
2. **[E6-z3ed-reference.md](E6-z3ed-reference.md)** - **TECHNICAL REFERENCE**
|
||||||
|
- Complete command reference
|
||||||
|
- API documentation
|
||||||
|
- Implementation guides
|
||||||
|
- Troubleshooting
|
||||||
|
|
||||||
|
3. **[E6-z3ed-implementation-plan.md](E6-z3ed-implementation-plan.md)** - **IMPLEMENTATION TRACKER**
|
||||||
|
- Task backlog and roadmap
|
||||||
|
- Progress tracking
|
||||||
|
- Known issues
|
||||||
|
- Next priorities
|
||||||
|
|
||||||
|
### Quick Start Guides
|
||||||
|
|
||||||
|
4. **[IT-01-QUICKSTART.md](IT-01-QUICKSTART.md)** - Test harness quick start
|
||||||
|
- Starting the gRPC server
|
||||||
|
- Testing with grpcurl
|
||||||
|
- Common workflows
|
||||||
|
|
||||||
|
5. **[AGENT_TEST_QUICKREF.md](AGENT_TEST_QUICKREF.md)** - CLI agent test command
|
||||||
|
- Supported prompt patterns
|
||||||
|
- Example workflows
|
||||||
|
- Error handling
|
||||||
|
|
||||||
|
6. **[E2E_VALIDATION_GUIDE.md](E2E_VALIDATION_GUIDE.md)** - Complete validation checklist
|
||||||
|
- Testing procedures
|
||||||
|
- Success criteria
|
||||||
|
- Issue reporting
|
||||||
|
|
||||||
### Status Documents
|
### Status Documents
|
||||||
- [Project Status](PROJECT_STATUS_OCT2.md) - Comprehensive overview
|
|
||||||
- [Work Summary](WORK_SUMMARY_OCT2.md) - Today's accomplishments
|
|
||||||
- [Test Validation](TEST_VALIDATION_STATUS_OCT2.md) - E2E test results
|
|
||||||
|
|
||||||
### Archive
|
7. **[PROJECT_STATUS_OCT2.md](PROJECT_STATUS_OCT2.md)** - Current project status
|
||||||
Historical documentation moved to archive/ folder.
|
- Component completion percentages
|
||||||
|
- Performance metrics
|
||||||
|
- Known limitations
|
||||||
|
|
||||||
|
8. **[NEXT_PRIORITIES_OCT2.md](NEXT_PRIORITIES_OCT2.md)** - Detailed next steps
|
||||||
|
- Priority 0-3 task breakdowns
|
||||||
|
- Implementation guides
|
||||||
|
- Time estimates
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
See NEXT_ACTIONS_OCT3.md for detailed next steps.
|
### Build z3ed
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic build (without gRPC)
|
||||||
|
cmake --build build --target z3ed -j8
|
||||||
|
|
||||||
|
# With gRPC support (for GUI automation)
|
||||||
|
cmake -B build-grpc-test -DYAZE_WITH_GRPC=ON
|
||||||
|
cmake --build build-grpc-test --target z3ed -j$(sysctl -n hw.ncpu)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Display ROM info
|
||||||
|
z3ed rom info --rom=zelda3.sfc
|
||||||
|
|
||||||
|
# Export a palette
|
||||||
|
z3ed palette export sprites_aux1 4 soldier.col
|
||||||
|
|
||||||
|
# Create an agent proposal
|
||||||
|
z3ed agent run --prompt "Make soldiers red" --rom=zelda3.sfc --sandbox
|
||||||
|
|
||||||
|
# List all proposals
|
||||||
|
z3ed agent list
|
||||||
|
|
||||||
|
# View proposal changes
|
||||||
|
z3ed agent diff
|
||||||
|
|
||||||
|
# Automated GUI testing (requires test harness)
|
||||||
|
z3ed agent test --prompt "Open Overworld editor and verify it loads"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Start Test Harness (Optional)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Terminal 1: Start YAZE with test harness
|
||||||
|
./build-grpc-test/bin/yaze.app/Contents/MacOS/yaze \
|
||||||
|
--enable_test_harness \
|
||||||
|
--test_harness_port=50052 \
|
||||||
|
--rom_file=assets/zelda3.sfc &
|
||||||
|
|
||||||
|
# Terminal 2: Run automated test
|
||||||
|
./build-grpc-test/bin/z3ed agent test \
|
||||||
|
--prompt "Open Overworld editor"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Documentation Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/z3ed/
|
||||||
|
├── Core Documentation (3 files)
|
||||||
|
│ ├── E6-z3ed-cli-design.md [Source of Truth]
|
||||||
|
│ ├── E6-z3ed-reference.md [Technical Reference]
|
||||||
|
│ └── E6-z3ed-implementation-plan.md [Tracker]
|
||||||
|
│
|
||||||
|
├── Quick Start Guides (3 files)
|
||||||
|
│ ├── IT-01-QUICKSTART.md [Test Harness]
|
||||||
|
│ ├── AGENT_TEST_QUICKREF.md [CLI Agent Test]
|
||||||
|
│ └── E2E_VALIDATION_GUIDE.md [Validation]
|
||||||
|
│
|
||||||
|
├── Status Documents (4 files)
|
||||||
|
│ ├── README.md [This file]
|
||||||
|
│ ├── PROJECT_STATUS_OCT2.md [Current Status]
|
||||||
|
│ ├── NEXT_PRIORITIES_OCT2.md [Next Steps]
|
||||||
|
│ └── WORK_SUMMARY_OCT2.md [Recent Work]
|
||||||
|
│
|
||||||
|
└── Archive (15+ files)
|
||||||
|
└── Historical documentation and implementation notes
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Features
|
||||||
|
|
||||||
|
### ✅ Completed (Production-Ready on macOS)
|
||||||
|
|
||||||
|
- **Resource-Oriented CLI**: Clean command structure (`z3ed <resource> <action>`)
|
||||||
|
- **Resource Catalogue**: Machine-readable API specs (`docs/api/z3ed-resources.yaml`)
|
||||||
|
- **Acceptance Workflow**: Proposal tracking, sandbox management, GUI review
|
||||||
|
- **ImGuiTestHarness (IT-01)**: gRPC-based GUI automation (6 RPC methods)
|
||||||
|
- **CLI Agent Test (IT-02)**: Natural language → automated GUI tests
|
||||||
|
- **ProposalDrawer**: Integrated proposal review UI in YAZE
|
||||||
|
- **ROM Operations**: info, validate, diff, generate-golden
|
||||||
|
- **Palette Operations**: export, import, list
|
||||||
|
- **Overworld Operations**: get-tile, set-tile
|
||||||
|
- **Dungeon Operations**: list-rooms, add-object
|
||||||
|
|
||||||
|
### 🔄 In Progress (80% Complete)
|
||||||
|
|
||||||
|
- **E2E Validation**: Full workflow testing (window detection needs fix)
|
||||||
|
|
||||||
|
### 📋 Planned (Next Priorities)
|
||||||
|
|
||||||
|
1. **Policy Evaluation Framework (AW-04)**: YAML-based constraints
|
||||||
|
2. **Windows Cross-Platform Testing**: Validate on Windows with vcpkg
|
||||||
|
3. **Production Readiness**: Telemetry, screenshot, expanded tests
|
||||||
|
|
||||||
|
## Architecture Highlights
|
||||||
|
|
||||||
|
### Proposal-Based Workflow
|
||||||
|
|
||||||
|
```
|
||||||
|
User Prompt → AI Service → Sandbox ROM → Execute Commands →
|
||||||
|
Create Proposal → Review in GUI → Accept/Reject → Commit to ROM
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Stack
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────┐
|
||||||
|
│ AI Agent (LLM) │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ z3ed CLI │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ Service Layer │
|
||||||
|
│ • ProposalRegistry │
|
||||||
|
│ • RomSandboxManager │
|
||||||
|
│ • GuiAutomationClient │
|
||||||
|
│ • TestWorkflowGenerator │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ ImGuiTestHarness (gRPC) │
|
||||||
|
├─────────────────────────────────┤
|
||||||
|
│ YAZE GUI + ProposalDrawer │
|
||||||
|
└─────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Resources
|
||||||
|
|
||||||
|
**Machine-Readable API**: `docs/api/z3ed-resources.yaml`
|
||||||
|
**Proto Schema**: `src/app/core/proto/imgui_test_harness.proto`
|
||||||
|
**Test Script**: `scripts/test_harness_e2e.sh`
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
See **[B1-contributing.md](../B1-contributing.md)** for general contribution guidelines.
|
||||||
|
|
||||||
|
For z3ed-specific development:
|
||||||
|
1. Read **E6-z3ed-cli-design.md** for architecture
|
||||||
|
2. Check **E6-z3ed-implementation-plan.md** for open tasks
|
||||||
|
3. Use **E6-z3ed-reference.md** for API details
|
||||||
|
4. Follow **NEXT_PRIORITIES_OCT2.md** for current work
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Same as YAZE - see `LICENSE` in repository root.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: October 2, 2025
|
||||||
|
**Contributors**: @scawful, GitHub Copilot
|
||||||
|
**Next Milestone**: E2E Validation Complete (Est. Oct 3, 2025)
|
||||||
|
|||||||
@@ -1,6 +1,82 @@
|
|||||||
# z3ed Documentation Archive
|
# z3ed Documentation Archive
|
||||||
|
|
||||||
This folder contains historical documentation that was useful during development but is no longer actively maintained. These files are kept for reference and to understand the project's evolution.
|
**Last Updated**: October 2, 2025
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
This archive contains historical documentation from the z3ed development process. These documents capture implementation decisions, progress logs, and technical investigations that led to the current design.
|
||||||
|
|
||||||
|
**⚠️ Note**: These documents are **historical references only**. For current information, see the main documentation in the parent directory.
|
||||||
|
|
||||||
|
## Archive Contents
|
||||||
|
|
||||||
|
### Technical Investigations
|
||||||
|
|
||||||
|
- **IT-01-grpc-evaluation.md** - gRPC vs alternatives analysis (decision: use gRPC)
|
||||||
|
- **GRPC_TECHNICAL_NOTES.md** - gRPC implementation details and lessons learned
|
||||||
|
- **DEPENDENCY_MANAGEMENT.md** - Build system and dependency strategy
|
||||||
|
|
||||||
|
### Implementation Progress Logs
|
||||||
|
|
||||||
|
- **GRPC_TEST_SUCCESS.md** - IT-01 Phase 1 completion (gRPC infrastructure working)
|
||||||
|
- **IT-01-PHASE2-IMPLEMENTATION-GUIDE.md** - TestManager integration guide
|
||||||
|
- **IT-01-PHASE3-COMPLETE.md** - Full ImGuiTestEngine integration completion
|
||||||
|
- **IT-01-getting-started-grpc.md** - Early gRPC setup guide
|
||||||
|
|
||||||
|
### Session Summaries
|
||||||
|
|
||||||
|
- **STATE_SUMMARY_2025-10-01.md** - October 1 status snapshot
|
||||||
|
- **STATE_SUMMARY_2025-10-02.md** - October 2 status snapshot
|
||||||
|
- **SESSION_SUMMARY_OCT2.md** - October 2 morning session
|
||||||
|
- **SESSION_SUMMARY_OCT2_EVENING.md** - October 2 evening session
|
||||||
|
- **PROGRESS_SUMMARY_2025-10-02.md** - Consolidated progress report
|
||||||
|
|
||||||
|
### Implementation Status Reports
|
||||||
|
|
||||||
|
- **IMPLEMENTATION_PROGRESS_OCT2.md** - Detailed progress tracking
|
||||||
|
- **IMPLEMENTATION_STATUS_OCT2_PM.md** - PM session status
|
||||||
|
- **RUNTIME_FIX_COMPLETE_OCT2.md** - IT-02 runtime fix completion
|
||||||
|
- **QUICK_TEST_RUNTIME_FIX.md** - Quick validation guide
|
||||||
|
|
||||||
|
### Planning & Organization
|
||||||
|
|
||||||
|
- **DOCUMENTATION_CONSOLIDATION_OCT2.md** - Documentation cleanup plan
|
||||||
|
- **DOCUMENTATION_REVIEW_OCT2.md** - Documentation audit results
|
||||||
|
- **FILE_MODIFICATION_CHECKLIST.md** - Change tracking checklist
|
||||||
|
|
||||||
|
## Superseded By
|
||||||
|
|
||||||
|
All information in these archived documents has been consolidated into:
|
||||||
|
|
||||||
|
1. **[E6-z3ed-cli-design.md](../E6-z3ed-cli-design.md)** - Architecture and design decisions
|
||||||
|
2. **[E6-z3ed-reference.md](../E6-z3ed-reference.md)** - Technical reference and APIs
|
||||||
|
3. **[E6-z3ed-implementation-plan.md](../E6-z3ed-implementation-plan.md)** - Current status and roadmap
|
||||||
|
4. **[IT-01-QUICKSTART.md](../IT-01-QUICKSTART.md)** - Test harness usage guide
|
||||||
|
5. **[AGENT_TEST_QUICKREF.md](../AGENT_TEST_QUICKREF.md)** - CLI agent test reference
|
||||||
|
6. **[PROJECT_STATUS_OCT2.md](../PROJECT_STATUS_OCT2.md)** - Current project status
|
||||||
|
|
||||||
|
## When to Reference Archive
|
||||||
|
|
||||||
|
Use archived documents when:
|
||||||
|
- Investigating why a particular technical decision was made
|
||||||
|
- Understanding the evolution of the codebase
|
||||||
|
- Debugging platform-specific issues covered in technical notes
|
||||||
|
- Reviewing historical performance metrics or test results
|
||||||
|
|
||||||
|
## Retention Policy
|
||||||
|
|
||||||
|
These documents are retained for:
|
||||||
|
- **Historical reference**: Understanding design evolution
|
||||||
|
- **Troubleshooting**: Platform-specific quirks and workarounds
|
||||||
|
- **Knowledge transfer**: New contributors understanding project history
|
||||||
|
|
||||||
|
Documents may be removed after 6 months if their content is fully superseded and no longer referenced.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Maintained by**: @scawful
|
||||||
|
**Archive Created**: October 2, 2025
|
||||||
|
**Purpose**: Preserve development history and technical investigations
|
||||||
|
|
||||||
## Archived Documentation
|
## Archived Documentation
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user