functualize-tasks-local 0.1.0__tar.gz

functualize_tasks_local-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_tasks_local-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: functualize-tasks-local
+Version: 0.1.0
+Summary: Local state-backed task storage plugin for functualize
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: functualize-state<1.0.0,>=0.1.0
+Requires-Dist: functualize-tasks<1.0.0,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-tasks-local
+
+> **Status: Published** — Independently installable from PyPI.
+
+Local state-backed task storage plugin for functualize. Provides a `TaskProvider`
+implementation that persists tasks as JSON blobs in the active `StateBackend`,
+using keys prefixed with `tasks:`. Zero external dependencies beyond the
+functualize workspace packages — if you have a state backend registered, this
+plugin gives you a fully functional task queue with no additional infrastructure.
+
+## Installation
+
+```bash
+pip install functualize-tasks-local
+```
+
+## Quick Start
+
+```python
+from functualize_state import InMemoryState
+from functualize_tasks import TaskStatus
+from functualize_tasks_local import LocalTaskProvider
+
+# Create a provider backed by an in-memory state store
+backend = InMemoryState()
+provider = LocalTaskProvider(backend=backend)
+
+# Add a task and retrieve it
+task_id = provider.add("Deploy staging server")
+tasks = provider.list(status=TaskStatus.PENDING)
+print(tasks[0].title)  # "Deploy staging server"
+
+# Update status and clean up
+provider.update(task_id, status=TaskStatus.DONE)
+provider.delete(task_id)
+```
+
+## Features
+
+- **State-backed persistence** — delegates all storage to the active `StateBackend`, so tasks survive restarts when using a durable backend like SQLite
+- **Automatic plugin registration** — registers via the `functualize.tasks_providers` entry point with name `"local"`, no manual wiring required
+- **Full CRUD operations** — create, list, update, delete, and link tasks with filtering by status or title substring
+- **Zero external dependencies** — only depends on `functualize-tasks` and `functualize-state` from the workspace
+- **JSON serialization** — each task stored as a compact JSON blob under `tasks:{task_id}`, easily inspectable for debugging
+
+## API Reference
+
+Public classes exported by this plugin:
+
+- `LocalTaskProvider` — `TaskProvider` implementation that stores tasks in a `StateBackend` with `tasks:` key prefix. Methods: `add()`, `list()`, `update()`, `delete()`, `link()`
+- `LocalTasksPlugin` — Plugin entry point that resolves the active `StateBackend` from DI at boot and registers a `LocalTaskProvider` as the `TaskProvider` implementation
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-tasks-local/tests/ -v
+```

functualize_tasks_local-0.1.0/README.md

@@ -0,0 +1,59 @@
+# functualize-tasks-local
+
+> **Status: Published** — Independently installable from PyPI.
+
+Local state-backed task storage plugin for functualize. Provides a `TaskProvider`
+implementation that persists tasks as JSON blobs in the active `StateBackend`,
+using keys prefixed with `tasks:`. Zero external dependencies beyond the
+functualize workspace packages — if you have a state backend registered, this
+plugin gives you a fully functional task queue with no additional infrastructure.
+
+## Installation
+
+```bash
+pip install functualize-tasks-local
+```
+
+## Quick Start
+
+```python
+from functualize_state import InMemoryState
+from functualize_tasks import TaskStatus
+from functualize_tasks_local import LocalTaskProvider
+
+# Create a provider backed by an in-memory state store
+backend = InMemoryState()
+provider = LocalTaskProvider(backend=backend)
+
+# Add a task and retrieve it
+task_id = provider.add("Deploy staging server")
+tasks = provider.list(status=TaskStatus.PENDING)
+print(tasks[0].title)  # "Deploy staging server"
+
+# Update status and clean up
+provider.update(task_id, status=TaskStatus.DONE)
+provider.delete(task_id)
+```
+
+## Features
+
+- **State-backed persistence** — delegates all storage to the active `StateBackend`, so tasks survive restarts when using a durable backend like SQLite
+- **Automatic plugin registration** — registers via the `functualize.tasks_providers` entry point with name `"local"`, no manual wiring required
+- **Full CRUD operations** — create, list, update, delete, and link tasks with filtering by status or title substring
+- **Zero external dependencies** — only depends on `functualize-tasks` and `functualize-state` from the workspace
+- **JSON serialization** — each task stored as a compact JSON blob under `tasks:{task_id}`, easily inspectable for debugging
+
+## API Reference
+
+Public classes exported by this plugin:
+
+- `LocalTaskProvider` — `TaskProvider` implementation that stores tasks in a `StateBackend` with `tasks:` key prefix. Methods: `add()`, `list()`, `update()`, `delete()`, `link()`
+- `LocalTasksPlugin` — Plugin entry point that resolves the active `StateBackend` from DI at boot and registers a `LocalTaskProvider` as the `TaskProvider` implementation
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-tasks-local/tests/ -v
+```

