feat: add support for appending and prepending file content

This commit introduces two new file manipulation actions: "Append File" and "Prepend File". Users can now define these actions in their markdown input to add content to the end or beginning of specified files.

Key features and changes:
- **New Headers:** Recognizes `## Append File: <path>` / `**Append File: <path>**` and `## Prepend File: <path>` / `**Prepend File: <path>**`. These headers must be followed by a code block containing the content to append or prepend.
- **File Creation:** If the target file for an append or prepend action does not exist, it will be created with the specified content.
- **Parser Updates:**
    - `ActionType` enum extended with `Append` and `Prepend`.
    - Header parsing logic (`header_utils.rs`, `external_header.rs`, `internal_standard_handler.rs`, `wrapped_header.rs`) updated to recognize and process these new action types.
    - `constants.rs` updated with new action keywords.
- **Processor Implementation:**
    - New modules `src/processor/append.rs` and `src/processor/prepend.rs` implement the core logic.
    - `action_handler.rs` dispatches to these new handlers.
    - Error handling (`errors.rs`) includes new variants for append/prepend to a directory (`TargetIsDirectoryForAppend`, `TargetIsDirectoryForPrepend`).
- **Core Types & Summary:**
    - `Summary` struct in `core_types.rs` now includes fields for `appended`, `prepended`, `failed_isdir_append`, and `failed_isdir_prepend`.
    - New status enums `AppendStatus` and `PrependStatus` introduced.
    - CLI output (`cli/output.rs`) and summary updating logic (`processor/summary_updater.rs`) reflect these additions.
- **Documentation:** `README.md` updated to document the new actions, their syntax, and examples.
- **Testing:** Comprehensive integration tests added for parsing, processing, and CLI usage of append/prepend actions, including interactions with other actions and error scenarios.

This enhancement provides more granular control over file content generation, allowing users to build up files incrementally.

Author: Romelium

README.md

@@ -6,17 +6,19 @@
 * **Documentation:** Document file structures and provide their content within a single markdown file.
 * **Reproducible Setups:** Define file layouts declaratively.
 
-The tool reads a markdown file, identifies actions (like creating, deleting, or moving files) based on specific header formats, and executes these actions relative to a specified output directory.
+The tool reads a markdown file, identifies actions (like creating, appending, prepending, deleting, or moving files) based on specific header formats, and executes these actions relative to a specified output directory.
 
 ## Features
 
 * Supports creating files with content defined in code blocks.
+* Supports appending content to existing files (creates if not exists).
+* Supports prepending content to existing files (creates if not exists).
 * Supports deleting files.
 * Supports moving files.
 * Multiple header formats for defining actions (Markdown headers, backticks, internal comments).
 * "Wrapped" header format for associating headers with subsequent code blocks or for standalone delete/move actions.
-* Automatic creation of parent directories for created or moved files.
-* Safety checks to prevent writing or moving outside the target base directory.
+* Automatic creation of parent directories for created, appended, prepended or moved files.
+* Safety checks to prevent writing or moving files outside the target base directory.
 * Option to force overwriting existing files (for create and move actions).
 * Detailed summary output of actions performed, skipped, or failed.
 * Pre-commit hooks configured for code quality and consistency.
@@ -67,7 +69,7 @@ strux [OPTIONS] <MARKDOWN_FILE>
   * **Default:** `./project-generated`. This path is relative to the **current working directory** where you run the command.
   * The directory will be created if it doesn't exist.
   * The command will fail if the specified path exists but is not a directory.
-* `-f`, `--force`: Overwrite existing files when a `File` or `Moved File` action targets a path that already exists as a file. Without this flag, existing files will be skipped. This flag does not allow replacing a directory with a file.
+* `-f`, `--force`: Overwrite existing files when a `File` or `Moved File` action targets a path that already exists as a file. Without this flag, existing files will be skipped. This flag does not allow replacing a directory with a file. It does not currently affect `Append File` or `Prepend File` actions beyond their standard behavior (they will operate on existing files or create new ones).
 * `-h`, `--help`: Print help information.
 * `-V`, `--version`: Print version information.
 
