Module workspace

Expand description

Workspace filesystem abstraction for explicit path resolution.

This module provides the Workspace trait and implementations that eliminate CWD dependencies by making all path operations explicit relative to the repository root.

§Problem

The codebase previously relied on std::env::set_current_dir() to set the process CWD to the repository root, then used relative paths (.agent/, PROMPT.md, etc.) throughout. This caused:

Test flakiness when tests ran in parallel (CWD is process-global)
Background thread bugs when CWD changed after thread started
Poor testability without complex CWD manipulation

§Solution

The Workspace trait defines the interface for file operations, with two implementations:

WorkspaceFs - Production implementation using the real filesystem
MemoryWorkspace - Test implementation with in-memory storage (available with test-utils feature)

§Well-Known Paths

This module defines constants for all Ralph artifact paths:

AGENT_DIR - .agent/ directory
PLAN_MD - .agent/PLAN.md
ISSUES_MD - .agent/ISSUES.md
PROMPT_MD - PROMPT.md (repository root)
CHECKPOINT_JSON - .agent/checkpoint.json

The Workspace trait provides convenience methods for these paths (e.g., Workspace::plan_md).

§Production Example

use ralph_workflow::workspace::WorkspaceFs;
use std::path::PathBuf;

let ws = WorkspaceFs::new(PathBuf::from("/path/to/repo"));

// Get paths to well-known files
let plan = ws.plan_md();  // /path/to/repo/.agent/PLAN.md
let prompt = ws.prompt_md();  // /path/to/repo/PROMPT.md

// Perform file operations
ws.write(Path::new(".agent/test.txt"), "content")?;
let content = ws.read(Path::new(".agent/test.txt"))?;

§Testing with MemoryWorkspace

The test-utils feature enables MemoryWorkspace for integration tests:

use ralph_workflow::workspace::{MemoryWorkspace, Workspace};
use std::path::Path;

// Create a test workspace with pre-populated files
let ws = MemoryWorkspace::new_test()
    .with_file("PROMPT.md", "# Task: Add logging")
    .with_file(".agent/PLAN.md", "1. Add log statements");

// Verify file operations
assert!(ws.exists(Path::new("PROMPT.md")));
assert_eq!(ws.read(Path::new("PROMPT.md"))?, "# Task: Add logging");

// Write and verify
ws.write(Path::new(".agent/output.txt"), "result")?;
assert!(ws.was_written(".agent/output.txt"));

§See Also

crate::executor::ProcessExecutor - Similar abstraction for process execution

Structs§

DirEntry: A directory entry returned by Workspace::read_dir.
WorkspaceFs: Production workspace implementation using the real filesystem.

Constants§

AGENTS_TOML: Path to the agents registry file.
AGENT_CONFIG_TOML: Path to the agent config file.
AGENT_DIR: The .agent directory where Ralph stores all artifacts.
AGENT_LOGSDeprecated: The .agent/logs directory for agent logs (deprecated - per-run logs use RunLogContext).
AGENT_TMP: The .agent/tmp directory for temporary files.
CHECKPOINT_JSON: Path to the checkpoint file for resume support.
COMMIT_MESSAGE_TXT: Path to the commit message file.
ISSUES_MD: Path to the issues file from code review.
NOTES_MD: Path to the notes file.
PIPELINE_LOGDeprecated: Path to the pipeline log file (deprecated - per-run logs use RunLogContext).
PLAN_MD: Path to the implementation plan file.
PROMPT_BACKUP: Path to the prompt backup file.
PROMPT_MD: Path to the prompt file in repository root.
REVIEW_BASELINE_TXT: Path to the review baseline tracking file.
START_COMMIT: Path to the start commit tracking file.
STATUS_MD: Path to the status file.

Traits§

Workspace: Trait defining the workspace filesystem interface.