qtmp 0.2.0__tar.gz

qtmp-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: qtmp
+Version: 0.2.0
+Summary: Qtmp -- Developer Environment Automation CLI. Detects project environments, resolves dependencies, generates execution plans, and runs package-manager commands, with idempotent operations and dry-run planning built in.
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary

qtmp-0.2.0/README.md

@@ -0,0 +1,156 @@
+# qtmp — Q-Templates: Developer Environment Automation CLI
+
+A Python CLI that detects your project environment, resolves
+dependencies between tech stacks, generates an execution plan, and
+runs the package-manager commands — instead of you hunting through
+docs and typing them one by one.
+
+```bash
+pip3 install qtmp
+qtmp create react
+qtmp add tailwind
+qtmp plan add sqlalchemy   # dry run first
+qtmp add sqlalchemy        # then actually run it
+qtmp doctor
+```
+
+## Why this isn't just "a script that runs npm install"
+
+- **Recipe architecture** — every piece of the stack (React, Tailwind,
+  FastAPI, SQLAlchemy, ...) is a self-contained `Recipe` with three
+  methods: `requires()`, `detect()`, `plan()`. Adding a new one is one
+  file + one line in a registry — nothing in the CLI, planner, or
+  executor changes.
+- **Real dependency resolution** — `qtmp add sqlalchemy` in an empty
+  folder resolves to: scaffold FastAPI → install the Postgres driver
+  → install SQLAlchemy, in that order, with shared dependencies
+  (a "diamond") only ever installed once.
+- **Project detection** — reads `package.json`, `vite.config.*`,
+  `pyproject.toml`, `requirements.txt`, `docker-compose.yml`,
+  `tailwind.config.*` once per run into a `ProjectContext`, so every
+  recipe and `qtmp doctor` see the same picture of "what's already here."
+- **Dry-run planning** — `qtmp plan add X` shows the exact commands that
+  would run, against the real dependency graph, without touching the
+  filesystem. `qtmp add X` is the same resolution path, one step later.
+- **Idempotent by construction** — every recipe's `detect()` is checked
+  *before* its `plan()` is even called. Running `qtmp add tailwind`
+  twice reports "already installed, nothing to do" instead of
+  reinstalling or corrupting config.
+- **Fail-fast, resumable execution** — if a step fails (bad network,
+  missing tool), everything after it stops. Already-applied steps are
+  skipped on the next attempt; nothing after the failure was touched.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `qtmp create react` / `qtmp create fastapi` | Scaffold a brand-new project (asks name, and for React, beginner/advanced) |
+| `qtmp add <capability>` | Resolve dependencies and install/configure a capability |
+| `qtmp plan add <capability>` | Same resolution, dry-run only — prints the commands, changes nothing |
+| `qtmp doctor` | Diagnose which tools are on PATH and what this directory looks like |
+| `qtmp list` | List every registered capability |
+| `qtmp cheatsheet [name]` | View built-in or your own personal cheatsheets |
+| `qtmp --version` | Print the installed version |
+
+Beginner React (`b`) gets Vite + Tailwind automatically. Advanced (`a`)
+gets TypeScript, Tailwind, shadcn/ui, React Router, Axios, and a
+`src/components|pages|hooks|lib` layout — all resolved and applied
+through the same planner/executor path as a manual `qtmp add`.
+
+## Architecture
+
+```
+qtmp/
+├── context.py      ProjectContext.detect(cwd) -- one detection pass, shared everywhere
+├── planner.py      Step, Plan, resolve_plan() -- pure dependency-graph resolution
+├── executor.py      apply(plan) -- runs pending steps, skips satisfied ones, fails fast
+├── doctor.py        read-only environment + project diagnostics
+├── recipes/
+│   ├── base.py       Recipe ABC: requires() / detect() / plan() / (optional) create()
+│   ├── react.py       provides "react", creatable
+│   ├── tailwind.py    provides "tailwind", requires "react" only if no node project exists yet
+│   ├── router_axios.py provides "router" / "axios" / "shadcn" (shadcn requires "tailwind")
+│   ├── fastapi.py      provides "fastapi", creatable
+│   ├── database.py     provides "postgres" / "db-driver-postgres" / "sqlalchemy"
+│   └── __init__.py     REGISTRY = {capability_name: recipe_instance} -- the only file
+│                       you edit to add a new recipe
+├── cheatsheet_manager.py   bundled vs. personal (~/.qtmp/cheatsheets/) cheatsheets
+└── cli.py            argparse subcommands, all going through resolve_plan()/apply()
+```
+
+### The dependency-resolution example, end to end
+
+`qtmp add sqlalchemy` on an empty folder resolves like this:
+
+```
+sqlalchemy
+ ├── requires: fastapi          -> not detected -> scaffold venv, install fastapi+uvicorn, write main.py
+ └── requires: db-driver-postgres
+      └── requires: fastapi     -> already resolved above, not repeated
+                                -> not detected -> pip install psycopg2-binary
+ -> not detected -> pip install sqlalchemy
+```
+
+Run it for real and check the output of `qtmp plan add sqlalchemy` first
+— that's the exact plan the executor will follow, nothing hidden.
+
+### Adding a new recipe
+
+```python
+# qtmp/recipes/docker.py
+from qtmp.recipes.base import Recipe
+from qtmp.planner import Step
+
+class DockerRecipe(Recipe):
+    name = "Docker"
+    provides = "docker"
+
+    def detect(self, ctx):
+        return ctx.has_docker_compose
+
+    def plan(self, ctx):
+        return [Step("Write docker-compose.yml", apply_fn=lambda: ...)]
+```
+```python
+# qtmp/recipes/__init__.py
+from qtmp.recipes.docker import DockerRecipe
+REGISTRY["docker"] = DockerRecipe()
+```
+That's the entire integration surface. `cli.py`, `planner.py`, and
+`executor.py` never need to know Docker exists.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+40 tests covering:
+- **Project detection** — Node/Vite/Python/venv/Docker/Tailwind sniffing, and that a malformed `package.json` doesn't crash detection.
+- **Dependency resolution** — ordering, diamond dependencies installed once, unknown capabilities raising a clear error, and the exact FastAPI→driver→SQLAlchemy shape from the design doc.
+- **Idempotency & safe execution** — a fully-satisfied chain is a no-op; a failure mid-plan halts everything after it and reports which step failed; already-applied steps are never re-run.
+- **Individual recipes** — `detect()`/`plan()`/`requires()` logic for React, Tailwind, Router, Axios, shadcn, FastAPI, and the database chain, with **no real npm/pip/network calls** — commands are asserted on, never executed, in unit tests.
+- **Cheatsheets** — personal overrides taking precedence over bundled ones, and falling back correctly on removal.
+
+Recipe tests never shell out for real — `plan()` is asserted on
+directly, so these pass identically whether or not Node/Python/Postgres
+happen to be installed on the machine running CI.
+
+## Honest limitations (not yet done)
+
+- **Cross-platform**: path handling is OS-aware (`os.name == "nt"`
+  branches for venv paths), but this has only actually been *run* on
+  macOS/Linux. Windows support is written for, not verified.
+- **Package manager choice**: assumes `npm` and `pip`. No `pnpm`/`yarn`/
+  `poetry`/`uv` alternative paths yet — a natural next recipe-level
+  feature (a `--pm` flag resolved per-ecosystem).
+- **`postgres` recipe** deliberately does *not* auto-install a local
+  Postgres server (that usually needs `sudo` / a package-manager
+  choice we shouldn't make for you) — it only guides you and checks
+  for `psql` on PATH. Automating a *sudo-requiring* step didn't feel
+  like something a CLI should do silently, even in service of a demo.
+- **AI-assisted setup** from an earlier iteration was removed in this
+  rewrite to keep the core deterministic and testable; if it comes
+  back, it'll be a strictly optional layer on top of `resolve_plan()`,
+  never a replacement for it.

qtmp-0.2.0/qtmp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

qtmp-0.2.0/qtmp/cheatsheet_manager.py

@@ -0,0 +1,75 @@
+"""
+qtmp.cheatsheet_manager
+-------------------------------
+Two sources of cheatsheets:
+
+1. Bundled  -> qtmp/cheatsheets/*.md   (shipped with the package)
+2. Personal -> ~/.qtmp/cheatsheets/*.md (your own handmade notes)
+
+Personal cheatsheets always take priority: if you drop a `react.md` in
+your personal folder, it overrides the bundled one — so you can keep
+your own handwritten reference without losing it on an upgrade.
+"""
+
+import os
+import shutil
+
+BUNDLED_DIR = os.path.join(os.path.dirname(__file__), "cheatsheets")
+PERSONAL_DIR = os.path.join(os.path.expanduser("~"), ".qtmp", "cheatsheets")
+
+
+def _ensure_personal_dir():
+    os.makedirs(PERSONAL_DIR, exist_ok=True)
+
+
+def list_cheatsheets():
+    """Return {name: (path, source)} merged, personal overriding bundled."""
+    _ensure_personal_dir()
+    sheets = {}
+
+    if os.path.isdir(BUNDLED_DIR):
+        for fname in sorted(os.listdir(BUNDLED_DIR)):
+            if fname.endswith(".md"):
+                name = fname[:-3]
+                sheets[name] = (os.path.join(BUNDLED_DIR, fname), "bundled")
+
+    for fname in sorted(os.listdir(PERSONAL_DIR)):
+        if fname.endswith(".md"):
+            name = fname[:-3]
+            sheets[name] = (os.path.join(PERSONAL_DIR, fname), "personal")
+
+    return sheets
+
+
+def view(name: str) -> str:
+    sheets = list_cheatsheets()
+    if name not in sheets:
+        return None
+    path, _source = sheets[name]
+    with open(path, "r") as f:
+        return f.read()
+
+
+def add(name: str, source_path: str) -> str:
+    """
+    Copy a user's own handmade cheatsheet file into the personal folder,
+    so it survives package upgrades and overrides any bundled sheet of
+    the same name.
+    """
+    _ensure_personal_dir()
+    source_path = os.path.expanduser(source_path)
+    if not os.path.isfile(source_path):
+        raise FileNotFoundError(source_path)
+
+    dest = os.path.join(PERSONAL_DIR, f"{name}.md")
+    shutil.copyfile(source_path, dest)
+    return dest
+
+
+def remove(name: str) -> bool:
+    """Remove a personal cheatsheet override (bundled ones can't be removed)."""
+    path = os.path.join(PERSONAL_DIR, f"{name}.md")
+    if os.path.isfile(path):
+        os.remove(path)
+        return True
+    return False

qtmp-0.2.0/qtmp/cheatsheets/fastapi.md

@@ -0,0 +1,24 @@
+# FastAPI Cheatsheet
+
+## Dev commands
+    uvicorn main:app --reload      start dev server (localhost:8000)
+
+## Built-in docs
+    /docs      Swagger UI
+    /redoc     ReDoc
+
+## Minimal app
+    from fastapi import FastAPI
+    app = FastAPI()
+
+    @app.get("/")
+    def read_root():
+        return {"message": "hello"}
+
+## PostgreSQL (via SQLAlchemy)
+    DATABASE_URL = "postgresql://user:pass@localhost:5432/dbname"
+
+## Gotchas
+- `uvicorn[standard]` pulls in the faster event loop + websockets support;
+  plain `uvicorn` is a lighter install if you don't need those.
+- `--reload` is for development only — never use it in production.

qtmp-0.2.0/qtmp/cheatsheets/react.md

@@ -0,0 +1,22 @@
+# React + Vite Cheatsheet
+
+## Dev commands
+    npm run dev        start dev server
+    npm run build      production build
+    npm run preview    preview the build
+
+## Common add-ons
+    npm install react-router-dom     # routing
+    npm install axios                # HTTP client
+    npx shadcn@latest add button     # add a shadcn component
+
+## File structure (default Vite scaffold)
+    src/
+      main.jsx     entry point, mounts <App />
+      App.jsx      root component
+    index.html     Vite's HTML entry (not public/index.html like CRA)
+
+## Gotchas
+- Env vars must be prefixed `VITE_` to be exposed to the client
+  (e.g. `VITE_API_URL`, accessed via `import.meta.env.VITE_API_URL`).
+- Vite dev server default port: 5173 (not 3000).

qtmp-0.2.0/qtmp/cli.py

@@ -0,0 +1,234 @@
+"""
+qtmp.cli
+---------
+Real subcommands, not a menu loop:
+
+    qtmp create react
+    qtmp create fastapi
+    qtmp add tailwind
+    qtmp add sqlalchemy
+    qtmp plan add sqlalchemy   # dry run: show what would happen, change nothing
+    qtmp doctor
+    qtmp list
+    qtmp cheatsheet [name]
+
+Every `add`/`plan add` goes through the same dependency-resolution
+path (qtmp.planner.resolve_plan), so the dry run and the real run can
+never drift apart from each other.
+"""
+
+import argparse
+import os
+import sys
+
+from qtmp import __version__
+from qtmp.context import ProjectContext
+from qtmp.recipes import REGISTRY, CREATABLE, resolve_name
+from qtmp.planner import resolve_plan, ResolutionError
+from qtmp.executor import apply as execute_plan, report as report_result
+from qtmp.doctor import run_doctor
+from qtmp.utils import banner, info, warn, ok, err, print_logo, C
+from qtmp import cheatsheet_manager as cheats
+
+
+def cmd_create(args):
+    key = resolve_name(args.recipe)
+    recipe = CREATABLE.get(key)
+    if recipe is None:
+        available = ", ".join(sorted(CREATABLE.keys()))
+        err(f"'{args.recipe}' isn't creatable. Available: {available}")
+        sys.exit(1)
+
+    ctx = ProjectContext.detect(args.cwd)
+    banner(f"Create: {recipe.name}")
+    project_dir, advanced = recipe.create(ctx)
+
+    if key == "react" and advanced:
+        sub_ctx = ProjectContext.detect(project_dir)
+        info("Advanced preset: adding Tailwind, shadcn/ui, Router, Axios automatically.")
+        for capability in ("tailwind", "shadcn", "router", "axios"):
+            _add_capability(capability, sub_ctx)
+    elif key == "react":
+        sub_ctx = ProjectContext.detect(project_dir)
+        info("Beginner preset: adding Tailwind automatically.")
+        _add_capability("tailwind", sub_ctx)
+
+    ok(f"Done. cd {project_dir}")
+
+
+def cmd_add(args):
+    ctx = ProjectContext.detect(args.cwd)
+    key = resolve_name(args.capability)
+    _add_capability(key, ctx)
+
+
+def cmd_plan(args):
+    ctx = ProjectContext.detect(args.cwd)
+    key = resolve_name(args.capability)
+    _print_plan(key, ctx)
+
+
+def _add_capability(key: str, ctx):
+    try:
+        plan = resolve_plan(key, ctx, REGISTRY)
+    except ResolutionError as e:
+        err(str(e))
+        return
+
+    banner(f"add: {key}")
+    if plan.is_noop():
+        for step in plan.steps:
+            ok(step.description)
+        info("Nothing to do.")
+        return
+
+    for step in plan.pending_steps:
+        print(f"  {C.DIM}->{C.RESET} {step.description}")
+
+    result = execute_plan(plan)
+    report_result(result, key)
+
+
+def _print_plan(key: str, ctx):
+    try:
+        plan = resolve_plan(key, ctx, REGISTRY)
+    except ResolutionError as e:
+        err(str(e))
+        return
+
+    banner(f"plan: {key}")
+    if plan.is_noop():
+        for step in plan.steps:
+            ok(f"{step.description} (already satisfied)")
+        info("Nothing to do — running 'qtmp add' now would be a no-op.")
+        return
+
+    for step in plan.steps:
+        if step.already_satisfied:
+            print(f"  {C.DIM}✓ {step.description} (already satisfied){C.RESET}")
+        else:
+            cmd_preview = " ".join(step.command) if step.command else "(custom action)"
+            print(f"  {C.B_YELLOW}→{C.RESET} {step.description}")
+            print(f"    {C.DIM}$ {cmd_preview}{C.RESET}")
+
+    info("Dry run only — nothing was changed. Run 'qtmp add "
+         f"{key}' to execute this plan.")
+
+
+def cmd_doctor(args):
+    ctx = ProjectContext.detect(args.cwd)
+    run_doctor(ctx)
+
+
+def cmd_list(args):
+    banner("Available capabilities")
+    for cap, recipe in sorted(REGISTRY.items()):
+        tag = f"{C.DIM}(creatable){C.RESET}" if recipe.creatable else ""
+        print(f"  {C.CYAN}{cap}{C.RESET}  {tag}")
+    info("qtmp add <capability>  |  qtmp create <capability>  |  qtmp plan add <capability>")
+
+
+def cmd_cheatsheet(args):
+    extra = args.extra or []
+    if not extra:
+        sheets = cheats.list_cheatsheets()
+        if not sheets:
+            info("No cheatsheets yet. Add one with: qtmp cheatsheet add <name> <path/to/file.md>")
+            return
+        banner("Cheatsheets")
+        for name, (_path, source) in sheets.items():
+            tag = f"{C.DIM}(yours){C.RESET}" if source == "personal" else f"{C.DIM}(built-in){C.RESET}"
+            print(f"  {C.CYAN}{name}{C.RESET} {tag}")
+        info("View one with: qtmp cheatsheet <name>")
+        return
+
+    if extra[0] == "add":
+        if len(extra) < 3:
+            warn("Usage: qtmp cheatsheet add <name> <path/to/your-notes.md>")
+            return
+        name, path = extra[1], extra[2]
+        try:
+            dest = cheats.add(name, path)
+            ok(f"Saved your cheatsheet as '{name}' -> {dest}")
+        except FileNotFoundError:
+            warn(f"File not found: {path}")
+        return
+
+    if extra[0] == "remove":
+        if len(extra) < 2:
+            warn("Usage: qtmp cheatsheet remove <name>")
+            return
+        removed = cheats.remove(extra[1])
+        if removed:
+            ok(f"Removed your custom cheatsheet '{extra[1]}'.")
+        else:
+            warn(f"No personal cheatsheet named '{extra[1]}' to remove "
+                 "(built-in ones can't be removed, only overridden).")
+        return
+
+    name = extra[0]
+    content = cheats.view(name)
+    if content is None:
+        warn(f"No cheatsheet named '{name}'. Run 'qtmp cheatsheet' to see what's available.")
+        return
+    print(f"\n{content}")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="qtmp",
+        description="Developer Environment Automation CLI — detects your project, "
+        "resolves dependencies, and executes package-manager commands so you don't "
+        "have to hunt through docs.",
+    )
+    parser.add_argument("--version", action="version", version=f"qtmp {__version__}")
+    parser.add_argument("--cwd", default=os.getcwd(), help="Directory to operate in.")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_create = sub.add_parser("create", help="Scaffold a brand-new project (react, fastapi).")
+    p_create.add_argument("recipe")
+    p_create.set_defaults(func=cmd_create)
+
+    p_add = sub.add_parser("add", help="Add a capability, resolving dependencies, and run it.")
+    p_add.add_argument("capability")
+    p_add.set_defaults(func=cmd_add)
+
+    p_plan = sub.add_parser("plan", help="Dry-run: show what 'add' would do without doing it.")
+    plan_sub = p_plan.add_subparsers(dest="plan_command")
+    p_plan_add = plan_sub.add_parser("add")
+    p_plan_add.add_argument("capability")
+    p_plan_add.set_defaults(func=cmd_plan)
+
+    p_doctor = sub.add_parser("doctor", help="Diagnose the environment and this project.")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    p_list = sub.add_parser("list", help="List all available capabilities.")
+    p_list.set_defaults(func=cmd_list)
+
+    p_cheat = sub.add_parser("cheatsheet", help="View or manage cheatsheets.")
+    p_cheat.add_argument("extra", nargs="*")
+    p_cheat.set_defaults(func=cmd_cheatsheet)
+
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+    args.cwd = os.path.abspath(args.cwd)
+
+    if not getattr(args, "command", None):
+        print_logo()
+        parser.print_help()
+        return
+
+    if args.command == "plan" and getattr(args, "plan_command", None) != "add":
+        parser.parse_args(["plan", "--help"])
+        return
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

