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
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# 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
|
