stkit 17.0.0__py3-none-any.whl

stk/cli/doctor.py

@@ -0,0 +1,262 @@
+"""`stk doctor`: the state of this checkout, and the next action for anything wrong.
+
+Answers the questions you would otherwise discover one failed command at a time:
+is the environment configured, is the database migrated, is there an admin, are
+the vendored assets present, is the test-only login accidentally exposed.
+"""
+
+from pathlib import Path
+
+from sqlalchemy import func, select
+
+import stk
+import stk.extensions as ext
+from stk.cli.base import app_spec, cli_app, project_root, run_async
+from stk.migrations import build_alembic_config, sync_url
+
+CORE_STATIC = Path(stk.__file__).parent / "static"
+
+OK = "ok"
+WARN = "warn"
+FAIL = "fail"
+
+
+def _finding(name, status, detail, remedy=None):
+    return {"name": name, "status": status, "detail": detail, "remedy": remedy}
+
+
+def _check_env_file(root):
+    path = root / ".env"
+    if not path.exists():
+        return _finding(
+            "env file",
+            FAIL,
+            ".env is missing",
+            "copy .env-sample to .env, fill secrets",
+        )
+    return _finding("env file", OK, str(path.relative_to(root)))
+
+
+def _check_secrets(config):
+    weak = [
+        name
+        for name in ("SECRET_KEY", "SECURITY_PASSWORD_SALT")
+        if len(str(config.get(name) or "")) < 32
+    ]
+    if weak:
+        return _finding(
+            "secrets",
+            FAIL,
+            f"weak or missing: {', '.join(weak)}",
+            "set 32+ random characters in .env",
+        )
+    return _finding("secrets", OK, "SECRET_KEY and password salt look random")
+
+
+def _check_database(config):
+    url = config["SQLALCHEMY_DATABASE_URI"]
+    if url.startswith("sqlite"):
+        path = Path(url.split("///")[-1])
+        if not path.exists():
+            return _finding(
+                "database", FAIL, f"{path} does not exist", "uv run stk create-db"
+            )
+        size = path.stat().st_size // 1024
+        return _finding("database", OK, f"sqlite {path.name} ({size} KiB)")
+    return _finding("database", OK, url.split("@")[-1])
+
+
+def _as_tuple(value):
+    return () if value is None else (value,) if isinstance(value, str) else value
+
+
+def _applied(script, current):
+    """Every revision the database already has: its heads and their ancestry.
+
+    The version table holds only heads, and an app revision that depends on
+    stk's head stands in for it.
+    """
+    applied, pending = set(), list(current)
+    while pending:
+        revision = script.get_revision(pending.pop())
+        if revision.revision not in applied:
+            applied.add(revision.revision)
+            pending += [
+                *_as_tuple(revision.down_revision),
+                *_as_tuple(revision.dependencies),
+            ]
+    return applied
+
+
+def _defined(script, revision):
+    try:
+        script.get_revision(revision)
+    except Exception:  # alembic raises CommandError for a revision it cannot find
+        return False
+    return True
+
+
+def _check_migrations(app):
+    """Compare the database revisions against the migration heads on disk."""
+    from alembic.runtime.migration import MigrationContext
+    from alembic.script import ScriptDirectory
+    from sqlalchemy import create_engine
+
+    script = ScriptDirectory.from_config(build_alembic_config(app))
+    heads = set(script.get_heads())
+    engine = create_engine(sync_url(app.config["SQLALCHEMY_DATABASE_URI"]))
+    try:
+        with engine.connect() as connection:
+            current = set(MigrationContext.configure(connection).get_current_heads())
+    except Exception as exc:  # unreachable database is its own diagnosis
+        return _finding("migrations", FAIL, str(exc)[:80], "uv run stk db upgrade")
+    finally:
+        engine.dispose()
+
+    shown = ", ".join(sorted(heads))
+    if not current:
+        return _finding(
+            "migrations", FAIL, "database has no revision", "uv run stk db upgrade"
+        )
+    unknown = sorted(rev for rev in current if not _defined(script, rev))
+    if unknown:
+        return _finding(
+            "migrations",
+            FAIL,
+            f"database is stamped at {', '.join(unknown)}, which no migration defines",
+            "uv run stk db stamp heads (after checking the schema matches)",
+        )
+    if missing := sorted(heads - _applied(script, current)):
+        return _finding(
+            "migrations",
+            WARN,
+            f"database is behind: {', '.join(missing)} not applied",
+            "uv run stk db upgrade",
+        )
+    return _finding("migrations", OK, f"at heads ({shown})")
+
+
+def _check_admin():
+    from stk.user.models import Role, User
+
+    async def _count():
+        async with ext.async_session_factory() as session:
+            statement = (
+                select(func.count())
+                .select_from(User)
+                .where(User.roles.any(Role.name == "admin"))
+            )
+            return (await session.execute(statement)).scalar_one()
+
+    try:
+        admins = run_async(_count())
+    except Exception as exc:
+        return _finding("admin user", FAIL, str(exc)[:80], "uv run stk db upgrade")
+    if admins:
+        return _finding("admin user", OK, f"{admins} admin(s)")
+    return _finding("admin user", WARN, "no admin user", "uv run stk install")
+
+
+def _check_assets():
+    versions = CORE_STATIC / "VERSIONS.txt"
+    if not versions.exists():
+        return _finding("assets", WARN, "VERSIONS.txt missing", "./vendor.sh")
+    expected = [
+        CORE_STATIC / name
+        for name in (
+            "js/vue.min.js",
+            "js/vuetify.min.js",
+            "css/vuetify.min.css",
+            "icons/tabler-icons.min.css",
+            "icons/fonts/tabler-icons.woff2",
+        )
+    ]
+    missing = [path.name for path in expected if not path.exists()]
+    if missing:
+        return _finding("assets", FAIL, f"missing: {', '.join(missing)}", "./vendor.sh")
+    pinned = " ".join(versions.read_text().split("\n")[0:2]).strip()
+    return _finding("assets", OK, pinned)
+
+
+def _check_agent_login(config):
+    enabled = config.get("STK_ENABLE_AGENT_LOGIN", False)
+    env = config.get("STK_ENV", "production")
+    if enabled and env != "development":
+        return _finding(
+            "agent login",
+            FAIL,
+            f"test-only login enabled with STK_ENV={env}",
+            "unset STK_ENABLE_AGENT_LOGIN, or set STK_ENV=development",
+        )
+    return _finding(
+        "agent login", OK, "enabled in development only" if enabled else "disabled"
+    )
+
+
+def _check_browser():
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        return _finding(
+            "browser", WARN, "playwright not installed", "uv sync --extra dev"
+        )
+    try:
+        with sync_playwright() as playwright:
+            path = Path(playwright.chromium.executable_path)
+    except Exception:
+        return _finding(
+            "browser",
+            WARN,
+            "chromium not installed",
+            "uv run playwright install chromium",
+        )
+    if not path.exists():
+        return _finding(
+            "browser",
+            WARN,
+            "chromium not installed",
+            "uv run playwright install chromium",
+        )
+    return _finding("browser", OK, "chromium ready for stk smoke")
+
+
+def _check_repl():
+    try:
+        import ptpython  # noqa: F401
+    except ImportError:
+        return _finding(
+            "shell",
+            WARN,
+            "ptpython missing, stk shell falls back to the plain console",
+            "uv sync --extra dev",
+        )
+    return _finding("shell", OK, "ptpython: highlighting and completion")
+
+
+def build_doctor_report():
+    """Return every finding, plus the worst status seen."""
+    findings = [_check_env_file(project_root())]
+    try:
+        app = cli_app()
+    except Exception as exc:  # an app that cannot load is the diagnosis
+        findings.append(
+            _finding("app", FAIL, str(exc)[:120], "read the error, then rerun")
+        )
+        app = None
+    if app is not None:
+        findings += [
+            _finding("app", OK, app_spec()),
+            _check_secrets(app.config),
+            _check_database(app.config),
+            _check_migrations(app),
+            _check_admin(),
+            _check_agent_login(app.config),
+        ]
+    findings += [_check_assets(), _check_browser(), _check_repl()]
+    if any(item["status"] == FAIL for item in findings):
+        status = FAIL
+    elif any(item["status"] == WARN for item in findings):
+        status = WARN
+    else:
+        status = OK
+    return {"status": status, "findings": findings}

