agh 0.3.2__tar.gz → 0.3.3__tar.gz

{agh-0.3.2/agh.egg-info → agh-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agh
-Version: 0.3.2
+Version: 0.3.3
 Summary: Self-hosted guidance distribution for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/giulianotesta7/AgentGuidanceHub

{agh-0.3.2 → agh-0.3.3}/agh/server/routes/packs.py

@@ -7,8 +7,9 @@ import json
 import os
 import shutil
 import sqlite3
+import stat as stat_module
 from pathlib import Path, PurePosixPath
-from typing import Any
+from typing import Any, NoReturn
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from pydantic import BaseModel, ValidationError
@@ -31,6 +32,8 @@ MAX_PACK_PATH_LENGTH = 240
 MAX_PACK_FILE_BYTES = 256 * 1024
 MAX_PACK_TOTAL_BYTES = 1024 * 1024
 MAX_PACK_PUBLISH_BODY_BYTES = MAX_PACK_TOTAL_BYTES + (MAX_PACK_FILES * 128)
+PACK_ARTIFACT_MISSING_DETAIL = "pack file not found"
+PACK_ARTIFACT_STORAGE_DETAIL = "pack artifact storage unavailable"
 
 
 class PackPublish(BaseModel):
@@ -76,6 +79,31 @@ def _pack_version_resolve_response(row: sqlite3.Row) -> dict[str, str]:
     }
 
 
+def _raise_pack_artifact_missing() -> NoReturn:
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail=PACK_ARTIFACT_MISSING_DETAIL,
+    )
+
+
+def _raise_pack_artifact_storage_unavailable(
+    exc: OSError | UnicodeDecodeError,
+) -> NoReturn:
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail=PACK_ARTIFACT_STORAGE_DETAIL,
+    ) from exc
+
+
+def _read_published_pack_file(storage_dir: Path, safe_path: Path) -> str:
+    candidate = storage_dir / safe_path
+    _require_pack_artifact_read_target(storage_dir, candidate)
+    try:
+        return candidate.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        _raise_pack_artifact_storage_unavailable(exc)
+
+
 def _parse_pack_version_ref_or_400(value: str) -> PackVersionRef:
     try:
         return parse_pack_version_ref(value, allow_latest=False)
@@ -280,23 +308,16 @@ def get_pack_file(
         safe_path = _safe_relative_path(file_path)
     except PackManifestError as exc:
         raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND, detail="pack file not found"
+            status_code=status.HTTP_404_NOT_FOUND, detail=PACK_ARTIFACT_MISSING_DETAIL
         ) from exc
     connection = _connect(request)
     try:
         row = _find_pack_version(connection, domain, name, version)
         if row is None:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND, detail="pack file not found"
-            )
+            _raise_pack_artifact_missing()
         storage_dir = Path(row["storage_path"])
-        candidate = storage_dir / safe_path
-        if not _is_safe_pack_file(storage_dir, candidate):
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND, detail="pack file not found"
-            )
         return Response(
-            candidate.read_text(encoding="utf-8"),
+            _read_published_pack_file(storage_dir, safe_path),
             media_type="text/plain; charset=utf-8",
         )
     finally:
@@ -557,19 +578,37 @@ def _pack_checksum(pack_dir: Path) -> str:
     return f"sha256:{digest.hexdigest()}"
 
 
-def _is_safe_pack_file(storage_dir: Path, candidate: Path) -> bool:
+def _require_pack_artifact_read_target(storage_dir: Path, candidate: Path) -> None:
     try:
         resolved_root = storage_dir.resolve(strict=True)
         resolved_candidate = candidate.resolve(strict=True)
         resolved_candidate.relative_to(resolved_root)
