docspan 0.1.0__tar.gz

docspan-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # needed for hatch-vcs version detection
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest --tb=short -q

docspan-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # needed for hatch-vcs version from git tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/docspan
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/docspan
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

docspan-0.1.0/.github/workflows/release-please.yml

@@ -0,0 +1,18 @@
+name: Release Please
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

docspan-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Google API credentials
+credentials.json
+token.json
+*_credentials.json
+account_a_credentials.json
+account_b_credentials.json
+
+# Configuration files with sensitive data
+config.yaml
+markgate.yaml
+
+# State files
+.sync_state.json
+conflicts.log
+.markgate-state.json
+.markgate-base/
+
+# IDE
+.vscode/
+.idea/
+.cursor/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# MkDocs build output
+site/
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfvars
+.terraform.lock.hcl

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

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

docspan-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-07
+
+### Added
+- `docspan push` — push local markdown files to Google Docs or Confluence
+- `docspan pull` — pull remote documents into local markdown files with three-way merge
+- `docspan status` — show current mapping status in a table
+- `docspan auth setup` — interactive authentication setup for `google_docs` and `confluence` backends
+- `docspan conflicts list` — list files with unresolved merge conflicts
+- `docspan conflicts resolve` — resolve merge conflicts with `remote`, `local`, or `merged` strategy
+- Google Docs backend: push and pull via Google Docs API (service account auth)
+- Confluence backend: push and pull via Atlassian REST API (API token auth)
+- Three-way merge for bidirectional sync conflict detection
+- Confluence comment sidecar: pull writes inline and footer comments to `{file}.comments.md`
+- `markgate.yaml` config file format with per-mapping direction control (`push`/`pull`/`both`)
+- Sync state tracking via `.markgate-state.json` and content-addressed base store in `.markgate-base/`
+
+### Known Limitations
+- Google Docs: comments on edited paragraphs are destroyed on push (paragraph-level diff; comments on unchanged paragraphs are preserved)
+- Push: no image support — local image files 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: comment sidecar (`{file}.comments.md`) is informational only; comments cannot be pushed back
+- Config file is named `markgate.yaml` (not `docspan.yaml`) and state file is `.markgate-state.json` (not `.docspan-state.json`). These will be renamed in v0.2.0.
+
+[Unreleased]: https://github.com/tstapler/docspan/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/tstapler/docspan/releases/tag/v0.1.0

docspan-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,148 @@
+# Contributing to docspan
+
+## Prerequisites
+
+- Python 3.9+
+- [uv](https://docs.astral.sh/uv/) — fast Python package manager
+- git
+
+## Dev Setup
+
+```bash
+git clone https://github.com/tstapler/docspan
+cd docspan
+uv venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+docspan --help   # verify the CLI works
+```
+
+## Running Tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=docspan --cov-report=term-missing
+
+# Lint
+ruff check src/ tests/
+
+# Format
+ruff format src/ tests/
+
+# Type check
+mypy src/
+```
+
+## Project Structure
+
+```
+src/docspan/
+├── cli/main.py          <- Typer commands (push, pull, status, auth, conflicts)
+├── config.py            <- MarkgateConfig Pydantic model + YAML loader
+├── backends/
+│   ├── base.py          <- Backend ABC (push, pull, auth_setup, validate_config, get_remote_version)
+│   ├── __init__.py      <- BACKENDS registry {"google_docs": ..., "confluence": ...}
+│   ├── google_docs/     <- Google Docs backend implementation
+│   └── confluence/      <- Confluence backend implementation
+└── core/
+    ├── state.py         <- SyncState / MappingState (JSON persistence)
+    ├── orchestrator.py  <- Push/pull orchestration (conflict detection, three-way merge)
+    ├── merge.py         <- Three-way text merge
+    └── paths.py         <- Path constants (.markgate-state.json, etc.)
+```
+
+## How to Add a New Backend
+
+### Step 1: Create the backend package
+
+```
+src/docspan/backends/myplatform/
+├── __init__.py
+└── backend.py
+```
+
+### Step 2: Implement the Backend ABC in `backend.py`
+
+```python
+from docspan.backends.base import Backend, PushResult, PullResult
+from docspan.config import MarkgateConfig
+
+class MyPlatformBackend(Backend):
+    name = "myplatform"  # must match the key used in markgate.yaml
+
+    def __init__(self, config) -> None:
+        self.config = config
+
+    @classmethod
+    def from_config(cls, markgate_config: MarkgateConfig) -> "MyPlatformBackend":
+        return cls(markgate_config.backends.myplatform)
+
+    def push(self, local_path: str, doc_id: str, **kwargs) -> PushResult:
+        # read local_path, convert to platform format, upload to doc_id
+        # return PushResult(status="ok", doc_id=doc_id, url=url)
+        # on error: return PushResult(status="error", doc_id=doc_id, message=str(exc))
+        ...
+
+    def pull(self, doc_id: str, local_path: str, **kwargs) -> PullResult:
+        # fetch from platform, convert to markdown, write to local_path
+        # return PullResult(status="ok", doc_id=doc_id, local_path=local_path)
+        ...
+
+    def auth_setup(self) -> None:
+        # print setup instructions or run interactive prompts
+        ...
+
+    def get_remote_version(self, doc_id: str) -> str:
+        # return an opaque version token (e.g. revision ID, version number string)
+        # used to detect whether the remote has changed since last sync
+        ...
+
+    def validate_config(self) -> None:
+        # raise ValueError("Missing X. Run: docspan auth setup myplatform") if misconfigured
+        ...
+```
+
+### Step 3: Add a config model to `config.py`
+
+```python
+class MyPlatformConfig(BaseModel):
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+
+class BackendsConfig(BaseModel):
+    google_docs: Optional[GoogleDocsConfig] = None
+    confluence: Optional[ConfluenceConfig] = None
+    myplatform: Optional[MyPlatformConfig] = None  # add this
+```
+
+### Step 4: Register in the `BACKENDS` dict
+
+In `src/docspan/backends/__init__.py`:
+
+```python
+from docspan.backends.myplatform.backend import MyPlatformBackend
+
+BACKENDS: dict[str, type[Backend]] = {
+    "google_docs": GoogleDocsBackend,
+    "confluence": ConfluenceBackend,
+    "myplatform": MyPlatformBackend,  # add this
+}
+```
+
+Then write tests in `tests/backends/test_myplatform.py` and a docs page at `docs/backends/myplatform.md`.
+
+## Note about `markgate.yaml`
+
+The config file is gitignored by default because it contains API tokens. Add your own `markgate.yaml` locally based on the `markgate.yaml.example` template — it will not be committed.
+
+## PR Process
+
+1. Fork the repository and create a feature branch from `main`
+2. Ensure all tests pass: `pytest`
+3. Ensure lint passes: `ruff check src/ tests/`
+4. Add tests for any new functionality
+5. Open a PR against `main` — CI runs `pytest`, `ruff`, and `mypy` automatically
+6. At least one review approval is required before merge; keep each PR to one logical change

docspan-0.1.0/PKG-INFO

@@ -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).

docspan-0.1.0/Procfile

@@ -0,0 +1 @@
+worker: python sync.py