logion-cli 0.1.0__py3-none-any.whl

cli/commands/courses/capabilities.py

@@ -0,0 +1,250 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for ``courses capabilities`` sub-commands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli._config import resolve_config_from_args
+from cli._course_bundle import CourseBundleError, validate_course_bundle
+from cli._course_capabilities import (
+    CAPABILITY_MANIFEST_PATH,
+    CapabilityManifestError,
+    load_and_validate_capability_manifest,
+    summarize_capability_manifest,
+)
+from cli._output import emit_json
+from cli.commands.courses._capability_render import (
+    _append_summary_fields,
+)
+from cli.commands.courses.capability_frontmatter import (
+    extract_logion_capabilities_from_skill,
+)
+
+CAPABILITIES_TEMPLATE_FILENAME = "course_capabilities.template.yaml"
+LICENSE_TEMPLATE_FILES = {
+    "mit": "course_license_mit.template.txt",
+    "apache-2.0": "course_license_apache-2.0.template.txt",
+    "logion-standard-course-v1": (
+        "course_license_logion-standard-course-v1.template.txt"
+    ),
+}
+
+
+def handle_courses_capabilities_validate(
+    args: argparse.Namespace,
+) -> int:
+    """Validate a local capability manifest and print a summary."""
+    try:
+        validate_course_bundle(args.bundle_dir)
+        manifest = load_and_validate_capability_manifest(args.bundle_dir)
+    except CourseBundleError as exc:
+        print(f"Invalid course bundle: {exc}", file=sys.stderr)
+        return 2
+    except CapabilityManifestError as exc:
+        print(f"Invalid capability manifest: {exc}", file=sys.stderr)
+        return 2
+    config = resolve_config_from_args(args)
+    summary = summarize_capability_manifest(manifest)
+    if config.json_output:
+        payload = {"capabilities_status": "declared", **summary}
+        emit_json("logion.courses.capabilities.validate", payload)
+    else:
+        lines = ["capabilities_status: declared"]
+        _append_summary_fields(lines, summary)
+        print("\n".join(lines))
+    return 0
+
+
+def handle_courses_capabilities_print(
+    args: argparse.Namespace,
+) -> int:
+    """Validate a local capability manifest and print normalised JSON."""
+    try:
+        validate_course_bundle(args.bundle_dir)
+        manifest = load_and_validate_capability_manifest(args.bundle_dir)
+    except CourseBundleError as exc:
+        print(f"Invalid course bundle: {exc}", file=sys.stderr)
+        return 2
+    except CapabilityManifestError as exc:
+        print(f"Invalid capability manifest: {exc}", file=sys.stderr)
+        return 2
+    config = resolve_config_from_args(args)
+    if config.json_output:
+        emit_json("logion.courses.capabilities.print", manifest)
+    else:
+        print(json.dumps(manifest, indent=2, sort_keys=True))
+    return 0
+
+
+def _template_text() -> str:
+    """Return the bundled capability manifest scaffold contents."""
+    return (
+        resources
+        .files("cli.templates")
+        .joinpath(CAPABILITIES_TEMPLATE_FILENAME)
+        .read_text(encoding="utf-8")
+    )
+
+
+def _license_template_text(template_name: str) -> str:
+    """Return the bundled LICENSE scaffold contents."""
+    return (
+        resources
+        .files("cli.templates")
+        .joinpath(LICENSE_TEMPLATE_FILES[template_name])
+        .read_text(encoding="utf-8")
+    )
+
+
+def _default_license_template(license_template: str | None) -> str:
+    """Choose a license template when scaffolding a local bundle."""
+    return license_template or "mit"
+
+
+def _serialize_manifest_yaml(manifest: dict[str, Any]) -> str:
+    """Serialise a normalised manifest dict to YAML with a header."""
+    body = yaml.safe_dump(
+        manifest,
+        default_flow_style=False,
+        sort_keys=True,
+        allow_unicode=True,
+        width=88,
+    )
+    header = (
+        "# course/capabilities.yaml — generated from SKILL.md\n"
+        "#\n"
+        "# Generated by `logion courses capabilities scaffold --from-skill`.\n"
+        "# Review every field before publishing. This file is the canonical\n"
+        "# publication contract — SKILL.md frontmatter is only a seed.\n"
+        "\n"
+    )
+    return header + body
+
+
+def _scaffold_from_skill(
+    skill_path: Path,
+    bundle_dir: Path | None,
+    force: bool,
+    license_template: str | None,
+) -> int:
+    """Seed a capability manifest from SKILL.md frontmatter."""
+    try:
+        manifest = extract_logion_capabilities_from_skill(skill_path)
+    except CapabilityManifestError as exc:
+        print(f"Error reading SKILL.md: {exc}", file=sys.stderr)
+        return 2
+    if manifest is None:
+        print(
+            "SKILL.md has no metadata.logion capability manifest",
+            file=sys.stderr,
+        )
+        return 2
+    text = _serialize_manifest_yaml(manifest)
+    if bundle_dir is None:
+        print(text, end="")
+        return 0
+    dest = bundle_dir / CAPABILITY_MANIFEST_PATH
+    if dest.exists() and not force:
+        print(
+            f"Refusing to overwrite existing manifest: {dest} "
+            "(pass --force to replace)",
+            file=sys.stderr,
+        )
+        return 2
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(text, encoding="utf-8")
+    print(f"Wrote scaffold to {dest}")
+    return _write_scaffold_license(bundle_dir, license_template, force)
+
+
+def _write_license_template(
+    bundle_dir: Path,
+    template_name: str,
+    force: bool,
+) -> None:
+    """Materialise a LICENSE file from the selected template."""
+    dest = bundle_dir / "LICENSE"
+    if dest.exists() and not force:
+        raise FileExistsError(dest)
+    dest.write_text(_license_template_text(template_name), encoding="utf-8")
+
+
+def _write_scaffold_license(
+    bundle_dir: Path,
+    license_template: str | None,
+    force: bool,
+) -> int:
+    """Write the bundle LICENSE file for scaffold flows."""
+    try:
+        _write_license_template(
+            bundle_dir,
+            _default_license_template(license_template),
+            force,
+        )
+    except FileExistsError:
+        license_path = bundle_dir / "LICENSE"
+        print(
+            f"Refusing to overwrite existing license: {license_path} "
+            "(pass --force to replace)",
+            file=sys.stderr,
+        )
+        return 2
+    print(f"Wrote scaffold to {bundle_dir / 'LICENSE'}")
+    return 0
+
+
+def _scaffold_template(
+    bundle_dir: Path | None,
+    force: bool,
+    license_template: str | None,
+) -> int:
+    """Emit the generic commented template scaffold."""
+    text = _template_text()
+    if bundle_dir is None:
+        if license_template is not None:
+            print("--license-template requires --bundle-dir", file=sys.stderr)
+            return 2
+        print(text, end="")
+        return 0
+    dest = bundle_dir / CAPABILITY_MANIFEST_PATH
+    if dest.exists() and not force:
+        print(
+            f"Refusing to overwrite existing manifest: {dest} "
+            "(pass --force to replace)",
+            file=sys.stderr,
+        )
+        return 2
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    # Write the already-loaded text directly.  ``resources.files()``
+    # returns a Traversable that may not have a stable on-disk path
+    # (e.g. zip-installed wheels), so do not round-trip through
+    # ``Path(str(...))`` just to call shutil.copyfile.
+    dest.write_text(text, encoding="utf-8")
+    print(f"Wrote scaffold to {dest}")
+    return _write_scaffold_license(bundle_dir, license_template, force)
+
+
+def handle_courses_capabilities_scaffold(
+    args: argparse.Namespace,
+) -> int:
+    """Emit the capability manifest scaffold."""
+    bundle_dir: Path | None = getattr(args, "bundle_dir", None)
+    from_skill: Path | None = getattr(args, "from_skill", None)
+    force: bool = getattr(args, "force", False)
+    license_template: str | None = getattr(args, "license_template", None)
+    if from_skill is not None:
+        return _scaffold_from_skill(
+            from_skill,
+            bundle_dir,
+            force,
+            license_template,
+        )
+    return _scaffold_template(bundle_dir, force, license_template)