-    except (OSError, ValueError):
-        return False
-    if not resolved_candidate.is_file():
-        return False
+    except ValueError:
+        _raise_pack_artifact_missing()
+    except (FileNotFoundError, NotADirectoryError):
+        _raise_pack_artifact_missing()
+    except OSError as exc:
+        _raise_pack_artifact_storage_unavailable(exc)
+    try:
+        candidate_stat = resolved_candidate.stat()
+    except (FileNotFoundError, NotADirectoryError):
+        _raise_pack_artifact_missing()
+    except OSError as exc:
+        _raise_pack_artifact_storage_unavailable(exc)
+    if not stat_module.S_ISREG(candidate_stat.st_mode):
+        _raise_pack_artifact_missing()
     current = candidate
     paths: list[Path] = []
     while current != storage_dir:
         paths.append(current)
         current = current.parent
     paths.append(storage_dir)
-    return not any(path.is_symlink() for path in paths)
+    for path in paths:
+        try:
+            path_stat = path.lstat()
+        except (FileNotFoundError, NotADirectoryError):
+            _raise_pack_artifact_missing()
+        except OSError as exc:
+            _raise_pack_artifact_storage_unavailable(exc)
+        if stat_module.S_ISLNK(path_stat.st_mode):
+            _raise_pack_artifact_missing()

{agh-0.3.2 → agh-0.3.3}/agh/server/routes/projects.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import sqlite3
 from pathlib import Path
-from typing import Any
+from typing import Any, NoReturn
 from urllib.parse import quote
 
 from fastapi import (  # pyright: ignore[reportMissingImports]
@@ -329,23 +329,78 @@ def _pack_file_download_url(domain: str, name: str, version: str, path: str) ->
     return f"/api/v1/packs/{domain}/{name}/versions/{version}/files/{quoted_path}"
 
 
-def _read_pack_file(storage_dir: Path, relative_path: str) -> str | None:
+def _raise_pack_artifact_missing() -> NoReturn:
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail="pack file not found",
+    )
+
+
+def _raise_pack_artifact_storage_unavailable(
+    exc: OSError | UnicodeDecodeError,
+) -> NoReturn:
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="pack artifact storage unavailable",
+    ) from exc
+
+
+def _missing_pack_artifact_or_none(required: bool) -> None:
+    if required:
+        _raise_pack_artifact_missing()
+    return None
+
+
+def _read_pack_file(
+    storage_dir: Path, relative_path: str, *, required: bool
+) -> str | None:
     candidate = storage_dir / relative_path
     try:
         resolved_root = storage_dir.resolve(strict=True)
         resolved_candidate = candidate.resolve(strict=True)
         resolved_candidate.relative_to(resolved_root)
-    except (OSError, ValueError):
-        return None
+    except ValueError:
+        return _missing_pack_artifact_or_none(required)
+    except (FileNotFoundError, NotADirectoryError):
+        return _missing_pack_artifact_or_none(required)
+    except OSError as exc:
+        _raise_pack_artifact_storage_unavailable(exc)
     if not resolved_candidate.is_file():
-        return None
-    return resolved_candidate.read_text(encoding="utf-8")
+        return _missing_pack_artifact_or_none(required)
+    if _pack_artifact_path_has_symlink_component(storage_dir, candidate):
+        return _missing_pack_artifact_or_none(required)
+    try:
+        return resolved_candidate.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        _raise_pack_artifact_storage_unavailable(exc)
+
+
+def _pack_artifact_path_has_symlink_component(
+    storage_dir: Path, candidate: Path
+) -> bool:
+    current = candidate
+    while True:
+        try:
+            is_symlink = current.is_symlink()
+        except OSError as exc:
+            _raise_pack_artifact_storage_unavailable(exc)
+        if is_symlink:
+            return True
+        if current == storage_dir:
+            return False
+        current = current.parent
 
 
 def _instruction_artifact(
-    *, domain: str, name: str, version: str, storage_dir: Path, path: str
+    *,
+    domain: str,
+    name: str,
+    version: str,
+    storage_dir: Path,
+    path: str,
+    required: bool,
 ) -> dict[str, str] | None:
-    content = _read_pack_file(storage_dir, path)
+    content = _read_pack_file(storage_dir, path, required=required)
     if content is None:
         return None
     target_agent = "opencode" if path.endswith("AGENTS.md") else "claude"
@@ -361,42 +416,109 @@ def _instruction_artifact(
 
 
 def _skill_artifacts(
-    *, domain: str, name: str, version: str, storage_dir: Path
+    *,
+    domain: str,
+    name: str,
+    version: str,
+    storage_dir: Path,
+    expected_paths: list[str] | None = None,
 ) -> list[dict[str, str]]:
+    if expected_paths is not None:
+        artifacts: list[dict[str, str]] = []
+        for path in sorted(expected_paths):
+            artifacts.extend(
+                _skill_artifacts_for_path(
+                    domain=domain,
+                    name=name,
+                    version=version,
+                    storage_dir=storage_dir,
+                    path=path,
+                    required=True,
+                )
+            )
+        return artifacts
+
     skills_dir = storage_dir / "skills"
     if not skills_dir.is_dir() or skills_dir.is_symlink():
         return []
     artifacts: list[dict[str, str]] = []
     for skill_dir in sorted(item for item in skills_dir.iterdir() if item.is_dir()):
         path = f"skills/{skill_dir.name}/SKILL.md"
-        content = _read_pack_file(storage_dir, path)
-        if content is None:
-            continue
-        checksum = managed_payload_checksum(content)
-        download_url = _pack_file_download_url(domain, name, version, path)
         artifacts.extend(
-            [
-                {
-                    "kind": "skill",
-                    "path": path,
-                    "target_agent": "opencode",
-                    "target_path": f".opencode/skills/{skill_dir.name}/SKILL.md",
-                    "checksum": checksum,
-                    "download_url": download_url,
-                },
-                {
-                    "kind": "skill",
-                    "path": path,
-                    "target_agent": "claude",
-                    "target_path": f".claude/skills/{skill_dir.name}/SKILL.md",
-                    "checksum": checksum,
-                    "download_url": download_url,
-                },
-            ]
+            _skill_artifacts_for_path(
+                domain=domain,
+                name=name,
+                version=version,
+                storage_dir=storage_dir,
+                path=path,
+                required=False,
+            )
         )
     return artifacts
 
 
+def _skill_artifacts_for_path(
+    *,
+    domain: str,
+    name: str,
+    version: str,
+    storage_dir: Path,
+    path: str,
+    required: bool,
+) -> list[dict[str, str]]:
+    skill_name = _skill_name_from_artifact_path(path)
+    if skill_name is None:
+        return []
+    content = _read_pack_file(storage_dir, path, required=required)
+    if content is None:
+        return []
+    checksum = managed_payload_checksum(content)
+    download_url = _pack_file_download_url(domain, name, version, path)
+    return [
+        {
+            "kind": "skill",
+            "path": path,
+            "target_agent": "opencode",
+            "target_path": f".opencode/skills/{skill_name}/SKILL.md",
+            "checksum": checksum,
+            "download_url": download_url,
+        },
+        {
+            "kind": "skill",
+            "path": path,
+            "target_agent": "claude",
+            "target_path": f".claude/skills/{skill_name}/SKILL.md",
+            "checksum": checksum,
+            "download_url": download_url,
+        },
+    ]
+
+
+def _skill_name_from_artifact_path(path: str) -> str | None:
+    parts = path.split("/")
+    if len(parts) == 3 and parts[0] == "skills" and parts[1] and parts[2] == "SKILL.md":
+        return parts[1]
+    return None
+
+
+def _expected_artifact_paths(manifest: dict[str, Any]) -> set[str] | None:
+    raw_paths = manifest.get("artifact_paths")
+    if raw_paths is None:
+        return None
+    if not isinstance(raw_paths, list):
+        return None
+    if not raw_paths or not all(
+        isinstance(path, str)
+        and (
+            path in {"instructions/AGENTS.md", "instructions/CLAUDE.md"}
+            or _skill_name_from_artifact_path(path) is not None
+        )
+        for path in raw_paths
+    ):
+        return None
+    return set(raw_paths)
+
+
 def _pull_manifest_pack(
     connection: sqlite3.Connection, row: sqlite3.Row
 ) -> dict[str, Any]:
@@ -407,6 +529,8 @@ def _pull_manifest_pack(
     domain = str(row["domain"])
     name = str(row["name"])
     storage_dir = Path(str(version_row["storage_path"]))
+    manifest = json.loads(str(version_row["manifest_json"]))
+    expected_paths = _expected_artifact_paths(manifest)
     artifacts: list[dict[str, str]] = []
     for instruction_path in ["instructions/AGENTS.md", "instructions/CLAUDE.md"]:
         artifact = _instruction_artifact(
@@ -415,19 +539,31 @@ def _pull_manifest_pack(
             version=version,
             storage_dir=storage_dir,
             path=instruction_path,
+            required=expected_paths is not None and instruction_path in expected_paths,
         )
         if artifact is not None:
             artifacts.append(artifact)
+    expected_skill_paths = None
+    if expected_paths is not None:
+        expected_skill_paths = [
+            path for path in expected_paths if _skill_name_from_artifact_path(path)
+        ]
     artifacts.extend(
         _skill_artifacts(
-            domain=domain, name=name, version=version, storage_dir=storage_dir
+            domain=domain,
+            name=name,
+            version=version,
+            storage_dir=storage_dir,
+            expected_paths=expected_skill_paths,
         )
     )
     return {
         "id": f"{domain}/{name}@{version}",
         "assignment_id": row["id"],
         "position": int(row["position"]),
-        "manifest": json.loads(str(version_row["manifest_json"])),
+        "manifest": {
+            key: value for key, value in manifest.items() if key != "artifact_paths"
+        },
         "artifacts": artifacts,
     }
 

{agh-0.3.2 → agh-0.3.3/agh.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agh
-Version: 0.3.2
+Version: 0.3.3
 Summary: Self-hosted guidance distribution for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/giulianotesta7/AgentGuidanceHub

{agh-0.3.2 → agh-0.3.3}/tests/test_pack_routes.py

@@ -62,6 +62,18 @@ def _publish(client: TestClient, token: str, files: dict[str, str]):
     return client.post("/api/v1/packs", json={"files": files}, headers=_auth(token))
 
 
+def _stored_agents_file(tmp_path: Path) -> Path:
+    return (
+        tmp_path
+        / "packs"
+        / "acme"
+        / "onboarding"
+        / "1.0.0"
+        / "instructions"
+        / "AGENTS.md"
+    )
+
+
 def test_owner_publishes_lists_and_downloads_pack_files(
     tmp_path: Path, monkeypatch
 ) -> None:
@@ -561,6 +573,7 @@ def test_pack_file_download_rejects_traversal_and_symlinks(
         headers=_auth(owner_token),
     )
     assert traversal.status_code == 404
+    assert traversal.json() == {"detail": "pack file not found"}
 
     outside = tmp_path / "outside-secret.txt"
     outside.write_text("secret", encoding="utf-8")
@@ -571,3 +584,90 @@ def test_pack_file_download_rejects_traversal_and_symlinks(
         headers=_auth(owner_token),
     )
     assert leak.status_code == 404
+    assert leak.json() == {"detail": "pack file not found"}
+
+
+def test_pack_file_download_missing_artifact_returns_json_404(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token = _client_with_owner(tmp_path, monkeypatch)
+    assert _publish(client, owner_token, _pack_files()).status_code == 201
+    stored_file = _stored_agents_file(tmp_path)
+    stored_file.unlink()
+
+    response = client.get(
+        "/api/v1/packs/acme/onboarding/versions/1.0.0/files/instructions/AGENTS.md",
+        headers=_auth(owner_token),
+    )
+
+    assert response.status_code == 404
+    assert response.json() == {"detail": "pack file not found"}
+
+
+def test_pack_file_download_unreadable_artifact_returns_json_503(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token = _client_with_owner(tmp_path, monkeypatch)
+    assert _publish(client, owner_token, _pack_files()).status_code == 201
+    stored_file = _stored_agents_file(tmp_path)
+    stored_file.write_bytes(b"\xff\xfe\x00")
+
+    response = client.get(
+        "/api/v1/packs/acme/onboarding/versions/1.0.0/files/instructions/AGENTS.md",
+        headers=_auth(owner_token),
+    )
+
+    assert response.status_code == 503
+    assert response.json() == {"detail": "pack artifact storage unavailable"}
+
+
+def test_pack_file_download_read_error_returns_json_503(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token = _client_with_owner(tmp_path, monkeypatch)
+    assert _publish(client, owner_token, _pack_files()).status_code == 201
+    stored_file = _stored_agents_file(tmp_path)
+    original_read_text = Path.read_text
+
+    def fail_candidate_read_text(
+        self: Path,
+        encoding: str | None = None,
+        errors: str | None = None,
+    ) -> str:
+        if self == stored_file and encoding == "utf-8":
+            raise OSError("simulated read failure")
+        return original_read_text(self, encoding=encoding, errors=errors)
+
+    monkeypatch.setattr(Path, "read_text", fail_candidate_read_text)
+
+    response = client.get(
+        "/api/v1/packs/acme/onboarding/versions/1.0.0/files/instructions/AGENTS.md",
+        headers=_auth(owner_token),
+    )
+
+    assert response.status_code == 503
+    assert response.json() == {"detail": "pack artifact storage unavailable"}
+
+
+def test_pack_file_download_path_resolution_error_returns_json_503(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token = _client_with_owner(tmp_path, monkeypatch)
+    assert _publish(client, owner_token, _pack_files()).status_code == 201
+    stored_file = _stored_agents_file(tmp_path)
+    original_resolve = Path.resolve
+
+    def fail_candidate_resolve(self: Path, strict: bool = False) -> Path:
+        if self == stored_file and strict:
+            raise OSError("simulated path resolution failure")
+        return original_resolve(self, strict=strict)
+
+    monkeypatch.setattr(Path, "resolve", fail_candidate_resolve)
+
+    response = client.get(
+        "/api/v1/packs/acme/onboarding/versions/1.0.0/files/instructions/AGENTS.md",
+        headers=_auth(owner_token),
+    )
+
+    assert response.status_code == 503
+    assert response.json() == {"detail": "pack artifact storage unavailable"}

{agh-0.3.2 → agh-0.3.3}/tests/test_pull_manifest_routes.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+import json
+import shutil
 from pathlib import Path
 from typing import Any
 
+import pytest
 from fastapi.testclient import TestClient
 
 from agh.common.checksums import managed_payload_checksum
 from agh.server.app import create_app
+from agh.server.db import connect_database, get_database_path
 
 
 def _client_with_owner(tmp_path: Path, monkeypatch) -> tuple[TestClient, str]:
@@ -118,6 +122,57 @@ def _assign_pack(
     return response.json()
 
 
+def _publish_and_assign(
+    tmp_path: Path, monkeypatch, ref: str, **files: str | None
+) -> tuple[TestClient, str, dict[str, Any]]:
+    client, owner_token = _client_with_owner(tmp_path, monkeypatch)
+    project = _create_project(client, owner_token)
+    _publish_pack(client, owner_token, ref, **files)
+    _assign_pack(client, owner_token, project["id"], ref)
+    return client, owner_token, project
+
+
+def _pull_manifest(client: TestClient, token: str, project: dict[str, Any]) -> Any:
+    return client.get(
+        f"/api/v1/projects/{project['id']}/pull-manifest",
+        headers=_auth(token),
+    )
+
+
+def _assert_skill_artifacts(artifacts: list[dict[str, Any]], content: str) -> None:
+    assert {artifact["target_path"] for artifact in artifacts} == {
+        ".opencode/skills/lint/SKILL.md",
+        ".claude/skills/lint/SKILL.md",
+    }
+    assert all(
+        artifact["checksum"] == managed_payload_checksum(content)
+        for artifact in artifacts
+    )
+
+
+def _store_manifest_artifact_paths(tmp_path: Path, artifact_paths: Any) -> None:
+    connection = connect_database(get_database_path(tmp_path))
+    try:
+        row = connection.execute(
+            "SELECT id, manifest_json FROM pack_versions"
+        ).fetchone()
+        manifest = json.loads(row["manifest_json"])
+        manifest["artifact_paths"] = artifact_paths
+        connection.execute(
+            "UPDATE pack_versions SET manifest_json = ? WHERE id = ?",
+            (json.dumps(manifest, sort_keys=True), row["id"]),
+        )
+        connection.commit()
+    finally:
+        connection.close()
+
+
+def _stored_pack_path(tmp_path: Path, ref: str, relative_path: str) -> Path:
+    pair, version = ref.split("@", 1)
+    domain, name = pair.split("/", 1)
+    return tmp_path / "packs" / domain / name / version / relative_path
+
+
 def test_pull_manifest_resolves_latest_orders_assignments_and_builds_artifacts(
     tmp_path: Path, monkeypatch
 ) -> None:
@@ -221,6 +276,181 @@ def test_pull_manifest_includes_skill_only_pack_artifacts(
     )
 
 
+def test_pull_manifest_legacy_missing_discovered_skill_file_is_skipped(
+    tmp_path: Path, monkeypatch
+) -> None:
+    agents = "# Guide\n"
+    client, owner_token, project = _publish_and_assign(
+        tmp_path,
+        monkeypatch,
+        "acme/legacy@1.0.0",
+        agents=agents,
+        skill="# Lint\n",
+    )
+    stored_skill = _stored_pack_path(
+        tmp_path, "acme/legacy@1.0.0", "skills/lint/SKILL.md"
+    )
+    stored_skill.unlink()
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 200, response.text
+    artifacts = response.json()["packs"][0]["artifacts"]
+    assert [artifact["path"] for artifact in artifacts] == ["instructions/AGENTS.md"]
+    assert artifacts[0]["checksum"] == managed_payload_checksum(agents)
+
+
+def test_pull_manifest_legacy_missing_optional_instruction_file_is_skipped(
+    tmp_path: Path, monkeypatch
+) -> None:
+    agents = "# OpenCode Guide\n"
+    client, owner_token, project = _publish_and_assign(
+        tmp_path,
+        monkeypatch,
+        "acme/legacy@1.0.0",
+        agents=agents,
+        claude="# Claude Guide\n",
+        skill=None,
+    )
+    stored_claude = _stored_pack_path(
+        tmp_path, "acme/legacy@1.0.0", "instructions/CLAUDE.md"
+    )
+    stored_claude.unlink()
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 200, response.text
+    artifacts = response.json()["packs"][0]["artifacts"]
+    assert [artifact["path"] for artifact in artifacts] == ["instructions/AGENTS.md"]
+    assert artifacts[0]["checksum"] == managed_payload_checksum(agents)
+
+
+def test_pull_manifest_expected_instruction_read_oserror_returns_json_503(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token, project = _publish_and_assign(
+        tmp_path,
+        monkeypatch,
+        "acme/current@1.0.0",
+        agents="# OpenCode Guide\n",
+        claude=None,
+        skill=None,
+    )
+    _store_manifest_artifact_paths(tmp_path, ["instructions/AGENTS.md"])
+    stored_agents = _stored_pack_path(
+        tmp_path, "acme/current@1.0.0", "instructions/AGENTS.md"
+    )
+    original_read_text = Path.read_text
+
+    def fail_expected_agents_read(path: Path, *args: Any, **kwargs: Any) -> str:
+        if path == stored_agents:
+            raise OSError("simulated storage read failure")
+        return original_read_text(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", fail_expected_agents_read)
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 503
+    assert response.json() == {"detail": "pack artifact storage unavailable"}
+
+
+@pytest.mark.parametrize("artifact_paths", ["skills/lint/SKILL.md", ["not/a/thing"]])
+def test_pull_manifest_malformed_artifact_paths_uses_legacy_discovery(
+    tmp_path: Path, monkeypatch, artifact_paths: Any
+) -> None:
+    skill_content = "# Lint\nUse lint skill.\n"
+    client, owner_token, project = _publish_and_assign(
+        tmp_path, monkeypatch, "acme/legacy@1.0.0", skill=skill_content
+    )
+    _store_manifest_artifact_paths(tmp_path, artifact_paths)
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 200, response.text
+    _assert_skill_artifacts(response.json()["packs"][0]["artifacts"], skill_content)
+
+
+@pytest.mark.parametrize(
+    ("ref", "files", "artifact_paths", "missing_path", "remove_tree"),
+    [
+        (
+            "acme/guide@1.0.0",
+            {"agents": "# Guide\n"},
+            ["instructions/AGENTS.md"],
+            "instructions/AGENTS.md",
+            False,
+        ),
+        (
+            "acme/mixed@1.0.0",
+            {"agents": "# Guide\n", "skill": "# Lint\n"},
+            ["instructions/AGENTS.md", "skills/lint/SKILL.md"],
+            "skills",
+            True,
+        ),
+    ],
+)
+def test_pull_manifest_expected_missing_storage_returns_json_404(
+    tmp_path: Path,
+    monkeypatch,
+    ref: str,
+    files: dict[str, str],
+    artifact_paths: list[str],
+    missing_path: str,
+    remove_tree: bool,
+) -> None:
+    client, owner_token, project = _publish_and_assign(
+        tmp_path, monkeypatch, ref, **files
+    )
+    _store_manifest_artifact_paths(tmp_path, artifact_paths)
+    stored_path = _stored_pack_path(tmp_path, ref, missing_path)
+    shutil.rmtree(stored_path) if remove_tree else stored_path.unlink()
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 404
+    assert response.json() == {"detail": "pack file not found"}
+
+
+def test_pull_manifest_expected_symlink_artifact_returns_json_404(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token, project = _publish_and_assign(
+        tmp_path, monkeypatch, "acme/skills@1.0.0", skill="# Lint\n"
+    )
+    _store_manifest_artifact_paths(tmp_path, ["skills/lint/SKILL.md"])
+    stored_skill = _stored_pack_path(
+        tmp_path, "acme/skills@1.0.0", "skills/lint/SKILL.md"
+    )
+    stored_skill.unlink()
+    stored_skill.symlink_to(
+        _stored_pack_path(tmp_path, "acme/skills@1.0.0", "agh.pack.toml")
+    )
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 404
+    assert response.json() == {"detail": "pack file not found"}
+
+
+def test_pull_manifest_unreadable_expected_artifact_returns_json_503(
+    tmp_path: Path, monkeypatch
+) -> None:
+    client, owner_token, project = _publish_and_assign(
+        tmp_path, monkeypatch, "acme/skills@1.0.0", skill="# Lint\n"
+    )
+    _store_manifest_artifact_paths(tmp_path, ["skills/lint/SKILL.md"])
+    stored_skill = _stored_pack_path(
+        tmp_path, "acme/skills@1.0.0", "skills/lint/SKILL.md"
+    )
+    stored_skill.write_bytes(b"\xff\xfe\x00")
+
+    response = _pull_manifest(client, owner_token, project)
+
+    assert response.status_code == 503
+    assert response.json() == {"detail": "pack artifact storage unavailable"}
+
+
 def test_pull_manifest_developer_access_and_non_member_denial(
     tmp_path: Path, monkeypatch
 ) -> None: