qtmp 0.2.0__py3-none-any.whl

qtmp/recipes/__init__.py

@@ -0,0 +1,51 @@
+"""
+qtmp.recipes
+--------------
+The registry every other module reads from. Adding a new recipe means:
+  1. Write a Recipe subclass in its own file (see any existing recipe).
+  2. Add one line here.
+Nothing in planner.py, executor.py, or cli.py needs to change.
+"""
+
+from qtmp.recipes.react import ReactRecipe
+from qtmp.recipes.tailwind import TailwindRecipe
+from qtmp.recipes.router_axios import RouterRecipe, AxiosRecipe, ShadcnRecipe
+from qtmp.recipes.fastapi import FastAPIRecipe
+from qtmp.recipes.database import PostgresRecipe, DbDriverPostgresRecipe, SQLAlchemyRecipe
+
+REGISTRY = {
+    r.provides: r
+    for r in [
+        ReactRecipe(),
+        TailwindRecipe(),
+        RouterRecipe(),
+        AxiosRecipe(),
+        ShadcnRecipe(),
+        FastAPIRecipe(),
+        PostgresRecipe(),
+        DbDriverPostgresRecipe(),
+        SQLAlchemyRecipe(),
+    ]
+}
+
+CREATABLE = {key: r for key, r in REGISTRY.items() if r.creatable}
+
+ALIASES = {
+    "reactjs": "react",
+    "react.js": "react",
+    "fast": "fastapi",
+    "postgresql": "postgres",
+    "psql": "postgres",
+    "pg": "postgres",
+    "router": "router",
+    "react-router": "router",
+    "react-router-dom": "router",
+    "sqlalchemy": "sqlalchemy",
+    "shadcn-ui": "shadcn",
+    "shadcn/ui": "shadcn",
+}
+
+
+def resolve_name(name: str) -> str:
+    key = name.strip().lower()
+    return ALIASES.get(key, key)

qtmp/recipes/base.py

@@ -0,0 +1,62 @@
+"""
+qtmp.recipes.base
+-------------------
+A Recipe is the only thing a developer needs to write to teach qtmp
+about a new piece of the stack. It answers three questions:
+
+  - requires(ctx)  -> what other capabilities must exist first?
+  - detect(ctx)    -> is this capability already satisfied? (idempotency)
+  - plan(ctx)      -> what Steps would satisfy it, if not?
+
+Nothing in qtmp/planner.py, qtmp/executor.py, or qtmp/cli.py needs to
+change when a new Recipe is added — only qtmp/recipes/__init__.py's
+registry needs one new line.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from qtmp.planner import Step
+
+
+class Recipe(ABC):
+    #: human-readable name, e.g. "Tailwind CSS"
+    name: str = ""
+    #: capability id this recipe satisfies, e.g. "tailwind" — this is
+    #: what `qtmp add <id>` and `requires()` refer to.
+    provides: str = ""
+    #: True if this recipe supports `qtmp create <provides>` (scaffolding
+    #: a brand-new project) in addition to `qtmp add`.
+    creatable: bool = False
+
+    def requires(self, ctx) -> List[str]:
+        """
+        Capability ids that must be satisfied before this one can run.
+        Can depend on `ctx` — e.g. SQLAlchemy's driver requirement
+        depends on which database is actually in play.
+        """
+        return []
+
+    @abstractmethod
+    def detect(self, ctx) -> bool:
+        """Is this capability already present in ctx.cwd?"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def plan(self, ctx) -> List[Step]:
+        """
+        Steps needed to satisfy this capability. Only ever called when
+        detect(ctx) is False — recipes don't need their own "already
+        installed" guard, the planner handles that centrally.
+        """
+        raise NotImplementedError
+
+    def create(self, ctx, **kwargs):
+        """
+        Only for creatable recipes: scaffold a brand-new project.
+        Returns the new project's directory. Not part of the
+        detect/plan/requires idempotency contract — creating "my-app"
+        twice is expected to be a user decision (a new folder), not
+        something the planner should intervene in.
+        """
+        raise NotImplementedError(f"{self.name} does not support 'create'")

