confpub-cli 1.7.0__tar.gz → 1.7.2__tar.gz

confpub_cli-1.7.2/.github/copilot-instructions.md

@@ -0,0 +1,88 @@
+# Copilot Instructions
+
+Agent-first CLI for publishing Markdown to Confluence. Python 3.10+, no linter configured.
+
+## Commands
+
+```bash
+uv pip install -e ".[dev]"                                               # Install with dev deps
+pytest tests/ -v                                                         # Run all tests
+pytest tests/test_converter.py -v                                        # Run one module
+pytest tests/test_converter.py::TestHeadings::test_h1 -v                # Run single test
+pytest tests/ -k "fingerprint" -v                                        # Run by name pattern
+pytest tests/ -v --cov=confpub                                           # Run with coverage
+uvx hatch version minor                                                  # Bump version (patch/minor/major)
+```
+
+## Architecture
+
+### Command flow
+
+Every command follows this path through `cli.py`:
+
+1. Typer handler receives flags and calls `command_context(command_name)` — a context manager that records timing, catches errors, and emits the final JSON envelope on stdout.
+2. Handler populates a `CommandResult` (result, target, warnings, metrics) then delegates to a domain module (`publish.py`, `applier.py`, `puller.py`, `planner.py`, etc.).
+3. Domain module calls `ConfluenceClient` (`confluence.py`), which wraps `atlassian-python-api` and translates its exceptions into `ConfpubError`.
+4. `command_context` serializes an `Envelope` and writes it to stdout; any exception that escapes domain code is caught here too.
+
+### Subcommand groups
+
+`page`, `plan`, `auth`, `config`, `space`, `attachment`, `label`, `comment` — each is a `typer.Typer` added to the root `app` in `cli.py`.
+
+### Transactional plan workflow
+
+`plan create` → `plan validate` → `plan apply` → `plan verify`
+
+Only `plan apply` has side effects. `plan create` fingerprints existing pages (SHA-256 of storage-format body) so that `plan apply` can detect external edits (`ERR_CONFLICT_FINGERPRINT`) before writing.
+
+### Markdown conversion
+
+- `converter.py` — `markdown-it-py` + custom `ConfluenceRenderer` → Confluence Storage Format XHTML. Pure function, no I/O.
+- `reverse_converter.py` — BeautifulSoup4 + markdownify → Markdown. Pure function, no I/O.
+
+### Lockfile
+
+`confpub.lock` maps page titles → `{page_id, version, content_fingerprint}`. Updated atomically (tempfile + `os.replace`) by publish, pull, apply, and delete.
+
+## Key Conventions
+
+### stdout is JSON-only
+
+Every invocation emits exactly one `Envelope` object on stdout. Never write anything else there. Progress events and diagnostics go to stderr via `output.py` helpers (`emit_progress`, `emit_stderr`), and are suppressed when `--quiet`, `LLM=true`, or stdout is not a TTY.
+
+### Error codes are stable public API
+
+Error codes use the pattern `ERR_{CATEGORY}_{SPECIFIC}`. Category prefixes map to fixed exit codes:
+
+| Prefix | Exit code |
+|---|---|
+| `ERR_VALIDATION` | 10 |
+| `ERR_AUTH` | 20 |
+| `ERR_CONFLICT` | 40 |
+| `ERR_IO` | 50 |
+| `ERR_INTERNAL` | 90 |
+
+Never rename or remove an error code constant without a major version bump. Use the builder helpers (`validation_error(...)`, `auth_error(...)`, etc.) in `errors.py` rather than constructing `ConfpubError` directly.
+
+### ConfpubError
+
+All domain errors must be `ConfpubError` instances. Fields: `code`, `message`, `retryable`, `suggested_action`, `details`. These flow directly into `Envelope.errors`.
+
+### Pydantic models everywhere
+
+`Envelope`, `Lockfile`, `Manifest`, `ConfigModel`, and plan artifacts are all Pydantic v2 `BaseModel`. Use `model_dump(mode="json")` for serialization.
+
+### Credential precedence
+
+CLI flags → env vars (`CONFPUB_URL`, `CONFPUB_TOKEN`, `CONFPUB_USER`, `CONFPUB_SPACE`, `CONFPUB_SSL_VERIFY`) → config file (`~/.config/confpub/config.json`) → OS keychain.
+
+### Test conventions
+
+- Use the `run_cli` fixture from `conftest.py` (wraps `typer.testing.CliRunner`) for all CLI-level tests.
+- Mock all Confluence API calls with `unittest.mock` — no live integration tests.
+- Group related test cases in classes (e.g. `class TestHeadings`, `class TestApplyPlanReal`).
+- Unit tests for new domain functions go in the matching `test_<module>.py`; CLI-level behavior goes in `test_integration.py`.
+
+## Version
+
+Defined in `confpub/__init__.py`. Hatch reads it from `pyproject.toml`. Pushing to `main` triggers the GitHub Actions publish workflow.

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.7.0
+Version: 1.7.2
 Summary: Agent-first CLI to publish Markdown to Confluence
 Project-URL: Homepage, https://github.com/ThomasRohde/confpub-cli
 Project-URL: Repository, https://github.com/ThomasRohde/confpub-cli.git

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/confpub/__init__.py

