ralph-agent-loop 0.4.0

A Rust CLI for managing AI agent loops with a structured JSON task queue
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
75
76
77

//! Queue archive subcommand.
//!
//! Responsibilities:
//! - Move terminal tasks (done/rejected) from queue.json to done.json.
//! - Support dry-run mode to preview what would be archived.
//!
//! Not handled here:
//! - Automatic archiving based on task age (see `queue.auto_archive_terminal_after_days`).
//! - Archive internals (see `crate::queue::operations::archive`).
//!
//! Invariants/assumptions:
//! - Dry-run mode does NOT create undo snapshots or write to disk.
//! - Normal mode creates an undo snapshot before mutation.

use anyhow::Result;
use clap::Args;

use crate::config::Resolved;
use crate::queue;

/// Arguments for `ralph queue archive`.
#[derive(Args)]
#[command(
    after_long_help = "Examples:\n  ralph queue archive\n  ralph queue archive --dry-run\n\nDry run:\n  Shows what would be archived without modifying files."
)]
pub struct QueueArchiveArgs {
    /// Show what would be archived without writing to disk.
    #[arg(long)]
    pub dry_run: bool,
}

pub(crate) fn handle(resolved: &Resolved, force: bool, args: QueueArchiveArgs) -> Result<()> {
    let _queue_lock = queue::acquire_queue_lock(&resolved.repo_root, "queue archive", force)?;

    // Create undo snapshot before mutation (only if not dry-run)
    if !args.dry_run {
        crate::undo::create_undo_snapshot(resolved, "queue archive")?;
    }

    let max_depth = resolved.config.queue.max_dependency_depth.unwrap_or(10);

    if args.dry_run {
        // Dry-run: compute what would be archived without modifying files
        let mut active = queue::load_queue(&resolved.queue_path)?;
        let mut done = queue::load_queue_or_default(&resolved.done_path)?;
        let now = crate::timeutil::now_utc_rfc3339()?;
        let report = queue::archive_terminal_tasks_in_memory(&mut active, &mut done, &now)?;

        if report.moved_ids.is_empty() {
            log::info!("Dry run: no terminal tasks to archive.");
        } else {
            log::info!(
                "Dry run: would archive {} terminal task(s).",
                report.moved_ids.len()
            );
            log::info!("Task IDs: {}", report.moved_ids.join(", "));
        }
    } else {
        // Normal execution
        let report = queue::archive_terminal_tasks(
            &resolved.queue_path,
            &resolved.done_path,
            &resolved.id_prefix,
            resolved.id_width,
            max_depth,
        )?;
        if report.moved_ids.is_empty() {
            log::info!("No terminal tasks (done/rejected) to archive.");
        } else {
            log::info!(
                "Archived {} terminal task(s) (done/rejected).",
                report.moved_ids.len()
            );
        }
    }
    Ok(())
}