5 files changed, 616 insertions, 0 deletions
diff --git a/tests/test-gptel-tools-list-directory-files.el b/tests/test-gptel-tools-list-directory-files.el
new file mode 100644
index 00000000..a91a7e79
--- /dev/null
+++ b/tests/test-gptel-tools-list-directory-files.el
@@ -0,0 +1,162 @@
+;;; test-gptel-tools-list-directory-files.el --- Tests for list_directory_files -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for the helpers in list_directory_files.el.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+  (add-to-list 'load-path (expand-file-name "gptel-tools" user-emacs-directory))
+  (setq load-prefer-newer t)
+  (unless (featurep 'gptel)
+    (defvar gptel-tools nil)
+    (defun gptel-make-tool (&rest _args) nil)
+    (defun gptel-get-tool (&rest _args) nil)
+    (provide 'gptel)))
+
+(require 'list_directory_files)
+
+;; -------------------------- helpers
+
+(defun test-gptel-tools-list--with-tree (fn)
+  "Create a small directory tree, call FN with its root, clean up."
+  (let ((root (make-temp-file "test-gptel-tools-list-" t)))
+    (unwind-protect
+        (progn
+          (with-temp-file (expand-file-name "a.txt" root) (insert "a"))
+          (with-temp-file (expand-file-name "b.org" root) (insert "b"))
+          (make-directory (expand-file-name "sub" root))
+          (with-temp-file (expand-file-name "sub/c.txt" root) (insert "c"))
+          (funcall fn root))
+      (delete-directory root t))))
+
+;; -------------------------- mode-to-permissions
+
+(ert-deftest test-gptel-tools-list-mode-to-permissions-regular-file ()
+  "Mode 0644 on a regular file: -rw-r--r--."
+  (should (equal (list-directory-files--mode-to-permissions #o0644)
+                 "-rw-r--r--")))
+
+(ert-deftest test-gptel-tools-list-mode-to-permissions-directory ()
+  "Mode 0755 + dir bit: drwxr-xr-x."
+  (should (equal (list-directory-files--mode-to-permissions
+                  (logior #o40000 #o0755))
+                 "drwxr-xr-x")))
+
+(ert-deftest test-gptel-tools-list-mode-to-permissions-executable ()
+  "Mode 0700: -rwx------."
+  (should (equal (list-directory-files--mode-to-permissions #o0700)
+                 "-rwx------")))
+
+;; -------------------------- get-file-info
+
+(ert-deftest test-gptel-tools-list-get-file-info-success ()
+  "Success: returns a plist with :success t and metadata."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let ((info (list-directory-files--get-file-info
+                  (expand-file-name "a.txt" root))))
+       (should (plist-get info :success))
+       (should (numberp (plist-get info :size)))
+       (should (stringp (plist-get info :permissions)))))))
+
+(ert-deftest test-gptel-tools-list-get-file-info-directory ()
+  "Directory info: :is-directory is t."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let ((info (list-directory-files--get-file-info
+                  (expand-file-name "sub" root))))
+       (should (plist-get info :is-directory))))))
+
+;; -------------------------- filter-by-extension
+
+(ert-deftest test-gptel-tools-list-filter-by-extension-keeps-match ()
+  "Filter for txt keeps txt files."
+  (let* ((filter (list-directory-files--filter-by-extension "txt"))
+         (info '(:success t :path "/x/foo.txt" :is-directory nil)))
+    (should (funcall filter info))))
+
+(ert-deftest test-gptel-tools-list-filter-by-extension-drops-non-match ()
+  "Filter for txt drops non-txt files."
+  (let* ((filter (list-directory-files--filter-by-extension "txt"))
+         (info '(:success t :path "/x/foo.org" :is-directory nil)))
+    (should-not (funcall filter info))))
+
+(ert-deftest test-gptel-tools-list-filter-by-extension-always-keeps-directories ()
+  "Filter keeps directories regardless of extension."
+  (let* ((filter (list-directory-files--filter-by-extension "txt"))
+         (info '(:success t :path "/x/sub" :is-directory t)))
+    (should (funcall filter info))))
+
+(ert-deftest test-gptel-tools-list-filter-by-extension-no-extension-is-nil ()
+  "No extension produces a nil filter (i.e. no filtering)."
+  (should-not (list-directory-files--filter-by-extension nil)))
+
+;; -------------------------- format-file-entry
+
+(ert-deftest test-gptel-tools-list-format-file-entry-shape ()
+  "Formatted entry contains permissions, size, mtime, and relative path."
+  (let* ((info (list (cons :path "/home/u/foo.txt")
+                     (cons :permissions "-rw-r--r--")
+                     (cons :executable nil)
+                     (cons :size 42)
+                     (cons :last-modified (current-time))))
+         ;; Build as plist by flattening the cons list.
+         (info-plist (cl-loop for (k . v) in info append (list k v)))
+         (out (list-directory-files--format-file-entry info-plist "/home/u")))
+    (should (string-match-p "-rw-r--r--" out))
+    (should (string-match-p "foo.txt" out))))
+
+;; -------------------------- list-directory
+
+(ert-deftest test-gptel-tools-list-list-directory-flat ()
+  "Non-recursive listing returns only entries in the top level."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let* ((result (list-directory-files--list-directory root nil nil))
+            (files (plist-get result :files)))
+       (should files)
+       (let ((paths (mapcar (lambda (i) (plist-get i :path)) files)))
+         (should (cl-some (lambda (p) (string-match-p "/a\\.txt\\'" p)) paths))
+         (should-not (cl-some (lambda (p) (string-match-p "/c\\.txt\\'" p)) paths)))))))
+
+(ert-deftest test-gptel-tools-list-list-directory-recursive ()
+  "Recursive listing also returns sub-directory contents."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let* ((result (list-directory-files--list-directory root t nil))
+            (files (plist-get result :files))
+            (paths (mapcar (lambda (i) (plist-get i :path)) files)))
+       (should (cl-some (lambda (p) (string-match-p "/c\\.txt\\'" p)) paths))))))
+
+(ert-deftest test-gptel-tools-list-list-directory-error-not-a-directory ()
+  "Non-directory path returns errors entry."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let* ((result (list-directory-files--list-directory
+                     (expand-file-name "a.txt" root) nil nil))
+            (errors (plist-get result :errors)))
+       (should errors)))))
+
+;; -------------------------- format-output
+
+(ert-deftest test-gptel-tools-list-format-output-has-files-section ()
+  "Format-output includes a \"Found N file(s)\" line when files present."
+  (test-gptel-tools-list--with-tree
+   (lambda (root)
+     (let* ((result (list-directory-files--list-directory root nil nil))
+            (out (list-directory-files--format-output root result)))
+       (should (string-match-p "Found [0-9]+ file" out))))))
+
+(ert-deftest test-gptel-tools-list-format-output-empty ()
+  "Empty result: \"No files found\"."
+  (let ((out (list-directory-files--format-output
+              "/nowhere" '(:files nil :errors nil))))
+    (should (string-match-p "No files found" out))))
+
+(provide 'test-gptel-tools-list-directory-files)
+;;; test-gptel-tools-list-directory-files.el ends here
diff --git a/tests/test-gptel-tools-move-to-trash.el b/tests/test-gptel-tools-move-to-trash.el
new file mode 100644
index 00000000..a6ab1200
--- /dev/null
+++ b/tests/test-gptel-tools-move-to-trash.el
@@ -0,0 +1,136 @@
+;;; test-gptel-tools-move-to-trash.el --- Tests for move_to_trash gptel tool -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for the helpers in move_to_trash.el.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+  (add-to-list 'load-path (expand-file-name "gptel-tools" user-emacs-directory))
+  (setq load-prefer-newer t)
+  (unless (featurep 'gptel)
+    (defvar gptel-tools nil)
+    (defun gptel-make-tool (&rest _args) nil)
+    (defun gptel-get-tool (&rest _args) nil)
+    (provide 'gptel)))
+
+(require 'move_to_trash)
+
+;; -------------------------- helpers
+
+(defun test-gptel-tools-trash--with-tmp-tree (fn)
+  "Create a temp source dir and trash dir; run FN with both; clean up."
+  (let* ((src (make-temp-file "test-gptel-tools-trash-src-" t))
+         (trash (make-temp-file "test-gptel-tools-trash-dst-" t)))
+    (unwind-protect
+        (funcall fn src trash)
+      (when (file-exists-p src) (delete-directory src t))
+      (when (file-exists-p trash) (delete-directory trash t)))))
+
+;; -------------------------- generate-unique-name
+
+(ert-deftest test-gptel-tools-trash-generate-unique-name-no-conflict ()
+  "No conflict: returns the plain base name in trash."
+  (test-gptel-tools-trash--with-tmp-tree
+   (lambda (_src trash)
+     (let ((out (gptel--move-to-trash-generate-unique-name
+                 "/anywhere/foo.txt" trash)))
+       (should (equal (file-name-nondirectory out) "foo.txt"))))))
+
+(ert-deftest test-gptel-tools-trash-generate-unique-name-conflict-timestamps ()
+  "Name conflict: returns a name with a timestamp suffix."
+  (test-gptel-tools-trash--with-tmp-tree
+   (lambda (_src trash)
+     (with-temp-file (expand-file-name "foo.txt" trash) (insert ""))
+     (let* ((out (gptel--move-to-trash-generate-unique-name
+                  "/anywhere/foo.txt" trash))
+            (name (file-name-nondirectory out)))
+       (should-not (equal name "foo.txt"))
+       (should (string-match-p "\\`foo-[0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\}-[0-9]\\{2\\}-[0-9]\\{2\\}-[0-9]\\{2\\}\\.txt\\'"
+                               name))))))
+
+(ert-deftest test-gptel-tools-trash-generate-unique-name-no-extension ()
+  "Conflict on a name without extension: timestamp appended to the bare name."
+  (test-gptel-tools-trash--with-tmp-tree
+   (lambda (_src trash)
+     (with-temp-file (expand-file-name "noext" trash) (insert ""))
+     (let* ((out (gptel--move-to-trash-generate-unique-name
+                  "/anywhere/noext" trash))
+            (name (file-name-nondirectory out)))
+       (should-not (equal name "noext"))
+       (should (string-match-p "\\`noext-[0-9]" name))))))
+
+;; -------------------------- validate-path
+
+(ert-deftest test-gptel-tools-trash-validate-path-normal-home ()
+  "Normal: an existing path under HOME validates."
+  (let ((path (expand-file-name
+               (format ".test-gptel-tools-trash-home-%s.tmp"
+                       (format-time-string "%s%N"))
+               "~")))
+    (unwind-protect
+        (progn
+          (with-temp-file path (insert ""))
+          (should (equal (gptel--move-to-trash-validate-path path)
+                         (expand-file-name path))))
+      (when (file-exists-p path) (delete-file path)))))
+
+(ert-deftest test-gptel-tools-trash-validate-path-normal-tmp ()
+  "Normal: an existing path under /tmp validates."
+  (let ((path (make-temp-file "test-gptel-tools-trash-tmpvalidate-")))
+    (unwind-protect
+        (should (equal (gptel--move-to-trash-validate-path path)
+                       (expand-file-name path)))
+      (when (file-exists-p path) (delete-file path)))))
+
+(ert-deftest test-gptel-tools-trash-validate-path-error-outside-allowed ()
+  "Error: a path outside HOME or /tmp signals."
+  (should-error (gptel--move-to-trash-validate-path "/etc/hostname")))
+
+(ert-deftest test-gptel-tools-trash-validate-path-error-critical-dir ()
+  "Error: critical directories (home root, .emacs.d, .config, /tmp) signal."
+  (should-error (gptel--move-to-trash-validate-path "~"))
+  (should-error (gptel--move-to-trash-validate-path "~/.emacs.d"))
+  (should-error (gptel--move-to-trash-validate-path "~/.config"))
+  (should-error (gptel--move-to-trash-validate-path "/tmp")))
+
+(ert-deftest test-gptel-tools-trash-validate-path-error-missing ()
+  "Error: missing path signals."
+  (let ((path (expand-file-name
+               (format ".test-gptel-tools-trash-missing-%s.tmp"
+                       (format-time-string "%s%N"))
+               "~")))
+    (when (file-exists-p path) (delete-file path))
+    (should-error (gptel--move-to-trash-validate-path path))))
+
+;; -------------------------- perform
+
+(ert-deftest test-gptel-tools-trash-perform-moves-file ()
+  "Perform: moves the file out of the source dir into the trash dir."
+  (test-gptel-tools-trash--with-tmp-tree
+   (lambda (src trash)
+     (let ((file (expand-file-name "doomed.txt" src)))
+       (with-temp-file file (insert "trash me"))
+       (let ((status (gptel--move-to-trash-perform file trash)))
+         (should (string-match-p "moved to trash" status))
+         (should-not (file-exists-p file))
+         (should (file-exists-p (expand-file-name "doomed.txt" trash))))))))
+
+(ert-deftest test-gptel-tools-trash-perform-handles-directory ()
+  "Perform: moves a directory as a unit."
+  (test-gptel-tools-trash--with-tmp-tree
+   (lambda (src trash)
+     (let ((dir (expand-file-name "subdir" src)))
+       (make-directory dir)
+       (with-temp-file (expand-file-name "inside.txt" dir) (insert "x"))
+       (let ((status (gptel--move-to-trash-perform dir trash)))
+         (should (string-match-p "Directory moved to trash" status))
+         (should-not (file-exists-p dir))
+         (should (file-exists-p (expand-file-name "subdir/inside.txt" trash))))))))
+
+(provide 'test-gptel-tools-move-to-trash)
+;;; test-gptel-tools-move-to-trash.el ends here
diff --git a/tests/test-gptel-tools-read-buffer.el b/tests/test-gptel-tools-read-buffer.el
new file mode 100644
index 00000000..75efd604
--- /dev/null
+++ b/tests/test-gptel-tools-read-buffer.el
@@ -0,0 +1,60 @@
+;;; test-gptel-tools-read-buffer.el --- Tests for read_buffer gptel tool -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for `cj/read-buffer--get-content', the testable helper that
+;; backs the read_buffer gptel tool.
+
+;;; Code:
+
+(require 'ert)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+  (add-to-list 'load-path (expand-file-name "gptel-tools" user-emacs-directory))
+  (setq load-prefer-newer t)
+  (unless (featurep 'gptel)
+    (defvar gptel-tools nil)
+    (defun gptel-make-tool (&rest _args) nil)
+    (defun gptel-get-tool (&rest _args) nil)
+    (provide 'gptel)))
+
+(require 'read_buffer)
+
+(ert-deftest test-gptel-tools-read-buffer-normal ()
+  "Normal: returns the contents of an existing buffer."
+  (with-temp-buffer
+    (rename-buffer "test-gptel-tools-read-buffer-normal" t)
+    (insert "hello world")
+    (should (equal (cj/read-buffer--get-content (buffer-name)) "hello world"))))
+
+(ert-deftest test-gptel-tools-read-buffer-boundary-empty-buffer ()
+  "Boundary: empty buffer returns the empty string."
+  (with-temp-buffer
+    (rename-buffer "test-gptel-tools-read-buffer-empty" t)
+    (should (equal (cj/read-buffer--get-content (buffer-name)) ""))))
+
+(ert-deftest test-gptel-tools-read-buffer-boundary-buffer-object ()
+  "Boundary: accepts a buffer object as well as a name string."
+  (with-temp-buffer
+    (insert "from buffer object")
+    (should (equal (cj/read-buffer--get-content (current-buffer))
+                   "from buffer object"))))
+
+(ert-deftest test-gptel-tools-read-buffer-boundary-strips-text-properties ()
+  "Boundary: the returned string has no text properties."
+  (with-temp-buffer
+    (rename-buffer "test-gptel-tools-read-buffer-props" t)
+    (insert (propertize "fontified" 'face 'bold))
+    (let ((content (cj/read-buffer--get-content (buffer-name))))
+      (should (equal content "fontified"))
+      (should-not (text-properties-at 0 content)))))
+
+(ert-deftest test-gptel-tools-read-buffer-error-missing-buffer ()
+  "Error: nonexistent buffer name signals."
+  (when (get-buffer "test-gptel-tools-read-buffer-absent")
+    (kill-buffer "test-gptel-tools-read-buffer-absent"))
+  (should-error (cj/read-buffer--get-content
+                 "test-gptel-tools-read-buffer-absent")))
+
+(provide 'test-gptel-tools-read-buffer)
+;;; test-gptel-tools-read-buffer.el ends here
diff --git a/tests/test-gptel-tools-read-text-file.el b/tests/test-gptel-tools-read-text-file.el
new file mode 100644
index 00000000..3a4f6662
--- /dev/null
+++ b/tests/test-gptel-tools-read-text-file.el
@@ -0,0 +1,117 @@
+;;; test-gptel-tools-read-text-file.el --- Tests for read_text_file gptel tool -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for the helpers in read_text_file.el.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+  (add-to-list 'load-path (expand-file-name "gptel-tools" user-emacs-directory))
+  (setq load-prefer-newer t)
+  (unless (featurep 'gptel)
+    (defvar gptel-tools nil)
+    (defun gptel-make-tool (&rest _args) nil)
+    (defun gptel-get-tool (&rest _args) nil)
+    (provide 'gptel)))
+
+(require 'read_text_file)
+
+;; -------------------------- helpers
+
+(defun test-gptel-tools-read-text-file--in-home (suffix content fn)
+  "Run FN with a temp file (containing CONTENT) under HOME using SUFFIX."
+  (let* ((name (format ".test-gptel-tools-read-text-file-%s-%s.tmp"
+                       suffix (format-time-string "%s%N")))
+         (path (expand-file-name name "~")))
+    (unwind-protect
+        (progn
+          (with-temp-file path (insert content))
+          (funcall fn path))
+      (when (file-exists-p path) (delete-file path)))))
+
+;; -------------------------- validate-file-path
+
+(ert-deftest test-gptel-tools-read-text-file-validate-path-normal ()
+  "Normal: an existing readable file under HOME passes."
+  (test-gptel-tools-read-text-file--in-home
+   "normal" "hi"
+   (lambda (path)
+     (should (equal (cj/validate-file-path path) (file-truename path))))))
+
+(ert-deftest test-gptel-tools-read-text-file-validate-path-error-outside-home ()
+  "Error: path outside HOME signals."
+  (should-error (cj/validate-file-path "/etc/hostname")))
+
+(ert-deftest test-gptel-tools-read-text-file-validate-path-error-missing ()
+  "Error: missing file signals."
+  (let ((path (expand-file-name
+               (format ".test-gptel-tools-read-text-file-missing-%s.tmp"
+                       (format-time-string "%s%N"))
+               "~")))
+    (when (file-exists-p path) (delete-file path))
+    (should-error (cj/validate-file-path path))))
+
+(ert-deftest test-gptel-tools-read-text-file-validate-path-error-directory ()
+  "Error: a directory signals."
+  (should-error (cj/validate-file-path "~")))
+
+;; -------------------------- get-file-metadata
+
+(ert-deftest test-gptel-tools-read-text-file-get-metadata-shape ()
+  "Returns a plist with :size and :string keys."
+  (test-gptel-tools-read-text-file--in-home
+   "meta" "abc"
+   (lambda (path)
+     (let ((meta (cj/get-file-metadata path)))
+       (should (plist-get meta :size))
+       (should (= 3 (plist-get meta :size)))
+       (should (stringp (plist-get meta :string)))
+       (should (string-match-p "modified" (plist-get meta :string)))))))
+
+;; -------------------------- check-file-size-limits
+
+(ert-deftest test-gptel-tools-read-text-file-size-limits-normal ()
+  "Small size below warning limit is a no-op."
+  (should-not (cj/check-file-size-limits 1024 nil)))
+
+(ert-deftest test-gptel-tools-read-text-file-size-limits-error-hard-cap ()
+  "Sizes above 100MB always signal."
+  (should-error (cj/check-file-size-limits (* 101 1024 1024) t))
+  (should-error (cj/check-file-size-limits (* 101 1024 1024) nil)))
+
+(ert-deftest test-gptel-tools-read-text-file-size-limits-warning-with-no-confirm ()
+  "Above 10MB but below 100MB with no-confirm passes through silently."
+  (should-not (cj/check-file-size-limits (* 11 1024 1024) t)))
+
+;; -------------------------- detect-binary-file
+
+(ert-deftest test-gptel-tools-read-text-file-detect-binary-text-file ()
+  "Text file: detect-binary returns nil."
+  (test-gptel-tools-read-text-file--in-home
+   "text" "plain ascii content"
+   (lambda (path)
+     (should-not (cj/detect-binary-file path)))))
+
+(ert-deftest test-gptel-tools-read-text-file-detect-binary-with-null-byte ()
+  "File with NUL in first 1024 bytes returns truthy."
+  (test-gptel-tools-read-text-file--in-home
+   "bin" (concat "head\0tail")
+   (lambda (path)
+     (should (cj/detect-binary-file path)))))
+
+;; -------------------------- handle-special-file-types
+
+(ert-deftest test-gptel-tools-read-text-file-handle-special-epub-error ()
+  "EPUB special-type handler signals \"not yet implemented\"."
+  (should-error (cj/handle-special-file-types "/tmp/foo.epub" t)))
+
+(ert-deftest test-gptel-tools-read-text-file-handle-special-binary-returns-nil ()
+  "Generic binary file with no-confirm returns nil to indicate normal read."
+  (should-not (cj/handle-special-file-types "/tmp/foo.bin" t)))
+
+(provide 'test-gptel-tools-read-text-file)
+;;; test-gptel-tools-read-text-file.el ends here
diff --git a/tests/test-gptel-tools-write-text-file.el b/tests/test-gptel-tools-write-text-file.el
new file mode 100644
index 00000000..258ae8cc
--- /dev/null
+++ b/tests/test-gptel-tools-write-text-file.el
@@ -0,0 +1,141 @@
+;;; test-gptel-tools-write-text-file.el --- Tests for write_text_file gptel tool -*- lexical-binding: t; -*-
+
+;;; Commentary:
+;; Tests for `cj/write-text-file--run' and its helpers.
+
+;;; Code:
+
+(require 'ert)
+(require 'cl-lib)
+
+(eval-and-compile
+  (add-to-list 'load-path (expand-file-name "tests" user-emacs-directory))
+  (add-to-list 'load-path (expand-file-name "gptel-tools" user-emacs-directory))
+  (setq load-prefer-newer t)
+  (unless (featurep 'gptel)
+    (defvar gptel-tools nil)
+    (defun gptel-make-tool (&rest _args) nil)
+    (defun gptel-get-tool (&rest _args) nil)
+    (provide 'gptel)))
+
+(require 'write_text_file)
+
+;; ------------------------------------------------------- helpers
+
+(defun test-gptel-tools-write-text-file--in-home (suffix fn)
+  "Run FN with a fresh path under HOME using SUFFIX.  Clean up after."
+  (let* ((name (format ".test-gptel-tools-write-text-file-%s-%s.tmp"
+                       suffix (format-time-string "%s%N")))
+         (path (expand-file-name name "~")))
+    (unwind-protect
+        (funcall fn path)
+      (when (file-exists-p path) (delete-file path))
+      (dolist (b (file-expand-wildcards (concat path "-*.bak")))
+        (when (file-exists-p b) (delete-file b))))))
+
+;; --------------------------------------------- validate-path
+
+(ert-deftest test-gptel-tools-write-text-file-validate-path-normal ()
+  "Normal: returns the expanded path for a HOME-relative input."
+  (let ((result (cj/write-text-file--validate-path "foo.txt")))
+    (should (string-prefix-p (expand-file-name "~") result))
+    (should (string-suffix-p "/foo.txt" result))))
+
+(ert-deftest test-gptel-tools-write-text-file-validate-path-error-outside-home ()
+  "Error: a path outside HOME signals."
+  (should-error (cj/write-text-file--validate-path "/etc/hostname")))
+
+;; --------------------------------------------- backup-name
+
+(ert-deftest test-gptel-tools-write-text-file-backup-name-shape ()
+  "Backup names append a YYYY-MM-DD-HHMMSS suffix and .bak."
+  (let ((name (cj/write-text-file--backup-name "/home/user/foo.txt")))
+    (should (string-prefix-p "/home/user/foo.txt-" name))
+    (should (string-suffix-p ".bak" name))
+    (should (string-match-p "-[0-9]\\{4\\}-[0-9]\\{2\\}-[0-9]\\{2\\}-[0-9]\\{6\\}\\.bak\\'"
+                            name))))
+
+;; --------------------------------------------- ensure-parent
+
+(ert-deftest test-gptel-tools-write-text-file-ensure-parent-creates-missing ()
+  "Normal: creates missing parent directories."
+  (let* ((base (make-temp-file "test-gptel-tools-write-text-file-" t))
+         (deep (expand-file-name "a/b/c/file.txt" base)))
+    (unwind-protect
+        (progn
+          (cj/write-text-file--ensure-parent deep)
+          (should (file-directory-p (file-name-directory deep))))
+      (delete-directory base t))))
+
+(ert-deftest test-gptel-tools-write-text-file-ensure-parent-error-unwritable ()
+  "Error: an unwritable parent signals."
+  (let* ((parent (make-temp-file "test-gptel-tools-write-text-file-ro-" t))
+         (target (expand-file-name "child.txt" parent)))
+    (unwind-protect
+        (progn
+          (set-file-modes parent #o500)
+          (should-error (cj/write-text-file--ensure-parent target)))
+      (set-file-modes parent #o700)
+      (delete-directory parent t))))
+
+;; --------------------------------------------- run
+
+(ert-deftest test-gptel-tools-write-text-file-run-normal ()
+  "Normal: writes new content and returns a status string."
+  (test-gptel-tools-write-text-file--in-home
+   "new"
+   (lambda (path)
+     (let ((result (cj/write-text-file--run
+                    (file-name-nondirectory path) "hello\n" nil)))
+       (should (string-match-p "Successfully wrote" result))
+       (with-temp-buffer
+         (insert-file-contents path)
+         (should (equal (buffer-string) "hello\n")))))))
+
+(ert-deftest test-gptel-tools-write-text-file-run-error-existing-no-overwrite ()
+  "Error: existing file without overwrite signals."
+  (test-gptel-tools-write-text-file--in-home
+   "existing"
+   (lambda (path)
+     (with-temp-file path (insert "old content\n"))
+     (should-error (cj/write-text-file--run
+                    (file-name-nondirectory path) "new content\n" nil))
+     ;; File preserved
+     (with-temp-buffer
+       (insert-file-contents path)
+       (should (equal (buffer-string) "old content\n"))))))
+
+(ert-deftest test-gptel-tools-write-text-file-run-overwrite-creates-backup ()
+  "Overwrite path makes a timestamped backup before writing."
+  (test-gptel-tools-write-text-file--in-home
+   "overwrite"
+   (lambda (path)
+     (with-temp-file path (insert "old content\n"))
+     (cj/write-text-file--run
+      (file-name-nondirectory path) "new content\n" t)
+     ;; New content landed
+     (with-temp-buffer
+       (insert-file-contents path)
+       (should (equal (buffer-string) "new content\n")))
+     ;; Backup exists with old content
+     (let ((backups (file-expand-wildcards (concat path "-*.bak"))))
+       (should (= 1 (length backups)))
+       (with-temp-buffer
+         (insert-file-contents (car backups))
+         (should (equal (buffer-string) "old content\n")))))))
+
+(ert-deftest test-gptel-tools-write-text-file-run-boundary-empty-content ()
+  "Boundary: nil content writes an empty file."
+  (test-gptel-tools-write-text-file--in-home
+   "empty"
+   (lambda (path)
+     (cj/write-text-file--run (file-name-nondirectory path) nil nil)
+     (should (file-exists-p path))
+     (should (= 0 (file-attribute-size (file-attributes path)))))))
+
+(ert-deftest test-gptel-tools-write-text-file-run-error-outside-home ()
+  "Error: a path outside HOME signals."
+  (should-error (cj/write-text-file--run "/etc/test-write.txt" "x" nil)))
+
+(provide 'test-gptel-tools-write-text-file)
+;;; test-gptel-tools-write-text-file.el ends here