qtmp-0.2.0/qtmp/context.py

@@ -0,0 +1,94 @@
+"""
+qtmp.context
+-------------
+Detects what kind of project directory we're standing in, once per run.
+Every recipe reads from this instead of re-implementing its own file
+sniffing — that's what makes `qtmp doctor` and dependency resolution
+consistent with each other.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProjectContext:
+    cwd: str
+
+    # Node / JS
+    has_package_json: bool = False
+    is_node: bool = False
+    is_vite: bool = False
+    node_deps: set = field(default_factory=set)
+
+    # Python
+    has_pyproject: bool = False
+    has_requirements: bool = False
+    is_python: bool = False
+    has_venv: bool = False
+
+    # Infra
+    has_docker_compose: bool = False
+    has_tailwind_config: bool = False
+
+    @classmethod
+    def detect(cls, cwd: str) -> "ProjectContext":
+        ctx = cls(cwd=cwd)
+
+        pkg_path = os.path.join(cwd, "package.json")
+        if os.path.isfile(pkg_path):
+            ctx.has_package_json = True
+            ctx.is_node = True
+            try:
+                with open(pkg_path) as f:
+                    data = json.load(f)
+                deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+                ctx.node_deps = set(deps.keys())
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        for fname in ("vite.config.js", "vite.config.ts"):
+            if os.path.isfile(os.path.join(cwd, fname)):
+                ctx.is_vite = True
+
+        if os.path.isfile(os.path.join(cwd, "pyproject.toml")):
+            ctx.has_pyproject = True
+            ctx.is_python = True
+        if os.path.isfile(os.path.join(cwd, "requirements.txt")):
+            ctx.has_requirements = True
+            ctx.is_python = True
+        if os.path.isdir(os.path.join(cwd, "venv")) or os.path.isdir(os.path.join(cwd, ".venv")):
+            ctx.has_venv = True
+            ctx.is_python = True
+
+        for fname in ("docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"):
+            if os.path.isfile(os.path.join(cwd, fname)):
+                ctx.has_docker_compose = True
+
+        for fname in ("tailwind.config.js", "tailwind.config.ts"):
+            if os.path.isfile(os.path.join(cwd, fname)):
+                ctx.has_tailwind_config = True
+
+        return ctx
+
+    # ---- venv path helpers (kept here so recipes never hardcode OS paths) --
+
+    def _venv_dir(self):
+        for name in ("venv", ".venv"):
+            candidate = os.path.join(self.cwd, name)
+            if os.path.isdir(candidate):
+                return candidate
+        return os.path.join(self.cwd, "venv")
+
+    def venv_python(self) -> str:
+        venv_dir = self._venv_dir()
+        if os.name == "nt":
+            return os.path.join(venv_dir, "Scripts", "python.exe")
+        return os.path.join(venv_dir, "bin", "python")
+
+    def venv_pip(self) -> str:
+        venv_dir = self._venv_dir()
+        if os.name == "nt":
+            return os.path.join(venv_dir, "Scripts", "pip.exe")
+        return os.path.join(venv_dir, "bin", "pip")

qtmp-0.2.0/qtmp/doctor.py

@@ -0,0 +1,51 @@
+"""
+qtmp.doctor
+------------
+`qtmp doctor` — one command that answers "what does qtmp think this
+environment looks like, and what's missing." Read-only: it never
+installs anything, only reports.
+"""
+
+from qtmp.utils import C, ok, warn, info, which
+
+
+TOOLS = [
+    ("node", "Node.js"),
+    ("npm", "npm"),
+    ("python3", "Python 3"),
+    ("pip3", "pip"),
+    ("psql", "PostgreSQL client"),
+    ("docker", "Docker"),
+]
+
+
+def run_doctor(ctx):
+    print(f"\n{C.BOLD}Tools on PATH{C.RESET}")
+    for binary, label in TOOLS:
+        if which(binary):
+            ok(f"{label} ({binary})")
+        else:
+            warn(f"{label} ({binary}) not found")
+
+    print(f"\n{C.BOLD}Project detected at {ctx.cwd}{C.RESET}")
+
+    flags = [
+        (ctx.has_package_json, "package.json (Node project)"),
+        (ctx.is_vite, "Vite config"),
+        (ctx.has_tailwind_config, "Tailwind config"),
+        (ctx.has_pyproject, "pyproject.toml (Python project)"),
+        (ctx.has_requirements, "requirements.txt"),
+        (ctx.has_venv, "virtual environment (venv/.venv)"),
+        (ctx.has_docker_compose, "docker-compose file"),
+    ]
+    any_detected = False
+    for present, label in flags:
+        if present:
+            ok(label)
+            any_detected = True
+
+    if not any_detected:
+        info("No recognizable project here yet — 'qtmp create react' or 'qtmp create fastapi' to start one.")
+
+    if ctx.node_deps:
+        print(f"\n{C.DIM}Detected npm dependencies: {', '.join(sorted(ctx.node_deps))}{C.RESET}")