qtmp 0.2.0__tar.gz → 0.3.0__tar.gz

{qtmp-0.2.0 → qtmp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qtmp
-Version: 0.2.0
+Version: 0.3.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

{qtmp-0.2.0 → qtmp-0.3.0}/README.md

@@ -44,7 +44,8 @@ qtmp doctor
 
 | Command | What it does |
 |---|---|
-| `qtmp create react` / `qtmp create fastapi` | Scaffold a brand-new project (asks name, and for React, beginner/advanced) |
+| `qtmp create react` / `qtmp create fastapi` / `qtmp create frontend-basic` | Scaffold a brand-new project |
+| `qtmp <capability>` | **Shorthand** — `qtmp fastapi` == `qtmp create fastapi`; `qtmp tailwind` == `qtmp add tailwind` (creatable capabilities go to `create`, everything else to `add`) |
 | `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 |
@@ -52,11 +53,25 @@ qtmp doctor
 | `qtmp cheatsheet [name]` | View built-in or your own personal cheatsheets |
 | `qtmp --version` | Print the installed version |
 
+`--cwd` works in **either position** — `qtmp --cwd ./my-app create react` and `qtmp create react --cwd ./my-app` both work identically.
+
 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`.
 
+`frontend-basic` (aliases: `frontend`, `html-css-js`, `vanilla`) scaffolds
+a plain `index.html` + `style.css` + `script.js` — no framework, no npm,
+no network required. Good for confirming files land where you expect
+without waiting on any package manager.
+
+### Re-running `create` is safe
+
+Every creatable recipe checks the target folder before scaffolding:
+- **Doesn't exist / empty** → scaffolds normally.
+- **Already a valid project of that type** → skipped, reports "already exists," doesn't touch it.
+- **Exists, non-empty, and isn't that project type** → clean error, doesn't blindly run a scaffolder into someone else's files.
+
 ## Architecture
 
 ```
@@ -72,10 +87,13 @@ qtmp/
 │   ├── router_axios.py provides "router" / "axios" / "shadcn" (shadcn requires "tailwind")
 │   ├── fastapi.py      provides "fastapi", creatable
 │   ├── database.py     provides "postgres" / "db-driver-postgres" / "sqlalchemy"
+│   ├── frontend_basic.py provides "frontend-basic", creatable -- plain HTML/CSS/JS
 │   └── __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()
+└── cli.py            argparse subcommands, all going through resolve_plan()/apply();
+                       also handles --cwd extraction (works before/after the
+                       subcommand) and shorthand expansion ('qtmp fastapi' -> 'qtmp create fastapi')
 ```
 
 ### The dependency-resolution example, end to end
@@ -126,7 +144,9 @@ pip install -e ".[dev]"
 pytest -v
 ```
 
-40 tests covering:
+60 tests covering:
+- **CLI helpers** — shorthand expansion (`qtmp fastapi` → `create fastapi`), and `--cwd` extraction working in either position, including the `--cwd=value` form and repeated occurrences.
+- **Existing-target safety** — `create` skips cleanly on an already-valid project of the same type, and raises a clear error (not a crash) on a genuine name collision with unrelated content.
 - **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.

qtmp-0.3.0/qtmp/__init__.py

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

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp/cli.py

@@ -19,6 +19,7 @@ never drift apart from each other.
 
 import argparse
 import os
+import subprocess
 import sys
 
 from qtmp import __version__
@@ -30,6 +31,69 @@ 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
 
+KNOWN_COMMANDS = {"create", "add", "plan", "doctor", "list", "cheatsheet"}
+
+
+def extract_cwd(argv):
+    """
+    Pull --cwd (or --cwd=VALUE) out of argv wherever it appears and
+    return (remaining_argv, value_or_None).
+
+    This exists because argparse has a sharp edge with subparsers:
+    when the same --cwd argument is defined on both the top-level
+    parser and a subparser (so it can appear either before or after
+    the subcommand), the subparser's *default* silently overwrites
+    whatever the top-level parser already captured -- even if the
+    person never typed --cwd a second time. Handling it here, once,
+    before argparse ever sees it, sidesteps that entirely and lets
+    --cwd work in either position reliably.
+    """
+    remaining = []
+    value = None
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok == "--cwd" and i + 1 < len(argv):
+            value = argv[i + 1]
+            i += 2
+            continue
+        if tok.startswith("--cwd="):
+            value = tok.split("=", 1)[1]
+            i += 1
+            continue
+        remaining.append(tok)
+        i += 1
+    return remaining, value
+
+
+def expand_shorthand(argv):
+    """
+    Lets 'qtmp fastapi' work directly instead of requiring
+    'qtmp create fastapi' / 'qtmp add fastapi'. The first bare word
+    that isn't already a known subcommand is checked against the
+    recipe registry: creatable recipes become 'create <name>',
+    everything else becomes 'add <name>'. Anything that doesn't match
+    a known command or a registered capability is left untouched, so
+    argparse still reports a normal error for genuine typos.
+    """
+    for i, tok in enumerate(argv):
+        if tok == "--cwd":
+            continue
+        if i > 0 and argv[i - 1] == "--cwd":
+            continue
+        if tok.startswith("--cwd="):
+            continue
+        if tok.startswith("-"):
+            continue
+        if tok in KNOWN_COMMANDS:
+            return argv
+        key = resolve_name(tok)
+        if key in REGISTRY:
+            verb = "create" if key in CREATABLE else "add"
+            return argv[:i] + [verb, tok] + argv[i + 1:]
+        return argv
+    return argv
+
 
 def cmd_create(args):
     key = resolve_name(args.recipe)
@@ -41,7 +105,23 @@ def cmd_create(args):
 
     ctx = ProjectContext.detect(args.cwd)
     banner(f"Create: {recipe.name}")
-    project_dir, advanced = recipe.create(ctx)
+
+    try:
+        project_dir, advanced = recipe.create(ctx)
+    except RuntimeError as e:
+        err(str(e))
+        return
+    except subprocess.CalledProcessError as e:
+        err(f"A command failed while scaffolding: {e}")
+        warn("Nothing after the failed step ran. Fix the issue and re-run — "
+             "if a partial folder was created, remove it first to avoid a "
+             "'directory not empty' error on retry.")
+        return
+
+    if project_dir is None:
+        # recipe.create() already reported why it stopped (e.g. skipped
+        # because the project already exists) -- nothing more to do.
+        return
 
     if key == "react" and advanced:
         sub_ctx = ProjectContext.detect(project_dir)
@@ -182,11 +262,15 @@ def build_parser():
         "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.")
+    parser.add_argument("--cwd", default=os.getcwd(),
+                         help="Directory to operate in. Works before or after "
+                         "the subcommand, e.g. both 'qtmp --cwd X create react' "
+                         "and 'qtmp create react --cwd X'.")
 
     sub = parser.add_subparsers(dest="command")
 
-    p_create = sub.add_parser("create", help="Scaffold a brand-new project (react, fastapi).")
+    p_create = sub.add_parser("create",
+                               help="Scaffold a brand-new project (react, fastapi, frontend-basic).")
     p_create.add_argument("recipe")
     p_create.set_defaults(func=cmd_create)
 
@@ -214,8 +298,14 @@ def build_parser():
 
 
 def main():
+    argv, cwd_override = extract_cwd(sys.argv[1:])
+    argv = expand_shorthand(argv)
+
     parser = build_parser()
-    args = parser.parse_args()
+    args = parser.parse_args(argv)
+
+    if cwd_override is not None:
+        args.cwd = cwd_override
     args.cwd = os.path.abspath(args.cwd)
 
     if not getattr(args, "command", None):

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp/recipes/__init__.py

@@ -12,6 +12,7 @@ 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
+from qtmp.recipes.frontend_basic import FrontendBasicRecipe
 
 REGISTRY = {
     r.provides: r
@@ -25,6 +26,7 @@ REGISTRY = {
         PostgresRecipe(),
         DbDriverPostgresRecipe(),
         SQLAlchemyRecipe(),
+        FrontendBasicRecipe(),
     ]
 }
 
@@ -43,6 +45,10 @@ ALIASES = {
     "sqlalchemy": "sqlalchemy",
     "shadcn-ui": "shadcn",
     "shadcn/ui": "shadcn",
+    "frontend": "frontend-basic",
+    "html-css-js": "frontend-basic",
+    "vanilla": "frontend-basic",
+    "basic": "frontend-basic",
 }
 
 

qtmp-0.3.0/qtmp/recipes/base.py

@@ -0,0 +1,105 @@
+"""
+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.
+"""
+
+import os
+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 (project_dir, advanced_flag), or (None, False) if
+        creation was skipped (e.g. the target already exists as a
+        valid project of this type — see check_existing_target below).
+        """
+        raise NotImplementedError(f"{self.name} does not support 'create'")
+
+    def check_existing_target(self, project_dir: str):
+        """
+        Shared guard every 'create' implementation should call before
+        scaffolding: prevents blindly re-running a scaffolder (e.g.
+        'npm create vite@latest') into a folder that already has
+        something in it.
+
+        Returns:
+          "skip"   -> folder already looks like a valid project of this
+                      type; caller should report that and return early
+                      instead of re-scaffolding.
+          "clear"  -> folder doesn't exist yet, or exists and is empty;
+                      safe to scaffold into.
+        Raises:
+          RuntimeError -> folder exists, is non-empty, and isn't a
+                          recognizable project of this type. Scaffolding
+                          into it would likely fail anyway (most
+                          scaffolders refuse a non-empty directory) or
+                          silently mix files from two different projects.
+        """
+        from qtmp.context import ProjectContext
+        from qtmp.utils import ok, info
+
+        if not os.path.isdir(project_dir):
+            return "clear"
+
+        if not os.listdir(project_dir):
+            return "clear"
+
+        existing_ctx = ProjectContext.detect(project_dir)
+        if self.detect(existing_ctx):
+            ok(f"'{os.path.basename(project_dir)}' already exists and is "
+               f"already a {self.name} project — skipping scaffold.")
+            info(f"Run 'qtmp add <capability> --cwd {project_dir}' to add "
+                 "more to it, it won't be recreated.")
+            return "skip"
+
+        raise RuntimeError(
+            f"'{project_dir}' already exists and isn't empty, and doesn't "
+            f"look like a {self.name} project. Choose a different name or "
+            "remove that folder first."
+        )

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp/recipes/fastapi.py

@@ -72,6 +72,11 @@ class FastAPIRecipe(Recipe):
 
         name = prompt("Project name", default="my-fastapi-app")
         project_dir = os.path.join(ctx.cwd, name)
+
+        status = self.check_existing_target(project_dir)
+        if status == "skip":
+            return None, False
+
         os.makedirs(project_dir, exist_ok=True)
 
         from qtmp.utils import Spinner, run, ok

qtmp-0.3.0/qtmp/recipes/frontend_basic.py

@@ -0,0 +1,123 @@
+"""
+qtmp.recipes.frontend_basic
+------------------------------
+Provides "frontend-basic": a plain HTML + CSS + JS starter, no
+framework, no npm, no network required. This is the recipe to reach
+for when someone doesn't want React/Vite at all — just a page that
+opens directly in a browser.
+"""
+
+import os
+from typing import List
+
+from qtmp.planner import Step
+from qtmp.recipes.base import Recipe
+from qtmp.utils import prompt
+
+
+INDEX_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{title}</title>
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+  <main>
+    <h1>{title}</h1>
+    <p>Edit index.html, style.css, and script.js to get started.</p>
+    <button id="demo-button">Click me</button>
+  </main>
+  <script src="script.js"></script>
+</body>
+</html>
+"""
+
+STYLE_CSS = """* {
+  box-sizing: border-box;
+}
+
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+  margin: 0;
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #0f172a;
+  color: #e2e8f0;
+}
+
+main {
+  text-align: center;
+  padding: 2rem;
+}
+
+button {
+  padding: 0.6rem 1.2rem;
+  font-size: 1rem;
+  border: none;
+  border-radius: 6px;
+  background: #3b82f6;
+  color: white;
+  cursor: pointer;
+}
+
+button:hover {
+  background: #2563eb;
+}
+"""
+
+SCRIPT_JS = """document.getElementById('demo-button').addEventListener('click', () => {
+  alert('script.js is wired up.');
+});
+"""
+
+
+def _write_files(project_dir, title):
+    with open(os.path.join(project_dir, "index.html"), "w") as f:
+        f.write(INDEX_HTML.format(title=title))
+    with open(os.path.join(project_dir, "style.css"), "w") as f:
+        f.write(STYLE_CSS)
+    with open(os.path.join(project_dir, "script.js"), "w") as f:
+        f.write(SCRIPT_JS)
+
+
+class FrontendBasicRecipe(Recipe):
+    name = "Frontend Basics (HTML/CSS/JS)"
+    provides = "frontend-basic"
+    creatable = True
+
+    def detect(self, ctx) -> bool:
+        index = os.path.join(ctx.cwd, "index.html")
+        css = os.path.join(ctx.cwd, "style.css")
+        js = os.path.join(ctx.cwd, "script.js")
+        return os.path.isfile(index) and os.path.isfile(css) and os.path.isfile(js)
+
+    def plan(self, ctx) -> List[Step]:
+        title = os.path.basename(ctx.cwd.rstrip("/")) or "My Site"
+        return [
+            Step(
+                "Write index.html, style.css, script.js",
+                apply_fn=lambda: _write_files(ctx.cwd, title),
+            )
+        ]
+
+    def create(self, ctx, **kwargs):
+        name = prompt("Project name", default="my-site")
+        project_dir = os.path.join(ctx.cwd, name)
+
+        status = self.check_existing_target(project_dir)
+        if status == "skip":
+            return None, False
+
+        os.makedirs(project_dir, exist_ok=True)
+        _write_files(project_dir, name)
+
+        from qtmp.utils import ok
+        ok(f"Frontend basics ready at {project_dir}")
+        info_paths = ", ".join(["index.html", "style.css", "script.js"])
+        from qtmp.utils import info
+        info(f"Files: {info_paths}")
+        return project_dir, False

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp/recipes/react.py

@@ -42,6 +42,12 @@ class ReactRecipe(Recipe):
             raise RuntimeError("npm not found on PATH. Install Node.js first: https://nodejs.org")
 
         name = prompt("Project name", default="my-react-app")
+        project_dir = os.path.join(ctx.cwd, name)
+
+        status = self.check_existing_target(project_dir)
+        if status == "skip":
+            return None, False
+
         level = prompt("Beginner or advanced setup? [b/a]", default="b").strip().lower()
         advanced = level.startswith("a")
         template = "react-ts" if advanced else "react"
@@ -51,7 +57,6 @@ class ReactRecipe(Recipe):
         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)
 

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qtmp
-Version: 0.2.0
+Version: 0.3.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

{qtmp-0.2.0 → qtmp-0.3.0}/qtmp.egg-info/SOURCES.txt

@@ -20,11 +20,14 @@ qtmp/recipes/__init__.py
 qtmp/recipes/base.py
 qtmp/recipes/database.py
 qtmp/recipes/fastapi.py
+qtmp/recipes/frontend_basic.py
 qtmp/recipes/react.py
 qtmp/recipes/router_axios.py
 qtmp/recipes/tailwind.py
 tests/test_cheatsheet_manager.py
+tests/test_cli_helpers.py
 tests/test_context.py
 tests/test_executor.py
+tests/test_existing_target_and_frontend_basic.py
 tests/test_planner.py
 tests/test_recipes.py

{qtmp-0.2.0 → qtmp-0.3.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="qtmp",
-    version="0.2.0",
+    version="0.3.0",
     description=(
         "Qtmp -- Developer Environment Automation CLI. Detects project "
         "environments, resolves dependencies, generates execution plans, "

qtmp-0.3.0/tests/test_cli_helpers.py

@@ -0,0 +1,78 @@
+"""
+Tests for the small pure-function helpers in qtmp.cli that don't need
+a subprocess or a real filesystem: shorthand command expansion and
+--cwd extraction (both/either position).
+"""
+
+from qtmp.cli import expand_shorthand, extract_cwd
+
+
+# ---- expand_shorthand ---------------------------------------------------
+
+def test_known_command_is_left_untouched():
+    assert expand_shorthand(["create", "react"]) == ["create", "react"]
+    assert expand_shorthand(["doctor"]) == ["doctor"]
+
+
+def test_bare_creatable_capability_becomes_create():
+    assert expand_shorthand(["fastapi"]) == ["create", "fastapi"]
+    assert expand_shorthand(["react"]) == ["create", "react"]
+
+
+def test_bare_non_creatable_capability_becomes_add():
+    assert expand_shorthand(["tailwind"]) == ["add", "tailwind"]
+    assert expand_shorthand(["sqlalchemy"]) == ["add", "sqlalchemy"]
+
+
+def test_alias_resolves_before_expanding():
+    # "pg" is an alias for "postgres", which is not creatable -> add.
+    # The original token is preserved (not replaced by the canonical
+    # name) since cmd_add() resolves aliases again downstream anyway.
+    assert expand_shorthand(["pg"]) == ["add", "pg"]
+
+
+def test_unknown_token_is_left_untouched_for_argparse_to_reject():
+    assert expand_shorthand(["not-a-real-thing"]) == ["not-a-real-thing"]
+
+
+def test_trailing_args_are_preserved_after_expansion():
+    assert expand_shorthand(["fastapi", "--cwd", "/tmp/x"]) == \
+        ["create", "fastapi", "--cwd", "/tmp/x"]
+
+
+def test_leading_flags_are_skipped_when_finding_the_command():
+    # A leading flag shouldn't be mistaken for the command itself.
+    assert expand_shorthand(["--cwd", "/tmp/x", "tailwind"]) == \
+        ["--cwd", "/tmp/x", "add", "tailwind"]
+
+
+# ---- extract_cwd ---------------------------------------------------------
+
+def test_extract_cwd_before_subcommand():
+    remaining, value = extract_cwd(["--cwd", "/tmp/x", "create", "react"])
+    assert value == "/tmp/x"
+    assert remaining == ["create", "react"]
+
+
+def test_extract_cwd_after_subcommand():
+    remaining, value = extract_cwd(["create", "react", "--cwd", "/tmp/x"])
+    assert value == "/tmp/x"
+    assert remaining == ["create", "react"]
+
+
+def test_extract_cwd_equals_form():
+    remaining, value = extract_cwd(["create", "react", "--cwd=/tmp/x"])
+    assert value == "/tmp/x"
+    assert remaining == ["create", "react"]
+
+
+def test_extract_cwd_absent_returns_none():
+    remaining, value = extract_cwd(["create", "react"])
+    assert value is None
+    assert remaining == ["create", "react"]
+
+
+def test_extract_cwd_last_occurrence_wins():
+    remaining, value = extract_cwd(["--cwd", "/first", "create", "react", "--cwd", "/second"])
+    assert value == "/second"
+    assert remaining == ["create", "react"]

qtmp-0.3.0/tests/test_existing_target_and_frontend_basic.py

@@ -0,0 +1,91 @@
+"""
+Tests for:
+  - Recipe.check_existing_target(): the shared guard that stops 'create'
+    from blindly re-scaffolding into a folder that already has something
+    in it.
+  - FrontendBasicRecipe: detect()/plan()/create() for the plain
+    HTML/CSS/JS recipe, including that files actually land in the
+    directory passed in (no real subprocess needed for this one).
+"""
+
+import os
+
+from qtmp.context import ProjectContext
+from qtmp.recipes.frontend_basic import FrontendBasicRecipe
+
+
+def test_check_existing_target_clear_when_directory_absent(tmp_path):
+    recipe = FrontendBasicRecipe()
+    target = os.path.join(str(tmp_path), "does-not-exist-yet")
+    assert recipe.check_existing_target(target) == "clear"
+
+
+def test_check_existing_target_clear_when_directory_empty(tmp_path):
+    recipe = FrontendBasicRecipe()
+    empty_dir = tmp_path / "empty"
+    empty_dir.mkdir()
+    assert recipe.check_existing_target(str(empty_dir)) == "clear"
+
+
+def test_check_existing_target_skip_when_already_valid_project(tmp_path):
+    recipe = FrontendBasicRecipe()
+    project_dir = tmp_path / "existing"
+    project_dir.mkdir()
+    (project_dir / "index.html").write_text("<html></html>")
+    (project_dir / "style.css").write_text("body{}")
+    (project_dir / "script.js").write_text("// js")
+
+    assert recipe.check_existing_target(str(project_dir)) == "skip"
+
+
+def test_check_existing_target_raises_on_unrelated_nonempty_folder(tmp_path):
+    recipe = FrontendBasicRecipe()
+    unrelated_dir = tmp_path / "unrelated"
+    unrelated_dir.mkdir()
+    (unrelated_dir / "random.txt").write_text("not a frontend project")
+
+    raised = False
+    try:
+        recipe.check_existing_target(str(unrelated_dir))
+    except RuntimeError:
+        raised = True
+    assert raised, "expected RuntimeError for a non-empty, unrelated folder"
+
+
+def test_frontend_basic_not_detected_in_empty_dir(tmp_path):
+    ctx = ProjectContext.detect(str(tmp_path))
+    assert FrontendBasicRecipe().detect(ctx) is False
+
+
+def test_frontend_basic_detected_after_files_written(tmp_path):
+    (tmp_path / "index.html").write_text("<html></html>")
+    (tmp_path / "style.css").write_text("body{}")
+    (tmp_path / "script.js").write_text("// js")
+
+    ctx = ProjectContext.detect(str(tmp_path))
+    assert FrontendBasicRecipe().detect(ctx) is True
+
+
+def test_frontend_basic_not_detected_if_any_one_file_missing(tmp_path):
+    (tmp_path / "index.html").write_text("<html></html>")
+    (tmp_path / "style.css").write_text("body{}")
+    # script.js deliberately missing
+
+    ctx = ProjectContext.detect(str(tmp_path))
+    assert FrontendBasicRecipe().detect(ctx) is False
+
+
+def test_frontend_basic_plan_writes_files_into_the_given_cwd(tmp_path):
+    ctx = ProjectContext.detect(str(tmp_path))
+    steps = FrontendBasicRecipe().plan(ctx)
+
+    assert len(steps) == 1
+    steps[0].apply_fn()  # simulate the executor running it
+
+    assert (tmp_path / "index.html").is_file()
+    assert (tmp_path / "style.css").is_file()
+    assert (tmp_path / "script.js").is_file()
+
+    html_content = (tmp_path / "index.html").read_text()
+    assert 'href="style.css"' in html_content
+    assert 'src="script.js"' in html_content

qtmp-0.2.0/qtmp/__init__.py

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

qtmp-0.2.0/qtmp/recipes/base.py

@@ -1,62 +0,0 @@
-"""
-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'")