flint-kit 0.14.0__tar.gz

flint_kit-0.14.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: flint-kit
+Version: 0.14.0
+Summary: Interactive project scaffolding for Python frameworks — create-next-app, for FastAPI, Flask, and friends.
+Keywords: scaffolding,fastapi,cli,project-generator,create-next-app
+Author: abdulazeezoj
+License-Expression: MIT
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Dist: typer>=0.15.1
+Requires-Dist: questionary>=2.1.0
+Requires-Dist: rich>=13.9.4
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: pydantic>=2.10.3
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/abdulazeezoj/flint
+Description-Content-Type: text/markdown
+
+# flint
+
+[![CI](https://github.com/abdulazeezoj/flint/actions/workflows/ci.yml/badge.svg)](https://github.com/abdulazeezoj/flint/actions/workflows/ci.yml)
+[![Docs](https://github.com/abdulazeezoj/flint/actions/workflows/docs.yml/badge.svg)](https://abdulazeezoj.github.io/flint/)
+[![PyPI](https://img.shields.io/pypi/v/flint-kit)](https://pypi.org/project/flint-kit/)
+
+`create-next-app`, for Python. One command, a short interactive wizard,
+and you have a running project — no hand-written boilerplate. Pick a
+richer template and the same wizard wires up a real database,
+migrations, and a background worker too.
+
+```
+uvx --from flint-kit flint
+```
+
+```
+? What is your project named? my-api
+? Which framework? FastAPI
+? Which template? REST API
+? Database? PostgreSQL
+? ORM? SQLModel
+? Add Alembic migrations? Yes
+? Background worker? Taskiq
+Using uv to manage dependencies.
+? Add a Dockerfile? No
+? Initialize a git repository? Yes
+? Install dependencies with uv now? Yes
+
+Options: database=postgres, orm=sqlmodel, migrations=True, worker=taskiq, broker=redis, redis=True
+Creating my-api/ from fastapi/rest-api...
+  ✔ ...
+✔ Initialized git repository
+✔ Installed dependencies (uv sync)
+
+Success! Created my-api at ./my-api
+
+Next steps:
+  cd my-api
+  uv run alembic upgrade head
+  uv run fastapi dev src/my_api/main.py
+  uv run taskiq worker my_api.worker:broker --app-dir src   # separate process
+```
+
+**📖 Full documentation: [abdulazeezoj.github.io/flint](https://abdulazeezoj.github.io/flint/)**
+— getting started, a full CLI reference, one page per template
+(options, generated layout, gotchas), the `.agents/skills/` catalog,
+remembered preferences, and how to contribute.
+
+## Install
+
+```
+uv tool install flint-kit   # persistent `flint` on PATH
+# or run it ephemerally, no install:
+uvx --from flint-kit flint
+```
+
+## Usage
+
+```
+flint                                     # interactive wizard
+flint new my-api                           # interactive, name pre-filled
+flint new my-api \
+  --framework fastapi --template rest-api \
+  -o database=sqlite -o orm=sqlmodel \
+  --docker --git --install --yes            # fully non-interactive, for scripts/CI
+flint list-templates                       # what's available, without generating anything
+flint --version
+flint --help
+```
+
+Every prompt has a matching flag, and Flint remembers your last
+choices in `~/.flint/last.json` as the new default next time. See the
+[CLI Reference](https://abdulazeezoj.github.io/flint/cli-reference/)
+and [Remembered Preferences](https://abdulazeezoj.github.io/flint/preferences/)
+docs for the full details.
+
+## What flint ships
+
+A project is always generated from a `<framework>/<template>` pair —
+**FastAPI** and **Flask**, each with a **Hello World** and a fuller
+**REST API** template offering real head-start choices (database, ORM,
+migrations, a background worker, Redis). Every generated project also
+gets `.agents/skills/` — deeper, library-specific reference material
+for exactly the stack it uses. See the
+[Templates](https://abdulazeezoj.github.io/flint/project-templates/)
+and [Agent Skills](https://abdulazeezoj.github.io/flint/agent-skills/)
+docs for what each one actually generates.
+
+## Contributing
+
+```
+uv sync
+uv run pytest       # also runs coverage — the suite fails under 100%
+uv run flint --help
+```
+
+Adding a framework, template, or skill is a content-only change — no
+code edits needed. See the
+[Contributing](https://abdulazeezoj.github.io/flint/contributing/)
+docs for the full local-setup, template/skill-authoring, and release
+process, or [`CHANGELOG.md`](CHANGELOG.md) for release history.

flint_kit-0.14.0/README.md

@@ -0,0 +1,101 @@
+# flint
+
+[![CI](https://github.com/abdulazeezoj/flint/actions/workflows/ci.yml/badge.svg)](https://github.com/abdulazeezoj/flint/actions/workflows/ci.yml)
+[![Docs](https://github.com/abdulazeezoj/flint/actions/workflows/docs.yml/badge.svg)](https://abdulazeezoj.github.io/flint/)
+[![PyPI](https://img.shields.io/pypi/v/flint-kit)](https://pypi.org/project/flint-kit/)
+
+`create-next-app`, for Python. One command, a short interactive wizard,
+and you have a running project — no hand-written boilerplate. Pick a
+richer template and the same wizard wires up a real database,
+migrations, and a background worker too.
+
+```
+uvx --from flint-kit flint
+```
+
+```
+? What is your project named? my-api
+? Which framework? FastAPI
+? Which template? REST API
+? Database? PostgreSQL
+? ORM? SQLModel
+? Add Alembic migrations? Yes
+? Background worker? Taskiq
+Using uv to manage dependencies.
+? Add a Dockerfile? No
+? Initialize a git repository? Yes
+? Install dependencies with uv now? Yes
+
+Options: database=postgres, orm=sqlmodel, migrations=True, worker=taskiq, broker=redis, redis=True
+Creating my-api/ from fastapi/rest-api...
+  ✔ ...
+✔ Initialized git repository
+✔ Installed dependencies (uv sync)
+
+Success! Created my-api at ./my-api
+
+Next steps:
+  cd my-api
+  uv run alembic upgrade head
+  uv run fastapi dev src/my_api/main.py
+  uv run taskiq worker my_api.worker:broker --app-dir src   # separate process
+```
+
+**📖 Full documentation: [abdulazeezoj.github.io/flint](https://abdulazeezoj.github.io/flint/)**
+— getting started, a full CLI reference, one page per template
+(options, generated layout, gotchas), the `.agents/skills/` catalog,
+remembered preferences, and how to contribute.
+
+## Install
+
+```
+uv tool install flint-kit   # persistent `flint` on PATH
+# or run it ephemerally, no install:
+uvx --from flint-kit flint
+```
+
+## Usage
+
+```
+flint                                     # interactive wizard
+flint new my-api                           # interactive, name pre-filled
+flint new my-api \
+  --framework fastapi --template rest-api \
+  -o database=sqlite -o orm=sqlmodel \
+  --docker --git --install --yes            # fully non-interactive, for scripts/CI
+flint list-templates                       # what's available, without generating anything
+flint --version
+flint --help
+```
+
+Every prompt has a matching flag, and Flint remembers your last
+choices in `~/.flint/last.json` as the new default next time. See the
+[CLI Reference](https://abdulazeezoj.github.io/flint/cli-reference/)
+and [Remembered Preferences](https://abdulazeezoj.github.io/flint/preferences/)
+docs for the full details.
+
+## What flint ships
+
+A project is always generated from a `<framework>/<template>` pair —
+**FastAPI** and **Flask**, each with a **Hello World** and a fuller
+**REST API** template offering real head-start choices (database, ORM,
+migrations, a background worker, Redis). Every generated project also
+gets `.agents/skills/` — deeper, library-specific reference material
+for exactly the stack it uses. See the
+[Templates](https://abdulazeezoj.github.io/flint/project-templates/)
+and [Agent Skills](https://abdulazeezoj.github.io/flint/agent-skills/)
+docs for what each one actually generates.
+
+## Contributing
+
+```
+uv sync
+uv run pytest       # also runs coverage — the suite fails under 100%
+uv run flint --help
+```
+
+Adding a framework, template, or skill is a content-only change — no
+code edits needed. See the
+[Contributing](https://abdulazeezoj.github.io/flint/contributing/)
+docs for the full local-setup, template/skill-authoring, and release
+process, or [`CHANGELOG.md`](CHANGELOG.md) for release history.

flint_kit-0.14.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "flint-kit"
+version = "0.14.0"
+description = "Interactive project scaffolding for Python frameworks — create-next-app, for FastAPI, Flask, and friends."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "abdulazeezoj" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.15.1",
+    "questionary>=2.1.0",
+    "rich>=13.9.4",
+    "jinja2>=3.1.4",
+    "pydantic>=2.10.3",
+]
+keywords = ["scaffolding", "fastapi", "cli", "project-generator", "create-next-app"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Code Generators",
+]
+
+[project.urls]
+Repository = "https://github.com/abdulazeezoj/flint"
+
+[project.scripts]
+flint = "flint.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.8.17,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "flint"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-cov>=7.1.0",
+]
+docs = [
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.49",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov=flint --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+branch = true
+source = ["flint"]

flint_kit-0.14.0/src/flint/__init__.py

@@ -0,0 +1,3 @@
+"""Flint — interactive project scaffolding for Python frameworks."""
+
+__version__ = "0.14.0"

flint_kit-0.14.0/src/flint/__main__.py

@@ -0,0 +1,4 @@
+from flint.cli import main
+
+if __name__ == "__main__":
+    main()

flint_kit-0.14.0/src/flint/cli.py

@@ -0,0 +1,289 @@
+"""The `flint` command-line app.
+
+See PRODUCT_FLOW.md §1 for the entry-point table this implements: bare
+`flint` behaves like `flint new` (an interactive wizard), `flint new
+NAME --flags...` skips prompts for anything a flag already answers, and
+`--yes` / a non-TTY stdin skips prompting entirely.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from flint import __version__
+from flint import generator, postgen, prefs, prompts
+from flint.errors import FlintUserError
+
+app = typer.Typer(add_completion=False, no_args_is_help=False)
+console = Console()
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    version: Annotated[
+        bool, typer.Option("--version", help="Show the version and exit.")
+    ] = False,
+) -> None:
+    """Flint — interactive project scaffolding for Python frameworks."""
+    if version:
+        console.print(f"flint {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        _run_new(
+            name=None,
+            framework=None,
+            template=None,
+            option=[],
+            docker=None,
+            git=None,
+            install=None,
+            yes=False,
+            force=False,
+            remember=True,
+        )
+
+
+@app.command()
+def new(
+    name: Annotated[
+        Optional[str], typer.Argument(help="Project name, e.g. 'my-api'.")
+    ] = None,
+    framework: Annotated[
+        Optional[str], typer.Option(help="Framework to use, e.g. 'fastapi'.")
+    ] = None,
+    template: Annotated[
+        Optional[str],
+        typer.Option(help="Template variant within the framework, e.g. 'hello-world'."),
+    ] = None,
+    option: Annotated[
+        list[str],
+        typer.Option(
+            "--option",
+            "-o",
+            help=(
+                "Set a template-specific option as key=value (repeatable), "
+                "e.g. -o database=postgres -o orm=sqlmodel. See the wizard "
+                "or the template's README for available keys."
+            ),
+        ),
+    ] = [],  # noqa: B006 - Typer's documented pattern for repeatable options
+    docker: Annotated[
+        Optional[bool],
+        typer.Option("--docker/--no-docker", help="Add a Dockerfile."),
+    ] = None,
+    git: Annotated[
+        Optional[bool],
+        typer.Option("--git/--no-git", help="Initialize a git repository."),
+    ] = None,
+    install: Annotated[
+        Optional[bool],
+        typer.Option("--install/--no-install", help="Install dependencies with uv."),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes", "-y", help="Accept defaults for anything not given as a flag."
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force", help="Generate even if the target directory already exists."
+        ),
+    ] = False,
+    remember: Annotated[
+        bool,
+        typer.Option(
+            "--remember/--no-remember",
+            help=(
+                "Remember these choices in ~/.flint/last.json as the "
+                "default for next time (framework/template + per-template "
+                "options, docker, git, install). Explicit flags/--option "
+                "always win regardless."
+            ),
+        ),
+    ] = True,
+) -> None:
+    """Generate a new project."""
+    _run_new(
+        name=name,
+        framework=framework,
+        template=template,
+        option=option,
+        docker=docker,
+        git=git,
+        install=install,
+        yes=yes,
+        force=force,
+        remember=remember,
+    )
+
+
+@app.command("list-templates")
+def list_templates_cmd() -> None:
+    """List available framework/template combinations."""
+    table = Table()
+    table.add_column("Framework")
+    table.add_column("Template")
+    table.add_column("Description")
+    table.add_column("Docker", justify="center")
+
+    for framework in generator.list_frameworks():
+        framework_label = (
+            framework.label if framework.enabled else f"{framework.label} (coming soon)"
+        )
+        for template in generator.list_templates(framework.id):
+            template_label = (
+                template.label if template.enabled else f"{template.label} (coming soon)"
+            )
+            table.add_row(
+                framework_label,
+                template_label,
+                template.description,
+                "✓" if template.supports_docker else "—",
+            )
+
+    console.print(table)
+    console.print(
+        "\nPass a pair with e.g. [bold]flint new my-api --framework fastapi "
+        "--template rest-api[/bold]. Templates with their own choices "
+        "(database, ORM, ...) take -o key=value — see the wizard or each "
+        "template's README for available keys."
+    )
+
+
+def _run_new(
+    *,
+    name: Optional[str],
+    framework: Optional[str],
+    template: Optional[str],
+    option: list[str],
+    docker: Optional[bool],
+    git: Optional[bool],
+    install: Optional[bool],
+    yes: bool,
+    force: bool,
+    remember: bool,
+) -> None:
+    interactive = sys.stdin.isatty() and not yes
+    stored_prefs = prefs.load_prefs() if remember else {}
+
+    try:
+        project_name, slug, package_name = prompts.prompt_project_name(name, interactive)
+
+        target_dir = Path.cwd() / slug
+        if target_dir.exists() and any(target_dir.iterdir()):
+            force = prompts.prompt_force_overwrite(slug, force, interactive)
+            if not force:
+                raise FlintUserError(
+                    f"Directory '{slug}' already exists and is not empty. "
+                    "Use --force to generate into it anyway."
+                )
+
+        frameworks = generator.list_frameworks()
+        framework_id = prompts.prompt_framework(
+            framework,
+            frameworks,
+            interactive,
+            default_id=prefs.get_last_framework(stored_prefs),
+        )
+
+        chosen_framework = generator.get_framework(framework_id)
+
+        templates = generator.list_templates(framework_id)
+        template_id = prompts.prompt_template(
+            template,
+            templates,
+            interactive,
+            default_id=prefs.get_last_template(stored_prefs, framework_id),
+        )
+
+        chosen_template = generator.get_template(framework_id, template_id)
+        remembered = prefs.get_template_prefs(stored_prefs, chosen_template.full_id)
+
+        provided_options = prompts.parse_option_flags(option)
+        resolved_options = prompts.prompt_template_options(
+            chosen_template, provided_options, interactive, last=remembered["options"]
+        )
+
+        docker_requested = prompts.prompt_docker(
+            docker, interactive, remembered=remembered["docker"]
+        )
+        if docker_requested and not chosen_template.supports_docker:
+            console.print(
+                f"[yellow]![/yellow] {chosen_template.full_id} doesn't support "
+                "--docker yet — skipping the Dockerfile."
+            )
+            docker_requested = False
+
+        if interactive:
+            console.print("Using uv to manage dependencies.")
+
+        git_init = prompts.prompt_git_init(git, interactive, remembered=remembered["git_init"])
+        install_now = prompts.prompt_install(install, interactive, remembered=remembered["install"])
+
+        answers = generator.Answers(
+            project_name=project_name,
+            slug=slug,
+            package_name=package_name,
+            framework=framework_id,
+            template=template_id,
+            git_init=git_init,
+            install=install_now,
+            docker=docker_requested,
+            options=resolved_options,
+        )
+        created = generator.render(framework_id, template_id, target_dir, answers, force=force)
+
+        if remember:
+            prefs.save_prefs(
+                prefs.record_run(
+                    stored_prefs,
+                    framework_id=framework_id,
+                    template_id=template_id,
+                    full_id=chosen_template.full_id,
+                    options=resolved_options,
+                    docker=docker_requested,
+                    git_init=git_init,
+                    install=install_now,
+                )
+            )
+
+        git_ok = postgen.git_init(target_dir) if git_init else False
+        installed_ok = postgen.install_dependencies(target_dir) if install_now else False
+
+        postgen.print_summary(
+            project_name=project_name,
+            slug=slug,
+            template_full_id=chosen_template.full_id,
+            target_dir=target_dir,
+            created=created,
+            git_ok=git_ok,
+            installed_ok=installed_ok,
+            installed_requested=install_now,
+            run_command=chosen_framework.run_command.format(package_name=package_name),
+            options=resolved_options,
+        )
+    except FlintUserError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from None
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001 - top-level safety net, see errors.py
+        console.print(f"[red]Unexpected error:[/red] {exc}")
+        raise typer.Exit(2) from None
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

flint_kit-0.14.0/src/flint/errors.py

@@ -0,0 +1,17 @@
+"""Flint's error hierarchy.
+
+`FlintUserError` maps to exit code 1 (the user did something we can
+explain, e.g. an existing directory or an invalid name). Anything else
+bubbles up and is treated as exit code 2 (unexpected/internal error), per
+PRODUCT_FLOW.md §5.
+"""
+
+from __future__ import annotations
+
+
+class FlintError(Exception):
+    """Base class for all Flint-raised errors."""
+
+
+class FlintUserError(FlintError):
+    """An error caused by user input/environment, not a Flint bug."""