stkit 17.0.0__py3-none-any.whl

stk/cli/agent.py

@@ -0,0 +1,267 @@
+"""Agent-facing commands: inspect, verify, smoke, report, shell, scaffold."""
+
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import click
+
+from stk.cli.base import cli_app, console
+from stk.cli.reports import (
+    build_commands_report,
+    build_context_report,
+    build_project_report_html,
+    build_routes_report,
+    build_verify_report,
+    render_commands_markdown,
+)
+from stk.cli.smoke import print_smoke_report, run_smoke, smoke_exit_code
+
+
+@click.group(name="inspect")
+def inspect_cmd():
+    """Inspect app structure for agents and tooling."""
+
+
+@inspect_cmd.command("routes")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+def inspect_routes(as_json):
+    """Inspect registered routes."""
+    report = build_routes_report(cli_app())
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+        return
+
+    for route in report:
+        methods = ",".join(route["methods"])
+        click.echo(f"{methods:12} {route['rule']} -> {route['endpoint']}")
+
+
+@inspect_cmd.command("context")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+def inspect_context(as_json):
+    """Inspect routes and models as one agent-readable contract."""
+    report = build_context_report(cli_app())
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+        return
+
+    click.echo(
+        f"Context: {len(report['routes'])} routes, {len(report['models'])} models"
+    )
+
+
+@inspect_cmd.command("commands")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+@click.option("--markdown", is_flag=True, help="Emit the docs CLI reference page.")
+def inspect_commands(as_json, markdown):
+    """Inspect every stk command and its options."""
+    report = build_commands_report(click.get_current_context().find_root())
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+    elif markdown:
+        click.echo(render_commands_markdown(report), nl=False)
+    else:
+        for command in report:
+            click.echo(f"{command['usage']:48} {command['help']}")
+
+
+@click.command()
+@click.option("-c", "--command", "source", default=None, help="Run code and exit.")
+def shell(source):
+    """Async REPL with the app, a live DB session, and all models loaded."""
+    from stk.shell import run_shell
+
+    run_shell(cli_app(), source)
+
+
+MARKERS = {"passed": "[green]✓[/]", "failed": "[red]✗[/]", "skipped": "[yellow]-[/]"}
+
+
+def _print_verify_report(report, detail_lines=5):
+    for check in report["checks"]:
+        console.print(f"{MARKERS[check['status']]} {check['name']}", highlight=False)
+        if check["status"] != "failed":
+            continue
+        output = check["stdout"].strip() or check["stderr"].strip()
+        for line in output.splitlines()[-detail_lines:]:
+            console.print(f"    [dim]{line}[/]", highlight=False)
+        if check["remedy"]:
+            console.print(f"    [cyan]→ {check['remedy']}[/]", highlight=False)
+
+
+@click.command()
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+@click.option(
+    "-w", "--watch", is_flag=True, help="Re-run affected checks on every file save."
+)
+def verify(as_json, watch):
+    """Run STK verification checks."""
+    if watch:
+        _watch_and_verify()
+        return
+
+    report = build_verify_report()
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+        raise click.exceptions.Exit(0 if report["status"] == "passed" else 1)
+
+    _print_verify_report(report)
+    raise click.exceptions.Exit(0 if report["status"] == "passed" else 1)
+
+
+def _watch_and_verify(interval=0.5):
+    """Verify now, then re-verify whatever the next edit could have broken."""
+    from stk.cli import watch as watcher
+    from stk.cli.reports import VERIFY_COMMANDS
+
+    root = Path.cwd()
+    console.print("[bold]stk verify --watch[/] [dim]ctrl-c to stop[/]\n")
+    _print_verify_report(build_verify_report())
+    seen = watcher.scan(root)
+
+    while True:
+        time.sleep(interval)
+        current = watcher.scan(root)
+        touched = watcher.changed(seen, current)
+        seen = current
+        if not touched:
+            continue
+
+        names = watcher.checks_for(touched)
+        if not names:
+            continue
+        shown = ", ".join(
+            str(path.relative_to(root)) if path.is_relative_to(root) else str(path)
+            for path in touched[:3]
+        )
+        extra = f" +{len(touched) - 3}" if len(touched) > 3 else ""
+        console.print(f"\n[dim]changed:[/] {shown}{extra}")
+        commands = [item for item in VERIFY_COMMANDS if item[0] in names]
+        _print_verify_report(build_verify_report(commands))
+
+
+@click.command()
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+def smoke(as_json):
+    """Run a real-browser smoke check against a temporary development app."""
+    report = run_smoke()
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+    else:
+        print_smoke_report(report)
+    raise click.exceptions.Exit(smoke_exit_code(report))
+
+
+# Named `doctor_cmd` because `stk.cli.doctor` is the module that backs it, and
+# importing a submodule rebinds that attribute on the package.
+@click.command("doctor")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+def doctor_cmd(as_json):
+    """Report the state of this checkout, and what to run for anything wrong."""
+    from stk.cli.doctor import build_doctor_report
+
+    report = build_doctor_report()
+    if as_json:
+        click.echo(json.dumps(report, indent=2))
+        raise click.exceptions.Exit(0 if report["status"] != "fail" else 1)
+
+    marks = {"ok": "[green]✓[/]", "warn": "[yellow]![/]", "fail": "[red]✗[/]"}
+    for finding in report["findings"]:
+        console.print(
+            f"{marks[finding['status']]} [bold]{finding['name']:14}[/] {finding['detail']}",
+            highlight=False,
+        )
+        if finding["remedy"]:
+            console.print(f"    [cyan]→ {finding['remedy']}[/]", highlight=False)
+
+    summary = {
+        "ok": "[green]Everything is ready.[/]",
+        "warn": "[yellow]Usable, with the warnings above.[/]",
+        "fail": "[red]Fix the failures above before building.[/]",
+    }
+    console.print(f"\n{summary[report['status']]}")
+    raise click.exceptions.Exit(0 if report["status"] != "fail" else 1)
+
+
+@click.command()
+@click.option(
+    "-o",
+    "--output",
+    default="docs/stk-report.html",
+    help="HTML output path.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON.")
+def report(output, as_json):
+    """Generate a static project report."""
+    routes = build_routes_report(cli_app())
+    verify_report = build_verify_report()
+    report_data = {"routes": routes, "verification": verify_report}
+    if as_json:
+        click.echo(json.dumps(report_data, indent=2))
+        return
+
+    html_report = build_project_report_html(routes, verify_report)
+    output_path = Path(output)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(html_report)
+    console.print(f"[green]Project report written:[/] {output_path}")
+
+
+def _run_stk(args):
+    result = subprocess.run([sys.executable, "-m", "stk", *args], check=False)
+    if result.returncode != 0:
+        raise click.ClickException(f"stk {' '.join(args)} failed")
+
+
+@click.command("new")
+@click.argument("name")
+@click.option(
+    "--migrate/--no-migrate",
+    default=True,
+    help="Autogenerate and apply the migration for the new model.",
+)
+@click.option("--port", default=5000, show_default=True, help="Port used in the URL.")
+def new_module(name, migrate, port):
+    """Scaffold a new extension module in the app, ending at a page you can open.
+
+    NAME is a singular lowercase snake_case identifier (e.g. blog_post); the
+    page and API use its plural (/blog_posts/).
+    Writes the module package and adds it to the app's extension list.
+    """
+    from stk.migrations import app_label
+    from stk.scaffold.generator import generate_module
+    from stk.scaffold.templates import plural
+
+    app = cli_app()
+    try:
+        actions = generate_module(name, app)
+    except (ValueError, FileExistsError, RuntimeError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    console.print(f"\n[green]Scaffolded module:[/] [bold]{name}[/]")
+    for action in actions:
+        console.print(f"  [blue]+[/] {action}")
+
+    if migrate:
+        # The app object predates the module; a fresh process imports it.
+        # Autogenerate compares against a database at its heads.
+        _run_stk(["db", "upgrade"])
+        _run_stk(["db", "revision", "-m", f"add {name}"])
+        _run_stk(["db", "upgrade"])
+        console.print(f"  [blue]+[/] migration generated and applied for {name}")
+
+    url = f"http://localhost:{port}/{plural(name)}/"
+    console.print(f"\n[green]Open:[/] [bold]{url}[/]  [dim](start it with: stk run)[/]")
+    console.print(
+        f"""[dim]Then:[/]
+  Shape the domain in [bold]{app_label(app)}/{name}/models.py[/]{
+            ', and re-run `stk db revision -m "..." && stk db upgrade`'
+            if migrate
+            else ', then `stk db revision -m "add ' + name + '"` and `stk db upgrade`'
+        }
+  Keep it honest with [bold]stk verify --watch[/] while you edit
+"""
+    )

stk/cli/base.py

@@ -0,0 +1,79 @@
+"""Shared CLI plumbing: finding the app, console output, the sync/async bridge."""
+
+import asyncio
+import importlib
+import os
+import sys
+import tomllib
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+import stk.extensions as ext
+
+console = Console()
+
+
+def project_root() -> Path:
+    """The directory of the nearest pyproject.toml, from the working directory up."""
+    cwd = Path.cwd()
+    for directory in (cwd, *cwd.parents):
+        if (directory / "pyproject.toml").is_file():
+            return directory
+    raise click.ClickException("no pyproject.toml here or above: cd into an app")
+
+
+def _tool_stk() -> dict:
+    pyproject = project_root() / "pyproject.toml"
+    return tomllib.loads(pyproject.read_text()).get("tool", {}).get("stk", {})
+
+
+def app_spec() -> str:
+    """The app as `module:attribute`, from STK_APP or `[tool.stk] app`."""
+    if spec := os.environ.get("STK_APP"):
+        return spec
+    if spec := _tool_stk().get("app"):
+        return spec
+    raise click.ClickException(
+        f'{project_root() / "pyproject.toml"} has no [tool.stk] app = "package.app:app".'
+        " Start one with: uv run stk init <name>"
+    )
+
+
+def app_root() -> Path:
+    """The directory the app's package is imported from.
+
+    The project, unless `[tool.stk] path` names another: stk's own repository
+    runs its bundled example that way.
+    """
+    path = None if os.environ.get("STK_APP") else _tool_stk().get("path")
+    return project_root() / path if path else project_root()
+
+
+def load_app():
+    """Import and return the app named by `app_spec()`."""
+    module_name, _, attribute = app_spec().partition(":")
+    # The project need not be installed: import it from its own directory.
+    sys.path.insert(0, str(app_root()))
+    return getattr(importlib.import_module(module_name), attribute or "app")
+
+
+def cli_app():
+    """The app for this CLI invocation, loaded once."""
+    from quart.cli import ScriptInfo
+
+    return click.get_current_context().ensure_object(ScriptInfo).load_app()
+
+
+def run_async(coro):
+    """Run an async function in sync context (for CLI commands)."""
+
+    async def _wrapper():
+        try:
+            return await coro
+        finally:
+            if ext.engine:
+                await ext.engine.dispose()
+
+    return asyncio.run(_wrapper())

stk/cli/database.py

@@ -0,0 +1,199 @@
+"""Database and migration commands."""
+
+import click
+from alembic import command
+
+from stk.cli.base import cli_app, console
+from stk.migrations import (
+    CORE_LABEL,
+    app_label,
+    app_versions,
+    build_alembic_config,
+    get_target_metadata,
+    throwaway_database_url,
+)
+
+
+def run_alembic(action, *args, **kwargs):
+    """Run an alembic command, reporting its complaint instead of a traceback."""
+    from alembic.util.exc import CommandError
+
+    try:
+        return action(*args, **kwargs)
+    except CommandError as exc:
+        raise click.ClickException(f"{exc}\nrun: uv run stk doctor") from exc
+
+
+def _flatten(diffs):
+    for diff in diffs:
+        if isinstance(diff, list):
+            yield from diff
+        else:
+            yield diff
+
+
+def _describe_diff(diff):
+    """Render an autogenerate diff tuple as one readable line."""
+    parts = []
+    for element in diff[1:]:
+        if element is None or isinstance(element, dict):  # schema, autogenerate opts
+            continue
+        parts.append(str(getattr(element, "name", element)))
+    return f"{diff[0]}: {' '.join(parts)}".strip()
+
+
+def build_migration_drift_report(app=None, database_url=None):
+    """Return differences between the migrations at their heads and the models.
+
+    Migrations run against a throwaway database of the app's dialect, so the
+    answer does not depend on the state of any developer machine. With no app,
+    stk's own lineage is checked against its own models.
+    """
+    from alembic.autogenerate import compare_metadata
+    from alembic.runtime.migration import MigrationContext
+    from sqlalchemy import create_engine
+
+    from stk.migrations import include_object
+
+    if database_url is None:
+        database_url = app.config["SQLALCHEMY_DATABASE_URI"]
+    with throwaway_database_url(database_url, sync=True) as url:
+        config = build_alembic_config(app, url, quiet=True)
+        command.upgrade(config, "heads")
+
+        engine = create_engine(url)
+        try:
+            with engine.connect() as connection:
+                context = MigrationContext.configure(
+                    connection,
+                    opts={
+                        "compare_type": True,
+                        "compare_server_default": True,
+                        "include_object": include_object,
+                    },
+                )
+                diffs = compare_metadata(context, get_target_metadata())
+        finally:
+            engine.dispose()
+
+    return [_describe_diff(diff) for diff in _flatten(diffs)]
+
+
+def generate_revision(app, message, *, autogenerate=True, head=None, quiet=False):
+    """Write a revision in the app's lineage, or in `head`'s when given.
+
+    The app's first revision starts its branch. Every app revision depends on
+    stk's head at the time it is written, so core tables (`user`) exist first.
+    """
+    from alembic.script import ScriptDirectory
+
+    config = build_alembic_config(app, quiet=quiet)
+    if head is not None:
+        return run_alembic(
+            command.revision,
+            config,
+            message=message,
+            autogenerate=autogenerate,
+            head=head,
+        )
+    script = ScriptDirectory.from_config(config)
+    label = app_label(app)
+    started = any(label in rev.branch_labels for rev in script.walk_revisions())
+    core_head = script.get_revision(f"{CORE_LABEL}@head").revision
+    options = (
+        {"head": f"{label}@head"}
+        if started
+        else {
+            "head": "base",
+            "branch_label": label,
+            "version_path": str(app_versions(app)),
+        }
+    )
+    app_versions(app).mkdir(exist_ok=True)
+    return run_alembic(
+        command.revision,
+        config,
+        message=message,
+        autogenerate=autogenerate,
+        depends_on=core_head,
+        **options,
+    )
+
+
+@click.command()
+def create_db():
+    """Apply all database migrations (same as `stk db upgrade`)."""
+    run_alembic(command.upgrade, build_alembic_config(cli_app()), "heads")
+    console.print("[green]Database migrations applied successfully[/]")
+
+
+@click.group()
+def db():
+    """Alembic-backed database migration commands."""
+
+
+@db.command("upgrade")
+@click.argument("revision", default="heads")
+def db_upgrade(revision):
+    """Upgrade the database: stk's migrations and the app's, to their heads."""
+    run_alembic(command.upgrade, build_alembic_config(cli_app()), revision)
+
+
+# Relative targets like "-1" look like options to click; accept them as the argument.
+@db.command("downgrade", context_settings={"ignore_unknown_options": True})
+@click.argument("revision")
+def db_downgrade(revision):
+    """Downgrade the database to a target revision."""
+    run_alembic(command.downgrade, build_alembic_config(cli_app()), revision)
+
+
+@db.command("revision")
+@click.option("-m", "--message", required=True, help="Revision message")
+@click.option(
+    "--autogenerate/--empty",
+    default=True,
+    help="Autogenerate from model metadata or create an empty revision",
+)
+@click.option(
+    "--head",
+    default=None,
+    help="Extend this head instead of the app's lineage (stk@head for core).",
+)
+def db_revision(message, autogenerate, head):
+    """Create a migration revision in the app's own lineage."""
+    generate_revision(cli_app(), message, autogenerate=autogenerate, head=head)
+
+
+@db.command("check")
+def db_check():
+    """Fail if models have drifted away from the migrations."""
+    drift = build_migration_drift_report(cli_app())
+    if not drift:
+        console.print("[green]No migration drift: models match migrations[/]")
+        return
+
+    console.print("[red]Migration drift detected:[/]")
+    for line in drift:
+        console.print(f"  [yellow]{line}[/]")
+    raise click.ClickException(
+        'run: uv run stk db revision -m "describe change" && uv run stk db upgrade'
+    )
+
+
+@db.command("current")
+def db_current():
+    """Show the current database revision."""
+    run_alembic(command.current, build_alembic_config(cli_app()))
+
+
+@db.command("history")
+def db_history():
+    """Show migration history."""
+    run_alembic(command.history, build_alembic_config(cli_app()))
+
+
+@db.command("stamp")
+@click.argument("revision", default="heads")
+def db_stamp(revision):
+    """Stamp a database with a revision without running migrations."""
+    run_alembic(command.stamp, build_alembic_config(cli_app()), revision)

stk/cli/develop.py

@@ -0,0 +1,63 @@
+"""Starting an app and serving it locally."""
+
+from pathlib import Path
+
+import click
+
+import stk
+from stk.cli.base import app_root, app_spec, cli_app, console
+
+
+@click.command("init")
+@click.argument("name")
+@click.option(
+    "--source",
+    default=None,
+    help="Install stk from this checkout or wheel instead of the stkit package.",
+)
+def init(name, source):
+    """Start a new app package NAME in ./NAME, depending on this stk version."""
+    from stk.scaffold.generator import generate_app
+
+    try:
+        actions = generate_app(name, Path.cwd() / name, source)
+    except (ValueError, FileExistsError) as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    for action in actions:
+        console.print(f"  [blue]+[/] {action}")
+    console.print(
+        f"""
+[green]App {name} is ready.[/] Next:
+  cd {name}
+  uv run stk db upgrade && uv run stk install
+  uv run stk run
+"""
+    )
+
+
+@click.command("run")
+@click.option("--host", default="127.0.0.1", help="The interface to bind to.")
+@click.option("-p", "--port", default=5000, help="The port to bind to.")
+@click.option(
+    "--reload/--no-reload",
+    default=None,
+    help="Restart on code changes (default: on when QUART_DEBUG is set).",
+)
+def run(host, port, reload):
+    """Run a local development server (uvicorn, as in production)."""
+    import uvicorn
+    from quart.helpers import get_debug_flag
+
+    app = cli_app()
+    # Hypercorn, Quart's own runner, waits forever on open tabs at Ctrl+C. The
+    # timeout ends long-lived streams (/ws, SSE); browsers reconnect.
+    uvicorn.run(
+        app_spec(),
+        host=host,
+        port=port,
+        reload=get_debug_flag() if reload is None else reload,
+        reload_dirs=[app.root_path, str(Path(stk.__file__).parent)],
+        app_dir=str(app_root()),
+        timeout_graceful_shutdown=3,
+    )