cli/commands/courses/capability_frontmatter.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+"""Import Logion capability manifests from SKILL.md frontmatter.
+
+``course/capabilities.yaml`` is the single canonical publication contract.
+SKILL.md frontmatter may seed or scaffold that file, but it is not a second
+publication source of truth — the backend never reads SKILL.md as a fallback.
+
+Accepted frontmatter shapes (under ``metadata``):
+
+  metadata:
+    logion:
+      version: 1
+      ...
+
+  metadata:
+    logion:
+      capabilities:
+        version: 1
+        ...
+
+Both ``metadata.logion`` and ``metadata.logion.capabilities`` may carry the
+exact manifest shape, but only one may be present at a time. The extracted
+mapping is passed through ``normalize_capability_manifest()`` so the result
+is identical to loading ``course/capabilities.yaml`` directly.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli._course_capabilities import (
+    CapabilityManifestError,
+    normalize_capability_manifest,
+)
+
+
+def extract_logion_capabilities_from_skill(
+    skill_path: Path,
+) -> dict[str, Any] | None:
+    """Return a normalised capability manifest from SKILL.md frontmatter.
+
+    Returns ``None`` when the file has no ``metadata.logion`` section.
+
+    Raises :class:`CapabilityManifestError` when:
+      - both ``metadata.logion`` and ``metadata.logion.capabilities`` are
+        present (ambiguous — refuse rather than guess);
+      - the extracted value is present but not a YAML mapping;
+      - the mapping fails ``normalize_capability_manifest()``.
+
+    Only the YAML frontmatter block delimited by the first two ``---`` lines
+    at the top of the file is parsed. The Markdown body is ignored.
+    """
+    raw = _read_frontmatter(skill_path)
+    if raw is None:
+        return None
+    manifest = _extract_logion_mapping(raw)
+    if manifest is None:
+        return None
+    if not isinstance(manifest, dict):
+        raise CapabilityManifestError(
+            "metadata.logion capability manifest must be a mapping"
+        )
+    return normalize_capability_manifest(manifest)
+
+
+def _read_frontmatter(skill_path: Path) -> dict[str, Any] | None:
+    """Parse the YAML frontmatter block from *skill_path*.
+
+    Returns ``None`` if the file is missing or has no frontmatter block.
+    """
+    if not skill_path.is_file():
+        return None
+    try:
+        text = skill_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    if not text.startswith("---"):
+        return None
+    # Anchor closing delimiter to end-of-line so "\n---xyz" is not
+    # mistaken for a frontmatter terminator.
+    end = text.find("\n---\n", 3)
+    if end < 0:
+        # Handle frontmatter that is the entire file (no trailing newline).
+        stripped = text.rstrip()
+        if stripped.endswith("---") and text.count("---") >= 2:
+            end = stripped.rfind("---")
+            block = text[3:end].rstrip()
+        else:
+            return None
+    else:
+        block = text[3:end]
+    try:
+        parsed = yaml.safe_load(block)
+    except yaml.YAMLError as exc:
+        raise CapabilityManifestError(
+            "Invalid YAML in SKILL.md frontmatter"
+        ) from exc
+    if not isinstance(parsed, dict):
+        return None
+    return parsed
+
+
+def _extract_logion_mapping(
+    frontmatter: dict[str, Any],
+) -> Any | None:
+    """Pull the Logion capability manifest from parsed frontmatter.
+
+    Accepts ``metadata.logion`` (direct manifest) or
+    ``metadata.logion.capabilities`` (nested). Rejects having both.
+    Returns ``None`` when neither is present.
+    """
+    metadata = frontmatter.get("metadata")
+    if not isinstance(metadata, dict):
+        return None
+    logion = metadata.get("logion")
+    if logion is None:
+        return None
+    if not isinstance(logion, dict):
+        raise CapabilityManifestError(
+            "metadata.logion capability manifest must be a mapping"
+        )
+    direct = logion
+    nested = logion.get("capabilities")
+    has_direct = any(
+        k in logion
+        for k in (
+            "version",
+            "summary",
+            "tools",
+            "network",
+            "filesystem",
+            "secrets",
+            "human_approval",
+            "runtime",
+        )
+    )
+    has_nested = isinstance(nested, dict)
+    if has_direct and has_nested:
+        raise CapabilityManifestError(
+            "SKILL.md has both metadata.logion and "
+            "metadata.logion.capabilities; provide only one."
+        )
+    if has_nested:
+        return nested
+    if has_direct:
+        return direct
+    return None

cli/commands/courses/handlers.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+"""Stable handler exports for courses commands."""
+
+from ._purchase import handle_purchase
+from .capabilities import (
+    handle_courses_capabilities_print,
+    handle_courses_capabilities_validate,
+)
+from .mutations import (
+    handle_create,
+    handle_get,
+    handle_update,
+)
+from .publication import (
+    handle_publication_latest,
+    handle_publication_request,
+)
+from .report_usage import handle_report_usage
+from .reviews import (
+    handle_feedback,
+    handle_reviews_list,
+    handle_reviews_mine,
+    handle_reviews_summary,
+    handle_reviews_upsert,
+)
+from .uploads import (
+    handle_uploads_complete,
+    handle_uploads_create,
+)
+from .versions import handle_versions_get
+
+__all__ = [
+    "handle_courses_capabilities_print",
+    "handle_courses_capabilities_validate",
+    "handle_create",
+    "handle_feedback",
+    "handle_get",
+    "handle_publication_latest",
+    "handle_publication_request",
+    "handle_purchase",
+    "handle_report_usage",
+    "handle_reviews_list",
+    "handle_reviews_mine",
+    "handle_reviews_summary",
+    "handle_reviews_upsert",
+    "handle_update",
+    "handle_uploads_complete",
+    "handle_uploads_create",
+    "handle_versions_get",
+]

cli/commands/courses/mutations.py

@@ -0,0 +1,217 @@
+# SPDX-License-Identifier: MIT
+"""Mutation handlers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error, print_err, validate_uuid_id
+from cli._output import emit, emit_json, to_data
+from cli._utils import only_not_none
+from cli.commands.courses._capability_render import (
+    _append_summary_fields,
+    append_approved_capability_summary_lines,
+)
+
+MUTABLE_UPDATE_FIELDS = [
+    "title",
+    "description",
+    "price_cents",
+    "currency",
+    "language",
+    "short_summary",
+    "visibility",
+    "category",
+]
+
+
+def _append_course_capability_lines(
+    lines: list[str],
+    data: dict[str, object],
+) -> None:
+    """Append latest-version capability summary lines for course detail."""
+    status = data.get("latest_version_capabilities_status")
+    if status:
+        lines.append(f"latest_version_capabilities_status: {status}")
+    schema_version = data.get("latest_version_capabilities_schema_version")
+    if schema_version is not None:
+        lines.append(
+            f"latest_version_capabilities_schema_version: {schema_version}"
+        )
+    summary = data.get("latest_version_capabilities_summary")
+    if summary and isinstance(summary, dict):
+        _append_summary_fields(lines, summary)
+
+
+def _check_clear_price_conflict(args: argparse.Namespace) -> int | None:
+    if args.clear_price and (args.currency or args.clear_currency):
+        print_err(
+            "Error: --clear-price cannot be used with "
+            "--currency or --clear-currency."
+        )
+        return 2
+    return None
+
+
+def _apply_update_overrides(
+    args: argparse.Namespace,
+    kwargs: dict[str, object],
+) -> None:
+    if args.clear_tags:
+        kwargs["tags"] = []
+    elif args.tags:
+        kwargs["tags"] = args.tags
+    if args.clear_description:
+        kwargs["description"] = None
+    if args.clear_short_summary:
+        kwargs["short_summary"] = None
+    if args.clear_language:
+        kwargs["language"] = None
+    if args.clear_currency:
+        kwargs["currency"] = None
+    if args.clear_price:
+        kwargs["price_cents"] = None
+        kwargs["currency"] = None
+
+
+def _has_mutable_field(args: argparse.Namespace) -> bool:
+    if any(
+        getattr(args, field, None) is not None
+        for field in MUTABLE_UPDATE_FIELDS
+    ):
+        return True
+    if args.tags:
+        return True
+    return bool(
+        args.clear_tags
+        or args.clear_description
+        or args.clear_short_summary
+        or args.clear_language
+        or args.clear_currency
+        or args.clear_price
+    )
+
+
+def handle_create(args: argparse.Namespace) -> int:
+    """Execute the courses create command."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {"title": args.title, "slug": args.slug},
+            description=args.description,
+            price_cents=args.price_cents,
+            currency=args.currency,
+            language=args.language,
+            short_summary=args.short_summary,
+            visibility=args.visibility,
+            category=getattr(args, "category", None),
+        )
+        if args.tags:
+            kwargs["tags"] = args.tags
+        result = client.v1.courses.create(**kwargs)
+        if config.json_output:
+            emit_json("logion.courses.create", to_data(result))
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_get(args: argparse.Namespace) -> int:
+    """Execute the courses get command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.courses.get(course_id=args.course_id)
+        if config.json_output:
+            emit(result, json_output=True)
+        else:
+            data = to_data(result)
+            lines: list[str] = [
+                f"id: {data['id']}",
+                f"owner_agent_id: {data['owner_agent_id']}",
+                f"title: {data['title']}",
+                f"slug: {data['slug']}",
+                f"status: {data['status']}",
+                f"visibility: {data['visibility']}",
+            ]
+            if data.get("description"):
+                lines.append(f"description: {data['description']}")
+            if data.get("short_summary"):
+                lines.append(f"short_summary: {data['short_summary']}")
+            lines.append(f"price_cents: {data['price_cents']}")
+            lines.append(f"currency: {data['currency']}")
+            if data.get("language"):
+                lines.append(f"language: {data['language']}")
+            if data.get("tags"):
+                lines.append(f"tags: {', '.join(data['tags'])}")
+            lines.append(f"current_version: {data.get('current_version')}")
+            latest_version_id = data.get("latest_version_id")
+            if latest_version_id:
+                lines.append(f"latest_version_id: {latest_version_id}")
+            _append_course_capability_lines(lines, data)
+            append_approved_capability_summary_lines(lines, data)
+            if data.get("published_at"):
+                lines.append(f"published_at: {data['published_at']}")
+            lines.append(f"created_at: {data['created_at']}")
+            lines.append(f"updated_at: {data['updated_at']}")
+            sys.stdout.write("\n".join(lines))
+            sys.stdout.write("\n")
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_update(args: argparse.Namespace) -> int:
+    """Execute the courses update command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    price_conflict = _check_clear_price_conflict(args)
+    if price_conflict is not None:
+        return price_conflict
+    if not _has_mutable_field(args):
+        print_err(
+            "Error: courses update requires at least one field to change."
+        )
+        return 2
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {"course_id": args.course_id},
+            title=args.title,
+            description=args.description,
+            price_cents=args.price_cents,
+            currency=args.currency,
+            language=args.language,
+            short_summary=args.short_summary,
+            visibility=args.visibility,
+            category=getattr(args, "category", None),
+        )
+        _apply_update_overrides(args, kwargs)
+        result = client.v1.courses.update(**kwargs)
+        if config.json_output:
+            emit_json("logion.courses.update", to_data(result))
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()