# 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

### Modular Command Architecture
The project uses a fully modularized command architecture with unified context management:

- **`src/cmd/`**: Directory containing individual command implementations
- **`CommandContext`**: Unified context struct containing allocator, I/O capture, and execution functions
- **Command Pattern**: Each command implements `eval(command, ctx: CommandContext)` with consistent signature
- **Type Safety**: Commands are strongly typed Zig structs with compile-time guarantees
- **Shared Types**: Common types defined in `src/cmd/lib/types.zig` for consistency
- **Clean Architecture**: All commands (Builtin, External, Redirect, Pipe) use the same modular pattern

### 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**

**Phase 1 Commands (Core):**
- **`COPY`** - File copying with overwrite prompts and device handling
- **`DIR`** - Directory listing with file sizes, counts, and free space display
- **`TYPE`** - Display file contents with binary character filtering
- **`CD/CHDIR`** - Directory navigation with path validation

**Phase 2 Commands (Extended File Operations):**
- **`MD/MKDIR`** - Directory creation with nested path support
- **`RD/RMDIR`** - Directory removal with safety checks
- **`REN/RENAME`** - File and directory renaming
- **`DEL/REMOVE`** - File deletion with wildcard support
- **`PATH`** - Environment PATH variable management (GET/SET)
- **`MOVE`** - File/directory moving (placeholder - not yet implemented)

**Shell and System Commands:**
- **`ECHO`** (with ON/OFF variants) - Text output and echo state control
- **`CLS`** - Clear screen with ANSI escape sequences  
- **`EXIT`** - Exit the shell
- **`HELP`** - Display command help and usage information
- **`VER`** - Version information display
- **`DATE`** - Current system date with proper calendar calculations
- **`TIME`** - Current system time display
- **`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

### Project Structure

```
src/
├── cmd/                    # Modular command implementations
│   ├── lib/
│   │   ├── flags.zig      # Command-line flag parsing utilities
│   │   └── types.zig      # Shared command types and interfaces
│   ├── chdir.zig          # CD/CHDIR command
│   ├── cls.zig            # CLS command  
│   ├── copy.zig           # COPY command
│   ├── date.zig           # DATE command
│   ├── dir.zig            # DIR command
│   ├── echo.zig           # ECHO command variants
│   ├── external.zig       # External command execution
│   ├── help.zig           # HELP command
│   ├── mkdir.zig          # MD/MKDIR command
│   ├── move.zig           # MOVE command (placeholder)
│   ├── path.zig           # PATH command (GET/SET)
│   ├── pipe.zig           # Command pipe handling
│   ├── redirect.zig       # I/O redirection handling
│   ├── remove.zig         # DEL/REMOVE command
│   ├── rename.zig         # REN/RENAME command
│   ├── rmdir.zig          # RD/RMDIR command
│   ├── sort.zig           # SORT command
│   ├── time.zig           # TIME command
│   ├── type.zig           # TYPE command
│   └── ver.zig            # VER command
├── cmd.zig                # Command type definitions and imports
├── eval.zig               # Command execution engine
├── parser.zig             # DOS command line parser
├── paths.zig              # DOS path formatting utilities  
├── syntax.zig             # Command syntax structures
└── main.zig               # Application entry point and REPL
```

### 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