# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview **Dose** is a DOS-style command shell implementation written in Zig. Originally started in Rust, the project has been completely rewritten in Zig to provide a nostalgic DOS computing experience with modern systems programming capabilities. ## Development Commands ```bash # Development (Zig) zig build # Build debug version zig build run # Build and run in debug mode zig build test # Run unit tests zig build -Doptimize=ReleaseFast # Optimized build # Legacy (Original Rust - archived) cargo run # Run in debug mode with REPL shell cargo build # Build debug version ``` ## Architecture ### Command System Design The application uses a type-safe command architecture with Zig unions and enums: - **`Command`**: Top-level union supporting pipes, redirections, external programs, and builtins - **`BuiltinCommand`**: Comprehensive DOS command set covering file operations, shell control, and utilities - **`FileSpec`**: Handles console (`Con`) vs file path targets for I/O redirection - **`InputSource`**: Manages input redirection from files with line-by-line processing - **`OutputCapture`**: Buffers command output for redirection to files ### Implementation Status #### ✅ **Fully Implemented Features** - **Interactive REPL Shell**: Command-line interface with DOS-style prompts (`C:\PATH>`) - **Command Parsing**: Complete lexer/parser for DOS command syntax with quote support - **Built-in Commands**: Core DOS commands with authentic behavior and error messages - **External Command Execution**: Full process spawning with I/O redirection support - **I/O Redirection**: Complete input (`<`), output (`>`), and append (`>>`) redirection - **Error Handling**: DOS-authentic error messages and proper exit codes - **Path Formatting**: DOS-style path display with drive letters and 8.3 filename conversion #### 📋 **Built-in Commands Available** - **`ECHO`** (with ON/OFF variants) - Text output and echo state control - **`CLS`** - Clear screen with ANSI escape sequences - **`EXIT`** - Exit the shell - **`VER`** - Version information display - **`DATE`** - Current system date with proper calendar calculations - **`TIME`** - Current system time display - **`DIR`** - Directory listing with file sizes and counts - **`TYPE`** - Display file contents with binary character filtering - **`SORT`** - Alphabetical line sorting with input redirection support #### 🔧 **External Command Support** - **Process Spawning**: Uses `std.process.Child` for external program execution - **Argument Passing**: Proper command-line argument handling - **I/O Redirection**: Full stdin/stdout/stderr redirection support - **Error Handling**: DOS-compatible "command not found" messages - **Exit Code Propagation**: Proper process exit code handling #### 🔀 **Redirection System** - **Input Redirection** (`<`): Read file content as command input - **Output Redirection** (`>`): Write command output to file (overwrite) - **Append Redirection** (`>>`): Append command output to file - **Combined Redirection**: Support for both input and output redirection simultaneously - **Device Handling**: Proper CON/LPT/PRN device recognition and error handling ### Key Technical Features #### **Memory Management** - **Allocator-based**: Uses Zig's `GeneralPurposeAllocator` for all dynamic memory - **RAII Pattern**: Proper resource cleanup with `defer` statements - **Leak Detection**: Built-in memory leak detection in debug builds #### **Error Handling** - **Zig Error Unions**: Native `!T` error handling instead of exceptions - **DOS-Authentic Messages**: Faithful reproduction of classic DOS error text - **Graceful Degradation**: Robust error recovery and user guidance #### **Cross-Platform Support** - **Zig Standard Library**: Portable file system and process operations - **ANSI Terminal Support**: Cross-platform terminal manipulation - **Path Handling**: DOS-style path formatting on all platforms ### Dependencies **Zero External Dependencies** - The Zig implementation uses only the standard library: - **`std.process`**: External command execution and process management - **`std.fs`**: File system operations for I/O redirection and DIR command - **`std.mem`**: Memory management and string operations - **`std.time`**: System time access for DATE/TIME commands - **`std.io`**: Terminal I/O and file operations ### Build Configuration The project uses Zig's standard build system with optimizations: - **Debug builds**: Full error checking and memory leak detection - **Release builds**: Size and speed optimized for production use - **Cross-compilation**: Native Zig cross-platform compilation support