deckops 1.0.0__tar.gz

deckops-1.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: deckops
+Version: 1.0.0
+Summary: Manage Anki decks as Markdown files.
+License: MIT
+Project-URL: Repository, https://github.com/visserle/DeckOps
+Project-URL: Issues, https://github.com/visserle/DeckOps/issues
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: html-to-markdown>=2.24.5
+Requires-Dist: mistune>=3.2.0
+Requires-Dist: pygments>=2.14.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# DeckOps
+
+Manage your Anki decks as Markdown files.
+
+## The Problem
+
+Managing Anki decks through the UI can feel complex and slow, especially with many cards. Working with decks as plain text files would offer a simpler alternative, enabling batch editing, AI-friendliness, version control, easy data sharing, and tool independence.
+
+## The Solution
+
+DeckOps is an Anki ↔ Markdown bridge that solves exactly this problem. Each Anki deck is represented by a Markdown file, and edits in either place can be synced to the other. This enables a hybrid approach between your Anki database and filesystem, allowing for faster editing and easier maintenance.
+
+## Features
+
+- Fully round-trip, bidirectional sync that handles identity, moves, drifts, conflicts, and deletions
+- Markdown support with nearly all features (including syntax-highlighted code blocks, supported on desktop and mobile)
+- Built-in Git integration with autocommit for never losing your data
+- Image support via VS Code where images are directly copied into your Anki media folder (automatically set up)
+- Support for Base Type (Q&A) and Cloze notes
+- Simple CLI interface—after setup, only two commands are needed for daily drive
+
+## Getting Started
+
+1. **Install DeckOps via [pipx](https://github.com/pypa/pipx)**:
+```bash
+pipx install deckops
+```
+2. **Initialize DeckOps**: Make sure that Anki is running, with the [AnkiConnect add-on](https://ankiweb.net/shared/info/2055492159) enabled. Initialize DeckOps in any empty directory of your choosing. This is where your text-based decks will live. The additional tutorial flag creates a sample Markdown deck with further information.
+
+```bash
+deckops init --tutorial
+```
+
+3. **Execute DeckOps**: Import the tutorial deck into Anki. The tutorial deck provides a good starting point for exploring DeckOps features. Import it into Anki using:
+```bash
+deckops ma # markdown to anki (import)
+```
+
+4. **Keep everything in sync**: Each sync is unidirectional—the last sync direction overwrites the other (sync in the same direction per session to avoid losing edits). The CLI provides additional flags for syncing single files or decks. To export changes after reviewing and editing the tutorial in Anki, use:
+
+```bash
+deckops am # anki to markdown (export)
+```
+
+## FAQ
+
+### Is it safe to use?
+
+Yes! DeckOps only acts on its own note types, so your existing collection is never affected. You can mix managed and unmanaged cards in the same deck without issues. Before every DeckOps sync, it automatically creates a Git commit of your Markdown folder so you can always roll your files back if needed. For Anki, additional safety features are implemented. DeckOps only syncs if the activated profiles matches the one it was initialized with. When orpahned DeckOps cards are detected, you will be prompted to confirm their deletion.
+
+### How do I create new cards?
+
+Create a new Markdown file in your initialized DeckOps folder. For the first import, the file name will act as the deck name. Subdecks are supported via two underscores `__` (Anki's `::` is not supported in the file system). Start by writing your cards in Markdown. For each card, you can decide whether to use the QA or cloze format. Cards must be separated by a new line, three dashes `---`, and another new line.
+
+```markdown
+Q: Question text here
+A: Answer text here
+E: Extra information (optional)
+M: Content behind a "more" button (optional)
+
+---
+
+T: Text with {{c1::multiple}} {{c2::cloze deletions}}.
+E: ![image with set width](im.png){width=700}
+
+---
+
+And so on…
+```
+
+### Which characters or symbols cannot be used?
+
+Since cards are separated by horizontal lines (`---`), they cannot be used within the content fields of your cards. This includes all special Markdown characters that render these lines (`***`, `___`), and `<hr>`.
+
+### How does it work?
+
+On first import, DeckOps assigns IDs from Anki to each deck/note/card for tracking. They are represented by a single-line HTML tag (e.g., `<!-- card_id: 1770487991522 -->`) above a card in the Markdown. With the IDs in place, we can track what is new, changed, moved between decks, or deleted, and DeckOps will sync accordingly. Note that one DeckOps folder represents an entire Anki profile.
+
+### Why do some cards have a `card_id` and others a `note_id`?
+
+`DeckOpsQA` cards have a `card_id`, while `DeckOpsCloze` cards have a `note_id` HTML tag. This is because cloze notes can generate multiple cards. If you want to transform a Cloze note into a QA card in Markdown, make sure to change the prefix from `T:` to `Q:` & `A:` and delete the old `note_id`. DeckOps will assign a new `card_id` in the next import.
+
+### What is the recommended workflow?
+
+We recommend using VS Code. It has excellent AI integration, a great [add-on](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced) for Markdown previews, and supports image pasting (which will be saved in your Anki media folder by default).
+
+### How can I migrate my existing cards into DeckOps?
+
+While it is doable, the migration can be tricky. If you convert your cards into DeckOps' note types, then all you need to do is export your cards from Anki to Markdown. In the first re-import, some formatting may be changed because the original HTML from Anki may not follow the CommonMark standard; however, all changes are easily trackable via Git. If your note format does not work with the DeckOps format, you will have to adapt the code to your needs.
+
+### How can I develop DeckOps locally?
+
+Fork this repository and initialize the tutorial in your root folder (make sure Anki is running). This will create a folder called `collection` with the sample Markdown in it. Paths will adapt automatically to the development environment. You can run DeckOps using the main script:
+```bash
+python -m main init --tutorial
+python -m main ma
+```
+
+### How does DeckOps solve bidirectional sync? (Claude's answer)
+
+DeckOps handles the core challenges of bidirectional synchronization between markdown and Anki:
+
+#### 1. Identity
+
+**Solution**: Embed immutable IDs directly in markdown as HTML comments
+
+- **Deck Identity**: `<!-- deck_id: 1234567890 -->` on first line of file
+- **Card Identity** (QA cards): `<!-- card_id: 1770487991522 -->` before each card
+- **Note Identity** (Cloze): `<!-- note_id: 1770487991521 -->` before each note
+
+IDs are Anki's native IDs (timestamps in milliseconds), written to Markdown on first sync and persisting across all future syncs, enabling bidirectional linking.
+
+
+#### 2. Moves (Between Decks)
+
+**Solution**: Move detection + automatic deck correction
+
+**Import (Markdown → Anki)**:
+When you move a card between markdown files:
+1. Cut card from `DeckA.md` (keeping its ID)
+2. Paste into `DeckB.md`
+3. Import detects card in wrong deck → **auto-moves to DeckB**
+4. **Review history preserved** 
+
+
+**Export (Anki → Markdown)**:
+When you move a card between decks in Anki:
+1. Export detects card disappeared from DeckA, appeared in DeckB
+2. Reports as move (not deletion + creation)
+3. Card appears in correct Markdown file
+
+Note: Deck renaming is only possible via export (Anki → Markdown). While import (Markdown → Anki) can be used to create new decks named after the file, renaming decks should always happen via export. Since the `deck_id` is not dependent on the file name, there is no conflict when the Markdown file name differs from a deck's name in Anki.
+
+#### 3. Conflict Resolution
+
+**Solution**: **Last sync direction wins** (no merging)
+
+**Import (Markdown → Anki)**:
+- Markdown content **overwrites** Anki content
+- Updates existing cards with markdown content
+- If fields match → skip (optimization)
+- If fields differ → markdown wins
+
+**Export (Anki → Markdown)**:
+- Anki content **overwrites** Markdown content
+- Existing blocks replaced with Anki's current state
+- Deck renames reflected in file renames
+
+This simple approach requires discipline: always sync in the same direction for a given edit session.
+
+#### 4. Drift Detection & Recovery
+
+**Solution**: "Stale card" detection with automatic re-creation
+
+**What is drift?**
+- Card exists in Markdown with `card_id: 123`
+- But ID 123 no longer exists in Anki (manually deleted)
+
+**How it's resolved**:
+1. Phase 1: Try to update card 123 → fails
+2. Mark as "stale"
+3. Phase 3: Re-create in Anki with new ID (e.g., 456)
+4. Phase 4: Update Markdown: `<!-- card_id: 123 -->` → `<!-- card_id: 456 -->`
+
+**Result**: Drift is automatically healed. Content preserved, but review history lost (new card).
+
+#### 5. Deletions
+
+**Solution**: Bidirectional orphan cleanup
+
+**Markdown → Anki (Import)**:
+- Cards in Anki deck but NOT in Markdown file → deleted from Anki
+- Exception: Cards claimed by other files are moved, not deleted
+
+**Anki → Markdown (Export)**:
+- **Orphaned decks**: File has `deck_id` but deck doesn't exist → delete file
+- **Orphaned cards**: Card has `card_id` but card doesn't exist → remove block
+
+Deletions propagate in both directions to maintain consistency.
+
+#### Summary
+
+| Challenge | Solution | Preserves History? |
+|-----------|----------|-------------------|
+| **Identity** | Embed Anki IDs in Markdown |  Yes |
+| **Moves** | Auto-move + global tracking |  Yes |
+| **Conflicts** | Last sync wins (no merge) |  Yes |
+| **Drift** | Stale card detection + re-creation | No |
+| **Deletions** | Bidirectional orphan cleanup | N/A |
+
+---
+
+## Support This Project
+
+If DeckOps saves you time or makes your workflow better, consider buying me a coffee—it would make my day!
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/visserle)
+
+MIT License

deckops-1.0.0/README.md

@@ -0,0 +1,199 @@
+# DeckOps
+
+Manage your Anki decks as Markdown files.
+
+## The Problem
+
+Managing Anki decks through the UI can feel complex and slow, especially with many cards. Working with decks as plain text files would offer a simpler alternative, enabling batch editing, AI-friendliness, version control, easy data sharing, and tool independence.
+
+## The Solution
+
+DeckOps is an Anki ↔ Markdown bridge that solves exactly this problem. Each Anki deck is represented by a Markdown file, and edits in either place can be synced to the other. This enables a hybrid approach between your Anki database and filesystem, allowing for faster editing and easier maintenance.
+
+## Features
+
+- Fully round-trip, bidirectional sync that handles identity, moves, drifts, conflicts, and deletions
+- Markdown support with nearly all features (including syntax-highlighted code blocks, supported on desktop and mobile)
+- Built-in Git integration with autocommit for never losing your data
+- Image support via VS Code where images are directly copied into your Anki media folder (automatically set up)
+- Support for Base Type (Q&A) and Cloze notes
+- Simple CLI interface—after setup, only two commands are needed for daily drive
+
+## Getting Started
+
+1. **Install DeckOps via [pipx](https://github.com/pypa/pipx)**:
+```bash
+pipx install deckops
+```
+2. **Initialize DeckOps**: Make sure that Anki is running, with the [AnkiConnect add-on](https://ankiweb.net/shared/info/2055492159) enabled. Initialize DeckOps in any empty directory of your choosing. This is where your text-based decks will live. The additional tutorial flag creates a sample Markdown deck with further information.
+
+```bash
+deckops init --tutorial
+```
+
+3. **Execute DeckOps**: Import the tutorial deck into Anki. The tutorial deck provides a good starting point for exploring DeckOps features. Import it into Anki using:
+```bash
+deckops ma # markdown to anki (import)
+```
+
+4. **Keep everything in sync**: Each sync is unidirectional—the last sync direction overwrites the other (sync in the same direction per session to avoid losing edits). The CLI provides additional flags for syncing single files or decks. To export changes after reviewing and editing the tutorial in Anki, use:
+
+```bash
+deckops am # anki to markdown (export)
+```
+
+## FAQ
+
+### Is it safe to use?
+
+Yes! DeckOps only acts on its own note types, so your existing collection is never affected. You can mix managed and unmanaged cards in the same deck without issues. Before every DeckOps sync, it automatically creates a Git commit of your Markdown folder so you can always roll your files back if needed. For Anki, additional safety features are implemented. DeckOps only syncs if the activated profiles matches the one it was initialized with. When orpahned DeckOps cards are detected, you will be prompted to confirm their deletion.
+
+### How do I create new cards?
+
+Create a new Markdown file in your initialized DeckOps folder. For the first import, the file name will act as the deck name. Subdecks are supported via two underscores `__` (Anki's `::` is not supported in the file system). Start by writing your cards in Markdown. For each card, you can decide whether to use the QA or cloze format. Cards must be separated by a new line, three dashes `---`, and another new line.
+
+```markdown
+Q: Question text here
+A: Answer text here
+E: Extra information (optional)
+M: Content behind a "more" button (optional)
+
+---
+
+T: Text with {{c1::multiple}} {{c2::cloze deletions}}.
+E: ![image with set width](im.png){width=700}
+
+---
+
+And so on…
+```
+
+### Which characters or symbols cannot be used?
+
+Since cards are separated by horizontal lines (`---`), they cannot be used within the content fields of your cards. This includes all special Markdown characters that render these lines (`***`, `___`), and `<hr>`.
+
+### How does it work?
+
+On first import, DeckOps assigns IDs from Anki to each deck/note/card for tracking. They are represented by a single-line HTML tag (e.g., `<!-- card_id: 1770487991522 -->`) above a card in the Markdown. With the IDs in place, we can track what is new, changed, moved between decks, or deleted, and DeckOps will sync accordingly. Note that one DeckOps folder represents an entire Anki profile.
+
+### Why do some cards have a `card_id` and others a `note_id`?
+
+`DeckOpsQA` cards have a `card_id`, while `DeckOpsCloze` cards have a `note_id` HTML tag. This is because cloze notes can generate multiple cards. If you want to transform a Cloze note into a QA card in Markdown, make sure to change the prefix from `T:` to `Q:` & `A:` and delete the old `note_id`. DeckOps will assign a new `card_id` in the next import.
+
+### What is the recommended workflow?
+
+We recommend using VS Code. It has excellent AI integration, a great [add-on](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced) for Markdown previews, and supports image pasting (which will be saved in your Anki media folder by default).
+
+### How can I migrate my existing cards into DeckOps?
+
+While it is doable, the migration can be tricky. If you convert your cards into DeckOps' note types, then all you need to do is export your cards from Anki to Markdown. In the first re-import, some formatting may be changed because the original HTML from Anki may not follow the CommonMark standard; however, all changes are easily trackable via Git. If your note format does not work with the DeckOps format, you will have to adapt the code to your needs.
+
+### How can I develop DeckOps locally?
+
+Fork this repository and initialize the tutorial in your root folder (make sure Anki is running). This will create a folder called `collection` with the sample Markdown in it. Paths will adapt automatically to the development environment. You can run DeckOps using the main script:
+```bash
+python -m main init --tutorial
+python -m main ma
+```
+
+### How does DeckOps solve bidirectional sync? (Claude's answer)
+
+DeckOps handles the core challenges of bidirectional synchronization between markdown and Anki:
+
+#### 1. Identity
+
+**Solution**: Embed immutable IDs directly in markdown as HTML comments
+
+- **Deck Identity**: `<!-- deck_id: 1234567890 -->` on first line of file
+- **Card Identity** (QA cards): `<!-- card_id: 1770487991522 -->` before each card
+- **Note Identity** (Cloze): `<!-- note_id: 1770487991521 -->` before each note
+
+IDs are Anki's native IDs (timestamps in milliseconds), written to Markdown on first sync and persisting across all future syncs, enabling bidirectional linking.
+
+
+#### 2. Moves (Between Decks)
+
+**Solution**: Move detection + automatic deck correction
+
+**Import (Markdown → Anki)**:
+When you move a card between markdown files:
+1. Cut card from `DeckA.md` (keeping its ID)
+2. Paste into `DeckB.md`
+3. Import detects card in wrong deck → **auto-moves to DeckB**
+4. **Review history preserved** 
+
+
+**Export (Anki → Markdown)**:
+When you move a card between decks in Anki:
+1. Export detects card disappeared from DeckA, appeared in DeckB
+2. Reports as move (not deletion + creation)
+3. Card appears in correct Markdown file
+
+Note: Deck renaming is only possible via export (Anki → Markdown). While import (Markdown → Anki) can be used to create new decks named after the file, renaming decks should always happen via export. Since the `deck_id` is not dependent on the file name, there is no conflict when the Markdown file name differs from a deck's name in Anki.
+
+#### 3. Conflict Resolution
+
+**Solution**: **Last sync direction wins** (no merging)
+
+**Import (Markdown → Anki)**:
+- Markdown content **overwrites** Anki content
+- Updates existing cards with markdown content
+- If fields match → skip (optimization)
+- If fields differ → markdown wins
+
+**Export (Anki → Markdown)**:
+- Anki content **overwrites** Markdown content
+- Existing blocks replaced with Anki's current state
+- Deck renames reflected in file renames
+
+This simple approach requires discipline: always sync in the same direction for a given edit session.
+
+#### 4. Drift Detection & Recovery
+
+**Solution**: "Stale card" detection with automatic re-creation
+
+**What is drift?**
+- Card exists in Markdown with `card_id: 123`
+- But ID 123 no longer exists in Anki (manually deleted)
+
+**How it's resolved**:
+1. Phase 1: Try to update card 123 → fails
+2. Mark as "stale"
+3. Phase 3: Re-create in Anki with new ID (e.g., 456)
+4. Phase 4: Update Markdown: `<!-- card_id: 123 -->` → `<!-- card_id: 456 -->`
+
+**Result**: Drift is automatically healed. Content preserved, but review history lost (new card).
+
+#### 5. Deletions
+
+**Solution**: Bidirectional orphan cleanup
+
+**Markdown → Anki (Import)**:
+- Cards in Anki deck but NOT in Markdown file → deleted from Anki
+- Exception: Cards claimed by other files are moved, not deleted
+
+**Anki → Markdown (Export)**:
+- **Orphaned decks**: File has `deck_id` but deck doesn't exist → delete file
+- **Orphaned cards**: Card has `card_id` but card doesn't exist → remove block
+
+Deletions propagate in both directions to maintain consistency.
+
+#### Summary
+
+| Challenge | Solution | Preserves History? |
+|-----------|----------|-------------------|
+| **Identity** | Embed Anki IDs in Markdown |  Yes |
+| **Moves** | Auto-move + global tracking |  Yes |
+| **Conflicts** | Last sync wins (no merge) |  Yes |
+| **Drift** | Stale card detection + re-creation | No |
+| **Deletions** | Bidirectional orphan cleanup | N/A |
+
+---
+
+## Support This Project
+
+If DeckOps saves you time or makes your workflow better, consider buying me a coffee—it would make my day!
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/visserle)
+
+MIT License

deckops-1.0.0/deckops/__init__.py

@@ -0,0 +1,4 @@
+from deckops.cli import main
+
+__version__ = "1.0.0"
+__all__ = ["main", "__version__"]

deckops-1.0.0/deckops/anki_client.py

@@ -0,0 +1,32 @@
+"""Shared AnkiConnect client and helpers used by both import/export scripts."""
+
+import re
+from typing import Any
+
+import requests
+
+from deckops.config import ANKI_CONNECT_URL
+
+
+def invoke(action: str, **params) -> Any:
+    """Send a request to AnkiConnect and return the result.
+
+    Raises an Exception when AnkiConnect returns an error.
+    """
+    response = requests.post(
+        ANKI_CONNECT_URL,
+        json={"action": action, "version": 6, "params": params},
+        timeout=10,
+    )
+    result = response.json()
+    if result.get("error"):
+        raise Exception(f"AnkiConnect error: {result['error']}")
+    return result["result"]
+
+
+def extract_deck_id(content: str) -> tuple[int | None, str]:
+    """Extract deck_id from the first line and return (deck_id, remaining content)."""
+    match = re.match(r"<!--\s*deck_id:\s*(\d+)\s*-->\n?", content)
+    if match:
+        return int(match.group(1)), content[match.end() :]
+    return None, content