Add preview mode to all mutators

CLAUDE.md

@@ -42,6 +42,10 @@ r -e 'tinypkgr::check()'
 - Text files in `this_week/` remain the source of truth. `tasks()` is a read-through projection, not a cache.
 - Internal callers that need the full schema (sections, period, paths, ordering) should keep using `parse_todo()`.
 
+## Preview mode
+
+Every mutator (`roll_day`, `run_monday`, `fix_parents`, `next_day`, `sync_from_daily`, `instantiate_todo`) accepts `preview = TRUE` and returns a `hacer_preview` describing the would-be change without writing. Set `HACER_PREVIEW=1` to flip the default — useful for one-shot agent invocations that should be inspectable before they touch the user's todo repo. Internals live in `R/preview.R`; each mutator builds a `targets` list of `path -> new_lines` and dispatches via `.write_or_preview()`.
+
 ## Task File Format
 
 ```

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: hacer
 Title: Plain-Text Nested ToDo Planning
-Version: 0.1.5
+Version: 0.1.6
 Authors@R: c(
     person("Troy", "Hernandez", role = c("aut", "cre"),
            email = "troy@cornball.ai",

NAMESPACE

@@ -19,4 +19,6 @@ export(tasks)
 export(todo_config)
 export(use_repo)
 
+S3method(print,hacer_preview)
+
 importFrom(yaml,read_yaml)

R/cli.R

@@ -2,60 +2,66 @@
 #' Generate the new week's files (run on Mondays)
 #' @param date A Date. Defaults to `Sys.Date()`.
 #' @param cfg A config list from `todo_config()`.
+#' @param preview If `TRUE`, return a `hacer_preview` instead of writing.
+#'   Defaults to the `HACER_PREVIEW=1` env var or `FALSE`.
 #' @export
-run_monday <- function(date = Sys.Date(), cfg = todo_config()) {
-  dir.create(cfg$live_dir, recursive = TRUE, showWarnings = FALSE)
-  dir.create(cfg$archive_dir, recursive = TRUE, showWarnings = FALSE)
-
+run_monday <- function(date = Sys.Date(), cfg = todo_config(),
+                       preview = .preview_default()) {
+  if (!preview) {
+    dir.create(cfg$live_dir, recursive = TRUE, showWarnings = FALSE)
+    dir.create(cfg$archive_dir, recursive = TRUE, showWarnings = FALSE)
+  }
+
   this_mon <- .monday_of(date)
-  # find previous Monday by subtracting 7 days
   prev_mon <- this_mon - 7L
-
-  # locate previous set in archive or live
+
   prev <- paths_for(prev_mon, cfg)
   if (!all(file.exists(prev$live)) && !all(file.exists(prev$archive))) {
     stop("Previous week's files not found in live or archive.")
   }
   src <- if (all(file.exists(prev$live))) prev$live else prev$archive
-
-  # read previous
+
   daily   <- parse_todo(src[.period_types == "Daily"],   "Daily")
   week    <- parse_todo(src[.period_types == "Week"],    "Week")
   month   <- parse_todo(src[.period_types == "Month"],   "Month")
   quarter <- parse_todo(src[.period_types == "Quarter"], "Quarter")
-
-  # advance and build new tables
+
   nxt <- advance_period(daily, week, month, quarter, prev_mon, this_mon)
-
-  # write to live (Syncthing)
+
   dst <- paths_for(this_mon, cfg)
+  targets <- list()
   for (p in .period_types) {
     df <- nxt[[p]]
-    write_todo_txt(df, dst$live[.period_types==p], p, cfg)
+    txt_path <- dst$live[.period_types == p]
+    targets[[txt_path]] <- build_todo_txt_lines(df, txt_path, p, cfg)
     if (isTRUE(cfg$render_markdown)) {
-      write_markdown(df, sub("\\.txt$", ".md", dst$live[.period_types==p]), p, cfg)
+      md_path <- sub("\\.txt$", ".md", txt_path)
+      targets[[md_path]] <- build_markdown_lines(df, md_path, p, cfg)
     }
     if (isTRUE(cfg$render_html)) {
-      write_simple_html(df, sub("\\.txt$", ".html", dst$live[.period_types==p]), p)
+      html_path <- sub("\\.txt$", ".html", txt_path)
+      targets[[html_path]] <- build_simple_html_lines(df, html_path, p)
     }
   }
-
+
+  result <- .write_or_preview(targets, preview)
+
   # archive: copy previous live into archive, then git add/commit if the folder is a repo
-  if (all(file.exists(prev$live))) {
+  # This side effect only happens in non-preview mode.
+  if (!preview && all(file.exists(prev$live))) {
     file.copy(from = prev$live, to = prev$archive, overwrite = TRUE)
-    # best-effort git (no dependency)
     old_wd <- getwd(); on.exit(setwd(old_wd), add = TRUE)
     setwd(cfg$archive_dir)
     if (file.exists(file.path(cfg$archive_dir, ".git"))) {
       system2("git", c("add", "."))
       msg <- paste("Archive ToDos:", format(prev_mon))
       system2("git", c("commit", "-m", shQuote(msg)), stdout = FALSE, stderr = FALSE)
-      # optional push:
       system2("git", c("push"), stdout = FALSE, stderr = FALSE)
     }
   }
-
-  invisible(dst$live)
+
+  if (!preview) return(invisible(dst$live))
+  result
 }
 
 #' Infer a period name from a ToDo filename
@@ -69,33 +75,42 @@ infer_period_from_filename <- function(f){
 
 #' Roll up parent statuses in a single file
 #' @param file_name Path to a ToDo `.txt` file.
+#' @param preview If `TRUE`, return a `hacer_preview` instead of writing.
+#'   Defaults to the `HACER_PREVIEW=1` env var or `FALSE`.
 #' @export
-fix_parents <- function(file_name){
+fix_parents <- function(file_name, preview = .preview_default()){
   per <- infer_period_from_filename(file_name)
   df  <- parse_todo(file_name, per)
   df  <- inherit_recur_to_parents(df)
   df  <- rollup_status(df)
-  write_todo_txt(df, file_name, ifelse(is.na(per), "Daily", per))
-  invisible(file_name)
+  per_eff <- ifelse(is.na(per), "Daily", per)
+  new_lines <- build_todo_txt_lines(df, file_name, per_eff)
+  targets <- list()
+  targets[[file_name]] <- new_lines
+  result <- .write_or_preview(targets, preview)
+  if (!preview) return(invisible(file_name))
+  result
 }
 
 # R/cli.R
 #' Sync new items added in Daily up to Week/Month/Quarter
 #' @param date A Date. Defaults to `Sys.Date()`.
 #' @param cfg A config list from `todo_config()`.
+#' @param preview If `TRUE`, return a `hacer_preview` instead of writing.
+#'   Defaults to the `HACER_PREVIEW=1` env var or `FALSE`.
 #' @export
-sync_from_daily <- function(date = Sys.Date(), cfg = todo_config()){
+sync_from_daily <- function(date = Sys.Date(), cfg = todo_config(),
+                            preview = .preview_default()){
   p   <- paths_for(date, cfg)
   d   <- parse_todo(p$live[grepl("_Daily", p$live)], "Daily")
   W   <- parse_todo(p$live[grepl("_Week",  p$live)], "Week")
   M   <- parse_todo(p$live[grepl("_Month", p$live)], "Month")
   Q   <- parse_todo(p$live[grepl("_Quarter",p$live)], "Quarter")
-  
+
   add_missing <- function(src, tgt){
     if (!nrow(src)) return(tgt)
     need <- setdiff(src$path, tgt$path)
     if (!length(need)) return(tgt)
-    # append missing paths (and any missing ancestors)
     append_path <- function(tgt, fullpath, section){
       parts <- strsplit(fullpath, " > ", fixed=TRUE)[[1]]
       cur <- character()
@@ -125,14 +140,22 @@ sync_from_daily <- function(date = Sys.Date(), cfg = todo_config()){
     }
     tgt
   }
-  
+
   W <- add_missing(d, W);  M <- add_missing(d, M);  Q <- add_missing(d, Q)
   W <- inherit_recur_to_parents(W); M <- inherit_recur_to_parents(M); Q <- inherit_recur_to_parents(Q)
   W <- rollup_status(W);             M <- rollup_status(M);             Q <- rollup_status(Q)
-  write_todo_txt(W, p$live[grepl("_Week",    p$live)], "Week",  cfg)
-  write_todo_txt(M, p$live[grepl("_Month",   p$live)], "Month", cfg)
-  write_todo_txt(Q, p$live[grepl("_Quarter", p$live)], "Quarter", cfg)
-  invisible(TRUE)
+
+  w_path <- p$live[grepl("_Week",    p$live)]
+  m_path <- p$live[grepl("_Month",   p$live)]
+  q_path <- p$live[grepl("_Quarter", p$live)]
+  targets <- list()
+  targets[[w_path]] <- build_todo_txt_lines(W, w_path, "Week",  cfg)
+  targets[[m_path]] <- build_todo_txt_lines(M, m_path, "Month", cfg)
+  targets[[q_path]] <- build_todo_txt_lines(Q, q_path, "Quarter", cfg)
+
+  result <- .write_or_preview(targets, preview)
+  if (!preview) return(invisible(TRUE))
+  result
 }
 
 #' Advance tasks from today to tomorrow within the Daily file
@@ -144,27 +167,28 @@ sync_from_daily <- function(date = Sys.Date(), cfg = todo_config()){
 #'
 #' @param date A Date. Defaults to `Sys.Date()`.
 #' @param cfg A config list from `todo_config()`.
+#' @param preview If `TRUE`, return a `hacer_preview` instead of writing.
+#'   Defaults to the `HACER_PREVIEW=1` env var or `FALSE`.
 #' @export
-next_day <- function(date = Sys.Date(), cfg = todo_config()) {
+next_day <- function(date = Sys.Date(), cfg = todo_config(),
+                     preview = .preview_default()) {
   p <- paths_for(date, cfg)
   daily_file <- p$live[grepl("_Daily", p$live)]
   if (!file.exists(daily_file)) stop("Daily file not found: ", daily_file)
 
   lines <- readLines(daily_file, warn = FALSE)
-  days <- cfg$daily_sections  # e.g., c("Monday", "Tuesday", ...)
-
-  # Determine today's weekday name
+  days <- cfg$daily_sections
 
   today_name <- weekdays(date)
   today_idx <- match(today_name, days)
   if (is.na(today_idx)) stop("Today (", today_name, ") not in daily_sections")
   if (today_idx >= length(days)) {
     message("Already at ", today_name, " (last day). Nothing to advance.")
+    if (preview) return(.new_preview())
     return(invisible(daily_file))
   }
   tomorrow_name <- days[today_idx + 1L]
 
-  # Find section boundaries
   section_starts <- grep("^#\\s+\\w", lines)
   section_names <- sub("^#\\s+", "", lines[section_starts])
 
@@ -174,84 +198,75 @@ next_day <- function(date = Sys.Date(), cfg = todo_config()) {
     stop("Could not find sections for ", today_name, " and ", tomorrow_name)
   }
 
-  # Find end of today's section (line before tomorrow or next section)
   today_end <- tomorrow_start - 1L
   while (today_end > today_start && grepl("^\\s*$|^#", lines[today_end])) {
     today_end <- today_end - 1L
   }
 
-  # Extract today's task lines
   if (today_end < today_start) {
     message("No tasks in ", today_name, " section.")
+    if (preview) return(.new_preview())
     return(invisible(daily_file))
   }
   today_lines <- lines[(today_start + 1L):today_end]
 
-  # Filter for copying to tomorrow:
-  # - Skip [x] completed items
-  # - Skip Email/ToDo if [/] (daily recurring that got done)
-  # - Keep blank lines between top-level tasks
   copy_lines <- character()
   last_was_task <- FALSE
   for (ln in today_lines) {
-    # Keep blank lines (they separate top-level task groups)
     if (grepl("^\\s*$", ln)) {
       if (last_was_task) copy_lines <- c(copy_lines, "")
       last_was_task <- FALSE
       next
     }
-    if (!grepl("^\\s*\\[", ln)) next  # not a task line
+    if (!grepl("^\\s*\\[", ln)) next
 
     status <- substr(sub("^\\s*", "", ln), 2, 2)
-    if (status == "x") next  # skip completed
+    if (status == "x") next
 
-    # Check if it's Email or ToDo with [/]
     is_daily_recur <- grepl("-\\s*\\*?(Email|ToDo)\\s*$", ln, ignore.case = TRUE)
-    if (is_daily_recur && status == "/") next  # skip done daily recurring
+    if (is_daily_recur && status == "/") next
 
-    # Reset status to blank for tomorrow
     ln_reset <- sub("\\[/\\]", "[ ]", ln)
-    ln_reset <- sub("\\[x\\]", "[ ]", ln_reset)  # just in case
+    ln_reset <- sub("\\[x\\]", "[ ]", ln_reset)
     copy_lines <- c(copy_lines, ln_reset)
     last_was_task <- TRUE
   }
 
-  # Filter today's section: keep only [/] and [x], remove [ ]
   keep_today <- character()
   for (ln in today_lines) {
     if (!grepl("^\\s*\\[", ln)) {
-      # Keep non-task lines (blanks, etc.)
       keep_today <- c(keep_today, ln)
     } else {
       status <- substr(sub("^\\s*", "", ln), 2, 2)
       if (status %in% c("/", "x", "!")) {
         keep_today <- c(keep_today, ln)
       }
-      # Drop [ ] unchecked items
     }
   }
 
-  # Find the separator line before tomorrow (e.g., #######################################)
   separator_start <- tomorrow_start - 1L
   while (separator_start > today_end && grepl("^\\s*$", lines[separator_start])) {
     separator_start <- separator_start - 1L
   }
-  # separator_start now points to the ### line (or today_end if none)
 
-  # Build new file
   new_lines <- c(
-    lines[1:today_start],            # everything up to and including today header
-    keep_today,                       # filtered today tasks
-    "",                               # blank line
-    lines[separator_start:tomorrow_start],  # separator + blank + tomorrow header
-    "",                               # blank after header
-    copy_lines,                       # copied tasks
-    "",                               # blank line
+    lines[1:today_start],
+    keep_today,
+    "",
+    lines[separator_start:tomorrow_start],
+    "",
+    copy_lines,
+    "",
     if (tomorrow_start < length(lines)) lines[(tomorrow_start + 1L):length(lines)] else character()
   )
 
-  # Remove excess blank lines
-  writeLines(new_lines, daily_file)
-  message("Advanced from ", today_name, " to ", tomorrow_name)
-  invisible(daily_file)
+  targets <- list()
+  targets[[daily_file]] <- new_lines
+  result <- .write_or_preview(targets, preview)
+
+  if (!preview) {
+    message("Advanced from ", today_name, " to ", tomorrow_name)
+    return(invisible(daily_file))
+  }
+  result
 }