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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: confpub-cli
-Version: 1.6.0
+Version: 1.7.0
 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.6.0 → confpub_cli-1.7.0}/confpub/__init__.py

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

{confpub_cli-1.6.0 → confpub_cli-1.7.0}/confpub/cli.py

@@ -21,19 +21,19 @@ from confpub.errors import ConfpubError, exit_code_for, ERR_INTERNAL_SDK
 from confpub.output import emit_stderr, emit_stdout, is_compact, is_verbose, set_compact, set_quiet, set_verbose
 
 
-def _resolve_space(cli_space: str | None, required: bool = False) -> str | None:
-    """Resolve space from CLI flag or CONFPUB_SPACE env var, with validation."""
+def _resolve_space(cli_space: str | None, required: bool = False, fm_space: str | None = None) -> str | None:
+    """Resolve space from CLI flag, front-matter, or CONFPUB_SPACE env var, with validation."""
     from confpub.config import ENV_SPACE
     from confpub.errors import validate_space_key
 
-    space = cli_space or os.environ.get(ENV_SPACE)
+    space = cli_space or fm_space or os.environ.get(ENV_SPACE)
     if space is not None:
         validate_space_key(space)
         return space
     if required:
         raise ConfpubError(
             "ERR_VALIDATION_REQUIRED",
-            "Space key is required. Use --space or set CONFPUB_SPACE.",
+            "Space key is required. Use --space, front-matter, or set CONFPUB_SPACE.",
         )
     return None
 
@@ -290,30 +290,59 @@ def page_publish(
     label: Optional[list[str]] = typer.Option(None, "--label", help="Label to apply (repeatable)"),
 ) -> None:
     """Publish a single Markdown file to Confluence."""
+    from pathlib import Path as _Path
+    from confpub.front_matter import parse_front_matter
     from confpub.publish import derive_title
-    resolved_title = derive_title(file, title, title_from_h1=title_from_h1)
+
+    # Parse front-matter from the file (before command_context so title is resolved for target)
+    fm = None
+    source = _Path(file)
+    if source.exists():
+        md_text = source.read_text(encoding="utf-8")
+        fm = parse_front_matter(md_text)
+
+    fm_title = fm.title if fm else None
+    fm_space = fm.space if fm else None
+    fm_parent = fm.parent if fm else None
+    fm_page_id = fm.page_id if fm else None
+    fm_labels = fm.labels if fm else []
+
+    resolved_title = derive_title(file, title, title_from_h1=title_from_h1, front_matter_title=fm_title)
+
+    # Resolve page_id: CLI flag > front-matter
+    effective_page_id = page_id or fm_page_id
+
     target = {"space": space, "title": resolved_title, "file": file}
-    if page_id:
-        target["page_id"] = page_id
+    if effective_page_id:
+        target["page_id"] = effective_page_id
     with command_context("page.publish", target=target) as ctx:
-        space = _resolve_space(space, required=True)
+        space = _resolve_space(space, required=True, fm_space=fm_space)
         ctx.target["space"] = space
-        if not page_id and not parent:
+
+        # Resolve parent: CLI flag > front-matter
+        effective_parent = parent or fm_parent
+
+        if not effective_page_id and not effective_parent:
             raise ConfpubError(
                 "ERR_VALIDATION_REQUIRED",
-                "Either --page-id or --parent is required",
+                "Either --page-id or --parent is required (via flag or front-matter)",
             )
+
+        # Merge labels: CLI + front-matter (deduplicated, order-preserving)
+        cli_labels = label or []
+        merged_labels = list(dict.fromkeys(cli_labels + fm_labels))
+
         from confpub.publish import publish_page
         result = publish_page(
             file=file,
             space=space,
-            parent=parent or "",
-            title=title,
-            page_id=page_id,
+            parent=effective_parent or "",
+            title=resolved_title,
+            page_id=effective_page_id,
             dry_run=dry_run,
             backup=backup,
             progress_callback=ctx,
-            labels=label or [],
+            labels=merged_labels,
         )
         ctx.result = result
 

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

@@ -13,6 +13,8 @@ import re
 from html import escape
 from typing import Any
 
+import yaml
+
 from markdown_it import MarkdownIt
 from markdown_it.token import Token
 from mdit_py_plugins.tasklists import tasklists_plugin
@@ -747,6 +749,27 @@ def extract_h1_title(md_text: str) -> str | None:
     return None
 
 
