fix: Insert --position before now adds blank line before heading (#216)

When inserting content before a section, a blank line was missing
between the inserted content and the following section heading.
This violated AsciiDoc/Markdown formatting conventions.

The issue was that the blank line was only added when the inserted
content did NOT start with a heading, but we always need a blank
line before a heading regardless of the inserted content type.

Fixes #216

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

.vibe/development-plan-fix-insert-before-blank-line-216.md

@@ -0,0 +1,87 @@
+# Development Plan: Fix #216 - Insert --position before missing blank line
+
+*Generated on 2026-01-31 by Vibe Feature MCP*
+*Workflow: [bugfix](https://mrsimpson.github.io/responsible-vibe-mcp/workflows/bugfix)*
+
+## Goal
+Fix the missing blank line between inserted section and following section when using `insert --position before`.
+
+## Key Decisions
+- Ensure consistent spacing behavior between `--position before` and `--position after`
+
+## Notes
+- Issue: https://github.com/docToolchain/dacli/issues/216
+- Branch: fix/insert-before-blank-line-216
+- Related: #223 (insert after - already fixed), same code location in cli.py
+
+## Reproduce
+
+### Phase Entrance Criteria:
+- [x] Issue #216 has been reviewed and understood
+
+### Tasks
+- [ ] Create test document with multiple sections
+- [ ] Run insert --position before command
+- [ ] Verify missing blank line in output
+
+### Completed
+- [x] Created development plan file
+
+## Analyze
+
+### Phase Entrance Criteria:
+- [ ] Bug has been successfully reproduced
+- [ ] Steps to reproduce are documented
+
+### Tasks
+- [ ] Find the insert code in cli.py
+- [ ] Compare before/after position handling
+- [ ] Identify why blank line is missing
+
+### Completed
+*None yet*
+
+## Fix
+
+### Phase Entrance Criteria:
+- [ ] Root cause identified
+- [ ] Solution approach confirmed
+
+### Tasks
+- [ ] Write failing test
+- [ ] Implement blank line handling for --position before
+- [ ] Verify existing tests pass
+
+### Completed
+*None yet*
+
+## Verify
+
+### Phase Entrance Criteria:
+- [ ] Fix implemented
+- [ ] All tests pass
+
+### Tasks
+- [ ] Run full test suite
+- [ ] Manual verification
+- [ ] Test edge cases
+
+### Completed
+*None yet*
+
+## Finalize
+
+### Phase Entrance Criteria:
+- [ ] All tests pass
+- [ ] No regressions
+
+### Tasks
+- [ ] Update version
+- [ ] Create commit
+- [ ] Create PR
+
+### Completed
+*None yet*
+
+---
+*This plan is maintained by the LLM.*

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dacli"
-version = "0.4.11"
+version = "0.4.12"
 description = "Documentation Access CLI - Navigate and query large documentation projects"
 readme = "README.md"
 license = { text = "MIT" }

src/dacli/__init__.py

@@ -4,4 +4,4 @@
 through hierarchical, content-aware access via the Model Context Protocol (MCP).
 """
 
-__version__ = "0.4.11"
+__version__ = "0.4.12"

src/dacli/cli.py

@@ -729,9 +729,9 @@ def ensure_trailing_blank_line(content: str) -> str:
 
         if position == "before":
             insert_line = start_line
-            # Check if the line we're inserting before is a heading
+            # Issue #216: Always add blank line before a heading
             next_line_idx = start_line - 1  # 0-based index
-            if next_line_is_heading(lines, next_line_idx) and not starts_with_heading:
+            if next_line_is_heading(lines, next_line_idx):
                 insert_content = ensure_trailing_blank_line(insert_content)
             new_lines = lines[: start_line - 1] + [insert_content] + lines[start_line - 1 :]
         elif position == "after":

tests/test_insert_before_blank_line_216.py

@@ -0,0 +1,118 @@
+"""Tests for Issue #216: Insert --position before missing blank line.
+
+When inserting content before a section, there should be a blank line
+between the inserted content and the following section.
+"""
+
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from dacli.cli import cli
+
+
+@pytest.fixture
+def temp_doc_dir(tmp_path: Path) -> Path:
+    """Create a temporary directory with test document."""
+    doc_file = tmp_path / "test.adoc"
+    doc_file.write_text(
+        """= Document
+
+== Section A
+
+Content A
+
+== Section B
+
+Content B
+""",
+        encoding="utf-8",
+    )
+    return tmp_path
+
+
+class TestInsertBeforeBlankLine:
+    """Test that insert --position before adds blank line correctly."""
+
+    def test_insert_section_before_adds_blank_line(self, temp_doc_dir: Path):
+        """Issue #216: Inserting a section before another should add blank line."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "insert",
+                "test:section-b",
+                "--position",
+                "before",
+                "--content",
+                "== Before B\n\nContent before B",
+            ],
+        )
+
+        assert result.exit_code == 0
+
+        # Check the file content
+        doc_file = temp_doc_dir / "test.adoc"
+        file_content = doc_file.read_text(encoding="utf-8")
+
+        # There should be a blank line between "Content before B" and "== Section B"
+        assert "Content before B\n\n== Section B" in file_content, (
+            f"Missing blank line before Section B. Content:\n{file_content}"
+        )
+
+    def test_insert_content_before_heading_adds_blank_line(self, temp_doc_dir: Path):
+        """Insert plain content before a heading should add blank line."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "insert",
+                "test:section-b",
+                "--position",
+                "before",
+                "--content",
+                "Some plain content without heading",
+            ],
+        )
+
+        assert result.exit_code == 0
+
+        doc_file = temp_doc_dir / "test.adoc"
+        file_content = doc_file.read_text(encoding="utf-8")
+
+        # There should be a blank line between the content and Section B
+        assert "Some plain content without heading\n\n== Section B" in file_content, (
+            f"Missing blank line before Section B. Content:\n{file_content}"
+        )
+
+    def test_insert_before_preserves_existing_blank_lines(self, temp_doc_dir: Path):
+        """Don't add extra blank lines if content already ends with them."""
+        runner = CliRunner()
+        result = runner.invoke(
+            cli,
+            [
+                "--docs-root",
+                str(temp_doc_dir),
+                "insert",
+                "test:section-b",
+                "--position",
+                "before",
+                "--content",
+                "== Before B\n\nContent before B\n\n",  # Already has trailing blank line
+            ],
+        )
+
+        assert result.exit_code == 0
+
+        doc_file = temp_doc_dir / "test.adoc"
+        file_content = doc_file.read_text(encoding="utf-8")
+
+        # Should have exactly one blank line (not extra)
+        assert "Content before B\n\n== Section B" in file_content
+        # Should NOT have triple newlines
+        assert "Content before B\n\n\n== Section B" not in file_content