skillnav 0.3.0__tar.gz → 0.4.2__tar.gz

{skillnav-0.3.0 → skillnav-0.4.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: skillnav
-Version: 0.3.0
-Summary: CLI client for the Skill management platform (MonoSkillNavigator)
+Version: 0.4.2
+Summary: CLI client for the Skill management platform (SkillNavigator)
 License: Apache-2.0
 Keywords: skill,cli,agent,registry
 Classifier: Programming Language :: Python :: 3
@@ -12,17 +12,19 @@ Description-Content-Type: text/markdown
 Requires-Dist: typer>=0.12
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
 
 # skillnav
 
-Official CLI client for the Skill management platform (MonoSkillNavigator).
+Official CLI client for the Skill management platform (SkillNavigator).
 
 Specification: `docs/cli-design.md` in the platform repository.
 
 ## Install
 
 ```bash
-pipx install skillnav
+pip install skillnav -i https://mirrors.aliyun.com/pypi/simple/
 # or from this repo:
 pip install -e "cli-py[dev]"
 ```
@@ -36,7 +38,6 @@ skillnav config test
 skillnav login --api-key sk_...
 skillnav search demo
 skillnav info demo-skill
-skillnav review examples/demo-skill
 skillnav publish examples/demo-skill --dry-run
 skillnav download demo-skill -o /tmp/demo.zip
 skillnav update              # upgrade when PyPI has a newer release

{skillnav-0.3.0 → skillnav-0.4.2}/README.md

@@ -1,13 +1,13 @@
 # skillnav
 
-Official CLI client for the Skill management platform (MonoSkillNavigator).
+Official CLI client for the Skill management platform (SkillNavigator).
 
 Specification: `docs/cli-design.md` in the platform repository.
 
 ## Install
 
 ```bash
-pipx install skillnav
+pip install skillnav -i https://mirrors.aliyun.com/pypi/simple/
 # or from this repo:
 pip install -e "cli-py[dev]"
 ```
@@ -21,7 +21,6 @@ skillnav config test
 skillnav login --api-key sk_...
 skillnav search demo
 skillnav info demo-skill
-skillnav review examples/demo-skill
 skillnav publish examples/demo-skill --dry-run
 skillnav download demo-skill -o /tmp/demo.zip
 skillnav update              # upgrade when PyPI has a newer release

{skillnav-0.3.0 → skillnav-0.4.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "skillnav"
-version = "0.3.0"
-description = "CLI client for the Skill management platform (MonoSkillNavigator)"
+version = "0.4.2"
+description = "CLI client for the Skill management platform (SkillNavigator)"
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "Apache-2.0" }
@@ -20,10 +20,30 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=8.0"]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+    "mypy>=1.10",
+]
 
 [project.scripts]
 skillnav = "skillnav.cli:main"
 
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src"]
+
+[tool.ruff.lint]
+# 默认集（F 全部 + E4/E7/E9）；后续需要可扩展（I/UP/B 等）。
+select = ["E4", "E7", "E9", "F"]
+
+[tool.mypy]
+python_version = "3.9"
+check_untyped_defs = false
+warn_redundant_casts = true
+no_implicit_optional = true
+ignore_missing_imports = true
+
 [tool.setuptools.packages.find]
 where = ["src"]

skillnav-0.4.2/src/skillnav/__init__.py

@@ -0,0 +1,3 @@
+"""skillnav — CLI client for the Skill management platform (SkillNavigator)."""
+
+__version__ = "0.4.2"

{skillnav-0.3.0 → skillnav-0.4.2}/src/skillnav/__main__.py

@@ -1,4 +1,4 @@
 from skillnav.cli import main
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    main()

{skillnav-0.3.0 → skillnav-0.4.2}/src/skillnav/api.py

@@ -7,7 +7,8 @@ import urllib.error
 import urllib.request
 from typing import Any
 