+def extract_front_matter(md_text: str) -> dict[str, Any] | None:
+    """Extract YAML front-matter as a raw dict, or None.
+
+    Uses the markdown-it-py front_matter plugin to locate the block,
+    then parses with yaml.safe_load.  Returns None if no front-matter
+    is present, if the YAML is invalid, or if the result is not a mapping.
+    """
+    parser = _create_parser()
+    tokens = parser.parse(md_text)
+    for token in tokens:
+        if token.type == "front_matter":
+            try:
+                data = yaml.safe_load(token.content)
+            except yaml.YAMLError:
+                return None
+            if isinstance(data, dict):
+                return data
+            return None
+    return None
+
+
 def fingerprint_content(content: str) -> str:
     """Return SHA-256 hex digest of content."""
     return hashlib.sha256(content.encode("utf-8")).hexdigest()

confpub_cli-1.7.0/confpub/front_matter.py

@@ -0,0 +1,99 @@
+"""Front-matter extraction and validation for single-file publish.
+
+Parses YAML front-matter from Markdown files into a typed dataclass.
+Used only by `page publish`; manifest flows ignore front-matter entirely.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import Any
+
+from confpub.converter import extract_front_matter
+from confpub.errors import ERR_VALIDATION_MARKDOWN, ConfpubError
+
+
+@dataclass
+class FrontMatterData:
+    """Validated front-matter fields."""
+
+    title: str | None = None
+    space: str | None = None
+    parent: str | None = None
+    labels: list[str] = field(default_factory=list)
+    page_id: str | None = None
+
+
+def _validate_string(raw: dict[str, Any], key: str) -> str | None:
+    """Extract and validate a string field, or None if absent."""
+    val = raw.get(key)
+    if val is None:
+        return None
+    if not isinstance(val, str):
+        raise ConfpubError(
+            ERR_VALIDATION_MARKDOWN,
+            f"Front-matter field '{key}' must be a string, got {type(val).__name__}",
+            details={"field": key, "value_type": type(val).__name__},
+        )
+    return val
+
+
+def parse_front_matter(md_text: str) -> FrontMatterData | None:
+    """Extract and validate front-matter from Markdown text.
+
+    Returns a FrontMatterData with validated fields, or None if no
+    front-matter is present.  Unknown keys are silently ignored.
+
+    Raises ConfpubError (ERR_VALIDATION_MARKDOWN) on type errors.
+    """
+    raw = extract_front_matter(md_text)
+    if raw is None:
+        return None
+
+    title = _validate_string(raw, "title")
+    space = _validate_string(raw, "space")
+    parent = _validate_string(raw, "parent")
+
+    # labels: list[str] or single string → list[str]
+    labels_raw = raw.get("labels")
+    labels: list[str] = []
+    if labels_raw is not None:
+        if isinstance(labels_raw, str):
+            labels = [labels_raw]
+        elif isinstance(labels_raw, list):
+            for item in labels_raw:
+                if not isinstance(item, str):
+                    raise ConfpubError(
+                        ERR_VALIDATION_MARKDOWN,
+                        f"Front-matter 'labels' items must be strings, got {type(item).__name__}",
+                        details={"field": "labels", "value_type": type(item).__name__},
+                    )
+            labels = labels_raw
+        else:
+            raise ConfpubError(
+                ERR_VALIDATION_MARKDOWN,
+                f"Front-matter 'labels' must be a list or string, got {type(labels_raw).__name__}",
+                details={"field": "labels", "value_type": type(labels_raw).__name__},
+            )
+
+    # page_id: string or int → string
+    page_id_raw = raw.get("page_id")
+    page_id: str | None = None
+    if page_id_raw is not None:
+        if isinstance(page_id_raw, (str, int)):
+            page_id = str(page_id_raw)
+        else:
+            raise ConfpubError(
+                ERR_VALIDATION_MARKDOWN,
+                f"Front-matter 'page_id' must be a string or integer, got {type(page_id_raw).__name__}",
+                details={"field": "page_id", "value_type": type(page_id_raw).__name__},
+            )
+
+    return FrontMatterData(
+        title=title,
+        space=space,
+        parent=parent,
+        labels=labels,
+        page_id=page_id,
+    )

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

@@ -138,12 +138,12 @@ def build_guide() -> dict[str, Any]:
                 "description": "Publish a single Markdown file to Confluence",
                 "flags": ["--space", "--parent", "--title", "--title-from-h1", "--page-id", "--dry-run", "--backup", "--label"],
                 "agent_hint": (
-                    "Title precedence: explicit --title > --title-from-h1 (first H1 heading) > filename inference. "
-                    "When --title is omitted, the title is inferred from the filename: "
-                    "the stem is extracted, hyphens and underscores are replaced with spaces, "
-                    "and the result is title-cased. E.g. 'my-cool-page.md' → 'My Cool Page'. "
-                    "Use --title-from-h1 to extract the title from the first # heading in the file. "
-                    "Use --label to apply labels (repeatable): --label api --label docs. "
+                    "Title precedence: explicit --title > --title-from-h1 > front-matter title > filename inference. "
+                    "Space precedence: --space > front-matter space > CONFPUB_SPACE env var. "
+                    "Parent precedence: --parent > front-matter parent. "
+                    "Labels: CLI --label merged with front-matter labels (union, deduplicated). "
+                    "When writing Markdown files for publication, include YAML front-matter to embed metadata: "
+                    "---\\ntitle: Page Title\\nspace: SPACEKEY\\nparent: Parent Title\\nlabels:\\n  - tag1\\n---\\n "
                     "For personal spaces, quote the tilde: --space '~username' "
                     "(PowerShell expands unquoted ~). Or set CONFPUB_SPACE env var."
                 ),
@@ -402,7 +402,11 @@ def build_guide() -> dict[str, Any]:
                 "math_block":     "$$...$$ → ac:structured-macro mathblock",
                 "definition_lists": "Term\\n: Definition → <dl><dt><dd>",
                 "footnotes":      "[^1] + [^1]: text → superscript links with numbered list",
-                "front_matter":   "---\\nyaml\\n--- → silently stripped",
+                "front_matter": (
+                    "---\\nyaml\\n--- → extracted for page metadata "
+                    "(title, space, parent, labels, page_id); "
+                    "used by page.publish; ignored when a manifest is used"
+                ),
                 "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",
@@ -425,6 +429,47 @@ def build_guide() -> dict[str, Any]:
                 "Macros on their own line become block-level (no <p> wrapping)."
             ),
         },
+        "front_matter": {
+            "description": (
+                "YAML front-matter in Markdown files provides default page metadata for page.publish. "
+                "When a manifest (confpub.yaml) is used, front-matter is ignored entirely."
+            ),
+            "fields": {
+                "title": "Page title (string)",
+                "space": "Confluence space key (string)",
+                "parent": "Parent page title (string)",
+                "labels": "Labels to apply (list of strings, or single string)",
+                "page_id": "Confluence page ID for direct update (string or integer)",
+            },
+            "precedence": {
+                "title": "--title > --title-from-h1 > front-matter > filename",
+                "space": "--space > front-matter > CONFPUB_SPACE",
+                "parent": "--parent > front-matter",
+                "page_id": "--page-id > front-matter",
+                "labels": "CLI --label + front-matter labels merged (deduplicated)",
+            },
+            "example": (
+                "---\n"
+                "title: API Reference\n"
+                "space: DEV\n"
+                "parent: Documentation\n"
+                "labels:\n"
+                "  - api\n"
+                "  - public\n"
+                "---\n"
+                "\n"
+                "# API Reference\n"
+                "\n"
+                "Content here..."
+            ),
+            "agent_hint": (
+                "When creating Markdown files for Confluence publication, always include "
+                "front-matter with at least title, space, and parent so the file can be "
+                "published with just `confpub page publish <file>` — no extra flags needed. "
+                "Unknown front-matter keys (e.g. draft, author) are silently ignored, "
+                "so front-matter is compatible with other tools like Jekyll or Hugo."
+            ),
+        },
         "assertions": {
             "description": "Post-condition assertions verified by plan.verify.",
             "file_format": "JSON array of assertion objects, or embedded in confpub.yaml under the 'assertions' key.",

{confpub_cli-1.6.0 → confpub_cli-1.7.0}/confpub/publish.py

@@ -23,10 +23,16 @@ from confpub.errors import (
 from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, update_lockfile
 
 
-def derive_title(file: str, title: str | None = None, *, title_from_h1: bool = False) -> str:
-    """Derive page title from explicit title, H1 heading, or filename.
+def derive_title(
+    file: str,
+    title: str | None = None,
+    *,
+    title_from_h1: bool = False,
+    front_matter_title: str | None = None,
+) -> str:
+    """Derive page title from explicit title, H1 heading, front-matter, or filename.
 
-    Precedence: explicit --title > --title-from-h1 > filename inference.
+    Precedence: explicit --title > --title-from-h1 > front-matter > filename inference.
     """
     if title:
         return title
