feat: implement conflict-aware draft updates (release 0.10.0)

Author: ma2za

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.10.0
+
+### Added
+
+- Export a stable remote revision fingerprint in Markdown backup metadata via
+  `python-substack-revision:v1` markers.
+- Conflict-aware draft updates: compare submitted expected revision with current
+  remote draft before any write, preventing silent overwrites of remote changes.
+- Return actionable mismatch details (body changes, title, subtitle, audience,
+  permissions, section, slug) during dry-run updates (`--dry-run --yes`).
+- Fail closed by default on conflicted updates or missing revision metadata
+  (unprotected updates).
+- Add explicit override via `--allow-conflict` / `--force` (requiring `--yes`)
+  in CLI and `allow_conflict=True` / `force=True` in SDK.
+- Export `revision` dictionary metadata in `Api.export_draft_to_markdown` and
+  CLI `--json drafts export`.
+- Introduce `DraftConflictError` exception inheriting from both `ValueError` and
+  `SubstackException`.
+
 ## 0.9.1
 
 ### Added

docs/cli.md

@@ -55,8 +55,16 @@ Updates preserve unsupported editor nodes exported as
 `python-substack-image:v2` markers. The command refuses to remove or alter
 those nodes by default. `--allow-unsupported-change` and
 `--allow-image-replacement` are available only with `--yes` for intentional
-modifications or unmatched image replacements. The CLI uses its authenticated
-API client while rendering, so local images can upload even during a dry run.
+modifications or unmatched image replacements.
+
+Draft updates also verify the revision fingerprint exported in
+`python-substack-revision:v1` markers. If remote draft changes occurred after
+export, the update fails closed to prevent overwriting remote work. Dry-run
+updates (`--dry-run --yes`) report specific mismatch details. Markdown files
+lacking revision metadata are treated as unprotected updates. Pass
+`--allow-conflict --yes` (or `--force --yes`) to explicitly override conflicts
+or apply unprotected updates. The CLI uses its authenticated API client while
+rendering, so local images can upload even during a dry run.
 
 ## Select a publication
 

docs/markdown.md

@@ -219,3 +219,22 @@ reused, or non-adjacent markers are rejected. Unmatched image replacements requi
 `allow_image_replacement=True` or `--allow-image-replacement --yes`. Legacy `v1`
 image markers remain supported when the image source resolves to exactly one
 remote image.
+
+## Revision fingerprint and conflict prevention
+
+Exported Markdown drafts include a top-level revision marker:
+
+```text
+<!-- python-substack-revision:v1 BASE64URL_JSON -->
+```
+
+The payload contains the exported `draft_id`, a deterministic SHA-256 body hash,
+title, subtitle, audience, comment permissions, section ID, slug, and timestamp.
+On draft update, `python-substack` compares the submitted expected revision
+against the current remote draft before any write. If remote changes were made
+after export, the update fails closed with `DraftConflictError` to prevent silent
+data loss. Dry-run updates (`--dry-run --yes`) return actionable mismatch
+details. Older Markdown files without revision metadata are treated as
+unprotected updates. Conflicted or unprotected updates require explicit
+authorization with `allow_conflict=True` (or `force=True`) in Python or
+`--allow-conflict --yes` (or `--force --yes`) in the CLI.

docs/python-sdk.md

@@ -73,3 +73,11 @@ default. Removing or changing them raises `ValueError` unless
 `allow_unsupported_change=True` is deliberately supplied. Similarly, image
 replacements that cannot resolve to their original remote source require
 `allow_image_replacement=True`.
+
+The method verifies the revision fingerprint from `python-substack-revision:v1`
+markers before updating. If the remote draft changed after export, it raises
+`DraftConflictError` unless `allow_conflict=True` (or `force=True`) is passed.
+Files lacking revision metadata are treated as unprotected updates and also
+require `allow_conflict=True`. In dry-run mode (`dry_run=True`), conflict
+status and specific mismatch details are returned in `preview["conflict"]` and
+`preview["mismatches"]`.

docs/releases/0.10.0.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: Release 0.10.0
+parent: Releases
+---
+
+# Release 0.10.0
+
+## Added
+
+- Export a stable remote revision fingerprint in Markdown backup metadata via
+  `python-substack-revision:v1` markers.
+- Conflict-aware draft updates: compare submitted expected revision with current
+  remote draft before any write, preventing silent overwrites of remote changes.
+- Return actionable mismatch details (body changes, title, subtitle, audience,
+  permissions, section, slug) during dry-run updates (`--dry-run --yes`).
+- Fail closed by default on conflicted updates or missing revision metadata
+  (unprotected updates).
+- Add explicit override via `--allow-conflict` / `--force` (requiring `--yes`)
+  in CLI and `allow_conflict=True` / `force=True` in SDK.
+- Export `revision` dictionary metadata in `Api.export_draft_to_markdown` and
+  CLI `--json drafts export`.
+- Introduce `DraftConflictError` exception inheriting from both `ValueError` and
+  `SubstackException`.