@@ -1,3 +1,3 @@
 """confpub — Agent-first CLI to publish Markdown to Confluence."""
 
-__version__ = "1.7.0"
+__version__ = "1.7.2"

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/confpub/converter.py

@@ -713,6 +713,43 @@ def _create_parser() -> MarkdownIt:
     return md
 
 
+_LAYOUT_BLOCK_RE = re.compile(r"<ac:layout>.*?</ac:layout>", re.DOTALL)
+
+_LAYOUT_WRAP_PREFIX = (
+    '<ac:layout><ac:layout-section ac:type="single"><ac:layout-cell>'
+)
+_LAYOUT_WRAP_SUFFIX = "</ac:layout-cell></ac:layout-section></ac:layout>"
+
+
+def _wrap_non_layout_content(html: str) -> str:
+    """Wrap content outside ``<ac:layout>`` blocks in single-column layouts.
+
+    Confluence Server's editor cannot handle a mix of layout blocks and
+    top-level content on the same page — it enters "layout mode" and makes
+    everything outside cells read-only.  This function detects when layout
+    blocks are present and wraps any surrounding content in its own
+    single-column layout so the entire page is in layout mode.
+    """
+    if "<ac:layout>" not in html:
+        return html
+
+    parts: list[str] = []
+    last_end = 0
+
+    for match in _LAYOUT_BLOCK_RE.finditer(html):
+        before = html[last_end:match.start()]
+        if before.strip():
+            parts.append(_LAYOUT_WRAP_PREFIX + before + _LAYOUT_WRAP_SUFFIX)
+        parts.append(match.group(0))
+        last_end = match.end()
+
+    after = html[last_end:]
+    if after.strip():
+        parts.append(_LAYOUT_WRAP_PREFIX + after + _LAYOUT_WRAP_SUFFIX)
+
+    return "".join(parts)
+
+
 def convert_markdown(md_text: str) -> str:
     """Convert Markdown text to Confluence Storage Format.
 
@@ -725,7 +762,8 @@ def convert_markdown(md_text: str) -> str:
     parser = _create_parser()
     tokens = parser.parse(md_text)
     renderer = ConfluenceRenderer()
-    return renderer.render(tokens, {}, {})
+    html = renderer.render(tokens, {}, {})
+    return _wrap_non_layout_content(html)
 
 
 def extract_h1_title(md_text: str) -> str | None:

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/confpub/guide.py

@@ -409,7 +409,7 @@ def build_guide() -> dict[str, Any]:
                 ),
                 "panels":         "::: panel Title\\ncontent\\n::: → ac:structured-macro panel",
                 "expand":         "::: expand Title\\ncontent\\n::: → ac:structured-macro expand",
-                "layouts":        ":::: layout two-equal\\n::: cell\\n...\\n::::\\n → ac:layout with ac:layout-section",
+                "layouts":        ":::: layout two-equal\\n::: cell\\n...\\n::::\\n → ac:layout with ac:layout-section. Content outside layout blocks is auto-wrapped in a single-column layout (Confluence requires all content in layout cells when layouts are used).",
                 "status":           "{status:Title|colour=Color} → ac:structured-macro status",
                 "toc":              "{toc} / {toc:maxLevel=N} → ac:structured-macro toc",
                 "anchor":           "{anchor:name} → ac:structured-macro anchor",
@@ -425,6 +425,8 @@ def build_guide() -> dict[str, Any]:
                 "All features are always-on — the parser simply ignores syntax that isn't used. "
                 "Math macros require the Confluence LaTeX Math plugin to be installed on the server. "
                 "Layouts use :::: (4 colons) for the outer layout block and ::: (3 colons) for inner cells. "
+                "When layouts are used, ALL page content must live inside layout cells — "
+                "confpub auto-wraps any content outside layout blocks in a single-column layout to satisfy this Confluence requirement. "
                 "Use {macro-name:params} for body-less Confluence macros. "
                 "Macros on their own line become block-level (no <p> wrapping)."
             ),

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/confpub/reverse_converter.py

@@ -452,14 +452,18 @@ def _preprocess_storage_format(html: str) -> tuple[BeautifulSoup, list[str]]:
             if next_sib and next_sib.name == "ol":
                 hr.decompose()
 
-    # 5. Transform ac:layout → div[data-layout-macro]
+    # 5. Transform ac:layout → div[data-layout-macro] per section
     for layout in soup.find_all("ac:layout"):
-        layout_div = soup.new_tag("div")
-        layout_div["data-layout-macro"] = "layout"
-        section = layout.find("ac:layout-section")
-        if section:
+        sections = layout.find_all("ac:layout-section", recursive=False)
+        if not sections:
+            layout.decompose()
+            continue
+        # Build one layout div per section, then replace the ac:layout
+        section_divs = []
+        for section in sections:
+            layout_div = soup.new_tag("div")
+            layout_div["data-layout-macro"] = "layout"
             layout_type = section.get("ac:type", "single")
-            # Convert underscores back to hyphens
             layout_type = layout_type.replace("_", "-")
             layout_div["data-layout-type"] = layout_type
             for cell in section.find_all("ac:layout-cell", recursive=False):
@@ -468,7 +472,11 @@ def _preprocess_storage_format(html: str) -> tuple[BeautifulSoup, list[str]]:
                 for child in list(cell.children):
                     cell_div.append(child.extract())
                 layout_div.append(cell_div)
-        layout.replace_with(layout_div)
+            section_divs.append(layout_div)
+        # Insert all section divs after the layout, then remove it
+        for div in reversed(section_divs):
+            layout.insert_after(div)
+        layout.decompose()
 
     # 6. Transform ac:link → a
     for link in soup.find_all("ac:link"):

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/tests/test_converter.py

@@ -421,6 +421,80 @@ class TestContainerLayout:
         assert result.count("<ac:layout-cell>") == 3
 
 
+class TestLayoutWrapping:
+    """Confluence Server cannot handle content outside <ac:layout> blocks.
+
+    When layout blocks are present, all surrounding content must be wrapped
+    in single-column layout blocks so the editor stays in layout mode.
+    """
+
+    def test_content_before_layout_is_wrapped(self):
+        md = "## Heading\n\nParagraph.\n\n:::: layout two-equal\n::: cell\nLeft\n:::\n::: cell\nRight\n:::\n::::"
+        result = convert_markdown(md)
+        # The heading and paragraph should be inside a single-column layout
+        assert result.startswith('<ac:layout><ac:layout-section ac:type="single"><ac:layout-cell>')
+        # The original layout block should still be present
+        assert '<ac:layout><ac:layout-section ac:type="two_equal">' in result
+
+    def test_content_after_layout_is_wrapped(self):
+        md = ":::: layout two-equal\n::: cell\nLeft\n:::\n::: cell\nRight\n:::\n::::\n\n## After\n\nMore text."
+        result = convert_markdown(md)
+        # Should end with a wrapped single-column block
+        assert result.endswith("</ac:layout-cell></ac:layout-section></ac:layout>")
+        # Count: one two_equal layout + one single wrapper
+        assert result.count("<ac:layout>") == 2
+
+    def test_content_before_and_after_layout_wrapped(self):
+        md = (
+            "## Before\n\n"
+            ":::: layout two-equal\n::: cell\nL\n:::\n::: cell\nR\n:::\n::::\n\n"
+            "## After\n"
+        )
+        result = convert_markdown(md)
+        # Two wrappers (before + after) plus the real layout = 3 layout blocks
+        assert result.count("<ac:layout>") == 3
+        assert result.count("</ac:layout>") == 3
+
+    def test_no_layout_blocks_unchanged(self):
+        md = "## Heading\n\nParagraph."
+        result = convert_markdown(md)
+        # No layout blocks should be introduced
+        assert "<ac:layout>" not in result
+
+    def test_only_layout_no_extra_wrapping(self):
+        md = ":::: layout two-equal\n::: cell\nLeft\n:::\n::: cell\nRight\n:::\n::::"
+        result = convert_markdown(md)
+        # Only one layout block — no extra wrappers
+        assert result.count("<ac:layout>") == 1
+
+    def test_mixed_content_with_table_and_macros(self):
+        """Reproduce the exact scenario from the bug report."""
+        md = (
+            "## Some heading\n\n"
+            "Regular paragraph text.\n\n"
+            ":::: layout two-equal\n"
+            "::: cell\nLeft column content.\n:::\n"
+            "::: cell\nRight column content.\n:::\n"
+            "::::\n\n"
+            "## Another heading\n\n"
+            "| Col A | Col B |\n"
+            "|-------|-------|\n"
+            "| 1     | 2     |\n"
+        )
+        result = convert_markdown(md)
+        # All content should be inside layout blocks
+        assert result.count("<ac:layout>") == 3
+        # The heading before should be wrapped
+        assert "Some heading" in result
+        # The table after should be wrapped
+        assert "Col A" in result
+        # No top-level content outside layout blocks
+        # Split by </ac:layout> and check there's nothing outside
+        import re
+        outside = re.sub(r"<ac:layout>.*?</ac:layout>", "", result, flags=re.DOTALL)
+        assert outside.strip() == ""
+
+
 class TestExtractFrontMatter:
     def test_basic_extraction(self):
         md = "---\ntitle: Hello\nspace: DEV\n---\n\n# Content"

{confpub_cli-1.7.0 → confpub_cli-1.7.2}/tests/test_reverse_converter.py

@@ -355,6 +355,50 @@ class TestLayoutReverse:
         assert "Right" in result.markdown
         assert "::::" in result.markdown
 
+    def test_layout_multiple_sections(self):
+        """Multiple ac:layout-section elements must all be converted (bug fix)."""
+        html = (
+            '<ac:layout>'
+            '<ac:layout-section ac:type="single">'
+            '<ac:layout-cell><p>Section one</p></ac:layout-cell>'
+            '</ac:layout-section>'
+            '<ac:layout-section ac:type="single">'
+            '<ac:layout-cell>'
+            '<h1>Main heading</h1>'
+            '<p>Body paragraph with <strong>bold</strong> text.</p>'
+            '<ul><li>Item A</li><li>Item B</li></ul>'
+            '</ac:layout-cell>'
+            '</ac:layout-section>'
+            '</ac:layout>'
+        )
+        result = convert_storage_to_markdown(html)
+        assert "Section one" in result.markdown
+        assert "# Main heading" in result.markdown
+        assert "Body paragraph" in result.markdown
+        assert "**bold**" in result.markdown
+        assert "Item A" in result.markdown
+        assert "Item B" in result.markdown
+
+    def test_layout_mixed_section_types(self):
+        """Sections with different layout types preserve their types."""
+        html = (
+            '<ac:layout>'
+            '<ac:layout-section ac:type="single">'
+            '<ac:layout-cell><p>Full width</p></ac:layout-cell>'
+            '</ac:layout-section>'
+            '<ac:layout-section ac:type="two_left_sidebar">'
+            '<ac:layout-cell><p>Sidebar</p></ac:layout-cell>'
+            '<ac:layout-cell><p>Main content</p></ac:layout-cell>'
+            '</ac:layout-section>'
+            '</ac:layout>'
+        )
+        result = convert_storage_to_markdown(html)
+        assert ":::: layout single" in result.markdown
+        assert ":::: layout two-left-sidebar" in result.markdown
+        assert "Full width" in result.markdown
+        assert "Sidebar" in result.markdown
+        assert "Main content" in result.markdown
+
 
 class TestPluginRoundTrips:
     """Test round-trip conversion for new plugin features."""