functualize_tasks_local-0.1.0/examples/README.md

@@ -0,0 +1,11 @@
+# functualize-tasks-local Examples
+
+The local task provider: stores tasks in any `StateBackend`, so task lists persist wherever your state does.
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`todo_local/`](todo_local/) | `LocalTaskProvider` wired to a state backend, driven through the `Tasks` capability |
+
+```bash
+uv run pytest plugins/functualize-tasks-local/examples/ -v
+```

functualize_tasks_local-0.1.0/examples/todo_local/test_todo_local.py

@@ -0,0 +1,13 @@
+"""Tests for the todo_local example."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from todo_local import checklist
+
+
+def test_one_item_remains_open():
+    assert checklist(MagicMock()) == 1

functualize_tasks_local-0.1.0/examples/todo_local/todo_local.py

@@ -0,0 +1,27 @@
+"""Tasks stored in a state backend via LocalTaskProvider.
+
+Pairs the tasks domain with the state domain: tasks live wherever your
+StateBackend does (in-memory here; SQLite in production). In a real app
+`LocalTasksPlugin` wires this automatically at boot.
+"""
+
+from functualize_state.testing import InMemoryState
+from functualize_tasks import Tasks, TaskStatus
+from functualize_tasks_local import LocalTaskProvider
+
+from functualize.job import RunContext
+
+
+def checklist(rc: RunContext) -> int:
+    """Create a checklist and report how many items remain open."""
+    backend = InMemoryState()
+    tasks = Tasks(_provider=LocalTaskProvider(backend))
+
+    first = tasks.add("Write the report")
+    tasks.add("Review the report")
+
+    tasks.update(first, status=TaskStatus.DONE)
+
+    open_items = [t for t in tasks.list() if t.status is not TaskStatus.DONE]
+    rc.log(f"{len(open_items)} item(s) still open")
+    return len(open_items)

functualize_tasks_local-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "functualize-tasks-local"
+version = "0.1.0"
+description = "Local state-backed task storage plugin for functualize"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "functualize-tasks>=0.1.0,<1.0.0",
+    "functualize-state>=0.1.0,<1.0.0",
+]
+
+[project.entry-points."functualize.tasks_providers"]
+local = "functualize_tasks_local:LocalTasksPlugin"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.sources]
+functualize-tasks = { workspace = true }
+functualize-state = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_tasks_local"]

functualize_tasks_local-0.1.0/src/functualize_tasks_local/__init__.py

@@ -0,0 +1,13 @@
+"""Functualize Tasks Local Plugin — state-backed task storage.
+
+Provides a TaskProvider implementation that stores tasks in the active
+StateBackend using keys prefixed with ``tasks:``. Zero external dependencies.
+"""
+
+from functualize_tasks_local._plugin import LocalTasksPlugin
+from functualize_tasks_local._provider import LocalTaskProvider
+
+__all__ = [
+    "LocalTasksPlugin",
+    "LocalTaskProvider",
+]

functualize_tasks_local-0.1.0/src/functualize_tasks_local/_plugin.py

@@ -0,0 +1,79 @@
+"""Local Tasks Plugin — DI registration.
+
+Registers LocalTaskProvider as TaskProvider with the DI registry via
+app.provide(). Uses the active StateBackend for task storage with
+keys prefixed ``tasks:``.
+
+Registered via entry point ``functualize.tasks_providers`` with name "local".
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from functualize_state import StateBackend
+from functualize_tasks import TaskProvider
+
+from functualize_tasks_local._provider import LocalTaskProvider
+
+__all__ = ["LocalTasksPlugin"]
+
+logger = logging.getLogger(__name__)
+
+
+class LocalTasksPlugin:
+    """Plugin that registers a local StateBackend-backed TaskProvider.
+
+    At boot time (APP_READY), resolves the active StateBackend from the DI
+    registry, creates a LocalTaskProvider wrapping it, and registers the
+    provider as the TaskProvider implementation via app.provide().
+
+    Implements the plugin callable protocol expected by functualize's plugin
+    discovery system.
+    """
+
+    name: str = "tasks-local"
+    version: str = "0.1.0"
+    description: str = "Local state-backed TaskProvider using tasks: prefix"
+
+    def __init__(self) -> None:
+        self._provider: LocalTaskProvider | None = None
+
+    @property
+    def provider(self) -> LocalTaskProvider | None:
+        """The LocalTaskProvider instance (available after APP_READY)."""
+        return self._provider
+
+    def __call__(self, app: Any) -> None:
+        """Register the plugin with the application instance.
+
+        Hooks into APP_READY for initialization and DI registration.
+        """
+        from functualize._events.hooks import HookEvent
+
+        app.hook_registry.register_global(HookEvent.APP_READY, self._on_app_ready)
+
+    def _on_app_ready(self, app: Any) -> None:
+        """Initialize LocalTaskProvider and register with DI registry.
+
+        Resolves the StateBackend from the DI registry and creates a
+        LocalTaskProvider backed by it. Registers the provider as
+        TaskProvider via app.provide().
+        """
+        try:
+            # Resolve the active StateBackend from DI
+            backend = app.resolve(StateBackend)
+
+            # Create local provider backed by the state backend
+            self._provider = LocalTaskProvider(backend=backend)
+
+            # Register as TaskProvider
+            app.provide(TaskProvider, self._provider)
+
+            logger.debug(
+                "LocalTasksPlugin: Registered TaskProvider (state-backed, "
+                "prefix='tasks:')"
+            )
+        except Exception as e:
+            logger.error("LocalTasksPlugin: Failed to initialize: %s", e)

