manual_slop/conductor/tracks/gencpp_python_bindings_20260308/plan.md

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