docspan 0.3.0__tar.gz → 0.4.0__tar.gz

docspan-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

{docspan-0.3.0 → docspan-0.4.0}/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0](https://github.com/tstapler/docspan/compare/docspan-v0.3.0...docspan-v0.4.0) (2026-08-13)
+
+
+### Features
+
+* **docspan:** add docspan map command and push auto-create for unmapped files ([#80](https://github.com/tstapler/docspan/issues/80)) ([aa4258b](https://github.com/tstapler/docspan/commit/aa4258b3ff381c3e6afc389ad55c426abb5850ba))
+* **google-docs:** add inline image push/pull support ([#101](https://github.com/tstapler/docspan/issues/101)) ([e5256af](https://github.com/tstapler/docspan/commit/e5256afa18076051b891f44511786e4f2750a489))
+* **google-docs:** render mermaid diagrams as inline PNGs on push ([9298d1b](https://github.com/tstapler/docspan/commit/9298d1b0c645231056571a2c5afaa296e14d751b))
+
+
+### Bug Fixes
+
+* **config:** round-trip YAML comments on save_config writes ([780ddcc](https://github.com/tstapler/docspan/commit/780ddcc18b760f184627eb9c9a2b870249c6ed51))
+* **confluence:** confirm mermaid render pipeline is a stub, not a rasterizer ([#94](https://github.com/tstapler/docspan/issues/94)) ([fb5ca80](https://github.com/tstapler/docspan/commit/fb5ca8002e91e050447766d7e498ff30eadae9dc))
+* **google-docs:** bound difflib's cubic-ish blowup on duplicate-heavy documents ([#84](https://github.com/tstapler/docspan/issues/84)) ([834df71](https://github.com/tstapler/docspan/commit/834df71d2737b09ee68b14dd1f509bc3928249da))
+* **google-docs:** distinguish delete-and-reinsert churn from real removal in push preview ([#86](https://github.com/tstapler/docspan/issues/86)) ([052b64d](https://github.com/tstapler/docspan/commit/052b64d591bc88ab6962e5173c2494b2fedab1c3))
+* **google-docs:** escape backticks in monospace spans on both pull paths ([#103](https://github.com/tstapler/docspan/issues/103)) ([74d007d](https://github.com/tstapler/docspan/commit/74d007d162d511641650d2afb8b9f8b482c3e48e))
+* **google-docs:** land PR [#70](https://github.com/tstapler/docspan/issues/70) restyle repair, verify AC0-8 (issue [#52](https://github.com/tstapler/docspan/issues/52)) ([#99](https://github.com/tstapler/docspan/issues/99)) ([8203c93](https://github.com/tstapler/docspan/commit/8203c93567a3d962bb3bb5754338298260f610aa))
+* **google-docs:** order same-anchor insert groups after restyle/delete groups ([#83](https://github.com/tstapler/docspan/issues/83)) ([b8eace0](https://github.com/tstapler/docspan/commit/b8eace0505f7196eeb5bfe659f2d284a4b8c07ad))
+* **google-docs:** render multi-paragraph table cells as HTML tables ([#79](https://github.com/tstapler/docspan/issues/79)) ([45e072d](https://github.com/tstapler/docspan/commit/45e072de2ae845443d6b5862a6c70234a55fb501))
+* **google-docs:** resolve cross-tab heading anchors on push ([#102](https://github.com/tstapler/docspan/issues/102)) ([c1be541](https://github.com/tstapler/docspan/commit/c1be541d7e8d227369367ac8d99700405ac31195))
+* **google-docs:** resolve relative cross-document markdown links to target Google Doc URLs ([#98](https://github.com/tstapler/docspan/issues/98)) ([27e7f15](https://github.com/tstapler/docspan/commit/27e7f1551549d7bff9d64b5e43abfd09f4f19e36))
+* **google-docs:** richer at-risk-comment warning, no anchor migration ([#92](https://github.com/tstapler/docspan/issues/92)) ([#95](https://github.com/tstapler/docspan/issues/95)) ([be854db](https://github.com/tstapler/docspan/commit/be854db8cc4dd5a8252685847455e51d444decee))
+* **google-docs:** split/preserve fenced code blocks in list items and blockquotes ([#87](https://github.com/tstapler/docspan/issues/87)) ([0a01f9f](https://github.com/tstapler/docspan/commit/0a01f9f6c927489c9234049aed56b4fe8c895b58))
+* **google-docs:** stop force-push from corrupting tab-scoped checkbox docs ([#97](https://github.com/tstapler/docspan/issues/97)) ([63ab43b](https://github.com/tstapler/docspan/commit/63ab43bc755dad67ce22d516b6ea4f1eaeba9c3e))
+* **google-docs:** stop replace branch from duplicating the doc-end-clamped newline ([#85](https://github.com/tstapler/docspan/issues/85)) ([68f0de9](https://github.com/tstapler/docspan/commit/68f0de985be5b13df0d4e1b3c4b0177a2e0eced8))
+
 ## [0.3.0](https://github.com/tstapler/docspan/compare/docspan-v0.2.0...docspan-v0.3.0) (2026-08-11)
 
 

{docspan-0.3.0 → docspan-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docspan
-Version: 0.3.0
+Version: 0.4.0
 Summary: Push and pull markdown to Google Docs and Confluence from a single CLI
 Project-URL: Homepage, https://github.com/tstapler/docspan
 Project-URL: Repository, https://github.com/tstapler/docspan
@@ -36,6 +36,7 @@ Requires-Dist: python-dateutil>=2.8.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.25.0
 Requires-Dist: rich>=13.0.0
+Requires-Dist: ruamel-yaml>=0.18.0
 Requires-Dist: typer>=0.9.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
@@ -306,8 +307,10 @@ docspan generates these files in your project directory after first sync:
 > [!NOTE]
 > **Known limitations in v0.1.0**
 >
-> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens — it is still not prevented.
-> - Push: no image support — local images cannot be pushed to Google Docs or Confluence
+> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens, naming every at-risk comment (id, author, quoted snippet) per flagged paragraph — it is still not prevented. Re-anchoring or recreating the comment was investigated and rejected: neither `comments().update` nor `comments().create` can produce a comment Google Docs' own UI renders as anchored to arbitrary text (see [ADR-003](project_plans/wedding-planning-workflow/decisions/ADR-003-no-comment-anchor-migration.md)), so no migration ships.
+> - Google Docs: images push and pull (`![alt](./local.png)` uploads to Drive; `https://` URLs are referenced directly). SVG, missing, and oversized (>50MB) images are reported as warnings rather than blocking the push. An image mixed into a paragraph alongside running text is not supported — only a standalone `![alt](src)` on its own line
+> - Google Docs: a pulled image's markdown link is Google's `contentUri` for that embedded object, which Google's API docs say may change over time even when the image itself hasn't. docspan's push diff keys image identity on `alt`/size rather than this URI, so a rotated URI alone will not cause a paragraph to be needlessly deleted and reinserted (and its comments lost) on the next push — but the URI written into your markdown file can itself go stale between pulls, and a stale-but-unchanged URI line can still show up as a one-sided edit in `docspan conflicts resolve`'s three-way diff even though nothing meaningful changed
+> - Push: no image support for Confluence — local images cannot be pushed
 > - Push: no table support — markdown tables are not rendered in Google Docs
 > - Confluence: requires an Atlassian API token; no OAuth flow
 > - Confluence: the comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back

{docspan-0.3.0 → docspan-0.4.0}/README.md

@@ -255,8 +255,10 @@ docspan generates these files in your project directory after first sync:
 > [!NOTE]
 > **Known limitations in v0.1.0**
 >
-> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens — it is still not prevented.
-> - Push: no image support — local images cannot be pushed to Google Docs or Confluence
+> - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved). `docspan push --dry-run` and a default fail-closed `--force`-gated block now warn before this happens, naming every at-risk comment (id, author, quoted snippet) per flagged paragraph — it is still not prevented. Re-anchoring or recreating the comment was investigated and rejected: neither `comments().update` nor `comments().create` can produce a comment Google Docs' own UI renders as anchored to arbitrary text (see [ADR-003](project_plans/wedding-planning-workflow/decisions/ADR-003-no-comment-anchor-migration.md)), so no migration ships.
+> - Google Docs: images push and pull (`![alt](./local.png)` uploads to Drive; `https://` URLs are referenced directly). SVG, missing, and oversized (>50MB) images are reported as warnings rather than blocking the push. An image mixed into a paragraph alongside running text is not supported — only a standalone `![alt](src)` on its own line
+> - Google Docs: a pulled image's markdown link is Google's `contentUri` for that embedded object, which Google's API docs say may change over time even when the image itself hasn't. docspan's push diff keys image identity on `alt`/size rather than this URI, so a rotated URI alone will not cause a paragraph to be needlessly deleted and reinserted (and its comments lost) on the next push — but the URI written into your markdown file can itself go stale between pulls, and a stale-but-unchanged URI line can still show up as a one-sided edit in `docspan conflicts resolve`'s three-way diff even though nothing meaningful changed
+> - Push: no image support for Confluence — local images cannot be pushed
 > - Push: no table support — markdown tables are not rendered in Google Docs
 > - Confluence: requires an Atlassian API token; no OAuth flow
 > - Confluence: the comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back

{docspan-0.3.0 → docspan-0.4.0}/docs/backends/confluence.md

@@ -65,3 +65,4 @@ export CONFLUENCE_API_TOKEN=your-token
     - **Comment sidecar is informational only**: Comments pulled from Confluence are written to `{file}.comments.md` but cannot be pushed back via docspan.
     - **Push replaces page content**: The full page body is replaced on every push. Inline comment positions in Confluence may shift after a push.
     - **Complex macros not preserved faithfully**: Confluence macros (status, panels, expand, etc.) are converted to approximate markdown equivalents on pull and may not round-trip cleanly on push.
+    - **Mermaid diagrams are not rendered**: a ` ```mermaid ` fence is pushed as a plain ADF code block (language `mermaid`), i.e. the raw diagram source as visible text — not an image, and not Confluence's native mermaid macro. `render_mermaid_diagrams` in `PublishConfig` currently has no effect on this: the code path that would rasterize a diagram (`MermaidParser.render_diagram()` in `markdown/extensions/mermaid.py`) is a stub that never runs — it's dead code, unreachable from the real parse pipeline (`markdown/parser.py` builds `MermaidNode` directly). Fixing this requires a real renderer (e.g. `mermaid-cli` or a hosted rendering service) wired to upload the result as a Confluence attachment before ADF conversion; tracked as follow-up work, not yet implemented.

docspan-0.4.0/docs/backends/google-docs.md

@@ -0,0 +1,67 @@
+# Google Docs Backend
+
+## How it works
+
+The Google Docs backend authenticates either via a Google service account JSON key or via per-user OAuth (an `InstalledAppFlow` that acts as you, similar to `gws`) — whichever `markgate.yaml` configures (`credentials_path` for the service account, `oauth_client_secret_path` for OAuth). Push uses a paragraph-level structural diff that computes the minimal set of `batchUpdate` requests needed to transform the current document into the target content. This approach preserves comments attached to paragraphs that have not changed. Pull exports the Google Doc as HTML and converts it to markdown.
+
+## Auth Setup
+
+Run `docspan auth setup google_docs` to see setup instructions.
+
+```
+Google Docs Auth Setup
+========================================
+Run this in an interactive terminal for a guided setup, or configure manually:
+
+  Per-user OAuth (recommended — acts as you, like gws):
+    1. Create an OAuth client (Desktop app); download client_secret.json
+    2. docspan auth setup google_docs --oauth --client-secret /path/to/client_secret.json
+       (or set backends.google_docs.oauth_client_secret_path in markgate.yaml)
+
+  Service account (automation):
+    1. Create a service account + JSON key; enable the Docs & Drive APIs
+    2. Share your docs with the service-account email
+    3. Set credentials_path in markgate.yaml (or ACCOUNT_A_CREDENTIALS_PATH env)
+```
+
+Service account credentials can also be provided inline via `ACCOUNT_A_CREDENTIALS` (the JSON itself, not a path) instead of `ACCOUNT_A_CREDENTIALS_PATH`.
+
+## Required Scopes
+
+Every credential path (`GoogleAuthenticator`, `OAuthAuthenticator`) requests the same read/write scopes (`PUSH_SCOPES`, aliased as `SCOPES`/`DEFAULT_SCOPES`), whether the operation is push or pull:
+
+- `https://www.googleapis.com/auth/documents` — read and write Google Docs
+- `https://www.googleapis.com/auth/drive` — read/write Drive (comment reads/writes, file metadata; not just export)
+- `https://www.googleapis.com/auth/spreadsheets.readonly` — read Sheets embedded/linked in a Doc
+
+`auth.py` also defines a narrower read-only `PULL_SCOPES`, but nothing in the codebase wires it up today — pull requests the same full grant as push, not a readonly subset. Comment reads/writes reuse this same grant too; no separate scope is added for them.
+
+## `markgate.yaml` Example
+
+```yaml
+backends:
+  google_docs:
+    credentials_path: /path/to/service-account.json
+    # token_path: .markgate/google_token.json  # default, rarely changed
+
+mappings:
+  - local: docs/design-doc.md
+    backend: google_docs
+    remote_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74O
+    direction: both
+```
+
+## Limitations
+
+!!! warning
+    - **Comments destroyed on push for edited paragraphs**: The structural diff preserves comments on unchanged paragraphs, but any paragraph that is deleted and reinserted loses its comments. This is a known v0.1.0 limitation.
+    - **Images push and pull**: `![alt](./local.png)` uploads the local file to Drive and references it by URI; an `https://` URL is referenced directly, bypassing upload. Only a standalone image on its own line is supported — one mixed into a paragraph alongside running text is left as plain text. Missing files, files over 50MB, and unsupported formats (SVG) are reported as push warnings rather than blocking the write or crashing.
+    - **Mermaid diagrams push as rendered PNGs**: a fenced ` ```mermaid ` block is rendered to a raster PNG (via `mermaid-cli`/`mmdc`, shelled out to — install with `npm install -g @mermaid-js/mermaid-cli`, or it's fetched on demand through `npx`) and pushed as an inline image, since `insertInlineImage` has no native mermaid or SVG support. A render failure (missing Node.js/mermaid-cli, invalid diagram syntax, timeout) is reported as a push warning, not a crash. There is no pull-side reconstruction — a mermaid diagram round-trips back to markdown as a plain image reference, not a ` ```mermaid ` fence.
+    - **Pulled image URIs can go stale**: a pulled `![alt](src)` link is Google's `contentUri` for that embedded object, which Google's API docs say may change over time even when the image itself is unchanged. The push structural diff keys image identity on `alt`/width/height, not this URI, so a rotated `contentUri` alone will not cause the paragraph to be deleted and reinserted (which would destroy any comment anchored to it) — but the stale URI persisted in your markdown file can still surface as a one-sided edit in `docspan conflicts resolve`'s three-way diff.
+    - **Table cells hold one paragraph**: a markdown table cell is pushed as a single
+      paragraph, and inline formatting inside it (bold, monospace, links, internal
+      `#anchor` references) is applied on the second pass. Two limits follow: a cell
+      whose content spans more than one paragraph in the Doc cannot be styled, and a
+      table created by the current push gets its cell styling on the *next* push —
+      docspan reports both rather than failing silently.
+    - **Rate limiting**: The Google Docs API allows 300 requests per minute per project. Large documents with many changed paragraphs may trigger rate limit errors.

{docspan-0.3.0 → docspan-0.4.0}/docs/index.md

@@ -57,7 +57,9 @@ See the [Install](install.md) page for full auth setup instructions and the [Com
 
 !!! warning "Known limitations in v0.1.0"
     - Google Docs: comments on edited paragraphs are lost on push (paragraph-level structural diff; comments on unchanged paragraphs are preserved)
-    - Push: no image support — local images cannot be pushed to Google Docs or Confluence
+    - Google Docs: images push and pull (local files upload to Drive; `https://` URLs are referenced directly)
+    - Google Docs: a pulled image's markdown link is Google's `contentUri`, which can change over time even when the image hasn't — push doesn't misdetect this as a real change, but the stale URI in your local file can still show up as a one-sided edit during conflict resolution
+    - Push: no image support for Confluence — local images cannot be pushed
     - Push: no table support — markdown tables are not rendered in Google Docs
     - Confluence: requires an Atlassian API token; no OAuth flow
     - Confluence: the comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back

docspan-0.4.0/project_plans/wedding-planning-workflow/decisions/ADR-003-no-comment-anchor-migration.md

@@ -0,0 +1,128 @@
+# ADR-003: Do not implement comment re-anchoring/migration on push — richer warning only
+
+**Date**: 2026-08-12
+**Status**: Accepted
+
+## Context
+
+`docspan` issue #92 asks whether a comment anchored to a paragraph that push
+resolves to delete+insert (per `_repair`'s docstring in
+`docs_request_builder.py`: any diff opcode that doesn't collapse to `"equal"`
+becomes a literal `deleteContentRange` + `insertText`) can be preserved
+across that push, either by mutating the
+Drive comment's existing `anchor`/`quotedFileContent` via `comments().update`,
+or by creating a replacement comment via `comments().create` with a custom
+`anchor`/`quotedFileContent` pointing at the reinserted paragraph.
+
+A live-API spike against a real Drive document/comment was the intended way
+to answer this, but no OAuth credentials or test Drive account are available
+in this sandboxed environment, so no live `comments().update`/`comments().create`
+call was made. This is stated plainly, not glossed over: the finding below
+rests on documented API contract and this repo's own prior investigation,
+not a fresh live call. **This is a hard environmental blocker, not a gap in
+effort** — closing it for real requires a human to supply live OAuth
+credentials plus a scratch Drive document/comment outside this sandbox and
+run the two calls below; no amount of further reasoning in this environment
+can substitute for that. If/when that access exists, the spike is exactly
+two calls:
+```
+comments().update(fileId=doc_id, commentId=c.id, fields="anchor", body={"anchor": target_anchor})
+comments().create(fileId=doc_id, body={"content": c.content, "anchor": target_anchor, "quotedFileContent": {"value": snippet}})
+```
+followed by reloading the comment in the Docs UI to see whether it renders anchored.
+
+### Confidence labeling
+
+- **UNVERIFIED (this session)**: whether a live `comments().update`/`comments().create`
+  call against a real document actually behaves as documented — no such call was made here.
+- **VERIFIED (secondary source, source 1 below)**: Google's own API reference and guide
+  text, read directly from developers.google.com, states anchors are immutable and that
+  `update`'s only documented-writable field is `content`.
+- **VERIFIED (this repo's own prior work, source 2 below)**: `project_plans/bidirectional-comments/plan.md`
+  §2 already reached and recorded the same conclusion, citing a third-party reproduction
+  (`googleworkspace/cli#169`) as its own evidence, independent of this ADR.
+
+Two sources answer the question decisively without a live call:
+
+1. **Google's own guide**, [Manage comments and replies](https://developers.google.com/workspace/drive/api/guides/manage-comments):
+   anchors are documented as immutable ("Anchors are immutable, and their
+   position relative to the content of a document cannot be guaranteed
+   between revisions"), and — separately — Google Workspace editor apps
+   (Docs included) render an API-set `anchor` as an **unanchored** comment in
+   the UI, regardless of whether the anchor value itself is well-formed.
+2. **This repo's own prior research**, `project_plans/bidirectional-comments/plan.md`
+   §2 (dated before this ADR, marked "High confidence — documented +
+   reproduced"): "`anchor` is ignored on Google Docs — a new anchored
+   comment renders as 'Original content deleted' / no highlight," citing
+   Google's guide plus a reproduced case at
+   [googleworkspace/cli#169](https://github.com/googleworkspace/cli/issues/169).
+   That plan already reached the same conclusion for *new* top-level
+   comments (ship unanchored-only, v1); this ADR extends the same finding
+   to the *migrate-an-existing-comment* case #92 asks about.
+
+Both sources agree, from two different angles (official docs; independent
+reproduction), that neither `comments().update` nor `comments().create` can
+produce a comment that Google Docs' own UI will render as anchored to
+arbitrary text. `comments().update`'s only documented writable field (per
+its REST reference) is `content` — no update path for `anchor` is
+documented at all.
+
+Options considered:
+
+1. **Re-anchor via `comments().update`.** Blocked: `anchor` isn't a
+   documented-writable field on `update`, and even if it were, "anchors are
+   immutable" per Google's own guide.
+2. **Recreate via `comments().create` + resolve/delete the original.**
+   Technically possible to call, but the new comment renders **unanchored**
+   in the Docs UI (source 1 and 2 above) — a materially different, arguably
+   worse UX than today's silent loss: instead of nothing, the user gets a
+   stray document-level comment, under a new `id`/`createdTime`, that fires
+   a fresh "new comment" notification to every watcher, with no visual
+   anchor to the paragraph it's about.
+3. **Warn-and-proceed only (status quo mechanism, richer message).** No new
+   Drive write capability, no new failure mode, no notification-spam
+   regression. Ship the AC2 enrichment (list every at-risk comment per
+   paragraph, not just the first) on top of this.
+
+## Decision
+
+Use **Option 3**. No comment migration ships. `find_high_risk_paragraphs`/
+`render_high_risk` (`push_preview.py`) are extended to enumerate every
+at-risk comment per flagged paragraph (id, author, snippet) instead of
+stopping at the first match, but the underlying warn-before-`--force`
+mechanism from ADR-002 is unchanged.
+
+## Rationale
+
+- Option 1 is foreclosed by the API contract itself, not by appetite or
+  risk tolerance — there's no live spike result that could reverse this;
+  the field is undocumented-as-writable and documented-as-immutable.
+- Option 2 is technically shippable but trades a *quiet* known limitation
+  for a *loud* new one (unanchored stray comment + notification spam) —
+  worse for the exact "silent vs. loud" trade ADR-002 already reasoned
+  through, but on the wrong side of it: ADR-002 chose loud-and-blocking
+  over silent-and-undetected specifically because a blocked push costs the
+  user two minutes, which is a good trade; recreate-based migration would
+  cost watchers a false "new comment" notification and the user a
+  duplicate, unanchored comment, which is not a favorable trade for a
+  problem that's still only partially solved (the anchor is still gone).
+- Option 3 keeps the fix surface exactly where ADR-002 already put it —
+  read-only risk detection — and directly satisfies #92's fallback
+  instruction: "If re-anchoring isn't feasible, improve the existing
+  warn-before-force message."
+
+## Consequences
+
+- AC5 ("if migration ships, a comment is preserved across push") is
+  satisfied by this ADR's explicit decision not to ship migration, per
+  #92's own conditional phrasing ("If migration ships...").
+- No new Drive API write surface is added; `PUSH_SCOPES` is unchanged
+  (already covers today's `create_reply` calls).
+- `push_preview.py`'s `HighRiskParagraph`/`find_high_risk_paragraphs`/
+  `render_high_risk` gain a richer, multi-comment rendering (AC2) without
+  changing which paragraphs get classified as high-risk (AC3) or how the
+  post-push open-comment-count backstop works (AC4).
+- If Google ever documents a writable `anchor` field on `comments().update`,
+  or changes how Workspace editors render API-set anchors, this decision
+  should be revisited — it is contingent on the current, cited API
+  behavior, not a permanent architectural constraint.

{docspan-0.3.0 → docspan-0.4.0}/pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
     "typer>=0.9.0",
     "rich>=13.0.0",
     "PyYAML>=6.0",
+    "ruamel.yaml>=0.18.0",
     "pydantic>=2.0.0",
     # Google Docs backend
     "google-auth>=2.23.0",

{docspan-0.3.0 → docspan-0.4.0}/src/docspan/backends/base.py

@@ -2,9 +2,9 @@
 
 import inspect
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
-from typing import Literal, Optional
+from typing import List, Literal, Optional
 
 
 class SyncDirection(str, Enum):
@@ -29,6 +29,10 @@ class PushResult:
     doc_id: str
     message: Optional[str] = None
     url: Optional[str] = None
+    # Drive file ids for images uploaded as part of this push but not yet
+    # deleted -- populated only when push failed after upload, so a retry
+    # can clean them up or reuse them instead of leaking orphaned files.
+    retryable_temp_drive_file_ids: List[str] = field(default_factory=list)
 
 
 @dataclass
@@ -39,6 +43,13 @@ class PullResult:
     message: Optional[str] = None
 
 
+@dataclass
+class CreateResult:
+    doc_id: str
+    title: str
+    url: Optional[str] = None
+
+
 class Backend(ABC):
     """
     Base class for all docspan platform backends.
@@ -67,6 +78,10 @@ class Backend(ABC):
     def pull(self, doc_id: str, local_path: str, **kwargs) -> PullResult:
         """Fetch the remote document and write it as local markdown."""
 
+    @abstractmethod
+    def create(self, title: str, **kwargs: object) -> CreateResult:
+        """Create a new remote document/page and return its id/title/url."""
+
     @abstractmethod
     def auth_setup(self, config_path: Optional[str] = None) -> None:
         """Interactive / instructional setup wizard for this backend.

{docspan-0.3.0 → docspan-0.4.0}/src/docspan/backends/confluence/backend.py

@@ -10,7 +10,7 @@ from typing import TYPE_CHECKING, Optional
 
 import markdownify as md_lib
 
-from docspan.backends.base import Backend, PullResult, PushResult
+from docspan.backends.base import Backend, CreateResult, PullResult, PushResult
 from docspan.backends.confluence.adf.converter import AdfConverter
 from docspan.backends.confluence.config.models import ConfluenceConfig as InternalConfluenceConfig
 from docspan.backends.confluence.markdown.parser import MarkdownParser
@@ -193,6 +193,26 @@ class ConfluenceBackend(Backend):
         page = self._client.get_page(doc_id)
         return str(page["version"]["number"])
 
+    def create(self, title: str, **kwargs: object) -> CreateResult:
+        """Create a new, empty Confluence page and return its id/title/url."""
+        self._ensure_client()
+        assert self._client is not None
+        space_key = kwargs.get("space") or self.config.space_key
+        if not space_key:
+            raise ValueError(
+                "Confluence page creation requires a space key (--space or backends.confluence.space_key)."
+            )
+        empty_adf = AdfConverter().convert(MarkdownParser().parse(""))
+        page = ConfluencePage(title=title, content=empty_adf, parent_id="", space_key=str(space_key))
+        result = self._client.create_page(page)
+        page_id = result["id"]
+        base_url = self.config.base_url or ""
+        return CreateResult(
+            doc_id=page_id,
+            title=result.get("title", title),
+            url=f"{base_url}/pages/{page_id}",
+        )
+
     def auth_setup(self, config_path: "Optional[str]" = None) -> None:
         """Interactive Confluence auth setup — prompts for credentials and prints YAML snippet."""
         print("\nConfluence auth setup")

{docspan-0.3.0 → docspan-0.4.0}/src/docspan/backends/confluence/config/models.py

@@ -75,7 +75,11 @@ class PublishConfig:
         auto_fix_hierarchy: Whether to automatically fix page hierarchy based on directory structure
         auto_migrate_legacy: Whether to automatically migrate legacy editor pages to new editor before publishing
         duplicate_similarity_threshold: Threshold for considering pages as duplicates (0.0-1.0, default 0.8)
-        render_mermaid_diagrams: Whether to render mermaid diagrams as images
+        render_mermaid_diagrams: Whether to render mermaid diagrams as images. NOTE: currently a
+            no-op — no code path reads this flag. Mermaid fences are always emitted as a plain
+            ADF code block (see docs/backends/confluence.md#limitations). Kept as a reserved
+            config key for when rendering is implemented, rather than removed, so existing
+            markgate.yaml files that set it don't start failing validation.
         process_assets: Whether to process assets (images, diagrams) for embedding
         ignore_patterns: List of file patterns to ignore (supports glob patterns like **/TODO.md)
         archive_ignored: Whether to archive/delete ignored files from Confluence if they have page IDs