stk/cli/main.py

@@ -0,0 +1,101 @@
+"""The `stk` command: one entry point for the whole framework.
+
+Wraps Quart's own CLI group. Every command in `stk/cli/__init__.py` lives on
+this group, so commands that need no app (`stk init`) run anywhere. The app is
+found from `[tool.stk] app` in the nearest pyproject.toml, or from STK_APP, and
+commands it registers (`app.cli.add_command`) appear here too.
+"""
+
+import inspect
+from importlib.metadata import version
+
+import click
+from quart.cli import QuartGroup
+
+import stk.cli as cli
+from stk.cli.base import load_app
+
+SECTIONS = [
+    ("Develop", ["init", "run", "shell", "new", "routes"]),
+    ("Database", ["db", "create-db"]),
+    ("Verify", ["doctor", "verify", "smoke", "inspect", "report"]),
+    (
+        "Accounts",
+        [
+            "install",
+            "create",
+            "add-role",
+            "reset",
+            "cleanup-sessions",
+            "browser-token",
+            "protect-mfa",
+        ],
+    ),
+]
+
+
+class StkGroup(QuartGroup):
+    """Quart's CLI group, listing commands by what they are for."""
+
+    def format_commands(self, ctx, formatter):
+        commands = {}
+        for name in self.list_commands(ctx):
+            command = self.get_command(ctx, name)
+            if command is not None and not command.hidden:
+                commands[name] = command
+
+        for title, names in SECTIONS:
+            rows = [
+                (name, commands.pop(name).get_short_help_str(limit=60))
+                for name in names
+                if name in commands
+            ]
+            if rows:
+                with formatter.section(title):
+                    formatter.write_dl(rows)
+
+        if commands:
+            with formatter.section("Other"):
+                formatter.write_dl(
+                    [
+                        (name, command.get_short_help_str(limit=60))
+                        for name, command in sorted(commands.items())
+                    ]
+                )
+
+
+def _create_app(**_kwargs):
+    return load_app()
+
+
+def _print_version(ctx, _param, value):
+    if not value or ctx.resilient_parsing:
+        return
+    # Apps rename the distribution, so report the framework package's own version.
+    import stk
+
+    click.echo(f"stk {stk.__version__} (quart {version('quart')})")
+    ctx.exit()
+
+
+main = StkGroup(
+    name="stk",
+    create_app=_create_app,
+    add_version_option=False,
+    help="stk: async Quart framework with a Vue frontend and no build step.",
+    params=[
+        click.Option(
+            ["-v", "--version"],
+            is_flag=True,
+            expose_value=False,
+            is_eager=True,
+            callback=_print_version,
+            help="Show the stk version and exit.",
+        )
+    ],
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+for _name, _command in inspect.getmembers(cli):
+    if isinstance(_command, click.Command):
+        main.add_command(_command)

stk/cli/reports.py

@@ -0,0 +1,296 @@
+"""Machine-readable reports behind `stk inspect`, `stk verify`, and `stk report`."""
+
+import html
+import inspect as pyinspect
+import subprocess
+import sys
+from pathlib import Path
+
+from stk.migrations import import_model_modules
+
+VERIFY_COMMANDS = [
+    ("ruff", ["ruff", "check", "."]),
+    ("checks", [sys.executable, "-m", "stk.checks"]),
+    ("migration-drift", [sys.executable, "-m", "stk", "db", "check"]),
+]
+
+# A failing check that does not say how to fix it makes the reader do the work
+# twice. Every check names its remedy, in the report and in the JSON an agent reads.
+REMEDIES = {
+    "ruff": "uv run ruff check --fix . && uv run ruff format .",
+    "checks": "read the failed assertion above; each check names what it expected",
+    "migration-drift": 'uv run stk db revision -m "describe change" && uv run stk db upgrade',
+}
+
+
+def _command_runner(command):
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError:
+        if command[0] == "ruff":
+            return None, "", "ruff not installed"
+        raise
+    return result.returncode, result.stdout, result.stderr
+
+
+def _route_source(view_func):
+    if view_func is None:
+        return None
+    source_file = pyinspect.getsourcefile(view_func)
+    if source_file is None:
+        return None
+    try:
+        _, line = pyinspect.getsourcelines(view_func)
+    except OSError:
+        line = None
+    source = {"file": str(Path(source_file).resolve())}
+    if line is not None:
+        source["line"] = line
+    return source
+
+
+def _guards(func):
+    """Return the quart-security guards wrapping `func`, outermost first.
+
+    ponytail: identifies the guards by the decorator's closure qualname because
+    quart-security exposes no marker. `checks.py` asserts the result against real
+    requests, so a rename upstream fails the gate instead of silently reporting
+    every route as open.
+    """
+    guards = []
+    while func is not None:
+        qualname = getattr(getattr(func, "__code__", None), "co_qualname", "")
+        for guard in ("auth_required", "roles_required"):
+            if qualname.startswith(f"{guard}."):
+                guards.append(guard)
+        func = getattr(func, "__wrapped__", None)
+    return guards
+
+
+def _route_auth(app, rule):
+    """Report whether a route is guarded, and where the guard is declared."""
+    if rule.rule.startswith("/_test/"):
+        return {"required": False, "source": "test-only", "scheme": "agent-token"}
+
+    blueprint = rule.endpoint.rsplit(".", 1)[0] if "." in rule.endpoint else None
+    if _guards(app.view_functions.get(rule.endpoint)):
+        return {"required": True, "source": "route", "scheme": "session"}
+
+    for func in app.before_request_funcs.get(blueprint, []):
+        if _guards(func):
+            return {"required": True, "source": "blueprint", "scheme": "session"}
+
+    return {"required": False, "source": "unguarded", "scheme": "public"}
+
+
+def build_routes_report(app):
+    """Return machine-readable route facts for agents and tooling."""
+    routes = []
+    for rule in sorted(app.url_map.iter_rules(), key=lambda item: item.rule):
+        methods = sorted((rule.methods or set()) - {"HEAD", "OPTIONS"})
+        view_func = app.view_functions.get(rule.endpoint)
+        blueprint = rule.endpoint.rsplit(".", 1)[0] if "." in rule.endpoint else None
+        routes.append(
+            {
+                "rule": rule.rule,
+                "endpoint": rule.endpoint,
+                "blueprint": blueprint,
+                "methods": methods,
+                "arguments": sorted(rule.arguments),
+                "auth": _route_auth(app, rule),
+                "source": _route_source(view_func),
+            }
+        )
+    return routes
+
+
+def build_models_report():
+    """Return model metadata in a compact, agent-readable shape."""
+    from stk.extensions import Base
+
+    import_model_modules()
+    models = {}
+    for table_name, table in sorted(Base.metadata.tables.items()):
+        models[table_name] = {
+            "columns": [
+                {
+                    "name": column.name,
+                    "type": str(column.type),
+                    "nullable": column.nullable,
+                    "primary_key": column.primary_key,
+                }
+                for column in table.columns
+            ],
+            "indexes": sorted(index.name for index in table.indexes if index.name),
+        }
+    return models
+
+
+def build_context_report(app):
+    """Return the project context contract used by agents and tooling."""
+    return {
+        "routes": build_routes_report(app),
+        "models": build_models_report(),
+    }
+
+
+def build_commands_report(root):
+    """Return every stk command, walked from the live click tree under `root`."""
+    import click
+
+    from stk.cli.main import SECTIONS
+
+    section_of = {name: title for title, names in SECTIONS for name in names}
+    commands = []
+
+    def walk(ctx, path):
+        command = ctx.command
+        if isinstance(command, click.Group):
+            for name in command.list_commands(ctx):
+                child = command.get_command(ctx, name)
+                if child is not None and not child.hidden:
+                    walk(
+                        click.Context(child, info_name=name, parent=ctx), [*path, name]
+                    )
+            return
+        help_text = pyinspect.cleandoc(command.help or "").split("\n\n")[0]
+        commands.append(
+            {
+                "command": " ".join(["stk", *path]),
+                "section": section_of.get(path[0], "Other"),
+                "usage": " ".join(["stk", *path, *command.collect_usage_pieces(ctx)]),
+                "help": " ".join(help_text.split()),
+                "options": [
+                    {
+                        "flags": ", ".join(param.opts + param.secondary_opts),
+                        "help": " ".join((param.help or "").split()),
+                    }
+                    for param in command.params
+                    if isinstance(param, click.Option)
+                ],
+            }
+        )
+
+    walk(root, [])
+    order = [title for title, _ in SECTIONS] + ["Other"]
+    return sorted(commands, key=lambda c: (order.index(c["section"]), c["command"]))
+
+
+def render_commands_markdown(commands):
+    """Render the commands report as the docs CLI reference page."""
+    lines = [
+        "---",
+        'title: "CLI Reference"',
+        'description: "Every stk command and option, generated from the code"',
+        "---",
+        "",
+        "Generated from the live command tree by `uv run stk inspect commands --markdown`.",
+        "Do not edit it by hand: `stk verify` fails when this page and the code disagree.",
+        "Agents can read the same data as JSON with `uv run stk inspect commands --json`.",
+    ]
+    section = None
+    for command in commands:
+        if command["section"] != section:
+            section = command["section"]
+            lines += ["", f"## {section}"]
+        lines += ["", f"### `{command['command']}`", "", f"`{command['usage']}`"]
+        if command["help"]:
+            lines += ["", command["help"]]
+        if command["options"]:
+            lines += ["", "| Option | Description |", "|---|---|"]
+            for option in command["options"]:
+                description = option["help"].replace("|", r"\|")
+                lines.append(f"| `{option['flags']}` | {description} |")
+    return "\n".join(lines) + "\n"
+
+
+def build_verify_report(commands=None, runner=_command_runner):
+    """Run verification commands and return a compact report."""
+    checks = []
+    for name, command_args in commands or VERIFY_COMMANDS:
+        returncode, stdout, stderr = runner(command_args)
+        checks.append(
+            {
+                "name": name,
+                "command": command_args,
+                "returncode": returncode,
+                "status": "skipped"
+                if returncode is None
+                else "passed"
+                if returncode == 0
+                else "failed",
+                "stdout": stdout.strip(),
+                "stderr": stderr.strip(),
+                "remedy": REMEDIES.get(name),
+            }
+        )
+    status = (
+        "passed"
+        if all(check["returncode"] in (0, None) for check in checks)
+        else "failed"
+    )
+    return {"status": status, "checks": checks}
+
+
+def build_project_report_html(routes, verify_report):
+    """Render a static project review artifact."""
+    rows = "\n".join(
+        "<tr>"
+        f"<td>{html.escape(route['rule'])}</td>"
+        f"<td>{html.escape(', '.join(route['methods']))}</td>"
+        f"<td>{html.escape(str(route['blueprint']))}</td>"
+        f"<td>{html.escape(route['auth']['scheme'])}</td>"
+        f"<td>{html.escape(route['auth']['source'])}</td>"
+        "</tr>"
+        for route in routes
+    )
+    check_rows = "\n".join(
+        "<tr>"
+        f"<td>{html.escape(check['name'])}</td>"
+        f"<td>{html.escape(check['status'])}</td>"
+        f"<td>{html.escape(' '.join(check['command']))}</td>"
+        "</tr>"
+        for check in verify_report["checks"]
+    )
+    status = html.escape(verify_report["status"])
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>STK Project Report</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 32px; color: #1f2933; }}
+    h1 {{ font-size: 28px; margin-bottom: 8px; }}
+    h2 {{ font-size: 18px; margin-top: 28px; }}
+    table {{ border-collapse: collapse; width: 100%; }}
+    th, td {{ border-bottom: 1px solid #d8dee4; padding: 8px; text-align: left; }}
+    th {{ background: #f6f8fa; }}
+    .status {{ display: inline-block; padding: 4px 8px; border: 1px solid #d8dee4; }}
+  </style>
+</head>
+<body>
+  <h1>STK Project Report</h1>
+  <p>Generated route and verification artifact for reviewing project boundaries.</p>
+  <p>Verification status: <span class="status">{status}</span></p>
+  <h2>Routes</h2>
+  <table>
+    <thead>
+      <tr><th>Route</th><th>Methods</th><th>Blueprint</th><th>Auth</th><th>Source</th></tr>
+    </thead>
+    <tbody>{rows}</tbody>
+  </table>
+  <h2>Verification</h2>
+  <table>
+    <thead>
+      <tr><th>Check</th><th>Status</th><th>Command</th></tr>
+    </thead>
+    <tbody>{check_rows}</tbody>
+  </table>
+</body>
+</html>
+"""