docs/safety.md

@@ -35,3 +35,10 @@ marker and listed in JSON output so it cannot disappear unnoticed. Updates
 refuse to remove or alter those markers or replace remote images without
 explicit authorization (`--allow-unsupported-change --yes` or
 `--allow-image-replacement --yes`).
+
+Draft updates verify remote revision fingerprints before writing. If the
+remote draft changed after export, the update fails closed with a conflict
+error to prevent overwriting remote work. Markdown files lacking revision
+metadata are treated as unprotected updates. Overriding conflicts or applying
+unprotected updates requires explicit confirmation (`--allow-conflict --yes`
+or `--force --yes` in the CLI, `allow_conflict=True` in the SDK).

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-substack"
-version = "0.9.1"
+version = "0.10.0"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
 authors = [
     { name = "Paolo Mazza", email = "mazzapaolo2019@gmail.com" }

substack/__init__.py

@@ -3,7 +3,7 @@
 __author__ = "Paolo Mazza"
 __email__ = "mazzapaolo2019@gmail.com"
 __license__ = "MIT License"
-__version__ = "0.9.1"
+__version__ = "0.10.0"
 __url__ = "https://github.com/ma2za/python-substack"
 __download_url__ = "https://pypi.python.org/pypi/python-substack"
 __description__ = (

substack/api.py

@@ -460,6 +460,7 @@ def get_draft(self, draft_id):
 
     def export_draft_to_markdown(self, draft_id):
         from substack.mdexport import document_to_markdown
+        from substack.revision import compute_draft_revision, format_revision_marker
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -474,9 +475,15 @@ def export_draft_to_markdown(self, draft_id):
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
         markdown, unsupported_nodes = document_to_markdown(draft_body)
+        revision = compute_draft_revision(draft)
+        revision_marker = format_revision_marker(revision)
+        full_markdown = (
+            f"{revision_marker}\n\n{markdown}" if markdown else f"{revision_marker}\n"
+        )
         return {
             "draft": draft,
-            "markdown": markdown,
+            "markdown": full_markdown,
+            "revision": revision,
             "unsupported_nodes": unsupported_nodes,
         }
 
@@ -496,13 +503,22 @@ def update_draft_from_markdown(
         dry_run: bool = False,
         allow_unsupported_change: bool = False,
         allow_image_replacement: bool = False,
+        expected_revision=None,
+        allow_conflict: bool = False,
+        force: bool = False,
     ) -> dict:
         """
         Update an existing draft body from Markdown, with optional metadata changes.
         """
         from substack import mdrender
+        from substack.exceptions import DraftConflictError
         from substack.mdexport import document_to_markdown
         from substack.post import Post
+        from substack.revision import (
+            compare_draft_revisions,
+            compute_draft_revision,
+            parse_revision_marker,
+        )
 
         draft = self.get_draft(draft_id)
         draft_body = draft.get("draft_body")
@@ -516,6 +532,50 @@ def update_draft_from_markdown(
         if not isinstance(draft_body, dict):
             raise ValueError("Malformed draft body: draft_body must be a JSON object")
 
+        current_rev = compute_draft_revision(draft)
+
+        target_expected_rev = None
+        if expected_revision is not None:
+            if isinstance(expected_revision, dict):
+                target_expected_rev = expected_revision
+            elif isinstance(expected_revision, str):
+                target_expected_rev = {"revision": expected_revision}
+            else:
+                raise ValueError("expected_revision must be a revision dict or string")
+        else:
+            target_expected_rev = parse_revision_marker(markdown)
+
+        override_enabled = bool(allow_conflict or force)
+        conflict_detected = False
+        mismatches = []
+
+        if target_expected_rev is None:
+            conflict_detected = True
+            mismatches = [
+                "Markdown file is missing revision metadata (unprotected update); safe conflict comparison is impossible."
+            ]
+            if not override_enabled and not dry_run:
+                raise DraftConflictError(
+                    "Refusing to update: Markdown file is missing revision metadata (unprotected update). "
+                    "Export the draft first or pass allow_conflict=True to proceed.",
+                    mismatches=mismatches,
+                    expected_revision=None,
+                    current_revision=current_rev,
+                )
+        else:
+            mismatches = compare_draft_revisions(target_expected_rev, current_rev)
+            if mismatches:
+                conflict_detected = True
+                if not override_enabled and not dry_run:
+                    details = "; ".join(mismatches)
+                    raise DraftConflictError(
+                        f"Refusing to update: remote draft has changed since export ({details}). "
+                        "Re-export the draft or pass allow_conflict=True to proceed.",
+                        mismatches=mismatches,
+                        expected_revision=target_expected_rev,
+                        current_revision=current_rev,
+                    )
+
         _, remote_unsupported = document_to_markdown(draft_body)
 
         image_markers = []
@@ -657,7 +717,7 @@ def update_draft_from_markdown(
             if tags_list:
                 tags_result = self.add_tags_to_post(draft_id, tags_list)
 
-        return {
+        result_payload = {
             "action": "update",
             "draft_id": draft_id,
             "dry_run": dry_run,
@@ -666,7 +726,14 @@ def update_draft_from_markdown(
             "draft": updated_draft,
             "tags": tags_result,
             "unsupported_nodes": unsupported_nodes,
+            "conflict": conflict_detected,
+            "mismatches": mismatches,
+            "expected_revision": target_expected_rev,
+            "current_revision": current_rev,
         }
+        if override_enabled and conflict_detected:
+            result_payload["override"] = True
+        return result_payload
 
     def delete_draft(self, draft_id):
         """

substack/cli.py

@@ -10,7 +10,11 @@
 from dotenv import load_dotenv
 
 from substack import Api, __version__
-from substack.exceptions import SubstackAPIException, SubstackRequestException
+from substack.exceptions import (
+    DraftConflictError,
+    SubstackAPIException,
+    SubstackRequestException,
+)
 from substack.post import Post
 
 
@@ -146,6 +150,14 @@ def _redact(message):
 
 
 def _error_payload(exc):
+    if isinstance(exc, DraftConflictError):
+        return {
+            "error": {
+                "type": "conflict_error",
+                "message": _redact(exc.message),
+                "mismatches": exc.mismatches,
+            }
+        }
     if isinstance(exc, SubstackAPIException):
         return {
             "error": {
@@ -314,6 +326,8 @@ def _drafts_update(api, args):
         raise CLIUsageError("--yes is required when using --allow-unsupported-change")
     if args.allow_image_replacement and not args.yes:
         raise CLIUsageError("--yes is required when using --allow-image-replacement")
+    if args.allow_conflict and not args.yes:
+        raise CLIUsageError("--yes is required when using --allow-conflict")
 
     if not args.yes and (args.json_output or not sys.stdin.isatty()):
         raise CLIUsageError("--yes is required in non-interactive or JSON mode")
@@ -354,13 +368,25 @@ def _drafts_update(api, args):
         dry_run=args.dry_run,
         allow_unsupported_change=args.allow_unsupported_change,
         allow_image_replacement=args.allow_image_replacement,
+        allow_conflict=args.allow_conflict,
     )
 
     if args.json_output:
         _print_json(result)
     else:
         status = "Dry-run updated" if args.dry_run else "Updated"
-        print(f"{status} draft {args.draft_id}")
+        if result.get("conflict"):
+            print(f"Conflict detected in draft {args.draft_id}:")
+            for mismatch in result.get("mismatches", []):
+                print(f"  - {mismatch}")
+            if result.get("dry_run"):
+                print(
+                    f"Dry-run preview completed for draft {args.draft_id} with conflicts."
+                )
+            else:
+                print(f"{status} draft {args.draft_id} (override applied)")
+        else:
+            print(f"{status} draft {args.draft_id}")
 
 
 def _drafts_export(api, args):
@@ -381,6 +407,8 @@ def _drafts_export(api, args):
         "markdown": markdown,
         "unsupported_nodes": result["unsupported_nodes"],
     }
+    if "revision" in result and result["revision"] is not None:
+        payload["revision"] = result["revision"]
     if args.json_output:
         _print_json(payload)
     elif output_path is not None:
@@ -517,6 +545,13 @@ def _build_parser():
     drafts_update.add_argument("--dry-run", action="store_true")
     drafts_update.add_argument("--allow-unsupported-change", action="store_true")
     drafts_update.add_argument("--allow-image-replacement", action="store_true")
+    drafts_update.add_argument(
+        "--allow-conflict",
+        "--force",
+        action="store_true",
+        dest="allow_conflict",
+        help="Allow updating draft even if remote revision has changed or revision metadata is missing.",
+    )
     drafts_update.add_argument("--yes", action="store_true")
     drafts_update.set_defaults(handler=_drafts_update)