docspan 0.1.0__py3-none-any.whl

docspan/core/orchestrator.py

@@ -0,0 +1,332 @@
+"""Sync orchestration logic — decoupled from the CLI layer.
+
+Each public function handles one push or pull scenario and returns a typed
+outcome that the CLI can render without knowing any sync logic.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+logger = logging.getLogger(__name__)
+
+from docspan.backends.base import Backend, PullResult, PushResult
+from docspan.core.merge import three_way_merge
+from docspan.core.paths import BASE_FILE_SUFFIX, BASE_STORE_DIR, ORIG_SUFFIX, STATE_FILENAME
+from docspan.core.state import MappingState, SyncState, sha256_of_content
+
+if TYPE_CHECKING:
+    from docspan.config import Mapping
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Path helpers
+# ─────────────────────────────────────────────────────────────────────────────
+
+def get_state_path(config_path: Optional[str]) -> str:
+    state_dir = _state_dir(config_path)
+    return os.path.join(state_dir, STATE_FILENAME)
+
+
+def get_state_dir(config_path: Optional[str]) -> str:
+    return _state_dir(config_path)
+
+
+def _state_dir(config_path: Optional[str]) -> str:
+    if config_path is not None:
+        return os.path.dirname(os.path.abspath(config_path))
+    return os.getcwd()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Content-addressed base store
+# ─────────────────────────────────────────────────────────────────────────────
+
+def get_base_content(state_dir: str, base_hash: str) -> str:
+    """Read the merge base for a file from the content-addressed store."""
+    base_path = os.path.join(state_dir, BASE_STORE_DIR, f"{base_hash}{BASE_FILE_SUFFIX}")
+    if not os.path.exists(base_path):
+        return ""
+    with open(base_path, encoding="utf-8") as fh:
+        return fh.read()
+
+
+def save_base_content(state_dir: str, content: str) -> str:
+    """Write content to the content-addressed base store. Returns the sha256 hex digest."""
+    sha = sha256_of_content(content)
+    base_dir = os.path.join(state_dir, BASE_STORE_DIR)
+    os.makedirs(base_dir, exist_ok=True)
+    base_path = os.path.join(base_dir, f"{sha}{BASE_FILE_SUFFIX}")
+    if not os.path.exists(base_path):
+        with open(base_path, "w", encoding="utf-8") as fh:
+            fh.write(content)
+    return sha
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Outcome types
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class PushOutcome:
+    local_path: str
+    result: PushResult
+    state_saved: bool = False
+
+
+@dataclass
+class PullOutcome:
+    local_path: str
+    # "first-sync" | "fast-forward" | "merged" | "up-to-date" | "local-only" | "error"
+    action: str
+    result: Optional[PullResult] = None
+    has_conflicts: bool = False
+    conflict_count: int = 0
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# State recording
+# ─────────────────────────────────────────────────────────────────────────────
+
+def record_state(
+    state: SyncState,
+    state_path: str,
+    state_dir: str,
+    local_path: str,
+    doc_id: str,
+    backend_name: str,
+    content: str,
+    remote_version: str,
+) -> bool:
+    """Persist sync state after a successful operation. Returns True on success."""
+    try:
+        local_hash = sha256_of_content(content)
+        base_hash = save_base_content(state_dir, content)
+        state.update(
+            local_path,
+            MappingState(
+                doc_id=doc_id,
+                backend=backend_name,
+                last_synced_at=datetime.now(timezone.utc).isoformat(),
+                base_hash=base_hash,
+                remote_version=remote_version,
+                local_hash=local_hash,
+            ),
+        )
+        state.save(state_path)
+        return True
+    except Exception:
+        logger.warning("Failed to save sync state for %s", local_path, exc_info=True)
+        return False
+
+
+def _record_state(
+    state: SyncState,
+    state_path: str,
+    state_dir: str,
+    local_path: str,
+    mapping: "Mapping",
+    content: str,
+    remote_version: str,
+) -> bool:
+    return record_state(
+        state, state_path, state_dir, local_path,
+        mapping.remote_id, mapping.backend, content, remote_version,
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Push orchestration
+# ─────────────────────────────────────────────────────────────────────────────
+
+def orchestrate_push(
+    mapping: "Mapping",
+    backend: Backend,
+    state: SyncState,
+    state_dir: str,
+    state_path: str,
+) -> PushOutcome:
+    result = backend.push(mapping.local, mapping.remote_id)
+    outcome = PushOutcome(local_path=mapping.local, result=result)
+
+    if result.status == "ok" and os.path.exists(mapping.local):
+        try:
+            remote_version = backend.get_remote_version(mapping.remote_id)
+        except Exception:
+            logger.warning(
+                "Could not retrieve remote version after push for %s; "
+                "recording empty version — next pull will re-sync",
+                mapping.remote_id,
+                exc_info=True,
+            )
+            remote_version = ""
+        with open(mapping.local, encoding="utf-8") as fh:
+            content = fh.read()
+        outcome.state_saved = _record_state(
+            state, state_path, state_dir, mapping.local, mapping, content, remote_version
+        )
+
+    return outcome
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Pull orchestration
+# ─────────────────────────────────────────────────────────────────────────────
+
+def orchestrate_pull(
+    mapping: "Mapping",
+    backend: Backend,
+    state: SyncState,
+    state_dir: str,
+    state_path: str,
+) -> PullOutcome:
+    entry = state.get(mapping.local)
+
+    local_exists = os.path.exists(mapping.local)
+    if local_exists:
+        with open(mapping.local, encoding="utf-8") as fh:
+            local_content = fh.read()
+        current_local_hash = sha256_of_content(local_content)
+    else:
+        local_content = ""
+        current_local_hash = ""
+
+    try:
+        remote_version = backend.get_remote_version(mapping.remote_id)
+    except Exception as exc:
+        return PullOutcome(
+            local_path=mapping.local,
+            action="error",
+            result=PullResult(
+                status="error",
+                doc_id=mapping.remote_id,
+                local_path=mapping.local,
+                message=str(exc),
+            ),
+        )
+
+    if entry is None:
+        return _first_sync_pull(mapping, backend, state, state_dir, state_path, remote_version)
+
+    remote_changed = remote_version != entry.remote_version
+    local_changed = local_exists and current_local_hash != entry.local_hash
+
+    if not remote_changed and not local_changed:
+        return PullOutcome(local_path=mapping.local, action="up-to-date")
+
+    if remote_changed and not local_changed:
+        return _fast_forward_pull(
+            mapping, backend, state, state_dir, state_path, remote_version
+        )
+
+    if local_changed and not remote_changed:
+        return PullOutcome(local_path=mapping.local, action="local-only")
+
+    # Both sides changed — three-way merge
+    return _merge_pull(
+        mapping, backend, state, state_dir, state_path,
+        local_content, remote_version, entry.base_hash,
+    )
+
+
+def _first_sync_pull(
+    mapping: "Mapping",
+    backend: Backend,
+    state: SyncState,
+    state_dir: str,
+    state_path: str,
+    remote_version: str,
+) -> PullOutcome:
+    result = backend.pull(mapping.remote_id, mapping.local)
+    outcome = PullOutcome(local_path=mapping.local, action="first-sync", result=result)
+    if result.status == "ok" and os.path.exists(mapping.local):
+        with open(mapping.local, encoding="utf-8") as fh:
+            new_content = fh.read()
+        _record_state(
+            state, state_path, state_dir, mapping.local, mapping,
+            new_content, remote_version or "",
+        )
+    return outcome
+
+
+def _fast_forward_pull(
+    mapping: "Mapping",
+    backend: Backend,
+    state: SyncState,
+    state_dir: str,
+    state_path: str,
+    remote_version: str,
+) -> PullOutcome:
+    result = backend.pull(mapping.remote_id, mapping.local)
+    outcome = PullOutcome(local_path=mapping.local, action="fast-forward", result=result)
+    if result.status == "ok" and os.path.exists(mapping.local):
+        with open(mapping.local, encoding="utf-8") as fh:
+            new_content = fh.read()
+        _record_state(
+            state, state_path, state_dir, mapping.local, mapping,
+            new_content, remote_version,
+        )
+    return outcome
+
+
+def _merge_pull(
+    mapping: "Mapping",
+    backend: Backend,
+    state: SyncState,
+    state_dir: str,
+    state_path: str,
+    local_content: str,
+    remote_version: str,
+    base_hash: str,
+) -> PullOutcome:
+    orig_path = mapping.local + ORIG_SUFFIX
+    with open(orig_path, "w", encoding="utf-8") as fh:
+        fh.write(local_content)
+
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as tmp:
+            tmp_path = tmp.name
+        tmp_result = backend.pull(mapping.remote_id, tmp_path)
+        if tmp_result.status == "ok":
+            with open(tmp_path, encoding="utf-8") as fh:
+                theirs_content = fh.read()
+            os.unlink(tmp_path)
+        else:
+            os.unlink(tmp_path)
+            return PullOutcome(
+                local_path=mapping.local, action="error", result=tmp_result
+            )
+    except Exception as exc:
+        return PullOutcome(
+            local_path=mapping.local,
+            action="error",
+            result=PullResult(
+                status="error",
+                doc_id=mapping.remote_id,
+                local_path=mapping.local,
+                message=str(exc),
+            ),
+        )
+
+    base_content = get_base_content(state_dir, base_hash)
+    merge_result = three_way_merge(base_content, theirs_content, local_content)
+
+    with open(mapping.local, "w", encoding="utf-8") as fh:
+        fh.write(merge_result.merged)
+
+    _record_state(
+        state, state_path, state_dir, mapping.local, mapping,
+        merge_result.merged, remote_version,
+    )
+
+    return PullOutcome(
+        local_path=mapping.local,
+        action="merged",
+        has_conflicts=merge_result.has_conflicts,
+        conflict_count=merge_result.conflict_count,
+    )

docspan/core/paths.py

@@ -0,0 +1,8 @@
+"""Centralised path constants for docspan's local state files."""
+
+STATE_FILENAME = ".markgate-state.json"
+BASE_STORE_DIR = ".markgate-base"
+BASE_FILE_SUFFIX = ".base"
+ORIG_SUFFIX = ".orig"
+COMMENTS_SUFFIX = ".comments.md"
+GOOGLE_TOKEN_PATH = ".markgate/google_token.json"

