shellbrain 0.1.23__tar.gz → 0.1.24__tar.gz

{shellbrain-0.1.23 → shellbrain-0.1.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.23
+Version: 0.1.24
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

shellbrain-0.1.24/app/boot/migrations.py

@@ -0,0 +1,115 @@
+"""Packaged Alembic bootstrap helpers for installed-shellbrain database migrations."""
+
+from __future__ import annotations
+
+from importlib.resources import as_file, files
+import importlib.metadata
+
+from alembic import command
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from alembic.script.revision import ResolutionError
+
+from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
+from app.boot.db import get_optional_db_dsn
+from app.periphery.admin.destructive_guard import backup_and_verify_before_destructive_action
+from app.periphery.admin.instance_guard import ensure_instance_metadata, fetch_instance_metadata
+from app.periphery.admin.privileges import reconcile_app_role_privileges
+
+
+class DatabaseRevisionAheadOfInstalledPackageError(RuntimeError):
+    """Raised when the target database revision is newer than the installed package knows about."""
+
+
+def upgrade_database(revision: str = "head") -> None:
+    """Apply packaged Alembic migrations to the configured database."""
+
+    config = Config()
+    admin_dsn = get_admin_db_dsn()
+    with as_file(files("app").joinpath("migrations")) as migrations_path:
+        config.set_main_option("script_location", str(migrations_path))
+        script = ScriptDirectory.from_config(config)
+        if _database_has_shellbrain_objects(admin_dsn):
+            _assert_database_revision_is_known(admin_dsn=admin_dsn, script=script)
+            backup_and_verify_before_destructive_action(
+                admin_dsn=admin_dsn,
+                backup_root=get_backup_dir(),
+                mirror_root=get_backup_mirror_dir(),
+            )
+        config.set_main_option("sqlalchemy.url", admin_dsn)
+        command.upgrade(config, revision)
+    if fetch_instance_metadata(admin_dsn) is None:
+        ensure_instance_metadata(
+            admin_dsn,
+            instance_mode=get_instance_mode_default(),
+            created_by="app.admin.migrate",
+            notes="Stamped by packaged migration runner.",
+        )
+    app_dsn = get_optional_db_dsn()
+    if app_dsn:
+        reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn)
+
+
+def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
+    """Return whether the target database already contains Shellbrain-managed tables."""
+
+    import psycopg
+
+    with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+        with conn.cursor() as cur:
+            cur.execute(
+                """
+                SELECT EXISTS (
+                  SELECT 1
+                  FROM information_schema.tables
+                  WHERE table_schema = 'public'
+                    AND table_name IN ('memories', 'episodes', 'episode_events', 'operation_invocations')
+                )
+                """
+            )
+            return bool(cur.fetchone()[0])
+
+
+def _assert_database_revision_is_known(*, admin_dsn: str, script: ScriptDirectory) -> None:
+    """Fail early with a user-facing error when the database revision is newer than this package."""
+
+    current_revision = _fetch_database_revision(admin_dsn)
+    if current_revision is None:
+        return
+    try:
+        script.get_revision(current_revision)
+    except ResolutionError as exc:
+        installed_version = _installed_shellbrain_version()
+        raise DatabaseRevisionAheadOfInstalledPackageError(
+            "Installed Shellbrain package "
+            f"({installed_version}) cannot manage database revision {current_revision}. "
+            "This database was likely migrated by a newer Shellbrain release than the one currently installed. "
+            "Upgrade Shellbrain to a build that includes this revision, then rerun `shellbrain init` or "
+            "`shellbrain admin migrate`."
+        ) from exc
+
+
+def _fetch_database_revision(admin_dsn: str) -> str | None:
+    """Return the current alembic revision when present."""
+
+    import psycopg
+
+    try:
+        with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT version_num FROM alembic_version")
+                row = cur.fetchone()
+    except psycopg.Error:
+        return None
+    if row is None or row[0] is None:
+        return None
+    return str(row[0])
+
+
+def _installed_shellbrain_version() -> str:
+    """Return the installed Shellbrain package version when available."""
+
+    try:
+        return importlib.metadata.version("shellbrain")
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"

{shellbrain-0.1.23 → shellbrain-0.1.24}/app/periphery/admin/init.py