functualize_tasks_local-0.1.0/src/functualize_tasks_local/_provider.py

@@ -0,0 +1,162 @@
+"""Local TaskProvider implementation backed by StateBackend.
+
+Stores tasks as JSON in the active StateBackend using keys prefixed with
+``tasks:``. Each task is stored under ``tasks:{task_id}`` as a JSON-encoded
+dict containing all TaskItem fields.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from typing import TYPE_CHECKING
+
+from functualize_tasks import TaskItem, TaskLink, TaskNotFoundError, TaskStatus
+
+if TYPE_CHECKING:
+    from functualize_state import StateBackend
+
+
+class LocalTaskProvider:
+    """TaskProvider implementation using StateBackend with ``tasks:`` prefix.
+
+    Each task is stored as a JSON blob under the key ``tasks:{task_id}``.
+    Listing operations scan all keys with the ``tasks:`` prefix and
+    deserialize them for filtering.
+    """
+
+    PREFIX = "tasks:"
+
+    def __init__(self, backend: StateBackend) -> None:
+        self._backend = backend
+
+    def _task_key(self, task_id: str) -> str:
+        """Return the full state key for a task ID."""
+        return f"{self.PREFIX}{task_id}"
+
+    def _serialize_task(self, task: TaskItem) -> str:
+        """Serialize a TaskItem to JSON string."""
+        data: dict = {
+            "id": task.id,
+            "title": task.title,
+            "status": task.status.value,
+            "linked_to": None,
+            "notes": task.notes,
+            "creator": task.creator,
+            "created_at": task.created_at,
+        }
+        if task.linked_to is not None:
+            data["linked_to"] = {
+                "kind": task.linked_to.kind,
+                "target": task.linked_to.target,
+            }
+        return json.dumps(data)
+
+    def _deserialize_task(self, raw: str) -> TaskItem:
+        """Deserialize a JSON string to a TaskItem."""
+        data = json.loads(raw)
+        linked_to = None
+        if data.get("linked_to") is not None:
+            linked_to = TaskLink(
+                kind=data["linked_to"]["kind"],
+                target=data["linked_to"]["target"],
+            )
+        return TaskItem(
+            id=data["id"],
+            title=data["title"],
+            status=TaskStatus(data["status"]),
+            linked_to=linked_to,
+            notes=data.get("notes"),
+            creator=data.get("creator"),
+            created_at=data.get("created_at"),
+        )
+
+    def _get_task(self, task_id: str) -> TaskItem:
+        """Retrieve a task by ID, raising TaskNotFoundError if it doesn't exist."""
+        raw = self._backend.get(self._task_key(task_id))
+        if raw is None:
+            raise TaskNotFoundError(f"Task '{task_id}' not found")
+        return self._deserialize_task(raw)
+
+    def add(self, title: str, linked_to: TaskLink | None = None) -> str:
+        """Create a new task and return its generated unique ID."""
+        task_id = uuid.uuid4().hex[:12]
+        task = TaskItem(
+            id=task_id,
+            title=title,
+            status=TaskStatus.PENDING,
+            linked_to=linked_to,
+            notes=None,
+            creator=None,
+            created_at=time.time(),
+        )
+        self._backend.set(self._task_key(task_id), self._serialize_task(task))
+        return task_id
+
+    def list(
+        self, status: TaskStatus | None = None, filter: str | None = None
+    ) -> list[TaskItem]:
+        """List tasks, optionally filtered by status or title substring."""
+        keys = self._backend.keys(self.PREFIX)
+        tasks: list[TaskItem] = []
+        for key in keys:
+            raw = self._backend.get(key)
+            if raw is None:
+                continue
+            task = self._deserialize_task(raw)
+            if status is not None and task.status != status:
+                continue
+            if filter is not None and filter not in task.title:
+                continue
+            tasks.append(task)
+        return tasks
+
+    def update(
+        self, task_id: str, status: TaskStatus | None = None, notes: str | None = None
+    ) -> None:
+        """Update a task's status and/or notes.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        task = self._get_task(task_id)
+        # Build updated task (TaskItem is frozen, so we reconstruct)
+        updated = TaskItem(
+            id=task.id,
+            title=task.title,
+            status=status if status is not None else task.status,
+            linked_to=task.linked_to,
+            notes=notes if notes is not None else task.notes,
+            creator=task.creator,
+            created_at=task.created_at,
+        )
+        self._backend.set(self._task_key(task_id), self._serialize_task(updated))
+
+    def delete(self, task_id: str) -> None:
+        """Delete a task by its ID.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        # Verify existence first
+        self._get_task(task_id)
+        self._backend.delete(self._task_key(task_id))
+
+    def link(self, task_id: str, linked_to: TaskLink) -> None:
+        """Associate a task with a job, workflow step, or job phase.
+
+        Raises:
+            TaskNotFoundError: If the task_id does not exist.
+        """
+        task = self._get_task(task_id)
+        updated = TaskItem(
+            id=task.id,
+            title=task.title,
+            status=task.status,
+            linked_to=linked_to,
+            notes=task.notes,
+            creator=task.creator,
+            created_at=task.created_at,
+        )
+        self._backend.set(self._task_key(task_id), self._serialize_task(updated))