docspan/core/state.py

@@ -0,0 +1,53 @@
+"""Sync state — tracks last-synced hashes and remote versions per local file."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from typing import Optional
+
+
+@dataclass
+class MappingState:
+    doc_id: str
+    backend: str
+    last_synced_at: str
+    base_hash: str
+    remote_version: str
+    local_hash: str
+
+
+@dataclass
+class SyncState:
+    mappings: dict[str, MappingState] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str) -> "SyncState":
+        if not os.path.exists(path):
+            return cls()
+        with open(path) as f:
+            data = json.load(f)
+        mappings = {k: MappingState(**v) for k, v in data.get("mappings", {}).items()}
+        return cls(mappings=mappings)
+
+    def save(self, path: str) -> None:
+        tmp = path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump({"mappings": {k: asdict(v) for k, v in self.mappings.items()}}, f, indent=2)
+        os.rename(tmp, path)
+
+    def get(self, local_path: str) -> Optional[MappingState]:
+        return self.mappings.get(local_path)
+
+    def update(self, local_path: str, mapping: MappingState) -> None:
+        self.mappings[local_path] = mapping
+
+
+def sha256_of_file(path: str) -> str:
+    with open(path, "rb") as fh:
+        return hashlib.sha256(fh.read()).hexdigest()
+
+
+def sha256_of_content(content: str) -> str:
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()

docspan-0.1.0.dist-info/METADATA

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: docspan
+Version: 0.1.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
+Project-URL: Issues, https://github.com/tstapler/docspan/issues
+Project-URL: Changelog, https://github.com/tstapler/docspan/releases
+Author-email: Tyler Stapler <tystapler@gmail.com>
+License: MIT
+Keywords: cli,confluence,docs-as-code,google-docs,markdown,sync
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Requires-Dist: google-api-python-client>=2.108.0
+Requires-Dist: google-auth-httplib2>=0.1.1
+Requires-Dist: google-auth-oauthlib>=1.1.0
+Requires-Dist: google-auth>=2.23.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: markdownify>=0.11.6
+Requires-Dist: merge3>=0.0.16
+Requires-Dist: mistune>=3.0
+Requires-Dist: pydantic>=2.0.0
+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: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: types-requests>=2.25.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10.0,>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs<2.0,>=1.5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# docspan
+
+[![PyPI](https://img.shields.io/pypi/v/docspan)](https://pypi.org/project/docspan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Push and pull markdown to Google Docs and Confluence from a single CLI. docspan provides bidirectional sync with three-way merge conflict detection, structural diff push that preserves comments on unchanged paragraphs, and a simple YAML-based configuration file.
+
+The config file is named `markgate.yaml` — this name is preserved for backward compatibility and will be renamed in v0.2.0.
+
+---
+
+## Supported Backends
+
+| Backend | Push | Pull |
+|---|---|---|
+| Google Docs | yes | yes |
+| Confluence | yes | yes |
+
+---
+
+## Install
+
+```bash
+pip install docspan
+```
+
+---
+
+## Quick start
+
+**1. Create `markgate.yaml`:**
+
+```yaml
+backends:
+  google_docs:
+    credentials_path: /path/to/service-account.json
+
+mappings:
+  - local: docs/design-doc.md
+    backend: google_docs
+    remote_id: YOUR_GOOGLE_DOC_ID
+    direction: both
+```
+
+**2. Set up authentication:**
+
+```bash
+docspan auth setup google_docs
+# or
+docspan auth setup confluence
+```
+
+**3. Push and pull:**
+
+```bash
+docspan push                     # push all mappings
+docspan pull                     # pull all mappings
+docspan status                   # show mapping table
+```
+
+**4. Resolve conflicts (if any):**
+
+```bash
+docspan conflicts list
+docspan conflicts resolve docs/design-doc.md --accept remote
+```
+
+---
+
+## Configuration (`markgate.yaml`)
+
+```yaml
+backends:
+  google_docs:
+    credentials_path: /path/to/service-account.json  # or use env ACCOUNT_A_CREDENTIALS_PATH
+  confluence:
+    base_url: https://yourorg.atlassian.net
+    username: you@example.com
+    api_token: your-api-token  # or env CONFLUENCE_API_TOKEN
+
+mappings:
+  - local: docs/notes.md
+    backend: google_docs
+    remote_id: YOUR_GOOGLE_DOC_ID
+    direction: both  # push | pull | both
+  - local: docs/page.md
+    backend: confluence
+    remote_id: YOUR_CONFLUENCE_PAGE_ID
+    direction: both
+```
+
+**Note**: `markgate.yaml` is gitignored by default because it may contain API tokens. Commit a `markgate.yaml.example` template alongside it.
+
+---
+
+## Command Reference
+
+### `docspan push`
+
+```
+docspan push [FILES]... [--dry-run] [--config PATH]
+```
+
+Push local markdown files to remote docs. Skips mappings with `direction = "pull"`. Accepts an optional list of local file paths to restrict which mappings are pushed.
+
+### `docspan pull`
+
+```
+docspan pull [FILES]... [--dry-run] [--config PATH]
+```
+
+Pull remote documents into local markdown files with three-way merge. Writes conflict markers to the file if automatic merge fails.
+
+### `docspan status`
+
+```
+docspan status [--config PATH]
+```
+
+Display all configured mappings in a table showing local file, backend, remote ID, and direction.
+
+### `docspan auth setup`
+
+```
+docspan auth setup BACKEND [--config PATH]
+```
+
+Interactive authentication setup. `BACKEND` is one of `google_docs` or `confluence`.
+
+For Google Docs, prints step-by-step service account setup instructions. For Confluence, prompts for base URL, username, and API token, then prints a YAML snippet to add to `markgate.yaml`.
+
+### `docspan conflicts list`
+
+```
+docspan conflicts list [--config PATH]
+```
+
+Scan all tracked files for unresolved merge conflict markers (`<<<<<<< `). Prints a table of conflicted files and conflict block counts.
+
+### `docspan conflicts resolve`
+
+```
+docspan conflicts resolve FILE --accept remote|local|merged [--config PATH]
+```
+
+Resolve a merge conflict in a tracked file.
+
+| Strategy | Behavior |
+|---|---|
+| `remote` | Re-fetch the remote version and overwrite the local file |
+| `local` | Restore the pre-merge local content from the `.orig` backup |
+| `merged` | Accept the current file contents as the resolved version (conflict markers must be removed first) |
+
+---
+
+## Configuration Reference
+
+### `backends.google_docs`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `credentials_path` | string | null | Path to Google service account JSON key |
+| `token_path` | string | `.markgate/google_token.json` | OAuth token storage path |
+
+**Environment variable alternatives:**
+- `ACCOUNT_A_CREDENTIALS_PATH` — path to service account JSON
+- `ACCOUNT_A_CREDENTIALS` — inline service account JSON string
+
+### `backends.confluence`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `base_url` | string | null | Confluence base URL, e.g. `https://yourorg.atlassian.net` |
+| `username` | string | null | Atlassian account email |
+| `api_token` | string | null | API token from id.atlassian.com |
+
+**Environment variable alternatives:**
+- `CONFLUENCE_BASE_URL`
+- `ATLASSIAN_USER_NAME`
+- `CONFLUENCE_API_TOKEN`
+
+### `mappings[]`
+
+| Field | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `local` | string | — | yes | Relative path to local markdown file |
+| `backend` | string | — | yes | `"google_docs"` or `"confluence"` |
+| `remote_id` | string | — | yes | Google Doc ID or Confluence page ID |
+| `direction` | enum | `"both"` | no | `"push"`, `"pull"`, or `"both"` |
+
+---
+
+## State Files
+
+docspan generates these files in your project directory after first sync:
+
+| File | Description |
+|---|---|
+| `.markgate-state.json` | Sync state tracking (content hashes, remote versions) |
+| `.markgate-base/` | Content-addressed store of merge bases |
+| `{file}.orig` | Backup of local file before merge; deleted after conflict resolution |
+| `{file}.comments.md` | Confluence comment sidecar; written during pull if comments exist |
+
+---
+
+## Known Limitations
+
+> [!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)
+> - Push: no image support — local images cannot be pushed to Google Docs or Confluence
+> - 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
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.
+
+For contribution guidelines, see [CONTRIBUTING.md](https://github.com/tstapler/docspan/blob/main/CONTRIBUTING.md).
+For the full change history, see [CHANGELOG.md](https://github.com/tstapler/docspan/blob/main/CHANGELOG.md).