logion-cli 0.1.0__py3-none-any.whl

cli/commands/skills/_install_helpers.py

@@ -0,0 +1,186 @@
+# SPDX-License-Identifier: MIT
+"""Internal helpers shared by the ``skills install`` and ``update``
+handlers.  Kept separate so handlers.py stays under the CLI's per-file
+source-size budget."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli._local_state import ensure_layout, read_manifest
+
+# Subset of ``source_dir`` that ``copy_skill_files`` actually installs.
+# Hashing must scan the same subset, otherwise extra files in the
+# source bundle (scripts/, tests/, etc.) produce false "different
+# content" errors against a manifest hash computed over only the
+# installed files.
+INSTALLED_SUBDIRS: tuple[str, ...] = ("course", "references", "templates")
+
+
+def resolve_target(args: argparse.Namespace) -> Path:
+    """Resolve LOGION_HOME from ``--target`` or the environment."""
+    target: Path | None = getattr(args, "target", None)
+    return ensure_layout(target)
+
+
+def collect_installable_files(source_dir: Path) -> list[Path]:
+    """Return the files that ``copy_skill_files`` would install.
+
+    Same algorithm as :func:`copy_skill_files` so a pre-copy hash can
+    be compared apples-to-apples against the post-install manifest
+    hash.  Excludes anything outside ``SKILL.md`` and
+    :data:`INSTALLED_SUBDIRS`.
+    """
+    out: list[Path] = []
+    skill_md = source_dir / "SKILL.md"
+    if skill_md.is_file():
+        out.append(skill_md)
+    for subdir in INSTALLED_SUBDIRS:
+        sdir = source_dir / subdir
+        if not sdir.is_dir():
+            continue
+        for child in sdir.rglob("*"):
+            if child.is_file() and child.name != "manifest.json":
+                out.append(child)
+    return sorted(out)
+
+
+_HASH_CHUNK = 64 * 1024  # 64 KiB — keeps peak memory bounded for big files.
+
+
+def compute_content_hash(files: list[Path], root: Path | None = None) -> str:
+    """Return SHA-256 over *files*, prefixing each with its rel path + length.
+
+    Reads each file in :data:`_HASH_CHUNK`-sized chunks so the peak
+    memory cost is bounded regardless of file size.  Each file
+    contributes ``<rel_path>\\0<length>\\0<bytes>\\0`` so renames or
+    repartitioning change the digest.  When *root* is provided, paths
+    are taken relative to it; otherwise the file name is used.
+    """
+    if not files:
+        return ""
+    h = hashlib.sha256()
+    for p in sorted(files):
+        if root is not None:
+            try:
+                rel = p.relative_to(root).as_posix()
+            except ValueError:
+                rel = p.name
+        else:
+            rel = p.name
+        size = p.stat().st_size
+        h.update(rel.encode("utf-8"))
+        h.update(b"\0")
+        h.update(str(size).encode("ascii"))
+        h.update(b"\0")
+        with p.open("rb") as fh:
+            while True:
+                chunk = fh.read(_HASH_CHUNK)
+                if not chunk:
+                    break
+                h.update(chunk)
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def read_capabilities(
+    cap_yaml: Path,
+    manifest_data: dict[str, Any],
+) -> dict[str, Any]:
+    """Update *manifest_data* with capabilities.yaml data if present.
+
+    Treats unreadable / malformed manifests the same way as a missing
+    file: leaves *manifest_data* untouched.  Catches ``OSError`` and
+    ``UnicodeDecodeError`` from ``read_text`` and ``yaml.YAMLError``
+    from parsing so a permissions glitch or non-UTF-8 file does not
+    crash ``logion skills install/update``.
+    """
+    if not cap_yaml.is_file():
+        return manifest_data
+    try:
+        raw = cap_yaml.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return manifest_data
+    try:
+        cap_data = yaml.safe_load(raw)
+    except yaml.YAMLError:
+        return manifest_data
+    if not isinstance(cap_data, dict):
+        return manifest_data
+    manifest_data["capabilities"] = [
+        c.get("id", "")
+        for c in cap_data.get("capabilities", [])
+        if isinstance(c, dict) and "id" in c
+    ]
+    manifest_data["required_tools"] = cap_data.get(
+        "tools", manifest_data.get("required_tools", ["terminal", "file"])
+    )
+    return manifest_data
+
+
+def check_existing_install(
+    course_id: str,
+    version_id: str,
+    source_dir: Path,
+    home: Path,
+) -> int:
+    """Return 0 if install can proceed, 2 if conflicting install exists."""
+    existing = read_manifest(course_id, version_id, home)
+    if existing is None:
+        return 0
+    existing_hash = existing.get("content_sha256", "")
+    new_hash = compute_content_hash(
+        collect_installable_files(source_dir), root=source_dir
+    )
+    if existing_hash and new_hash != existing_hash:
+        print(
+            f"ERROR: {course_id}/{version_id} already installed with "
+            "different content. Re-run `logion skills install ... --force` "
+            "to overwrite, or use `logion skills update` for the safety "
+            "checks.",
+            file=sys.stderr,
+        )
+        return 2
+    return 0
+
+
+def copy_skill_files(
+    src: Path,
+    dest: Path,
+    dry_run: bool,
+) -> list[Path]:
+    """Copy SKILL.md and supporting dirs from *src* to *dest*.
+
+    Excludes any ``manifest.json`` under the source tree — the manifest
+    is the install's own metadata, not part of the skill content, and
+    excluding it here keeps ``copy_skill_files`` byte-for-byte aligned
+    with the file set :func:`collect_installable_files` enumerates.
+    """
+    copied: list[Path] = []
+    skill_md = src / "SKILL.md"
+    if skill_md.is_file():
+        target = dest / "SKILL.md"
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(skill_md, target)
+        copied.append(target)
+    for subdir in INSTALLED_SUBDIRS:
+        sdir = src / subdir
+        if not sdir.is_dir():
+            continue
+        for child in sorted(sdir.rglob("*")):
+            if not child.is_file() or child.name == "manifest.json":
+                continue
+            target = dest / child.relative_to(src)
+            if not dry_run:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(child, target)
+            copied.append(target)
+    return copied

cli/commands/skills/_query_handlers.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for ``skills installed`` and ``skills updates`` commands."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from cli._local_state import (
+    list_installed,
+    verify_installed_content,
+)
+from cli._output import emit_json
+
+from .handlers import resolve_target
+
+
+def handle_skills_installed(args: argparse.Namespace) -> int:
+    """List installed skills."""
+    home = resolve_target(args)
+    installed = list_installed(home)
+    if getattr(args, "json_output", False):
+        emit_json("logion.skills.installed", installed)
+        return 0
+    if not installed:
+        print(f"No installed capabilities under {home / 'installed'}.")
+        return 0
+    print(f"Installed capabilities ({len(installed)}):")
+    for m in installed:
+        course_id = m.get("course_id", "?")
+        version_id = m.get("version_id", "?")
+        title = m.get("title", "")
+        status = m.get("review_status", "unknown")
+        line = f"  {course_id}/{version_id}"
+        if title:
+            line += f" — {title}"
+        line += f" [{status}]"
+        verification = verify_installed_content(course_id, version_id, home)
+        if verification["user_modified"]:
+            line += " [LOCALLY MODIFIED]"
+        print(line)
+    return 0
+
+
+def handle_skills_updates(args: argparse.Namespace) -> int:
+    """Report integrity of installed skills."""
+    home = resolve_target(args)
+    installed = list_installed(home)
+    if not installed:
+        print(f"No installed capabilities under {home / 'installed'}.")
+        return 0
+    out: list[dict[str, Any]] = []
+    for m in installed:
+        course_id = m.get("course_id", "?")
+        version_id = m.get("version_id", "?")
+        verification = verify_installed_content(course_id, version_id, home)
+        out.append({
+            "course_id": course_id,
+            "version_id": version_id,
+            "title": m.get("title", ""),
+            "source": m.get("source", "manual"),
+            "entitlement_status": m.get("entitlement_status", "unknown"),
+            "license_scope": m.get("license_scope", "unknown"),
+            "official_update_channel": m.get("official_update_channel", False),
+            "last_verified_at": m.get("last_verified_at"),
+            "manifest_path": m.get("manifest_path"),
+            "entrypoint": m.get("entrypoint", "SKILL.md"),
+            "ok": verification["ok"],
+            "user_modified": verification["user_modified"],
+        })
+    if getattr(args, "json_output", False):
+        emit_json("logion.skills.updates", out)
+        return 0
+    print(f"Update status ({len(out)} installed):")
+    for entry in out:
+        flags: list[str] = []
+        if entry["user_modified"]:
+            flags.append("locally-modified")
+        if not entry["ok"] and not entry["user_modified"]:
+            flags.append("integrity-unknown")
+        suffix = f" [{', '.join(flags)}]" if flags else ""
+        print(f"  {entry['course_id']}/{entry['version_id']}{suffix}")
+    return 0

cli/commands/skills/_search_handler.py

@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: MIT
+"""Handler for ``logion skills search``.
+
+Searches marketplace listings via the API and annotates each result
+with entitlement status derived from locally installed manifests.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error
+from cli._local_state import VALID_ENTITLEMENT_STATUSES, list_installed
+from cli._output import emit_json, truncate_summary
+
+from ._install_helpers import resolve_target
+
+
+def _normalize_items(result: Any) -> list[dict[str, Any]]:
+    """Convert SDK response items to plain dicts."""
+    # Prefer dict key 'items' over the dict method
+    if isinstance(result, dict):
+        raw = result.get("items", [])
+    elif hasattr(result, "items") and not isinstance(result, dict):
+        raw = getattr(result, "items", result)
+        if callable(raw):
+            raw = result
+    else:
+        raw = result
+
+    items: list[dict[str, Any]] = []
+    if isinstance(raw, list):
+        inner = raw
+    elif isinstance(raw, dict):
+        inner = raw.get("items", [raw])
+    else:
+        return items
+
+    for item in inner:
+        if hasattr(item, "model_dump"):
+            items.append(item.model_dump(mode="json"))
+        elif isinstance(item, dict):
+            items.append(dict(item))
+        else:
+            items.append({"value": item})
+    return items
+
+
+def _annotate_entitlement(
+    items: list[dict[str, Any]],
+    installed_manifests: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Add ``entitlement_status`` to each item based on installed data."""
+    entitlement_map: dict[str, str] = {}
+    for m in installed_manifests:
+        cid = m.get("course_id", "")
+        entitlement_map[cid] = m.get("entitlement_status", "unknown")
+
+    for item in items:
+        course_id = item.get("course_id")
+        if not isinstance(course_id, str) or not course_id:
+            item["entitlement_status"] = "unknown"
+            continue
+        if course_id in entitlement_map:
+            status = entitlement_map[course_id]
+            if status in VALID_ENTITLEMENT_STATUSES:
+                item["entitlement_status"] = status
+            else:
+                item["entitlement_status"] = "unknown"
+        else:
+            item["entitlement_status"] = "missing"
+    return items
+
+
+def _print_human(items: list[dict[str, Any]], verbose: bool) -> None:
+    """Print compact human-readable results."""
+    if not items:
+        print("No results found.")
+        return
+    print(f"Search results ({len(items)}):")
+    for item in items:
+        course_id = item.get("course_id", item.get("id", "?"))
+        title = item.get("title", "")
+        summary = truncate_summary(
+            item.get("short_summary") or item.get("summary") or ""
+        )
+        status = item.get("entitlement_status", "unknown")
+        line = f"  {course_id}"
+        if title:
+            line += f" — {title}"
+        line += f" [{status}]"
+        if summary:
+            line += f"\n    {summary}"
+        print(line, file=sys.stdout)
+    if verbose:
+        import json as _json
+
+        for item in items:
+            print(_json.dumps(item, indent=2, sort_keys=True))
+
+
+def handle_skills_search(args: argparse.Namespace) -> int:
+    """Search marketplace listings with installed/entitlement annotations."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    home = resolve_target(args)
+
+    installed_manifests = list_installed(home)
+
+    try:
+        result = client.v1.listings.search(
+            query=args.query,
+            limit=args.limit,
+        )
+    except Exception as exc:
+        return handle_error(exc)
+    finally:
+        client.close()
+
+    items = _normalize_items(result)
+    items = _annotate_entitlement(items, installed_manifests)
+
+    if config.json_output:
+        emit_json(
+            "logion.skills.search",
+            {"items": items, "total": len(items)},
+        )
+    else:
+        verbose = getattr(args, "verbose", False)
+        _print_human(items, verbose)
+
+    return 0

cli/commands/skills/_update_handler.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+"""Handler for ``logion skills update``.
+
+Kept separate from :mod:`handlers` so each file stays under the CLI's
+per-source-file line budget.  See :func:`handle_skills_update` for the
+control flow; the policy primitives live in :mod:`cli._update_policy`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from cli._local_state import read_manifest
+from cli._update_policy import evaluate_update
+
+from ._install_helpers import read_capabilities, resolve_target
+
+
+def _build_remote_manifest(
+    source: Path,
+    course_id: str,
+    version_id: str,
+    title: str | None,
+) -> dict[str, Any]:
+    """Synthesize a candidate manifest from a local source bundle.
+
+    The marketplace API is not in the loop for this flow — the
+    "remote" manifest is the one we *would* write if this install
+    proceeded.  ``evaluate_update`` diffs it against the installed
+    manifest to decide whether the change requires approval.
+    """
+    manifest: dict[str, Any] = {
+        "course_id": course_id,
+        "version_id": version_id,
+        "title": title or "",
+        "entrypoint": "SKILL.md",
+        "capabilities": [],
+        "required_tools": ["terminal", "file"],
+        "permissions": [],
+        "env_vars": [],
+        "execution_policy": "approval-required",
+        "review_status": "approved",
+    }
+    return read_capabilities(source / "course" / "capabilities.yaml", manifest)
+
+
+def handle_skills_update(args: argparse.Namespace) -> int:
+    """Apply an update with safety policy.
+
+    Diffs the installed manifest against the candidate manifest from
+    *source* via :func:`evaluate_update`.  If any gated field
+    (permissions, required tools, env vars, execution policy) changed
+    or the local content was modified, refuses unless ``--force`` is
+    passed.  Otherwise delegates to the install handler.
+    """
+    # Import here to avoid a circular import; handlers imports from
+    # this module via the parser registration.
+    from .handlers import handle_skills_install
+
+    home = resolve_target(args)
+    course_id: str = args.course_id
+    version_id: str = args.version_id
+
+    local_manifest = read_manifest(course_id, version_id, home)
+    if local_manifest is None:
+        print(
+            f"ERROR: no installed manifest for {course_id}/{version_id}; "
+            "use `logion skills install` first.",
+            file=sys.stderr,
+        )
+        return 1
+
+    remote_manifest = _build_remote_manifest(
+        args.source.resolve(),
+        course_id,
+        version_id,
+        getattr(args, "title", None),
+    )
+    policy = evaluate_update(
+        course_id, version_id, remote_manifest, local_manifest, home
+    )
+
+    if policy.notices:
+        for note in policy.notices:
+            print(f"NOTICE: {note}", file=sys.stderr)
+
+    blocked = policy.requires_approval or policy.blocks_silent_overwrite
+    if blocked and not args.force:
+        print(
+            f"Refusing to update {course_id}/{version_id} without approval:",
+            file=sys.stderr,
+        )
+        for reason in policy.reasons:
+            print(f"  - {reason}", file=sys.stderr)
+        print("Pass --force to apply.", file=sys.stderr)
+        return 2
+
+    install_args = argparse.Namespace(
+        source=args.source,
+        course_id=course_id,
+        version_id=version_id,
+        title=getattr(args, "title", None),
+        target=getattr(args, "target", None),
+        dry_run=False,
+        force=True,
+    )
+    return handle_skills_install(install_args)

cli/commands/skills/_verify_handler.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+"""Handler for ``logion skills verify``.
+
+Kept separate from :mod:`handlers` so each file stays under the CLI's
+per-source-file line budget.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from cli._errors import emit_error_json
+from cli._local_state import (
+    VALID_ENTITLEMENT_STATUSES,
+    UnsafeIdentifierError,
+    _safe_segment,
+    list_installed,
+    write_manifest,
+)
+from cli._output import emit_json
+
+from ._install_helpers import resolve_target
+
+
+def _error(
+    args: argparse.Namespace, code: str, message: str, exit_code: int
+) -> int:
+    """Emit a compliant error in JSON or human form."""
+    if getattr(args, "json_output", False):
+        emit_error_json(code, message, exit_code)
+    else:
+        print(f"ERROR: {message}", file=sys.stderr)
+    return exit_code
+
+
+def _local_verify_status(manifest: dict[str, Any]) -> str:
+    """Preserve the locally recorded entitlement status.
+
+    The public SDK currently exposes no entitlements read endpoint, so this
+    command cannot prove fresh server-side ownership. Marketplace installs keep
+    their stored entitlement state; non-marketplace installs remain unknown.
+    """
+    source = manifest.get("source")
+    current = manifest.get("entitlement_status")
+    if source != "logion-marketplace":
+        return "unknown"
+    if current in VALID_ENTITLEMENT_STATUSES:
+        return str(current)
+    return "unknown"
+
+
+def _verification_mode(_manifest: dict[str, Any]) -> str:
+    """Return the verification mode reported to callers."""
+    return "local-manifest-only"
+
+
+def handle_skills_verify(args: argparse.Namespace) -> int:
+    """Refresh locally stored entitlement metadata for installed skills."""
+    home = resolve_target(args)
+    course_id: str | None = getattr(args, "course_id", None)
+
+    if course_id is not None:
+        try:
+            _safe_segment(course_id, "course_id")
+        except UnsafeIdentifierError as exc:
+            return _error(args, "unsafe_identifier", str(exc), 2)
+
+    installed = list_installed(home)
+    if course_id is not None:
+        installed = [m for m in installed if m.get("course_id") == course_id]
+
+    results: list[dict[str, Any]] = []
+
+    for manifest in installed:
+        cid = str(manifest.get("course_id", "?"))
+        vid = str(manifest.get("version_id", "?"))
+        new_status = _local_verify_status(manifest)
+        old_status = manifest.get("entitlement_status")
+        manifest["entitlement_status"] = new_status
+        if new_status != old_status:
+            write_manifest(manifest, cid, vid, home)
+        results.append({
+            "course_id": cid,
+            "entitlement_status": new_status,
+            "last_verified_at": manifest.get("last_verified_at"),
+            "source": manifest.get("source", "unknown"),
+            "verification_mode": _verification_mode(manifest),
+        })
+
+    if getattr(args, "json_output", False):
+        emit_json("logion.skills.verify", results)
+        return 0
+
+    if not results:
+        print("No installed skills to verify.")
+        return 0
+
+    print(f"Verification results ({len(results)} skill(s)):")
+    for entry in results:
+        print(
+            f"  {entry['course_id']}: "
+            f"entitlement={entry['entitlement_status']}, "
+            f"mode={entry['verification_mode']}, "
+            f"source={entry['source']}, "
+            f"last_verified_at={entry['last_verified_at']}"
+        )
+    return 0