feat: add archive_folder support for preserving previous generations

When archive_folder is set in the project config, artifacts are moved to
numbered archive copies (e.g. x.01.jpg, x.02.jpg) instead of being
overwritten or deleted.

- Build command archives existing artifacts before rebuilding dirty targets
- Clean command moves files to archive instead of deleting them
- Subfolder structure is preserved in the archive directory
- State file is always deleted, never archived

hokusai/builder.py

@@ -11,6 +11,7 @@ from pathlib import Path
 
 import httpx
 
+from hokusai.archive import archive_file
 from hokusai.config import DownloadTargetConfig, GenerateTargetConfig, ProjectConfig
 from hokusai.graph import build_graph, get_build_order, get_subgraph_for_target
 from hokusai.prompt import extract_placeholder_files, resolve_prompt
@@ -145,8 +146,14 @@ async def _build_single_target(
     provider_index: dict[str, Provider],
 ) -> None:
     """Build a single target by dispatching to the appropriate provider."""
+    output_path = project_dir / target_name
+
     # Ensure parent directories exist for targets in subfolders.
-    (project_dir / target_name).parent.mkdir(parents=True, exist_ok=True)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Archive the existing artifact before overwriting.
+    if config.archive_folder is not None:
+        _ = archive_file(output_path, project_dir, config.archive_folder)
 
     target_cfg = config.targets[target_name]