Add markdown directory sync plugin in Python

Author: luuuc

examples/plugins/shape-sync-markdowndir-python/README.md

@@ -0,0 +1,126 @@
+# shape-sync-markdowndir-python
+
+A sync plugin for Shape CLI that stores briefs as individual markdown files with YAML frontmatter. Implemented in Python using only standard library dependencies.
+
+## Requirements
+
+- Python 3.7+
+
+## Installation
+
+```bash
+# Make executable
+chmod +x shape-sync-markdowndir-python
+
+# Option 1: Add to PATH
+ln -s $(pwd)/shape-sync-markdowndir-python ~/.local/bin/
+
+# Option 2: Add plugin directory to Shape config
+shape config set plugin_dirs "$(pwd)"
+```
+
+## Configuration
+
+Set the output directory via environment variable:
+
+```bash
+export SHAPE_SYNC_MARKDOWN_DIR="./my-pitches"
+```
+
+Default: `./pitches`
+
+## Usage
+
+The plugin syncs briefs to individual markdown files with YAML frontmatter.
+
+```bash
+# Test the plugin
+shape sync test shape-sync-markdowndir-python
+
+# Push briefs to markdown files
+shape sync push shape-sync-markdowndir-python
+
+# Pull briefs from markdown files
+shape sync pull shape-sync-markdowndir-python
+
+# Check sync status
+shape sync status shape-sync-markdowndir-python
+```
+
+## File Format
+
+Each brief is stored as a markdown file with YAML frontmatter:
+
+```markdown
+---
+id: b-123
+title: "My Feature"
+status: proposed
+appetite: 2-week
+synced_at: 2024-01-15T10:30:00Z
+---
+
+The body content of the brief goes here...
+```
+
+Files are named using the pattern: `{id}-{slugified-title}.md`
+
+Example: `b-123-my-feature.md`
+
+## Protocol
+
+### Manifest
+
+```bash
+./shape-sync-markdowndir-python --manifest
+```
+
+Returns:
+```json
+{"name":"shape-sync-markdowndir-python","version":"1.0.0","description":"Sync briefs to markdown directory (Python)","type":"sync","operations":["push","pull","status","test"]}
+```
+
+### Operations
+
+All operations receive JSON on stdin and return JSON on stdout.
+
+#### test
+
+Tests that the plugin is working.
+
+```bash
+echo '{"operation":"test","params":{}}' | ./shape-sync-markdowndir-python
+```
+
+#### push
+
+Writes briefs as individual markdown files.
+
+```bash
+echo '{"operation":"push","params":{"briefs":[{"id":"b-123","title":"Test Brief","status":"proposed","appetite":"2-week","body":"# Problem\n\nDescription here..."}]}}' | ./shape-sync-markdowndir-python
+```
+
+#### pull
+
+Reads briefs from markdown files in the output directory.
+
+```bash
+echo '{"operation":"pull","params":{}}' | ./shape-sync-markdowndir-python
+```
+
+#### status
+
+Returns the count of synced briefs.
+
+```bash
+echo '{"operation":"status","params":{}}' | ./shape-sync-markdowndir-python
+```
+
+## Why Python?
+
+This plugin showcases Python's strengths for scripting:
+
+1. **Ubiquity**: Python is pre-installed on most systems
+2. **Readable**: Clear, explicit code that's easy to understand and modify
+3. **Zero dependencies**: Uses only Python standard library (`json`, `os`, `re`, `sys`, `datetime`)
+4. **Cross-platform**: Works on Windows, macOS, and Linux without changes

