windcode 0.1.0__py3-none-any.whl

windcode/extensions/models.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+
+class ExtensionScope(StrEnum):
+    BUILTIN = "builtin"
+    USER = "user"
+    PROJECT = "project"
+    RUN = "run"
+
+
+SCOPE_RANK = {scope: rank for rank, scope in enumerate(ExtensionScope)}
+
+
+class CapabilityKind(StrEnum):
+    SKILL = "skill"
+    MCP_SERVER = "mcp_server"
+    MCP_TOOL = "mcp_tool"
+    MCP_RESOURCE = "mcp_resource"
+    MCP_PROMPT = "mcp_prompt"
+    HOOK = "hook"
+    COMMAND = "command"
+    PLUGIN = "plugin"
+
+
+class DiagnosticStage(StrEnum):
+    DISCOVER = "discover"
+    PARSE = "parse"
+    VALIDATE = "validate"
+    MERGE = "merge"
+    INSTALL = "install"
+    ACTIVATE = "activate"
+    EXECUTE = "execute"
+    CLOSE = "close"
+
+
+class DiagnosticSeverity(StrEnum):
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+class ActivationState(StrEnum):
+    INACTIVE = "inactive"
+    UNTRUSTED = "untrusted"
+    AVAILABLE = "available"
+    ACTIVE = "active"
+    FAILED = "failed"
+
+
+_ID_PART = re.compile(r"^[a-z0-9][a-z0-9_.-]*$")
+
+
+def normalize_id(value: str) -> str:
+    normalized = value.strip().lower().replace(" ", "-")
+    if not _ID_PART.fullmatch(normalized):
+        raise ValueError(f"invalid extension identifier: {value!r}")
+    return normalized
+
+
+def capability_id(kind: CapabilityKind, public_name: str, *, plugin_id: str | None = None) -> str:
+    name = normalize_id(public_name)
+    if plugin_id is None:
+        return f"{kind.value}:{name}"
+    return f"plugin:{normalize_id(plugin_id)}/{kind.value}/{name}"
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionSource:
+    scope: ExtensionScope
+    path: Path | None = None
+    plugin_id: str | None = None
+    component_id: str | None = None
+    digest: str | None = None
+
+    @property
+    def source_id(self) -> str:
+        if self.plugin_id is not None and self.component_id is not None:
+            return f"plugin:{normalize_id(self.plugin_id)}/{normalize_id(self.component_id)}"
+        label = str(self.path) if self.path is not None else "builtin"
+        return f"{self.scope.value}:{label}"
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionRequirement:
+    filesystem_read: bool = False
+    filesystem_write: bool = False
+    network: bool = False
+    process: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    stage: DiagnosticStage
+    severity: DiagnosticSeverity
+    category: str
+    message: str
+    source_id: str
+    suggestion: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityRecord:
+    capability_id: str
+    public_name: str
+    kind: CapabilityKind
+    source: ExtensionSource
+    enabled: bool = True
+    trusted: bool = True
+    required: bool = False
+    activation: ActivationState = ActivationState.AVAILABLE
+    permissions: PermissionRequirement = field(default_factory=PermissionRequirement)
+    shadowed_by: str | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    @property
+    def sort_key(self) -> tuple[int, str, str, str]:
+        return (
+            SCOPE_RANK[self.source.scope],
+            self.kind.value,
+            self.public_name,
+            self.source.source_id,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionSnapshot:
+    generation: int
+    config_fingerprint: str
+    capabilities: tuple[CapabilityRecord, ...] = ()
+    definitions: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.generation < 0:
+            raise ValueError("snapshot generation cannot be negative")
+        ordered = tuple(sorted(self.capabilities, key=lambda item: item.sort_key))
+        object.__setattr__(self, "capabilities", ordered)
+        object.__setattr__(self, "definitions", MappingProxyType(dict(self.definitions)))
+        object.__setattr__(
+            self,
+            "diagnostics",
+            tuple(
+                sorted(
+                    self.diagnostics,
+                    key=lambda item: (
+                        item.source_id,
+                        item.stage.value,
+                        item.severity.value,
+                        item.category,
+                    ),
+                )
+            ),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ManagementResult:
+    changed: bool
+    reload_required: bool
+    diagnostics: tuple[Diagnostic, ...] = ()

windcode/extensions/paths.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import os
+import stat
+from collections.abc import Iterator
+from pathlib import Path
+
+
+class PathBoundaryError(ValueError):
+    pass
+
+
+def resolve_beneath(root: Path, relative: str | Path, *, require_file: bool = False) -> Path:
+    root = root.expanduser().resolve(strict=True)
+    candidate_part = Path(relative)
+    if candidate_part.is_absolute() or ".." in candidate_part.parts:
+        raise PathBoundaryError(f"path escapes extension root: {relative}")
+    candidate = root.joinpath(candidate_part).resolve(strict=True)
+    if not candidate.is_relative_to(root):
+        raise PathBoundaryError(f"path escapes extension root: {relative}")
+    mode = candidate.stat().st_mode
+    if not (stat.S_ISREG(mode) or stat.S_ISDIR(mode)):
+        raise PathBoundaryError(f"unsupported extension file type: {relative}")
+    if require_file and not stat.S_ISREG(mode):
+        raise PathBoundaryError(f"extension path is not a regular file: {relative}")
+    return candidate
+
+
+def read_bounded(root: Path, relative: str | Path, *, max_bytes: int) -> bytes:
+    if max_bytes < 1:
+        raise ValueError("max_bytes must be positive")
+    path = resolve_beneath(root, relative, require_file=True)
+    with path.open("rb") as stream:
+        data = stream.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        raise PathBoundaryError(f"extension file exceeds {max_bytes} bytes: {relative}")
+    return data
+
+
+def scan_bounded(root: Path, *, max_depth: int, max_entries: int) -> Iterator[Path]:
+    if max_depth < 0 or max_entries < 1:
+        raise ValueError("invalid scan bounds")
+    resolved_root = root.expanduser().resolve(strict=True)
+    seen = 0
+    pending: list[tuple[Path, int]] = [(resolved_root, 0)]
+    while pending:
+        directory, depth = pending.pop()
+        with os.scandir(directory) as entries:
+            ordered = sorted(entries, key=lambda entry: entry.name)
+        child_directories: list[Path] = []
+        for entry in ordered:
+            seen += 1
+            if seen > max_entries:
+                raise PathBoundaryError(f"extension scan exceeds {max_entries} entries")
+            if entry.is_symlink():
+                continue
+            path = Path(entry.path)
+            mode = entry.stat(follow_symlinks=False).st_mode
+            if stat.S_ISREG(mode):
+                yield path
+            elif stat.S_ISDIR(mode) and depth < max_depth:
+                child_directories.append(path)
+            elif not stat.S_ISDIR(mode):
+                raise PathBoundaryError(f"unsupported extension file type: {path}")
+        pending.extend((path, depth + 1) for path in reversed(child_directories))
+
+
+def plugin_data_directory(data_root: Path, plugin_id: str) -> Path:
+    from windcode.extensions.models import normalize_id
+
+    return data_root.expanduser().resolve() / "plugin-data" / normalize_id(plugin_id)

windcode/extensions/plugins/__init__.py

@@ -0,0 +1,3 @@
+from windcode.extensions.plugins.manifest import PluginManifest, parse_plugin_manifest
+
+__all__ = ["PluginManifest", "parse_plugin_manifest"]

windcode/extensions/plugins/installer.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from uuid import uuid4
+
+from windcode.extensions.paths import PathBoundaryError, scan_bounded
+from windcode.extensions.plugins.manifest import PluginManifest, parse_plugin_manifest
+
+_IGNORED_PARTS = {".git", ".hg", ".svn", "__pycache__", ".pytest_cache", ".mypy_cache"}
+
+
+@dataclass(frozen=True, slots=True)
+class InstallResult:
+    manifest: PluginManifest
+    digest: str
+    destination: Path
+    changed: bool
+
+
+def _plugin_files(root: Path, *, max_entries: int = 10_000) -> tuple[Path, ...]:
+    files = (
+        path
+        for path in scan_bounded(root, max_depth=32, max_entries=max_entries)
+        if not any(part in _IGNORED_PARTS for part in path.relative_to(root).parts)
+    )
+    return tuple(sorted(files, key=lambda path: path.relative_to(root).as_posix()))
+
+
+def plugin_digest(root: Path) -> str:
+    root = root.expanduser().resolve(strict=True)
+    digest = hashlib.sha256()
+    for path in _plugin_files(root):
+        relative = path.relative_to(root).as_posix().encode()
+        digest.update(len(relative).to_bytes(8, "big"))
+        digest.update(relative)
+        with path.open("rb") as stream:
+            while block := stream.read(1024 * 1024):
+                digest.update(block)
+    return digest.hexdigest()
+
+
+def install_local_plugin(source: Path, plugins_root: Path) -> InstallResult:
+    source = source.expanduser().resolve(strict=True)
+    manifest = parse_plugin_manifest(source)
+    digest = plugin_digest(source)
+    plugin_root = plugins_root.expanduser().resolve() / manifest.plugin_id
+    destination = plugin_root / digest
+    if destination.exists():
+        return InstallResult(manifest, digest, destination, False)
+    if plugin_root.exists():
+        for installed in plugin_root.iterdir():
+            if not installed.is_dir():
+                continue
+            try:
+                existing = parse_plugin_manifest(installed)
+            except ValueError:
+                continue
+            if existing.version == manifest.version and installed.name != digest:
+                raise ValueError(
+                    f"plugin {manifest.plugin_id} version {manifest.version} has different content"
+                )
+    plugin_root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    temporary = plugin_root / f".tmp-{uuid4().hex}"
+    temporary.mkdir(mode=0o700)
+    try:
+        for path in _plugin_files(source):
+            relative = path.relative_to(source)
+            target = temporary / relative
+            target.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            shutil.copyfile(path, target, follow_symlinks=False)
+        if plugin_digest(temporary) != digest:
+            raise PathBoundaryError("plugin content changed during installation")
+        parse_plugin_manifest(temporary)
+        for directory, _, files in os.walk(temporary):
+            for name in files:
+                descriptor = os.open(Path(directory) / name, os.O_RDONLY)
+                try:
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+        os.replace(temporary, destination)
+        directory_fd = os.open(plugin_root, os.O_RDONLY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        shutil.rmtree(temporary, ignore_errors=True)
+    return InstallResult(manifest, digest, destination, True)

windcode/extensions/plugins/manifest.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+from windcode.extensions.models import normalize_id
+from windcode.extensions.paths import PathBoundaryError, read_bounded, resolve_beneath
+
+MANIFEST_PATH = Path(".windcode-plugin/plugin.toml")
+_VERSION = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$")
+_ALLOWED = {
+    "manifest_version",
+    "id",
+    "name",
+    "version",
+    "windcode",
+    "required",
+    "skills",
+    "hooks",
+    "commands",
+    "mcp_servers",
+    "permissions",
+    "data",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class PluginComponent:
+    component_id: str
+    path: str
+
+
+@dataclass(frozen=True, slots=True)
+class PluginCommand:
+    name: str
+    target: str
+
+
+@dataclass(frozen=True, slots=True)
+class PluginManifest:
+    manifest_version: int
+    plugin_id: str
+    name: str
+    version: str
+    windcode: str
+    required: bool
+    skills: tuple[PluginComponent, ...]
+    hooks: tuple[PluginComponent, ...]
+    mcp_servers: tuple[PluginComponent, ...]
+    commands: tuple[PluginCommand, ...]
+    effects: tuple[str, ...]
+    network_hosts: tuple[str, ...]
+    persistent_data: bool
+    root: Path
+
+
+def _components(root: Path, raw: object, label: str) -> tuple[PluginComponent, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ValueError(f"{label} must be an array")
+    result: list[PluginComponent] = []
+    seen: set[str] = set()
+    for value in cast(list[object], raw):
+        if not isinstance(value, dict):
+            raise ValueError(f"{label} entries must be tables")
+        item = cast(dict[str, object], value)
+        if set(item) != {"id", "path"}:
+            raise ValueError(f"{label} entries require only id and path")
+        component_id = normalize_id(str(item["id"]))
+        if component_id in seen:
+            raise ValueError(f"duplicate {label} id: {component_id}")
+        path = str(item["path"])
+        resolve_beneath(root, path)
+        seen.add(component_id)
+        result.append(PluginComponent(component_id, path))
+    return tuple(sorted(result, key=lambda item: item.component_id))
+
+
+def _mcp_components(root: Path, raw: object) -> tuple[PluginComponent, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, dict):
+        raise ValueError("mcp_servers must be a table")
+    return _components(
+        root,
+        [{"id": key, "path": value["path"]} for key, value in cast(dict[str, Any], raw).items()],
+        "mcp_servers",
+    )
+
+
+def _commands(raw: object) -> tuple[PluginCommand, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ValueError("commands must be an array")
+    result: list[PluginCommand] = []
+    seen: set[str] = set()
+    for value in cast(list[object], raw):
+        if not isinstance(value, dict):
+            raise ValueError("command entries must be tables")
+        item = cast(dict[str, object], value)
+        if set(item) != {"name", "target"}:
+            raise ValueError("command entries require only name and target")
+        name = normalize_id(str(item["name"]))
+        target = str(item["target"])
+        if name in seen or not re.fullmatch(
+            r"(?:skill|prompt|capability):[a-z0-9][a-z0-9_.-]*", target
+        ):
+            raise ValueError(f"invalid or duplicate command: {name}")
+        seen.add(name)
+        result.append(PluginCommand(name, target))
+    return tuple(sorted(result, key=lambda item: item.name))
+
+
+def parse_plugin_manifest(root: Path, *, max_bytes: int = 65_536) -> PluginManifest:
+    root = root.expanduser().resolve(strict=True)
+    try:
+        raw = cast(
+            dict[str, object],
+            tomllib.loads(read_bounded(root, MANIFEST_PATH, max_bytes=max_bytes).decode("utf-8")),
+        )
+    except (UnicodeError, tomllib.TOMLDecodeError, PathBoundaryError) as exc:
+        raise ValueError(f"invalid plugin manifest: {exc}") from exc
+    unknown = set(raw) - _ALLOWED
+    if unknown:
+        raise ValueError(f"unknown manifest fields: {', '.join(sorted(unknown))}")
+    required_fields = {"manifest_version", "id", "name", "version", "windcode"}
+    missing = required_fields - set(raw)
+    if missing:
+        raise ValueError(f"missing manifest fields: {', '.join(sorted(missing))}")
+    if raw["manifest_version"] != 1:
+        raise ValueError("unsupported manifest version")
+    plugin_id = normalize_id(str(raw["id"]))
+    name, version, compatibility = str(raw["name"]), str(raw["version"]), str(raw["windcode"])
+    if not name.strip() or len(name) > 100 or not _VERSION.fullmatch(version):
+        raise ValueError("invalid plugin name or version")
+    if compatibility not in {">=0.1,<0.2", ">=0.1.0,<0.2.0", "*"}:
+        raise ValueError(f"incompatible Windcode version range: {compatibility}")
+    permissions = cast(dict[str, object], raw.get("permissions", {}))
+    if set(permissions) - {"effects", "network_hosts"}:
+        raise ValueError("unknown permissions fields")
+    data = cast(dict[str, object], raw.get("data", {}))
+    if set(data) - {"persistent"}:
+        raise ValueError("unknown data fields")
+    return PluginManifest(
+        1,
+        plugin_id,
+        name.strip(),
+        version,
+        compatibility,
+        bool(raw.get("required", False)),
+        _components(root, raw.get("skills"), "skills"),
+        _components(root, raw.get("hooks"), "hooks"),
+        _mcp_components(root, raw.get("mcp_servers")),
+        _commands(raw.get("commands")),
+        tuple(sorted(str(value) for value in cast(list[object], permissions.get("effects", [])))),
+        tuple(
+            sorted(str(value) for value in cast(list[object], permissions.get("network_hosts", [])))
+        ),
+        bool(data.get("persistent", False)),
+        root,
+    )