logion-cli 0.1.0__py3-none-any.whl

cli/commands/course_reviews/_render.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+"""Capability evidence rendering for course-reviews CLI commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def append_review_capability_evidence_lines(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    """Append human-readable capability evidence lines to *lines*.
+
+    Used by course-reviews get to render declared/observed/mismatch
+    evidence in a readable format.
+    """
+    status = payload.get("capabilities_status")
+    if status is not None:
+        lines.append(f"capabilities_status: {status}")
+
+    score = payload.get("capability_risk_score")
+    if score is not None:
+        lines.append(f"capability_risk_score: {score}")
+
+    declared = payload.get("declared_capabilities")
+    if declared:
+        lines.append("declared_capabilities:")
+        _append_declared_lines(lines, declared)
+
+    observed = payload.get("observed_capabilities")
+    if observed:
+        lines.append("observed_capabilities:")
+        _append_observed_lines(lines, observed)
+
+    mismatches = payload.get("capability_mismatches")
+    if mismatches:
+        lines.append("capability_mismatches:")
+        for m in mismatches:
+            severity = m.get("severity", "unknown")
+            code = m.get("code", "unknown")
+            lines.append(f"  - {severity}: {code}")
+            if "observed" in m:
+                lines.append(f"    observed: {m['observed']}")
+            if "declared" in m:
+                lines.append(f"    declared: {m['declared']}")
+            if "message" in m:
+                lines.append(f"    message: {m['message']}")
+
+
+def append_queue_capability_summary_lines(
+    lines: list[str],
+    item: dict[str, Any],
+) -> None:
+    """Append compact capability summary lines for queue list items.
+
+    Only shows status, score, and mismatch count — never full payloads.
+    """
+    status = item.get("capabilities_status")
+    if status is not None:
+        lines.append(f"capabilities_status: {status}")
+
+    score = item.get("capability_risk_score")
+    if score is not None:
+        lines.append(f"capability_risk_score: {score}")
+
+    count = item.get("capability_mismatch_count")
+    if count is not None:
+        lines.append(f"capability_mismatch_count: {count}")
+
+
+def _append_declared_lines(
+    lines: list[str],
+    declared: dict[str, Any],
+) -> None:
+    tools = declared.get("tools")
+    if tools:
+        lines.append(f"  tools: {', '.join(tools)}")
+
+    network = declared.get("network")
+    if network:
+        domains = network.get("allow_domains")
+        if domains:
+            lines.append(f"  network.allow_domains: {', '.join(domains)}")
+
+    filesystem = declared.get("filesystem")
+    if filesystem:
+        write_paths = filesystem.get("write")
+        if write_paths:
+            lines.append(f"  filesystem.write: {', '.join(write_paths)}")
+
+    secrets = declared.get("secrets")
+    if secrets:
+        env_vars = secrets.get("env")
+        if env_vars:
+            lines.append(f"  secrets.env: {', '.join(env_vars)}")
+
+    human_approval = declared.get("human_approval")
+    if human_approval:
+        required = human_approval.get("required")
+        if required is not None:
+            lines.append(f"  human_approval.required: {str(required).lower()}")
+
+
+def _append_observed_lines(
+    lines: list[str],
+    observed: dict[str, Any],
+) -> None:
+    tools = observed.get("tools")
+    if tools:
+        lines.append(f"  tools: {', '.join(tools)}")
+
+    hosts = observed.get("network_hosts")
+    if hosts:
+        lines.append(f"  network_hosts: {', '.join(hosts)}")
+
+    fs_write = observed.get("filesystem_write")
+    if fs_write:
+        lines.append(f"  filesystem_write: {', '.join(fs_write)}")
+
+    env_vars = observed.get("secrets_env")
+    if env_vars:
+        lines.append(f"  secrets_env: {', '.join(env_vars)}")
+
+    dangerous = observed.get("dangerous_commands_detected")
+    if dangerous is not None:
+        lines.append(
+            f"  dangerous_commands_detected: {str(dangerous).lower()}"
+        )

cli/commands/course_reviews/handlers.py

@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for course-reviews commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from pydantic import BaseModel
+
+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, print_err, validate_uuid_id
+from cli._output import emit
+from cli._utils import only_not_none
+from cli.commands.course_reviews._render import (
+    append_queue_capability_summary_lines,
+    append_review_capability_evidence_lines,
+)
+
+REQUIRE_NON_EMPTY_MSG = "Error: {} must not be empty."
+
+
+def handle_list(args: argparse.Namespace) -> int:
+    """Execute course-reviews list."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none({}, limit=args.limit, cursor=args.cursor)
+        result = client.v1.course_reviews.list(**kwargs)
+        if config.json_output:
+            emit(result, json_output=True)
+        else:
+            _render_list(result)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_get(args: argparse.Namespace) -> int:
+    """Execute course-reviews get."""
+    bad_id = validate_uuid_id(args.review_id, "REVIEW_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.course_reviews.get(review_id=args.review_id)
+        if config.json_output:
+            emit(result, json_output=True)
+        else:
+            _render_get(result)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_approve(args: argparse.Namespace) -> int:
+    """Execute course-reviews approve."""
+    bad_id = validate_uuid_id(args.review_id, "REVIEW_ID")
+    if bad_id is not None:
+        return bad_id
+    if args.reviewer_notes is not None and not args.reviewer_notes.strip():
+        print_err(REQUIRE_NON_EMPTY_MSG.format("--reviewer-notes"))
+        return 2
+    refusal = require_yes(args.yes, "approve this review")
+    if refusal is not None:
+        return refusal
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {"review_id": args.review_id},
+            reviewer_notes=args.reviewer_notes,
+            acknowledge_capability_mismatches=(
+                args.acknowledge_capability_mismatches or None
+            ),
+        )
+        result = client.v1.course_reviews.approve(**kwargs)
+        emit(result, json_output=config.json_output)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_reject(args: argparse.Namespace) -> int:
+    """Execute course-reviews reject."""
+    bad_id = validate_uuid_id(args.review_id, "REVIEW_ID")
+    if bad_id is not None:
+        return bad_id
+    if not args.decision_reason.strip():
+        print_err(REQUIRE_NON_EMPTY_MSG.format("--decision-reason"))
+        return 2
+    if not args.reviewer_notes.strip():
+        print_err(REQUIRE_NON_EMPTY_MSG.format("--reviewer-notes"))
+        return 2
+    refusal = require_yes(args.yes, "reject this review")
+    if refusal is not None:
+        return refusal
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.course_reviews.reject(
+            review_id=args.review_id,
+            decision_reason=args.decision_reason,
+            reviewer_notes=args.reviewer_notes,
+            capability_reason_code=args.capability_reason_code,
+        )
+        emit(result, json_output=config.json_output)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+# ── Human-readable rendering helpers ────────────────────────────
+
+
+def _to_data(value: object) -> dict:
+    """Convert a Pydantic model or dict to a plain dict."""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, dict):
+        return value
+    return json.loads(json.dumps(value))
+
+
+def _render_list(result: object) -> None:
+    """Render queue list with human-readable capability summary."""
+    data = _to_data(result)
+    items = data.get("items", [])
+    if not items:
+        sys.stdout.write("No reviews in the queue.\n")
+        return
+    for item in items:
+        course = (
+            f"{item.get('course_title', '')} ({item.get('course_id', '')})"
+        )
+        lines: list[str] = [
+            f"review_id: {item.get('review_id', '')}",
+            f"course: {course}",
+            f"status: {item.get('review_status', '')}",
+            f"findings: {item.get('finding_count', 0)}",
+        ]
+        append_queue_capability_summary_lines(lines, item)
+        sys.stdout.write("\n".join(lines) + "\n\n")
+
+
+def _render_get(result: object) -> None:
+    """Render review detail with human-readable capability evidence."""
+    data = _to_data(result)
+    course = f"{data.get('course_title', '')} ({data.get('course_id', '')})"
+    lines: list[str] = [
+        f"review_id: {data.get('review_id', '')}",
+        f"course: {course}",
+        f"version_id: {data.get('version_id', '')}",
+        f"status: {data.get('review_status', '')}",
+        f"owner_agent_id: {data.get('owner_agent_id', '')}",
+        f"submitted_at: {data.get('submitted_at', '')}",
+    ]
+    append_review_capability_evidence_lines(lines, data)
+
+    findings_by_layer = data.get("findings_by_layer", {})
+    if findings_by_layer:
+        lines.append("findings:")
+        for layer, findings in findings_by_layer.items():
+            lines.append(f"  {layer}:")
+            for f in findings:
+                severity = f.get("severity", "unknown")
+                rule_id = f.get("rule_id", "unknown")
+                desc = f.get("description", "")
+                pass_marker = " [PASS]" if f.get("is_pass") else ""
+                lines.append(f"    - {severity}: {rule_id}{pass_marker}")
+                if desc:
+                    lines.append(f"      {desc}")
+
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+# Re-export from _download_handler so cli.commands.course_reviews.parser
+# can keep importing handle_download from this module.
+from cli.commands.course_reviews._download_handler import (  # noqa: E402, F401
+    handle_download,
+)