qtmp/recipes/database.py

@@ -0,0 +1,112 @@
+"""
+qtmp.recipes.database
+-----------------------
+Three capabilities that show real dependency resolution instead of a
+single flat "postgres" module:
+
+  postgres            -> a local server + database/user exist
+  db-driver-postgres   -> psycopg2-binary is installed in the venv
+  sqlalchemy           -> SQLAlchemy is installed, *and* requires a
+                          driver for whatever database is in play
+
+Running `qtmp add sqlalchemy` on a fresh FastAPI project resolves to:
+  fastapi (already installed, skipped)
+    -> db-driver-postgres (installs psycopg2-binary)
+    -> sqlalchemy (installs SQLAlchemy)
+
+This is the "add SQLAlchemy -> driver required -> resolve -> install"
+flow, expressed as two lines of `requires()` rather than special-cased
+CLI logic.
+"""
+
+import os
+import subprocess
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+from qtmp.utils import prompt, which
+
+
+class PostgresRecipe(Recipe):
+    name = "PostgreSQL (local server)"
+    provides = "postgres"
+
+    def detect(self, ctx) -> bool:
+        return which("psql") is not None
+
+    def plan(self, ctx) -> List[Step]:
+        # We can't silently "apt install postgresql" for someone — this
+        # is a step deliberately left as guidance, not automation, since
+        # it usually needs sudo / a package manager choice we shouldn't
+        # make on the user's behalf.
+        return [
+            Step(
+                "PostgreSQL is not installed — install it yourself, then re-run:\n"
+                "      macOS:  brew install postgresql\n"
+                "      Ubuntu: sudo apt install postgresql",
+                apply_fn=lambda: None,
+            )
+        ]
+
+
+class DbDriverPostgresRecipe(Recipe):
+    name = "psycopg2 (PostgreSQL driver)"
+    provides = "db-driver-postgres"
+
+    def requires(self, ctx) -> List[str]:
+        # Always declare fastapi as a dependency — resolve_plan() checks
+        # FastAPIRecipe.detect(ctx) itself and marks it already_satisfied
+        # if true, so this never double-installs. (A venv existing is
+        # not the same thing as fastapi being installed in it — don't
+        # use has_venv as a shortcut here.)
+        return ["fastapi"]
+
+    def detect(self, ctx) -> bool:
+        python = ctx.venv_python()
+        if not os.path.isfile(python):
+            return False
+        result = subprocess.run(
+            [python, "-c", "import psycopg2"], capture_output=True
+        )
+        return result.returncode == 0
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step(
+                "Install psycopg2-binary",
+                command=[ctx.venv_pip(), "install", "psycopg2-binary"],
+            )
+        ]
+
+
+class SQLAlchemyRecipe(Recipe):
+    name = "SQLAlchemy"
+    provides = "sqlalchemy"
+
+    def requires(self, ctx) -> List[str]:
+        # This is the resolution step from your diagram: SQLAlchemy
+        # itself doesn't care which database, but *something* has to
+        # decide which driver to install. Default to Postgres — a
+        # future recipe (e.g. db-driver-sqlite) could be chosen instead
+        # based on a --db flag or a detected DATABASE_URL scheme.
+        # fastapi is always declared too (see DbDriverPostgresRecipe for
+        # why has_venv can't be used as a substitute check).
+        return ["fastapi", "db-driver-postgres"]
+
+    def detect(self, ctx) -> bool:
+        python = ctx.venv_python()
+        if not os.path.isfile(python):
+            return False
+        result = subprocess.run(
+            [python, "-c", "import sqlalchemy"], capture_output=True
+        )
+        return result.returncode == 0
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step(
+                "Install SQLAlchemy",
+                command=[ctx.venv_pip(), "install", "sqlalchemy"],
+            )
+        ]

