claude_runner_core 1.0.0

Claude Code process execution with builder pattern
Documentation 
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

# src/

This directory contains the core implementation of the `claude_runner_core` crate, providing builder pattern API for executing Claude Code commands programmatically.

## Responsibility Table

| File | Responsibility |
|------|----------------|
| `lib.rs` | Crate entry point and public API surface |
| `command/` | ClaudeCommand builder split into per-tier parameter modules |
| `types.rs` | Enum type definitions and conversions |
| `process.rs` | Scan `/proc` for Claude processes; send SIGTERM/SIGKILL |
| `session_dir.rs` | Directory-based session isolation for invocations |

## Organization (5 entries)

Files organized by responsibility following Rust module conventions.

### Module Structure

```
src/
├── lib.rs              # Crate root, public API
├── command/            # ClaudeCommand builder (split into 4 files)
│   ├── mod.rs          # Struct def, execution methods, describe helpers
│   ├── params_core.rs  # Tier 1 critical parameters
│   ├── params_security.rs  # Tier 2 security-sensitive parameters
│   └── params_extended.rs  # Tier 3+ optional parameters
├── types.rs            # ActionMode, LogLevel enums
├── process.rs          # /proc scanner, signal sending
└── session_dir.rs      # Session directory isolation
```

### Scope

**In Scope:**
- Builder pattern API for Claude Code command construction
- Environment variable automation (tier 1 defaults: bash_timeout=3.6M, bash_max_timeout=7.2M, auto_continue=true, telemetry=false, max_output_tokens=200K)
- Type safety via enums (ActionMode, LogLevel)
- Private field encapsulation (prevents direct construction)
- Single execution point (execute() method)
- Test-only helpers for verification without actual execution
- `/proc` scanning for running Claude Code processes
- Signal delivery (SIGTERM, SIGKILL) to Claude processes

**Out of Scope:**
- Session lifecycle management (→ claude_profile crate)
- Context injection from wplan (→ dream_agent crate)
- Interactive terminal UI (→ terminal-based tools)
- Configuration hierarchy (→ config_hierarchy crate)

### Design Principles

1. **Single Execution Point**: All commands go through execute()
2. **Builder Pattern**: Configuration via chainable with_*() methods
3. **Private Fields**: Cannot construct with struct literals
4. **No Session Logic**: Pure execution, no state management
5. **Migration Complete**: Old factory pattern impossible (from_message/create/generate removed)
6. **Type Safety**: Enums replace string literals (ActionMode, LogLevel)

### Test Coverage

Comprehensive test suite in `tests/` directory:
- Builder pattern API (4 test files): edge cases, methods, defaults, environment variables
- Type definitions (1 test file): enum conversions and defaults
- Migration validation (2 test files): factory pattern removal, single execution point
- Verification framework (5 test files): 231 validation assertions across 6 layers (spec.md NFR-6)
- Inspection methods (1 test file): describe() and describe_env()
- Execution output (1 test file): ExecutionOutput struct and Display
- Skip permissions (1 test file): --dangerously-skip-permissions flag
- Manual execution (2 test files): real Claude binary tests (skipped in CI)
- **Total**: 21 test files, all passing; see tests/readme.md and spec.md NFR-6 for counts

See `tests/readme.md` for complete test documentation.