winterforge 0.1.0__tar.gz

winterforge-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: winterforge
+Version: 0.1.0
+Summary: AI-native framework with composable primitives
+Author: Beau Simensen
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: bcrypt>=4.1.2
+Requires-Dist: PyJWT>=2.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"

winterforge-0.1.0/README.md

@@ -0,0 +1,201 @@
+# WinterForge
+
+**Async-first framework for composable data primitives.**
+
+---
+
+## Quick Start
+
+```python
+from winterforge.frags import Frag
+from winterforge.frags.registries import UserRegistry
+from winterforge.plugins import discover_plugins, StorageManager
+
+# Initialize
+discover_plugins()
+StorageManager.load_bootstrap()
+
+# Create user
+users = UserRegistry()
+user = await users.create(
+    username='alice',
+    email='alice@example.com',
+    password='secure123'
+)
+
+# Query
+user = await users.get('alice@example.com')  # Email resolution
+active = await users.verified_only().all()   # Filter
+
+# Create Frag
+post = Frag(
+    affinities=['post', 'published'],
+    traits=['titled', 'timestamped', 'sluggable']
+)
+
+post.set_title("Hello World") \
+    .generate_slug("Hello World")
+
+await post.save()
+```
+
+---
+
+## Core Concepts
+
+### Frags
+Composable data primitives built from:
+- **Affinities** - What it IS (tags: `['user', 'admin']`)
+- **Traits** - What it CAN DO (behavior: `['titled', 'persistable']`)
+- **Aliases** - Flexible metadata (relations: `{'employee_id': '12345'}`)
+
+### Registries
+Query collections of Frags by composition.
+
+```python
+users = UserRegistry()
+admins = await users.with_role('admin').all()
+```
+
+### Storage
+**SQLite**, **PostgreSQL**, **YAML**, **Env** backends.
+
+```python
+storage = StorageManager.get('sqlite', db_path='app.db')
+await storage.save(frag)
+```
+
+---
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+---
+
+## Testing
+
+```bash
+# All tests
+pytest
+
+# Core tests (no PostgreSQL)
+pytest --ignore=tests/frags/storage/test_postgresql_integration.py
+```
+
+**Expected:** 581 passing, 1 warning (JWT dev secret)
+
+---
+
+## Documentation
+
+- **Quick Start:** `QUICKSTART.md` - 5-minute introduction
+- **Glossary:** `GLOSSARY.md` - Complete terminology reference
+- **Handoff:** `HANDOFF.md` - Recent changes and architecture
+- **Examples:** `examples/pkm/` - Personal knowledge management app
+
+---
+
+## Project Structure
+
+```
+winterforge/
+├── frags/              # Frag core
+│   ├── base.py        # Frag class
+│   ├── registry.py    # FragRegistry
+│   ├── traits/        # Built-in traits
+│   └── registries/    # Specialized registries
+├── plugins/           # Plugin system
+│   ├── storage/       # Storage backends
+│   ├── identity/      # Identity resolvers
+│   └── managers/      # Plugin managers
+└── cli/              # CLI commands
+```
+
+---
+
+## Built-in Traits
+
+- **titled** - title, subtitle
+- **sluggable** - URL slugs
+- **timestamped** - created_on, updated_on
+- **persistable** - save(), delete(), is_new()
+- **userable** - username, email, email_verified
+- **authenticatable** - password hashing
+- **authorizable** - roles, permissions
+- **sessionable** - session management
+
+---
+
+## CLI
+
+```bash
+# User management
+winterforge user create alice alice@example.com
+winterforge user add-role alice admin
+
+# Session management
+winterforge session create alice
+winterforge session verify <token>
+
+# Role/permission management
+winterforge role create admin "Admin role"
+winterforge permission create posts.create
+```
+
+---
+
+## Async-First
+
+**All I/O operations are async:**
+
+```python
+# Storage
+await storage.save(frag)
+frag = await storage.load(id)
+
+# Frags
+await frag.save()
+await frag.delete()
+
+# Registry
+frag = await registry.get(identity)
+all_frags = await registry.all()
+```
+
+**Sync wrapper (rare):**
+
+```python
+from winterforge.utils.sync import to_sync
+
+@to_sync
+async def create_user_sync(username, email):
+    users = UserRegistry()
+    return await users.create(username, email, 'password')
+
+user = create_user_sync('alice', 'alice@example.com')
+```
+
+---
+
+## Architecture
+
+- **Composition over inheritance** - Frags compose capabilities
+- **Plugin-based** - Extensible via decorators
+- **Async-first** - Modern Python standards
+- **Everything is a Frag** - Even CLI output
+
+---
+
+## Status
+
+**Version:** Pre-release (Phase 4 complete)
+**Tests:** 581 passing
+**Warnings:** 1 (expected)
+**Ready for:** Feature development
+
+---
+
+**WinterForge is async-first, composition-driven, and ready for production.**