-from skillnav.errors import NetworkError, SkillnavError
+from skillnav.error_hints import enrich_api_error, network_unreachable
+from skillnav.errors import AuthError, NetworkError, SkillnavError
 
 
 def request_bytes(
@@ -35,7 +36,9 @@ def request_bytes(
         return exc.code, exc.read(), dict(exc.headers.items())
     except urllib.error.URLError as exc:
         reason = getattr(exc, "reason", exc)
-        raise NetworkError(str(reason)) from exc
+        raise NetworkError.from_hint(network_unreachable(str(reason), registry=url)) from exc
+    except OSError as exc:
+        raise NetworkError.from_hint(network_unreachable(str(exc), registry=url)) from exc
 
 
 def request_json(
@@ -69,12 +72,10 @@ def api_error_message(body: Any) -> str:
 def raise_for_api_status(status: int, body: Any) -> None:
     if status < 400:
         return
-    message = api_error_message(body)
+    hint = enrich_api_error(api_error_message(body), status=status, body=body)
     if status in (401, 403):
-        from skillnav.errors import AuthError
-
-        raise AuthError(message)
-    raise SkillnavError(message)
+        raise AuthError(hint.summary, hint=hint)
+    raise SkillnavError(hint.summary, hint=hint)
 
 
 def parse_content_disposition_filename(header: str | None) -> str | None:

{skillnav-0.3.0 → skillnav-0.4.2}/src/skillnav/cli.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import sys
 from pathlib import Path
 from typing import Annotated, Any, Optional
 
@@ -16,14 +15,22 @@ from skillnav.api import (
     request_bytes,
     request_json,
 )
-from skillnav.config import get_profile, load_config, save_config
+from skillnav.config import get_profile, load_config, resolve_profile_api_key, save_config
 from skillnav.contributors import resolve_contributor_id
 from skillnav.context import CliContext
+from skillnav.error_hints import (
+    enrich_api_error,
+    enrich_usage_error,
+    hint_from_message,
+    invalid_api_key,
+    not_logged_in,
+)
 from skillnav.errors import (
     EXIT_AUTH,
     EXIT_BUSINESS,
     EXIT_NETWORK,
     EXIT_OK,
+    EXIT_USAGE,
     AuthError,
     NetworkError,
     SkillnavError,
@@ -32,17 +39,16 @@ from skillnav.errors import (
 from skillnav.output import (
     emit_error,
     emit_json,
+    filter_skill_body_version,
     print_leaderboard,
     print_report_version,
-    print_review,
-    print_review_result,
+    print_inspection_result,
     print_search_results,
     print_skill_info,
     print_skill_status,
-    print_virustotal_summary,
     unwrap_resource_id,
 )
-from skillnav.packages import extract_zip_to_directory, package_to_base64, resolve_user_path
+from skillnav.packages import extract_zip_to_directory, package_to_base64
 from skillnav.publish_metadata import build_publish_metadata, read_frontmatter_hints, resolve_package_path
 from skillnav.urls import join_registry_url, slug_path
 
@@ -61,20 +67,46 @@ def _ctx() -> CliContext:
     return _state["ctx"]
 
 
+def _normalize_skillnav_error(exc: SkillnavError) -> SkillnavError:
+    if exc.detail or exc.next_steps:
+        return exc
+    if isinstance(exc, UsageError):
+        hint = enrich_usage_error(exc.message)
+    else:
+        hint = hint_from_message(exc.message)
+    return type(exc)(hint.summary, hint=hint)
+
+
+def _emit_skillnav_error(exc: SkillnavError, *, json_output: bool) -> None:
+    emit_error(
+        exc.message,
+        json_output=json_output,
+        detail=exc.detail,
+        next_steps=exc.next_steps,
+    )
+
+
 def _handle_error(exc: BaseException) -> None:
     ctx = _state.get("ctx")
     json_output = bool(ctx and ctx.json_output)
+
+    if isinstance(exc, ValueError):
+        hint = enrich_usage_error(str(exc))
+        wrapped = UsageError(hint.summary, hint=hint)
+        _emit_skillnav_error(wrapped, json_output=json_output)
+        raise typer.Exit(EXIT_USAGE) from exc
+
     if isinstance(exc, AuthError):
-        emit_error(exc.message, json_output=json_output)
+        _emit_skillnav_error(_normalize_skillnav_error(exc), json_output=json_output)
         raise typer.Exit(EXIT_AUTH) from exc
     if isinstance(exc, UsageError):
-        emit_error(exc.message, json_output=json_output)
-        raise typer.Exit(EXIT_BUSINESS) from exc
+        _emit_skillnav_error(_normalize_skillnav_error(exc), json_output=json_output)
+        raise typer.Exit(EXIT_USAGE) from exc
     if isinstance(exc, NetworkError):
-        emit_error(exc.message, json_output=json_output)
+        _emit_skillnav_error(exc, json_output=json_output)
         raise typer.Exit(EXIT_NETWORK) from exc
     if isinstance(exc, SkillnavError):
-        emit_error(exc.message, json_output=json_output)
+        _emit_skillnav_error(_normalize_skillnav_error(exc), json_output=json_output)
         raise typer.Exit(EXIT_BUSINESS) from exc
     raise exc
 
@@ -92,16 +124,6 @@ def _api_json(method: str, path: str, *, body: dict | None = None, auth: bool =
     return payload
 
 
-def _friendly_publish_error(message: str) -> str:
-    if message == "skill_in_recycle_bin":
-        return "Skill is in the recycle bin — restore it on the web UI before publishing."
-    if message == "Only skill contributors can publish new versions":
-        return "Only skill contributors can publish new versions — ask the owner to add you."
-    if message == "review_pipeline_incomplete":
-        return "Review pipeline incomplete (503) — retry in a moment."
-    return message
-
-
 def _version_callback(value: bool) -> None:
     if value:
         typer.echo(f"skillnav {__version__}")
@@ -109,7 +131,7 @@ def _version_callback(value: bool) -> None:
 
 
 @app.callback()
-def main(
+def cli_root(
     ctx: typer.Context,
     registry: Annotated[
         Optional[str], typer.Option("--registry", help="API base URL (overrides profile)")
@@ -132,7 +154,7 @@ def main(
         ),
     ] = None,
 ) -> None:
-    """CLI client for the Skill management platform (MonoSkillNavigator)."""
+    """CLI client for the Skill management platform (SkillNavigator)."""
     _state["ctx"] = CliContext.resolve(
         registry_flag=registry,
         profile_flag=profile,
@@ -172,7 +194,7 @@ def config_use(name: Annotated[str, typer.Argument(help="Profile name to activat
         cli = _ctx()
         config = load_config()
         if name not in config.get("profiles", {}):
-            raise UsageError(f"Unknown profile: {name}")
+            raise UsageError.from_hint(enrich_usage_error(f"Unknown profile: {name}"))
         config["defaultProfile"] = name
         save_config(config)
         if cli.json_output:
@@ -216,7 +238,8 @@ def config_test(
         registry = profile.get("registry") or cli.registry
         status, body = request_json("GET", join_registry_url(registry, "/health"))
         if status >= 400:
-            raise SkillnavError(api_error_message(body))
+            hint = enrich_api_error(api_error_message(body), status=status, body=body)
+            raise SkillnavError(hint.summary, hint=hint)
         if cli.json_output:
             emit_json(body)
         else:
@@ -249,17 +272,17 @@ def login_cmd(
         credential = api_key
         if not credential:
             if cli.no_input:
-                raise AuthError("not logged in (run: skillnav login --api-key KEY)")
+                raise AuthError.from_hint(not_logged_in(profile=cli.profile_name))
             credential = typer.prompt("API key", hide_input=True).strip()
         if not credential:
-            raise AuthError("API key is required")
+            raise AuthError.from_hint(not_logged_in(profile=cli.profile_name))
         status, me_body = request_json(
             "GET",
             join_registry_url(cli.registry, "/auth/me"),
             token=credential,
         )
         if status >= 400:
-            raise AuthError(api_error_message(me_body))
+            raise AuthError.from_hint(invalid_api_key())
         cli.persist_api_key(credential, me_body)
         user = me_body.get("user") or {}
         if cli.json_output:
@@ -375,8 +398,14 @@ def info_cmd(slug: Annotated[str, typer.Argument(help="Skill slug")]) -> None:
 
 
 @app.command("status")
-def status_cmd(slug: Annotated[str, typer.Argument(help="Skill slug")]) -> None:
-    """Show publish status and version review summaries."""
+def status_cmd(
+    slug: Annotated[str, typer.Argument(help="Skill slug")],
+    version: Annotated[
+        Optional[str],
+        typer.Option("--version", help="Version to show (default: latest)"),
+    ] = None,
+) -> None:
+    """Show publish and inspection status for one skill version."""
     try:
         cli = _ctx()
         status, body = request_json(
@@ -385,10 +414,14 @@ def status_cmd(slug: Annotated[str, typer.Argument(help="Skill slug")]) -> None:
             token=cli.token,
         )
         raise_for_api_status(status, body)
+        target_version = version or body.get("latestVersion")
+        if not target_version:
+            raise SkillnavError(f"No versions found for skill '{slug}'")
+        body = filter_skill_body_version(body, str(target_version))
         if cli.json_output:
             emit_json(body)
         else:
-            print_skill_status(body)
+            print_skill_status(body, version=str(target_version))
     except Exception as exc:  # noqa: BLE001
         _handle_error(exc)
 
@@ -418,7 +451,28 @@ def report_cmd(
         _handle_error(exc)
 
 
-# --- publish / review ---
+# --- publish ---
+
+
+def _print_publish_response(status: int, payload: dict[str, Any], *, waited: bool) -> None:
+    if status == 202 or payload.get("inspectionStatus") == "inspecting":
+        typer.echo(
+            f"Uploaded {payload.get('name')} ({payload.get('slug')})@{payload.get('version')}"
+        )
+        if waited:
+            typer.echo("Inspection started (inspectionStatus: inspecting).")
+        else:
+            typer.echo("Inspection started in the background (inspectionStatus: inspecting).")
+        typer.echo(f"Check progress: skillnav status {payload.get('slug')}")
+        return
+
+    typer.echo(
+        f"Published {payload.get('name')} ({payload.get('slug')})@{payload.get('version')}"
+    )
+    typer.echo(f"Status: {payload.get('status')}")
+    typer.echo(f"Hash: {payload.get('contentHash')}")
+    if payload.get("inspection") or payload.get("review") or payload.get("evaluation"):
+        print_inspection_result(payload)
 
 
 @app.command("publish")
@@ -443,8 +497,15 @@ def publish_cmd(
     ] = None,
     changelog: Annotated[Optional[str], typer.Option("--changelog", help="Changelog text")] = None,
     dry_run: Annotated[bool, typer.Option("--dry-run", help="Preview without publishing")] = False,
+    wait: Annotated[
+        bool,
+        typer.Option(
+            "--wait",
+            help="Wait for the full inspection pipeline to finish before returning (default: upload only, inspection in background)",
+        ),
+    ] = False,
 ) -> None:
-    """Publish a skill package to the registry."""
+    """Upload a skill package to the registry; inspection runs in the background unless --wait."""
     try:
         cli = _ctx()
         token = cli.require_token()
@@ -466,6 +527,8 @@ def publish_cmd(
         body: dict[str, Any] = {"archiveBase64": archive_base64, "metadata": metadata}
         if changelog:
             body["changelog"] = changelog
+        if not dry_run:
+            body["async"] = not wait
         path = "/skills/publish/preview" if dry_run else "/skills/publish"
         status, payload = request_json(
             method="POST",
@@ -474,8 +537,8 @@ def publish_cmd(
             token=token,
         )
         if status >= 400:
-            message = _friendly_publish_error(api_error_message(payload))
-            raise SkillnavError(message)
+            hint = enrich_api_error(api_error_message(payload), status=status, body=payload)
+            raise SkillnavError(hint.summary, hint=hint)
         if cli.json_output:
             emit_json(payload if not dry_run else {"metadata": metadata, **payload})
             return
@@ -490,41 +553,39 @@ def publish_cmd(
             if payload.get("entryPath"):
                 typer.echo(f"Entry: {payload['entryPath']}")
             return
-        typer.echo(
-            f"Published {payload.get('name')} ({payload.get('slug')})@{payload.get('version')}"
-        )
-        typer.echo(f"Status: {payload.get('status')}")
-        typer.echo(f"Hash: {payload.get('contentHash')}")
-        if payload.get("review") or payload.get("evaluation"):
-            print_review_result(payload)
+        _print_publish_response(status, payload, waited=wait)
     except Exception as exc:  # noqa: BLE001
         _handle_error(exc)
 
 
-@app.command("review")
-def review_cmd(
-    package: Annotated[str, typer.Argument(help="Skill directory or .zip")],
-    version: Annotated[Optional[str], typer.Option("--version", help="Version label")] = None,
+@app.command("retry-publish")
+def retry_publish_cmd(
+    slug: Annotated[str, typer.Argument(help="Skill slug")],
+    wait: Annotated[
+        bool,
+        typer.Option(
+            "--wait",
+            help="Wait for the full inspection pipeline to finish before returning",
+        ),
+    ] = False,
 ) -> None:
-    """Run remote review without publishing."""
+    """Re-run inspection on the stored package after a failed or incomplete inspection."""
     try:
         cli = _ctx()
-        archive_base64 = package_to_base64(resolve_user_path(package))
-        body: dict[str, Any] = {"archiveBase64": archive_base64}
-        if version:
-            body["version"] = version
+        token = cli.require_token()
         status, payload = request_json(
-            "POST",
-            join_registry_url(cli.registry, "/reviews/run"),
-            body=body,
-            token=cli.require_token(),
+            method="POST",
+            url=join_registry_url(cli.registry, f"/skills/{slug_path(slug)}/retry-publish"),
+            body={"async": not wait},
+            token=token,
         )
-        raise_for_api_status(status, payload)
+        if status >= 400:
+            hint = enrich_api_error(api_error_message(payload), status=status, body=payload)
+            raise SkillnavError(hint.summary, hint=hint)
         if cli.json_output:
             emit_json(payload)
             return
-        if payload.get("review") or payload.get("evaluation"):
-            print_review_result(payload)
+        _print_publish_response(status, payload, waited=wait)
     except Exception as exc:  # noqa: BLE001
         _handle_error(exc)
 
@@ -557,9 +618,11 @@ def download_cmd(
                 import json
 
                 payload = json.loads(data.decode("utf-8"))
-                raise SkillnavError(api_error_message(payload))
+                hint = enrich_api_error(api_error_message(payload), status=status, body=payload)
+                raise SkillnavError(hint.summary, hint=hint)
             except (json.JSONDecodeError, UnicodeDecodeError):
-                raise SkillnavError(f"download failed ({status})") from None
+                hint = enrich_api_error(f"download failed ({status})", status=status)
+                raise SkillnavError(hint.summary, hint=hint) from None
         filename = parse_content_disposition_filename(headers.get("Content-Disposition"))
         out_path = output or Path(f"{slug}-{version}.zip")
         out_path.write_bytes(data)
@@ -596,9 +659,11 @@ def install_cmd(
 
             try:
                 payload = json.loads(data.decode("utf-8"))
-                raise SkillnavError(api_error_message(payload))
+                hint = enrich_api_error(api_error_message(payload), status=status, body=payload)
+                raise SkillnavError(hint.summary, hint=hint)
             except (json.JSONDecodeError, UnicodeDecodeError):
-                raise SkillnavError(f"download failed ({status})") from None
+                hint = enrich_api_error(f"download failed ({status})", status=status)
+                raise SkillnavError(hint.summary, hint=hint) from None
         target = dir or Path(slug)
         extract_zip_to_directory(data, target)
         if cli.json_output:
@@ -739,9 +804,11 @@ def remove_contributor_cmd(
     """Remove a contributor (owner only)."""
     try:
         if not id and not username:
-            raise UsageError("specify --id or --username")
+            raise UsageError.from_hint(enrich_usage_error("specify --id or --username"))
         if id and username:
-            raise UsageError("specify only one of --id or --username")
+            raise UsageError.from_hint(
+                enrich_usage_error("specify only one of --id or --username")
+            )
 
         cli = _ctx()
         token = cli.require_token()
@@ -755,6 +822,9 @@ def remove_contributor_cmd(
             raise_for_api_status(status, skill_body)
             contributor_id = resolve_contributor_id(skill_body, username)
 
+        if contributor_id is None:
+            raise UsageError.from_hint(enrich_usage_error("no contributor id available to remove"))
+
         status, payload = request_json(
             "DELETE",
             join_registry_url(
@@ -808,7 +878,12 @@ def run(argv: list[str] | None = None) -> int:
     except typer.Exit as exc:
         return int(exc.exit_code)
     except KeyboardInterrupt:
-        emit_error("interrupted", json_output=bool(_state.get("ctx") and _state["ctx"].json_output))
+        emit_error(
+            "interrupted",
+            json_output=bool(_state.get("ctx") and _state["ctx"].json_output),
+            detail="Command cancelled by user (Ctrl+C).",
+            next_steps=("Retry the command when ready.",),
+        )
         return 130
 
 

{skillnav-0.3.0 → skillnav-0.4.2}/src/skillnav/context.py

@@ -14,6 +14,7 @@ from skillnav.config import (
     save_config,
     set_profile_identity,
 )
+from skillnav.error_hints import not_logged_in
 from skillnav.errors import AuthError
 
 
@@ -68,7 +69,7 @@ class CliContext:
 
     def require_token(self) -> str:
         if not self.api_key:
-            raise AuthError("not logged in (run: skillnav login --api-key KEY)")
+            raise AuthError.from_hint(not_logged_in(profile=self.profile_name))
         return self.api_key
 
     def persist_api_key(self, api_key: str, me_body: dict) -> None:

{skillnav-0.3.0 → skillnav-0.4.2}/src/skillnav/contributors.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import Any
 
+from skillnav.error_hints import enrich_usage_error
 from skillnav.errors import SkillnavError
 
 
@@ -11,7 +12,9 @@ def resolve_contributor_id(skill_body: dict[str, Any], username: str) -> str:
     """Resolve a contributor id by username or display name (case-insensitive)."""
     needle = username.strip().casefold()
     if not needle:
-        raise SkillnavError("username must not be empty")
+        raise SkillnavError.from_hint(
+            enrich_usage_error("username must not be empty")
+        )
 
     matches: list[dict[str, Any]] = []
     for contributor in skill_body.get("contributors") or []:
@@ -25,10 +28,16 @@ def resolve_contributor_id(skill_body: dict[str, Any], username: str) -> str:
             matches.append(contributor)
 
     if not matches:
-        raise SkillnavError(f"contributor not found: {username}")
+        raise SkillnavError.from_hint(
+            enrich_usage_error(f"contributor not found: {username}")
+        )
     if len(matches) > 1:
-        raise SkillnavError(f"ambiguous contributor: {username}")
+        raise SkillnavError.from_hint(
+            enrich_usage_error(f"ambiguous contributor: {username}")
+        )
     contributor_id = matches[0].get("id")
     if not contributor_id:
-        raise SkillnavError(f"contributor not found: {username}")
+        raise SkillnavError.from_hint(
+            enrich_usage_error(f"contributor not found: {username}")
+        )
     return str(contributor_id)