@@ -104,7 +106,43 @@ fn main() {
 ```
 ````
 
-**2. `Deleted File` Actions:**
+**2. `Append File` Actions:**
+
+These headers must be immediately followed by a fenced code block. The content of the code block will be appended to the specified file. If the file does not exist, it will be created with the content.
+
+* **Markdown Headers:**
+  * `## Append File: path/to/your/file.txt`
+  * `**Append File: path/to/your/file.txt**`
+
+**Example (Append Header):**
+
+````markdown
+## Append File: logs/app.log
+
+```
+[INFO] Application started.
+```
+````
+
+**3. `Prepend File` Actions:**
+
+These headers must be immediately followed by a fenced code block. The content of the code block will be prepended to the specified file. If the file does not exist, it will be created with the content.
+
+* **Markdown Headers:**
+  * `## Prepend File: path/to/your/file.txt`
+  * `**Prepend File: path/to/your/file.txt**`
+
+**Example (Prepend Header):**
+
+````markdown
+## Prepend File: config.ini
+
+```ini
+; Generated by Strux
+```
+````
+
+**4. `Deleted File` Actions:**
 
 These headers define files to be deleted. They should *not* be followed by a code block unless using the special case below.
 
@@ -122,7 +160,7 @@ path/inside/block_to_delete.tmp
 ```
 ````
 
-**3. `Moved File` Actions:**
+**5. `Moved File` Actions:**
 
 These headers define files to be moved. They should *not* be followed by a code block. The keyword " to " (case-sensitive, with spaces) separates the source and destination paths.
 
@@ -138,9 +176,10 @@ These headers define files to be moved. They should *not* be followed by a code
 ## Moved File: temp/report.docx to final/official_report.docx
 ````
 
-**4. Internal Comment Headers (Inside Code Blocks for `File` actions):**
+**6. Internal Comment Headers (Inside Code Blocks for `File`, `Append File`, `Prepend File` actions):**
 
-These headers can appear on the *first line* inside a code block to define the file path for a `File` action.
+These headers can appear on the *first line* inside a code block to define the file path for a `File`, `Append File`, or `Prepend File` action.
+*Supported types: `File` (e.g., `// File: path/to/file.ext`). Support for `Append File` and `Prepend File` in this format may be added in the future.*
 
 * `// File: path/to/file.ext`: The header line itself is **excluded** from the file content. Supports paths in backticks (`// File:\`path with spaces.txt\``).
 
@@ -161,10 +200,10 @@ These headers can appear on the *first line* inside a code block to define the f
 
     *Heuristics apply to avoid misinterpreting comments as paths.*
 
-**5. Wrapped Headers:**
+**7. Wrapped Headers:**
 
 A header can be placed inside a ` ```markdown ` or ` ```md ` block.
-* For `File` actions, it applies to the *next adjacent* code block.
+* For `File`, `Append File`, or `Prepend File` actions, it applies to the *next adjacent* code block.
 * For `Deleted File` or `Moved File` actions, it's a standalone action.
 
 * **Create Example:**
@@ -180,6 +219,17 @@ A header can be placed inside a ` ```markdown ` or ` ```md ` block.
       feature_a: true
     ```
     ````
+* **Append Example:**
+
+    ````markdown
+    ```markdown
+    ## Append File: notes.txt
+    ```
+
+    ```
+    Another note.
+    ```
+    ````
 
 * **Delete Example:**
 
@@ -201,14 +251,14 @@ A header can be placed inside a ` ```markdown ` or ` ```md ` block.
 ### Path Handling and Safety
 
 * Paths specified in headers are treated as relative to the `--output-dir`.
-* Parent directories are created automatically as needed for `File` actions and for the destination of `Moved File` actions.
+* Parent directories are created automatically as needed for `File`, `Append File`, `Prepend File` actions and for the destination of `Moved File` actions.
 * **Safety:** The tool prevents writing or moving files outside the resolved base output directory. Paths containing `..` that would escape the base directory will cause the action to fail safely.
 * Paths containing invalid components (like `//` or trailing `/`) will be skipped.
 
-### Content Handling (for `File` actions)
+### Content Handling (for `File`, `Append File`, `Prepend File` actions)
 
-* The *entire* content within the fenced code block (excluding the fences themselves and certain internal headers) is written to the file.
-* A trailing newline (`\n`) is added to the file content if it doesn't already end with one.
+* The *entire* content within the fenced code block (excluding the fences themselves and certain internal headers) is written to the file (or appended/prepended).
+* A trailing newline (`\n`) is added to this content chunk if it doesn't already end with one.
 
 ## Examples
 
@@ -246,6 +296,11 @@ Generated by Strux.
 
 ## Moved File: temp/draft.txt to docs/final_draft.txt
 
+## Append File: README.md
+```
+This content will be appended.
+```
+
 ```md
 ## Deleted File: temp/to_delete.log
 ```
@@ -270,7 +325,7 @@ strux -o my_project example.md
 ```plaintext
 my_project/
 ├── .gitignore
-├── README.md
+├── README.md  # Content: "# My Project\nGenerated by Strux.\nThis content will be appended.\n"
 ├── docs/
 │   └── final_draft.txt  # Moved from temp/draft.txt
 └── src/
@@ -279,7 +334,7 @@ my_project/
 ```
 
 * `my_project/src/main.py` and `my_project/src/utils.py` contain their Python code.
-* `my_project/README.md` contains its content.
+* `my_project/README.md` contains its original content plus the appended text.
 * `my_project/.gitignore` contains its content.
 * `my_project/docs/final_draft.txt` contains "This is a draft file that will be moved.\n" (moved from `my_project/temp/draft.txt`).
 * The original `my_project/temp/draft.txt` is gone as it was moved.

src/cli/output.rs

@@ -15,6 +15,11 @@ pub fn print_summary(summary: &Summary, resolved_base: &Path) {
         "  Files overwritten (--force):        {}",
         summary.overwritten
     );
+    println!("  Files appended:                     {}", summary.appended); // New
+    println!(
+        "  Files prepended:                    {}",
+        summary.prepended
+    ); // New
     println!("  Files deleted:                      {}", summary.deleted);
     println!("  Files moved:                        {}", summary.moved);
     println!(
@@ -63,6 +68,14 @@ pub fn print_summary(summary: &Summary, resolved_base: &Path) {
         "  Failed (create, target is dir):     {}",
         summary.failed_isdir_create
     );
+    println!(
+        "  Failed (append, target is dir):     {}", // New
+        summary.failed_isdir_append
+    );
+    println!(
+        "  Failed (prepend, target is dir):    {}", // New
+        summary.failed_isdir_prepend
+    );
     println!(
         "  Failed (create, parent is file):    {}",
         summary.failed_parent_isdir

src/constants.rs

@@ -6,19 +6,28 @@ use regex; // Needed for regex::escape
 // --- Action Keywords ---
 pub const ACTION_FILE: &str = "File";
 pub const ACTION_DELETED_FILE: &str = "Deleted File";
-pub const ACTION_MOVED_FILE: &str = "Moved File"; // New action
+pub const ACTION_MOVED_FILE: &str = "Moved File";
+pub const ACTION_APPEND_FILE: &str = "Append File"; // New action
+pub const ACTION_PREPEND_FILE: &str = "Prepend File"; // New action
 
 // --- Parsing ---
 pub const INTERNAL_COMMENT_ACTION_PREFIX: &str = "// File:";
+// Consider if we need // Append File: or // Prepend File: prefixes later. For now, stick to File.
 
 // Helper to build the VALID_ACTIONS_REGEX string component once.
 // This is used by the regex definition in `parser::regex`.
 pub static VALID_ACTIONS_REGEX_STR: Lazy<String> = Lazy::new(|| {
-    [ACTION_FILE, ACTION_DELETED_FILE, ACTION_MOVED_FILE] // Added ACTION_MOVED_FILE
-        .iter()
-        .map(|a| regex::escape(a))
-        .collect::<Vec<_>>()
-        .join("|")
+    [
+        ACTION_FILE,
+        ACTION_DELETED_FILE,
+        ACTION_MOVED_FILE,
+        ACTION_APPEND_FILE,  // Added
+        ACTION_PREPEND_FILE, // Added
+    ]
+    .iter()
+    .map(|a| regex::escape(a))
+    .collect::<Vec<_>>()
+    .join("|")
 });
 
 // Note: Regex objects themselves are defined in `src/parser/regex.rs`

src/core_types.rs

@@ -9,15 +9,17 @@
 pub enum ActionType {
     Create,
     Delete,
-    Move, // New action type
+    Move,
+    Append,  // New action type
+    Prepend, // New action type
 }
 
 #[derive(Debug, Clone)]
 pub struct Action {
     pub action_type: ActionType,
-    pub path: String, // Source path for Move, target path for Create/Delete
+    pub path: String, // Source path for Move, target path for Create/Delete/Append/Prepend
     pub dest_path: Option<String>, // Destination path for Move
-    pub content: Option<String>, // Content for Create
+    pub content: Option<String>, // Content for Create/Append/Prepend
     pub original_pos: usize, // Byte offset in original markdown content
 }
 
@@ -26,20 +28,24 @@ pub struct Summary {
     pub created: u32,
     pub overwritten: u32,
     pub deleted: u32,
-    pub moved: u32,             // New summary field
-    pub moved_overwritten: u32, // New summary field
+    pub moved: u32,
+    pub moved_overwritten: u32,
+    pub appended: u32,  // New summary field
+    pub prepended: u32, // New summary field
     pub skipped_exists: u32,
     pub skipped_not_found: u32,
     pub skipped_isdir_delete: u32,
     pub skipped_other_type: u32,
-    pub skipped_move_src_not_found: u32, // New summary field
-    pub skipped_move_src_is_dir: u32,    // New summary field
-    pub skipped_move_dst_exists: u32,    // New summary field
-    pub skipped_move_dst_isdir: u32,     // New summary field
+    pub skipped_move_src_not_found: u32,
+    pub skipped_move_src_is_dir: u32,
+    pub skipped_move_dst_exists: u32,
+    pub skipped_move_dst_isdir: u32,
     pub failed_io: u32,
     pub failed_isdir_create: u32,
     pub failed_parent_isdir: u32,
     pub failed_unsafe: u32,
+    pub failed_isdir_append: u32,  // New summary field
+    pub failed_isdir_prepend: u32, // New summary field
     pub error_other: u32,
 }
 
@@ -62,9 +68,21 @@ pub enum DeleteStatus {
 #[derive(Debug, PartialEq, Eq)]
 pub enum MoveStatus {
     Moved,
-    MovedOverwritten, // When --force is used and destination file is overwritten
+    MovedOverwritten,
     SkippedSourceNotFound,
     SkippedSourceIsDir,
-    SkippedDestinationExists, // When destination file exists and --force is not used
-    SkippedDestinationIsDir,  // When destination path is an existing directory
+    SkippedDestinationExists,
+    SkippedDestinationIsDir,
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum AppendStatus {
+    Appended, // Content was appended to an existing file
+    Created,  // File did not exist, so it was created with the content
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub enum PrependStatus {
+    Prepended, // Content was prepended to an existing file
+    Created,   // File did not exist, so it was created with the content
 }

src/errors.rs

@@ -56,14 +56,16 @@ pub enum ProcessError {
     InvalidPathFormat { path: String },
     #[error("Cannot perform operation. Target path '{path}' exists and is a directory.")]
     TargetIsDirectory { path: PathBuf },
-    // #[error("Cannot perform operation. Target path '{path}' is not a file.")]
-    // TargetIsNotFile { path: PathBuf }, // Potentially for move source if not a file
     #[error(
         "Cannot create file '{path}'. Parent path '{parent_path}' exists but is not a directory."
     )]
     ParentIsNotDirectory { path: PathBuf, parent_path: PathBuf },
     #[error("Cannot move. Source path '{path}' is a directory, not a file.")]
-    MoveSourceIsDir { path: PathBuf }, // New error for Move
+    MoveSourceIsDir { path: PathBuf },
+    #[error("Cannot append to path '{path}' because it exists and is a directory.")]
+    TargetIsDirectoryForAppend { path: PathBuf }, // New error for Append
+    #[error("Cannot prepend to path '{path}' because it exists and is a directory.")]
+    TargetIsDirectoryForPrepend { path: PathBuf }, // New error for Prepend
     #[error("Unknown action type encountered")]
     UnknownAction, // Should not happen if parsing is correct
     #[error("Unexpected internal error: {0}")]

src/lib.rs

@@ -12,7 +12,10 @@ pub mod processor;
 // Re-export essential types/functions for easier use by the binary crate (main.rs)
 // or potentially other consumers of this library.
 pub use constants::*;
-pub use core_types::{Action, ActionType, CreateStatus, DeleteStatus, MoveStatus, Summary}; // Added MoveStatus
+pub use core_types::{
+    Action, ActionType, AppendStatus, CreateStatus, DeleteStatus, MoveStatus, PrependStatus,
+    Summary,
+}; // Added AppendStatus, PrependStatus
 pub use errors::{AppError, ParseError, ProcessError};
 pub use parser::parse_markdown;
 pub use processor::process_actions;

src/parser/header_utils.rs

@@ -1,13 +1,15 @@
 //! Utilities for parsing markdown header lines (e.g., **Action: path**).
 
-use crate::constants::{ACTION_DELETED_FILE, ACTION_FILE, ACTION_MOVED_FILE};
+use crate::constants::{
+    ACTION_APPEND_FILE, ACTION_DELETED_FILE, ACTION_FILE, ACTION_MOVED_FILE, ACTION_PREPEND_FILE,
+}; // Added new actions
 use crate::core_types::ActionType;
 use regex::Captures;
 
 /// Represents the details extracted from a header line.
 pub(crate) struct ParsedHeaderAction {
     pub action_word: String,
-    pub path: String, // Source path for Move, target path for File/Delete
+    pub path: String, // Source path for Move, target path for File/Delete/Append/Prepend
     pub dest_path: Option<String>, // Destination path for Move
 }
 
@@ -62,7 +64,8 @@ pub(crate) fn extract_header_action_details(caps: &Captures) -> Option<ParsedHea
                     None // Failed to parse "source to dest"
                 }
             } else {
-                // For ACTION_FILE (including backtick-only cases) and ACTION_DELETED_FILE
+                // For ACTION_FILE (including backtick-only cases), ACTION_DELETED_FILE,
+                // ACTION_APPEND_FILE, ACTION_PREPEND_FILE
                 if let Some(path) = parse_single_path_from_content(&raw_content) {
                     if is_path_valid_for_action(&path) {
                         Some(ParsedHeaderAction {
@@ -103,7 +106,8 @@ fn is_path_valid_for_action(path_str: &str) -> bool {
 }
 
 /// Parses a single path from a content string (which might include backticks or trailing comments).
-/// Used for "File:" and "Deleted File:" actions, and for backtick-only path headers.
+/// Used for "File:", "Deleted File:", "Append File:", "Prepend File:" actions,
+/// and for backtick-only path headers.
 fn parse_single_path_from_content(raw_content: &str) -> Option<String> {
     let trimmed_content = raw_content.trim();
 
@@ -198,7 +202,9 @@ pub(crate) fn get_action_type(action_word: &str) -> Option<ActionType> {
     match action_word {
         ACTION_FILE => Some(ActionType::Create),
         ACTION_DELETED_FILE => Some(ActionType::Delete),
-        ACTION_MOVED_FILE => Some(ActionType::Move), // New mapping
+        ACTION_MOVED_FILE => Some(ActionType::Move),
+        ACTION_APPEND_FILE => Some(ActionType::Append), // New mapping
+        ACTION_PREPEND_FILE => Some(ActionType::Prepend), // New mapping
         _ => None,
     }
 }