stkit 17.0.2__tar.gz → 17.1.0__tar.gz

{stkit-17.0.2 → stkit-17.1.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v17.1.0 (2026-10-25)
+
+No migration required.
+
+- `app_navigation()` returns the app's `app.navigation` entries alone, without stk's Dashboard, Account and Administration sections, for a layout that draws its own sidebar (Frontend, Navigation).
+- The layout ships an import map, `{{ import_map() }}`, that maps every `.js` and `.mjs` file in the app's, extensions' and stk's static folders to its versioned URL, app first. A module imported by another module is fresh after a deploy too. A layout that does not extend `stk/layout.html` calls it in its `<head>` (Frontend).
+- `build_alembic_config("myapp", url)` takes the app's import name with a URL, so a test can migrate a throwaway database before it builds its app. Passing the app still works (Models, Migrations).
+- `stk db revision` imports the module of each column type Alembic writes by its path (pgvector's `HALFVEC` and `BIT`, an app's `UserDefinedType`), then sorts the revision's imports and formats it with the app's ruff config. Before, such revisions failed with a `NameError`.
+- `stk db revision` warns about each column-level `CheckConstraint` in the columns it adds: Alembic autogenerate leaves them out. Declare checks in `__table_args__`, or add them to the revision by hand (Models, Migrations).
+- Configuration documents app paths in `settings.py` (`Path(__file__).resolve().parent.parent`) in place of the removed `Config.PROJECT_ROOT`, and `app.root_path` and `app.instance_path` at runtime.
+
+### Upgrade considerations
+
+Nothing breaks. Apps can delete what they wrote around these gaps:
+
+- A Jinja global that returns `app.navigation` (Sealbook's `rail_navigation` in `sealbook/shell/__init__.py`): call `app_navigation()` in the layout instead.
+- An app import map (Sealbook's `import_map()` and `MODULE_DIRS` in `sealbook/assets.py`): stk's `import_map()` global has the same name, so a copied layout that calls `{{ import_map() }}` keeps working. stk's map also lists minified `.js` files; they are harmless there.
+- Tests that import the module-level app only to call `build_alembic_config(app, url)`: pass `"myapp"` instead.
+- Nothing in existing revisions: hand-written imports there stay correct. New revisions import their types themselves.
+
+Paste-ready prompt for a coding agent:
+
+```text
+Upgrade this app to stkit 17.1.0 (bump the pin, `uv lock`). Then delete the workarounds 17.1.0 makes unnecessary: (1) any Jinja global returning app.navigation; call app_navigation() in the layout instead. (2) any app-built import map of versioned static modules; stk's import_map() global replaces it, so keep `{{ import_map() }}` in a copied layout and delete the app's function and its registration, plus test assertions that minified files are absent from the map. (3) in tests, `build_alembic_config(app, url, ...)` where the app was imported only for that: pass the app's import name, `build_alembic_config("<package>", url, ...)`, and drop the import. Leave existing migration revisions alone, including their hand-written imports and checks. Done when the tests, `uv run stk verify` and `uv run stk smoke` pass.
+```
+
 ## v17.0.2 (2026-10-25)
 
 No migration required.

{stkit-17.0.2 → stkit-17.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stkit
-Version: 17.0.2
+Version: 17.1.0
 Summary: An async Quart framework optimized for AI-assisted development workflows
 Author-email: Level09 <hello@level09.com>
 License: MIT

{stkit-17.0.2 → stkit-17.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stkit"
-version = "17.0.2"
+version = "17.1.0"
 description = "An async Quart framework optimized for AI-assisted development workflows"
 authors = [
     {name = "Level09", email = "hello@level09.com"}

{stkit-17.0.2 → stkit-17.1.0}/stk/__init__.py

@@ -3,7 +3,7 @@ stk Framework
 A modern Python web framework optimized for AI-assisted development.
 """
 
-__version__ = "17.0.2"
+__version__ = "17.1.0"
 
 
 def __getattr__(name):

{stkit-17.0.2 → stkit-17.1.0}/stk/app.py

@@ -4,11 +4,20 @@ import hashlib
 import importlib
 import importlib.util
 import inspect
+import json
 import os
 from pathlib import Path
 
 from jinja2 import ChoiceLoader, FileSystemLoader, PrefixLoader
-from quart import Quart, g, render_template, request, send_from_directory
+from markupsafe import Markup
+from quart import (
+    Quart,
+    g,
+    render_template,
+    request,
+    send_from_directory,
+    url_for,
+)
 from quart_security import Security, SQLAlchemyUserDatastore
 from quart_security.views import _ensure_csrf_token
 from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
@@ -232,6 +241,26 @@ def register_static_versioning(app):
             )
         return response
 
+    def import_map():
+        """Map each module's plain URL to its versioned one, so a module imported by
+        another module (`import "./x.js"`) is fresh after a deploy too."""
+        names = sorted(
+            {
+                path.relative_to(folder).as_posix()
+                for folder in app.static_folders
+                for path in folder.rglob("*")
+                if path.suffix in (".js", ".mjs")
+            }
+        )
+        imports = {
+            f"{app.static_url_path}/{name}": url_for("static", filename=name)
+            for name in names
+        }
+        body = json.dumps({"imports": imports}).replace("</", "<\\/")
+        return Markup(f'<script type="importmap">{body}</script>')
+
+    app.jinja_env.globals["import_map"] = import_map
+
 
 CORE_NAVIGATION_START = [
     {"heading": "Main"},
@@ -267,6 +296,8 @@ def register_navigation(app):
         *app.navigation,
         *CORE_NAVIGATION_END,
     ]
+    # The app's entries alone, for a layout that draws its own sidebar.
+    app.jinja_env.globals["app_navigation"] = lambda: app.navigation
 
 
 def register_errorhandlers(app):

{stkit-17.0.2 → stkit-17.1.0}/stk/cli/database.py

@@ -79,6 +79,44 @@ def build_migration_drift_report(app=None, database_url=None):
     return [_describe_diff(diff) for diff in _flatten(diffs)]
 
 
+def _column_checks(op):
+    """`table.column` for each column an autogenerated op adds with its own check."""
+    from sqlalchemy import CheckConstraint, Column
+
+    for child in getattr(op, "ops", ()):
+        yield from _column_checks(child)
+    columns = [*getattr(op, "columns", ()), getattr(op, "column", None)]
+    for column in columns:
+        if isinstance(column, Column) and any(
+            isinstance(c, CheckConstraint) for c in column.constraints
+        ):
+            yield f"{column.table.name}.{column.name}"
+
+
+def _warn_column_checks(context, revision, directives):
+    # Alembic renders table-level checks only; a column's own check is left out.
+    for name in _column_checks(directives[0].upgrade_ops):
+        console.print(
+            f"[yellow]{name}: autogenerate leaves out a column-level CheckConstraint."
+            " Move it to __table_args__, or add it to this revision by hand.[/]"
+        )
+
+
+def _tidy_revision(path):
+    """Sort the revision's imports and format it with the app's own ruff config."""
+    import importlib.util
+    import subprocess
+    import sys
+
+    if importlib.util.find_spec("ruff") is None:
+        console.print("[yellow]ruff is not installed: revision imports are unsorted[/]")
+        return
+    for args in (["check", "--fix", "--select", "I"], ["format"]):
+        subprocess.run(
+            [sys.executable, "-m", "ruff", *args, "--quiet", path], check=True
+        )
+
+
 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.
 
@@ -89,35 +127,29 @@ def generate_revision(app, message, *, autogenerate=True, head=None, quiet=False
 
     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(
+        options = {"head": head}
+    else:
+        script = ScriptDirectory.from_config(config)
+        label = app_label(app)
+        started = any(label in rev.branch_labels for rev in script.walk_revisions())
+        options = {"depends_on": script.get_revision(f"{CORE_LABEL}@head").revision}
+        if started:
+            options["head"] = f"{label}@head"
+        else:
+            options.update(
+                head="base", branch_label=label, version_path=str(app_versions(app))
+            )
+        app_versions(app).mkdir(exist_ok=True)
+    revision = run_alembic(
         command.revision,
         config,
         message=message,
         autogenerate=autogenerate,
-        depends_on=core_head,
+        process_revision_directives=_warn_column_checks,
         **options,
     )
+    _tidy_revision(revision.path)
+    return revision
 
 
 @click.command()

{stkit-17.0.2 → stkit-17.1.0}/stk/migrations/__init__.py

@@ -7,6 +7,7 @@ label; an app's carry its package name and live in `<package>/migrations/`.
 from __future__ import annotations
 
 import importlib
+import importlib.util
 import os
 import pkgutil
 import tempfile
@@ -55,6 +56,17 @@ def include_object(obj, name, type_, reflected, compare_to):
     return not (type_ == "table" and name in EXTENSION_TABLES)
 
 
+def render_item(type_, obj, autogen_context):
+    """Import the module of a type Alembic renders by its path (pgvector's, the app's).
+
+    Alembic writes such a type as `pgvector.sqlalchemy.halfvec.HALFVEC(dim=3)` and
+    imports only SQLAlchemy dialects, so the revision would not run.
+    """
+    if type_ == "type" and not type(obj).__module__.startswith("sqlalchemy."):
+        autogen_context.imports.add(f"import {type(obj).__module__}")
+    return False
+
+
 def sync_url(database_url: str) -> str:
     """Convert an async driver URL to the sync driver Alembic uses."""
     url = make_url(database_url)
@@ -71,11 +83,20 @@ def app_label(app) -> str:
 
 
 def app_versions(app) -> Path:
+    """The app's migrations directory; `app` is the app or its import name."""
+    if isinstance(app, str):
+        return Path(importlib.util.find_spec(app).origin).parent / "migrations"
     return Path(app.root_path) / "migrations"
 
 
 def build_alembic_config(app=None, url=None, *, quiet=False) -> AlembicConfig:
-    """Build an Alembic config for stk's lineage plus the app's, if given."""
+    """Build an Alembic config for stk's lineage plus the app's, if given.
+
+    `app` is the app, or its import name (`"myapp"`) with an explicit `url`, so a
+    test can migrate a throwaway database before it builds the app.
+    """
+    if isinstance(app, str) and url is None:
+        raise ValueError("pass url when app is an import name")
     config = AlembicConfig()
     config.set_main_option("script_location", str(SCRIPT_DIR))
     config.set_main_option("path_separator", "os")

{stkit-17.0.2 → stkit-17.1.0}/stk/migrations/env.py

@@ -5,7 +5,7 @@ import logging
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 
-from stk.migrations import get_target_metadata, include_object
+from stk.migrations import get_target_metadata, include_object, render_item
 
 config = context.config
 
@@ -25,6 +25,7 @@ def run_migrations_offline() -> None:
         compare_type=True,
         compare_server_default=True,
         include_object=include_object,
+        render_item=render_item,
         render_as_batch=url.startswith("sqlite"),
     )
 
@@ -44,6 +45,7 @@ def run_migrations_online() -> None:
             compare_type=True,
             compare_server_default=True,
             include_object=include_object,
+            render_item=render_item,
             # SQLite alters tables by copying them; batch mode does that for us.
             render_as_batch=connection.dialect.name == "sqlite",
         )

{stkit-17.0.2 → stkit-17.1.0}/stk/templates/layout.html

@@ -8,6 +8,7 @@
     <meta name="description" content="A framework for the next decade">
     <meta name="author" content="{{ config.APP_NAME }}">
     <meta name="viewport" content="width=device-width, initial-scale=1">
+    {{ import_map() }}
     <link rel="icon" href="/static/img/favicon.ico" type="image/x-icon">
 
     <link rel="stylesheet" href="{{ url_for('static', filename='css/vuetify.min.css') }}">

{stkit-17.0.2 → stkit-17.1.0}/tests/test_composition.py

@@ -1,6 +1,9 @@
 """An app composes stk: its files win over its extensions', which win over stk's."""
 
+import hashlib
 import importlib
+import json
+import re
 import sys
 import tempfile
 import textwrap
@@ -21,6 +24,8 @@ FILES = {
         """
     ),
     "tapp/static/css/app.css": "/* the app's */",
+    "tapp/static/js/page.js": 'import "./shared.js";',
+    "tapp/static/js/shared.js": "// the app's, shadowing the extension's",
     "tapp/first/__init__.py": textwrap.dedent(
         """\
         from tapp.first import models
@@ -36,6 +41,8 @@ FILES = {
     "tapp/first/templates/index.html": "the extension's, shadowed by the app's",
     "tapp/first/static/css/app.css": "/* the first extension's */",
     "tapp/first/static/css/ext.css": "/* first */",
+    "tapp/first/static/js/shared.js": "// the first extension's",
+    "tapp/first/static/js/lib/util.mjs": "export const x = 1;",
     "tapp/second/__init__.py": textwrap.dedent(
         """\
         def init_app(app):
@@ -107,6 +114,25 @@ class CompositionTest(unittest.IsolatedAsyncioTestCase):
             titles[:5], ["Main", "Dashboard", "First", "Second", "Account"]
         )
 
+    def test_app_navigation_is_the_apps_entries_alone(self):
+        titles = [i["title"] for i in self.app.jinja_env.globals["app_navigation"]()]
+        self.assertEqual(titles, ["First", "Second"])
+
+    async def test_import_map_versions_every_module_as_it_will_be_served(self):
+        page = await (await self.app.test_client().get("/")).get_data(as_text=True)
+        tag = re.search(r'<script type="importmap">(.*?)</script>', page)
+        imports = json.loads(tag.group(1))["imports"]
+        for name in ("js/page.js", "js/shared.js", "js/lib/util.mjs", "js/config.js"):
+            self.assertRegex(imports[f"/static/{name}"], r"\?v=[0-9a-f]{12}$")
+        async with self.app.test_request_context("/"):
+            from quart import url_for
+
+            shared = url_for("static", filename="js/shared.js")
+        self.assertEqual(imports["/static/js/shared.js"], shared)
+        app_digest = hashlib.sha256(b"// the app's, shadowing the extension's")
+        self.assertTrue(shared.endswith(app_digest.hexdigest()[:12]))
+        self.assertNotIn("/static/css/app.css", imports)
+
     def test_extension_models_load_before_init_app(self):
         self.assertTrue(self.app.config["SEEN_MODELS_FIRST"])
 

{stkit-17.0.2 → stkit-17.1.0}/tests/test_migration_drift.py

@@ -1,9 +1,11 @@
 """`stk db check` must notice a model that no migration has caught up with."""
 
 import json
+import os
 import subprocess
 import sys
 import unittest
+from pathlib import Path
 
 # stk's own lineage against stk's own models, on a throwaway SQLite database. A
 # fresh interpreter: other tests load the example app, whose tables would join
@@ -46,5 +48,33 @@ class MigrationDriftTest(unittest.TestCase):
         self.assertEqual(drift("probe"), ["add_table: drift_probe"])
 
 
+# Migrate by import name alone: the app module is never imported, so a test can
+# migrate before it builds its app.
+BY_NAME = """
+import sys
+from alembic import command
+from sqlalchemy import create_engine, inspect
+from stk.migrations import build_alembic_config, throwaway_database_url
+
+with throwaway_database_url("sqlite:///unused.db", sync=True) as url:
+    command.upgrade(build_alembic_config("minimal", url, quiet=True), "heads")
+    tables = inspect(create_engine(url)).get_table_names()
+print("note" in tables, "minimal.app" in sys.modules)
+"""
+
+
+class MigrateByImportNameTest(unittest.TestCase):
+    def test_app_lineage_migrates_without_an_app_object(self):
+        example = Path(__file__).resolve().parent.parent / "examples" / "minimal"
+        result = subprocess.run(
+            [sys.executable, "-c", BY_NAME],
+            capture_output=True,
+            text=True,
+            check=True,
+            env={**os.environ, "PYTHONPATH": str(example)},
+        )
+        self.assertEqual(result.stdout.split(), ["True", "False"])
+
+
 if __name__ == "__main__":
     unittest.main()

stkit-17.1.0/tests/test_revision_imports.py

@@ -0,0 +1,108 @@
+"""An autogenerated revision imports the modules of the types it renders by path."""
+
+import os
+import subprocess
+import sys
+import tempfile
+import textwrap
+import unittest
+from pathlib import Path
+
+FILES = {
+    "pyproject.toml": textwrap.dedent(
+        """\
+        [tool.ruff.lint]
+        select = ["E", "W", "F", "I", "B", "C4", "UP"]
+
+        [tool.ruff.lint.isort]
+        known-first-party = ["tgen"]
+        """
+    ),
+    "tgen/__init__.py": "",
+    # A column type from another module of the app, rendered by its module path.
+    "tgen/types.py": textwrap.dedent(
+        """\
+        from sqlalchemy.types import UserDefinedType
+
+
+        class Point(UserDefinedType):
+            cache_ok = True
+
+            def __init__(self, dim):
+                self.dim = dim
+
+            def get_col_spec(self, **kw):
+                return "POINT"
+        """
+    ),
+    "tgen/place/__init__.py": "def init_app(app):\n    pass\n",
+    "tgen/place/models.py": textwrap.dedent(
+        """\
+        from sqlalchemy import CheckConstraint, Integer
+        from sqlalchemy.orm import Mapped, mapped_column
+        from stk.extensions import Base
+
+        from tgen.types import Point
+
+
+        class Place(Base):
+            __tablename__ = "place"
+            id: Mapped[int] = mapped_column(primary_key=True)
+            spot = mapped_column(Point(2))
+            rank = mapped_column(Integer, CheckConstraint("rank > 0", name="rank"))
+        """
+    ),
+}
+
+# A fresh interpreter: the app's table would otherwise join shared metadata.
+SCRIPT = """
+import sys
+from alembic import command
+import tgen.place
+from stk.app import Stk
+from stk.cli.database import generate_revision
+from stk.migrations import build_alembic_config
+from stk.settings import TestingConfig
+
+class Config(TestingConfig):
+    SECRET_KEY = SECURITY_PASSWORD_SALT = "test"
+    SQLALCHEMY_DATABASE_URI = "sqlite+aiosqlite:///" + sys.argv[1]
+
+app = Stk("tgen", config=Config, extensions=[tgen.place])
+command.upgrade(build_alembic_config(app, quiet=True), "heads")
+print(generate_revision(app, "place", quiet=True).path)
+command.upgrade(build_alembic_config(app, quiet=True), "heads")
+"""
+
+
+class RevisionImportsTest(unittest.TestCase):
+    def test_revision_imports_app_types_and_passes_ruff(self):
+        with tempfile.TemporaryDirectory(prefix="stk-rev-") as root:
+            for name, text in FILES.items():
+                path = Path(root) / name
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(text)
+            result = subprocess.run(
+                [sys.executable, "-c", SCRIPT, f"{root}/app.db"],
+                cwd=root,
+                env={**os.environ, "PYTHONPATH": root},
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(result.returncode, 0, result.stderr)
+            revision = Path(result.stdout.strip().splitlines()[-1]).read_text()
+            lint = subprocess.run(
+                [sys.executable, "-m", "ruff", "check", "--no-cache", root],
+                cwd=root,
+                capture_output=True,
+                text=True,
+            )
+
+        self.assertIn("\nimport tgen.types\n", revision)
+        self.assertIn("tgen.types.Point(2)", revision)
+        self.assertEqual(lint.returncode, 0, lint.stdout)
+        self.assertIn("place.rank: autogenerate leaves out", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

{stkit-17.0.2 → stkit-17.1.0}/tests/test_scaffolder.py

@@ -329,7 +329,8 @@ class InitAndNewTests(unittest.TestCase):
         }
         self.assertEqual(assigned["branch_labels"], ("acme",))
         self.assertEqual(assigned["depends_on"], "stk_0001")
-        self.assertIn("create_table('widget'", revision.read_text())
+        # Formatted by the app's ruff config.
+        self.assertIn('op.create_table(\n        "widget",', revision.read_text())
 
     def test_both_lineages_match_the_models(self):
         # gadget was scaffolded without a migration, so it is the only drift.