@@ -36,6 +42,8 @@ def derive_title(file: str, title: str | None = None, *, title_from_h1: bool = F
         h1 = extract_h1_title(md_text)
         if h1:
             return h1
+    if front_matter_title:
+        return front_matter_title
     return Path(file).stem.replace("-", " ").replace("_", " ").title()
 
 

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

@@ -1,6 +1,6 @@
 """Tests for confpub.converter module."""
 
-from confpub.converter import convert_markdown, extract_h1_title, fingerprint_content
+from confpub.converter import convert_markdown, extract_front_matter, extract_h1_title, fingerprint_content
 
 
 class TestHeadings:
@@ -419,3 +419,32 @@ class TestContainerLayout:
         result = convert_markdown(md)
         assert 'ac:type="three_equal"' in result
         assert result.count("<ac:layout-cell>") == 3
+
+
+class TestExtractFrontMatter:
+    def test_basic_extraction(self):
+        md = "---\ntitle: Hello\nspace: DEV\n---\n\n# Content"
+        result = extract_front_matter(md)
+        assert result is not None
+        assert result["title"] == "Hello"
+        assert result["space"] == "DEV"
+
+    def test_no_front_matter_returns_none(self):
+        md = "# Just a heading\n\nParagraph."
+        assert extract_front_matter(md) is None
+
+    def test_invalid_yaml_returns_none(self):
+        md = "---\n: invalid: yaml: {{{\n---\n\nContent"
+        assert extract_front_matter(md) is None
+
+    def test_non_mapping_returns_none(self):
+        md = "---\n- just\n- a\n- list\n---\n\nContent"
+        assert extract_front_matter(md) is None
+
+    def test_preserves_unknown_keys(self):
+        md = "---\ntitle: Page\nauthor: Alice\ndraft: true\n---\n\nContent"
+        result = extract_front_matter(md)
+        assert result is not None
+        assert result["title"] == "Page"
+        assert result["author"] == "Alice"
+        assert result["draft"] is True

confpub_cli-1.7.0/tests/test_front_matter.py

@@ -0,0 +1,98 @@
+"""Tests for confpub.front_matter module."""
+
+import pytest
+
+from confpub.errors import ConfpubError, ERR_VALIDATION_MARKDOWN
+from confpub.front_matter import FrontMatterData, parse_front_matter
+
+
+class TestParseFrontMatter:
+    def test_all_fields_populated(self):
+        md = (
+            "---\n"
+            "title: My Page\n"
+            "space: DEV\n"
+            "parent: Documentation\n"
+            "labels:\n"
+            "  - api\n"
+            "  - public\n"
+            "page_id: '123456'\n"
+            "---\n"
+            "\n"
+            "# Content\n"
+        )
+        fm = parse_front_matter(md)
+        assert fm is not None
+        assert fm.title == "My Page"
+        assert fm.space == "DEV"
+        assert fm.parent == "Documentation"
+        assert fm.labels == ["api", "public"]
+        assert fm.page_id == "123456"
+
+    def test_partial_fields(self):
+        md = "---\ntitle: Just Title\n---\n\nContent"
+        fm = parse_front_matter(md)
+        assert fm is not None
+        assert fm.title == "Just Title"
+        assert fm.space is None
+        assert fm.parent is None
+        assert fm.labels == []
+        assert fm.page_id is None
+
+    def test_no_front_matter_returns_none(self):
+        md = "# No front matter\n\nJust content."
+        assert parse_front_matter(md) is None
+
+    def test_single_string_labels_coercion(self):
+        md = "---\nlabels: api\n---\n\nContent"
+        fm = parse_front_matter(md)
+        assert fm is not None
+        assert fm.labels == ["api"]
+
+    def test_int_page_id_coercion(self):
+        md = "---\npage_id: 789\n---\n\nContent"
+        fm = parse_front_matter(md)
+        assert fm is not None
+        assert fm.page_id == "789"
+
+    def test_unknown_keys_ignored(self):
+        md = "---\ntitle: Page\nauthor: Alice\ndraft: true\n---\n\nContent"
+        fm = parse_front_matter(md)
+        assert fm is not None
+        assert fm.title == "Page"
+        # No error from unknown keys
+
+    def test_title_as_list_raises(self):
+        md = "---\ntitle:\n  - one\n  - two\n---\n\nContent"
+        with pytest.raises(ConfpubError) as exc_info:
+            parse_front_matter(md)
+        assert exc_info.value.code == ERR_VALIDATION_MARKDOWN
+        assert "title" in exc_info.value.error_message
+
+    def test_labels_as_int_raises(self):
+        md = "---\nlabels: 42\n---\n\nContent"
+        with pytest.raises(ConfpubError) as exc_info:
+            parse_front_matter(md)
+        assert exc_info.value.code == ERR_VALIDATION_MARKDOWN
+        assert "labels" in exc_info.value.error_message
+
+    def test_labels_with_non_string_item_raises(self):
+        md = "---\nlabels:\n  - good\n  - 123\n---\n\nContent"
+        with pytest.raises(ConfpubError) as exc_info:
+            parse_front_matter(md)
+        assert exc_info.value.code == ERR_VALIDATION_MARKDOWN
+        assert "labels" in exc_info.value.error_message
+
+    def test_page_id_as_list_raises(self):
+        md = "---\npage_id:\n  - 1\n  - 2\n---\n\nContent"
+        with pytest.raises(ConfpubError) as exc_info:
+            parse_front_matter(md)
+        assert exc_info.value.code == ERR_VALIDATION_MARKDOWN
+        assert "page_id" in exc_info.value.error_message
+
+    def test_space_as_int_raises(self):
+        md = "---\nspace: 42\n---\n\nContent"
+        with pytest.raises(ConfpubError) as exc_info:
+            parse_front_matter(md)
+        assert exc_info.value.code == ERR_VALIDATION_MARKDOWN
+        assert "space" in exc_info.value.error_message

{confpub_cli-1.6.0 → confpub_cli-1.7.0}/tests/test_guide.py

@@ -137,7 +137,7 @@ class TestBuildGuide:
         guide = build_guide()
         cmd = guide["commands"]["page.publish"]
         assert "agent_hint" in cmd
-        assert "title-cased" in cmd["agent_hint"]
+        assert "filename inference" in cmd["agent_hint"]
 
     def test_page_pull_has_progress_hint(self):
         guide = build_guide()

{confpub_cli-1.6.0 → confpub_cli-1.7.0}/tests/test_integration.py

@@ -551,3 +551,105 @@ class TestEnvelopeContract:
         assert isinstance(data["metrics"], dict)
         assert "duration_ms" in data["metrics"]
         assert data["request_id"].startswith("req_")
+
+
+class TestPagePublishFrontMatter:
+    """Front-matter provides defaults for page publish."""
+
+    def test_front_matter_provides_space_and_parent(self, tmp_path, monkeypatch):
+        """Front-matter space/parent used when no CLI flags given."""
+        md = "---\ntitle: FM Page\nspace: DEV\nparent: Docs\n---\n\n# Content"
+        md_file = tmp_path / "page.md"
+        md_file.write_text(md)
+
+        from confpub.confluence import ConfluenceClient
+        from unittest.mock import MagicMock
+
+        mock_client = MagicMock()
+        mock_client.get_page.return_value = None
+        mock_client.create_page.return_value = {"id": "new_1", "version": {"number": 1}}
+        mock_client.get_attachments.return_value = []
+
+        monkeypatch.setattr("confpub.publish.load_config", lambda: MagicMock())
+        monkeypatch.setattr("confpub.publish.ConfluenceClient", lambda cfg: mock_client)
+
+        result = runner.invoke(app, ["page", "publish", str(md_file)])
+        assert result.exit_code == 0, result.output
+        data = json.loads(result.output)
+        assert data["ok"] is True
+        assert data["result"]["changes"][0]["title"] == "FM Page"
+
+    def test_cli_flags_override_front_matter(self, tmp_path, monkeypatch):
+        """CLI flags take precedence over front-matter values."""
+        md = "---\ntitle: FM Title\nspace: FMSPACE\nparent: FM Parent\n---\n\n# Content"
+        md_file = tmp_path / "page.md"
+        md_file.write_text(md)
+
+        from unittest.mock import MagicMock
+
+        mock_client = MagicMock()
+        mock_client.get_page.return_value = None
+        mock_client.create_page.return_value = {"id": "new_2", "version": {"number": 1}}
+        mock_client.get_attachments.return_value = []
+
+        monkeypatch.setattr("confpub.publish.load_config", lambda: MagicMock())
+        monkeypatch.setattr("confpub.publish.ConfluenceClient", lambda cfg: mock_client)
+
+        result = runner.invoke(app, [
+            "page", "publish", str(md_file),
+            "--space", "CLISPACE",
+            "--parent", "CLI Parent",
+            "--title", "CLI Title",
+        ])
+        assert result.exit_code == 0, result.output
+        data = json.loads(result.output)
+        assert data["ok"] is True
+        assert data["result"]["changes"][0]["title"] == "CLI Title"
+        # Verify the CLI space was used (passed to create_page)
+        call_args = mock_client.create_page.call_args
+        assert call_args[0][0] == "CLISPACE"
+
+    def test_labels_merge_cli_and_front_matter(self, tmp_path, monkeypatch):
+        """CLI labels and front-matter labels are merged (deduplicated)."""
+        md = "---\nspace: DEV\nparent: Docs\nlabels:\n  - fm1\n  - shared\n---\n\nContent"
+        md_file = tmp_path / "page.md"
+        md_file.write_text(md)
+
+        from unittest.mock import MagicMock
+
+        mock_client = MagicMock()
+        mock_client.get_page.return_value = None
+        mock_client.create_page.return_value = {"id": "new_3", "version": {"number": 1}}
+        mock_client.get_attachments.return_value = []
+        mock_client.set_labels.return_value = []
+
+        monkeypatch.setattr("confpub.publish.load_config", lambda: MagicMock())
+        monkeypatch.setattr("confpub.publish.ConfluenceClient", lambda cfg: mock_client)
+
+        result = runner.invoke(app, [
+            "page", "publish", str(md_file),
+            "--label", "cli1",
+            "--label", "shared",
+        ])
+        assert result.exit_code == 0, result.output
+        data = json.loads(result.output)
+        assert data["ok"] is True
+        # Labels should be merged and deduplicated
+        labels_call = mock_client.set_labels.call_args[0][1]
+        assert "cli1" in labels_call
+        assert "fm1" in labels_call
+        assert "shared" in labels_call
+        # No duplicates
+        assert len(labels_call) == len(set(labels_call))
+
+    def test_no_front_matter_existing_behavior(self, tmp_path):
+        """Without front-matter, missing --space still raises an error."""
+        md = "# Plain Page\n\nNo front-matter here."
+        md_file = tmp_path / "plain.md"
+        md_file.write_text(md)
+
+        result = runner.invoke(app, ["page", "publish", str(md_file)])
+        assert result.exit_code == 10
+        data = json.loads(result.output)
+        assert data["ok"] is False
+        assert "space" in data["errors"][0]["message"].lower()

{confpub_cli-1.6.0 → confpub_cli-1.7.0}/tests/test_publish.py

@@ -65,6 +65,26 @@ class TestDeriveTitle:
         assert derive_title(str(md_file), "Explicit Title", title_from_h1=True) == "Explicit Title"
 
 
+class TestDeriveTitleFrontMatter:
+    def test_front_matter_title_used_as_fallback(self):
+        assert derive_title("some-file.md", front_matter_title="FM Title") == "FM Title"
+
+    def test_cli_title_wins_over_front_matter(self):
+        assert derive_title("some-file.md", "CLI Title", front_matter_title="FM Title") == "CLI Title"
+
+    def test_h1_wins_over_front_matter(self, tmp_path):
+        md_file = tmp_path / "test.md"
+        md_file.write_text("# H1 Title\n\nContent here.")
+        result = derive_title(str(md_file), title_from_h1=True, front_matter_title="FM Title")
+        assert result == "H1 Title"
+
+    def test_front_matter_beats_filename(self):
+        assert derive_title("my-cool-page.md", front_matter_title="Better Title") == "Better Title"
+
+    def test_no_front_matter_falls_through_to_filename(self):
+        assert derive_title("my-cool-page.md", front_matter_title=None) == "My Cool Page"
+
+
 class TestPublishDryRun:
     @patch("confpub.publish.load_config")
     @patch("confpub.publish.ConfluenceClient")