qtmp 0.2.0__py3-none-any.whl

qtmp/__init__.py

@@ -0,0 +1 @@
+__version__ = "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/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/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/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/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/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}")

qtmp/executor.py

@@ -0,0 +1,98 @@
+"""
+qtmp.executor
+--------------
+Turns a Plan into real side effects. Two guarantees this module exists
+to provide:
+
+1. Idempotency: steps already marked `already_satisfied` by the planner
+   are reported, never re-run.
+2. Fail-fast with a clear report: if a step fails, later steps (which
+   may assume it succeeded) are not attempted, and the person gets a
+   readable summary of what did and didn't happen instead of a raw
+   traceback.
+"""
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import List
+
+from qtmp.planner import Plan, Step
+from qtmp.utils import Spinner, ok, warn, err, info
+
+
+@dataclass
+class ExecutionResult:
+    plan: Plan
+    applied: List[Step] = field(default_factory=list)
+    skipped: List[Step] = field(default_factory=list)
+    failed_step: Step = None
+    error: str = None
+
+    @property
+    def success(self) -> bool:
+        return self.failed_step is None
+
+
+def apply(plan: Plan) -> ExecutionResult:
+    result = ExecutionResult(plan=plan)
+
+    if plan.is_noop():
+        for step in plan.steps:
+            result.skipped.append(step)
+        return result
+
+    for step in plan.steps:
+        if step.already_satisfied:
+            result.skipped.append(step)
+            continue
+
+        try:
+            _run_step(step)
+            result.applied.append(step)
+        except Exception as e:  # noqa: BLE001 — any step failure halts the plan
+            result.failed_step = step
+            result.error = str(e)
+            break
+
+    return result
+
+
+def _run_step(step: Step):
+    from qtmp.utils import run as run_cmd
+
+    if step.apply_fn is not None:
+        with Spinner(step.description):
+            step.apply_fn()
+        return
+
+    if step.command is not None:
+        with Spinner(step.description):
+            run_cmd(step.command, cwd=step.cwd)
+        return
+
+    # A step with neither command nor apply_fn is just an informational
+    # marker (e.g. "already installed") and should never reach here since
+    # those are always already_satisfied — but guard anyway.
+
+
+def report(result: ExecutionResult, capability: str):
+    if result.plan.is_noop():
+        for step in result.skipped:
+            ok(step.description)
+        info("Nothing to do.")
+        return
+
+    for step in result.applied:
+        ok(step.description)
+    for step in result.skipped:
+        ok(f"{step.description} (skipped, already satisfied)")
+
+    if not result.success:
+        err(f"Failed: {result.failed_step.description}")
+        if result.error:
+            print(f"  {result.error}")
+        warn(f"Stopped before finishing '{capability}'. Nothing after the "
+             "failed step was run — safe to fix the issue and re-run 'qtmp add "
+             f"{capability}'; already-applied steps will be skipped next time.")
+    else:
+        ok(f"'{capability}' is ready.")

qtmp/planner.py

@@ -0,0 +1,84 @@
+"""
+qtmp.planner
+-------------
+A Step is one concrete unit of work. A Plan is an ordered list of Steps
+produced by walking a capability's dependency chain against the current
+ProjectContext. Nothing here touches the filesystem or a subprocess —
+that's the executor's job. This separation is what makes `qtmp plan add X`
+(dry run) and `qtmp add X` (real run) the exact same code path, just
+stopping one step earlier.
+"""
+
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional
+
+
+@dataclass
+class Step:
+    description: str
+    command: Optional[list] = None
+    cwd: Optional[str] = None
+    apply_fn: Optional[Callable[[], None]] = None
+    already_satisfied: bool = False
+    # Which capability this step belongs to, for readable plan output.
+    capability: str = ""
+
+
+@dataclass
+class Plan:
+    capability: str
+    steps: List[Step] = field(default_factory=list)
+
+    @property
+    def pending_steps(self) -> List[Step]:
+        return [s for s in self.steps if not s.already_satisfied]
+
+    def is_noop(self) -> bool:
+        return len(self.pending_steps) == 0
+
+
+class ResolutionError(Exception):
+    pass
+
+
+def resolve_plan(capability: str, ctx, registry, _seen=None) -> Plan:
+    """
+    Depth-first walk of `requires(ctx)`, dependencies before the target,
+    each capability visited at most once even if requested by multiple
+    dependents (a diamond dependency doesn't get installed twice).
+
+    A capability whose recipe.detect(ctx) is already True still shows up
+    in the plan, marked already_satisfied, so `qtmp plan` output is
+    honest about the whole chain rather than silently omitting parts
+    that are already done.
+    """
+    if _seen is None:
+        _seen = set()
+    if capability in _seen:
+        return Plan(capability=capability, steps=[])
+    _seen.add(capability)
+
+    recipe = registry.get(capability)
+    if recipe is None:
+        raise ResolutionError(
+            f"No recipe provides '{capability}'. Run 'qtmp list' to see what's available."
+        )
+
+    steps: List[Step] = []
+
+    for dep_capability in recipe.requires(ctx):
+        dep_plan = resolve_plan(dep_capability, ctx, registry, _seen)
+        steps.extend(dep_plan.steps)
+
+    if recipe.detect(ctx):
+        steps.append(Step(
+            description=f"{recipe.name} already installed",
+            already_satisfied=True,
+            capability=capability,
+        ))
+    else:
+        for step in recipe.plan(ctx):
+            step.capability = step.capability or capability
+            steps.append(step)
+
+    return Plan(capability=capability, steps=steps)