runic-migrate 0.1.0__tar.gz

runic_migrate-0.1.0/.gitignore

@@ -0,0 +1,114 @@
+__pycache__/
+__pypackages__/
+.cache
+.coverage
+.coverage.*
+.dmypy.json
+.DS_Store
+.eggs/
+.env
+.env.backup
+.env.docker
+.hypothesis/
+.idea/
+.installed.cfg
+.ipynb_checkpoints
+.mypy_cache/
+.nox/
+.pdm.toml
+.pybuilder/
+.pyre/
+.pytest_cache/
+.Python
+.python_packages
+.pytype/
+.ropeproject
+.scrapy
+.spyderproject
+.spyproject
+.states
+.tox/
+.venv
+.venv.mac
+.web
+.webassets-cache
+*.bak
+*.cover
+*.db
+*.egg
+*.egg-info/
+*.kv-env.*
+*.log
+*.manifest
+*.mo
+*.pot
+*.py,cover
+*.py[cod]
+*.sage.py
+*.so
+*.spec
+*.terraform.lock.hcl
+*.tfplan
+*.tfstate
+*.tfstate.*.backup
+*.tfstate.backup
+*.tfvars
+**/.terraform/*
+*$py.class
+/site
+/vectorstore/
+aila-storage/
+assets/external/
+build/
+celerybeat-schedule
+celerybeat.pid
+configuration/config.abaz009.yaml
+configuration/config.bubb001.yaml
+configuration/config.stie104.yaml
+configuration/config.voro047.yaml
+connector examples/sharepoint.json
+cover/
+coverage.xml
+cython_debug/
+db.sqlite3
+db.sqlite3-journal
+develop-eggs/
+dist/
+dmypy.json
+docs/_build/
+Documents/
+downloads/
+eggs/
+env.bak/
+env/
+ENV/
+htmlcov/
+instance/
+ipython_config.py
+knowledge/migrate.py
+lib/
+lib64/
+local_settings.py
+local.settings.json
+MANIFEST
+nosetests.xml
+out
+parts/
+pip-delete-this-directory.txt
+pip-log.txt
+Pipfile
+profile_default/
+sdist/
+share/python-wheels/
+sketchpad/
+sketchpad/
+stores/
+target/
+tests/mcp_test.py
+tmp.txt
+uploaded_files/
+uploads/
+var/
+venv.bak/
+venv/
+wheels/

runic_migrate-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Jens Rehpöhler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runic_migrate-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: runic-migrate
+Version: 0.1.0
+Summary: Graph schema migrations for FalkorDB.
+Project-URL: Homepage, https://github.com/jenreh/python-kit
+Project-URL: Repository, https://github.com/jenreh/python-kit
+Author: Jens Rehpöhler
+License: MIT
+License-File: LICENSE.md
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.14
+Requires-Dist: aiosqlite==0.22.1
+Requires-Dist: falkordb>=1.6.1
+Requires-Dist: falkordblite>=0.10.0
+Requires-Dist: fastmcp==3.3.1
+Requires-Dist: mako>=1.3.12
+Requires-Dist: pydantic-settings==2.14.1
+Requires-Dist: pydantic==2.13.4
+Requires-Dist: rich==15.0.0
+Requires-Dist: typer[all]==0.26.3
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="docs/source/_static/runic.svg" width="240" alt="Runic logo">
+
+# Runic
+
+**Graph schema migrations for FalkorDB.**
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+[![pypi](https://img.shields.io/pypi/v/runic.svg)](https://pypi.python.org/pypi/runic)
+[![Python](https://img.shields.io/badge/python-3.14%2B-orange)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+
+[Features](#features) • [Installation](#installation) • [A Simple Example](#a-simple-example) • [Documentation](#documentation)
+
+</div>
+
+---
+
+**Runic** is a lightweight, Alembic-style migration framework built specifically for [FalkorDB](https://falkordb.com/).
+It brings robust revision tracking, linear graph migrations, and a powerful CLI to graph database environments, managing schema versioning through Cypher scripts and native FalkorDB syntax.
+
+## Features
+
+- **Alembic-Style Workflow** — Familiar CLI verbs like `init`, `revision`, `upgrade`, `downgrade`, and `current`.
+- **Graph-Native** — Treats your database as a graph. Stores migration states intelligently inside dedicated nodes (e.g., `:_FalkorMigrateVersion`).
+- **Idempotent Cypher** — Encourages explicit, heavily-guarded migration steps, supporting robust backward capability even without transactional DDLs.
+- **Offline & Dry Run** — Review generated Cypher scripts thoroughly before executing them in production.
+- **Rollback Snapshots** — Advanced capabilities utilizing `GRAPH.COPY` for high-risk, non-reversible data migrations.
+
+## Installation
+
+Install via `pip` or `uv`:
+
+```bash
+uv pip install runic
+```
+
+Or add it to an existing project:
+
+```bash
+uv add runic
+```
+
+> [!NOTE]
+> Runic requires Python 3.14+ and is optimized for the latest FalkorDB clients.
+
+## A Simple Example
+
+Initialize your project and generate a new revision:
+
+```bash
+# Set up a new runic environment
+runic init
+
+# Create your first revision script
+runic revision -m "create user index"
+```
+
+This generates a revision file in `runic/versions`. Open it and define your upgrades and downgrades:
+
+```python
+"""create user index
+
+Revision ID: 1975ea83b712
+Revises: None
+Create Date: 2026-05-30 14:00:00.000000
+"""
+
+from runic import op
+
+# revision identifiers, used by Runic.
+revision = "1975ea83b712"
+down_revision = None
+
+
+def upgrade() -> None:
+    # Use Cypher to create an index
+    op.run_cypher("CREATE INDEX ON :User(email)")
+
+
+def downgrade() -> None:
+    # Safely revert the operation
+    op.run_cypher("DROP INDEX ON :User(email)")
+```
+
+Then apply your changes:
+
+```bash
+runic upgrade head
+```
+
+## Documentation
+
+For a full conceptual overview, advanced CLI usage, and deep dives into branching or multi-head resolution, visit the complete [Runic Documentation](https://jenreh.github.io/runic/).

runic_migrate-0.1.0/README.md

@@ -0,0 +1,94 @@
+<div align="center">
+  <img src="docs/source/_static/runic.svg" width="240" alt="Runic logo">
+
+# Runic
+
+**Graph schema migrations for FalkorDB.**
+
+![Version](https://img.shields.io/badge/version-0.1.0-blue)
+[![pypi](https://img.shields.io/pypi/v/runic.svg)](https://pypi.python.org/pypi/runic)
+[![Python](https://img.shields.io/badge/python-3.14%2B-orange)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE.md)
+
+[Features](#features) • [Installation](#installation) • [A Simple Example](#a-simple-example) • [Documentation](#documentation)
+
+</div>
+
+---
+
+**Runic** is a lightweight, Alembic-style migration framework built specifically for [FalkorDB](https://falkordb.com/).
+It brings robust revision tracking, linear graph migrations, and a powerful CLI to graph database environments, managing schema versioning through Cypher scripts and native FalkorDB syntax.
+
+## Features
+
+- **Alembic-Style Workflow** — Familiar CLI verbs like `init`, `revision`, `upgrade`, `downgrade`, and `current`.
+- **Graph-Native** — Treats your database as a graph. Stores migration states intelligently inside dedicated nodes (e.g., `:_FalkorMigrateVersion`).
+- **Idempotent Cypher** — Encourages explicit, heavily-guarded migration steps, supporting robust backward capability even without transactional DDLs.
+- **Offline & Dry Run** — Review generated Cypher scripts thoroughly before executing them in production.
+- **Rollback Snapshots** — Advanced capabilities utilizing `GRAPH.COPY` for high-risk, non-reversible data migrations.
+
+## Installation
+
+Install via `pip` or `uv`:
+
+```bash
+uv pip install runic
+```
+
+Or add it to an existing project:
+
+```bash
+uv add runic
+```
+
+> [!NOTE]
+> Runic requires Python 3.14+ and is optimized for the latest FalkorDB clients.
+
+## A Simple Example
+
+Initialize your project and generate a new revision:
+
+```bash
+# Set up a new runic environment
+runic init
+
+# Create your first revision script
+runic revision -m "create user index"
+```
+
+This generates a revision file in `runic/versions`. Open it and define your upgrades and downgrades:
+
+```python
+"""create user index
+
+Revision ID: 1975ea83b712
+Revises: None
+Create Date: 2026-05-30 14:00:00.000000
+"""
+
+from runic import op
+
+# revision identifiers, used by Runic.
+revision = "1975ea83b712"
+down_revision = None
+
+
+def upgrade() -> None:
+    # Use Cypher to create an index
+    op.run_cypher("CREATE INDEX ON :User(email)")
+
+
+def downgrade() -> None:
+    # Safely revert the operation
+    op.run_cypher("DROP INDEX ON :User(email)")
+```
+
+Then apply your changes:
+
+```bash
+runic upgrade head
+```
+
+## Documentation
+
+For a full conceptual overview, advanced CLI usage, and deep dives into branching or multi-head resolution, visit the complete [Runic Documentation](https://jenreh.github.io/runic/).

runic_migrate-0.1.0/pyproject.toml

@@ -0,0 +1,256 @@
+[project]
+name = "runic-migrate"
+version = "0.1.0"
+description = "Graph schema migrations for FalkorDB."
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Jens Rehpöhler" }]
+keywords = []
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Home Automation",
+]
+
+dependencies = [
+    "fastmcp==3.3.1",
+    "typer[all]==0.26.3",
+    "rich==15.0.0",
+    "pydantic==2.13.4",
+    "pydantic-settings==2.14.1",
+    "aiosqlite==0.22.1",
+    "falkordb>=1.6.1",
+    "mako>=1.3.12",
+    "falkordblite>=0.10.0",
+]
+
+[dependency-groups]
+dev = [
+    "bump-my-version==1.3.0",
+    "detect-secrets==1.5.0",
+    "pre-commit==4.6.0",
+    "pytest==9.0.3",
+    "pytest-asyncio==1.4.0",
+    "pytest-cov==7.1.0",
+    "pytest-httpserver==1.1.5",
+    "ruff==0.15.15",
+    "mypy==2.1.0",
+    "types-PyYAML==6.0.12.20260510",
+    "falkordblite>=0.10.0",
+    "sphinx>=9.1.0",
+    "furo>=2025.12.19",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.7.0",
+]
+
+[project.scripts]
+runic = "runic.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/jenreh/python-kit"
+Repository = "https://github.com/jenreh/python-kit"
+
+[tool.hatch.build.targets.wheel]
+packages = ["runic"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/runic",
+    "README.md",
+    "pyproject.toml",
+]
+exclude = [
+    ".agents/",
+    ".cache/",
+    ".claude/",
+    ".devcontainer/",
+    ".github/",
+    ".vscode/",
+    "skill/",
+    "spec/",
+    "tests/",
+    ".env",
+    ".gitignore",
+    ".pre-commit-config.yaml",
+    "AGENTS.md",
+    "coverage.xml",
+    "Taskfile.yaml",
+]
+
+[tool.bumpversion]
+commit = false
+current_version = "0.1.0"
+tag = false
+allow-dirty = false
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "README.md"
+search = '![Version](https://img.shields.io/badge/version-{current_version}-blue)'
+replace = '![Version](https://img.shields.io/badge/version-{new_version}-blue)'
+
+[tool.ruff]
+cache-dir = ".cache/ruff"
+indent-width = 4
+line-length = 88
+target-version = "py314"
+extend-exclude = [
+    ".agents",
+    ".cache",
+    ".claude",
+    ".devcontainer",
+    ".github",
+    ".vscode",
+    "build",
+    "dist",
+    "docs",
+]
+
+[tool.ruff.lint]
+extend-select = ["I"]
+ignore = [
+    "EM101",
+    "EM102",
+    "ISC001",
+    "N811",
+    "N818",
+    "PLR0913",
+    "PT011",
+    "PT012",
+    "RUF012",
+    "RUF100",
+    "SIM300",
+    "E501",
+    "B008",
+    "ASYNC240",
+    "PYI034",
+    "S101",
+    "PLR0912",
+    "PLR0915",
+    "ASYNC109",
+    "ARG001",
+    "PLR2004",
+    "PLW0603",
+    "PLC0415",
+    "SIM105",
+    "PLW2901",
+    "PLR0911",
+    "B017",
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+select = [
+    "A",
+    "ANN001",
+    "ANN201",
+    "ARG",
+    "ASYNC",
+    "B",
+    "C4",
+    "DTZ",
+    "E",
+    "EM",
+    "EXE",
+    "F",
+    "FIX",
+    "G",
+    "ICN",
+    "LOG",
+    "N",
+    "PERF",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "PYI",
+    "Q",
+    "RET",
+    "RUF",
+    "S",
+    "SIM",
+    "SLF",
+    "SLF001",
+    "T20",
+    "TID",
+    "UP",
+    "W",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001"]
+"test_**.py" = [
+    "S101",
+    "PLR2004",
+    "ANN001",
+    "S106",
+    "SLF001",
+    "RET504",
+    "PERF401",
+    "E402",
+    "S501",
+    "S110",
+    "ARG002",
+    "ARG005",
+    "E741",
+    "RUF059",
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+exclude = ["*.pyi"]
+
+[tool.ruff.lint.isort]
+known-local-folder = ["sonos"]
+
+[tool.pytest.ini_options]
+cache_dir = ".cache/pytest"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "sonos_live: requires real Sonos hardware on the network",
+    "integration: requires falkordblite (embedded FalkorDB, no external server)",
+]
+
+[tool.mypy]
+cache_dir = ".cache/mypy"
+disallow_untyped_defs = true
+incremental = true
+python_version = "3.14"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+exclude = [
+    ".cache",
+    ".claude",
+    ".venv",
+    "build",
+    "dist",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["app", "runic"]
+omit = []
+
+[tool.coverage.report]
+exclude_lines = ["if TYPE_CHECKING:", "if __name__ == .__main__.:", "pragma: no cover"]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

runic_migrate-0.1.0/runic/__init__.py

@@ -0,0 +1,33 @@
+from runic import context
+from runic.context import IrreversibleMigrationError
+from runic.exceptions import MultipleBasesError, MultipleHeadsError
+from runic.manifest import (
+    FulltextIndex,
+    MandatoryConstraint,
+    RangeIndex,
+    SchemaManifest,
+    UniqueConstraint,
+    VectorIndex,
+)
+from runic.operations import ConstraintFailedError, ConstraintTimeoutError, op
+from runic.script import AmbiguousRevision, RevisionNotFound
+from runic.service import RunicService
+
+__all__ = [
+    "AmbiguousRevision",
+    "ConstraintFailedError",
+    "ConstraintTimeoutError",
+    "FulltextIndex",
+    "IrreversibleMigrationError",
+    "MandatoryConstraint",
+    "MultipleBasesError",
+    "MultipleHeadsError",
+    "RangeIndex",
+    "RevisionNotFound",
+    "RunicService",
+    "SchemaManifest",
+    "UniqueConstraint",
+    "VectorIndex",
+    "context",
+    "op",
+]

runic_migrate-0.1.0/runic/adapters/__init__.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from runic.introspect import LiveSchema
+
+
+@runtime_checkable
+class GraphAdapter(Protocol):
+    """Protocol all graph-database adapters must satisfy.
+
+    The runic core depends only on this interface — no FalkorDB or any other
+    concrete database client leaks into shared code.
+    """
+
+    @property
+    def name(self) -> str: ...
+
+    # Low-level query execution
+    def run_query(self, query: str, params: dict | None = None) -> Any: ...
+    def run_ro_query(self, query: str) -> Any: ...
+
+    # Version tracking
+    def get_version(self) -> list[str]: ...
+    def set_version(self, revisions: list[str]) -> None: ...
+
+    # Schema introspection
+    def read_live_schema(self) -> LiveSchema: ...
+
+    # Schema DDL
+    def create_range_index(
+        self, label: str, prop: str, *, rel: bool = False
+    ) -> None: ...
+    def drop_range_index(self, label: str, prop: str, *, rel: bool = False) -> None: ...
+    def create_fulltext_index(
+        self,
+        label: str,
+        *props: str,
+        language: str | None = None,
+        stopwords: list[str] | None = None,
+    ) -> None: ...
+    def drop_fulltext_index(self, label: str, *props: str) -> None: ...
+    def create_vector_index(
+        self,
+        label: str,
+        prop: str,
+        dimension: int,
+        similarity: str,
+        *,
+        m: int = 16,
+        ef_construction: int = 200,
+        ef_runtime: int = 10,
+    ) -> None: ...
+    def drop_vector_index(self, label: str, prop: str) -> None: ...
+    def create_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None: ...
+    def drop_constraint(
+        self, kind: str, entity: str, label: str, props: list[str]
+    ) -> None: ...
+
+    # Snapshots
+    def snapshot(self, snap_name: str) -> None: ...
+    def restore_snapshot(self, snap_name: str) -> None: ...
+    def snapshot_exists(self, snap_name: str) -> bool: ...
+
+
+__all__ = ["GraphAdapter"]