{"id":51529075,"url":"https://github.com/brunobrown/flet-pkg","last_synced_at":"2026-07-27T23:00:34.323Z","repository":{"id":342450989,"uuid":"978323425","full_name":"brunobrown/flet-pkg","owner":"brunobrown","description":"CLI tool that scaffolds Flet extension packages from Flutter packages, with auto-generated Python controls, Dart bridge code, type mappings, and event handlers.","archived":false,"fork":false,"pushed_at":"2026-05-27T04:23:25.000Z","size":1300,"stargazers_count":12,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T06:03:39.827Z","etag":null,"topics":["cli","cli-tool","flet","flet-dev","package","python"],"latest_commit_sha":null,"homepage":"https://brunobrown.github.io/flet-pkg/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brunobrown.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-05T20:07:18.000Z","updated_at":"2026-05-27T04:05:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brunobrown/flet-pkg","commit_stats":null,"previous_names":["brunobrown/flet-pkg"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/brunobrown/flet-pkg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobrown%2Fflet-pkg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobrown%2Fflet-pkg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobrown%2Fflet-pkg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobrown%2Fflet-pkg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brunobrown","download_url":"https://codeload.github.com/brunobrown/flet-pkg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brunobrown%2Fflet-pkg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35968098,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-27T02:00:06.776Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-tool","flet","flet-dev","package","python"],"created_at":"2026-07-09T01:00:30.567Z","updated_at":"2026-07-27T23:00:34.241Z","avatar_url":"https://github.com/brunobrown.png","language":"Python","funding_links":["https://www.buymeacoffee.com/brunobrown"],"categories":["Tools"],"sub_categories":["Community Extensions"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/06ef3010-78b7-4007-b5f7-40cf0201cf3a\" width=\"50%\" height=\"50%\" alt=\"Flet PKG\"\u003e\u003c/p\u003e\n\n**CLI tool that scaffolds Flet extension packages from Flutter packages, with auto-generated Python controls, Dart bridge code, type mappings, and event handlers.**\n\n![Python](https://img.shields.io/badge/python-3.10+-3776AB?logo=python\u0026logoColor=white)\n![Flet](https://img.shields.io/badge/flet-0.85.0+-00B4D8?logo=flet)\n[![Main](https://github.com/brunobrown/flet-pkg/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/brunobrown/flet-pkg/actions/workflows/main.yml)\n[![Dev](https://github.com/brunobrown/flet-pkg/actions/workflows/dev.yml/badge.svg?branch=dev)](https://github.com/brunobrown/flet-pkg/actions/workflows/dev.yml)\n[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://brunobrown.github.io/flet-pkg)\n[![Coverage](https://codecov.io/gh/brunobrown/flet-pkg/graph/badge.svg)](https://codecov.io/gh/brunobrown/flet-pkg)\n![License](https://img.shields.io/badge/license-MIT-yellow)\n\n---\n\n\u003e **Important: this tool does not perform miracles.** 🙏😂\n\u003e\n\u003e Every Flutter package on [pub.dev](https://pub.dev) has its own API surface, configuration requirements, and platform-specific behaviors. Some packages expose simple method calls; others require complex initialization flows, native platform setup (Android manifests, iOS plists, Gradle/CocoaPods configuration), or callback-based architectures that don't map cleanly to Python.\n\u003e\n\u003e It would be unrealistic to write a code generation algorithm that generalizes perfectly for every possible Flutter package. **flet-pkg** aims to accelerate the process by delivering significantly more than a blank skeleton — it downloads the real Dart source, parses the public API, and auto-generates Python controls, type mappings, enum definitions, event handlers, and Dart bridge code. For service packages, this typically covers ~95% of the API surface.\n\u003e\n\u003e However, **the developer is still responsible for**:\n\u003e - Understanding how the original Flutter/Dart package works\n\u003e - Reviewing the generated code for correctness\n\u003e - Handling package-specific configurations (native platform setup, initialization flows, etc.)\n\u003e - Adjusting or complementing the generated code for edge cases the pipeline could not cover\n\u003e\n\u003e Think of flet-pkg as a smart starting point, not a finished product.\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Usage](#usage)\n  - [Interactive Mode](#interactive-mode)\n  - [Non-Interactive Mode (CI/Scripting)](#non-interactive-mode-ciscripting)\n  - [Using a Local Flutter Package](#using-a-local-flutter-package)\n- [Extension Types](#extension-types)\n- [CLI Reference](#cli-reference)\n  - [flet-pkg --help](#flet-pkg---help)\n  - [flet-pkg create](#flet-pkg-create)\n    - [Package Options](#package-options)\n    - [Code Generation Options](#code-generation-options)\n    - [AI Refinement Options](#ai-refinement-options)\n    - [Output Options](#output-options)\n- [Verbose Mode \u0026 Coverage Score](#verbose-mode--coverage-score)\n- [AI Refinement](#ai-refinement)\n  - [Free (Ollama - Local)](#free-ollama---local)\n    - [Ollama Model Requirements](#ollama-model-requirements)\n  - [Cloud Providers](#cloud-providers)\n  - [How AI Refinement Works](#how-ai-refinement-works)\n- [MCP Server](#mcp-server)\n  - [Installation](#mcp-installation)\n  - [Claude Desktop Configuration](#claude-desktop-configuration)\n  - [Available Tools](#available-tools)\n  - [Resources \u0026 Prompts](#resources--prompts)\n- [Generated Project Structure](#generated-project-structure)\n- [Name Conflict Detection](#name-conflict-detection)\n- [Generation Pipeline](#generation-pipeline)\n- [Coverage](#coverage)\n- [Examples](#examples)\n- [Development](#development)\n- [Learn more](#learn-more)\n- [Flet Community](#flet-community)\n- [Support](#support)\n- [Contributing](#contributing)\n\n---\n\n## Buy Me a Coffee\n\nIf you find this project useful, please consider supporting its development:\n\n\u003ca href=\"https://www.buymeacoffee.com/brunobrown\"\u003e\n\u003cimg src=\"https://www.buymeacoffee.com/assets/img/guidelines/download-assets-sm-1.svg\" width=\"200\" alt=\"Buy Me a Coffee\"\u003e\n\u003c/a\u003e\n\n---\n\n## Installation\n\n```bash\n# Using UV (recommended)\nuv add flet-pkg\n\n# Using pip\npip install flet-pkg\n```\n\nTo enable **AI refinement** (optional):\n\n```bash\n# Using UV\nuv add flet-pkg[ai]\n\n# Using pip\npip install flet-pkg[ai]\n```\n\nTo enable the **MCP server** (optional — for AI agent integrations):\n\n```bash\n# Using UV\nuv add flet-pkg[mcp]\n\n# Using pip\npip install flet-pkg[mcp]\n```\n\n**Requirements:** Python 3.10+\n\n---\n\n## Quick Start\n\n```bash\n# Interactive mode — prompts guide you through every step\nflet-pkg create\n\n# One-liner for a service extension\nflet-pkg create -t service -f shared_preferences\n\n# One-liner for a UI control extension\nflet-pkg create -t ui_control -f shimmer\n\n# Auto-detect type + AI refinement (free, uses Ollama locally)\nflet-pkg create -f onesignal_flutter --ai-refine\n\n# Verbose mode — detailed output + coverage breakdown table\nflet-pkg create -t service -f shared_preferences -v\n```\n\n---\n\n## How It Works\n\nflet-pkg automates the tedious parts of creating a Flet extension:\n\n1. **Downloads** the Flutter package source from [pub.dev](https://pub.dev) (or uses a local path)\n2. **Parses** the Dart source files to extract the public API (classes, methods, constructors, enums, streams)\n3. **Analyzes** the API to produce a generation plan (type mappings, event detection, sub-module grouping)\n4. **Generates** Python controls (`ft.Service` / `ft.LayoutControl`), Dart bridge code, type definitions, and `__init__.py` exports\n5. **Writes** everything into a ready-to-develop project with `pyproject.toml`, tests, examples, and docs scaffolding\n\nOptionally, an **AI refinement** step can analyze coverage gaps and auto-improve the generated code using LLM-powered edits.\n\n---\n\n## Usage\n\n### Interactive Mode\n\n```bash\nflet-pkg create\n```\n\n![flet_pkg](https://github.com/user-attachments/assets/dea17fa6-496e-4666-9127-c159e2954797)\n\nThe CLI walks you through each step with prompts:\n\n1. **Extension type** — Auto-detect (recommended), Service, or UI Control\n2. **Flutter package name** — The package name from pub.dev (e.g. `onesignal_flutter`)\n3. **Extension name** — Your Flet extension project name (e.g. `flet-onesignal`)\n4. **Python package name** — The importable package name (e.g. `flet_onesignal`)\n5. **Control class name** — The Python class name (e.g. `OneSignal`)\n6. **Description** — A short description for `pyproject.toml`\n7. **Author** — Your name\n8. **Debug console** — Whether to include a debug console module\n9. **AI refinement** — Whether to run AI-powered code improvement (only shown if `pydantic-ai` is installed)\n\n### Non-Interactive Mode (CI/Scripting)\n\nPass all options as flags to skip prompts entirely:\n\n```bash\nflet-pkg create \\\n  --type service \\\n  --flutter-package shared_preferences \\\n  --output ./my-extensions\n```\n\nFor a UI control with AI refinement:\n\n```bash\nflet-pkg create \\\n  --type ui_control \\\n  --flutter-package shimmer \\\n  --ai-refine \\\n  --ai-provider ollama \\\n  --no-console\n```\n\n### Using a Local Flutter Package\n\nIf you have the Flutter package source locally (useful for private packages or development):\n\n```bash\nflet-pkg create \\\n  --type service \\\n  --flutter-package my_package \\\n  --local-package ./path/to/my_package\n```\n\nThis skips the pub.dev download and uses your local files directly.\n\n---\n\n## Extension Types\n\n| Type | Base Class | Description | Example Packages |\n|------|-----------|-------------|------------------|\n| **Auto-detect** | _(detected)_ | Downloads the package and inspects the Dart source to determine the type automatically. Falls back to a manual prompt if detection fails. | Any package |\n| **Service** | `ft.Service` | Non-visual extensions that provide platform services — push notifications, storage, sensors, authentication. Methods are exposed as async Python calls via `invoke_method`. | `shared_preferences`, `onesignal_flutter`, `geolocator`, `local_auth`, `battery_plus` |\n| **UI Control** | `ft.LayoutControl` | Visual widget extensions that render Flutter widgets on screen. Constructor parameters become Python properties mapped via `_get_control_name` and `_before_build_command`. | `shimmer`, `flutter_rating_bar`, `rive`, `video_player` |\n\n---\n\n## CLI Reference\n\n### `flet-pkg --help` or `flet-pkg create --help`\n\n```\nUsage: flet-pkg [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --version    Show version and exit.\n  --help       Show this message and exit.\n\nCommands:\n  create    Create a new Flet extension package.\n```\n\n### flet-pkg create\n\n```\nUsage: flet-pkg create [OPTIONS]\n```\n\n#### Package Options\n\n| Option | Short | Type | Description |\n|--------|-------|------|-------------|\n| `--type` | `-t` | TEXT | Extension type: `auto` (default), `service`, or `ui_control`. |\n| `--flutter-package` | `-f` | TEXT | Flutter package name from [pub.dev](https://pub.dev). |\n| `--output` | `-o` | PATH | Output directory for the generated project. Defaults to current directory. |\n| `--local-package` | `-l` | PATH | Path to a local Flutter package source. Skips the pub.dev download. |\n\n#### Code Generation Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--analyze / --no-analyze` | BOOL | `analyze` | Analyze the Flutter package and auto-generate Python controls, type mappings, and Dart bridge code. Use `--no-analyze` to generate only the skeleton structure without code analysis. |\n| `--console / --no-console` | BOOL | _(prompted)_ | Include a debug console module (`console.py`) for development logging. |\n\n#### AI Refinement Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `--ai-refine / --no-ai-refine` | BOOL | _(prompted)_ | Run AI-powered refinement on generated code. Requires `uv add flet-pkg[ai]` or `pip install flet-pkg[ai]`. |\n| `--ai-provider` | TEXT | `ollama` | AI provider: `ollama` (local, free), `anthropic` (Claude), `openai` (GPT), or `google` (Gemini). |\n| `--ai-model` | TEXT | _(per provider)_ | Override the default model. Defaults: `ollama`=`qwen2.5-coder:14b`, `anthropic`=`claude-sonnet-4-6`, `openai`=`gpt-4.1-mini`, `google`=`gemini-2.5-flash`. See [Ollama Model Requirements](#ollama-model-requirements) for RAM sizing. |\n\n#### Output Options\n\n| Option | Short | Type | Default | Description |\n|--------|-------|------|---------|-------------|\n| `--verbose` | `-v` | BOOL | `False` | Show detailed analysis output and coverage breakdown table. Without this flag, only a one-line coverage score is shown. |\n\n---\n\n## Verbose Mode \u0026 Coverage Score\n\nAfter code generation, flet-pkg runs a **deterministic gap analysis** that compares the Dart API against the generated Python code. A **coverage score** is always displayed:\n\n```\n  Coverage: 95.4% (41/43 features mapped)\n```\n\n### Verbose Mode (`-v`)\n\nPass `--verbose` or `-v` to see detailed output at every pipeline step:\n\n```bash\n# Score only (default)\nflet-pkg create -t service -f shared_preferences --no-ai-refine\n\n# Full verbose output with breakdown table\nflet-pkg create -t service -f shared_preferences --no-ai-refine -v\n\n# Verbose + AI refinement details\nflet-pkg create -t service -f shared_preferences --ai-refine -v\n```\n\nIn verbose mode you'll see:\n\n- **Parse details** — every class and enum discovered in the Dart source\n- **Analyze details** — each method, sub-module, event, and property mapped\n- **Generate details** — file breakdown (Python vs Dart) with filenames\n- **AI details** _(when `--ai-refine`)_ — gap report, architect suggestions, editor edits, validation results\n- **Coverage breakdown table** — per-category Rich table:\n\n```\n            Coverage Breakdown\n┌────────────────┬──────────┬─────────┬─────────────────┐\n│ Category       │ Dart API │  Mapped │ Coverage        │\n├────────────────┼──────────┼─────────┼─────────────────┤\n│ Methods        │       25 │      24 │ ████████░░ 96%  │\n│ Events         │        5 │       5 │ ██████████ 100% │\n│ Enums          │        8 │       7 │ ███████░░░ 88%  │\n├────────────────┼──────────┼─────────┼─────────────────┤\n│ Total          │       38 │      36 │ █████████░ 95%  │\n└────────────────┴──────────┴─────────┴─────────────────┘\n```\n\n---\n\n## AI Refinement\n\nThe AI refinement is an **optional** post-generation step that uses an LLM to detect coverage gaps and auto-improve the generated code. It uses the **Architect/Editor pattern** (inspired by [Aider's research](https://aider.chat/2024/09/26/architect.html)) which separates reasoning from editing for better results.\n\n### Free (Ollama - Local)\n\nNo API key needed. Runs entirely on your machine:\n\n```bash\n# 1. Install Ollama (https://ollama.com)\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# 2. Pull the default coding model (see RAM requirements below)\nollama pull qwen2.5-coder:14b\n\n# 3. Install the AI dependency\nuv add flet-pkg[ai]    # or: pip install flet-pkg[ai]\n\n# 4. Create with AI refinement (Ollama is the default provider)\nflet-pkg create -f shimmer --ai-refine\n```\n\n#### Ollama Model Requirements\n\nChoose the model size based on your available RAM. Larger models produce better results but require more memory:\n\n| Model | Size | Min RAM | GPU | Notes |\n|-------|------|---------|-----|-------|\n| `qwen2.5-coder:7b` | ~4.5 GB | 8 GB | Optional | Fast, but may fail on complex structured output |\n| `qwen2.5-coder:14b` | ~9 GB | 16 GB | Optional | **Default — best balance of quality and speed** |\n| `qwen2.5-coder:32b` | ~19 GB | 32 GB | Recommended | Best quality, but slow without dedicated GPU |\n\n\u003e **Warning:** Running a model that exceeds your available RAM will cause severe system slowdown or freeze. If you have **no dedicated GPU** (NVIDIA/AMD), the model runs entirely on CPU+RAM. For machines with 24 GB RAM or less, use the **14b** model (default).\n\u003e\n\u003e To override the model: `flet-pkg create --ai-refine --ai-model qwen2.5-coder:7b`\n\n### Cloud Providers\n\nIf you prefer a cloud-hosted LLM, set the appropriate API key:\n\n```bash\n# Anthropic (Claude)\nexport ANTHROPIC_API_KEY=sk-ant-...\nflet-pkg create -f shimmer --ai-refine --ai-provider anthropic\n\n# OpenAI (GPT)\nexport OPENAI_API_KEY=sk-...\nflet-pkg create -f shimmer --ai-refine --ai-provider openai\n\n# Google (Gemini)\nexport GOOGLE_API_KEY=...\nflet-pkg create -f shimmer --ai-refine --ai-provider google\n```\n\n### How AI Refinement Works\n\nThe pipeline runs in 4 steps:\n\n```\nStep 1: Gap Report (deterministic, no LLM)\n├── Compares the Dart API against the generated code\n├── Identifies: missing methods, properties, enums, events, type mismatches\n└── Produces a structured GapReport\n\nStep 2: Architect (LLM)\n├── Receives the GapReport + Dart source snippets + generated file summaries\n├── Reasons about HOW to fix each feasible gap\n└── Produces an ArchitectPlan (text descriptions of improvements)\n\nStep 3: Editor (LLM)\n├── Receives the ArchitectPlan + actual file contents\n├── Produces precise search/replace code edits\n└── Returns structured FileEdit objects\n\nStep 4: Validator (deterministic, no LLM)\n├── Applies the edits to the generated files\n├── Validates Python syntax\n├── If errors: feeds back to Editor (max 2 retries)\n└── Writes the refined files\n```\n\n---\n\n## MCP Server\n\nflet-pkg includes an **MCP (Model Context Protocol) server** that exposes its scaffolding and code generation capabilities to AI agents like Claude Desktop, Cursor, and VS Code Copilot. This complements the CLI by allowing AI assistants to create Flet extensions programmatically.\n\n### MCP Installation\n\n```bash\n# Install with MCP support\nuv add flet-pkg[mcp]    # or: pip install flet-pkg[mcp]\n\n# Verify it works\nflet-pkg-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"flet-pkg\": {\n      \"command\": \"flet-pkg-mcp\"\n    }\n  }\n}\n```\n\nOr use `uvx` (no install needed):\n\n```json\n{\n  \"mcpServers\": {\n    \"flet-pkg\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"flet-pkg[mcp]\", \"flet-pkg-mcp\"]\n    }\n  }\n}\n```\n\n### Available Tools\n\n| Tool | Description | Network |\n|------|-------------|---------|\n| `tool_derive_names` | Derive project/package/control names from a Flutter package name | No |\n| `tool_map_dart_type` | Convert a Dart type to its Python/Flet equivalent | No |\n| `tool_fetch_metadata` | Get pub.dev package metadata (version, description, homepage) | Yes (cached) |\n| `tool_detect_extension_type` | Auto-detect whether a package is a service or ui_control | Yes (cached) |\n| `tool_scaffold` | Create a project skeleton from a template | No |\n| `tool_run_pipeline` | Full pipeline: download, parse, analyze, generate, write | Yes (cached) |\n| `tool_analyze_gaps` | Deterministic coverage gap analysis (no LLM) | Yes (cached) |\n\n### Resources \u0026 Prompts\n\n**Resources:**\n\n| URI | Description |\n|-----|-------------|\n| `flet-pkg://type-map` | Full Dart-to-Python type mapping table |\n| `flet-pkg://templates` | Available template names (service, ui_control) |\n\n**Prompts:**\n\n| Prompt | Description |\n|--------|-------------|\n| `scaffold_service` | Step-by-step guide to scaffold a service extension |\n| `scaffold_ui_control` | Step-by-step guide to scaffold a UI control extension |\n| `analyze_package` | Guide to analyze coverage without scaffolding |\n\n### Example Prompts\n\nWith the MCP server configured, use natural language in Claude Code or Claude Desktop:\n\n```\n\u003e Use the flet-pkg tool to analyze the Flutter package \"onesignal_flutter\" and tell me\n  the extension type and coverage.\n```\n\n```\n\u003e Use the flet-pkg tool to analyze the Flutter package \"rive\" and tell me the extension\n  type and coverage.\n```\n\n---\n\n## Generated Project Structure\n\nAfter running `flet-pkg create`, you get a complete, ready-to-develop project:\n\n```\nflet-onesignal/                     # Project root\n├── pyproject.toml                  # Hatchling build + Flet metadata\n├── README.md                       # Extension documentation\n├── CHANGELOG.md\n├── LICENSE\n├── mkdocs.yml                      # MkDocs Material config\n├── docs/                           # Documentation source\n│   ├── index.md\n│   ├── getting-started.md\n│   ├── api-reference.md\n│   └── examples.md\n├── tests/\n│   └── test_flet_onesignal.py      # Pytest test file\n├── examples/\n│   └── flet_onesignal_example/     # Working example app\n│       ├── pyproject.toml\n│       └── src/\n│           └── main.py             # ft.run(main) example\n└── src/\n    ├── flet_onesignal/             # Python package\n    │   ├── __init__.py             # Public exports\n    │   ├── onesignal.py            # Main control (@ft.control + ft.Service)\n    │   ├── user.py                 # Sub-module (auto-detected from Dart API)\n    │   ├── types.py                # Enums, dataclasses, type definitions\n    │   └── console.py              # Debug console (optional)\n    └── flutter/\n        └── flet_onesignal/         # Flutter package\n            ├── pubspec.yaml        # Flutter dependencies\n            ├── analysis_options.yaml\n            └── lib/\n                ├── flet_onesignal.dart\n                └── src/\n                    ├── extension.dart           # Flet extension entry point\n                    └── onesignal_service.dart    # Dart bridge code\n```\n\nThe files under `src/flet_onesignal/` and `src/flutter/.../lib/src/` are **auto-generated** from the Flutter package analysis. They contain real method mappings, type conversions, and event handlers — not just stubs.\n\n---\n\n## Name Conflict Detection\n\nWhen you choose an extension name, flet-pkg automatically checks for existing packages across:\n\n- **PyPI** — Python Package Index\n- **GitHub** — Public repositories\n- **Flet SDK** — Official Flet monorepo packages\n\nIf matches are found, you'll see a warning with links and a confirmation prompt before continuing. This helps avoid naming conflicts with existing packages.\n\n---\n\n## Generation Pipeline\n\nThe deterministic pipeline (no AI needed) follows these steps:\n\n```\ndownload → parse → analyze → generate → [AI refine] → write\n```\n\n| Step | Module | Description |\n|------|--------|-------------|\n| **Download** | `core/downloader.py` | Fetches the Flutter package from pub.dev. Caches locally at `~/.cache/flet-pkg/`. |\n| **Parse** | `core/parser.py` | Parses Dart source files into a structured `DartPackageAPI` (classes, methods, constructors, enums, streams, getters). |\n| **Analyze** | `core/analyzer.py` | Produces a `GenerationPlan` with method mappings, type conversions, event detection, sub-module grouping, compound widget detection, and sibling widget detection. |\n| **Generate** | `core/generators/` | Five generators produce Python and Dart code: control, sub-modules, types, `__init__.py`, and Dart service/control. |\n| **AI Refine** | `core/ai/` | _(Optional)_ Gap analysis + LLM-powered code improvement. |\n| **Write** | `core/pipeline.py` | Writes files into the project directory, cleans up template stubs that were replaced by generated files. |\n\nKey analysis features:\n\n- **Stream event detection** — `Stream\u003cT\u003e get onXxx` patterns become Python event handlers\n- **Sub-module grouping** — Related methods are grouped into separate Python files (e.g. `user.py`, `notifications.py`)\n- **Compound widget detection** — Typed sub-widget constructor params become `ft.Control` sub-classes\n- **Platform interface resolution** — Downloads `*_platform_interface` packages to fill stub enum values\n- **Type mapping** — Dart types are mapped to Python/Flet equivalents via `core/type_map.py`\n- **Internal method filtering** — `toString`, `hashCode`, `setMock*` and other framework methods are excluded\n\n---\n\n## Coverage\n\nThe deterministic pipeline (without AI) achieves the following coverage on tested packages:\n\n| Package | Type | Coverage |\n|---------|------|----------|\n| `shared_preferences` | Service | 100.0% |\n| `url_launcher` | UI Control | 100.0% |\n| `local_auth` | Service | 100.0% |\n| `geolocator` | Service | 100.0% |\n| `share_plus` | Service | 100.0% |\n| `image_picker` | Service | 100.0% |\n| `onesignal_flutter` | Service | 97.6% |\n\nCoverage is measured as the percentage of public Dart API surface (methods, properties, enums, events) that is correctly mapped to Python code.\n\n---\n\n## Examples\n\n### Create a service extension for shared_preferences\n\n```bash\nflet-pkg create -t service -f shared_preferences\ncd flet-shared-preferences\nuv sync\n```\n\n### Create a UI control for shimmer with AI refinement\n\n```bash\nuv add flet-pkg[ai]    # or: pip install flet-pkg[ai]\nollama pull qwen2.5-coder\nflet-pkg create -t ui_control -f shimmer --ai-refine\n```\n\n### Create from a local Flutter package\n\n```bash\nflet-pkg create -t service -f my_package -l ./my_flutter_package\n```\n\n### Verbose output with coverage breakdown\n\n```bash\nflet-pkg create -t service -f battery_plus -v\n```\n\n### Non-interactive mode for CI\n\n```bash\nflet-pkg create \\\n  -t auto \\\n  -f onesignal_flutter \\\n  -o ./output \\\n  --no-console \\\n  --no-ai-refine\n```\n\n---\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/brunobrown/flet-pkg.git\ncd flet-pkg\nuv sync\n\n# Run tests\nuv run pytest tests/ -v\n\n# Lint and format\nuv tool run ruff format\nuv tool run ruff check\nuv tool run ty check\n\n# Run the CLI locally\nuv run flet-pkg create\n```\n\n---\n\n## Learn more\n* [Documentation](https://brunobrown.github.io/flet-pkg)\n\n## Flet Community\n\nJoin the community to contribute or get help:\n\n* [Discussions](https://github.com/flet-dev/flet/discussions)\n* [Discord](https://discord.gg/dzWXP8SHG8)\n* [X (Twitter)](https://twitter.com/fletdev)\n* [Bluesky](https://bsky.app/profile/fletdev.bsky.social)\n* [Email us](mailto:hello@flet.dev)\n\n## Support\n\nIf you like this project, please give it a [GitHub star](https://github.com/brunobrown/flet-pkg) ⭐\n\n---\n\n## Contributing\n\nContributions and feedback are welcome!\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a pull request with detailed explanation\n\nFor feedback, [open an issue](https://github.com/brunobrown/flet-pkg/issues) with your suggestions.\n\n---\n## Try flet-pkg today and turn any Flutter package into a Flet extension in seconds!\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/431aa05f-5fbc-4daa-9689-b9723583e25a\" width=\"50%\"\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://www.bible.com/bible/116/PRO.16.NLT\"\u003e Commit your work to the LORD, and your plans will succeed. Proverbs 16:3\u003c/a\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunobrown%2Fflet-pkg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrunobrown%2Fflet-pkg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrunobrown%2Fflet-pkg/lists"}