s-skillkit 0.6.2__tar.gz → 0.6.3__tar.gz

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/CHANGELOG.md

@@ -4,6 +4,18 @@
 [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/); версионирование —
 [SemVer](https://semver.org/lang/ru/).
 
+## [0.6.3] - 2026-10-14
+
+### Added
+
+- Explicit owned-link migration into readable copies while preserving legitimate edits, deletions and reviewed untracked payload, with authenticated historical release baselines kept separate from current snapshots.
+- Bounded migration results report copied untracked paths. Shared source metadata/runtime remain unchanged; strict future updates still refuse local edits and unknown baselines.
+
+### Fixed
+
+- Verify completed migration agent, scope, project, Hub identity and historical manifest before accepting a repeated no-write migration.
+- Reject foreign bindings, metadata/runtime links and detected source/staging races; retain executable permissions when copying Linux helpers.
+
 ## [0.6.2] - 2026-10-14
 
 ### Fixed

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: s-skillkit
-Version: 0.6.2
+Version: 0.6.3
 Summary: Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs.
 Author: Dmitry
 License: MIT

s_skillkit-0.6.3/docs/edited-link-migration.md

@@ -0,0 +1,75 @@
+# Preserving an edited owned link as a readable copy
+
+`SkillStore.migrate_owned_link_to_copy` is an explicit offline operation for an
+existing owned provider link whose central-store payload contains legitimate
+local edits. Normal install/update/link behavior remains strict.
+
+```python
+result = store.migrate_owned_link_to_copy(
+    "demo",
+    trusted_release_manifest=authenticated_historical_inventory,
+    expected_version="1.2.3",
+    expected_commit_sha=historical_commit,
+    preserve_local_changes=True,
+    reviewed_untracked_paths=("notes.txt",),
+)
+assert result.link_kind == "copy"
+print(result.copied_untracked_paths, result.copied_untracked_count)
+```
+
+The caller obtains the exact historical inventory through an authenticated
+release authority and verifies its identity. Current source bytes, a current
+default branch, and an install bundle for a newer release are not historical
+authority. Legacy commit identifiers are compared exactly; this API does not
+fabricate or normalize them. Missing, mismatched, or unverifiable inventory is
+refused.
+
+Only an owned regular Hub store and its exact existing provider link are
+eligible. The version, commit, released hashes, file sizes and declared
+preserved paths must agree with the supplied historical inventory. Every
+untracked regular payload path requires an explicit finite reviewed allowlist;
+the default refuses untracked payload. Review these paths with the canonical
+content/secret gate before approving them. Runtime or auth-looking unknown
+files must not be approved as payload. This API does not infer new runtime
+exclusions or introduce a second secret classifier.
+
+The copy preserves current file contents, legitimate deletions and reviewed
+untracked files. The immutable `projection.baseline` records the historical
+release inventory. `migration_current_snapshot` separately records the bytes
+copied during this migration; it never replaces release authority. Subsequent
+install/update/link operations still report these local modifications and
+refuse overwrites, including when `force=True`.
+
+The central store, its metadata and its runtime state are unchanged. Canonical
+`PreservedPaths`, target policy and projection runtime roots exclude runtime
+and credentials from the new copy; runtime symlinks are refused. Metadata in
+the copy contains indexed release data and identity, excluding arbitrary
+auth/tool configuration. Runtime state remains at the original store and is
+not duplicated or moved. The caller must establish any later runtime
+projection separately through its approved runtime policy.
+
+Migration is bounded to 10,000 payload files and 64 MiB of actual bytes read
+and copied. Staging is a verified owned sibling. Link identity, source
+identity, metadata and payload hashes are checked again before the swap and
+after detaching the original link; failure restores that link. The operation
+does not adopt foreign links, unknown ordinary copies or changed bindings.
+Repeating a completed migration performs a verified no-write operation only
+when its original historical inventory, separate current snapshot, scope and
+source still agree. Normal `link_existing` retains its existing return contract.
+
+Recover unverifiable historical inventory from a verified pinned old release
+manifest/bundle, or review/export the original data manually. `force` and a
+snapshot of current edited bytes do not establish a missing release baseline.
+
+Completed-copy verification also checks the requested agent, scope, project,
+original Hub identity fields and historical manifest inventory/preserved paths.
+Editing those fields causes refusal without rewriting the copy or its source.
+
+Concurrency checks cover persistent link/source/staging changes at the tested
+checkpoints and restore the old link on detected pre-swap failures. The existing
+filesystem copy primitives do not provide an atomic no-follow file handle or an
+exclusive snapshot. These pre/post path and hash checks do not prevent a
+same-user writer from transiently replacing/reverting paths between checks, or
+changing data after the final check. Callers must serialize their own writers
+and inspect the final receipt; this API does not claim a filesystem transaction
+against arbitrary concurrent writers. Shared source data is never rewritten.

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s-skillkit"
-version = "0.6.2"
+version = "0.6.3"
 description = "Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs."
 readme = "README.md"
 license = { text = "MIT" }

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/skillkit/__init__.py

@@ -104,6 +104,7 @@ from skillkit.installer import (
     LinkKind,
     LocalPathSource,
     ManifestFile,
+    OwnedLinkMigrationResult,
     PathTraversalError,
     PreservedPaths,
     ProjectionKind,
@@ -155,6 +156,7 @@ __all__ = [
     "SkillInstaller",
     "InstallRequest",
     "InstallResult",
+    "OwnedLinkMigrationResult",
     "RemoveResult",
     "CredentialResolver",
     # запечатанный source-spec установки (T1)

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/skillkit/installer/__init__.py

@@ -97,6 +97,7 @@ from skillkit.installer.models import (
     LinkKind,
     LocalPathSource,
     ManifestFile,
+    OwnedLinkMigrationResult,
     ProjectionKind,
     RemoveResult,
     Scope,
@@ -119,6 +120,7 @@ __all__ = [
     "InstallManifest",
     "InstallRequest",
     "InstallResult",
+    "OwnedLinkMigrationResult",
     "LinkKind",
     "LocalPathSource",
     "ManifestFile",
@@ -762,6 +764,37 @@ class SkillStore:
         link = self._target.slug_dir(dir_name, project=project)
         return self._link_into_scope(link, store_dir, force=force, projection=projection)
 
+    def migrate_owned_link_to_copy(
+        self, dir_name: str, *, trusted_release_manifest: dict[str, Any],
+        expected_version: str, expected_commit_sha: str,
+        preserve_local_changes: bool = False, project: Path | None = None,
+        reviewed_untracked_paths: tuple[str, ...] = (),
+    ) -> OwnedLinkMigrationResult:
+        """Explicitly preserve edits while detaching an owned published-store link.
+
+        The caller supplies authenticated historical release inventory. Current
+        payload is recorded separately and never authorizes subsequent overwrites.
+        Source payload, metadata and runtime state remain unchanged.
+        """
+        from skillkit.installer.edited_projections import migrate_owned_link
+
+        if preserve_local_changes is not True:
+            raise ValueError("preserve_local_changes=True is required for this migration")
+        if (
+            not dir_name or dir_name in {".", ".."}
+            or dir_name != dir_name.strip() or dir_name.endswith(".")
+            or any(char in dir_name for char in "/\\:")
+        ):
+            raise ValueError("dir_name must be a single store directory name")
+        store_dir = self._store_path(dir_name)
+        return migrate_owned_link(
+            store_dir, self._target.slug_dir(dir_name, project=project), guard=self._guard,
+            trusted_release_manifest=trusted_release_manifest,
+            expected_version=expected_version, expected_commit_sha=expected_commit_sha,
+            target=self._target, project=project,
+            reviewed_untracked_paths=reviewed_untracked_paths,
+        )
+
     def migrate_scope(
         self, *, project: Path | None = None, dry_run: bool = False
     ) -> dict[str, list]:

s_skillkit-0.6.3/skillkit/installer/edited_projections.py

@@ -0,0 +1,302 @@
+"""Explicit owned-link migration; current edits never become release authority."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import stat
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from skillkit import linker
+from skillkit.installer.meta import (
+    PreservedPaths,
+    is_managed_dir,
+    read_meta,
+    stamp_ownership,
+    write_meta,
+)
+from skillkit.installer.models import OwnedLinkMigrationResult
+from skillkit.installer.ownership import PathGuard, same_path
+from skillkit.installer.projections import (
+    ProjectionConflict,
+    _baseline,
+    _ignored,
+    _index,
+    _raise_walk_error,
+    _validate_scope_state,
+)
+from skillkit.targets.base import AgentTarget
+
+_MAX_BYTES = 64 * 1024 * 1024
+_MAX_FILES = 10_000
+_MIGRATION = "owned-link-preserved-v1"
+
+
+def _snapshot(root: Path, preserved: PreservedPaths) -> dict[str, str]:
+    """Bound actual bytes read, including concurrent growth of individual files."""
+    result: dict[str, str] = {}
+    total = 0
+    for current, dirs, files in os.walk(root, followlinks=False, onerror=_raise_walk_error):
+        parent = Path(current)
+        for name in list(dirs):
+            path = parent / name
+            rel = path.relative_to(root).as_posix()
+            if linker.is_link(path):
+                raise ProjectionConflict("projection-runtime-link", (rel,))
+            if _ignored(rel, preserved):
+                dirs.remove(name)
+        for name in files:
+            path = parent / name
+            rel = path.relative_to(root).as_posix()
+            if linker.is_link(path) or not stat.S_ISREG(path.lstat().st_mode):
+                raise ProjectionConflict("projection-runtime-link", (rel,))
+            if _ignored(rel, preserved):
+                continue
+            if len(result) >= _MAX_FILES:
+                raise ProjectionConflict("projection-resource-limit", (rel,))
+            digest = hashlib.sha256()
+            with path.open("rb") as stream:
+                while chunk := stream.read(64 * 1024):
+                    total += len(chunk)
+                    if total > _MAX_BYTES:
+                        raise ProjectionConflict("projection-resource-limit", (rel,))
+                    digest.update(chunk)
+            result[rel] = digest.hexdigest()
+    return result
+
+
+def _identity(path: Path) -> tuple[int, int, int]:
+    info = path.lstat()
+    return info.st_dev, info.st_ino, info.st_mode
+
+
+def _regular_parents(path: Path) -> None:
+    if any(linker.is_link(parent) for parent in path.absolute().parents):
+        raise ProjectionConflict("projection-unmanaged-path")
+
+
+def _copy_snapshot(source: Path, destination: Path, expected: dict[str, str]) -> None:
+    total = 0
+    for rel, expected_hash in expected.items():
+        path = source / rel
+        target = destination / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if linker.is_link(path) or not stat.S_ISREG(path.lstat().st_mode):
+            raise ProjectionConflict("projection-source-changed", (rel,))
+        identity = _identity(path)
+        digest = hashlib.sha256()
+        with path.open("rb") as reader, target.open("xb") as writer:
+            while chunk := reader.read(64 * 1024):
+                total += len(chunk)
+                if total > _MAX_BYTES:
+                    raise ProjectionConflict("projection-resource-limit", (rel,))
+                digest.update(chunk)
+                writer.write(chunk)
+        if digest.hexdigest() != expected_hash or _identity(path) != identity:
+            raise ProjectionConflict("projection-source-changed", (rel,))
+        shutil.copystat(path, target, follow_symlinks=False)
+        if _identity(path) != identity or linker.is_link(path):
+            raise ProjectionConflict("projection-source-changed", (rel,))
+
+
+def migrate_owned_link(
+    store_dir: Path,
+    slot: Path,
+    *,
+    guard: PathGuard,
+    trusted_release_manifest: dict[str, Any],
+    expected_version: str,
+    expected_commit_sha: str,
+    target: AgentTarget,
+    reviewed_untracked_paths: tuple[str, ...],
+    project: Path | None,
+) -> OwnedLinkMigrationResult:
+    """Detach a verified owned link while retaining edits and old release hashes."""
+    _regular_parents(store_dir)
+    _regular_parents(slot)
+    metadata_path = store_dir / "_skill_meta.json"
+    if (
+        linker.is_link(store_dir)
+        or linker.is_link(metadata_path)
+        or not metadata_path.is_file()
+        or metadata_path.stat().st_size > 1024 * 1024
+        or not is_managed_dir(store_dir)
+        or not guard.inside_store(store_dir)
+    ):
+        raise ProjectionConflict("projection-unmanaged-path")
+    meta = read_meta(store_dir) or {}
+    manifest = meta.get("manifest")
+    if (
+        meta.get("source") != "hub"
+        or not isinstance(manifest, dict)
+        or not isinstance(trusted_release_manifest, dict)
+        or not expected_version
+        or not expected_commit_sha
+        or meta.get("version") != expected_version
+        or meta.get("commit_sha") != expected_commit_sha
+        or manifest.get("preserved_paths", [])
+        != trusted_release_manifest.get("preserved_paths", [])
+    ):
+        raise ProjectionConflict("projection-unverifiable-baseline")
+    declared = manifest.get("preserved_paths", [])
+    if not isinstance(declared, list) or not all(isinstance(x, str) and x for x in declared):
+        raise ProjectionConflict("projection-unverifiable-baseline")
+    preserved_paths = PreservedPaths.build(manifest, target)
+    historical = _index(trusted_release_manifest, preserved_paths, fingerprint=False)
+    if historical != _index(manifest, preserved_paths, fingerprint=False):
+        raise ProjectionConflict("projection-unverifiable-baseline")
+    inventory = []
+    for item in trusted_release_manifest["files"]:
+        entry = {key: item[key] for key in ("path", "sha256", "size") if key in item}
+        size = entry.get("size")
+        if size is not None and (type(size) is not int or size < 0):
+            raise ProjectionConflict("projection-unverifiable-baseline")
+        inventory.append(entry)
+    stored_sizes = {item["path"]: item.get("size") for item in manifest["files"]}
+    if any(item.get("size") != stored_sizes.get(item["path"]) for item in inventory):
+        raise ProjectionConflict("projection-unverifiable-baseline")
+    recorded = meta.get("projection_source_baseline")
+    if recorded is not None and historical != _index(recorded, preserved_paths, fingerprint=True):
+        raise ProjectionConflict("projection-unverifiable-baseline")
+    baseline = _baseline(historical)
+    source_identity = _identity(store_dir)
+    metadata_hash = hashlib.sha256((store_dir / "_skill_meta.json").read_bytes()).hexdigest()
+    _validate_scope_state(store_dir, preserved_paths)
+    before = _snapshot(store_dir, preserved_paths)
+    if "SKILL.md" not in before:
+        raise ProjectionConflict("projection-missing-entrypoint")
+    untracked = tuple(sorted(set(before) - set(historical)))
+    if (
+        not isinstance(reviewed_untracked_paths, tuple)
+        or len(reviewed_untracked_paths) > _MAX_FILES
+        or not all(isinstance(path, str) for path in reviewed_untracked_paths)
+        or len(set(reviewed_untracked_paths)) != len(reviewed_untracked_paths)
+        or set(reviewed_untracked_paths) != set(untracked)
+    ):
+        raise ProjectionConflict("projection-unreviewed-untracked-payload", untracked or (".",))
+
+    def verify_source() -> None:
+        _regular_parents(store_dir)
+        if (
+            linker.is_link(store_dir)
+            or linker.is_link(metadata_path)
+            or _identity(store_dir) != source_identity
+            or hashlib.sha256((store_dir / "_skill_meta.json").read_bytes()).hexdigest()
+            != metadata_hash
+            or _snapshot(store_dir, preserved_paths) != before
+        ):
+            raise ProjectionConflict("projection-source-changed")
+        _validate_scope_state(store_dir, preserved_paths)
+
+    if not linker.is_link(slot):
+        scope_metadata = slot / "_skill_meta.json"
+        if (
+            linker.is_link(scope_metadata)
+            or not scope_metadata.is_file()
+            or scope_metadata.stat().st_size > 1024 * 1024
+            or not is_managed_dir(slot)
+        ):
+            raise ProjectionConflict("projection-unmanaged-path")
+        previous = read_meta(slot) or {}
+        projection = previous.get("projection", {})
+        expected_identity = {key: meta.get(key) for key in (
+            "slug", "skill_id", "version", "commit_sha", "source",
+        )}
+        expected_identity.update(
+            agent=target.name, scope="project" if project else "global",
+            project=str(project) if project else None,
+        )
+        previous_manifest = previous.get("manifest")
+        if (
+            not isinstance(projection, dict)
+            or projection.get("migration") != _MIGRATION
+            or projection.get("kind") != "copy"
+            or not isinstance(projection.get("store_dir"), str)
+            or not same_path(Path(projection["store_dir"]), store_dir)
+            or projection.get("baseline") != baseline
+            or projection.get("source_revision") != expected_commit_sha
+            or projection.get("preserved_paths") != list(preserved_paths)
+            or previous.get("version") != expected_version
+            or previous.get("commit_sha") != expected_commit_sha
+            or any(previous.get(key) != value for key, value in expected_identity.items())
+            or not isinstance(previous_manifest, dict)
+            or previous_manifest.get("preserved_paths", []) != declared
+        ):
+            raise ProjectionConflict("projection-unverifiable-baseline")
+        if _index(previous_manifest, preserved_paths, fingerprint=False) != historical:
+            raise ProjectionConflict("projection-unverifiable-baseline")
+        previous_sizes = {}
+        for item in previous_manifest["files"]:
+            size = item.get("size")
+            if size is not None and (type(size) is not int or size < 0):
+                raise ProjectionConflict("projection-unverifiable-baseline")
+            previous_sizes[item["path"]] = size
+        if any(item.get("size") != previous_sizes.get(item["path"]) for item in inventory):
+            raise ProjectionConflict("projection-unverifiable-baseline")
+        expected = _index(
+            projection.get("migration_current_snapshot"), preserved_paths, fingerprint=True,
+        )
+        actual = _snapshot(slot, preserved_paths)
+        if actual != expected or actual != before:
+            raise ProjectionConflict("projection-local-modifications")
+        _validate_scope_state(slot, preserved_paths)
+        verify_source()
+        return OwnedLinkMigrationResult(untracked)
+
+    link_identity = _identity(slot)
+    raw_target = os.readlink(slot)
+
+    def verify_link(path: Path) -> None:
+        _regular_parents(path)
+        if (
+            not linker.is_link(path)
+            or _identity(path) != link_identity
+            or os.readlink(path) != raw_target
+            or not same_path(linker.link_target(path) or Path(), store_dir)
+            or not guard.is_ours(path, store_dir=store_dir)
+        ):
+            raise ProjectionConflict("projection-unmanaged-path")
+        verify_source()
+
+    verify_link(slot)
+    # Only identity and indexed release data enter the copy, never auth/tool config.
+    scope_meta = {
+        key: meta[key] for key in ("slug", "skill_id", "version", "commit_sha", "source")
+        if key in meta and isinstance(meta[key], (str, int, type(None)))
+    }
+    scope_meta.update(
+        agent=target.name, scope="project" if project else "global",
+        project=str(project) if project else None,
+        manifest={
+            "files": inventory,
+            "preserved_paths": declared,
+        },
+        projection={
+            "kind": "copy", "store_dir": str(store_dir),
+            "source_revision": expected_commit_sha, "preserved_paths": list(preserved_paths),
+            "baseline": baseline, "migration": _MIGRATION,
+            "migration_current_snapshot": _baseline(before),
+            "copied_untracked_paths": list(untracked),
+        },
+    )
+    staging = Path(tempfile.mkdtemp(prefix=f".{slot.name}.projection-stage-", dir=slot.parent))
+    try:
+        write_meta(staging, stamp_ownership(scope_meta))
+        _copy_snapshot(store_dir, staging, before)
+        if _snapshot(staging, preserved_paths) != before:
+            raise ProjectionConflict("projection-source-changed")
+        verify_link(slot)
+
+        def verify_swap(path: Path) -> None:
+            verify_link(path)
+            if _snapshot(staging, preserved_paths) != before:
+                raise ProjectionConflict("projection-source-changed")
+
+        guard.swap_in_scope(staging, slot, store_dir=store_dir, verify_entry=verify_swap)
+    finally:
+        if os.path.lexists(staging):
+            guard.destroy_in_scope(staging)
+    return OwnedLinkMigrationResult(untracked)

{s_skillkit-0.6.2 → s_skillkit-0.6.3}/skillkit/installer/models.py

@@ -27,6 +27,19 @@ Content = Literal["real", "stub"]
 Source = Literal["hub", "local-path", "git-url"]
 
 
+@dataclass(frozen=True)
+class OwnedLinkMigrationResult:
+    """A preserved-copy migration reports reviewed untracked paths, never contents."""
+
+    copied_untracked_paths: tuple[str, ...]
+    linked: bool = False
+    link_kind: Literal["copy"] = "copy"
+
+    @property
+    def copied_untracked_count(self) -> int:
+        return len(self.copied_untracked_paths)
+
+
 class ManifestFile(TypedDict, total=False):
     """Один файл install-манифеста: относительный путь + хеш + размер."""