cli/commands/course_reviews/parser.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for course-reviews commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import (
+    handle_approve,
+    handle_download,
+    handle_get,
+    handle_list,
+    handle_reject,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``course-reviews`` subcommand group."""
+    parser = subparsers.add_parser(
+        "course-reviews",
+        help="Manage course publication review queue",
+    )
+    sub = parser.add_subparsers(
+        dest="course_reviews_command",
+        required=True,
+    )
+
+    list_parser = sub.add_parser(
+        "list",
+        help="List actionable review queue items",
+        parents=[COMMON_PARSER],
+    )
+    list_parser.add_argument("--limit", type=int)
+    list_parser.add_argument("--cursor")
+    list_parser.set_defaults(handler=handle_list)
+
+    get = sub.add_parser(
+        "get",
+        help="Get review queue item details",
+        parents=[COMMON_PARSER],
+    )
+    get.add_argument("review_id", metavar="REVIEW_ID")
+    get.set_defaults(handler=handle_get)
+
+    approve = sub.add_parser(
+        "approve",
+        help="Approve a publication review",
+        parents=[COMMON_PARSER],
+    )
+    approve.add_argument("review_id", metavar="REVIEW_ID")
+    approve.add_argument("--reviewer-notes")
+    approve.add_argument(
+        "--acknowledge-capability-mismatches",
+        action="store_true",
+        help="Acknowledge capability mismatches on the review",
+    )
+    approve.add_argument("--yes", action="store_true")
+    approve.set_defaults(handler=handle_approve)
+
+    reject = sub.add_parser(
+        "reject",
+        help="Reject a publication review",
+        parents=[COMMON_PARSER],
+    )
+    reject.add_argument("review_id", metavar="REVIEW_ID")
+    reject.add_argument("--decision-reason", required=True)
+    reject.add_argument("--reviewer-notes", required=True)
+    reject.add_argument(
+        "--capability-reason-code",
+        help="Code from the review's capability mismatches",
+    )
+    reject.add_argument("--yes", action="store_true")
+    reject.set_defaults(handler=handle_reject)
+
+    download = sub.add_parser(
+        "download",
+        help=(
+            "Download the bundle under review to a local directory "
+            "so SKILL.md and references can be read before deciding"
+        ),
+        parents=[COMMON_PARSER],
+    )
+    download.add_argument("review_id", metavar="REVIEW_ID")
+    download.add_argument(
+        "--target",
+        help=(
+            "Directory to write the bundle into "
+            "(default: ./review-bundles/<review-id>/)"
+        ),
+    )
+    download.set_defaults(handler=handle_download)

cli/commands/courses/__init__.py

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

cli/commands/courses/_capability_render.py

@@ -0,0 +1,183 @@
+# SPDX-License-Identifier: MIT
+"""Shared capability summary rendering for CLI commands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _append_meta_fields(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    """Append capability metadata fields."""
+    status = payload.get("capabilities_status")
+    if status:
+        lines.append(f"capabilities_status: {status}")
+    schema_version = payload.get("capabilities_schema_version")
+    if schema_version is not None:
+        lines.append(f"capabilities_schema_version: {schema_version}")
+    manifest_path = payload.get("capabilities_manifest_path")
+    if manifest_path is not None:
+        lines.append(f"capabilities_manifest_path: {manifest_path}")
+
+
+def _append_summary_fields(
+    lines: list[str],
+    summary: dict[str, Any],
+) -> None:
+    """Append capability summary detail fields (tools, permissions, paths)."""
+    for tool in summary.get("tools") or []:
+        lines.append(f"tools: {tool}")
+    allows_shell = summary.get("allows_shell")
+    if allows_shell is not None:
+        lines.append(f"allows_shell: {str(allows_shell).lower()}")
+    allows_network = summary.get("allows_network")
+    if allows_network is not None:
+        lines.append(f"allows_network: {str(allows_network).lower()}")
+    for domain in summary.get("allowed_domains") or []:
+        lines.append(f"allowed_domains: {domain}")
+    for rpath in summary.get("filesystem_read") or []:
+        lines.append(f"filesystem_read: {rpath}")
+    for wpath in summary.get("filesystem_write") or []:
+        lines.append(f"filesystem_write: {wpath}")
+    for env_var in summary.get("secrets_env") or []:
+        lines.append(f"secrets_env: {env_var}")
+    human_approval = summary.get("human_approval_required")
+    if human_approval is not None:
+        lines.append(f"human_approval_required: {str(human_approval).lower()}")
+    _append_runtime_fields(lines, summary)
+    _append_runtime_warnings(lines, summary)
+
+
+def _render_install_steps(
+    lines: list[str],
+    install: list[dict[str, Any]],
+) -> None:
+    """Append install-step detail lines."""
+    lines.append("  install_steps:")
+    for step in install:
+        req = "required" if step.get("required") else "optional"
+        kind = step.get("kind", "")
+        command = step.get("command", "")
+        notes = step.get("notes", "")
+        cmd_part = f": {command}" if command else ""
+        note_part = f": {notes}" if notes else ""
+        lines.append(f"    - {kind}{cmd_part} ({req}){note_part}")
+
+
+def _append_runtime_fields(
+    lines: list[str],
+    summary: dict[str, Any],
+) -> None:
+    """Append runtime requirement and install-step detail fields.
+
+    Only rendered when any runtime field is non-empty, so minimal
+    manifests stay compact.
+    """
+    env = summary.get("runtime_requires_env") or []
+    bins = summary.get("runtime_requires_bins") or []
+    any_bins = summary.get("runtime_requires_any_bins") or []
+    config = summary.get("runtime_requires_config") or []
+    os_vals = summary.get("runtime_requires_os") or []
+    software = summary.get("runtime_requires_software") or []
+    install = summary.get("runtime_install") or []
+    if not any([env, bins, any_bins, config, os_vals, software, install]):
+        return
+    lines.append("runtime_requirements:")
+    if env:
+        lines.append(f"  env: {', '.join(env)}")
+    if bins:
+        lines.append(f"  bins: {', '.join(bins)}")
+    if any_bins:
+        groups = [" or ".join(g) for g in any_bins]
+        lines.append(f"  any_bins: {', '.join(groups)}")
+    if config:
+        lines.append(f"  config: {', '.join(config)}")
+    if os_vals:
+        lines.append(f"  os: {', '.join(os_vals)}")
+    if software:
+        lines.append("  software:")
+        for sw in software:
+            req = "required" if sw.get("required") else "optional"
+            install_kind = sw.get("install", "external")
+            name = sw.get("name", "")
+            notes = sw.get("notes", "")
+            suffix = f": {notes}" if notes else ""
+            lines.append(f"    - {name} ({install_kind}, {req}){suffix}")
+    if install:
+        _render_install_steps(lines, install)
+
+
+def _append_runtime_warnings(
+    lines: list[str],
+    summary: dict[str, Any],
+) -> None:
+    """Append runtime cross-field warning codes."""
+    codes = summary.get("runtime_warning_codes") or []
+    if not codes:
+        return
+    lines.append("runtime_warnings:")
+    for code in codes:
+        lines.append(f"  - {code}")
+
+
+def append_capability_summary_lines(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    """Append human-readable capability summary lines to *lines*."""
+    _append_meta_fields(lines, payload)
+    summary = payload.get("capabilities_summary")
+    if summary:
+        _append_summary_fields(lines, summary)
+
+
+def append_approved_capability_summary_lines(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    """Append human-readable approved capability summary lines.
+
+    Only renders the buyer-safe subset: tools, allows_shell,
+    allows_network, allowed_domains, human_approval_required.
+    Does not expose review-only evidence.
+    """
+    approved = payload.get("approved_capabilities_summary")
+    if not approved or not isinstance(approved, dict):
+        return
+    lines.append("approved_capabilities_summary:")
+    for tool in approved.get("tools") or []:
+        lines.append(f"  tools: {tool}")
+    allows_shell = approved.get("allows_shell")
+    if allows_shell is not None:
+        lines.append(f"  allows_shell: {str(allows_shell).lower()}")
+    allows_network = approved.get("allows_network")
+    if allows_network is not None:
+        lines.append(f"  allows_network: {str(allows_network).lower()}")
+    for domain in approved.get("allowed_domains") or []:
+        lines.append(f"  allowed_domains: {domain}")
+    human_approval = approved.get("human_approval_required")
+    if human_approval is not None:
+        val = str(human_approval).lower()
+        lines.append(f"  human_approval_required: {val}")
+
+
+def append_capability_feedback_lines(
+    lines: list[str],
+    payload: dict[str, Any],
+) -> None:
+    """Append human-readable capability feedback items."""
+    feedback_items = payload.get("capability_feedback")
+    if not feedback_items:
+        return
+    lines.append("capability_feedback:")
+    for item in feedback_items:
+        code = item.get("reason_code", "unknown")
+        msg = item.get("message", "")
+        lines.append(f"  - reason_code: {code}")
+        if msg:
+            lines.append(f"    message: {msg}")
+        file_path = item.get("file_path")
+        if file_path:
+            lines.append(f"    file_path: {file_path}")

cli/commands/courses/_cmd_help.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MIT
+"""Help strings for courses subcommands."""
+
+CMD_HELP = {
+    "create": "Create a new course",
+    "get": "Get course details",
+    "purchase": "Purchase a course using credits",
+    "update": "Update an existing course",
+    "uploads": "Manage course version uploads",
+    "publication": "Manage course publication review",
+    "reviews": "Manage marketplace course reviews",
+    "feedback": "Get review feedback for a course",
+    "versions": "Manage course versions",
+    "capabilities": "Validate and inspect local capability manifests",
+    "report-usage": (
+        "File a usage review after completing a course-driven task"
+    ),
+}