qtmp/recipes/fastapi.py

@@ -0,0 +1,92 @@
+"""
+qtmp.recipes.fastapi
+----------------------
+Provides "fastapi". Creates a venv + installs fastapi/uvicorn + writes
+a working main.py. Also the anchor of the Python dependency chain that
+SQLAlchemy's driver resolution hangs off of.
+"""
+
+import os
+import sys
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+from qtmp.utils import prompt, which
+
+
+MAIN_PY_TEMPLATE = '''from fastapi import FastAPI
+
+app = FastAPI(title="{title}")
+
+
+@app.get("/")
+def read_root():
+    return {{"message": "{title} is running"}}
+
+
+@app.get("/health")
+def health():
+    return {{"status": "ok"}}
+'''
+
+
+def _write_main_py(cwd, title):
+    with open(os.path.join(cwd, "main.py"), "w") as f:
+        f.write(MAIN_PY_TEMPLATE.format(title=title))
+
+
+class FastAPIRecipe(Recipe):
+    name = "FastAPI"
+    provides = "fastapi"
+    creatable = True
+
+    def detect(self, ctx) -> bool:
+        main_py = os.path.join(ctx.cwd, "main.py")
+        if not os.path.isfile(main_py):
+            return False
+        with open(main_py) as f:
+            return "fastapi" in f.read().lower()
+
+    def plan(self, ctx) -> List[Step]:
+        title = os.path.basename(ctx.cwd.rstrip("/")) or "app"
+        return [
+            Step(
+                "Create virtual environment",
+                command=[sys.executable, "-m", "venv", "venv"],
+                cwd=ctx.cwd,
+            ),
+            Step(
+                "Install fastapi + uvicorn",
+                command=[ctx.venv_pip(), "install", "fastapi", "uvicorn[standard]"],
+            ),
+            Step(
+                "Write main.py",
+                apply_fn=lambda: _write_main_py(ctx.cwd, title),
+            ),
+        ]
+
+    def create(self, ctx, **kwargs):
+        if not which(sys.executable):
+            raise RuntimeError("Python interpreter not found.")
+
+        name = prompt("Project name", default="my-fastapi-app")
+        project_dir = os.path.join(ctx.cwd, name)
+        os.makedirs(project_dir, exist_ok=True)
+
+        from qtmp.utils import Spinner, run, ok
+        from qtmp.context import ProjectContext
+
+        venv_dir = os.path.join(project_dir, "venv")
+        with Spinner("Creating virtual environment"):
+            run([sys.executable, "-m", "venv", venv_dir])
+
+        sub_ctx = ProjectContext.detect(project_dir)
+        pip = sub_ctx.venv_pip()
+        with Spinner("Installing fastapi + uvicorn"):
+            run([pip, "install", "--upgrade", "pip"])
+            run([pip, "install", "fastapi", "uvicorn[standard]"])
+
+        _write_main_py(project_dir, name)
+        ok(f"FastAPI project ready at {project_dir}")
+        return project_dir, False

qtmp/recipes/react.py