winterforge-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[project]
+name = "winterforge"
+version = "0.1.0"
+description = "AI-native framework with composable primitives"
+authors = [{name = "Beau Simensen"}]
+requires-python = ">=3.10"
+dependencies = [
+    "typing-extensions>=4.0.0",
+    "asyncpg>=0.29.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+    "click>=8.1.7",
+    "argon2-cffi>=23.1.0",
+    "bcrypt>=4.1.2",
+    "PyJWT>=2.8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-asyncio>=0.21.0",
+    "mypy>=1.0.0",
+]
+
+[project.entry-points."winterforge.storage_backends"]
+yaml = "winterforge.plugins.storage.yaml:YamlStorageBackend"
+sqlite = "winterforge.plugins.storage.sqlite:SQLiteStorageBackend"
+postgresql = "winterforge.plugins.storage.postgresql:PostgreSQLStorageBackend"
+
+[project.entry-points."winterforge.identity_resolvers"]
+frag_id = "winterforge.plugins.identity.frag_id_resolver:FragIdResolver"
+slug = "winterforge.plugins.identity.slug_resolver:SlugResolver"
+title = "winterforge.plugins.identity.title_resolver:TitleIdentityResolver"
+uuid = "winterforge.plugins.identity.uuid_resolver:UuidResolver"
+email = "winterforge.plugins.identity.email_resolver:EmailIdentityResolver"
+username = "winterforge.plugins.identity.username_resolver:UsernameIdentityResolver"
+
+[project.entry-points."winterforge.frag_traits"]
+fieldable = "winterforge.frags.traits.fieldable:FieldableTrait"
+titled = "winterforge.frags.traits.titled:TitledTrait"
+typed = "winterforge.frags.traits.typed:TypedTrait"
+timestamped = "winterforge.frags.traits.timestamped:TimestampedTrait"
+sluggable = "winterforge.frags.traits.sluggable:SluggableTrait"
+persistable = "winterforge.frags.traits.persistable:PersistableTrait"
+userable = "winterforge.frags.traits.userable:UserableTrait"
+authenticatable = "winterforge.frags.traits.authenticatable:AuthenticatableTrait"
+authorizable = "winterforge.frags.traits.authorizable:AuthorizableTrait"
+sessionable = "winterforge.frags.traits.sessionable:SessionableTrait"
+tokenable = "winterforge.frags.traits.tokenable:TokenableTrait"
+permissioned = "winterforge.frags.traits.permissioned:PermissionedTrait"
+ownable = "winterforge.frags.traits.ownable:OwnableTrait"
+
+[project.entry-points."winterforge.dx.elements"]
+panel = "winterforge_dx_tools.elements.builder_panel:PanelElement"
+table = "winterforge_dx_tools.elements.builder_table:TableElement"
+progress = "winterforge_dx_tools.elements.builder_progress:ProgressElement"
+tree = "winterforge_dx_tools.elements.builder_tree:TreeElement"
+
+[project.scripts]
+winterforge = "winterforge.cli:cli"
+
+[build-system]
+requires = ["setuptools>=65.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["winterforge*"]
+exclude = ["tests*", "mandates*", "winterforge_data*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.coverage.run]
+source = ["winterforge"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

winterforge-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

winterforge-0.1.0/tests/test_acceptance.py

@@ -0,0 +1,331 @@
+"""
+Acceptance criteria validation tests.
+
+These tests validate that all acceptance criteria from the spec are met.
+"""
+
+import pytest
+from winterforge.plugins import (
+    storage_backend,
+    frag_trait,
+    deriver,
+    StorageManager,
+    FragTraitManager,
+    root,
+)
+
+
+class TestAcceptanceCriteria:
+    """Validate acceptance criteria from specification."""
+
+    def test_public_api_decorator_registration(self) -> None:
+        """
+        Acceptance: Public API works - decorator registration.
+
+        from winterforge.plugins import storage_backend, StorageManager
+
+        @storage_backend('test')
+        class TestBackend:
+            pass
+
+        backend = StorageManager.get('test')
+        assert backend is not None
+        """
+        StorageManager.reset()
+
+        @storage_backend()
+        @root('test-ac-1')
+        class TestBackend:
+            pass
+
+        backend = StorageManager.get('test-ac-1')
+        assert backend is not None
+        assert isinstance(backend, TestBackend)
+
+    def test_public_api_import_structure(self) -> None:
+        """
+        Acceptance: All components importable from top-level.
+        """
+        # Should be able to import everything from winterforge.plugins
+        from winterforge.plugins import (
+            PluginManagerBase,
+            plugin,
+            deriver,
+            storage_backend,
+            frag_trait,
+            identity_resolver,
+            StorageManager,
+            FragTraitManager,
+            IdentityResolverManager,
+            StorageBackend,
+            ReadOnlyStorage,
+            FragTrait,
+            IdentityResolverProvider,
+            discover_plugins,
+        )
+
+        # All imports successful
+        assert PluginManagerBase is not None
+        assert plugin is not None
+        assert deriver is not None
+        assert StorageManager is not None
+        assert ReadOnlyStorage is not None
+
+    def test_plugin_derivatives_work(self) -> None:
+        """
+        Acceptance: Plugin derivatives work.
+
+        from winterforge.plugins import deriver, StorageManager
+
+        @deriver('winterforge.storage_backends')
+        def test_deriver():
+            yield {'id': 'derived', 'class': object}
+
+        StorageManager.derive_plugins()
+        assert StorageManager.has('derived')
+        """
+        StorageManager.reset()
+
+        class DerivedClass:
+            pass
+
+        @deriver('winterforge.storage_backends')
+        def test_deriver_ac():
+            yield {'id': 'derived_ac', 'class': DerivedClass}
+
+        StorageManager.derive_plugins()
+        assert StorageManager.has('derived_ac')
+
+        instance = StorageManager.get('derived_ac')
+        assert isinstance(instance, DerivedClass)
+
+    def test_lazy_instantiation_with_caching(self) -> None:
+        """Acceptance: Lazy instantiation with caching works."""
+        StorageManager.reset()
+
+        instantiation_count = 0
+
+        @storage_backend()
+        @root('cached')
+        class CachedBackend:
+            def __init__(self):
+                nonlocal instantiation_count
+                instantiation_count += 1
+
+        # Not instantiated yet
+        assert instantiation_count == 0
+
+        # First access
+        instance1 = StorageManager.get('cached')
+        assert instantiation_count == 1
+
+        # Second access - cached
+        instance2 = StorageManager.get('cached')
+        assert instantiation_count == 1
+        assert instance1 is instance2
+
+    def test_metadata_support(self) -> None:
+        """Acceptance: Plugin metadata works."""
+        StorageManager.reset()
+
+        @storage_backend(description='Test', version='1.0')
+        @root('with-meta')
+        class MetaBackend:
+            pass
+
+        metadata = StorageManager.get_metadata('with-meta')
+        assert metadata['description'] == 'Test'
+        assert metadata['version'] == '1.0'
+
+    def test_manager_methods_work(self) -> None:
+        """Acceptance: All manager methods work correctly."""
+        StorageManager.reset()
+
+        @storage_backend()
+        @root('method-test')
+        class MethodTestBackend:
+            pass
+
+        # has()
+        assert StorageManager.has('method-test')
+
+        # get()
+        backend = StorageManager.get('method-test')
+        assert backend is not None
+
+        # get_definitions()
+        defs = StorageManager.get_definitions()
+        assert 'method-test' in defs
+
+        # get_metadata()
+        meta = StorageManager.get_metadata('method-test')
+        assert isinstance(meta, dict)
+
+        # clear_cache()
+        instance1 = StorageManager.get('method-test')
+        StorageManager.clear_cache()
+        instance2 = StorageManager.get('method-test')
+        assert instance1 is not instance2
+
+        # reset()
+        StorageManager.reset()
+        assert not StorageManager.has('method-test')
+
+    def test_trait_manager_get_trait_fields(self) -> None:
+        """Acceptance: FragTraitManager.get_trait_fields() works."""
+        FragTraitManager.reset()
+
+        class MockField:
+            pass
+
+        @frag_trait()
+        @root('fields-test')
+        class FieldsTrait:
+            # Use private attributes (new convention)
+            _field1 = MockField()
+            _field2 = MockField()
+
+        fields = FragTraitManager.get_trait_fields('fields-test')
+        assert '_field1' in fields
+        assert '_field2' in fields
+
+    def test_custom_instantiation_args(self) -> None:
+        """Acceptance: Custom instantiation args work (not cached)."""
+        StorageManager.reset()
+
+        @storage_backend()
+        @root('custom-args')
+        class CustomArgsBackend:
+            def __init__(self, value=None):
+                self.value = value
+
+        instance1 = StorageManager.get('custom-args', value='a')
+        instance2 = StorageManager.get('custom-args', value='b')
+
+        assert instance1.value == 'a'
+        assert instance2.value == 'b'
+        assert instance1 is not instance2
+
+    def test_all_plugin_types(self) -> None:
+        """Acceptance: All plugin types work."""
+        from winterforge.plugins import (
+            storage_backend,
+            frag_trait,
+            identity_resolver,
+            StorageManager,
+            FragTraitManager,
+            IdentityResolverManager,
+            root,
+        )
+
+        StorageManager.reset()
+        FragTraitManager.reset()
+        IdentityResolverManager.reset()
+
+        @storage_backend()
+        @root('storage-test')
+        class StorageTest:
+            pass
+
+        @frag_trait()
+        @root('trait-test')
+        class TraitTest:
+            pass
+
+        @identity_resolver()
+        @root('resolver-test')
+        class ResolverTest:
+            pass
+
+        assert StorageManager.has('storage-test')
+        assert FragTraitManager.has('trait-test')
+        assert IdentityResolverManager.has('resolver-test')
+
+    def test_error_handling(self) -> None:
+        """Acceptance: Proper error handling."""
+        StorageManager.reset()
+
+        # Duplicate registration is now idempotent (silently skips)
+        @storage_backend()
+        @root('dup-test')
+        class DupTest:
+            pass
+
+        # Second registration should silently succeed (idempotent)
+        StorageManager.register('dup-test', DupTest)
+        assert StorageManager.has('dup-test')
+
+        # Plugin not found
+        with pytest.raises(KeyError, match="not found"):
+            StorageManager.get('nonexistent')
+
+        # Trait not found
+        with pytest.raises(KeyError, match="not found"):
+            FragTraitManager.get_trait_fields('nonexistent')
+
+
+class TestIntegrationScenarios:
+    """Test real-world integration scenarios."""
+
+    def test_complete_workflow(self) -> None:
+        """Test complete plugin workflow from registration to use."""
+        StorageManager.reset()
+
+        # 1. Register a plugin
+        @storage_backend(description='Test workflow')
+        @root('workflow-test')
+        class WorkflowBackend:
+            def __init__(self):
+                self.saved_items = []
+
+            def save(self, item):
+                self.saved_items.append(item)
+
+        # 2. Check registration
+        assert StorageManager.has('workflow-test')
+
+        # 3. Get instance
+        backend = StorageManager.get('workflow-test')
+
+        # 4. Use plugin
+        backend.save('item1')
+        backend.save('item2')
+
+        # 5. Verify caching
+        backend2 = StorageManager.get('workflow-test')
+        assert backend is backend2
+        assert len(backend2.saved_items) == 2
+
+    def test_derivative_workflow(self) -> None:
+        """Test complete derivative workflow."""
+        StorageManager.reset()
+
+        # 1. Define base class
+        class DatabaseBackend:
+            def __init__(self, config=None):
+                self.config = config
+
+        # 2. Register deriver
+        @deriver('winterforge.storage_backends')
+        def db_deriver():
+            configs = {'primary': {'host': 'localhost'}, 'backup': {'host': 'remote'}}
+            for name, config in configs.items():
+                yield {
+                    'id': f'db_{name}',
+                    'class': DatabaseBackend,
+                    'metadata': {'config': config}
+                }
+
+        # 3. Derive plugins
+        StorageManager.derive_plugins()
+
+        # 4. Verify derived plugins exist
+        assert StorageManager.has('db_primary')
+        assert StorageManager.has('db_backup')
+
+        # 5. Use derived plugins
+        primary = StorageManager.get('db_primary')
+        backup = StorageManager.get('db_backup')
+
+        assert isinstance(primary, DatabaseBackend)
+        assert isinstance(backup, DatabaseBackend)