examples/plugins/shape-sync-markdowndir-python/shape-sync-markdowndir-python

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+OUTPUT_DIR = os.environ.get("SHAPE_SYNC_MARKDOWN_DIR", "./pitches")
+
+MANIFEST = {
+    "name": "shape-sync-markdowndir-python",
+    "version": "1.0.0",
+    "description": "Sync briefs to markdown directory (Python)",
+    "type": "sync",
+    "operations": ["push", "pull", "status", "test"],
+}
+
+
+def slugify(title):
+    slug = title.lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)
+    slug = slug.strip("-")
+    return slug
+
+
+def generate_markdown(brief):
+    lines = ["---"]
+    lines.append(f"id: {brief['id']}")
+    lines.append(f"title: \"{brief['title']}\"")
+    lines.append(f"status: {brief.get('status', 'proposed')}")
+    if brief.get("appetite"):
+        lines.append(f"appetite: {brief['appetite']}")
+    synced_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    lines.append(f"synced_at: {synced_at}")
+    lines.append("---")
+    lines.append("")
+    lines.append(brief.get("body", ""))
+    return "\n".join(lines)
+
+
+def parse_frontmatter(content):
+    match = re.match(r"^---\n(.+?)\n---\n\n?(.*)", content, re.DOTALL)
+    if not match:
+        return None
+
+    frontmatter_text = match.group(1)
+    body = match.group(2)
+
+    brief = {"body": body}
+
+    for line in frontmatter_text.split("\n"):
+        if line.startswith("id:"):
+            brief["id"] = line[3:].strip()
+        elif line.startswith("title:"):
+            title = line[6:].strip()
+            title = title.strip('"')
+            brief["title"] = title
+        elif line.startswith("status:"):
+            brief["status"] = line[7:].strip()
+        elif line.startswith("appetite:"):
+            brief["appetite"] = line[9:].strip()
+
+    return brief
+
+
+def handle_test():
+    return {"success": True}
+
+
+def handle_push(params):
+    briefs = params.get("briefs", [])
+
+    os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+    mappings = []
+    for brief in briefs:
+        filename = f"{brief['id']}-{slugify(brief['title'])}.md"
+        filepath = os.path.join(OUTPUT_DIR, filename)
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(generate_markdown(brief))
+
+        mappings.append({
+            "local_id": brief["id"],
+            "remote_id": filename,
+            "entity_type": "brief",
+        })
+
+    return {
+        "success": True,
+        "data": {
+            "pushed": len(briefs),
+            "pulled": 0,
+            "conflicts": 0,
+            "errors": [],
+            "mappings": mappings,
+        },
+    }
+
+
+def handle_pull():
+    if not os.path.isdir(OUTPUT_DIR):
+        return {
+            "success": True,
+            "data": {
+                "briefs": [],
+                "tasks": [],
+                "mappings": [],
+                "pushed": 0,
+                "pulled": 0,
+                "conflicts": 0,
+                "errors": [],
+            },
+        }
+
+    briefs = []
+    for filename in os.listdir(OUTPUT_DIR):
+        if not filename.endswith(".md"):
+            continue
+
+        filepath = os.path.join(OUTPUT_DIR, filename)
+        with open(filepath, encoding="utf-8") as f:
+            content = f.read()
+
+        brief = parse_frontmatter(content)
+        if brief:
+            briefs.append(brief)
+
+    return {
+        "success": True,
+        "data": {
+            "briefs": briefs,
+            "tasks": [],
+            "mappings": [],
+            "pushed": 0,
+            "pulled": len(briefs),
+            "conflicts": 0,
+            "errors": [],
+        },
+    }
+
+
+def handle_status():
+    count = 0
+    if os.path.isdir(OUTPUT_DIR):
+        count = len([f for f in os.listdir(OUTPUT_DIR) if f.endswith(".md")])
+
+    return {
+        "success": True,
+        "data": {
+            "mapped_briefs": count,
+            "mapped_tasks": 0,
+        },
+    }
+
+
+def handle_request(request):
+    operation = request.get("operation")
+    params = request.get("params", {})
+
+    if operation == "test":
+        return handle_test()
+    elif operation == "push":
+        return handle_push(params)
+    elif operation == "pull":
+        return handle_pull()
+    elif operation == "status":
+        return handle_status()
+    else:
+        return {"success": False, "error": f"Unknown operation: {operation}"}
+
+
+if __name__ == "__main__":
+    if "--manifest" in sys.argv:
+        print(json.dumps(MANIFEST))
+    else:
+        request = json.loads(sys.stdin.readline())
+        response = handle_request(request)
+        print(json.dumps(response))