@@ -469,10 +469,13 @@ def _reconcile_database(config: MachineConfig) -> tuple[bool, MachineConfig]:
 def _apply_schema_migrations(config: MachineConfig) -> bool:
     """Apply packaged schema migrations to the configured Shellbrain database."""
 
-    from app.boot.migrations import upgrade_database
+    from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError, upgrade_database
 
     before_revision = _fetch_schema_revision(config.database.admin_dsn)
-    upgrade_database()
+    try:
+        upgrade_database()
+    except DatabaseRevisionAheadOfInstalledPackageError as exc:
+        raise InitConflictError(str(exc)) from exc
     after_revision = _fetch_schema_revision(config.database.admin_dsn)
     return before_revision != after_revision
 

{shellbrain-0.1.23 → shellbrain-0.1.24}/app/periphery/cli/main.py

@@ -714,9 +714,13 @@ def _run_admin_command(args: argparse.Namespace) -> int:
     """Execute one admin command."""
 
     if args.admin_command == "migrate":
-        from app.boot.migrations import upgrade_database
+        from app.boot.migrations import DatabaseRevisionAheadOfInstalledPackageError, upgrade_database
 
-        upgrade_database()
+        try:
+            upgrade_database()
+        except DatabaseRevisionAheadOfInstalledPackageError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
         print("Applied shellbrain schema migrations to head.")
         return 0
 

{shellbrain-0.1.23 → shellbrain-0.1.24}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "shellbrain"
-version = "0.1.23"
+version = "0.1.24"
 description = "Repo-scoped Shellbrain CLI with explicit evidence-backed writes."
 readme = "README.md"
 requires-python = ">=3.11"

{shellbrain-0.1.23 → shellbrain-0.1.24}/shellbrain.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.23
+Version: 0.1.24
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

shellbrain-0.1.23/app/boot/migrations.py

@@ -1,61 +0,0 @@
-"""Packaged Alembic bootstrap helpers for installed-shellbrain database migrations."""
-
-from __future__ import annotations
-
-from importlib.resources import as_file, files
-
-from alembic import command
-from alembic.config import Config
-
-from app.boot.admin_db import get_admin_db_dsn, get_backup_dir, get_backup_mirror_dir, get_instance_mode_default
-from app.boot.db import get_optional_db_dsn
-from app.periphery.admin.destructive_guard import backup_and_verify_before_destructive_action
-from app.periphery.admin.instance_guard import ensure_instance_metadata, fetch_instance_metadata
-from app.periphery.admin.privileges import reconcile_app_role_privileges
-
-
-def upgrade_database(revision: str = "head") -> None:
-    """Apply packaged Alembic migrations to the configured database."""
-
-    config = Config()
-    admin_dsn = get_admin_db_dsn()
-    if _database_has_shellbrain_objects(admin_dsn):
-        backup_and_verify_before_destructive_action(
-            admin_dsn=admin_dsn,
-            backup_root=get_backup_dir(),
-            mirror_root=get_backup_mirror_dir(),
-        )
-    config.set_main_option("sqlalchemy.url", admin_dsn)
-    with as_file(files("app").joinpath("migrations")) as migrations_path:
-        config.set_main_option("script_location", str(migrations_path))
-        command.upgrade(config, revision)
-    if fetch_instance_metadata(admin_dsn) is None:
-        ensure_instance_metadata(
-            admin_dsn,
-            instance_mode=get_instance_mode_default(),
-            created_by="app.admin.migrate",
-            notes="Stamped by packaged migration runner.",
-        )
-    app_dsn = get_optional_db_dsn()
-    if app_dsn:
-        reconcile_app_role_privileges(admin_dsn=admin_dsn, app_dsn=app_dsn)
-
-
-def _database_has_shellbrain_objects(admin_dsn: str) -> bool:
-    """Return whether the target database already contains Shellbrain-managed tables."""
-
-    import psycopg
-
-    with psycopg.connect(admin_dsn.replace("+psycopg", "")) as conn:
-        with conn.cursor() as cur:
-            cur.execute(
-                """
-                SELECT EXISTS (
-                  SELECT 1
-                  FROM information_schema.tables
-                  WHERE table_schema = 'public'
-                    AND table_name IN ('memories', 'episodes', 'episode_events', 'operation_invocations')
-                )
-                """
-            )
-            return bool(cur.fetchone()[0])