tina4-python 3.11.14__tar.gz → 3.11.16__tar.gz

{tina4_python-3.11.14 → tina4_python-3.11.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina4-python
-Version: 3.11.14
+Version: 3.11.16
 Summary: Tina4 for Python — 54 built-in features, zero dependencies
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.11.14 → tina4_python-3.11.16}/tina4_python/__init__.py

@@ -8,7 +8,7 @@ Tina4 Python v3.0 — Zero-dependency, lightweight web framework.
 
 One import, everything works.
 """
-__version__ = "3.11.14"
+__version__ = "3.11.16"
 
 # ── Route decorators ──
 from tina4_python.core.router import (  # noqa: E402, F401

{tina4_python-3.11.14 → tina4_python-3.11.16}/tina4_python/dev_admin/__init__.py

@@ -348,6 +348,20 @@ def get_api_handlers() -> dict:
         "/__dev/api/deps/search": ("GET", _api_deps_search),
         "/__dev/api/deps/install": ("POST", _api_deps_install),
         "/__dev/api/git/status": ("GET", _api_git_status),
+        # ── MCP REST shim ──
+        # Dev-admin speaks a REST flavour of MCP (plain GET/POST with
+        # JSON bodies) rather than the JSON-RPC SSE protocol used by
+        # Claude Desktop et al. Both surfaces share the same
+        # `_default_server` tool registry, so tools registered via the
+        # @mcp_tool decorator appear in both immediately.
+        "/__dev/api/mcp/tools": ("GET", _api_mcp_tools),
+        "/__dev/api/mcp/call": ("POST", _api_mcp_call),
+        # ── Scaffold REST shim ──
+        # Wraps the tina4python CLI's `generate <kind> <name>` so the
+        # + Route / + Model / + Migration / + Middleware buttons work
+        # without shelling out from the browser.
+        "/__dev/api/scaffold": ("GET", _api_scaffold_list),
+        "/__dev/api/scaffold/run": ("POST", _api_scaffold_run),
     }
 
 
@@ -2056,5 +2070,181 @@ async def _api_git_status(request, response):
     return response(result)
 
 
+# ─── MCP REST shim ─────────────────────────────────────────────────
+#
+# Exposes the framework's MCP tool registry (`_default_server`) over
+# plain GET/POST JSON so the dev-admin browser panel and any other
+# REST client can enumerate and invoke tools without speaking the full
+# JSON-RPC 2.0 over SSE protocol.
+#
+# The JSON-RPC endpoint at `/__dev/mcp/{message,sse}` stays live for
+# proper MCP clients (Claude Desktop et al.) — the two surfaces share
+# the same registry, so tools registered via the `@mcp_tool` decorator
+# show up on both immediately.
+
+async def _api_mcp_tools(request, response):
+    """GET — return the MCP tool registry as a plain JSON list.
+
+    Shape matches what dev-admin's `listMcpTools()` expects:
+        {"tools": [{"name": "...", "description": "...", "schema": {...}}, ...]}
+    """
+    try:
+        from tina4_python.mcp import _get_default_server
+        server = _get_default_server()
+        tools = [
+            {
+                "name": t["name"],
+                "description": t.get("description", ""),
+                "schema": t.get("inputSchema") or {"type": "object", "properties": {}},
+            }
+            for t in server._tools.values()
+        ]
+        return response({"tools": tools})
+    except Exception as exc:
+        return response({"tools": [], "error": str(exc)}, 500)
+
+
+async def _api_mcp_call(request, response):
+    """POST — invoke an MCP tool by name.
+
+    Request:  {"name": "tool_name", "arguments": {...}}
+    Response: {"ok": true, "name": "...", "result": ...}
+           or {"ok": false, "error": "..."}
+
+    The wrapper uses the tool's handler directly rather than routing
+    through `handle_message` — we already know the name and args, no
+    need to round-trip through JSON-RPC framing.
+    """
+    body = request.body or {}
+    if not isinstance(body, dict):
+        return response({"ok": False, "error": "body must be a JSON object"}, 400)
+
+    name = body.get("name")
+    if not name or not isinstance(name, str):
+        return response({"ok": False, "error": "missing 'name'"}, 400)
+
+    args = body.get("arguments") or body.get("args") or {}
+    if not isinstance(args, dict):
+        return response({"ok": False, "error": "'arguments' must be an object"}, 400)
+
+    try:
+        from tina4_python.mcp import _get_default_server
+        server = _get_default_server()
+        tool = server._tools.get(name)
+        if tool is None:
+            return response({"ok": False, "error": f"unknown tool: {name}"}, 404)
+
+        handler = tool["handler"]
+        # Tools are registered as regular functions or coroutines;
+        # await the result when the handler returns an awaitable.
+        import inspect
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**args)
+        else:
+            result = handler(**args)
+
+        return response({"ok": True, "name": name, "result": result})
+    except TypeError as exc:
+        # Bad args shape — surface the Python error cleanly rather
+        # than returning a 500. Callers see "argument X missing" etc.
+        return response({"ok": False, "name": name, "error": f"argument error: {exc}"}, 400)
+    except Exception as exc:
+        return response({"ok": False, "name": name, "error": str(exc)}, 500)
+
+
+# ─── Scaffold REST shim ────────────────────────────────────────────
+#
+# Wraps the tina4python `generate <kind> <name>` CLI commands so the
+# + Route / + Model / + Migration / + Middleware buttons in dev-admin
+# can call them without shelling out from the browser. The handlers
+# import the generator functions directly rather than shelling out —
+# avoids spawning a subprocess per click and surfaces errors as JSON.
+
+_SCAFFOLD_KINDS = [
+    {"kind": "route",      "label": "+ Route",      "needs_name": True},
+    {"kind": "model",      "label": "+ Model",      "needs_name": True},
+    {"kind": "migration",  "label": "+ Migration",  "needs_name": True},
+    {"kind": "middleware", "label": "+ Middleware", "needs_name": True},
+]
+
+
+async def _api_scaffold_list(request, response):
+    """GET — list the scaffold kinds this framework knows how to emit.
+
+    Dev-admin renders one button per item. Each carries a `kind` the
+    /scaffold/run endpoint expects and a human `label` for the UI.
+    """
+    return response({"kinds": _SCAFFOLD_KINDS})
+
+
+async def _api_scaffold_run(request, response):
+    """POST — invoke a generator.
+
+    Request:  {"kind": "route", "name": "contact"}
+    Response: {"ok": true, "files": ["src/routes/contact.py"]}
+           or {"ok": false, "error": "..."}
+
+    Uses tina4_python.cli's module-level generator functions rather
+    than shelling out via subprocess — faster, no path/env lookup.
+    """
+    body = request.body or {}
+    if not isinstance(body, dict):
+        return response({"ok": False, "error": "body must be a JSON object"}, 400)
+
+    kind = (body.get("kind") or "").strip().lower()
+    name = (body.get("name") or "").strip()
+    if not kind:
+        return response({"ok": False, "error": "missing 'kind'"}, 400)
+    if not name and kind != "auth":
+        return response({"ok": False, "error": "missing 'name'"}, 400)
+
+    # Guard against path traversal / shell-metacharacter injection in
+    # the name — generator functions pass it into file paths.
+    import re
+    if not re.match(r"^[A-Za-z][A-Za-z0-9_\-]*$", name):
+        return response({"ok": False, "error": "name must match [A-Za-z][A-Za-z0-9_-]*"}, 400)
+
+    generator_map = {
+        "route":      "generate_route",
+        "model":      "generate_model",
+        "migration":  "generate_migration",
+        "middleware": "generate_middleware",
+    }
+    fn_name = generator_map.get(kind)
+    if fn_name is None:
+        return response({"ok": False, "error": f"unknown scaffold kind: {kind}"}, 400)
+
+    try:
+        from tina4_python import cli as cli_module
+        fn = getattr(cli_module, fn_name, None)
+        if fn is None:
+            # Fall back to shelling out — keeps the endpoint useful
+            # even if the generator function names drift.
+            import subprocess
+            cp = subprocess.run(
+                ["tina4python", "generate", kind, name],
+                capture_output=True, text=True, timeout=30,
+            )
+            if cp.returncode != 0:
+                return response({"ok": False, "error": cp.stderr.strip() or cp.stdout.strip()}, 500)
+            return response({"ok": True, "output": cp.stdout.strip()})
+
+        # Invoke the generator directly. The CLI functions typically
+        # print to stdout + write files; we don't capture their
+        # output here — the file tree will refresh and show the new
+        # files, which is what the user actually cares about.
+        result = fn(name) if fn.__code__.co_argcount == 1 else fn(name, None)
+
+        # Most generators return a path or list of paths; normalise.
+        files: list[str] = []
+        if isinstance(result, str):
+            files = [result]
+        elif isinstance(result, list):
+            files = [str(p) for p in result]
+        return response({"ok": True, "kind": kind, "name": name, "files": files})
+    except Exception as exc:
+        return response({"ok": False, "error": str(exc)}, 500)
+
+
 __all__ = ["MessageLog", "RequestInspector", "BrokenTracker",
            "get_api_handlers", "render_dev_toolbar"]

tina4_python-3.11.16/tina4_python/dev_admin/plan.py

@@ -0,0 +1,454 @@
+"""Project plan management — persistent, human-readable task state.
+
+A "plan" is a markdown file under ``plan/`` at the project root with a
+lightweight structure the AI (and the human) can both read and edit:
+
+    # Add user authentication
+
+    Goal: JWT login/registration with refresh tokens.
+
+    ## Steps
+
+    - [x] Create User model in src/orm/User.py
+    - [x] Add auth middleware in src/app/middleware.py
+    - [ ] Add /api/login route
+    - [ ] Add /api/register route
+
+    ## Notes
+
+    Use tina4_python.auth.get_token, 60-minute tokens.
+
+At any moment exactly one plan is "current" — recorded by the filename
+stored in ``plan/.current``. That plan's contents are injected into
+every chat turn's system prompt so the AI keeps working on the same
+thing across conversations, and the step list gives a clear "done /
+not done" snapshot.
+
+This module is the storage + manipulation layer. MCP tools in
+``tina4_python.mcp.tools`` expose it to the AI; the dev-admin UI surfaces
+it to the human.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from pathlib import Path
+
+PLAN_DIR = "plan"
+CURRENT_FILE = ".current"
+ARCHIVE_SUBDIR = "done"
+
+
+def _project_root() -> Path:
+    return Path(os.getcwd()).resolve()
+
+
+def _plan_dir() -> Path:
+    p = _project_root() / PLAN_DIR
+    p.mkdir(exist_ok=True)
+    return p
+
+
+def _current_pointer() -> Path:
+    return _plan_dir() / CURRENT_FILE
+
+
+def _archive_dir() -> Path:
+    p = _plan_dir() / ARCHIVE_SUBDIR
+    p.mkdir(exist_ok=True)
+    return p
+
+
+def _slugify(title: str) -> str:
+    """File-system-safe filename stem for a plan title."""
+    slug = re.sub(r"[^A-Za-z0-9_-]+", "-", title.strip().lower()).strip("-")
+    return slug[:80] or f"plan-{int(time.time())}"
+
+
+# ── Plan file shape ──────────────────────────────────────────────────
+
+_STEP_RE = re.compile(r"^\s*[-*]\s*\[(?P<box>[ xX])\]\s*(?P<text>.+?)\s*$")
+
+
+def _parse(text: str) -> dict:
+    """Parse a plan markdown file into a structured dict.
+
+    The parser is tolerant — missing sections are fine; unknown sections
+    are preserved verbatim under ``extra``. We only pick apart what we
+    need to manipulate programmatically (title, goal, steps).
+    """
+    lines = text.splitlines()
+    title = ""
+    goal = ""
+    steps: list = []
+    notes_lines: list = []
+    section = None  # None | "steps" | "notes"
+
+    for raw in lines:
+        line = raw.rstrip()
+        if not title and line.startswith("# "):
+            title = line[2:].strip()
+            continue
+        low = line.strip().lower()
+        if low.startswith("goal:") and not goal:
+            goal = line.split(":", 1)[1].strip()
+            continue
+        if low == "## steps":
+            section = "steps"
+            continue
+        if low == "## notes":
+            section = "notes"
+            continue
+        if line.startswith("## "):
+            section = "other"
+            continue
+        if section == "steps":
+            m = _STEP_RE.match(line)
+            if m:
+                steps.append({
+                    "text": m.group("text").strip(),
+                    "done": m.group("box").lower() == "x",
+                })
+        elif section == "notes" and line.strip():
+            notes_lines.append(line)
+
+    return {
+        "title": title,
+        "goal": goal,
+        "steps": steps,
+        "notes": "\n".join(notes_lines).strip(),
+    }
+
+
+def _render(plan: dict) -> str:
+    """Serialise a parsed dict back to canonical markdown."""
+    parts: list = [f"# {plan.get('title', 'Untitled plan')}", ""]
+    goal = plan.get("goal")
+    if goal:
+        parts += [f"Goal: {goal}", ""]
+    parts.append("## Steps")
+    parts.append("")
+    for step in plan.get("steps", []):
+        box = "x" if step.get("done") else " "
+        parts.append(f"- [{box}] {step.get('text', '').strip()}")
+    notes = (plan.get("notes") or "").strip()
+    if notes:
+        parts += ["", "## Notes", "", notes]
+    return "\n".join(parts) + "\n"
+
+
+# ── Public API ───────────────────────────────────────────────────────
+
+
+def list_plans() -> list:
+    """All plan files at the root of plan/ (excludes done/)."""
+    d = _plan_dir()
+    current = current_name() or ""
+    out: list = []
+    for p in sorted(d.glob("*.md")):
+        parsed = _parse(p.read_text(encoding="utf-8", errors="replace"))
+        total = len(parsed["steps"])
+        done = sum(1 for s in parsed["steps"] if s["done"])
+        out.append({
+            "name": p.name,
+            "title": parsed["title"] or p.stem,
+            "steps_total": total,
+            "steps_done": done,
+            "is_current": p.name == current,
+        })
+    return out
+
+
+def current_name() -> str:
+    """Filename of the current plan, or '' when none is set."""
+    ptr = _current_pointer()
+    if not ptr.exists():
+        return ""
+    return ptr.read_text(encoding="utf-8").strip()
+
+
+def set_current(name: str) -> dict:
+    """Point .current at the given plan file. Creates plan/ if needed."""
+    name = name.strip()
+    if not name.endswith(".md"):
+        name += ".md"
+    plan_path = _plan_dir() / name
+    if not plan_path.exists():
+        return {"ok": False, "error": f"No such plan: {name}"}
+    _current_pointer().write_text(name, encoding="utf-8")
+    return {"ok": True, "current": name}
+
+
+def clear_current() -> dict:
+    """Unset the current plan (e.g. when everything's done and nothing's queued)."""
+    p = _current_pointer()
+    if p.exists():
+        p.unlink()
+    return {"ok": True}
+
+
+def current() -> dict:
+    """The whole current plan: title, goal, steps (with index + done), notes,
+    and a cheap 'next' pointer to the first unchecked step. Returns
+    {current: null} when no plan is active — the AI treats that as
+    'no specific plan, proceed normally'."""
+    name = current_name()
+    if not name:
+        return {"current": None}
+    path = _plan_dir() / name
+    if not path.exists():
+        # Pointer is dangling — clean up, report.
+        clear_current()
+        return {"current": None, "warning": f"Current pointer referenced missing file: {name}"}
+    parsed = _parse(path.read_text(encoding="utf-8", errors="replace"))
+    indexed_steps = [
+        {"index": i, "text": s["text"], "done": s["done"]}
+        for i, s in enumerate(parsed["steps"])
+    ]
+    next_step = next((s for s in indexed_steps if not s["done"]), None)
+    return {
+        "current": name,
+        "title": parsed["title"],
+        "goal": parsed["goal"],
+        "steps": indexed_steps,
+        "next_step": next_step,
+        "notes": parsed["notes"],
+        "progress": {
+            "done": sum(1 for s in indexed_steps if s["done"]),
+            "total": len(indexed_steps),
+        },
+        # Attach the execution summary so callers get the full picture
+        # in one call — no second round-trip needed just to find out
+        # which files this plan has already touched.
+        "execution": summarise_execution(name),
+    }
+
+
+def read(name: str) -> dict:
+    """Full structured view of any plan by filename."""
+    if not name.endswith(".md"):
+        name += ".md"
+    path = _plan_dir() / name
+    if not path.exists():
+        return {"error": f"No such plan: {name}"}
+    return _parse(path.read_text(encoding="utf-8", errors="replace")) | {"name": name}
+
+
+def create(title: str, goal: str = "", steps: list | None = None, make_current: bool = True) -> dict:
+    """Write a new plan file and (by default) make it the active one.
+    ``steps`` is a list of strings — all start unchecked."""
+    title = (title or "").strip()
+    if not title:
+        return {"ok": False, "error": "title is required"}
+    stem = _slugify(title)
+    name = f"{stem}.md"
+    path = _plan_dir() / name
+    if path.exists():
+        return {"ok": False, "error": f"Plan already exists: {name}. Pick a different title or edit the existing one."}
+    plan = {
+        "title": title,
+        "goal": goal.strip(),
+        "steps": [{"text": s.strip(), "done": False} for s in (steps or []) if s.strip()],
+        "notes": "",
+    }
+    path.write_text(_render(plan), encoding="utf-8")
+    if make_current:
+        _current_pointer().write_text(name, encoding="utf-8")
+    return {"ok": True, "name": name, "title": title, "is_current": make_current}
+
+
+def _load_parsed(name: str) -> tuple[Path, dict]:
+    if not name.endswith(".md"):
+        name += ".md"
+    path = _plan_dir() / name
+    if not path.exists():
+        raise FileNotFoundError(f"No such plan: {name}")
+    return path, _parse(path.read_text(encoding="utf-8", errors="replace"))
+
+
+def complete_step(index: int, name: str = "") -> dict:
+    """Tick a step (by 0-based index) on the current plan (or a named one).
+    Returns the updated plan summary + what's next."""
+    name = name or current_name()
+    if not name:
+        return {"ok": False, "error": "No current plan and no name given"}
+    try:
+        path, plan = _load_parsed(name)
+    except FileNotFoundError as e:
+        return {"ok": False, "error": str(e)}
+    if not 0 <= index < len(plan["steps"]):
+        return {"ok": False, "error": f"Step index {index} out of range (0..{len(plan['steps']) - 1})"}
+    plan["steps"][index]["done"] = True
+    path.write_text(_render(plan), encoding="utf-8")
+    remaining = [i for i, s in enumerate(plan["steps"]) if not s["done"]]
+    return {
+        "ok": True,
+        "completed": plan["steps"][index]["text"],
+        "remaining": len(remaining),
+        "next_step": plan["steps"][remaining[0]]["text"] if remaining else None,
+    }
+
+
+def uncomplete_step(index: int, name: str = "") -> dict:
+    """Uncheck a step — useful when a change turns out to have regressed."""
+    name = name or current_name()
+    if not name:
+        return {"ok": False, "error": "No current plan and no name given"}
+    try:
+        path, plan = _load_parsed(name)
+    except FileNotFoundError as e:
+        return {"ok": False, "error": str(e)}
+    if not 0 <= index < len(plan["steps"]):
+        return {"ok": False, "error": f"Step index {index} out of range"}
+    plan["steps"][index]["done"] = False
+    path.write_text(_render(plan), encoding="utf-8")
+    return {"ok": True, "step": plan["steps"][index]["text"]}
+
+
+def add_step(text: str, name: str = "") -> dict:
+    """Append a new unchecked step."""
+    text = (text or "").strip()
+    if not text:
+        return {"ok": False, "error": "text is required"}
+    name = name or current_name()
+    if not name:
+        return {"ok": False, "error": "No current plan and no name given"}
+    try:
+        path, plan = _load_parsed(name)
+    except FileNotFoundError as e:
+        return {"ok": False, "error": str(e)}
+    plan["steps"].append({"text": text, "done": False})
+    path.write_text(_render(plan), encoding="utf-8")
+    return {"ok": True, "step": text, "index": len(plan["steps"]) - 1}
+
+
+def append_note(text: str, name: str = "") -> dict:
+    """Add a line to the plan's Notes section — great for 'here's a
+    gotcha I hit' breadcrumbs the AI drops as it works."""
+    text = (text or "").strip()
+    if not text:
+        return {"ok": False, "error": "text is required"}
+    name = name or current_name()
+    if not name:
+        return {"ok": False, "error": "No current plan and no name given"}
+    try:
+        path, plan = _load_parsed(name)
+    except FileNotFoundError as e:
+        return {"ok": False, "error": str(e)}
+    existing = (plan.get("notes") or "").strip()
+    stamp = time.strftime("%Y-%m-%d %H:%M")
+    plan["notes"] = (existing + f"\n- [{stamp}] {text}").strip()
+    path.write_text(_render(plan), encoding="utf-8")
+    return {"ok": True, "appended": text}
+
+
+# ── Execution ledger — "what has this plan touched so far?" ──────────
+#
+# Every file_write / file_patch / migration_create that lands while a
+# plan is current gets recorded here. The AI reads the *summary* at the
+# top of each chat turn (via `summarise_execution()`) so it doesn't
+# re-create files it already made — that's the "two migrations for the
+# same table" bug we saw.
+#
+# Stored next to the plan file as `<plan-stem>.log.json` to keep all
+# plan state in one place. Not committed (plan/.gitignore covers it).
+
+
+def _ledger_path(name: str = "") -> Path | None:
+    name = name or current_name()
+    if not name:
+        return None
+    if not name.endswith(".md"):
+        name += ".md"
+    return _plan_dir() / f"{name[:-3]}.log.json"
+
+
+def record_action(action: str, path: str, note: str = "") -> None:
+    """Append an entry to the current plan's ledger. Silently no-ops
+    when no plan is active — tools call this unconditionally."""
+    lp = _ledger_path()
+    if lp is None:
+        return
+    entries: list = []
+    if lp.exists():
+        try:
+            entries = json.loads(lp.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            entries = []
+    entries.append({
+        "t": int(time.time()),
+        "action": action,     # "created" | "patched" | "migration"
+        "path": path,
+        "note": note,
+    })
+    # Bound the log so it can't grow forever on long-running plans.
+    if len(entries) > 500:
+        entries = entries[-500:]
+    try:
+        lp.write_text(json.dumps(entries, indent=2), encoding="utf-8")
+    except OSError:
+        pass  # ledger is best-effort
+
+
+def summarise_execution(name: str = "") -> dict:
+    """Grouped view of what the current plan has touched — small
+    enough to inline into every system prompt. Groups:
+      - `created`: files written for the first time
+      - `patched`: files edited
+      - `migrations`: migration files generated
+    Each bucket is de-duped and capped at 20 paths."""
+    lp = _ledger_path(name)
+    if lp is None or not lp.exists():
+        return {"created": [], "patched": [], "migrations": [], "total": 0}
+    try:
+        entries = json.loads(lp.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"created": [], "patched": [], "migrations": [], "total": 0}
+
+    created: list[str] = []
+    patched: list[str] = []
+    migrations: list[str] = []
+    for e in entries:
+        action = e.get("action")
+        path = e.get("path")
+        if not path:
+            continue
+        bucket = (
+            migrations if action == "migration"
+            else created if action == "created"
+            else patched if action == "patched"
+            else None
+        )
+        if bucket is not None and path not in bucket:
+            bucket.append(path)
+    return {
+        "created": created[-20:],
+        "patched": patched[-20:],
+        "migrations": migrations[-20:],
+        "total": len(entries),
+    }
+
+
+def archive(name: str = "") -> dict:
+    """Move a plan to plan/done/ and clear the current pointer if it
+    was pointing at this plan. A no-op + warning if it's already
+    archived."""
+    name = name or current_name()
+    if not name:
+        return {"ok": False, "error": "No current plan and no name given"}
+    if not name.endswith(".md"):
+        name += ".md"
+    src = _plan_dir() / name
+    if not src.exists():
+        return {"ok": False, "error": f"No such plan: {name}"}
+    dest = _archive_dir() / name
+    # Handle name collisions — prefix with timestamp on conflict
+    if dest.exists():
+        dest = _archive_dir() / f"{int(time.time())}-{name}"
+    src.rename(dest)
+    if current_name() == name:
+        clear_current()
+    return {"ok": True, "archived_to": str(dest.relative_to(_project_root()))}