pz-cli 5.0.0__py3-none-any.whl

pz_core/authoring/dev_import.py

@@ -0,0 +1,1061 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+import hashlib
+import json
+import io
+import os
+import re
+from pathlib import Path, PurePosixPath
+import shutil
+import stat
+import subprocess
+import tarfile
+import tempfile
+import tomllib
+import uuid
+from urllib.parse import urlsplit, urlunsplit
+
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover - Windows
+    _fcntl = None
+
+try:
+    import msvcrt as _msvcrt
+except ImportError:  # pragma: no cover - POSIX
+    _msvcrt = None
+
+import tomlkit  # type: ignore[import-not-found]
+
+from pz_core.runtime.errors import PzError
+
+from .official_dev_sources import resolve_source_locator
+from .project_state import ensure_project_state, load_project_payload, save_project_payload
+from .workspace import iter_workspace_packages_in_roots
+
+
+_OWNER = "pz_core.authoring.dev_import"
+_REPO_KEY_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+_FULL_COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
+_CACHE_OWNER_FILE = ".pz-cache-owner.json"
+
+
+@dataclass(frozen=True, slots=True)
+class CachedGitSource:
+    repo_key: str
+    source: str
+    branch: str
+    checkout: Path
+    commit: str
+    resolution_ref: str
+
+
+@dataclass(frozen=True, slots=True)
+class ImportedApp:
+    app_id: str
+    destination: Path
+    subpath: PurePosixPath
+    commit: str
+    created: bool
+
+
+def _error(code: str, message: str, *, action: str, detail: str | None = None) -> PzError:
+    return PzError(
+        code=code,
+        message=message,
+        stage="dev",
+        owner=_OWNER,
+        action=action,
+        detail=detail,
+    )
+
+
+def _run_git(
+    *args: str,
+    cwd: Path | None,
+    action: str,
+    code: str = "PZ_DEV_CACHE_REFRESH_FAILED",
+) -> str:
+    completed = subprocess.run(
+        ("git", *args),
+        cwd=cwd,
+        check=False,
+        capture_output=True,
+        text=True,
+        stdin=subprocess.DEVNULL,
+        env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+    )
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "git command failed").strip()
+        detail = re.sub(
+            r"([A-Za-z][A-Za-z0-9+.-]*://)[^/@\s]+@",
+            r"\1<redacted>@",
+            detail,
+        )
+        raise _error(
+            code,
+            "无法准备开发源码 Git cache。",
+            action=action,
+            detail=detail[:500],
+        )
+    return completed.stdout.strip()
+
+
+def _canonical_remote(value: str) -> str:
+    raw = value.strip().rstrip("/")
+    if "://" not in raw and ":" in raw and not raw.startswith(("/", ".")):
+        user_host, path = raw.split(":", 1)
+        host = user_host.rsplit("@", 1)[-1].lower()
+        return f"ssh://{host}/{path.removesuffix('.git')}"
+    parsed = urlsplit(raw)
+    if parsed.scheme:
+        host = (parsed.hostname or "").lower()
+        if parsed.port is not None:
+            host = f"{host}:{parsed.port}"
+        return urlunsplit(
+            (parsed.scheme.lower(), host, parsed.path.rstrip("/").removesuffix(".git"), "", "")
+        )
+    return str(Path(raw).expanduser().resolve()).removesuffix(".git")
+
+
+def _cache_paths(repo_key: str) -> tuple[Path, Path]:
+    if not _REPO_KEY_RE.fullmatch(repo_key):
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache repo_key 只能包含字母、数字、下划线和连字符。",
+            action="dev_source_cache",
+            detail=repo_key,
+        )
+    user_key = f"uid-{os.getuid()}" if hasattr(os, "getuid") else "current-user"
+    root = Path(tempfile.gettempdir()) / "pz" / "users" / user_key / "git"
+    return root / repo_key, root / f".{repo_key}.lock"
+
+
+def _ensure_cache_root(root: Path, *, action: str) -> None:
+    root.mkdir(parents=True, mode=0o700, exist_ok=True)
+    if root.is_symlink() or not root.is_dir():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "当前用户的 Git cache 根目录不可信。",
+            action=action,
+            detail=str(root),
+        )
+    metadata = root.stat()
+    if hasattr(os, "getuid") and metadata.st_uid != os.getuid():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "当前用户不是 Git cache 根目录的所有者。",
+            action=action,
+            detail=str(root),
+        )
+    if stat.S_IMODE(metadata.st_mode) & 0o077:
+        root.chmod(0o700)
+
+
+@contextmanager
+def _repo_lock(path: Path, *, action: str):
+    _ensure_cache_root(path.parent, action=action)
+    if path.is_symlink():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache lock 不能是符号链接。",
+            action=action,
+            detail=str(path),
+        )
+    flags = os.O_CREAT | os.O_RDWR
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    try:
+        descriptor = os.open(path, flags, 0o600)
+    except OSError as exc:
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "无法安全打开 Git cache lock。",
+            action=action,
+            detail=str(path),
+        ) from exc
+    with os.fdopen(descriptor, "a+b") as lock:
+        metadata = os.fstat(lock.fileno())
+        if hasattr(os, "getuid") and metadata.st_uid != os.getuid():
+            raise _error(
+                "PZ_DEV_CACHE_INVALID",
+                "当前用户不是 Git cache lock 的所有者。",
+                action=action,
+                detail=str(path),
+            )
+        os.fchmod(lock.fileno(), 0o600)
+        if _fcntl is not None:
+            _fcntl.flock(lock.fileno(), _fcntl.LOCK_EX)
+        elif _msvcrt is not None:  # pragma: no cover - Windows
+            lock.seek(0)
+            if lock.read(1) == b"":
+                lock.write(b"\0")
+                lock.flush()
+            lock.seek(0)
+            _msvcrt.locking(lock.fileno(), _msvcrt.LK_LOCK, 1)
+        else:  # pragma: no cover - unsupported runtime
+            raise _error(
+                "PZ_DEV_CACHE_INVALID",
+                "当前平台不支持可靠的 Git cache 文件锁。",
+                action="dev_source_cache",
+            )
+        try:
+            yield
+        finally:
+            if _fcntl is not None:
+                _fcntl.flock(lock.fileno(), _fcntl.LOCK_UN)
+            elif _msvcrt is not None:  # pragma: no cover - Windows
+                lock.seek(0)
+                _msvcrt.locking(lock.fileno(), _msvcrt.LK_UNLCK, 1)
+
+
+def _resolution_ref(commit: str) -> str:
+    return f"refs/pz/resolutions/{commit}"
+
+
+def _owner_payload(*, repo_key: str, source: str) -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "uid": os.getuid() if hasattr(os, "getuid") else None,
+        "repo_key": repo_key,
+        "source": _canonical_remote(source),
+    }
+
+
+def _write_cache_owner(checkout: Path, *, repo_key: str, source: str) -> None:
+    marker = checkout / _CACHE_OWNER_FILE
+    marker.write_text(
+        json.dumps(_owner_payload(repo_key=repo_key, source=source), sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    marker.chmod(0o600)
+
+
+def _validate_cache(
+    checkout: Path,
+    *,
+    repo_key: str,
+    source: str,
+    action: str,
+) -> None:
+    if checkout.is_symlink() or not checkout.is_dir() or not (checkout / ".git").is_dir():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "系统临时目录中的源码 cache 不是可信 Git checkout。",
+            action=action,
+            detail=str(checkout),
+        )
+    metadata = checkout.stat()
+    if hasattr(os, "getuid") and metadata.st_uid != os.getuid():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "当前用户不是 Git cache checkout 的所有者。",
+            action=action,
+            detail=str(checkout),
+        )
+    marker = checkout / _CACHE_OWNER_FILE
+    if marker.is_symlink() or not marker.is_file():
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache 缺少可信 owner marker。",
+            action=action,
+            detail=str(checkout),
+        )
+    marker_metadata = marker.stat()
+    if (
+        hasattr(os, "getuid")
+        and marker_metadata.st_uid != os.getuid()
+        or stat.S_IMODE(marker_metadata.st_mode) & 0o077
+    ):
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache owner marker 的所有者或权限无效。",
+            action=action,
+            detail=str(marker),
+        )
+    try:
+        owner = json.loads(marker.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache owner marker 无效。",
+            action=action,
+            detail=str(marker),
+        ) from exc
+    if owner != _owner_payload(repo_key=repo_key, source=source):
+        raise _error(
+            "PZ_DEV_CACHE_INVALID",
+            "Git cache owner marker 与请求身份不一致。",
+            action=action,
+            detail=str(checkout),
+        )
+    remote = _run_git("remote", "get-url", "origin", cwd=checkout, action=action)
+    if _canonical_remote(remote) != _canonical_remote(source):
+        raise _error(
+            "PZ_DEV_CACHE_REMOTE_MISMATCH",
+            "系统临时目录中的源码 cache remote 不匹配。",
+            action=action,
+            detail=f"expected={_canonical_remote(source)}; actual={_canonical_remote(remote)}",
+        )
+
+
+def cache_git_source(
+    *,
+    repo_key: str,
+    source: str,
+    branch: str = "develop",
+    revision: str | None = None,
+    action: str = "dev_source_cache",
+) -> CachedGitSource:
+    checkout, lock_path = _cache_paths(repo_key)
+    cache_root = checkout.parent
+    _ensure_cache_root(cache_root, action=action)
+    if revision is not None and not _FULL_COMMIT_RE.fullmatch(revision):
+        raise _error(
+            "PZ_DEV_CACHE_RESOLUTION_MISSING",
+            "Git revision 必须是完整的 40 位 commit hash。",
+            action=action,
+            detail=revision,
+        )
+    with _repo_lock(lock_path, action=action):
+        created = False
+        if checkout.exists() or checkout.is_symlink():
+            _validate_cache(
+                checkout,
+                repo_key=repo_key,
+                source=source,
+                action=action,
+            )
+        if not checkout.exists() and not checkout.is_symlink():
+            if revision is not None:
+                raise _error(
+                    "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                    "系统临时 Git cache 已丢失，不能凭任意对象重建既有 revision handoff。",
+                    action=action,
+                    detail=revision,
+                )
+            staged = cache_root / f".{repo_key}.{uuid.uuid4().hex}.tmp"
+            try:
+                _run_git(
+                    "clone",
+                    "--branch",
+                    branch,
+                    "--single-branch",
+                    source,
+                    str(staged),
+                    cwd=None,
+                    action=action,
+                )
+                _write_cache_owner(staged, repo_key=repo_key, source=source)
+                staged.chmod(0o700)
+                os.replace(staged, checkout)
+                created = True
+            finally:
+                shutil.rmtree(staged, ignore_errors=True)
+        else:
+            _run_git("fetch", "origin", branch, cwd=checkout, action=action)
+        if revision is not None:
+            reference = _resolution_ref(revision)
+            try:
+                commit = _run_git(
+                    "rev-parse", f"{reference}^{{commit}}", cwd=checkout, action=action
+                )
+            except PzError as exc:
+                raise _error(
+                    "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                    "Git cache 中不存在先前固定的 revision handoff。",
+                    action=action,
+                    detail=revision,
+                ) from exc
+            if commit != revision:
+                raise _error(
+                    "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                    "Git cache resolution ref 与请求 revision 不一致。",
+                    action=action,
+                    detail=revision,
+                )
+        else:
+            selected = "HEAD" if created else "FETCH_HEAD"
+            commit = _run_git(
+                "rev-parse", f"{selected}^{{commit}}", cwd=checkout, action=action
+            )
+            reference = _resolution_ref(commit)
+            _run_git("update-ref", reference, commit, cwd=checkout, action=action)
+    return CachedGitSource(
+        repo_key,
+        _canonical_remote(source),
+        branch,
+        checkout,
+        commit,
+        reference,
+    )
+
+
+def load_cached_git_source(
+    *,
+    repo_key: str,
+    source: str,
+    revision: str,
+    branch: str = "develop",
+    action: str = "dev_source_import",
+) -> CachedGitSource:
+    if not _FULL_COMMIT_RE.fullmatch(revision):
+        raise _error(
+            "PZ_DEV_CACHE_RESOLUTION_MISSING",
+            "Git revision 必须是完整的 40 位 commit hash。",
+            action=action,
+            detail=revision,
+        )
+    checkout, lock_path = _cache_paths(repo_key)
+    if not lock_path.parent.is_dir():
+        raise _error(
+            "PZ_DEV_CACHE_RESOLUTION_MISSING",
+            "系统临时 Git cache 不存在。",
+            action=action,
+        )
+    with _repo_lock(lock_path, action=action):
+        _validate_cache(
+            checkout,
+            repo_key=repo_key,
+            source=source,
+            action=action,
+        )
+        reference = _resolution_ref(revision)
+        try:
+            commit = _run_git(
+                "rev-parse", f"{reference}^{{commit}}", cwd=checkout, action=action
+            )
+        except PzError as exc:
+            raise _error(
+                "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                "Git cache 中不存在请求的不可变 revision。",
+                action=action,
+                detail=revision,
+            ) from exc
+        if commit != revision:
+            raise _error(
+                "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                "Git cache resolution ref 与请求 revision 不一致。",
+                action=action,
+                detail=f"expected={revision}; actual={commit}",
+            )
+    return CachedGitSource(
+        repo_key,
+        _canonical_remote(source),
+        branch,
+        checkout,
+        commit,
+        reference,
+    )
+
+
+def _archive_bytes(cache: CachedGitSource, subpath: PurePosixPath, *, action: str) -> bytes:
+    completed = subprocess.run(
+        (
+            "git",
+            "-C",
+            str(cache.checkout),
+            "archive",
+            "--format=tar",
+            cache.commit,
+            subpath.as_posix(),
+        ),
+        check=False,
+        capture_output=True,
+        stdin=subprocess.DEVNULL,
+    )
+    if completed.returncode != 0:
+        raise _error(
+            "PZ_DEV_SOURCE_IMPORT_FAILED",
+            "无法从固定 Git revision 导出子包源码。",
+            action=action,
+            detail=completed.stderr.decode("utf-8", errors="replace")[:500],
+        )
+    return completed.stdout
+
+
+def _extract_archive(payload: bytes, destination: Path, subpath: PurePosixPath, *, action: str) -> None:
+    prefix_parts = subpath.parts
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:") as archive:
+        for member in archive.getmembers():
+            parts = PurePosixPath(member.name).parts
+            if parts[: len(prefix_parts)] != prefix_parts:
+                raise _error(
+                    "PZ_DEV_SOURCE_IMPORT_FAILED",
+                    "Git archive 包含越界路径。",
+                    action=action,
+                    detail=member.name,
+                )
+            relative = PurePosixPath(*parts[len(prefix_parts) :])
+            if not relative.parts:
+                continue
+            if relative.is_absolute() or ".." in relative.parts:
+                raise _error(
+                    "PZ_DEV_SOURCE_IMPORT_FAILED",
+                    "Git archive 包含不安全路径。",
+                    action=action,
+                    detail=member.name,
+                )
+            target = destination / Path(*relative.parts)
+            if member.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if member.isfile():
+                source = archive.extractfile(member)
+                if source is None:
+                    raise _error("PZ_DEV_SOURCE_IMPORT_FAILED", "无法读取 Git archive 文件。", action=action)
+                target.write_bytes(source.read())
+                target.chmod(stat.S_IMODE(member.mode))
+                continue
+            if member.issym():
+                link = PurePosixPath(member.linkname)
+                if link.is_absolute() or ".." in link.parts:
+                    raise _error(
+                        "PZ_DEV_SOURCE_IMPORT_FAILED",
+                        "Git archive 包含不安全符号链接。",
+                        action=action,
+                        detail=member.name,
+                    )
+                target.symlink_to(member.linkname)
+                continue
+            raise _error(
+                "PZ_DEV_SOURCE_IMPORT_FAILED",
+                "Git archive 包含不支持的文件类型。",
+                action=action,
+                detail=member.name,
+            )
+
+
+def _validate_app(path: Path, app_id: str, *, action: str) -> None:
+    pyproject = path / "pyproject.toml"
+    try:
+        payload = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        distribution = payload["project"]["name"]
+    except Exception as exc:
+        raise _error(
+            "PZ_DEV_SOURCE_LAYOUT_INVALID",
+            "导入目录不是正式最小子包。",
+            action=action,
+            detail=f"{path}: {exc}",
+        ) from exc
+    if not isinstance(distribution, str) or distribution.replace("-", "_") != app_id:
+        raise _error(
+            "PZ_DEV_SOURCE_LAYOUT_INVALID",
+            "导入子包的 distribution 与 app_id 不一致。",
+            action=action,
+            detail=str(path),
+        )
+
+
+def _write_provenance(path: Path, cache: CachedGitSource, subpath: PurePosixPath) -> None:
+    pyproject = path / "pyproject.toml"
+    document = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
+    tool = document.setdefault("tool", tomlkit.table())
+    pz = tool.setdefault("pz", tomlkit.table())
+    provenance = tomlkit.table()
+    provenance["kind"] = "git"
+    provenance["source"] = _canonical_remote(cache.source)
+    provenance["revision"] = cache.commit
+    provenance["subpath"] = subpath.as_posix()
+    pz["imported_from"] = provenance
+    pyproject.write_text(tomlkit.dumps(document), encoding="utf-8")
+
+
+def _write_local_provenance(
+    path: Path,
+    *,
+    source: str,
+    subpath: PurePosixPath,
+) -> None:
+    pyproject = path / "pyproject.toml"
+    document = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
+    tool = document.setdefault("tool", tomlkit.table())
+    pz = tool.setdefault("pz", tomlkit.table())
+    provenance = tomlkit.table()
+    provenance["kind"] = "path"
+    provenance["source"] = "local"
+    provenance["identity"] = hashlib.sha256(source.encode("utf-8")).hexdigest()
+    provenance["subpath"] = subpath.as_posix()
+    pz["imported_from"] = provenance
+    pyproject.write_text(tomlkit.dumps(document), encoding="utf-8")
+
+
+def _declare_local_source_mode(project_dir: Path, app_id: str, *, action: str) -> None:
+    ensure_project_state(project_dir, action=action)
+    payload = load_project_payload(project_dir, action=action)
+    apps = payload.setdefault("apps", {})
+    if not isinstance(apps, dict):
+        raise _error(
+            "PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+            "项目 apps 配置必须是对象。",
+            action=action,
+        )
+    app = apps.setdefault(app_id, {})
+    if not isinstance(app, dict):
+        raise _error(
+            "PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+            f"项目 app 配置必须是对象：{app_id}",
+            action=action,
+        )
+    sources = app.setdefault("sources", {})
+    if not isinstance(sources, dict):
+        raise _error(
+            "PZ_SCAFFOLD_PROJECT_CONFIG_INVALID",
+            f"项目 app sources 配置必须是对象：{app_id}",
+            action=action,
+        )
+    if sources.get("source_mode") == "local":
+        return
+    sources["source_mode"] = "local"
+    save_project_payload(project_dir, payload, action=action)
+
+
+def _existing_import_matches(
+    path: Path,
+    *,
+    app_id: str,
+    cache: CachedGitSource,
+    subpath: PurePosixPath,
+    action: str,
+) -> bool:
+    _validate_app(path, app_id, action=action)
+    try:
+        payload = tomllib.loads((path / "pyproject.toml").read_text(encoding="utf-8"))
+        imported = payload["tool"]["pz"]["imported_from"]
+    except Exception:
+        return False
+    return (
+        isinstance(imported, dict)
+        and imported.get("kind") == "git"
+        and _canonical_remote(str(imported.get("source") or ""))
+        == _canonical_remote(cache.source)
+        and imported.get("revision") == cache.commit
+        and imported.get("subpath") == subpath.as_posix()
+    )
+
+
+def _existing_local_import_matches(
+    path: Path,
+    *,
+    app_id: str,
+    source: str,
+    subpath: PurePosixPath,
+    action: str,
+) -> bool:
+    _validate_app(path, app_id, action=action)
+    try:
+        payload = tomllib.loads((path / "pyproject.toml").read_text(encoding="utf-8"))
+        imported = payload["tool"]["pz"]["imported_from"]
+    except Exception:
+        return False
+    return (
+        isinstance(imported, dict)
+        and imported.get("kind") == "path"
+        and imported.get("source") == "local"
+        and imported.get("identity")
+        == hashlib.sha256(source.encode("utf-8")).hexdigest()
+        and imported.get("revision") is None
+        and imported.get("subpath") == subpath.as_posix()
+    )
+
+
+def find_existing_local_import(
+    locator: str,
+    *,
+    project_dir: Path,
+    action: str = "dev_source_import",
+) -> ImportedApp | None:
+    resolved = resolve_source_locator(locator, project_dir=project_dir, action=action)
+    if resolved.source_kind != "link" or resolved.expected_app_id is None:
+        return None
+    root = Path(resolved.clone_source).expanduser().resolve()
+    destination = project_dir / "apps" / resolved.expected_app_id
+    if not destination.is_dir() or destination.is_symlink():
+        return None
+    if not _existing_local_import_matches(
+        destination,
+        app_id=resolved.expected_app_id,
+        source=str(root),
+        subpath=resolved.subpath,
+        action=action,
+    ):
+        return None
+    return ImportedApp(
+        resolved.expected_app_id,
+        destination,
+        resolved.subpath,
+        "local",
+        False,
+    )
+
+
+def _import_cached_apps_unlocked(
+    cache: CachedGitSource,
+    *,
+    project_dir: Path,
+    apps: tuple[tuple[str, PurePosixPath], ...],
+    action: str = "dev_source_import",
+) -> tuple[ImportedApp, ...]:
+    apps_root = project_dir / "apps"
+    apps_root.mkdir(parents=True, exist_ok=True)
+    config_path = project_dir / "pz.jsonc"
+    config_before = config_path.read_bytes() if config_path.is_file() else None
+    metadata_path = project_dir / "pyproject.toml"
+    metadata_before = metadata_path.read_bytes() if metadata_path.is_file() else None
+    existing: list[ImportedApp] = []
+    pending: list[tuple[str, PurePosixPath, Path, Path]] = []
+    for app_id, subpath in apps:
+        destination = apps_root / app_id
+        if destination.exists() or destination.is_symlink():
+            if (
+                destination.is_dir()
+                and not destination.is_symlink()
+                and _existing_import_matches(
+                    destination,
+                    app_id=app_id,
+                    cache=cache,
+                    subpath=subpath,
+                    action=action,
+                )
+            ):
+                existing.append(ImportedApp(app_id, destination, subpath, cache.commit, False))
+                continue
+            raise _error(
+                "PZ_DEV_SOURCE_CONFLICT",
+                f"目标 app 路径已被占用：{app_id}",
+                action=action,
+                detail=str(destination),
+            )
+        staged = apps_root / f".{app_id}.{uuid.uuid4().hex}.tmp"
+        pending.append((app_id, subpath, destination, staged))
+    created: list[ImportedApp] = []
+    try:
+        for app_id, subpath, destination, staged in pending:
+            staged.mkdir()
+            _extract_archive(_archive_bytes(cache, subpath, action=action), staged, subpath, action=action)
+            _validate_app(staged, app_id, action=action)
+            _write_provenance(staged, cache, subpath)
+        for app_id, subpath, destination, staged in pending:
+            os.replace(staged, destination)
+            created.append(ImportedApp(app_id, destination, subpath, cache.commit, True))
+            _declare_local_source_mode(project_dir, app_id, action=action)
+        imported = tuple(existing + created)
+        declare_imported_apps(project_dir, imported, action=action)
+    except Exception:
+        for item in created:
+            shutil.rmtree(item.destination, ignore_errors=True)
+        if config_before is None:
+            config_path.unlink(missing_ok=True)
+        else:
+            config_path.write_bytes(config_before)
+        if metadata_before is None:
+            metadata_path.unlink(missing_ok=True)
+        else:
+            metadata_path.write_bytes(metadata_before)
+        raise
+    finally:
+        for _, _, _, staged in pending:
+            shutil.rmtree(staged, ignore_errors=True)
+    return tuple(existing + created)
+
+
+def import_cached_apps(
+    cache: CachedGitSource,
+    *,
+    project_dir: Path,
+    apps: tuple[tuple[str, PurePosixPath], ...],
+    action: str = "dev_source_import",
+) -> tuple[ImportedApp, ...]:
+    checkout, lock_path = _cache_paths(cache.repo_key)
+    if checkout != cache.checkout:
+        raise _error(
+            "PZ_DEV_CACHE_RESOLUTION_MISSING",
+            "cache checkout 路径与规范 repo key 不匹配。",
+            action=action,
+        )
+    with _repo_lock(lock_path, action=action):
+        _validate_cache(
+            checkout,
+            repo_key=cache.repo_key,
+            source=cache.source,
+            action=action,
+        )
+        actual = _run_git(
+            "rev-parse",
+            f"{cache.resolution_ref}^{{commit}}",
+            cwd=checkout,
+            action=action,
+        )
+        if actual != cache.commit:
+            raise _error(
+                "PZ_DEV_CACHE_RESOLUTION_MISSING",
+                "导入前 cache 的固定 revision 已发生变化。",
+                action=action,
+                detail=f"expected={cache.commit}; actual={actual}",
+            )
+        return _import_cached_apps_unlocked(
+            cache,
+            project_dir=project_dir,
+            apps=apps,
+            action=action,
+        )
+
+
+def _copy_local_app(
+    source: Path,
+    *,
+    project_dir: Path,
+    app_id: str,
+    source_identity: str,
+    subpath: PurePosixPath,
+    action: str,
+) -> ImportedApp:
+    destination = project_dir / "apps" / app_id
+    if destination.exists() or destination.is_symlink():
+        raise _error(
+            "PZ_DEV_SOURCE_CONFLICT",
+            f"目标 app 路径已被占用：{app_id}",
+            action=action,
+            detail=str(destination),
+        )
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    staged = destination.parent / f".{app_id}.{uuid.uuid4().hex}.tmp"
+    excluded = {".git", ".venv", "__pycache__", ".pytest_cache", "dist", "build"}
+    committed = False
+    config_path = project_dir / "pz.jsonc"
+    config_before = config_path.read_bytes() if config_path.is_file() else None
+    metadata_path = project_dir / "pyproject.toml"
+    metadata_before = metadata_path.read_bytes() if metadata_path.is_file() else None
+    try:
+        source_root = source.resolve(strict=True)
+        for candidate in source.rglob("*"):
+            if not candidate.is_symlink():
+                continue
+            try:
+                target = candidate.resolve(strict=True)
+            except (OSError, RuntimeError) as exc:
+                raise _error(
+                    "PZ_DEV_SOURCE_IMPORT_FAILED",
+                    "本地来源包含无效符号链接。",
+                    action=action,
+                    detail=str(candidate),
+                ) from exc
+            if not target.is_relative_to(source_root):
+                raise _error(
+                    "PZ_DEV_SOURCE_IMPORT_FAILED",
+                    "本地来源包含指向目录外的符号链接。",
+                    action=action,
+                    detail=str(candidate),
+                )
+        shutil.copytree(
+            source,
+            staged,
+            symlinks=True,
+            ignore=lambda _root, names: [name for name in names if name in excluded or name.endswith(".egg-info")],
+        )
+        _validate_app(staged, app_id, action=action)
+        _write_local_provenance(
+            staged,
+            source=source_identity,
+            subpath=subpath,
+        )
+        os.replace(staged, destination)
+        committed = True
+        _declare_local_source_mode(project_dir, app_id, action=action)
+        result = ImportedApp(app_id, destination, subpath, "local", True)
+        declare_imported_apps(project_dir, (result,), action=action)
+    except Exception:
+        if committed:
+            shutil.rmtree(destination, ignore_errors=True)
+        if config_before is None:
+            config_path.unlink(missing_ok=True)
+        else:
+            config_path.write_bytes(config_before)
+        if metadata_before is None:
+            metadata_path.unlink(missing_ok=True)
+        else:
+            metadata_path.write_bytes(metadata_before)
+        raise
+    finally:
+        shutil.rmtree(staged, ignore_errors=True)
+    return result
+
+
+def import_dev_source(
+    locator: str,
+    *,
+    project_dir: Path,
+    branch: str = "develop",
+    action: str = "dev_source_import",
+) -> ImportedApp:
+    resolved = resolve_source_locator(locator, project_dir=project_dir, action=action)
+    if resolved.source_kind == "link":
+        root = Path(resolved.clone_source).expanduser().resolve()
+        source = root if resolved.subpath == PurePosixPath(".") else root / Path(*resolved.subpath.parts)
+        app_id = resolved.expected_app_id
+        if app_id is None:
+            raise _error(
+                "PZ_DEV_SOURCE_IMPORT_AMBIGUOUS",
+                "本地目录包含多个子包，请指定一个最小子包目录。",
+                action=action,
+                detail=locator,
+            )
+        return _copy_local_app(
+            source,
+            project_dir=project_dir,
+            app_id=app_id,
+            source_identity=str(root),
+            subpath=resolved.subpath,
+            action=action,
+        )
+
+    assert resolved.repo_key is not None
+    cache = cache_git_source(
+        repo_key=resolved.repo_key,
+        source=resolved.clone_source,
+        branch=branch,
+        action=action,
+    )
+    return import_git_app(
+        locator,
+        cache=cache,
+        project_dir=project_dir,
+        action=action,
+    )
+
+
+def import_local_dev_source(
+    locator: str,
+    *,
+    project_dir: Path,
+    action: str = "dev_source_import",
+) -> ImportedApp:
+    resolved = resolve_source_locator(locator, project_dir=project_dir, action=action)
+    if resolved.source_kind != "link":
+        raise _error(
+            "PZ_DEV_SOURCE_NOT_LOCAL",
+            "source import local mode requires a non-Git local directory.",
+            action=action,
+            detail=locator,
+        )
+    root = Path(resolved.clone_source).expanduser().resolve()
+    source = root if resolved.subpath == PurePosixPath(".") else root / Path(*resolved.subpath.parts)
+    if resolved.expected_app_id is None:
+        raise _error(
+            "PZ_DEV_SOURCE_IMPORT_AMBIGUOUS",
+            "本地目录包含多个子包，请指定一个最小子包目录。",
+            action=action,
+            detail=locator,
+        )
+    return _copy_local_app(
+        source,
+        project_dir=project_dir,
+        app_id=resolved.expected_app_id,
+        source_identity=str(root),
+        subpath=resolved.subpath,
+        action=action,
+    )
+
+
+def import_git_app(
+    locator: str,
+    *,
+    cache: CachedGitSource,
+    project_dir: Path,
+    action: str = "dev_source_import",
+) -> ImportedApp:
+    resolved = resolve_source_locator(locator, project_dir=project_dir, action=action)
+    if resolved.source_kind != "git" or resolved.repo_key != cache.repo_key:
+        raise _error(
+            "PZ_DEV_CACHE_RESOLUTION_MISSING",
+            "源码 locator 与固定 Git cache identity 不一致。",
+            action=action,
+            detail=locator,
+        )
+    if resolved.expected_app_id is not None:
+        app_id = resolved.expected_app_id
+        subpath = resolved.subpath
+    else:
+        packages = tuple(
+            package
+            for package in iter_workspace_packages_in_roots((cache.checkout,))
+            if package.repo.resolve() != cache.checkout.resolve()
+        )
+        if len(packages) != 1:
+            raise _error(
+                "PZ_DEV_SOURCE_IMPORT_AMBIGUOUS",
+                "Git 来源必须唯一解析到一个正式最小子包。",
+                action=action,
+                detail=f"matches={len(packages)}",
+            )
+        package = packages[0]
+        app_id = package.app_id
+        subpath = PurePosixPath(package.repo.relative_to(cache.checkout).as_posix())
+    return import_cached_apps(
+        cache,
+        project_dir=project_dir,
+        apps=((app_id, subpath),),
+        action=action,
+    )[0]
+
+
+def declare_imported_apps(
+    project_dir: Path,
+    imported: tuple[ImportedApp, ...],
+    *,
+    action: str = "declare_imported_apps",
+) -> None:
+    path = project_dir / "pyproject.toml"
+    try:
+        document = tomlkit.parse(path.read_text(encoding="utf-8"))
+        project = document["project"]
+    except Exception as exc:
+        raise _error(
+            "PZ_DEV_PROJECT_METADATA_INVALID",
+            "无法更新项目依赖声明。",
+            action=action,
+            detail=str(exc),
+        ) from exc
+    dependencies = project.setdefault("dependencies", tomlkit.array())
+    existing = {str(item).split("[", 1)[0].strip().lower() for item in dependencies}
+    tool = document.setdefault("tool", tomlkit.table())
+    uv = tool.setdefault("uv", tomlkit.table())
+    sources = uv.setdefault("sources", tomlkit.table())
+    for item in imported:
+        try:
+            payload = tomllib.loads(
+                (item.destination / "pyproject.toml").read_text(encoding="utf-8")
+            )
+        except Exception:
+            raise
+        distribution = str(payload["project"]["name"]).strip()
+        if distribution.lower() not in existing:
+            dependencies.append(distribution)
+            existing.add(distribution.lower())
+        source = tomlkit.inline_table()
+        source["path"] = item.destination.relative_to(project_dir).as_posix()
+        source["editable"] = True
+        sources[distribution] = source
+    staged = path.with_name(f".{path.name}.{uuid.uuid4().hex}.tmp")
+    try:
+        staged.write_text(tomlkit.dumps(document), encoding="utf-8")
+        os.replace(staged, path)
+    finally:
+        staged.unlink(missing_ok=True)
+
+
+__all__ = [
+    "CachedGitSource",
+    "ImportedApp",
+    "cache_git_source",
+    "declare_imported_apps",
+    "find_existing_local_import",
+    "import_cached_apps",
+    "import_dev_source",
+    "import_git_app",
+    "import_local_dev_source",
+    "load_cached_git_source",
+]