functualize_tasks_local-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared fixtures for functualize-tasks-local plugin tests."""

functualize_tasks_local-0.1.0/tests/test_local_provider.py

@@ -0,0 +1,97 @@
+"""Functional tests for LocalTaskProvider.
+
+Tests local store/retrieve tasks, list filtering, and state persistence
+via InMemoryState fixture.
+"""
+
+from __future__ import annotations
+
+import pytest
+from functualize_state import InMemoryState
+from functualize_tasks import TaskLink, TaskNotFoundError, TaskStatus
+from functualize_tasks_local import LocalTaskProvider
+
+
+@pytest.fixture
+def backend() -> InMemoryState:
+    """Provide a fresh InMemoryState backend for each test."""
+    return InMemoryState()
+
+
+@pytest.fixture
+def provider(backend: InMemoryState) -> LocalTaskProvider:
+    """Provide a LocalTaskProvider backed by InMemoryState."""
+    return LocalTaskProvider(backend=backend)
+
+
+class TestStoreAndRetrieve:
+    """Tests for adding and listing tasks."""
+
+    def test_add_task_returns_id_and_persists(
+        self, provider: LocalTaskProvider
+    ) -> None:
+        """Adding a task returns a unique ID and is retrievable via list."""
+        task_id = provider.add("Deploy service")
+
+        assert task_id is not None
+        assert len(task_id) == 12  # uuid4 hex[:12]
+
+        tasks = provider.list()
+        assert len(tasks) == 1
+        assert tasks[0].id == task_id
+        assert tasks[0].title == "Deploy service"
+        assert tasks[0].status == TaskStatus.PENDING
+
+    def test_add_task_with_link(self, provider: LocalTaskProvider) -> None:
+        """Adding a task with a TaskLink persists the link correctly."""
+        link = TaskLink(kind="job", target="deploy-job")
+        provider.add("Linked task", linked_to=link)
+
+        tasks = provider.list()
+        assert len(tasks) == 1
+        assert tasks[0].linked_to is not None
+        assert tasks[0].linked_to.kind == "job"
+        assert tasks[0].linked_to.target == "deploy-job"
+
+
+class TestListFiltering:
+    """Tests for filtering tasks by status and title substring."""
+
+    def test_filter_by_status(self, provider: LocalTaskProvider) -> None:
+        """Listing with a status filter returns only matching tasks."""
+        id1 = provider.add("Task A")
+        id2 = provider.add("Task B")
+        provider.update(id1, status=TaskStatus.DONE)
+
+        pending = provider.list(status=TaskStatus.PENDING)
+        done = provider.list(status=TaskStatus.DONE)
+
+        assert len(pending) == 1
+        assert pending[0].id == id2
+        assert len(done) == 1
+        assert done[0].id == id1
+
+    def test_filter_by_title_substring(self, provider: LocalTaskProvider) -> None:
+        """Listing with a filter string returns only tasks whose title contains it."""
+        provider.add("Deploy service")
+        provider.add("Run migrations")
+        provider.add("Deploy database")
+
+        results = provider.list(filter="Deploy")
+        assert len(results) == 2
+        titles = {t.title for t in results}
+        assert titles == {"Deploy service", "Deploy database"}
+
+
+class TestErrorHandling:
+    """Tests for error cases and proper exception raising."""
+
+    def test_update_nonexistent_task_raises(self, provider: LocalTaskProvider) -> None:
+        """Updating a task that doesn't exist raises TaskNotFoundError."""
+        with pytest.raises(TaskNotFoundError):
+            provider.update("nonexistent-id", status=TaskStatus.DONE)
+
+    def test_delete_nonexistent_task_raises(self, provider: LocalTaskProvider) -> None:
+        """Deleting a task that doesn't exist raises TaskNotFoundError."""
+        with pytest.raises(TaskNotFoundError):
+            provider.delete("nonexistent-id")

functualize_tasks_local-0.1.0/tests/test_plugin.py

@@ -0,0 +1,15 @@
+"""Unit tests for functualize-tasks-local plugin.
+
+Tests the local task runner implementation.
+"""
+
+from __future__ import annotations
+
+
+class TestImports:
+    """Verify the plugin is importable."""
+
+    def test_import_package(self):
+        import functualize_tasks_local
+
+        assert dir(functualize_tasks_local)