scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

Browse Source
This commit is contained in:
scawful
2025-12-22 00:20:49 +00:00
parent 2934c82b75
commit 5c4cd57ff8
1259 changed files with 239160 additions and 43801 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/public/cli/README.md Normal file
View File

@@ -0,0 +1,84 @@
# z3ed CLI Reference
The `z3ed` command-line tool provides ROM inspection, validation, AI-assisted editing, and automation capabilities.
---
## Command Categories
### Doctor Suite (Diagnostics)
Validate and repair ROM data integrity.
- [Doctor Commands](doctor-commands.md) - `rom-doctor`, `dungeon-doctor`, `overworld-doctor`, `rom-compare`
### Test Infrastructure
Machine-readable test discovery and execution.
- [Test Commands](test-commands.md) - `test-list`, `test-run`, `test-status`
### Inspection Tools
| Command | Description |
|---------|-------------|
| `hex-read` | Read raw bytes from ROM |
| `hex-search` | Search for byte patterns |
| `palette-get-colors` | Extract palette data |
| `sprite-list` | List sprites |
| `music-list` | List music tracks |
| `dialogue-list` | List dialogue entries |
### Overworld Tools
| Command | Description |
|---------|-------------|
| `overworld-find-tile` | Find tile usage across maps |
| `overworld-describe-map` | Describe map properties |
| `overworld-list-warps` | List warp points |
| `overworld-list-sprites` | List overworld sprites |
### Dungeon Tools
| Command | Description |
|---------|-------------|
| `dungeon-list-sprites` | List dungeon sprites |
| `dungeon-describe-room` | Describe room properties |
| `dungeon-list-objects` | List room objects |
---
## Common Flags
| Flag | Description |
|------|-------------|
| `--rom <path>` | Path to ROM file |
| `--format json\|text` | Output format |
| `--verbose` | Detailed output |
| `--help` | Show command help |
---
## Examples
```bash
# List all commands
z3ed help
# Get help for a command
z3ed help rom-doctor
# JSON output for scripting
z3ed rom-doctor --rom zelda3.sfc --format json
# Parse with jq
z3ed rom-doctor --rom zelda3.sfc --format json | jq '.checksum_valid'
```
---
## Related Documentation
- [z3ed CLI Guide](../usage/z3ed-cli.md) - Usage tutorials and workflows
- [Getting Started](../overview/getting-started.md) - Quick start guide

190
docs/public/cli/doctor-commands.md Normal file
View File

