confpub-cli 0.2.2__tar.gz → 0.2.3__tar.gz

confpub_cli-0.2.3/FEEDBACK.md

@@ -0,0 +1,118 @@
+# confpub-cli v0.2.2 — Blind Test Feedback
+
+**Tester:** Claude Code (Opus 4.6), acting as an LLM agent
+**Date:** 2026-03-01
+**Method:** Zero-shot exploration starting from `uvx confpub-cli --help`, then progressively deeper testing of every subcommand, error path, and workflow.
+
+---
+
+## Overall Impression
+
+confpub is a **remarkably well-designed agent-first CLI**. The `guide` command as a single bootstrap entry point is a standout idea — I was able to learn the entire CLI schema, error codes, auth precedence, and concurrency rules in one call. The structured JSON envelope on stdout with progress on stderr is exactly right for machine consumption. This is one of the best-designed CLIs I've encountered for agent integration.
+
+**Score: 8.5/10** — excellent foundation, a few rough edges to polish.
+
+---
+
+## What Works Well
+
+### 1. The `guide` command is brilliant
+One call to `confpub guide` gave me everything: all commands with flags, mutation indicators, error codes with exit codes and retry hints, auth precedence, and concurrency rules. The `--section` filter is a nice touch. This is the gold standard for agent-discoverability.
+
+### 2. Structured JSON envelope is consistent
+Every response — success or failure — follows the same shape: `schema_version`, `request_id`, `ok`, `command`, `target`, `result`, `warnings`, `errors`, `metrics`. I never had to guess the format. The `request_id` is useful for log correlation.
+
+### 3. Error codes are stable and actionable
+`ERR_IO_FILE_NOT_FOUND` with `retryable: true` and `suggested_action: "retry"` — that's exactly what an agent needs. The exit code bucketing (10=validation, 20=auth, 40=conflict, 50=IO, 90=internal) is clean. I could build a robust retry/escalation loop from just the `guide --section error_codes` output.
+
+### 4. Transactional plan workflow
+The `plan create → validate → apply → verify` pipeline with fingerprint-based conflict detection is a strong design. Separating the plan artifact from execution lets an agent inspect and reason about changes before committing. The `--dry-run` flag on both `page publish` and `plan apply` is essential.
+
+### 5. Safety annotations
+The `safety_flags` in the guide output (e.g., `--cascade: "Also deletes child pages"`) are a great signal for agents to ask for human confirmation before using dangerous flags.
+
+### 6. Auth precedence is well-thought-out
+CLI flags → env vars → config file → OS keychain, with `LLM=true` suppressing interactive prompts — exactly right.
+
+### 7. Mutation markers
+Every command in the guide is tagged with `mutates: true/false` and grouped (`read`, `write`, `transactional`). This makes it trivial for an agent to know which commands are safe to call speculatively.
+
+---
+
+## Issues Found
+
+### Bug: `--quiet` flag does not suppress stderr
+
+**Severity:** Medium
+**Steps:** Run `confpub-cli --quiet page publish page.md --space SD --parent "Software Development" --dry-run` and capture stderr.
+**Expected:** stderr should be empty (or at least suppress the "Can't find..." message).
+**Actual:** The message `Can't find 'Page' page on https://thomasklokrohde.atlassian.net/wiki` still appears on stderr, identical to the non-quiet run.
+
+### Bug: `target.title` shows raw filename instead of resolved title
+
+**Severity:** Low
+**Steps:** Run `page publish page.md --space SD --parent "..." --dry-run` (no `--title` flag).
+**Expected:** `target.title` should be `"Page"` (the resolved title).
+**Actual:** `target.title` is `"page.md"` (the raw filename), while the actual page title used in `result.changes` is `"Page"`. An agent parsing `target.title` would get the wrong value.
+
+### Bug: Nonexistent space returns `ERR_INTERNAL_SDK` (exit 90) instead of a specific error
+
+**Severity:** Medium
+**Steps:** Run `page inspect --space NONEXISTENT --title "nope"`.
+**Expected:** A specific error like `ERR_AUTH_FORBIDDEN` (exit 20) or a new `ERR_NOT_FOUND` code.
+**Actual:** Returns `ERR_INTERNAL_SDK` with exit code 90 and `suggested_action: "escalate"`. The message is `"Unexpected API error (get_page): The calling user does not have permission to view the content"`. This is misleading — it's not an internal error, it's a permissions/not-found issue. An agent following the `escalate` suggestion would file a bug report instead of trying a different space key.
+
+### Rough edge: `--verbose` flag has no visible effect
+
+**Severity:** Low
+**Steps:** Compare `auth inspect` output with and without `--verbose`.
+**Observation:** The JSON output is identical. No extra diagnostics field, no additional stderr output. Either verbose mode isn't implemented yet, or its effect is too subtle to observe.
+
+### Rough edge: `page.list` and `page.inspect` responses are extremely verbose
+
+**Severity:** Medium (for agent consumption)
+**Observation:** These commands return the raw Confluence API response including `_expandable`, `_links`, `macroRenderedOutput`, `profilePicture`, `accountType`, etc. A single `page.list` for 5 pages produced ~300 lines of JSON. For an agent working within a context window, this is wasteful. A slimmed-down response with just `id`, `title`, `version.number`, `version.when`, and `webui` link would be far more token-efficient. The full raw response could be available behind `--verbose` or a `--raw` flag.
+
+### Rough edge: Manifest validation error exposes raw Pydantic internals
+
+**Severity:** Low
+**Steps:** Submit a manifest missing `parent` and `pages.0.title`.
+**Actual message:**
+```
+Invalid manifest: 2 validation errors for Manifest
+parent
+  Field required [type=missing, input_value={'space': 'SD', ...}, input_type=dict]
+    For further information visit https://errors.pydantic.dev/2.12/v/missing
+```
+**Suggestion:** Wrap Pydantic errors into a cleaner `details` array, e.g.:
+```json
+"details": {
+  "missing_fields": ["parent", "pages[0].title"]
+}
+```
+The raw Pydantic output with `input_value`, `input_type`, and the pydantic.dev URL leaks implementation details.
+
+---
+
+## Suggestions
+
+### 1. Add a `--compact` or `--slim` output mode
+For agent use, return only the fields that matter. The full Confluence API payloads in `page.list` and `page.inspect` are 10x more data than an agent needs. This would significantly reduce token usage.
+
+### 2. Consider a `page.get-body` subcommand (or flag)
+`page.inspect` returns the full storage-format body inline, which is great for inspection but makes the response enormous. A `--no-body` flag on inspect (or a separate `page.body` command) would let agents choose when they need content vs. metadata.
+
+### 3. Add `schema_version` to the manifest validation error
+When a manifest is missing `schema_version`, the error message mentions `parent` and `pages.0.title` but doesn't flag the missing `schema_version`. (Tested: a manifest without `schema_version` but with `parent` was accepted — so it appears optional. The README says it should be there. Clarify whether it's required.)
+
+### 4. The `config set` subcommand help is sparse
+`config set --help` doesn't show what keys are valid or their expected values. Adding a `config list-keys` or including examples in the help text would help.
+
+### 5. Document the title-from-filename behavior
+The help text says `--title TEXT  Page title (defaults to filename)` but the actual behavior is "filename without extension, title-cased" (e.g., `test-confpub.md` → `Test Confpub`, `page.md` → `Page`). Document the transformation rule.
+
+---
+
+## Summary
+
+confpub nails the core agent-first design philosophy: structured output, stable error codes, a self-describing `guide` command, mutation markers, safety annotations, and a clean transactional workflow. The main areas for improvement are (1) trimming the verbose Confluence API payloads for agent-friendly output, (2) fixing the `--quiet` bug, and (3) better error classification for permission/not-found cases vs. true internal errors. This is a tool I'd be confident integrating into an autonomous agent workflow today.

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/PKG-INFO

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

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

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/confpub/cli.py

