workstate-protocol 0.1.7__tar.gz → 0.2.1__tar.gz

{workstate_protocol-0.1.7 → workstate_protocol-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-protocol
-Version: 0.1.7
+Version: 0.2.1
 Summary: Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest.
 License: MIT
 Project-URL: Homepage, https://github.com/darce/workstate

{workstate_protocol-0.1.7 → workstate_protocol-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "workstate-protocol"
-version = "0.1.7"
+version = "0.2.1"
 description = "Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest."
 readme = "README.md"
 requires-python = ">=3.11"

{workstate_protocol-0.1.7 → workstate_protocol-0.2.1}/src/workstate_protocol/__init__.py

@@ -44,7 +44,7 @@ from .paths import (
 )
 from .skills import SkillManifest, SkillScope
 
-__version__ = "0.1.6"
+__version__ = "0.2.1"
 
 __all__ = [
     "ActiveTask",

{workstate_protocol-0.1.7 → workstate_protocol-0.2.1}/src/workstate_protocol/bootstrap.py

@@ -9,9 +9,18 @@ single typed shape rather than per-key heuristics.
 
 from __future__ import annotations
 
+from pathlib import PurePosixPath
 from typing import Annotated, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    WithJsonSchema,
+    field_validator,
+    model_validator,
+)
 
 
 Sha40 = Annotated[str, StringConstraints(pattern=r"^[0-9a-f]{40}$")]
@@ -20,6 +29,35 @@ PluginComponentName = Annotated[
     str,
     StringConstraints(pattern=r"^[A-Za-z0-9][A-Za-z0-9._-]*$"),
 ]
+PluginOverrideRelativePath = Annotated[
+    str,
+    StringConstraints(min_length=1),
+    WithJsonSchema(
+        {
+            "type": "string",
+            "minLength": 1,
+            "not": {
+                "anyOf": [
+                    {"pattern": "^/"},
+                    {"pattern": "(^|/)\\.\\.(/|$)"},
+                    {"pattern": "^\\.?$"},
+                    {"pattern": "\\\\"},
+                ]
+            },
+        }
+    ),
+]
+
+
+def _normalize_plugin_override_path(value: str) -> str:
+    if "\\" in value:
+        raise ValueError("override paths must use POSIX '/' separators")
+    path = PurePosixPath(value)
+    if path.is_absolute() or value == "." or ".." in path.parts:
+        raise ValueError(
+            "override paths must be relative and stay under the override root"
+        )
+    return path.as_posix()
 
 
 class OverlaySurface(BaseModel):
@@ -66,17 +104,31 @@ class PluginSkillOverride(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
-    mode: Literal["replace", "disable", "add"]
-    path: str | None = None
+    mode: Literal["replace", "patch", "disable", "add"]
+    path: PluginOverrideRelativePath | None = None
+    base_path: PluginOverrideRelativePath | None = None
     upstream_digest: Sha256Digest | None = None
     on_upstream_change: Literal["warn", "error", "ignore"] | None = None
 
+    @field_validator("path", "base_path")
+    @classmethod
+    def validate_override_paths(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return _normalize_plugin_override_path(value)
+
     @model_validator(mode="after")
     def validate_mode_fields(self) -> PluginSkillOverride:
-        if self.mode in {"replace", "add"} and not self.path:
-            raise ValueError("path is required when mode is replace or add")
-        if self.mode == "replace" and self.upstream_digest is None:
-            raise ValueError("upstream_digest is required when mode is replace")
+        if self.mode in {"replace", "patch", "add"} and not self.path:
+            raise ValueError("path is required when mode is replace, patch, or add")
+        if self.mode in {"replace", "patch"} and self.upstream_digest is None:
+            raise ValueError(
+                "upstream_digest is required when mode is replace or patch"
+            )
+        if self.mode == "patch" and not self.base_path:
+            raise ValueError("base_path is required when mode is patch")
+        if self.mode != "patch" and self.base_path is not None:
+            raise ValueError("base_path is only valid when mode is patch")
         return self
 
 
@@ -86,9 +138,16 @@ class PluginMcpServerOverride(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     mode: Literal["patch", "disable", "add"]
-    patch_path: str | None = None
+    patch_path: PluginOverrideRelativePath | None = None
     requires_trust_ack: bool = False
 
+    @field_validator("patch_path")
+    @classmethod
+    def validate_patch_path(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        return _normalize_plugin_override_path(value)
+
     @model_validator(mode="after")
     def validate_mode_fields(self) -> PluginMcpServerOverride:
         if self.mode in {"patch", "add"} and not self.patch_path:
@@ -182,6 +241,16 @@ class PluginMcpServerPatch(BaseModel):
     ops: list[PluginMcpPatchOperation] = Field(min_length=1)
 
 
+class PluginAcceptUpstreamProvenance(BaseModel):
+    """Recorded ``overrides accept-upstream`` event for one component."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    previous_upstream_digest: Sha256Digest
+    new_upstream_digest: Sha256Digest
+    accepted_at: str = Field(min_length=1)
+
+
 class PluginOverrideLockEntry(BaseModel):
     """Tracked provenance for one consumer-owned plugin override."""
 
@@ -191,8 +260,10 @@ class PluginOverrideLockEntry(BaseModel):
     name: PluginComponentName
     mode: Literal["replace", "disable", "add", "patch"]
     local_path: str | None = None
+    base_path: str | None = None
     patch_path: str | None = None
     upstream_digest: Sha256Digest | None = None
+    last_accept_upstream: PluginAcceptUpstreamProvenance | None = None
 
 
 class PluginOverrideLock(BaseModel):
@@ -213,9 +284,9 @@ class PluginEffectiveLockEntry(BaseModel):
 
     component_kind: Literal["skill", "command", "mcp_server"]
     name: PluginComponentName
-    mode: Literal["replace", "disable", "add", "patch"]
+    mode: Literal["replace", "disable", "add", "patch", "passthrough"]
     effective_digest: Sha256Digest
-    status: Literal["stale"] | None = None
+    status: Literal["stale", "merge_conflict"] | None = None
     override_path: str | None = None
     recorded_upstream_digest: Sha256Digest | None = None
     current_base_digest: Sha256Digest | None = None

{workstate_protocol-0.1.7 → workstate_protocol-0.2.1}/src/workstate_protocol.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workstate-protocol
-Version: 0.1.7
+Version: 0.2.1
 Summary: Typed cross-repo contracts for the Workstate system: handoff state, MCP I/O, hook events, skill manifests, bootstrap install manifest.
 License: MIT
 Project-URL: Homepage, https://github.com/darce/workstate

workstate_protocol-0.2.1/tests/test_plugin_override_schema.py

@@ -0,0 +1,330 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from workstate_protocol.bootstrap import (
+    PluginEffectiveLock,
+    PluginMcpServerPatch,
+    PluginOverrideLock,
+    PluginOverrideManifest,
+)
+
+
+def test_override_manifest_accepts_skill_and_mcp_components() -> None:
+    manifest = PluginOverrideManifest.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "components": {
+                "skills": {
+                    "branch-review": {
+                        "mode": "replace",
+                        "path": "skills/branch-review/SKILL.md",
+                        "upstream_digest": "sha256:" + "a" * 64,
+                        "on_upstream_change": "warn",
+                    },
+                    "review-parallel": {
+                        "mode": "disable",
+                    },
+                },
+                "mcp_servers": {
+                    "workstate-handoff-mcp": {
+                        "mode": "patch",
+                        "patch_path": "tools/mcp_servers.patch.yaml",
+                        "requires_trust_ack": True,
+                    }
+                },
+            },
+        }
+    )
+
+    assert manifest.plugin == "workstate-system"
+    assert manifest.components.skills["branch-review"].mode == "replace"
+    assert manifest.components.mcp_servers["workstate-handoff-mcp"].mode == "patch"
+
+
+def test_mcp_server_patch_accepts_typed_operations() -> None:
+    patch = PluginMcpServerPatch.model_validate(
+        {
+            "schema_version": 1,
+            "target_server": "workstate-handoff-mcp",
+            "ops": [
+                {"op": "replace_command", "value": "uvx"},
+                {
+                    "op": "replace_args",
+                    "value": ["mcp-workstate-handoff@0.11.4", "--profile", "consumer"],
+                },
+                {"op": "upsert_env", "name": "HANDOFF_PROFILE", "value": "consumer"},
+                {"op": "remove_env", "name": "LEGACY_FLAG"},
+            ],
+        }
+    )
+
+    assert [entry.op for entry in patch.ops] == [
+        "replace_command",
+        "replace_args",
+        "upsert_env",
+        "remove_env",
+    ]
+
+
+def test_mcp_server_patch_rejects_wildcard_and_unsupported_file_replacement() -> None:
+    with pytest.raises(ValidationError):
+        PluginMcpServerPatch.model_validate(
+            {
+                "schema_version": 1,
+                "target_server": "*",
+                "ops": [
+                    {
+                        "op": "replace_file",
+                        "path": "../../../tmp/override.sh",
+                        "value": "hacked",
+                    }
+                ],
+            }
+        )
+
+
+def test_lock_models_roundtrip() -> None:
+    override_lock = PluginOverrideLock.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "base_remote_sha": "b" * 40,
+            "components": [
+                {
+                    "component_kind": "skill",
+                    "name": "branch-review",
+                    "mode": "replace",
+                    "local_path": "skills/branch-review/SKILL.md",
+                    "upstream_digest": "sha256:" + "c" * 64,
+                }
+            ],
+        }
+    )
+    effective_lock = PluginEffectiveLock.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "base_remote_sha": "d" * 40,
+            "effective_root": ".workstate/generated/plugins/workstate-system/effective/claude",
+            "components": [
+                {
+                    "component_kind": "skill",
+                    "name": "branch-review",
+                    "mode": "replace",
+                    "effective_digest": "sha256:" + "e" * 64,
+                }
+            ],
+        }
+    )
+
+    assert (
+        PluginOverrideLock.model_validate_json(override_lock.model_dump_json())
+        == override_lock
+    )
+    assert (
+        PluginEffectiveLock.model_validate_json(effective_lock.model_dump_json())
+        == effective_lock
+    )
+
+
+def test_skill_patch_mode_roundtrip() -> None:
+    manifest = PluginOverrideManifest.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "components": {
+                "skills": {
+                    "branch-review": {
+                        "mode": "patch",
+                        "path": "skills/branch-review/SKILL.md",
+                        "base_path": "skills/branch-review/SKILL.base.md",
+                        "upstream_digest": "sha256:" + "a" * 64,
+                        "on_upstream_change": "warn",
+                    }
+                }
+            },
+        }
+    )
+
+    override = manifest.components.skills["branch-review"]
+    assert override.mode == "patch"
+    assert override.base_path == "skills/branch-review/SKILL.base.md"
+    assert (
+        PluginOverrideManifest.model_validate_json(manifest.model_dump_json())
+        == manifest
+    )
+
+
+def test_skill_patch_mode_requires_path_base_path_and_digest() -> None:
+    base = {
+        "mode": "patch",
+        "path": "skills/branch-review/SKILL.md",
+        "base_path": "skills/branch-review/SKILL.base.md",
+        "upstream_digest": "sha256:" + "a" * 64,
+    }
+    for missing in ("path", "base_path", "upstream_digest"):
+        payload = {key: value for key, value in base.items() if key != missing}
+        with pytest.raises(ValidationError):
+            PluginOverrideManifest.model_validate(
+                {
+                    "schema_version": 1,
+                    "plugin": "workstate-system",
+                    "components": {"skills": {"branch-review": payload}},
+                }
+            )
+
+
+def test_skill_non_patch_modes_reject_base_path() -> None:
+    with pytest.raises(ValidationError):
+        PluginOverrideManifest.model_validate(
+            {
+                "schema_version": 1,
+                "plugin": "workstate-system",
+                "components": {
+                    "skills": {
+                        "branch-review": {
+                            "mode": "replace",
+                            "path": "skills/branch-review/SKILL.md",
+                            "base_path": "skills/branch-review/SKILL.base.md",
+                            "upstream_digest": "sha256:" + "a" * 64,
+                        }
+                    }
+                },
+            }
+        )
+
+
+def test_override_manifest_rejects_paths_outside_override_root() -> None:
+    base_skill = {
+        "mode": "patch",
+        "path": "skills/branch-review/SKILL.md",
+        "base_path": "skills/branch-review/SKILL.base.md",
+        "upstream_digest": "sha256:" + "a" * 64,
+    }
+
+    for field, value in (
+        ("path", "../outside/SKILL.md"),
+        ("path", "/tmp/SKILL.md"),
+        ("base_path", "skills/../../outside.base.md"),
+    ):
+        payload = {**base_skill, field: value}
+        with pytest.raises(ValidationError):
+            PluginOverrideManifest.model_validate(
+                {
+                    "schema_version": 1,
+                    "plugin": "workstate-system",
+                    "components": {"skills": {"branch-review": payload}},
+                }
+            )
+
+    with pytest.raises(ValidationError):
+        PluginOverrideManifest.model_validate(
+            {
+                "schema_version": 1,
+                "plugin": "workstate-system",
+                "components": {
+                    "mcp_servers": {
+                        "workstate-handoff-mcp": {
+                            "mode": "patch",
+                            "patch_path": "../server.patch.yaml",
+                            "requires_trust_ack": True,
+                        }
+                    }
+                },
+            }
+        )
+
+
+def test_effective_lock_supports_merge_conflict_and_passthrough() -> None:
+    effective_lock = PluginEffectiveLock.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "base_remote_sha": "d" * 40,
+            "effective_root": ".workstate/generated/plugins/workstate-system/effective/claude",
+            "components": [
+                {
+                    "component_kind": "skill",
+                    "name": "branch-review",
+                    "mode": "patch",
+                    "effective_digest": "sha256:" + "e" * 64,
+                    "status": "merge_conflict",
+                    "override_path": "skills/branch-review/SKILL.md",
+                    "recorded_upstream_digest": "sha256:" + "f" * 64,
+                    "current_base_digest": "sha256:" + "0" * 64,
+                },
+                {
+                    "component_kind": "skill",
+                    "name": "scope",
+                    "mode": "passthrough",
+                    "effective_digest": "sha256:" + "1" * 64,
+                },
+            ],
+        }
+    )
+
+    statuses = [entry.status for entry in effective_lock.components]
+    modes = [entry.mode for entry in effective_lock.components]
+    assert statuses == ["merge_conflict", None]
+    assert modes == ["patch", "passthrough"]
+    assert (
+        PluginEffectiveLock.model_validate_json(effective_lock.model_dump_json())
+        == effective_lock
+    )
+
+
+def test_override_lock_accept_upstream_provenance_roundtrip() -> None:
+    override_lock = PluginOverrideLock.model_validate(
+        {
+            "schema_version": 1,
+            "plugin": "workstate-system",
+            "base_remote_sha": "b" * 40,
+            "components": [
+                {
+                    "component_kind": "skill",
+                    "name": "branch-review",
+                    "mode": "patch",
+                    "local_path": "skills/branch-review/SKILL.md",
+                    "base_path": "skills/branch-review/SKILL.base.md",
+                    "upstream_digest": "sha256:" + "c" * 64,
+                    "last_accept_upstream": {
+                        "previous_upstream_digest": "sha256:" + "9" * 64,
+                        "new_upstream_digest": "sha256:" + "c" * 64,
+                        "accepted_at": "2026-06-04T06:00:00Z",
+                    },
+                }
+            ],
+        }
+    )
+
+    entry = override_lock.components[0]
+    assert entry.last_accept_upstream is not None
+    assert entry.last_accept_upstream.new_upstream_digest == "sha256:" + "c" * 64
+    assert (
+        PluginOverrideLock.model_validate_json(override_lock.model_dump_json())
+        == override_lock
+    )
+
+
+def test_generated_schema_artifacts_include_plugin_override_models() -> None:
+    artifact_dir = Path(__file__).resolve().parent.parent / "schemas"
+    expected = {
+        "plugin-override-manifest.json": PluginOverrideManifest,
+        "plugin-override-lock.json": PluginOverrideLock,
+        "plugin-effective-lock.json": PluginEffectiveLock,
+        "plugin-mcp-server-patch.json": PluginMcpServerPatch,
+    }
+
+    for file_name, model in expected.items():
+        schema = model.model_json_schema()
+        assert "schema_version" in schema["properties"]
+
+        on_disk = artifact_dir / file_name
+        persisted = json.loads(on_disk.read_text())
+        assert "schema_version" in persisted["properties"]

workstate_protocol-0.1.7/tests/test_plugin_override_schema.py

@@ -1,145 +0,0 @@
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-import pytest
-from pydantic import ValidationError
-
-from workstate_protocol.bootstrap import (
-    PluginEffectiveLock,
-    PluginMcpServerPatch,
-    PluginOverrideLock,
-    PluginOverrideManifest,
-)
-
-
-def test_override_manifest_accepts_skill_and_mcp_components() -> None:
-    manifest = PluginOverrideManifest.model_validate(
-        {
-            "schema_version": 1,
-            "plugin": "workstate-system",
-            "components": {
-                "skills": {
-                    "branch-review": {
-                        "mode": "replace",
-                        "path": "skills/branch-review/SKILL.md",
-                        "upstream_digest": "sha256:" + "a" * 64,
-                        "on_upstream_change": "warn",
-                    },
-                    "review-parallel": {
-                        "mode": "disable",
-                    },
-                },
-                "mcp_servers": {
-                    "workstate-handoff-mcp": {
-                        "mode": "patch",
-                        "patch_path": "tools/mcp_servers.patch.yaml",
-                        "requires_trust_ack": True,
-                    }
-                },
-            },
-        }
-    )
-
-    assert manifest.plugin == "workstate-system"
-    assert manifest.components.skills["branch-review"].mode == "replace"
-    assert manifest.components.mcp_servers["workstate-handoff-mcp"].mode == "patch"
-
-
-def test_mcp_server_patch_accepts_typed_operations() -> None:
-    patch = PluginMcpServerPatch.model_validate(
-        {
-            "schema_version": 1,
-            "target_server": "workstate-handoff-mcp",
-            "ops": [
-                {"op": "replace_command", "value": "uvx"},
-                {
-                    "op": "replace_args",
-                    "value": ["mcp-workstate-handoff@0.11.4", "--profile", "consumer"],
-                },
-                {"op": "upsert_env", "name": "HANDOFF_PROFILE", "value": "consumer"},
-                {"op": "remove_env", "name": "LEGACY_FLAG"},
-            ],
-        }
-    )
-
-    assert [entry.op for entry in patch.ops] == [
-        "replace_command",
-        "replace_args",
-        "upsert_env",
-        "remove_env",
-    ]
-
-
-def test_mcp_server_patch_rejects_wildcard_and_unsupported_file_replacement() -> None:
-    with pytest.raises(ValidationError):
-        PluginMcpServerPatch.model_validate(
-            {
-                "schema_version": 1,
-                "target_server": "*",
-                "ops": [
-                    {
-                        "op": "replace_file",
-                        "path": "../../../tmp/override.sh",
-                        "value": "hacked",
-                    }
-                ],
-            }
-        )
-
-
-def test_lock_models_roundtrip() -> None:
-    override_lock = PluginOverrideLock.model_validate(
-        {
-            "schema_version": 1,
-            "plugin": "workstate-system",
-            "base_remote_sha": "b" * 40,
-            "components": [
-                {
-                    "component_kind": "skill",
-                    "name": "branch-review",
-                    "mode": "replace",
-                    "local_path": "skills/branch-review/SKILL.md",
-                    "upstream_digest": "sha256:" + "c" * 64,
-                }
-            ],
-        }
-    )
-    effective_lock = PluginEffectiveLock.model_validate(
-        {
-            "schema_version": 1,
-            "plugin": "workstate-system",
-            "base_remote_sha": "d" * 40,
-            "effective_root": ".workstate/generated/plugins/workstate-system/effective/claude",
-            "components": [
-                {
-                    "component_kind": "skill",
-                    "name": "branch-review",
-                    "mode": "replace",
-                    "effective_digest": "sha256:" + "e" * 64,
-                }
-            ],
-        }
-    )
-
-    assert PluginOverrideLock.model_validate_json(override_lock.model_dump_json()) == override_lock
-    assert PluginEffectiveLock.model_validate_json(effective_lock.model_dump_json()) == effective_lock
-
-
-def test_generated_schema_artifacts_include_plugin_override_models() -> None:
-    artifact_dir = Path(__file__).resolve().parent.parent / "schemas"
-    expected = {
-        "plugin-override-manifest.json": PluginOverrideManifest,
-        "plugin-override-lock.json": PluginOverrideLock,
-        "plugin-effective-lock.json": PluginEffectiveLock,
-        "plugin-mcp-server-patch.json": PluginMcpServerPatch,
-    }
-
-    for file_name, model in expected.items():
-        schema = model.model_json_schema()
-        assert "schema_version" in schema["properties"]
-
-        on_disk = artifact_dir / file_name
-        persisted = json.loads(on_disk.read_text())
-        assert "schema_version" in persisted["properties"]