# Track Specification: Bootstrap gencpp Python Bindings Project

## Overview

Create a new standalone Python project to build CFFI bindings for gencpp (C/C++ staged metaprogramming library). This will eventually provide richer C++ AST understanding than tree-sitter (full type information, operators, specifiers) but is a longer-term effort. This track bootstraps the project structure and initial bindings.

## Current State Audit

### gencpp Analysis (from research)
- **gencpp**: C++ library for staged metaprogramming with built-in C/C++ parser
- **Parser**: Non-standards-compliant single-pass parser for declarations/definitions
- **NOT execution-aware**: Does NOT parse expressions or statements (only declarations)
- **AST Types**: Code_Class, Code_Struct, Code_Function, Code_Enum, Code_Typedef, etc.
- **Available bindings**: Odin (82KB binding file demonstrates scope)
- **Repository**: https://github.com/Ed94/gencpp

### What gencpp Can Extract
- Function declarations and definitions (signatures only)
- Class/struct/enum/union definitions
- Type aliases (typedef)
- Template declarations (partial)
- Access specifiers
- Operators (overload resolution)
- Preprocessor includes/defines

### What gencpp CANNOT Do
- Parse function bodies/implementations
- Expression evaluation
- Template instantiation

## Goals

1. Create new Python project structure for gencpp bindings
2. Set up CFFI to interface with gencpp C library
3. Build minimal viable bindings for declaration extraction
4. Create Python API matching existing mcp_client patterns
5. Document future expansion path

## Functional Requirements

### Project Setup
- Create new repository/project: `gencpp-python-bindings` (or `pygencpp`)
- Use CFFI for C library binding (pure Python, no C extension compilation required for basic use)
- Structure: Python package with CFFI-based wrapper

### Core API (Phase 1)
| Function | Description |
|----------|-------------|
| `parse_c_file(path) -> List[Declaration]` | Parse C file, return declarations |
| `parse_cpp_file(path) -> List[Declaration]` | Parse C++ file, return declarations |
| `Declaration` dataclass | name, type, line_number, node_type |

### Declaration Types to Bind
- `Code_Function` / `Code_Function_Fwd`
- `Code_Struct` / `Code_Struct_Fwd`
- `Code_Enum` / `Code_Enum_Fwd`
- `Code_Union` / `Code_Union_Fwd`
- `Code_Typedef`
- `Code_Class` (C++)
- `Code_Namespace` (C++)

### Integration Points (Future)
- Design Python API to match mcp_client patterns for easy integration
- Allow language parameter: `parse_file(path, language: str)`
- Return structured data suitable for skeleton generation

## Non-Functional Requirements

- Pure Python with CFFI (no compiled extensions required at install time)
- Must work on Windows (gencpp provides win64 precompiled library)
- Follow existing 1-space indentation code style
- Include type hints for all public APIs

## Architecture Reference

- **gencpp C library**: Precompiled `gencpp_c11.lib` (Windows) or source compilation
- **CFFI pattern**: Use `cffi.FFI().set_source()` to wrap C library
- **Odin bindings reference**: https://github.com/Ed94/gencpp-odin (shows AST type scope)
- **Existing mcp_client pattern**: `src/mcp_client.py` tool dispatch

## Out of Scope (This Track)
- Full AST traversal (only top-level declarations)
- Expression parsing
- Template instantiation analysis
- Integration into Manual Slop (future track)
- macOS/Linux support (Windows first)

## Relationship to Tree-Sitter Track

This is a SEPARATE long-term effort. The tree-sitter track provides immediate C/C++ support. The gencpp bindings track is for future richer functionality:

| Aspect | tree-sitter (Track 1) | gencpp (This Track) |
|--------|---------------------|---------------------|
| Scope | Per-file syntax | Per-file declarations |
| Types | Syntax nodes only | Named types, operators |
| Timeline | Immediate | Months |
| Effort | 1-2 weeks | Ongoing |

The tools will be named `ts_c_*` / `ts_cpp_*` for tree-sitter to leave namespace open for `gencpp_*` tools in the future.