@@ -0,0 +1,59 @@
+"""
+qtmp.recipes.react
+--------------------
+Provides "react". Creatable (scaffolds a brand-new Vite project) and
+also a dependency target — e.g. `qtmp add tailwind` in an empty folder
+will pull this in automatically via requires().
+"""
+
+import os
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+from qtmp.utils import prompt, confirm, which
+
+
+class ReactRecipe(Recipe):
+    name = "React"
+    provides = "react"
+    creatable = True
+
+    def detect(self, ctx) -> bool:
+        return "react" in ctx.node_deps
+
+    def plan(self, ctx) -> List[Step]:
+        # `plan()` for react-as-a-dependency assumes a name isn't being
+        # asked interactively (that only happens via `create`), so this
+        # covers the case "something requires react and it's missing" —
+        # it scaffolds a project named after the current folder, in place.
+        folder_name = os.path.basename(ctx.cwd.rstrip("/")) or "app"
+        return [
+            Step(
+                f"Scaffold React (Vite) into ./{folder_name}",
+                command=["npm", "create", "vite@latest", ".", "--", "--template", "react"],
+                cwd=ctx.cwd,
+            ),
+            Step("Install npm dependencies", command=["npm", "install"], cwd=ctx.cwd),
+        ]
+
+    def create(self, ctx, **kwargs):
+        if not which("npm"):
+            raise RuntimeError("npm not found on PATH. Install Node.js first: https://nodejs.org")
+
+        name = prompt("Project name", default="my-react-app")
+        level = prompt("Beginner or advanced setup? [b/a]", default="b").strip().lower()
+        advanced = level.startswith("a")
+        template = "react-ts" if advanced else "react"
+
+        from qtmp.utils import Spinner, run, ok
+
+        with Spinner(f"Scaffolding {name} with Vite"):
+            run(["npm", "create", "vite@latest", name, "--", "--template", template], cwd=ctx.cwd)
+
+        project_dir = os.path.join(ctx.cwd, name)
+        with Spinner("Installing dependencies"):
+            run(["npm", "install"], cwd=project_dir)
+
+        ok(f"React project ready at {project_dir}")
+        return project_dir, advanced

qtmp/recipes/router_axios.py

@@ -0,0 +1,69 @@
+"""
+qtmp.recipes.router_axios
+---------------------------
+Two small recipes, both requiring "react", showing what a minimal
+add-on recipe looks like once the base project is a dependency someone
+else already resolved.
+"""
+
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+
+
+class RouterRecipe(Recipe):
+    name = "React Router"
+    provides = "router"
+
+    def requires(self, ctx) -> List[str]:
+        return [] if ctx.is_node else ["react"]
+
+    def detect(self, ctx) -> bool:
+        return "react-router-dom" in ctx.node_deps
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step(
+                "Install react-router-dom",
+                command=["npm", "install", "react-router-dom"],
+                cwd=ctx.cwd,
+            )
+        ]
+
+
+class AxiosRecipe(Recipe):
+    name = "Axios"
+    provides = "axios"
+
+    def requires(self, ctx) -> List[str]:
+        return [] if ctx.is_node else ["react"]
+
+    def detect(self, ctx) -> bool:
+        return "axios" in ctx.node_deps
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step("Install axios", command=["npm", "install", "axios"], cwd=ctx.cwd)
+        ]
+
+
+class ShadcnRecipe(Recipe):
+    name = "shadcn/ui"
+    provides = "shadcn"
+
+    def requires(self, ctx) -> List[str]:
+        return ["tailwind"]  # shadcn/ui always needs Tailwind configured first
+
+    def detect(self, ctx) -> bool:
+        import os
+        return os.path.isfile(f"{ctx.cwd}/components.json")
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step(
+                "Initialize shadcn/ui",
+                command=["npx", "shadcn@latest", "init", "-d"],
+                cwd=ctx.cwd,
+            )
+        ]

qtmp/recipes/tailwind.py

