✨ feat(fs_write): Add append functionality to fs_write tool (#764)

* ✨ feat(cli): Add append functionality to fs_write tool

This commit enhances the fs_write tool by adding a new "append" command that allows
users to append content to the end of files without having to read and rewrite the
entire file.

## Features
- 📝 Add new `Append` variant to the `FsWrite` enum
- 🔄 Implement functionality to append content to existing files
- 🆕 Auto-create files when appending to non-existent files
- 📁 Auto-create parent directories when needed
- 🧪 Add comprehensive test coverage for the new functionality

## Implementation Details
- Added validation to ensure path and content are not empty
- Enhanced user feedback during append operations
- Implemented syntax highlighting for appended content
- Maintained consistent code patterns with existing commands
- Added proper newline handling to ensure clean appends
- Updated tool_index.json schema to expose the new command

## Use Cases
- Adding new lines to configuration files
- Appending log entries
- Adding new content to the end of text files
- Creating files incrementally

This enhancement improves the user experience by providing a more convenient way to
add content to files without having to read the entire file first and then use the
"create" command to overwrite it.

Resolves: #[issue-number]

* 🔧 Clean up code formatting in fs_write.rs

Standardized code formatting in the fs_write.rs file by:
- Fixing inconsistent indentation
- Removing unnecessary whitespace
- Simplifying multi-line assertions
- Maintaining consistent brace style for struct definitions

No functional changes, purely cosmetic improvements for better code readability.

* 🔄 refactor(fs_write): rename "content" parameter to "new_str" in append command

Standardized parameter naming across all fs_write commands by renaming the "content" parameter to "new_str" in the append command to maintain consistency with other commands. Also removed automatic newline insertion when appending content to files, giving more control to the caller.

* ✨ fix: Improve file append behavior with automatic newline handling

- Added logic to automatically insert newlines when appending content to files
- Updated fs_write tool description to document the new behavior
- Fixed test case to properly validate the newline insertion behavior

This change resolves the pain point of getting whitespace right when appending content to files, ensuring consistent behavior regardless of whether the existing file ends with a newline or the new content starts with one.

* Change append behavior to fail when file doesn't exist

* Update fs_write tool description to match new append behavior

* 🧹 chore: remove commented-out test code in fs_write tool

Removed obsolete commented-out test code that was no longer valid after changing the behavior to not create files when appending. This improves code readability and maintenance by eliminating dead code that was already noted as "no longer valid".

Author: jsamuel1

crates/q_cli/src/cli/chat/tools/fs_write.rs

@@ -45,6 +45,8 @@ pub enum FsWrite {
         insert_line: usize,
         new_str: String,
     },
+    #[serde(rename = "append")]
+    Append { path: String, new_str: String },
 }
 
 impl FsWrite {
@@ -121,6 +123,38 @@ impl FsWrite {
                 fs.write(&path, &file).await?;
                 Ok(Default::default())
             },
+            FsWrite::Append { path, new_str } => {
+                let path = sanitize_path_tool_arg(ctx, path);
+
+                // Return an error if the file doesn't exist
+                if !fs.exists(&path) {
+                    bail!("The file does not exist: {}", path.display());
+                }
+
+                queue!(
+                    updates,
+                    style::Print("Appending to: "),
+                    style::SetForegroundColor(Color::Green),
+                    style::Print(format_path(cwd, &path)),
+                    style::ResetColor,
+                    style::Print("\n"),
+                )?;
+
+                // Read existing content
+                let mut file_content = fs.read_to_string(&path).await.unwrap_or_default();
+
+                // Check if we need to add a newline before appending
+                // Only add a newline if the file is not empty and doesn't already end with one
+                // Also don't add a newline if the new content starts with one
+                if !file_content.is_empty() && !file_content.ends_with('\n') && !new_str.starts_with('\n') {
+                    file_content.push('\n');
+                }
+
+                // Append the new content
+                file_content.push_str(new_str);
+                fs.write(&path, file_content).await?;
+                Ok(Default::default())
+            },
         }
     }
 
@@ -210,6 +244,21 @@ impl FsWrite {
                 )?;
                 Ok(())
             },
+            FsWrite::Append { path, new_str } => {
+                let relative_path = format_path(cwd, path);
+                let file = stylize_output_if_able(ctx, &relative_path, new_str, None, Some("+"));
+                queue!(
+                    updates,
+                    style::Print("Path: "),
+                    style::SetForegroundColor(Color::Green),
+                    style::Print(relative_path),
+                    style::ResetColor,
+                    style::Print("\n\nAppending content:\n"),
+                    style::Print(file),
+                    style::ResetColor,
+                )?;
+                Ok(())
+            },
         }
     }
 
