memex/notes/org-skill-org-json-bridge.org

SKILL: Org-JSON Bridge (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Parse Org-mode to JSON AST without loss of hierarchy
    • Render JSON AST back to Org-mode text matching original format
    • Table row injection via JSON manipulation verification
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Python Parser Wrapper
• Phase E: Chaos (Verification)

Overview

The Org-JSON Bridge enables programmatic manipulation of Org-mode files by converting them into a structured JSON representation and vice-versa. This bypasses the fragility of direct string manipulation for complex structures like tables, properties, and source blocks.

Phase A: Demand (PRD)

1. Purpose

Define the interfaces for bidirectional Org-to-JSON conversion.

2. User Needs

• Robust Parsing: Convert Org-mode files into structured JSON AST.
• High-Fidelity Rendering: Re-materialize JSON AST back into syntactically correct Org-mode text.
• Complex Structure Support: Handle tables, property drawers, and source blocks without data loss.
• Programmatic API: Provide a CLI and Lisp interface for other skills to use.

3. Success Criteria

TODO Parse Org-mode to JSON AST without loss of hierarchy

TODO Render JSON AST back to Org-mode text matching original format

TODO Table row injection via JSON manipulation verification

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

The bridge acts as a translator between the human-readable Org AST and the machine-manipulable JSON format.

2. Semantic Interfaces

(defun org-bridge-parse (file-path)
  "Executes the Python parser to output JSON AST.")

(defun org-bridge-render (json-path output-path)
  "Executes the Python renderer to re-create Org text.")

Phase D: Build (Implementation)

Implementation logic is in `projects/org-json-bridge/org_bridge.py`.

Python Parser Wrapper

;; Logic for calling the python bridge

Phase E: Chaos (Verification)

Verification involves round-trip testing: Org -> JSON -> Org must result in a file identical to the source.