logion-cli 0.1.0__py3-none-any.whl

cli/commands/referrals/parser.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for referrals commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import (
+    handle_referrals_attributions,
+    handle_referrals_code,
+    handle_referrals_link,
+    handle_referrals_stats,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``referrals`` subcommand group."""
+    parser = subparsers.add_parser(
+        "referrals",
+        help="Manage referral codes, links, and attributions",
+    )
+    sub = parser.add_subparsers(
+        dest="referrals_command",
+        required=True,
+    )
+
+    # referrals code
+    code = sub.add_parser(
+        "code",
+        help="Show your default referral code",
+        parents=[COMMON_PARSER],
+    )
+    code.set_defaults(handler=handle_referrals_code)
+
+    # referrals link
+    link = sub.add_parser(
+        "link",
+        help="Generate a referral link for a course",
+        parents=[COMMON_PARSER],
+    )
+    link.add_argument("course_id", metavar="COURSE_ID")
+    link.add_argument(
+        "--yes",
+        action="store_true",
+        help="Confirm sharing this referral link.",
+    )
+    link.set_defaults(handler=handle_referrals_link)
+
+    # referrals stats
+    stats = sub.add_parser(
+        "stats",
+        help="Show referral statistics",
+        parents=[COMMON_PARSER],
+    )
+    stats.set_defaults(handler=handle_referrals_stats)
+
+    # referrals attributions
+    attributions = sub.add_parser(
+        "attributions",
+        help="List referral attributions",
+        parents=[COMMON_PARSER],
+    )
+    attributions.set_defaults(handler=handle_referrals_attributions)

cli/commands/reports/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+"""Reports command package."""
+
+from .parser import register
+
+__all__ = ["register"]

cli/commands/reports/handlers.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for reports commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._config import resolve_config_from_args
+from cli._confirm import require_yes
+from cli._context import make_client
+from cli._errors import handle_error, require_non_empty_id, validate_uuid_id
+from cli._output import emit
+from cli._utils import only_not_none
+
+UUID_TARGET_TYPES = frozenset([
+    "agent",
+    "bounty",
+    "bounty_submission",
+    "course",
+    "user",
+])
+
+
+def _validate_target_id(target_type: str, target_id: str) -> int | None:
+    """Validate ``target_id`` for the selected report target type."""
+    if target_type in UUID_TARGET_TYPES:
+        return validate_uuid_id(target_id, "--target-id")
+    return require_non_empty_id(target_id, "--target-id")
+
+
+def handle_create(args: argparse.Namespace) -> int:
+    """Execute the reports create command."""
+    bad_id = _validate_target_id(args.target_type, args.target_id)
+    if bad_id is not None:
+        return bad_id
+    refusal = require_yes(args.yes, "create this report")
+    if refusal is not None:
+        return refusal
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {
+                "target_type": args.target_type,
+                "target_id": args.target_id,
+                "reason": args.reason,
+            },
+            description=args.description,
+        )
+        result = client.v1.reports.create(**kwargs)
+        emit(result, json_output=config.json_output)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()

cli/commands/reports/parser.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for reports commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import handle_create
+
+TARGET_TYPES = [
+    "agent",
+    "bounty",
+    "bounty_submission",
+    "course",
+    "user",
+]
+REPORT_REASONS = [
+    "spam",
+    "scam",
+    "harassment",
+    "hate",
+    "illegal",
+    "ip_violation",
+    "malware",
+    "other",
+]
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``reports`` subcommand group."""
+    parser = subparsers.add_parser(
+        "reports",
+        help="Create content reports",
+    )
+    sub = parser.add_subparsers(
+        dest="reports_command",
+        required=True,
+    )
+
+    create = sub.add_parser(
+        "create",
+        help="Create a new report",
+        parents=[COMMON_PARSER],
+    )
+    create.add_argument("--target-type", required=True, choices=TARGET_TYPES)
+    create.add_argument("--target-id", required=True)
+    create.add_argument("--reason", required=True, choices=REPORT_REASONS)
+    create.add_argument("--description")
+    create.add_argument("--yes", action="store_true")
+    create.set_defaults(handler=handle_create)

cli/commands/skills/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+"""Skills command package — local install/update/inspect of marketplace
+capabilities under ``~/.logion/installed``."""
+
+from .parser import register
+
+__all__ = ["register"]

cli/commands/skills/_agent_symlink.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: MIT
+"""Symlink installed skills into a coding agent's skill directory.
+
+Logion's canonical install location is
+``$LOGION_HOME/installed/<course-id>/<version-id>/``.  That keeps
+Logion's lifecycle separate from the user's agent harness.  But agents
+(Claude Code, Codex, OpenCode, Hermes, ...) load skills from their own
+fixed directories, so without a symlink the user has to wire the two
+together manually after every install.
+
+This module reads the skill name from the bundle's SKILL.md frontmatter
+and offers to create the symlink.  The target directory is whatever the
+user types — no auto-detection, no harness inference.  The known
+conventions are listed in the prompt as examples only.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Shown only as examples in the prompt.  We do not infer or filter.
+EXAMPLE_AGENT_DIRS: tuple[tuple[str, str], ...] = (
+    ("Claude Code", "~/.claude/skills"),
+    ("Codex", "~/.agents/skills"),
+    ("OpenCode", "~/.config/opencode/skills"),
+    ("Hermes", "~/.hermes/skills"),
+)
+
+
+def read_skill_name(source_dir: Path) -> str | None:
+    """Read ``name:`` from the bundle's SKILL.md frontmatter."""
+    skill_md = source_dir / "SKILL.md"
+    if not skill_md.is_file():
+        return None
+    try:
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    block = text[3:end]
+    for line in block.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("name:"):
+            value = stripped[len("name:") :].strip().strip('"').strip("'")
+            return value or None
+    return None
+
+
+def prompt_symlink_dir(
+    skill_name: str,
+    *,
+    explicit_dir: str | None,
+    no_symlink: bool,
+) -> Path | None:
+    """Decide where to symlink the installed skill.
+
+    Returns the resolved parent directory (which the link will be
+    placed inside) or ``None`` to skip.
+
+    Resolution order:
+      1. ``--no-symlink`` → None.
+      2. ``--symlink-dir PATH`` → PATH (no prompt).
+      3. Non-interactive (stdin not a TTY) → None.
+      4. Otherwise prompt: y/n, then a free-form path.
+    """
+    if no_symlink:
+        return None
+    if explicit_dir:
+        return Path(explicit_dir).expanduser()
+    if not sys.stdin.isatty():
+        return None
+
+    sys.stdout.write(
+        f"\nSymlink skill '{skill_name}' into a coding-agent skill dir? "
+        "[y/N]: "
+    )
+    sys.stdout.flush()
+    try:
+        raw = input().strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        sys.stdout.write("\n")
+        return None
+    if raw not in ("y", "yes"):
+        return None
+
+    sys.stdout.write("Target directory for the symlink. Examples:\n")
+    for label, path in EXAMPLE_AGENT_DIRS:
+        sys.stdout.write(f"  {label:14}  {path}\n")
+    sys.stdout.write("Path: ")
+    sys.stdout.flush()
+    try:
+        raw_path = input().strip()
+    except (EOFError, KeyboardInterrupt):
+        sys.stdout.write("\n")
+        return None
+    if not raw_path:
+        return None
+    return Path(raw_path).expanduser()
+
+
+def create_symlink(
+    parent_dir: Path, skill_name: str, install_dest: Path
+) -> Path:
+    """Symlink ``install_dest`` into ``parent_dir / skill_name``.
+
+    Replaces any prior symlink or file at the target.  Refuses to
+    clobber a real directory (the user may have placed it themselves).
+    Creates ``parent_dir`` if missing.  Returns the resulting link path.
+    """
+    parent_dir.mkdir(parents=True, exist_ok=True)
+    link = parent_dir / skill_name
+    if link.is_symlink() or link.is_file():
+        link.unlink()
+    elif link.is_dir():
+        raise FileExistsError(
+            f"{link} is a real directory, not a symlink. "
+            "Remove it before re-running install."
+        )
+    link.symlink_to(install_dest, target_is_directory=True)
+    return link
+
+
+def resolve_symlink_intent(
+    source_dir: Path, args
+) -> tuple[str | None, Path | None]:
+    """Read the skill name and prompt for symlink target up-front.
+
+    Returns ``(skill_name, symlink_parent)``.  Either or both may be None
+    if the bundle has no readable name or the user declined.
+    """
+    skill_name = read_skill_name(source_dir)
+    if not skill_name:
+        return None, None
+    symlink_parent = prompt_symlink_dir(
+        skill_name,
+        explicit_dir=getattr(args, "symlink_dir", None),
+        no_symlink=getattr(args, "dry_run", False)
+        or getattr(args, "no_symlink", True),
+    )
+    return skill_name, symlink_parent
+
+
+def apply_post_install_symlink(
+    symlink_parent: Path, skill_name: str, dest: Path
+) -> None:
+    """Create the symlink and surface errors as warnings (non-fatal)."""
+    try:
+        link = create_symlink(symlink_parent, skill_name, dest)
+    except FileExistsError as exc:
+        sys.stderr.write(f"WARN: symlink skipped: {exc}\n")
+    except OSError as exc:
+        sys.stderr.write(
+            f"WARN: symlink failed ({exc}); canonical install is fine\n"
+        )
+    else:
+        sys.stdout.write(f"Symlinked: {link} -> {dest}\n")

cli/commands/skills/_finalize.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+"""Finalisation step for ``logion skills install``.
+
+Kept separate from :mod:`_install_helpers` so each source file stays
+under the per-file line budget enforced by ``test_cli_architecture``.
+"""
+
+from __future__ import annotations
+
+import datetime
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from cli._local_state import (
+    build_index,
+    enrich_manifest,
+    rebuild_recall,
+    release_lock,
+    state_lock,
+    validate_manifest,
+    write_index,
+    write_manifest,
+)
+
+from ._install_helpers import compute_content_hash, copy_skill_files
+
+
+def copy_and_finalize(
+    source: Path,
+    dest: Path,
+    course_id: str,
+    version_id: str,
+    manifest_data: dict[str, Any],
+    home: Path,
+) -> tuple[int, list[Path]]:
+    """Copy files, write manifest+index+recall, and release the lock.
+
+    Returns ``(exit_code, copied)``.  On failure the partial install
+    is removed so the next attempt is not confused by orphan files.
+    Filesystem errors (rmtree/copy2/hashing) are caught and reported
+    as exit code 5 rather than allowed to crash the CLI.
+    """
+    copied: list[Path] = []
+    try:
+        try:
+            if dest.exists():
+                shutil.rmtree(dest)
+            copied = copy_skill_files(source, dest, dry_run=False)
+            existing_files = [
+                p for p in sorted(dest.rglob("*")) if p.is_file()
+            ]
+            manifest_data["content_sha256"] = compute_content_hash(
+                existing_files, root=dest
+            )
+        except (OSError, shutil.Error) as exc:
+            print(
+                f"ERROR: filesystem error while installing "
+                f"{course_id}/{version_id}: {exc}",
+                file=sys.stderr,
+            )
+            if dest.exists():
+                shutil.rmtree(dest, ignore_errors=True)
+            return 5, copied
+
+        manifest_data["installed_at"] = datetime.datetime.now(
+            datetime.UTC
+        ).isoformat()
+        manifest_data = enrich_manifest(
+            manifest_data,
+            course_id,
+            version_id,
+            home,
+        )
+        errors = validate_manifest(manifest_data)
+        if errors:
+            for e in errors:
+                print(f"MANIFEST ERROR: {e}", file=sys.stderr)
+            if dest.exists():
+                shutil.rmtree(dest, ignore_errors=True)
+            return 3, copied
+        try:
+            write_manifest(manifest_data, course_id, version_id, home)
+        except OSError as exc:
+            print(
+                f"ERROR: failed to write manifest for "
+                f"{course_id}/{version_id}: {exc}",
+                file=sys.stderr,
+            )
+            if dest.exists():
+                shutil.rmtree(dest, ignore_errors=True)
+            return 5, copied
+    finally:
+        release_lock(course_id, version_id, home)
+
+    try:
+        # state_lock serializes the index+recall refresh so a parallel
+        # install or `recall record` cannot race and drop entries.
+        with state_lock(home):
+            write_index(build_index(home), home)
+            rebuild_recall(home)
+    except OSError as exc:
+        # Install succeeded on disk; only the index/recall refresh
+        # failed.  Report but do not roll back — the next install or
+        # recall rebuild will repair the indexes.
+        print(
+            f"WARNING: install succeeded but index/recall refresh "
+            f"failed: {exc}",
+            file=sys.stderr,
+        )
+    return 0, copied

cli/commands/skills/_inspect_handler.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: MIT
+"""Handler for ``logion skills inspect``.
+
+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._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import emit_error_json
+from cli._local_state import (
+    UnsafeIdentifierError,
+    _safe_segment,
+    list_installed,
+    read_manifest,
+)
+from cli._output import emit_json
+
+from ._install_helpers import resolve_target
+
+_REMOTE_MERGE_KEYS = (
+    "title",
+    "slug",
+    "status",
+    "visibility",
+    "description",
+    "short_summary",
+    "price_cents",
+    "currency",
+    "language",
+    "owner_agent_id",
+    "tags",
+)
+
+
+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 _to_plain_dict(value: Any) -> dict[str, Any] | None:
+    """Convert SDK values to plain dicts when possible."""
+    if value is None:
+        return None
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")  # type: ignore[union-attr]
+    if isinstance(value, dict):
+        return dict(value)
+    return None
+
+
+def _fetch_remote_payloads(
+    args: argparse.Namespace,
+    course_id: str,
+    version_id: str | None,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    """Fetch remote course and version payloads when SDK support exists."""
+    try:
+        config = resolve_config_from_args(args)
+        client = make_client(config)
+    except Exception:
+        return None, None
+
+    try:
+        remote_course = None
+        remote_version = None
+        try:
+            remote_course = _to_plain_dict(
+                client.v1.courses.get(course_id=course_id)
+            )
+        except Exception:
+            remote_course = None
+
+        if version_id is not None and hasattr(
+            client.v1.courses, "get_version"
+        ):
+            try:
+                remote_version = _to_plain_dict(
+                    client.v1.courses.get_version(
+                        course_id=course_id,
+                        version_id=version_id,
+                    )
+                )
+            except Exception:
+                remote_version = None
+        return remote_course, remote_version
+    finally:
+        client.close()
+
+
+def _local_manifest_for_course(
+    home: Any, course_id: str
+) -> dict[str, Any] | None:
+    """Return the newest available local manifest for *course_id*."""
+    candidates = [
+        m for m in list_installed(home) if m.get("course_id") == course_id
+    ]
+    if not candidates:
+        return None
+    return candidates[-1]
+
+
+def _synthesized_remote_manifest(
+    course_id: str,
+    version_id: str | None,
+    remote_course: dict[str, Any],
+) -> dict[str, Any]:
+    """Build a provenance-compatible inspect payload
+    for remote-only courses.
+    """
+    latest_version = remote_course.get("latest_version_id")
+    return {
+        "course_id": course_id,
+        "version_id": version_id or latest_version,
+        "title": remote_course.get("title", ""),
+        "source": "logion-marketplace",
+        "entitlement_status": "missing",
+        "license_scope": "unknown",
+        "official_update_channel": True,
+        "last_verified_at": None,
+        "manifest_path": None,
+        "entrypoint": "SKILL.md",
+    }
+
+
+def handle_skills_inspect(args: argparse.Namespace) -> int:
+    """Inspect a local skill install, enriched with remote metadata."""
+    home = resolve_target(args)
+    course_id: str = args.course_id
+    version_id: str | None = getattr(args, "version_id", None)
+    verbose = bool(getattr(args, "verbose", False))
+
+    try:
+        _safe_segment(course_id, "course_id")
+        if version_id is not None:
+            _safe_segment(version_id, "version_id")
+    except UnsafeIdentifierError as exc:
+        return _error(args, "unsafe_identifier", str(exc), 2)
+
+    manifest = (
+        read_manifest(course_id, version_id, home)
+        if version_id is not None
+        else _local_manifest_for_course(home, course_id)
+    )
+    remote_course, remote_version = _fetch_remote_payloads(
+        args, course_id, version_id
+    )
+
+    if manifest is None and remote_course is None:
+        target = f"{course_id}/{version_id}" if version_id else course_id
+        return _error(
+            args, "not_found", f"No skill metadata found for {target}", 1
+        )
+
+    merged: dict[str, Any] = (
+        dict(manifest)
+        if manifest is not None
+        else _synthesized_remote_manifest(
+            course_id, version_id, remote_course or {}
+        )
+    )
+    if remote_course is not None:
+        for key in _REMOTE_MERGE_KEYS:
+            if key in remote_course and remote_course[key] is not None:
+                merged[key] = remote_course[key]
+        if verbose:
+            merged["remote_course"] = remote_course
+    if remote_version is not None:
+        merged["remote_version"] = remote_version
+        merged["version_id"] = remote_version.get(
+            "id", merged.get("version_id")
+        )
+        merged.setdefault(
+            "capabilities_manifest_path",
+            remote_version.get("capabilities_manifest_path"),
+        )
+        merged.setdefault("version_status", remote_version.get("status"))
+
+    if getattr(args, "json_output", False):
+        emit_json("logion.skills.inspect", merged)
+    else:
+        fields = [
+            ("course_id", merged.get("course_id", "")),
+            ("version_id", merged.get("version_id", "")),
+            ("title", merged.get("title", "")),
+            ("source", merged.get("source", "")),
+            ("entitlement_status", merged.get("entitlement_status", "")),
+            ("license_scope", merged.get("license_scope", "")),
+            (
+                "official_update_channel",
+                merged.get("official_update_channel", ""),
+            ),
+            (
+                "last_verified_at",
+                merged.get("last_verified_at", "") or "never",
+            ),
+            ("manifest_path", merged.get("manifest_path", "") or "n/a"),
+        ]
+        for label, value in fields:
+            print(f"  {label}: {value}")
+        if verbose and remote_version is not None:
+            print(
+                f"  remote_version_status: {remote_version.get('status', '')}"
+            )
+
+    return 0