@@ -226,6 +275,14 @@ impl FsWrite {
                     bail!("The provided path must exist in order to replace or insert contents into it")
                 }
             },
+            FsWrite::Append { path, new_str } => {
+                if path.is_empty() {
+                    bail!("Path must not be empty")
+                };
+                if new_str.is_empty() {
+                    bail!("Content to append must not be empty")
+                };
+            },
         }
 
         Ok(())
@@ -350,6 +407,15 @@ mod tests {
         });
         let fw = serde_json::from_value::<FsWrite>(v).unwrap();
         assert!(matches!(fw, FsWrite::Insert { .. }));
+
+        // append
+        let v = serde_json::json!({
+            "path": path,
+            "command": "append",
+            "new_str": "appended content",
+        });
+        let fw = serde_json::from_value::<FsWrite>(v).unwrap();
+        assert!(matches!(fw, FsWrite::Append { .. }));
     }
 
     #[tokio::test]
@@ -565,6 +631,49 @@ mod tests {
         assert_eq!(actual, format!("{}{}{}", new_str, test_file_contents, new_str),);
     }
 
+    #[tokio::test]
+    async fn test_fs_write_tool_append() {
+        let ctx = setup_test_directory().await;
+        let mut stdout = std::io::stdout();
+
+        // Test appending to existing file
+        let content_to_append = "\n5: Appended line";
+        let v = serde_json::json!({
+            "path": TEST_FILE_PATH,
+            "command": "append",
+            "new_str": content_to_append,
+        });
+
+        serde_json::from_value::<FsWrite>(v)
+            .unwrap()
+            .invoke(&ctx, &mut stdout)
+            .await
+            .unwrap();
+
+        let actual = ctx.fs().read_to_string(TEST_FILE_PATH).await.unwrap();
+        assert_eq!(
+            actual,
+            format!("{}{}", TEST_FILE_CONTENTS, content_to_append),
+            "Content should be appended to the end of the file"
+        );
+
+        // Test appending to non-existent file (should fail)
+        let new_file_path = "/new_append_file.txt";
+        let content = "This is a new file created by append";
+        let v = serde_json::json!({
+            "path": new_file_path,
+            "command": "append",
+            "new_str": content,
+        });
+
+        let result = serde_json::from_value::<FsWrite>(v)
+            .unwrap()
+            .invoke(&ctx, &mut stdout)
+            .await;
+
+        assert!(result.is_err(), "Appending to non-existent file should fail");
+    }
+
     #[test]
     fn test_truncate_str() {
         let s = "Hello, world!";

crates/q_cli/src/cli/chat/tools/tool_index.json

@@ -36,14 +36,14 @@
   },
   "fs_write": {
     "name": "fs_write",
-    "description": "A tool for creating and editing files\n * The `create` command will override the file at `path` if it already exists as a file, and otherwise create a new file\n * Please prefer creating smaller files even when asked otherwise as large file creations are likely to fail.\n Notes for using the `str_replace` command:\n * The `old_str` parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!\n * If the `old_str` parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in `old_str` to make it unique\n * The `new_str` parameter should contain the edited lines that should replace the `old_str`.",
+    "description": "A tool for creating and editing files\n * The `create` command will override the file at `path` if it already exists as a file, and otherwise create a new file\n * The `append` command will add content to the end of an existing file, automatically adding a newline if the file doesn't end with one. The file must exist.\n Notes for using the `str_replace` command:\n * The `old_str` parameter should match EXACTLY one or more consecutive lines from the original file. Be mindful of whitespaces!\n * If the `old_str` parameter is not unique in the file, the replacement will not be performed. Make sure to include enough context in `old_str` to make it unique\n * The `new_str` parameter should contain the edited lines that should replace the `old_str`.",
     "input_schema": {
       "type": "object",
       "properties": {
         "command": {
           "type": "string",
-          "enum": ["create", "str_replace", "insert"],
-          "description": "The commands to run. Allowed options are: `create`, `str_replace`, `insert`."
+          "enum": ["create", "str_replace", "insert", "append"],
+          "description": "The commands to run. Allowed options are: `create`, `str_replace`, `insert`, `append`."
         },
         "file_text": {
           "description": "Required parameter of `create` command, with the content of the file to be created.",
@@ -54,7 +54,7 @@
           "type": "integer"
         },
         "new_str": {
-          "description": "Required parameter of `str_replace` command containing the new string. Required parameter of `insert` command containing the string to insert.",
+          "description": "Required parameter of `str_replace` command containing the new string. Required parameter of `insert` command containing the string to insert. Required parameter of `append` command containing the content to append to the file.",
           "type": "string"
         },
         "old_str": {