Metadata-Version: 2.4
Name: svgn
Version: 0.2.0
Summary: Two-way sync between Linear/Notion and local Markdown files — Docs-as-Code for developers
Author: Sai Revanth
License: MIT License
        
        Copyright (c) 2025 Sai Revanth
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/SaiRevanth25/sovereign-sync
Project-URL: Repository, https://github.com/SaiRevanth25/sovereign-sync
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.3.1
Requires-Dist: md2notion>=2.4.1
Requires-Dist: notion-client>=2.7.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.32.5
Provides-Extra: dev
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: ruff>=0.14.10; extra == "dev"
Dynamic: license-file


# Sovereign Sync (`svgn`)

`svgn` is a professional developer utility that synchronizes your **Linear backlog** and **Notion documentation** with local Markdown files. It enables a "Docs-as-Code" and "Dev-as-Code" workflow, allowing you to manage project execution and technical specifications directly from your code editor.

---

## 📂 Project Structure

The codebase is organized into a modular package for scalability and reliability:

```text
src/svgn/
├── api/             # Low-level API wrappers for Linear & Notion
├── engines/         # Sync logic and state management
├── utils/           # Markdown parsing and Notion block conversion
└── main.py          # CLI Entry point
```

---

## 🛠 Command Reference

### 1. Core Lifecycle Commands

#### `svgn init`
**Run this first.**
- Discovers Linear teams and sets your **Team ID** if not provided.
- Automatically detects **Notion** credentials if present in `.env`.
- Creates `linear_tickets/` and `docs/` directories.
---
#### `svgn sync`
**Linear Master Pull.**
- Fetches all active tickets from Linear and populates your local folders.
- Updates local "fingerprints" to ensure subsequent updates are efficient.

#### `svgn update`
**Local ➡ Linear.**
- Scans `linear_tickets/` for local changes (status moves or text edits).
- Pushes changes to Linear. Uses `.svgn_state` to skip unchanged files.

---

### 2. Documentation (Notion) Commands

#### `svgn docs sync`
**Notion ➡ Local.**
- Downloads your Notion root page and all sub-pages as Markdown files into the `docs/` folder.
- Converts Notion blocks (headings, code, lists) into clean local Markdown.

#### `svgn docs update`
**Local ➡ Notion.**
- Detects edits in your `docs/` folder.
- Clears the corresponding Notion page and re-uploads the fresh Markdown content as blocks.
- **Note:** Only modifies pages that have changed locally.

---

### 3. Utility Commands

#### `svgn inspect`
- Prints valid **Assignee Emails**, **Labels**, and **Projects** from Linear. Use this to ensure your Markdown frontmatter is accurate.

#### `svgn logs`
- Displays a timestamped history of local-to-remote sync operations.

---

## 📋 Full Setup Workflow

1. **Install**: Run `uv pip install -e .` (or `pip install -e .`) from the root directory.
2. **Environment**: Ensure your `.env` contains the following :
   ```env
   LINEAR_API_KEY=...
   LINEAR_TEAM_ID=...
   NOTION_TOKEN=...
   NOTION_ROOT_PAGE_ID=...
   ```
3. **Notion Permission**: Open your [Notion page](https://www.notion.so/profile/integrations), click `...` -> `Connect to` -> and select your Integration.
    - Each page should be given access explicitly in the integrations.
4. **Initialize**:
   ```bash
   svgn init
   svgn sync        # Pull tickets from Linear
   svgn docs sync   # Pull documentation
   ```

---

## 🧠 Using with AI (Cursor / Copilot)

The generated `.cursorrules` file instructs AI agents to respect the `svgn` workflow.

### Example Prompts:

**Planning with Docs:**
> "Read @architecture.md from the docs folder and create three implementation tasks in the todo folder. Assign them to me and run svgn update."

**Executing a Task:**
> "Help me implement the logic described in @setup-database-migration.md. Once done, move the file to the done folder and run svgn sync."

---

## 📄 Metadata Examples

### Linear Ticket (`linear_tickets/todo/task.md`)
```markdown
---
linear_id: "uuid"
title: "Fix Auth Bug"
assignee: "dev@company.com"
labels: ["bug", "security"]
priority: "urgent"
---
## Description
...
```

### Notion Document (`docs/api-spec.md`)
```markdown
---
notion_id: "uuid"
title: "API Specification v2"
---
# API v2
This document tracks our REST endpoints...
```

---

## 🛠 Troubleshooting

- **400 Bad Request (Notion)**: Ensure you have duplicated the Notion page to your private workspace and added the "Connection" via the page settings.
- **Sync Loops**: `svgn` uses `.svgn_state` and `.svgn_docs_state` to store fingerprints. If a file is reverting unexpectedly, run `svgn pull` or `svgn docs sync` to refresh the local state.