@@ -0,0 +1,190 @@
# z3ed Doctor Commands
The doctor command suite provides diagnostic and repair tools for ROM data integrity. All commands support structured JSON output for automation.
## Available Doctor Commands
| Command | Description |
|---------|-------------|
| `overworld-doctor` | Diagnose/repair overworld data (tile16, pointers, ZSCustom features) |
| `overworld-validate` | Validate map32 pointers and decompression |
| `dungeon-doctor` | Diagnose dungeon room data (objects, sprites, chests) |
| `rom-doctor` | Validate ROM file integrity (header, checksums, expansions) |
| `rom-compare` | Compare two ROMs for differences |
## Common Flags
All doctor commands support:
- `--rom <path>` - Path to ROM file (required)
- `--format json|text` - Output format (default: text)
- `--verbose` - Show detailed output
## overworld-doctor
Diagnose and repair overworld data corruption.
```bash
# Basic diagnosis
z3ed overworld-doctor --rom zelda3.sfc
# Compare against vanilla baseline
z3ed overworld-doctor --rom zelda3.sfc --baseline vanilla.sfc
# Apply fixes with dry-run preview
z3ed overworld-doctor --rom zelda3.sfc --fix --output fixed.sfc --dry-run
# JSON output for agents
z3ed overworld-doctor --rom zelda3.sfc --format json
```
### Detects
- ZSCustomOverworld version (Vanilla, v2, v3)
- Expanded tile16/tile32 regions
- Expanded pointer tables (tail map support)
- Tile16 corruption at known problem addresses
- Map pointer validity for all 160+ maps
## dungeon-doctor
Diagnose dungeon room data integrity.
```bash
# Sample key rooms (fast)
z3ed dungeon-doctor --rom zelda3.sfc
# Analyze all 296 rooms
z3ed dungeon-doctor --rom zelda3.sfc --all
# Analyze specific room
z3ed dungeon-doctor --rom zelda3.sfc --room 0x10
# JSON output
z3ed dungeon-doctor --rom zelda3.sfc --format json --verbose
```
### Validates
- Room header pointers
- Object counts (max 400 before lag)
- Sprite counts (max 64 per room)
- Chest counts (max 6 per room for item flags)
- Object bounds (0-63 for x/y coordinates)
### Sample Output (Text)
```
╔═══════════════════════════════════════════════════════════════╗
║ DUNGEON DOCTOR ║
╠═══════════════════════════════════════════════════════════════╣
║ Rooms Analyzed: 19 ║
║ Valid Rooms: 19 ║
║ Rooms with Warnings: 0 ║
║ Rooms with Errors: 0 ║
╠═══════════════════════════════════════════════════════════════╣
║ Total Objects: 890 ║
║ Total Sprites: 98 ║
╚═══════════════════════════════════════════════════════════════╝
```
## rom-doctor
Validate ROM file integrity and expansion status.
```bash
# Basic validation
z3ed rom-doctor --rom zelda3.sfc
# Verbose with all findings
z3ed rom-doctor --rom zelda3.sfc --verbose
# JSON output for CI/automation
z3ed rom-doctor --rom zelda3.sfc --format json
```
### Validates
- SNES header (title, map mode, country)
- Checksum verification (complement XOR checksum = 0xFFFF)
- ROM size (vanilla 1MB vs expanded 2MB)
- ZSCustomOverworld version detection
- Expansion flags (tile16, tile32, pointer tables)
- Free space analysis in expansion region
### Sample Output (Text)
```
╔═══════════════════════════════════════════════════════════════╗
║ ROM DOCTOR ║
╠═══════════════════════════════════════════════════════════════╣
║ ROM Title: THE LEGEND OF ZELDA ║
║ Size: 0x200000 bytes (2048 KB) ║
║ Map Mode: LoROM ║
║ Country: USA ║
╠═══════════════════════════════════════════════════════════════╣
║ Checksum: 0xAF0D (complement: 0x50F2) - VALID ║
║ ZSCustomOverworld: Vanilla ║
║ Expanded Tile16: NO ║
║ Expanded Tile32: NO ║
║ Expanded Ptr Tables: NO ║
╚═══════════════════════════════════════════════════════════════╝
```
## rom-compare
Compare two ROMs to identify differences.
```bash
# Basic comparison
z3ed rom-compare --rom my_rom.sfc --baseline vanilla.sfc
# Show detailed byte differences
z3ed rom-compare --rom my_rom.sfc --baseline vanilla.sfc --show-diff
# JSON output
z3ed rom-compare --rom my_rom.sfc --baseline vanilla.sfc --format json
```
## Diagnostic Schema
All doctor commands produce findings with consistent structure:
```json
{
"findings": [
{
"id": "tile16_corruption",
"severity": "error",
"message": "Corrupted tile16 at 0x1E878B",
"location": "0x1E878B",
"suggested_action": "Run with --fix to zero corrupted entries",
"fixable": true
}
],
"summary": {
"total_findings": 1,
"critical": 0,
"errors": 1,
"warnings": 0,
"info": 0,
"fixable": 1
}
}
```
### Severity Levels
- `info` - Informational, no action needed
- `warning` - Potential issue, may need attention
- `error` - Problem detected, should be fixed
- `critical` - Severe issue, requires immediate attention
## Agent Usage
For AI agents consuming doctor output:
```bash
# Get structured JSON for parsing
z3ed rom-doctor --rom zelda3.sfc --format json
# Chain with jq for specific fields
z3ed rom-doctor --rom zelda3.sfc --format json | jq '.checksum_valid'
# Check exit code for pass/fail
z3ed rom-doctor --rom zelda3.sfc --format json && echo "ROM OK"
```

237
docs/public/cli/test-commands.md Normal file
View File