@@ -0,0 +1,69 @@
+"""
+qtmp.recipes.tailwind
+-----------------------
+Provides "tailwind". Demonstrates the simplest form of dependency
+resolution: if you `qtmp add tailwind` in an empty folder, it pulls in
+"react" first, because Tailwind needs *some* JS project to attach to.
+If a node project already exists, it attaches directly.
+"""
+
+import os
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+
+
+TAILWIND_CONFIG = (
+    "/** @type {import('tailwindcss').Config} */\n"
+    "export default {\n"
+    '  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],\n'
+    "  theme: { extend: {} },\n"
+    "  plugins: [],\n"
+    "}\n"
+)
+
+
+def _write_config(cwd):
+    with open(os.path.join(cwd, "tailwind.config.js"), "w") as f:
+        f.write(TAILWIND_CONFIG)
+
+
+def _append_directives(cwd):
+    css_path = os.path.join(cwd, "src", "index.css")
+    if os.path.isdir(os.path.join(cwd, "src")):
+        with open(css_path, "a") as f:
+            f.write("\n@tailwind base;\n@tailwind components;\n@tailwind utilities;\n")
+
+
+class TailwindRecipe(Recipe):
+    name = "Tailwind CSS"
+    provides = "tailwind"
+
+    def requires(self, ctx) -> List[str]:
+        return [] if ctx.is_node else ["react"]
+
+    def detect(self, ctx) -> bool:
+        return ctx.has_tailwind_config
+
+    def plan(self, ctx) -> List[Step]:
+        return [
+            Step(
+                "Install tailwindcss, postcss, autoprefixer",
+                command=["npm", "install", "-D", "tailwindcss", "postcss", "autoprefixer"],
+                cwd=ctx.cwd,
+            ),
+            Step(
+                "Run tailwindcss init",
+                command=["npx", "tailwindcss", "init", "-p"],
+                cwd=ctx.cwd,
+            ),
+            Step(
+                "Write tailwind.config.js content globs",
+                apply_fn=lambda: _write_config(ctx.cwd),
+            ),
+            Step(
+                "Add @tailwind directives to src/index.css",
+                apply_fn=lambda: _append_directives(ctx.cwd),
+            ),
+        ]

qtmp/utils.py

@@ -0,0 +1,180 @@
+"""
+qtmp.utils
+----------------
+Small helpers: colored terminal output, safe subprocess execution,
+and a minimal spinner. Pure stdlib, no third-party deps.
+"""
+
+import subprocess
+import sys
+import shutil
+import time
+import threading
+import itertools
+
+
+class C:
+    """ANSI color codes (auto-disabled on unsupported terminals)."""
+    _enabled = sys.stdout.isatty()
+    RESET = "\033[0m" if _enabled else ""
+    BOLD = "\033[1m" if _enabled else ""
+    DIM = "\033[2m" if _enabled else ""
+    ITALIC = "\033[3m" if _enabled else ""
+    GREEN = "\033[32m" if _enabled else ""
+    RED = "\033[31m" if _enabled else ""
+    YELLOW = "\033[33m" if _enabled else ""
+    CYAN = "\033[36m" if _enabled else ""
+    MAGENTA = "\033[35m" if _enabled else ""
+    BLUE = "\033[34m" if _enabled else ""
+    WHITE = "\033[97m" if _enabled else ""
+    # Bright variants read better on dark terminal backgrounds.
+    B_CYAN = "\033[96m" if _enabled else ""
+    B_MAGENTA = "\033[95m" if _enabled else ""
+    B_GREEN = "\033[92m" if _enabled else ""
+    B_YELLOW = "\033[93m" if _enabled else ""
+
+
+LOGO = r"""
+       _
+  __ _| |_ _ __ ___  _ __
+ / _` | __| '_ ` _ \| '_ \
+| (_| | |_| | | | | | |_) |
+ \__, |\__|_| |_| |_| .__/
+    |_|             |_|
+"""
+
+
+def print_logo(tagline: str = "scaffold your stack, without the busywork"):
+    print(f"{C.B_CYAN}{LOGO}{C.RESET}")
+    print(f"  {C.DIM}{C.ITALIC}{tagline}{C.RESET}\n")
+
+
+def banner(text: str):
+    width = max(len(text) + 4, 20)
+    top = "╭" + "─" * (width - 2) + "╮"
+    bottom = "╰" + "─" * (width - 2) + "╯"
+    pad = width - 2 - len(text)
+    left_pad = pad // 2
+    right_pad = pad - left_pad
+    print(f"\n{C.B_MAGENTA}{top}{C.RESET}")
+    print(f"{C.B_MAGENTA}│{C.RESET}{' ' * left_pad}{C.BOLD}{C.WHITE}{text}{C.RESET}{' ' * right_pad}{C.B_MAGENTA}│{C.RESET}")
+    print(f"{C.B_MAGENTA}{bottom}{C.RESET}")
+
+
+def info(text: str):
+    print(f"{C.B_CYAN}i{C.RESET}  {text}")
+
+
+def ok(text: str):
+    print(f"{C.B_GREEN}✓{C.RESET}  {text}")
+
+
+def warn(text: str):
+    print(f"{C.B_YELLOW}!{C.RESET}  {text}")
+
+
+def err(text: str):
+    print(f"{C.RED}✗{C.RESET}  {text}")
+
+
+def which(binary: str) -> bool:
+    """Check whether a binary exists on PATH."""
+    return shutil.which(binary) is not None
+
+
+class Spinner:
+    """A tiny context-manager spinner for long-running commands."""
+
+    FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def __init__(self, message: str):
+        self.message = message
+        self._stop = threading.Event()
+        self._thread = None
+
+    def _spin(self):
+        for frame in itertools.cycle(self.FRAMES):
+            if self._stop.is_set():
+                break
+            sys.stdout.write(f"\r{C.MAGENTA}{frame}{C.RESET}  {self.message}   ")
+            sys.stdout.flush()
+            time.sleep(0.08)
+        sys.stdout.write("\r" + " " * (len(self.message) + 10) + "\r")
+        sys.stdout.flush()
+
+    def __enter__(self):
+        if sys.stdout.isatty():
+            self._thread = threading.Thread(target=self._spin, daemon=True)
+            self._thread.start()
+        else:
+            print(f"... {self.message}")
+        return self
+
+    def __exit__(self, *exc):
+        self._stop.set()
+        if self._thread:
+            self._thread.join()
+
+
+def run(cmd, cwd=None, spinner_msg=None, check=True) -> subprocess.CompletedProcess:
+    """
+    Run a shell command, streaming output live to the console.
+    `cmd` can be a list (preferred) or a string.
+
+    Returns the CompletedProcess. Raises CalledProcessError if check=True
+    and the command fails (caller can catch this to report cleanly).
+    """
+    shown = cmd if isinstance(cmd, str) else " ".join(cmd)
+    print(f"{C.DIM}$ {shown}{C.RESET}")
+
+    result = subprocess.run(
+        cmd,
+        cwd=cwd,
+        shell=isinstance(cmd, str),
+        text=True,
+    )
+
+    if check and result.returncode != 0:
+        raise subprocess.CalledProcessError(result.returncode, cmd)
+
+    return result
+
+
+def prompt(msg: str, default: str = None) -> str:
+    suffix = f" [{default}]" if default else ""
+    val = input(f"{C.BOLD}{msg}{suffix}: {C.RESET}").strip()
+    return val or (default or "")
+
+
+def confirm(msg: str, default: bool = True) -> bool:
+    suffix = "[Y/n]" if default else "[y/N]"
+    val = input(f"{C.BOLD}{msg} {suffix}: {C.RESET}").strip().lower()
+    if not val:
+        return default
+    return val in ("y", "yes")
+
+
+def prompt_directory(default_cwd: str) -> str:
+    """
+    Simple directory picker: default is "create right here" — just hit
+    Enter. Only asks for a name if the person wants a fresh subfolder,
+    never a full path.
+    """
+    import os as _os
+
+    info(f"Creating in: {default_cwd}")
+    name = prompt("Folder name (Enter = use this directory as-is)", default="")
+
+    if not name:
+        return default_cwd
+
+    path = _os.path.join(default_cwd, name)
+    if _os.path.isfile(path):
+        err(f"{path} is a file, not a directory.")
+        return prompt_directory(default_cwd)
+
+    if not _os.path.isdir(path):
+        _os.makedirs(path, exist_ok=True)
+        ok(f"Created ./{name}")
+
+    return path