winterforge 0.1.0__tar.gz → 0.2.0__tar.gz

winterforge-0.2.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: winterforge
+Version: 0.2.0
+Summary: AI-native framework with composable primitives
+Author: Beau Simensen
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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
+
+**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 → winterforge-0.2.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "winterforge"
-version = "0.1.0"
+version = "0.2.0"
 description = "AI-native framework with composable primitives"
+readme = "README.md"
 authors = [{name = "Beau Simensen"}]
 requires-python = ">=3.10"
 dependencies = [
@@ -31,11 +32,16 @@ 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.materials"]
+manager = "winterforge.materials.manager:Manager"
+registry = "winterforge.materials.registry:Registry"
+
+[project.entry-points."winterforge.named_compositions"]
+
 [project.entry-points."winterforge.frag_traits"]
 fieldable = "winterforge.frags.traits.fieldable:FieldableTrait"
 titled = "winterforge.frags.traits.titled:TitledTrait"
@@ -50,15 +56,18 @@ sessionable = "winterforge.frags.traits.sessionable:SessionableTrait"
 tokenable = "winterforge.frags.traits.tokenable:TokenableTrait"
 permissioned = "winterforge.frags.traits.permissioned:PermissionedTrait"
 ownable = "winterforge.frags.traits.ownable:OwnableTrait"
+has_permanence = "winterforge.plugins.traits.has_permanence:HasPermanenceTrait"
+material_state = "winterforge.plugins.traits.material_state:MaterialStateTrait"
+
 
-[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.entry-points."winterforge.decorator_scope_handlers"]
+class_solo = "winterforge.plugins.decorators.scope_handlers.class_solo:ClassSoloScopeHandler"
+function = "winterforge.plugins.decorators.scope_handlers.function:FunctionScopeHandler"
+method_in_decorated_class = "winterforge.plugins.decorators.scope_handlers.method_in_decorated_class:MethodInDecoratedClassScopeHandler"
+method_in_undecorated_class = "winterforge.plugins.decorators.scope_handlers.method_in_undecorated_class:MethodInUndecoratedClassScopeHandler"
 
 [project.scripts]
-winterforge = "winterforge.cli:cli"
+winterforge = "winterforge.plugins.cli.main:cli"
 
 [build-system]
 requires = ["setuptools>=65.0"]
@@ -66,7 +75,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["winterforge*"]
+include = ["winterforge", "winterforge.*"]
 exclude = ["tests*", "mandates*", "winterforge_data*"]
 
 [tool.pytest.ini_options]

{winterforge-0.1.0 → winterforge-0.2.0}/tests/test_acceptance.py

@@ -7,7 +7,7 @@ These tests validate that all acceptance criteria from the spec are met.
 import pytest
 from winterforge.plugins import (
     storage_backend,
-    frag_trait,
+    trait,
     deriver,
     StorageManager,
     FragTraitManager,
@@ -52,7 +52,7 @@ class TestAcceptanceCriteria:
             plugin,
             deriver,
             storage_backend,
-            frag_trait,
+            trait,
             identity_resolver,
             StorageManager,
             FragTraitManager,
@@ -178,7 +178,7 @@ class TestAcceptanceCriteria:
         class MockField:
             pass
 
-        @frag_trait()
+        @trait()
         @root('fields-test')
         class FieldsTrait:
             # Use private attributes (new convention)
@@ -210,7 +210,7 @@ class TestAcceptanceCriteria:
         """Acceptance: All plugin types work."""
         from winterforge.plugins import (
             storage_backend,
-            frag_trait,
+            trait,
             identity_resolver,
             StorageManager,
             FragTraitManager,
@@ -227,7 +227,7 @@ class TestAcceptanceCriteria:
         class StorageTest:
             pass
 
-        @frag_trait()
+        @trait()
         @root('trait-test')
         class TraitTest:
             pass

winterforge-0.2.0/tests/test_channel_debug.py

@@ -0,0 +1,44 @@
+"""Debug channel initialization."""
+import pytest
+from channels.primitives.channel import Channel
+
+
+@pytest.mark.asyncio
+async def test_channel_debug(storage):
+    """Debug why channels don't initialize properly."""
+    # Create channel
+    channel = Channel()
+
+    print(f"\nClass: {type(channel).__name__}")
+    print(f"\nMRO (first 10):")
+    for i, cls in enumerate(type(channel).__mro__[:10], 1):
+        print(f"  {i}. {cls.__name__}")
+        if hasattr(cls, '_initialize') and '_initialize' in cls.__dict__:
+            print(f"      ^ has _initialize()")
+        if hasattr(cls, '_ensure_schema') and '_ensure_schema' in cls.__dict__:
+            print(f"      ^ has _ensure_schema()")
+
+    # Check initialization
+    print(f"\nInitialization:")
+    print(f"  has _fieldable_data: {hasattr(channel, '_fieldable_data')}")
+    print(f"  _fieldable_data value: {getattr(channel, '_fieldable_data', 'NOT SET')}")
+    print(f"  has _schema_built: {hasattr(channel, '_schema_built')}")
+    print(f"  _schema_built value: {getattr(channel, '_schema_built', 'NOT SET')}")
+
+    # Try to set title
+    print(f"\nCalling set_title('Test')...")
+    try:
+        channel.set_title('Test')
+        print(f"  SUCCESS!")
+    except Exception as e:
+        print(f"  FAILED: {type(e).__name__}: {e}")
+
+        # Try calling _ensure_schema manually
+        print(f"\nTrying _ensure_schema() manually...")
+        if hasattr(channel, '_ensure_schema'):
+            channel._ensure_schema()
+            print(f"  _fieldable_data after: {getattr(channel, '_fieldable_data', 'NOT SET')}")
+
+            # Try set_title again
+            channel.set_title('Test')
+            print(f"  set_title succeeded after manual _ensure_schema!")

winterforge-0.2.0/tests/test_clone_debug.py

@@ -0,0 +1,37 @@
+"""Debug clone behavior."""
+import pytest
+from winterforge.frags.base import Frag
+
+
+@pytest.mark.asyncio
+async def test_clone_debug(storage):
+    """Debug why clone doesn't set history links."""
+    original = Frag(
+        traits=['titled', 'with_history']
+    )
+    original.set_title('Version 1')
+    await original.save()
+
+    # Check MRO
+    print(f"\nClass: {type(original).__name__}")
+    print(f"\nMRO:")
+    for i, cls in enumerate(type(original).__mro__, 1):
+        print(f"  {i}. {cls.__name__}")
+        if hasattr(cls, 'clone') and 'clone' in cls.__dict__:
+            print(f"      ^ has clone() method")
+
+    # Check which clone method we're calling
+    clone_method = getattr(original, 'clone')
+    print(f"\nclone method from: {clone_method.__qualname__ if hasattr(clone_method, '__qualname__') else 'unknown'}")
+
+    # Clone
+    print(f"\nCalling clone()...")
+    clone = original.clone()
+
+    # Check results
+    print(f"\nResults:")
+    print(f"  clone ID: {clone.id}")
+    print(f"  original.get_alias('history_next'): {original.get_alias('history_next')}")
+    print(f"  clone.get_alias('history_prev'): {clone.get_alias('history_prev')}")
+
+    assert original.get_alias('history_next') == str(clone.id)

{winterforge-0.1.0 → winterforge-0.2.0}/tests/test_e2e_integration.py

@@ -49,7 +49,6 @@ async def test_full_stack_integration(temp_paths):
     # Create Frag with multiple traits
     now = datetime.now(UTC).isoformat()
     frag = Frag(
-        affinities=['content', 'test'],
         traits=['fieldable', 'titled', 'timestamped', 'sluggable']
     )
 
@@ -83,7 +82,6 @@ async def test_multi_frag_composition(temp_paths):
 
     # Create parent Frag (author)
     author = Frag(
-        affinities=['author'],
         traits=['fieldable', 'titled']
     )
     author.set_title('Test Author')
@@ -91,7 +89,6 @@ async def test_multi_frag_composition(temp_paths):
 
     # Create child Frags (posts) linked via aliases
     post1 = Frag(
-        affinities=['post'],
         traits=['fieldable', 'titled'],
         aliases={'author': author.id}
     )
@@ -99,7 +96,6 @@ async def test_multi_frag_composition(temp_paths):
     await storage.save(post1)
 
     post2 = Frag(
-        affinities=['post'],
         traits=['fieldable', 'titled'],
         aliases={'author': author.id}
     )
@@ -170,13 +166,13 @@ async def test_fluent_interface(temp_paths):
 async def test_is_new_tracking(temp_paths):
     """Test is_new() through save/load cycle (persistable trait only)."""
 
-    from winterforge.frags.traits.persistable import set_storage
+    from winterforge.plugins.traits.persistable import set_storage
 
     storage = StorageManager.get('sqlite', db_path=str(temp_paths['db']))
     set_storage(storage)
 
     # Frag with persistable trait has is_new() tracking
-    frag = Frag(affinities=['test'], traits=['fieldable', 'titled', 'persistable'])
+    frag = Frag(traits=['fieldable', 'titled', 'persistable'])
 
     # New Frag starts as new (not yet in storage)
     assert await frag.is_new()
@@ -232,21 +228,18 @@ async def test_complex_query_patterns(temp_paths):
 
     # Create diverse Frags
     frag1 = Frag(
-        affinities=['post', 'published'],
         traits=['fieldable', 'titled']
     )
     frag1.set_title('Published Post')
     await storage.save(frag1)
 
     frag2 = Frag(
-        affinities=['post', 'draft'],
         traits=['fieldable', 'titled']
     )
     frag2.set_title('Draft Post')
     await storage.save(frag2)
 
     frag3 = Frag(
-        affinities=['page', 'published'],
         traits=['fieldable', 'titled']
     )
     frag3.set_title('Published Page')

{winterforge-0.1.0 → winterforge-0.2.0}/tests/test_initialization.py

@@ -4,7 +4,7 @@ import pytest
 import os
 from winterforge import async_initialize, async_shutdown, initialize, shutdown
 from winterforge.plugins.storage.manager import StorageManager
-from winterforge.frags.traits._manager import FragTraitManager
+from winterforge.plugins.traits import FragTraitManager
 from winterforge.plugins.identity.manager import IdentityResolverManager
 
 

winterforge-0.2.0/tests/test_is_dirty_debug.py

@@ -0,0 +1,41 @@
+"""Debug is_dirty behavior."""
+import pytest
+from winterforge.frags.base import Frag
+
+
+@pytest.mark.asyncio
+async def test_is_dirty_debug(storage):
+    """Debug why is_dirty isn't working."""
+    frag = Frag(traits=['is_dirty'])
+
+    # Check MRO
+    print(f"\nClass: {type(frag).__name__}")
+    print(f"\nMRO:")
+    for i, cls in enumerate(type(frag).__mro__, 1):
+        print(f"  {i}. {cls.__name__}")
+        if hasattr(cls, 'set') and 'set' in cls.__dict__:
+            print(f"      ^ has set() method")
+        if hasattr(cls, 'is_dirty') and 'is_dirty' in cls.__dict__:
+            print(f"      ^ has is_dirty() method")
+
+    # Test initial state
+    print(f"\nInitial state:")
+    print(f"  is_dirty(): {frag.is_dirty()}")
+    print(f"  _dirty attr: {getattr(frag, '_dirty', 'NOT SET')}")
+
+    # Check what set method we're calling
+    print(f"\nCalling set('duration', 0.5)...")
+    set_method = getattr(frag, 'set')
+    print(f"  set method type: {type(set_method)}")
+    print(f"  set method from: {set_method.__qualname__ if hasattr(set_method, '__qualname__') else 'unknown'}")
+
+    # Call set
+    frag.set('duration', 0.5)
+
+    # Check state after
+    print(f"\nAfter set:")
+    print(f"  is_dirty(): {frag.is_dirty()}")
+    print(f"  _dirty attr: {getattr(frag, '_dirty', 'NOT SET')}")
+    print(f"  _fields: {getattr(frag, '_fields', 'NOT SET')}")
+
+    assert frag.is_dirty() == True

winterforge-0.2.0/tests/test_kernel.py

@@ -0,0 +1,118 @@
+"""Smoke test for Kernel + Materials shape.
+
+Verifies the Kernel/Materials shape laid down by Phase 7 of the
+Great Collapse:
+- Kernel.build() is async and returns a composed Frag
+- Kernel.build() runs Material execute() to populate managers
+- Material State trait compiles a snapshot
+- Materials are registered with MaterialManager
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from winterforge.kernel import Kernel, _kernel_context
+from winterforge.materials import Manager, Registry
+from winterforge.plugins.materials import MaterialManager
+from winterforge.plugins.named_compositions import NamedCompositionManager
+
+
+@pytest.fixture(autouse=True)
+def _reset_kernel_context():
+    """Reset the Kernel ContextVar between tests."""
+    token = _kernel_context.set(None)
+    yield
+    _kernel_context.reset(token)
+
+
+class TestKernelShape:
+    """Verify Kernel/Materials shape."""
+
+    @pytest.mark.asyncio
+    async def test_kernel_build_returns_composed_frag(self) -> None:
+        kernel = await Kernel.build()
+
+        assert kernel is not None
+        assert 'is_application' in kernel.traits
+        assert 'persistable' in kernel.traits
+        assert 'material_state' in kernel.traits
+        assert 'has_permanence' in kernel.traits
+
+    @pytest.mark.asyncio
+    async def test_kernel_build_materializes_managers(self) -> None:
+        kernel = await Kernel.build()
+
+        assert hasattr(kernel, 'managers')
+        assert hasattr(kernel, '_managers')
+        assert len(kernel._managers) > 0
+
+    @pytest.mark.asyncio
+    async def test_kernel_material_state_snapshot(self) -> None:
+        kernel = await Kernel.build()
+
+        snapshot = kernel.material_state()
+        assert isinstance(snapshot, dict)
+        assert len(snapshot) > 0
+
+    @pytest.mark.asyncio
+    async def test_kernel_current_returns_same_instance(self) -> None:
+        kernel = await Kernel.build()
+        current = Kernel.current()
+
+        assert current is kernel
+
+    @pytest.mark.asyncio
+    async def test_kernel_current_returns_none_when_uncached(self) -> None:
+        # New contract: current() returns None when nothing cached.
+        # Build/rematerialize are explicit choices.
+        current = Kernel.current()
+
+        assert current is None
+
+    @pytest.mark.asyncio
+    async def test_kernel_clear_removes_non_permanent(self) -> None:
+        kernel = await Kernel.build()
+        assert len(kernel._managers) > 0
+
+        await kernel.clear()
+        # All auto-generated managers cleared.
+        for mgr in kernel._managers.values():
+            assert mgr.is_permanent
+
+    def test_kernel_sources_from_materials(self) -> None:
+        assert Kernel._buildable_sources == ['winterforge.materials']
+        assert Kernel._buildable_context is _kernel_context
+
+
+class TestMaterials:
+    """Verify Material registration."""
+
+    def test_material_manager_id(self) -> None:
+        assert MaterialManager.plugin_id() == 'winterforge.materials'
+
+    def test_manager_material_registered(self) -> None:
+        assert MaterialManager.has('manager')
+        plugin_class = MaterialManager._plugins['manager']
+        assert plugin_class is Manager
+
+    def test_registry_material_registered(self) -> None:
+        assert MaterialManager.has('registry')
+        plugin_class = MaterialManager._plugins['registry']
+        assert plugin_class is Registry
+
+    def test_manager_material_sources(self) -> None:
+        assert Manager._buildable_sources == [
+            'winterforge.plugin_managers'
+        ]
+
+    def test_registry_material_sources(self) -> None:
+        assert Registry._buildable_sources == [
+            'winterforge.named_compositions'
+        ]
+
+    def test_named_composition_manager_stub_registered(self) -> None:
+        assert (
+            NamedCompositionManager.plugin_id()
+            == 'winterforge.named_compositions'
+        )