plans and docs

conductor/tracks/gencpp_python_bindings_20260308/plan.md

@@ -0,0 +1,95 @@
+# Plan: Bootstrap gencpp Python Bindings Project
+
+## Overview
+Create standalone Python project with CFFI bindings for gencpp C library.
+
+## Phase 1: Project Setup
+Focus: Create repository structure and CFFI configuration
+
+- [ ] Task 1.1: Create new project directory `gencpp-python-bindings/`
+  - WHERE: New directory outside manual_slop
+  - WHAT: Initialize as Python package with pyproject.toml
+  - HOW: Standard Python package structure
+  - SAFETY: New project, no impact on manual_slop
+
+- [ ] Task 1.2: Set up CFFI in pyproject.toml
+  - WHERE: gencpp-python-bindings/pyproject.toml
+  - WHAT: Add cffi dependency and build requirements
+  - HOW: Standard CFFI setup
+  - SAFETY: New file
+
+- [ ] Task 1.3: Obtain gencpp C library
+  - WHERE: gencpp-python-bindings/lib/
+  - WHAT: Download or reference gencpp_c11.lib from gencpp releases
+  - HOW: Clone gencpp or add as git submodule
+  - SAFETY: External dependency
+
+## Phase 2: CFFI Binding Skeleton
+Focus: Set up FFI and basic type mappings
+
+- [ ] Task 2.1: Create CFFI wrapper module
+  - WHERE: gencpp-python-bindings/src/gencpp/_cffi.py
+  - WHAT: Set up FFI with gencpp C header declarations
+  - HOW: Map basic types from gencpp C API
+  - SAFETY: New module
+
+- [ ] Task 2.2: Define Python Declaration dataclasses
+  - WHERE: gencpp-python-bindings/src/gencpp/models.py
+  - WHAT: Create Declaration, FunctionDecl, StructDecl, EnumDecl, etc.
+  - HOW: Dataclasses matching gencpp AST types
+  - SAFETY: New module
+
+- [ ] Task 2.3: Build minimal CFFI bindings for top-level declarations
+  - WHERE: gencpp-python-bindings/src/gencpp/bindings.py
+  - WHAT: Bind gencpp C functions for parsing and AST traversal
+  - HOW: Focus on Code_Function, Code_Struct, Code_Enum, Code_Typedef
+  - SAFETY: New module
+
+## Phase 3: Python API Implementation
+Focus: Create Python-friendly API
+
+- [ ] Task 3.1: Implement parse_c_file()
+  - WHERE: gencpp-python-bindings/src/gencpp/parser.py
+  - WHAT: Parse C file, return list of Declaration objects
+  - HOW: Call gencpp C library, convert to Python dataclasses
+  - SAFETY: New function
+
+- [ ] Task 3.2: Implement parse_cpp_file()
+  - WHERE: gencpp-python-bindings/src/gencpp/parser.py
+  - WHAT: Parse C++ file, return list of Declaration objects (includes classes)
+  - HOW: Similar to C with additional C++ types
+  - SAFETY: New function
+
+- [ ] Task 3.3: Add skeleton generation helpers
+  - WHERE: gencpp-python-bindings/src/gencpp/skeleton.py
+  - WHAT: Convert Declaration list to skeleton string (matching mcp_client format)
+  - HOW: Format function signatures, struct fields, etc.
+  - SAFETY: New module
+
+## Phase 4: Testing & Documentation
+Focus: Verify bindings work and document
+
+- [ ] Task 4.1: Write basic parse tests
+  - WHERE: gencpp-python-bindings/tests/
+  - WHAT: Test parsing sample C and C++ files
+  - HOW: Use pytest with fixture sample files
+  - SAFETY: New test files
+
+- [ ] Task 4.2: Document API and future expansion
+  - WHERE: gencpp-python-bindings/README.md
+  - WHAT: Document current capabilities, what's missing, how to extend
+  - HOW: Markdown documentation
+  - SAFETY: New documentation
+
+- [ ] Task 4.3: Verify Windows build works
+  - WHERE: Local Windows environment
+  - WHAT: Ensure CFFI can load gencpp_c11.lib
+  - HOW: Run tests on Windows
+  - SAFETY: Validation only
+
+## Future Work (Not This Track)
+- Full AST traversal (beyond top-level)
+- Integration into manual_slop mcp_client as `gencpp_*` tools
+- macOS/Linux support
+- Template parameter parsing
+- Operator overloading resolution