@@ -16,7 +16,7 @@ import typer
 from confpub import __version__
 from confpub.envelope import Envelope
 from confpub.errors import ConfpubError, exit_code_for, ERR_INTERNAL_SDK
-from confpub.output import emit_stderr, emit_stdout, set_quiet, set_verbose
+from confpub.output import emit_stderr, emit_stdout, is_verbose, set_quiet, set_verbose
 
 # ---------------------------------------------------------------------------
 # Subcommand group apps
@@ -101,6 +101,9 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
     except ConfpubError as e:
         duration_ms = int((time.monotonic() - start) * 1000)
         ctx.metrics["duration_ms"] = duration_ms
+        if is_verbose():
+            import traceback as tb
+            ctx.metrics["diagnostics"] = {"traceback": tb.format_exc()}
         envelope = Envelope.failure(
             command_name,
             [e],
@@ -133,6 +136,12 @@ def command_context(command_name: str, target: dict[str, Any] | None = None) ->
     else:
         duration_ms = int((time.monotonic() - start) * 1000)
         ctx.metrics["duration_ms"] = duration_ms
+        if is_verbose():
+            ctx.metrics["diagnostics"] = {
+                "command": command_name,
+                "target": ctx.target,
+                "warning_count": len(ctx.warnings),
+            }
         envelope = Envelope.success(
             command_name,
             ctx.result,
@@ -154,11 +163,10 @@ def page_list(
 ) -> None:
     """List pages in a Confluence space."""
     with command_context("page.list", target={"space": space}) as ctx:
-        # Phase 6: delegate to confluence.list_pages
-        from confpub.confluence import build_client
+        from confpub.confluence import build_client, _slim_page
         client = build_client()
         pages = client.list_pages(space)
-        ctx.result = {"pages": pages}
+        ctx.result = {"pages": [_slim_page(p) for p in pages]}
 
 
 @page_app.command("inspect")
@@ -166,10 +174,11 @@ def page_inspect(
     space: str = typer.Option(None, "--space", help="Confluence space key"),
     title: str = typer.Option(None, "--title", help="Page title"),
     page_id: str = typer.Option(None, "--page-id", help="Confluence page ID"),
+    raw: bool = typer.Option(False, "--raw", help="Return full raw API response"),
 ) -> None:
     """Inspect a Confluence page."""
     with command_context("page.inspect", target={"space": space, "title": title, "page_id": page_id}) as ctx:
-        from confpub.confluence import build_client
+        from confpub.confluence import build_client, _slim_page
         client = build_client()
         if page_id:
             page = client.get_page_by_id(page_id)
@@ -178,7 +187,7 @@ def page_inspect(
             if not space or not title:
                 raise validation_error(ERR_VALIDATION_REQUIRED, "Either --page-id or both --space and --title are required")
             page = client.get_page(space, title)
-        ctx.result = page
+        ctx.result = page if raw else _slim_page(page) if page else page
 
 
 @page_app.command("publish")
@@ -186,12 +195,14 @@ def page_publish(
     file: str = typer.Argument(..., help="Markdown file to publish"),
     space: str = typer.Option(..., "--space", help="Confluence space key"),
     parent: str = typer.Option(..., "--parent", help="Parent page title"),
-    title: Optional[str] = typer.Option(None, "--title", help="Page title (defaults to filename)"),
+    title: Optional[str] = typer.Option(None, "--title", help="Page title (defaults to filename stem, hyphen/underscore→spaces, title-cased)"),
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without writing"),
     backup: bool = typer.Option(False, "--backup", help="Backup existing page before overwriting"),
 ) -> None:
     """Publish a single Markdown file to Confluence."""
-    target = {"space": space, "title": title or file, "file": file}
+    from confpub.publish import derive_title
+    resolved_title = derive_title(file, title)
+    target = {"space": space, "title": resolved_title, "file": file}
     with command_context("page.publish", target=target) as ctx:
         from confpub.publish import publish_page
         result = publish_page(
@@ -329,7 +340,7 @@ def auth_inspect() -> None:
 
 @config_app.command("set")
 def config_set(
-    key: str = typer.Argument(..., help="Configuration key"),
+    key: str = typer.Argument(..., help="Configuration key (base_url, user, token)"),
     value: str = typer.Argument(..., help="Configuration value"),
 ) -> None:
     """Set a configuration value."""

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/confpub/confluence.py

@@ -59,6 +59,20 @@ class ConfluenceClient:
             raise ConfpubError(ERR_IO_TIMEOUT, f"Request timed out: {msg}") from exc
         if "ConnectionError" in msg or "connection" in msg.lower():
             raise ConfpubError(ERR_IO_CONNECTION, f"Connection failed: {msg}") from exc
+        # Permission denied (e.g., nonexistent space, restricted content)
+        if "permission" in msg.lower() or "not permitted" in msg.lower():
+            raise ConfpubError(
+                ERR_AUTH_FORBIDDEN,
+                f"Permission denied ({context}): {msg}",
+                suggested_action="escalate",
+            ) from exc
+        # Not found (404 or explicit "not found")
+        if "404" in msg or "not found" in msg.lower():
+            from confpub.errors import ERR_IO_FILE_NOT_FOUND
+            raise ConfpubError(
+                ERR_IO_FILE_NOT_FOUND,
+                f"Resource not found ({context}): {msg}",
+            ) from exc
         raise ConfpubError(ERR_INTERNAL_SDK, f"Unexpected API error ({context}): {msg}") from exc
 
     # ------------------------------------------------------------------
@@ -229,6 +243,29 @@ class ConfluenceClient:
             return None
 
 
+def _slim_page(page: dict[str, Any]) -> dict[str, Any]:
+    """Extract agent-relevant fields from a raw Confluence page object."""
+    result: dict[str, Any] = {
+        "id": page.get("id"),
+        "title": page.get("title"),
+    }
+    version = page.get("version")
+    if isinstance(version, dict):
+        result["version"] = {
+            "number": version.get("number"),
+            "when": version.get("when"),
+            "by": version.get("by", {}).get("displayName") if isinstance(version.get("by"), dict) else None,
+        }
+    body = page.get("body", {}).get("storage", {}).get("value")
+    if body is not None:
+        result["body_storage"] = body
+    links = page.get("_links", {})
+    if "webui" in links:
+        base = links.get("base", "")
+        result["webui"] = base + links["webui"]
+    return result
+
+
 def build_client(
     cli_url: str | None = None,
     cli_user: str | None = None,

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/confpub/manifest.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Literal, Optional
 
 import yaml
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, ValidationError, model_validator
 
 from confpub.errors import ERR_VALIDATION_MANIFEST, ConfpubError
 
@@ -150,6 +150,18 @@ def load_manifest(path: str) -> Manifest:
         return Manifest(**data)
     except ConfpubError:
         raise
+    except ValidationError as exc:
+        details = {
+            "validation_errors": [
+                {"field": ".".join(str(loc) for loc in e["loc"]), "message": e["msg"]}
+                for e in exc.errors()
+            ]
+        }
+        raise ConfpubError(
+            ERR_VALIDATION_MANIFEST,
+            f"Invalid manifest: {len(exc.errors())} validation error(s)",
+            details=details,
+        ) from exc
     except Exception as exc:
         raise ConfpubError(
             ERR_VALIDATION_MANIFEST,

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/confpub/output.py

@@ -75,6 +75,8 @@ def emit_progress(step: int, total: int, message: str) -> None:
 
 
 def emit_stderr(message: str) -> None:
-    """Write a diagnostic message to stderr."""
+    """Write a diagnostic message to stderr. Suppressed in quiet mode."""
+    if is_quiet():
+        return
     sys.stderr.write(message + "\n")
     sys.stderr.flush()

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/confpub/publish.py

@@ -22,6 +22,13 @@ from confpub.errors import (
 from confpub.lockfile import Lockfile, load_lockfile, save_lockfile, update_lockfile
 
 
+def derive_title(file: str, title: str | None = None) -> str:
+    """Derive page title from explicit title or filename."""
+    if title:
+        return title
+    return Path(file).stem.replace("-", " ").replace("_", " ").title()
+
+
 def publish_page(
     file: str,
     space: str,
@@ -44,7 +51,7 @@ def publish_page(
         )
 
     # Derive title from filename if not provided
-    page_title = title or source_path.stem.replace("-", " ").replace("_", " ").title()
+    page_title = derive_title(file, title)
 
     # Read and convert
     md_text = source_path.read_text(encoding="utf-8")

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/tests/test_confluence.py

@@ -5,12 +5,13 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from confpub.config import ResolvedConfig
-from confpub.confluence import ConfluenceClient
+from confpub.confluence import ConfluenceClient, _slim_page
 from confpub.errors import (
     ERR_AUTH_FORBIDDEN,
     ERR_AUTH_REQUIRED,
     ERR_CONFLICT_PAGE_EXISTS,
     ERR_IO_CONNECTION,
+    ERR_IO_FILE_NOT_FOUND,
     ERR_INTERNAL_SDK,
     ConfpubError,
 )
@@ -148,8 +149,73 @@ class TestErrorTranslation:
             client.list_spaces()
         assert exc_info.value.code == ERR_IO_CONNECTION
 
+    def test_permission_error(self, client):
+        client._mock_api.get_all_spaces.side_effect = Exception(
+            "User does not have permission to view the content"
+        )
+        with pytest.raises(ConfpubError) as exc_info:
+            client.list_spaces()
+        assert exc_info.value.code == ERR_AUTH_FORBIDDEN
+
+    def test_not_found_error(self, client):
+        client._mock_api.get_all_spaces.side_effect = Exception("404 Not Found")
+        with pytest.raises(ConfpubError) as exc_info:
+            client.list_spaces()
+        assert exc_info.value.code == ERR_IO_FILE_NOT_FOUND
+
     def test_generic_error(self, client):
         client._mock_api.get_all_spaces.side_effect = Exception("Something weird happened")
         with pytest.raises(ConfpubError) as exc_info:
             client.list_spaces()
         assert exc_info.value.code == ERR_INTERNAL_SDK
+
+
+class TestSlimPage:
+    def test_extracts_basic_fields(self):
+        page = {"id": "123", "title": "Test Page", "_expandable": {"stuff": "..."}}
+        result = _slim_page(page)
+        assert result == {"id": "123", "title": "Test Page"}
+        assert "_expandable" not in result
+
+    def test_extracts_version(self):
+        page = {
+            "id": "123",
+            "title": "Test",
+            "version": {
+                "number": 5,
+                "when": "2025-01-01T00:00:00Z",
+                "by": {"displayName": "Alice", "profilePicture": "/avatar.png"},
+                "minorEdit": False,
+            },
+        }
+        result = _slim_page(page)
+        assert result["version"] == {
+            "number": 5,
+            "when": "2025-01-01T00:00:00Z",
+            "by": "Alice",
+        }
+
+    def test_extracts_body_storage(self):
+        page = {
+            "id": "1",
+            "title": "T",
+            "body": {"storage": {"value": "<p>hi</p>", "representation": "storage"}},
+        }
+        result = _slim_page(page)
+        assert result["body_storage"] == "<p>hi</p>"
+
+    def test_extracts_webui_link(self):
+        page = {
+            "id": "1",
+            "title": "T",
+            "_links": {"base": "https://wiki.example.com", "webui": "/spaces/DEV/pages/1"},
+        }
+        result = _slim_page(page)
+        assert result["webui"] == "https://wiki.example.com/spaces/DEV/pages/1"
+
+    def test_omits_missing_optional_fields(self):
+        page = {"id": "1", "title": "T"}
+        result = _slim_page(page)
+        assert "version" not in result
+        assert "body_storage" not in result
+        assert "webui" not in result

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/tests/test_integration.py

@@ -22,7 +22,7 @@ class TestCLIHelp:
     def test_version(self):
         result = runner.invoke(app, ["--version"])
         assert result.exit_code == 0
-        assert "0.1.0" in result.output
+        assert "confpub" in result.output
 
     def test_page_help(self):
         result = runner.invoke(app, ["page", "--help"])

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/tests/test_manifest.py

@@ -170,6 +170,39 @@ class TestResolvePageTree:
         assert flat[0].assets == ["img/*.png"]
 
 
+class TestManifestValidationErrors:
+    def test_pydantic_errors_are_clean(self, tmp_path):
+        """Pydantic ValidationError should produce clean details, not raw internals."""
+        f = tmp_path / "bad_manifest.yaml"
+        # conflict_strategy only allows "fail", "overwrite", "skip"
+        f.write_text("space: DEV\nparent: Root\nconflict_strategy: invalid_value\n")
+        with pytest.raises(ConfpubError) as exc_info:
+            load_manifest(str(f))
+        err = exc_info.value
+        assert err.code == ERR_VALIDATION_MANIFEST
+        assert "validation error" in err.error_message
+        assert "validation_errors" in err.details
+        for entry in err.details["validation_errors"]:
+            assert "field" in entry
+            assert "message" in entry
+            # Should not contain raw Pydantic internals
+            assert "input_value" not in str(entry)
+            assert "pydantic" not in str(entry).lower()
+
+    def test_missing_required_fields(self, tmp_path):
+        """Missing required fields produce clean validation errors."""
+        f = tmp_path / "minimal.yaml"
+        f.write_text("labels: []\n")  # missing space and parent
+        with pytest.raises(ConfpubError) as exc_info:
+            load_manifest(str(f))
+        err = exc_info.value
+        assert err.code == ERR_VALIDATION_MANIFEST
+        assert "validation_errors" in err.details
+        fields = [e["field"] for e in err.details["validation_errors"]]
+        assert "space" in fields
+        assert "parent" in fields
+
+
 class TestPlanArtifact:
     def test_create_plan(self):
         plan = PlanArtifact(

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/tests/test_output.py

@@ -85,6 +85,15 @@ class TestEmitProgress:
 
 class TestEmitStderr:
     def test_writes_to_stderr(self, capsys):
+        set_quiet(False)
         emit_stderr("debug info")
         captured = capsys.readouterr()
         assert "debug info" in captured.err
+        set_quiet(None)  # type: ignore[arg-type]
+
+    def test_suppressed_in_quiet_mode(self, capsys):
+        set_quiet(True)
+        emit_stderr("should not appear")
+        captured = capsys.readouterr()
+        assert captured.err == ""
+        set_quiet(None)  # type: ignore[arg-type]

{confpub_cli-0.2.2 → confpub_cli-0.2.3}/tests/test_publish.py

@@ -7,7 +7,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from confpub.errors import ConfpubError, ERR_IO_FILE_NOT_FOUND
-from confpub.publish import publish_page
+from confpub.publish import derive_title, publish_page
 
 
 @pytest.fixture
@@ -30,6 +30,23 @@ def mock_client():
     return client
 
 
+class TestDeriveTitle:
+    def test_explicit_title_wins(self):
+        assert derive_title("some-file.md", "My Custom Title") == "My Custom Title"
+
+    def test_derives_from_filename(self):
+        assert derive_title("my-cool-page.md") == "My Cool Page"
+
+    def test_underscores_to_spaces(self):
+        assert derive_title("api_reference.md") == "Api Reference"
+
+    def test_mixed_separators(self):
+        assert derive_title("my-api_docs.md") == "My Api Docs"
+
+    def test_path_uses_stem_only(self):
+        assert derive_title("docs/subfolder/overview.md") == "Overview"
+
+
 class TestPublishDryRun:
     @patch("confpub.publish.load_config")
     @patch("confpub.publish.ConfluenceClient")