@@ -0,0 +1,237 @@
# z3ed Test Commands
The test command suite provides machine-readable test discovery and execution for CI/CD and agent automation.
## Available Test Commands
| Command | Description | Requires ROM |
|---------|-------------|--------------|
| `test-list` | List available test suites with labels and requirements | No |
| `test-run` | Run tests with structured output | No |
| `test-status` | Show test configuration status | No |
## test-list
Discover available test suites and their requirements.
```bash
# Human-readable list
z3ed test-list
# Machine-readable JSON for agents
z3ed test-list --format json
# Filter by label
z3ed test-list --label stable
```
### Sample Output (Text)
```
=== Available Test Suites ===
stable Core unit and integration tests (fast, reliable)
Requirements: None
gui GUI smoke tests (ImGui framework validation)
Requirements: SDL display or headless
z3ed z3ed CLI self-test and smoke tests
Requirements: z3ed target built
headless_gui GUI tests in headless mode (CI-safe)
Requirements: None
rom_dependent Tests requiring actual Zelda3 ROM
Requirements: YAZE_ENABLE_ROM_TESTS=ON + ROM path
⚠ Requires ROM file
experimental AI runtime features and experiments
Requirements: YAZE_ENABLE_AI_RUNTIME=ON
⚠ Requires AI runtime
benchmark Performance and optimization tests
Requirements: None
```
### Sample Output (JSON)
```json
{
"suites": [
{
"label": "stable",
"description": "Core unit and integration tests (fast, reliable)",
"requirements": "None",
"requires_rom": false,
"requires_ai": false
},
{
"label": "rom_dependent",
"description": "Tests requiring actual Zelda3 ROM",
"requirements": "YAZE_ENABLE_ROM_TESTS=ON + ROM path",
"requires_rom": true,
"requires_ai": false
}
],
"total_tests_discovered": 42,
"build_directory": "build"
}
```
## test-run
Run tests and get structured results.
```bash
# Run stable tests (default)
z3ed test-run
# Run specific label
z3ed test-run --label gui
# Run with preset
z3ed test-run --label stable --preset mac-test
# Verbose output
z3ed test-run --label stable --verbose
# JSON output for CI
z3ed test-run --label stable --format json
```
### Sample Output (JSON)
```json
{
"build_directory": "build",
"label": "stable",
"preset": "default",
"tests_passed": 42,
"tests_failed": 0,
"tests_total": 42,
"success": true
}
```
### Exit Codes
- `0` - All tests passed
- `1` - One or more tests failed or error occurred
## test-status
Show current test configuration.
```bash
# Human-readable status
z3ed test-status
# JSON for agents
z3ed test-status --format json
```
### Sample Output (Text)
```
╔═══════════════════════════════════════════════════════════════╗
║ TEST CONFIGURATION ║
╠═══════════════════════════════════════════════════════════════╣
║ ROM Path: (not set) ║
║ Skip ROM Tests: NO ║
║ UI Tests Enabled: NO ║
║ Active Preset: mac-test (fast) ║
╠═══════════════════════════════════════════════════════════════╣
║ Available Build Directories: ║
║ ✓ build ║
╠═══════════════════════════════════════════════════════════════╣
║ Available Test Suites: ║
║ ✓ stable ║
║ ✓ gui ║
║ ✓ z3ed ║
║ ✗ rom_dependent (needs ROM) ║
║ ✓ experimental (needs AI) ║
╚═══════════════════════════════════════════════════════════════╝
```
### Sample Output (JSON)
```json
{
"rom_path": "not set",
"skip_rom_tests": false,
"ui_tests_enabled": false,
"build_directories": ["build"],
"active_preset": "mac-test (fast)",
"available_suites": ["stable", "gui", "z3ed", "headless_gui", "experimental", "benchmark"]
}
```
## Environment Variables
The test commands respect these environment variables:
| Variable | Description |
|----------|-------------|
| `YAZE_TEST_ROM_PATH` | Path to Zelda3 ROM for ROM-dependent tests |
| `YAZE_SKIP_ROM_TESTS` | Set to `1` to skip ROM tests |
| `YAZE_ENABLE_UI_TESTS` | Set to `1` to enable UI tests |
## Quick Start
### For Developers
```bash
# Configure fast test build
cmake --preset mac-test
# Build test targets
cmake --build --preset mac-test
# Run stable tests
z3ed test-run --label stable
```
### For CI/Agents
```bash
# Check what's available
z3ed test-list --format json
# Run stable suite and capture results
z3ed test-run --label stable --format json > test-results.json
# Check exit code
if [ $? -eq 0 ]; then echo "All tests passed"; fi
```
### With ROM Tests
```bash
# Set ROM path
export YAZE_TEST_ROM_PATH=/path/to/zelda3.sfc
# Configure with ROM tests enabled
cmake --preset mac-dev -DYAZE_ENABLE_ROM_TESTS=ON
# Run ROM-dependent tests
z3ed test-run --label rom_dependent
```
## Integration with ctest
The test commands wrap `ctest` internally. You can also use ctest directly:
```bash
# Equivalent to z3ed test-run --label stable
ctest --test-dir build -L stable
# Run all tests
ctest --test-dir build --output-on-failure
# Run specific pattern
ctest --test-dir build -R "RomTest"
```
## Test Labels Reference
| Label | Description | CI Stage |
|-------|-------------|----------|
| `stable` | Core unit + integration tests | PR/Push |
| `gui` | GUI smoke tests | PR/Push |
| `z3ed` | CLI self-tests | PR/Push |
| `headless_gui` | CI-safe GUI tests | PR/Push |
| `rom_dependent` | Tests requiring ROM | Nightly |
| `experimental` | AI features | Nightly |
| `benchmark` | Performance tests | Nightly |