feat: implement image-sync safety with v2 markers (release 0.9.1)

Author: ma2za

CHANGELOG.md

@@ -1,23 +1,46 @@
 # Changelog
-
-## 0.9.0
-
-### Added
-
-- Preserve image editor attributes through Markdown export and update with
-  `python-substack-image:v1` markers.
-- Add `allow_image_replacement=False` and
-  `substack drafts update --allow-image-replacement` for explicit image
-  replacement authorization.
-
-### Fixed
-
-- Preserve absolute and home-relative local Markdown image paths during upload,
-  retain existing root-relative asset fallback, and report missing files or
-  failed uploads instead of saving broken image sources.
-
-- Return draft records from the Substack drafts response envelope so
-  `drafts list` works with the current API response.
+
+## 0.9.1
+
+### Added
+
+- Export `python-substack-image:v2` markers immediately after every image,
+  binding the image to its original remote source and preserving non-owned
+  editor attributes including alignment, dimensions, watermark, and unknown
+  attributes.
+- Resolve V2 markers by their bound source during draft updates, allowing changed
+  Markdown image sources to safely retain original editor metadata.
+- Reject corrupt, stale, duplicate, reused, or non-adjacent image markers.
+- Continue supporting V1 image markers when the submitted image source resolves
+  uniquely to a single remote image.
+
+### Dependencies
+
+- Bump `pyjwt` from 2.13.0 to 2.15.0 (#80).
+- Bump `fastmcp` from 4.0.5 to 4.0.10 (#81).
+
+### Improved
+
+- Modernize `pyproject.toml` to PEP 621 metadata standard, eliminating Poetry 2 packaging warnings.
+
+## 0.9.0
+
+### Added
+
+- Preserve image editor attributes through Markdown export and update with
+  `python-substack-image:v1` markers.
+- Add `allow_image_replacement=False` and
+  `substack drafts update --allow-image-replacement` for explicit image
+  replacement authorization.
+
+### Fixed
+
+- Preserve absolute and home-relative local Markdown image paths during upload,
+  retain existing root-relative asset fallback, and report missing files or
+  failed uploads instead of saving broken image sources.
+
+- Return draft records from the Substack drafts response envelope so
+  `drafts list` works with the current API response.
 
 ## 0.8.0
 
@@ -79,7 +102,7 @@
 - Seven new MCP tools for read operations and safe publishing: `get_status`, `list_publications`, `list_drafts`, `get_draft`, `schedule_draft`, `unschedule_draft`, and `publish_draft_checked`.
 - Pre-publish validation, interactive confirmation requirements, and no-email defaults for the new `publish_draft_checked` MCP tool.
 - Verified MCP client configuration examples in `docs/mcp.md`.
-- Documentation for local agent workflows.
+- Documentation for local agent workflows.
 
 ### Improved
 

docs/markdown.md

@@ -204,5 +204,18 @@ explicitly authorizes that change with `allow_unsupported_change=True` or
 `--allow-unsupported-change --yes`.
 
 Export preserves the Markdown meaning of supported images: source, alt text,
-link, and plain-text caption. Substack-only image layout attributes are not a
-Markdown contract.
+link, and plain-text caption. In addition, images are exported with an immediate:
+
+```text
+<!-- python-substack-image:v2 BASE64URL_JSON -->
+```
+
+The payload binds the image to its original remote source and preserves
+editor layout and non-owned attributes (such as alignment, dimensions,
+watermark, and unrecognized attributes). Markdown remains authoritative for
+`src`, `alt`, `href`, and caption. Changed image sources resolve to their bound
+remote image and restore those attributes safely. Stale, corrupt, duplicate,
+reused, or non-adjacent markers are rejected. Unmatched image replacements require
+`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.

docs/releases/0.9.1.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Release 0.9.1
+parent: Releases
+---
+
+# Release 0.9.1
+
+## Added
+
+- Export `python-substack-image:v2` markers immediately following every image,
+  binding the image to its original remote source and preserving non-owned
+  editor attributes including alignment, dimensions, watermark, and unknown
+  attributes.
+- Resolve V2 markers during draft updates by bound original source so changed
+  image sources in Markdown safely retain editor attributes.
+- Reject corrupt, stale, duplicate, reused, or non-adjacent image markers.
+- Maintain backwards compatibility for existing V1 image markers when the
+  submitted image source resolves uniquely to a remote image.
+
+## Dependencies
+
+- Bump `pyjwt` from 2.13.0 to 2.15.0 (#80).
+- Bump `fastmcp` from 4.0.5 to 4.0.10 (#81).
+
+## Improved
+
+- Modernize `pyproject.toml` to PEP 621 metadata standard, eliminating Poetry 2 packaging warnings.

poetry.lock

@@ -1,19 +1,13 @@
-[tool.poetry]
+[project]
 name = "python-substack"
-version = "0.9.0"
+version = "0.9.1"
 description = "Write and safely manage Substack drafts from Markdown with Python, CLI, and MCP."
-authors = ["Paolo Mazza <mazzapaolo2019@gmail.com>"]
-license = "MIT"
-packages = [
-    { include = "substack" },
-    { include = "substack_mcp" }
+authors = [
+    { name = "Paolo Mazza", email = "mazzapaolo2019@gmail.com" }
 ]
-
+license = "MIT"
 readme = "README.md"
-
-repository = "https://github.com/ma2za/python-substack"
-homepage = "https://github.com/ma2za/python-substack"
-
+requires-python = ">=3.10,<4.0"
 keywords = ["substack", "substack-api", "cli", "newsletter", "publishing", "automation", "mcp"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -27,24 +21,38 @@ classifiers = [
     "Topic :: Internet :: WWW/HTTP",
     "Topic :: Software Development :: Libraries :: Python Modules"
 ]
+dependencies = [
+    "requests>=2.32.0,<3.0.0",
+    "python-dotenv>=1.2.1,<2.0.0",
+    "PyYAML>=6.0,<7.0",
+    "markdown-it-py>=3,<5",
+    "mdit-py-plugins>=0.5,<0.7"
+]
+
+[project.optional-dependencies]
+mcp = [
+    "fastmcp>=3.1.1,<5.0.0"
+]
 
-[tool.poetry.urls]
+[project.urls]
 "Documentation" = "https://ma2za.github.io/python-substack/"
 "Changelog" = "https://github.com/ma2za/python-substack/blob/main/CHANGELOG.md"
 "Issues" = "https://github.com/ma2za/python-substack/issues"
+"Homepage" = "https://github.com/ma2za/python-substack"
+"Repository" = "https://github.com/ma2za/python-substack"
 
-[tool.poetry.dependencies]
-python = "<4.0,>=3.10"
-
-requests = "^2.32.0"
-python-dotenv = "^1.2.1"
-PyYAML = "^6.0"
-markdown-it-py = ">=3,<5"
-mdit-py-plugins = ">=0.5,<0.7"
-fastmcp = { version = ">=3.1.1,<5.0.0", optional = true }
+[project.scripts]
+substack = "substack.cli:main"
+substack-auth-check = "substack.cli:auth_check"
+substack-publish-markdown = "substack.cli:publish_markdown"
+substack-publish-yaml = "substack.cli:publish_yaml"
+substack-mcp = "substack_mcp.mcp_server:main"
 
-[tool.poetry.extras]
-mcp = ["fastmcp"]
+[tool.poetry]
+packages = [
+    { include = "substack" },
+    { include = "substack_mcp" }
+]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.1.1"
@@ -56,13 +64,6 @@ markers = [
     "live: opt-in tests that call the live Substack service",
 ]
 
-[tool.poetry.scripts]
-substack = "substack.cli:main"
-substack-auth-check = "substack.cli:auth_check"
-substack-publish-markdown = "substack.cli:publish_markdown"
-substack-publish-yaml = "substack.cli:publish_yaml"
-substack-mcp = "substack_mcp.mcp_server:main"
-
 [build-system]
-requires = ["poetry-core>=1.0.0"]
+requires = ["poetry-core>=2.0.0"]
 build-backend = "poetry.core.masonry.api"

pyproject.toml

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