v4_cli 0.3.0

CLI tool for V4 VM bytecode deployment
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.4.0] - 2025-11-05

### Added
- **New debugging meta-commands for REPL**
  - `.stack` - Display data stack and return stack contents
  - `.rstack` - Display return stack with call trace
  - `.dump [addr] [len]` - Hexdump memory at specified address (default: 256 bytes)
  - `.see <word_idx>` - Show word bytecode disassembly
- **V4-link protocol query commands**
  - `QueryStack (0x30)` - Query stack state
  - `QueryMemory (0x40)` - Query memory dump
  - `QueryWord (0x50)` - Query word information
- Serial protocol methods: `query_stack()`, `query_memory()`, `query_word()`
- Response data field for query command payloads
- CLI error variant for user input validation errors

### Changed
- Updated `.help` command to include new debugging meta-commands
- Enhanced `Response` struct with `data` field for query responses

## [0.3.0] - 2025-11-04

### Added

- `v4 exec <file> --port <PORT>` command for executing Forth source files on device
  - Compiles Forth source code (.fs files) using V4-front
  - Sends word definitions to device and registers them in VM
  - Executes main bytecode if present
  - Supports `--timeout` flag for configuring execution timeout
- `v4 exec --repl` flag to enter REPL after file execution
  - Preserves compiler context from file execution
  - Enables immediate testing of defined words
  - Seamless transition from batch execution to interactive mode
- `v4 repl --no-reset` flag to skip VM reset on REPL startup
  - Preserves existing word definitions on device
  - Useful for connecting to already-running VMs
  - Displays warning about empty compiler context
- Example Forth library: `examples/nanoc6/led.fs`
  - LED control words for NanoC6 (ESP32-C6) board
  - Provides `led-on`, `led-off`, `led-blink`, `led-blink-fast`, `led-blink-slow`
  - Demonstrates GPIO syscall usage (SYS 0, SYS 1, SYS 34)

### Changed

- REPL startup message now shows version from `CARGO_PKG_VERSION`
- Improved REPL help text with `.reset` command documentation

## [0.2.0] - 2025-11-02

### Added

- Build configuration for V4-front library integration via CMake
- Support for compiling Forth source code to bytecode
- Vendored V4, V4-front, and V4-repl libraries for standalone builds
- Static linking of libv4, libv4front, and libv4repl
- Rust FFI bindings for V4-front compiler API with safe wrapper
- `v4 repl --port <PORT>` command for interactive Forth REPL over serial connection
- Meta-commands in REPL: `.help`, `.ping`, `.reset`, `.exit`
- Persistent word definitions across REPL lines
- Command history with rustyline (arrow keys navigation)

### Changed

- **BREAKING**: Extended V4-link protocol EXEC response to variable-length format
  - EXEC response now includes word indices registered by device VM
  - Response format: `[STX][LEN_L][LEN_H][ERR_CODE][WORD_COUNT][WORD_IDX...]...[CRC8]`
  - Required for proper word definition synchronization between host compiler and device VM
- Updated REPL to use device-returned word indices instead of auto-incrementing
- Fixed word definition functionality in REPL (previously would timeout on word usage)
- Updated CLI help text to include REPL command

### Fixed

- Fixed serial response reading to support variable-length frames
  - Previously hardcoded to read exactly 5 bytes (old protocol format)
  - Now reads LENGTH field from frame header to determine total frame size
  - Enables proper handling of EXEC responses with word indices
  - Critical fix for REPL word definition support

### Infrastructure

- Add comprehensive CI/CD workflows (test, lint, security, release)
- Add cargo-deny configuration for dependency management
- Add multi-platform release builds (Linux, macOS, Windows, ARM64)
- Add security audit workflow with cargo-audit

## [0.1.0] - 2025-01-XX

### Added

- Initial release of v4 CLI tool
- V4-link protocol implementation (CRC-8, frame encoding/decoding)
- `v4 push` command for deploying bytecode to devices
- `v4 ping` command for checking device connection
- `v4 reset` command for resetting VM state
- Progress bar for bytecode deployment
- Configurable timeout for all commands
- `--detach` flag for fire-and-forget deployment
- Support for ESP32-C6, CH32V203, and other V4-enabled devices

### Technical Details

- CRC-8 checksum with polynomial 0x07
- Little-endian frame encoding
- Default baud rate: 115200
- Maximum payload size: 512 bytes
- Default timeout: 5 seconds

[Unreleased]: https://github.com/kirisaki/v4-cli/compare/v0.3.0...HEAD
[0.3.0]: https://github.com/kirisaki/v4-cli/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/kirisaki/v4-cli/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/kirisaki/v4-cli/releases/tag/v0.1.0