Doc system test

Created folder cleanup

A headless create that stops before done removes exactly the folders it created, so a pending question leaves the disk as it was.

Meta block front matter of this doc
namespaces
  • durian.cloud/cyanprint/project-lifecycle
  • durian.cloud/cyanprint/prompting
type
guard
code
  • sulfone.iridium/cyanprint/src/run.rs

The problem. A headless run is a loop driven by a script: run, get a question back, run again with one more answer. Each run that stops on a question must leave no trace, or the next run sees a half-made folder.

The rule this guard keeps. Until a headless run reaches done, the filesystem is exactly as it was: any folder this run created (including empty parents of a nested path) is removed; a folder that already existed is never touched.

The picture shows the guard's two states.

stateDiagram-v2
  [*] --> Armed: create_dir_all(target)
  Armed --> Removed: any return before done (question pending, error), headless
  Armed --> Kept: need_input check passed (disarm)
  Armed --> Kept: interactive run (guard is inert)
  Removed --> [*]
  Kept --> [*]
The created-folder guard

How it works

  1. Before creating the target folder, find the shallowest part of its path that does not exist yet (for ./a/b/c with only . existing, that is ./a).
  2. Create the folder, then arm a guard holding that path.
  3. Every early return (an invalid template, a batch error, a pending question) drops the guard while armed; a headless guard then removes that one folder tree.
  4. Once the run passes the pending-question check, the guard is disarmed and the folder is kept, even if a later step (state save, commands) fails.

Here is the real code.

sulfone.iridiumcyanprint/src/run.rs
  1. lines 359-366The shallowest missing ancestor: removing it undoes the whole create_dir_all.
    cyanprint/src/run.rs:359-366rust
    fn shallowest_uncreated_ancestor(target_dir: &Path) -> Option<PathBuf> {
    target_dir
    .ancestors()
    .filter(|a| !a.as_os_str().is_empty())
    .filter(|a| !a.exists())
    .last()
    .map(|p| p.to_path_buf())
    }
  2. lines 396-425The guard: removes only when headless and still armed.
    cyanprint/src/run.rs:396-425rust
    struct CreatedDirGuard {
    first_created_dir: Option<PathBuf>,
    headless: bool,
    armed: bool,
    }
    impl CreatedDirGuard {
    fn new(first_created_dir: Option<PathBuf>, headless: bool) -> Self {
    Self {
    first_created_dir,
    headless,
    armed: true,
    }
    }
    /// Mark the run as committed to its output so dropping the guard no longer removes the
    /// created directory. Called once the `need_input` check has passed and the happy path
    /// is about to persist state / write files.
    fn disarm(&mut self) {
    self.armed = false;
    }
    }
    impl Drop for CreatedDirGuard {
    fn drop(&mut self) {
    if self.headless && self.armed {
    remove_created_dir(&self.first_created_dir);
    }
    }
    }
  3. lines 524-532Armed right after the folder is created.
    cyanprint/src/run.rs:524-532rust
    let first_created_dir = shallowest_uncreated_ancestor(target_dir);
    fs::create_dir_all(target_dir).map_err(|e| Box::new(e) as Box<dyn Error + Send>)?;
    // Arm the directory guard immediately after creation: ANY return before the run is
    // committed to writing output (a pre-batch early return, a batch error, or a pending
    // `need_input`) drops the guard while armed and removes exactly the tree this
    // invocation created, leaving the filesystem as it was found. Disarmed once the
    // `need_input` check passes (the `done` path then keeps its output). Inert when
    // interactive, so that path is unchanged.
    let mut dir_guard = CreatedDirGuard::new(first_created_dir, headless);
  4. lines 834-843A pending question returns while armed (removed); otherwise disarm.
    cyanprint/src/run.rs:834-843rust
    if let Some(question) = need_input {
    return Ok(CyanRunResult {
    session_ids,
    need_input: Some(question),
    });
    }
    // Past the `need_input` check the run is committed to producing output (`done`):
    // disarm the directory guard so the created tree is kept from here on.
    dir_guard.disarm();

Worked example

On a machine with no cache entries for web:5 (or with --no-output-cache): cyanprint create atomi/web:5 ./blog/site --headless with no answers, where ./blog does not exist: the run creates ./blog/site, reaches docker:7's node_version question, prints a need_input envelope and removes ./blog. The next call with node_version answered starts from the same empty disk. On the shop machine with the cache on, the same command never stops: every node hits the cache and the run ends done with shop's answers (the node cache problem).

Hard cases

  • After done is decided, nothing is undone. A failing post-template command leaves the written files and state.
  • An existing folder is never removed, even if the run wrote nothing.
  • Interactive runs never remove anything.