Dev

.github/workflows/dev.yml

@@ -0,0 +1,70 @@
+name: flet-pkg - Dev
+
+on:
+  push:
+    branches: [ dev ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [
+          "3.10",
+#          "3.11",
+          "3.13",
+#          "3.14"
+        ]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up UV and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache UV dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-py${{ matrix.python-version }}-
+            uv-${{ runner.os }}-
+
+      - name: Sync dependencies with UV
+        run: |
+          uv sync --dev --frozen --no-editable
+
+      - name: Check code formatting with Ruff
+        run: |
+          uv tool run ruff format --check
+
+      - name: Lint with Ruff
+        run: |
+          uv tool run ruff check
+
+      - name: Check types with ty
+        run: |
+          uv tool run ty check
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest -v -m "not network" --cov=flet_pkg --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          flags: unittests
+          fail_ci_if_error: false
+
+      - name: Build docs
+        if: matrix.python-version == '3.13'
+        run: |
+          uv sync --group docs --frozen --no-editable
+          NO_MKDOCS_2_WARNING=1 uv run --group docs mkdocs build --strict

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up UV and Python
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Cache UV dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-docs-${{ runner.os }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-docs-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          uv sync --group docs --frozen --no-editable
+
+      - name: Build documentation
+        run: |
+          NO_MKDOCS_2_WARNING=1 uv run --group docs mkdocs build --strict
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -0,0 +1,105 @@
+name: flet-pkg - Main
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [
+          "3.10",
+#          "3.11",
+          "3.13",
+#          "3.14"
+        ]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up UV and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache UV dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-py${{ matrix.python-version }}-
+            uv-${{ runner.os }}-
+
+      - name: Sync dependencies with UV
+        run: |
+          uv sync --dev --frozen --no-editable
+
+      - name: Check code formatting with Ruff
+        run: |
+          uv tool run ruff format --check
+
+      - name: Lint with Ruff
+        run: |
+          uv tool run ruff check
+
+      - name: Check types with ty
+        run: |
+          uv tool run ty check
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest -v -m "not network" --cov=flet_pkg --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          flags: unittests
+          fail_ci_if_error: false
+
+      - name: Build docs
+        if: matrix.python-version == '3.13'
+        run: |
+          uv sync --group docs --frozen --no-editable
+          NO_MKDOCS_2_WARNING=1 uv run --group docs mkdocs build --strict
+
+      - name: Verify version was bumped
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch origin main
+
+          # Skip version check if only docs/examples changed
+          changed=$(git diff --name-only origin/main...HEAD)
+          code_changed=$(echo "$changed" | grep -vE '^(docs/|examples/|README\.md|mkdocs\.yml|scripts/|\.github/)' || true)
+
+          if [ -z "$code_changed" ]; then
+            echo "✅ Docs/examples-only PR — version bump not required"
+            exit 0
+          fi
+
+          current=$(grep -E '^version = ' pyproject.toml | cut -d'"' -f2)
+
+          if [[ ! $current =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "❌ Version must follow semantic versioning (e.g., 0.2.0)"
+            exit 1
+          fi
+
+          base=$(git show origin/main:pyproject.toml | grep -E '^version = ' | cut -d'"' -f2)
+
+          if [ "$current" = "$base" ]; then
+            echo "❌ Version not bumped: $current (same as main)"
+            exit 1
+          fi
+
+          echo "✅ Version bumped: $base -> $current"

.gitignore

@@ -5,6 +5,7 @@
 *.swp
 *.tmp
 *.lock
+!uv.lock
 .DS_Store
 .atom/
 .buildlog/
@@ -238,9 +239,5 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
-dart_wrappers/
-package/
-flet_pkg/python_wrappers/
-
 .claude
 tmp

CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## [0.1.0] - 2026-03-05
+
+### Added
+
+- **CLI tool** (`flet-pkg create`) with interactive and non-interactive modes for scaffolding Flet extension packages.
+- **Auto-detect extension type** — downloads the Flutter package and inspects Dart source to determine `service` or `ui_control` automatically.
+- **Deterministic generation pipeline** — download, parse, analyze, generate, write — produces Python controls, Dart bridge code, type mappings, enum definitions, and event handlers from any Flutter package on pub.dev.
+- **Service extensions** (`ft.Service`) with async method invocation via `invoke_method`.
+- **UI Control extensions** (`ft.LayoutControl`) with constructor-to-property mapping.
+- **Sub-module grouping** — related Dart classes (e.g. `OneSignalUser`, `OneSignalNotifications`) become separate Python modules.
+- **Compound widget detection** — typed sub-widget constructor params become `ft.Control` sub-classes.
+- **Stream event detection** — `Stream<T> get onXxx` patterns become Python `ft.EventHandler` attributes.
+- **Platform interface resolution** — downloads `*_platform_interface` packages to fill stub enum values and data class fields.
+- **Type mapping** — comprehensive Dart-to-Python/Flet type mapping (`core/type_map.py`) including Flutter enums, generics, and nullable types.
+- **Name conflict detection** — checks PyPI, GitHub, and Flet SDK monorepo before creating a package.
+- **Verbose mode** (`-v`) with deterministic coverage score and Rich breakdown table per category (Methods, Events, Enums, Properties).
+- **Debug console module** — optional `console.py` with `DebugConsole` widget and `setup_logging()` for development.
+- **AI refinement** (optional, `flet-pkg[ai]`) — post-generation LLM-powered code improvement using the Architect/Editor pattern:
+  - Deterministic gap analysis comparing Dart API vs generated Python code.
+  - Architect agent reasons about how to fix each gap.
+  - Editor agent produces precise search/replace code edits.
+  - Validator checks Python syntax with retry loop.
+  - Supports Ollama (free, local), Anthropic, OpenAI, and Google providers.
+  - Diff review, spinners, and coverage comparison output.
+- **MCP Server** (optional, `flet-pkg[mcp]`) — Model Context Protocol server exposing scaffolding and code generation tools to AI agents (Claude Desktop, Cursor, VS Code Copilot).
+- **Documentation** — MkDocs Material site with API Reference (mkdocstrings), architecture guide, CLI reference, and MCP server docs.
+- **Generated project structure** includes `pyproject.toml`, `README.md`, `mkdocs.yml`, tests, examples, and docs scaffolding.
+- **Template engine** — Jinja2 templates for both `service` and `ui_control` types with `include_console` conditionals.
+- **Python reserved word sanitization** — module names and method names that collide with Python keywords (e.g. `async`, `await`) are automatically renamed.
+- **Dart control-flow filtering** — false method matches from `catch`/`finally`/`then` patterns are excluded from generation.
+- **Test suite** — 383 tests covering models, type map, downloader, analyzer, generators, pipeline, scaffolder, CLI, validators, and coverage.
+- **CI/CD** — GitHub Actions workflows for `dev` and `main` branches with ruff, ty, pytest, and mkdocs build.
+
+[0.1.0]: https://github.com/brunobrown/flet-pkg/releases/tag/v0.1.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bruno Brown
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.