logion-cli 0.1.0__py3-none-any.whl

cli/commands/courses/parser.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import handle_feedback, handle_versions_get
+from .parser_capabilities import register_capabilities
+from .parser_sections import (
+    CMD_HELP,
+    register_create,
+    register_get,
+    register_publication,
+    register_purchase,
+    register_reviews,
+    register_update,
+    register_uploads,
+)
+from .report_usage import (
+    register_report_usage,
+)
+from .taxonomy_handler import register_taxonomy
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``courses`` subcommand group."""
+    parser = subparsers.add_parser("courses", help="Manage courses")
+    sub = parser.add_subparsers(
+        dest="courses_command",
+        required=True,
+    )
+
+    register_create(sub)
+    register_get(sub)
+    register_update(sub)
+    register_uploads(sub)
+    register_publication(sub)
+    register_purchase(sub)
+    register_reviews(sub)
+    register_report_usage(sub)
+    register_capabilities(sub)
+    register_taxonomy(sub)
+    feedback = sub.add_parser(
+        "feedback",
+        help=CMD_HELP["feedback"],
+        parents=[COMMON_PARSER],
+    )
+    feedback.add_argument("course_id", metavar="COURSE_ID")
+    feedback.set_defaults(handler=handle_feedback)
+
+    versions = sub.add_parser("versions", help=CMD_HELP["versions"])
+    versions_sub = versions.add_subparsers(
+        dest="courses_versions_command",
+        required=True,
+    )
+    get = versions_sub.add_parser(
+        "get",
+        help="Get a course version",
+        parents=[COMMON_PARSER],
+    )
+    get.add_argument("course_id", metavar="COURSE_ID")
+    get.add_argument("version_id", metavar="VERSION_ID")
+    get.set_defaults(handler=handle_versions_get)

cli/commands/courses/parser_capabilities.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for course capability commands."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from cli._options import COMMON_PARSER
+
+from .capabilities import (
+    handle_courses_capabilities_print,
+    handle_courses_capabilities_scaffold,
+    handle_courses_capabilities_validate,
+)
+from .parser_sections import CMD_HELP
+
+
+def register_capabilities(subparsers: argparse._SubParsersAction) -> None:
+    """Register course capability manifest subcommands."""
+    capabilities = subparsers.add_parser(
+        "capabilities",
+        help=CMD_HELP["capabilities"],
+    )
+    capabilities_sub = capabilities.add_subparsers(
+        dest="courses_capabilities_command",
+        required=True,
+    )
+
+    validate = capabilities_sub.add_parser(
+        "validate",
+        help="Validate a local capability manifest",
+        parents=[COMMON_PARSER],
+    )
+    validate.add_argument(
+        "--bundle-dir",
+        type=Path,
+        required=True,
+        help="Path to the course bundle directory",
+    )
+    validate.set_defaults(handler=handle_courses_capabilities_validate)
+
+    print_cmd = capabilities_sub.add_parser(
+        "print",
+        help="Print the normalised capability manifest as JSON",
+        parents=[COMMON_PARSER],
+    )
+    print_cmd.add_argument(
+        "--bundle-dir",
+        type=Path,
+        required=True,
+        help="Path to the course bundle directory",
+    )
+    print_cmd.set_defaults(handler=handle_courses_capabilities_print)
+
+    scaffold = capabilities_sub.add_parser(
+        "scaffold",
+        help="Write a commented course/capabilities.yaml scaffold",
+        parents=[COMMON_PARSER],
+    )
+    scaffold.add_argument(
+        "--bundle-dir",
+        type=Path,
+        default=None,
+        help=(
+            "Course bundle directory.  If omitted the scaffold is "
+            "printed to stdout."
+        ),
+    )
+    scaffold.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing course/capabilities.yaml",
+    )
+    scaffold.add_argument(
+        "--license-template",
+        choices=["mit", "apache-2.0", "logion-standard-course-v1"],
+        default=None,
+        help=(
+            "Write bundle-dir/LICENSE from the selected template. "
+            "When omitted, scaffold writes MIT by default."
+        ),
+    )
+    scaffold.add_argument(
+        "--from-skill",
+        type=Path,
+        default=None,
+        metavar="SKILL_MD_PATH",
+        help=(
+            "Seed the scaffold from the metadata.logion capability "
+            "manifest in the given SKILL.md instead of emitting the "
+            "generic template."
+        ),
+    )
+    scaffold.set_defaults(handler=handle_courses_capabilities_scaffold)

cli/commands/courses/parser_sections.py

@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: MIT
+"""Subparser builders for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from ._cmd_help import CMD_HELP
+from .handlers import (
+    handle_create,
+    handle_get,
+    handle_publication_latest,
+    handle_publication_request,
+    handle_purchase,
+    handle_reviews_list,
+    handle_reviews_mine,
+    handle_reviews_summary,
+    handle_reviews_upsert,
+    handle_update,
+)
+from .parser_uploads import register_uploads as _register_uploads
+from .parser_utils import (
+    add_category_argument,
+    add_tag_arguments,
+    add_tristate_flag,
+)
+
+# Re-export for existing imports.
+register_uploads = _register_uploads
+
+
+def register_create(subparsers: argparse._SubParsersAction) -> None:
+    create = subparsers.add_parser(
+        "create",
+        help=CMD_HELP["create"],
+        parents=[COMMON_PARSER],
+    )
+    create.add_argument("--title", required=True)
+    create.add_argument("--slug", required=True)
+    create.add_argument("--description")
+    create.add_argument("--price-cents", type=int)
+    create.add_argument("--currency")
+    add_tag_arguments(create, default=[])
+    add_category_argument(create)
+    create.add_argument("--language")
+    create.add_argument("--short-summary")
+    create.add_argument(
+        "--visibility", choices=["public", "unlisted", "private"]
+    )
+    create.set_defaults(handler=handle_create)
+
+
+def register_get(subparsers: argparse._SubParsersAction) -> None:
+    get = subparsers.add_parser(
+        "get",
+        help=CMD_HELP["get"],
+        parents=[COMMON_PARSER],
+    )
+    get.add_argument("course_id", metavar="COURSE_ID")
+    get.set_defaults(handler=handle_get)
+
+
+def register_update(subparsers: argparse._SubParsersAction) -> None:
+    update = subparsers.add_parser(
+        "update",
+        help=CMD_HELP["update"],
+        parents=[COMMON_PARSER],
+    )
+    update.add_argument("course_id", metavar="COURSE_ID")
+    update.add_argument("--title")
+
+    description = update.add_mutually_exclusive_group()
+    description.add_argument("--description")
+    description.add_argument(
+        "--clear-description",
+        action="store_true",
+        help="Clear the course description",
+    )
+
+    price = update.add_mutually_exclusive_group()
+    price.add_argument("--price-cents", type=int)
+    price.add_argument(
+        "--clear-price",
+        action="store_true",
+        help=(
+            "Clear the course price (price_cents and currency). "
+            "Note: this also clears the currency."
+        ),
+    )
+
+    currency = update.add_mutually_exclusive_group()
+    currency.add_argument("--currency")
+    currency.add_argument(
+        "--clear-currency",
+        action="store_true",
+        help="Clear the course currency",
+    )
+
+    language = update.add_mutually_exclusive_group()
+    language.add_argument("--language")
+    language.add_argument(
+        "--clear-language",
+        action="store_true",
+        help="Clear the course language",
+    )
+
+    short_summary = update.add_mutually_exclusive_group()
+    short_summary.add_argument("--short-summary")
+    short_summary.add_argument(
+        "--clear-short-summary",
+        action="store_true",
+        help="Clear the short summary",
+    )
+
+    add_tag_arguments(update, default=None)
+    add_category_argument(update)
+    update.add_argument(
+        "--visibility", choices=["public", "unlisted", "private"]
+    )
+    update.set_defaults(handler=handle_update)
+
+
+def register_publication(subparsers: argparse._SubParsersAction) -> None:
+    publication = subparsers.add_parser(
+        "publication",
+        help=CMD_HELP["publication"],
+    )
+    pub_sub = publication.add_subparsers(
+        dest="courses_publication_command",
+        required=True,
+    )
+
+    request = pub_sub.add_parser(
+        "request",
+        help="Request publication review",
+        parents=[COMMON_PARSER],
+    )
+    request.add_argument("course_id", metavar="COURSE_ID")
+    request.set_defaults(handler=handle_publication_request)
+
+    latest = pub_sub.add_parser(
+        "latest",
+        help="Get latest publication review status",
+        parents=[COMMON_PARSER],
+    )
+    latest.add_argument("course_id", metavar="COURSE_ID")
+    add_tristate_flag(latest, "--include-pass", dest="include_pass")
+    latest.set_defaults(handler=handle_publication_latest)
+
+
+def register_reviews(subparsers: argparse._SubParsersAction) -> None:
+    reviews = subparsers.add_parser("reviews", help=CMD_HELP["reviews"])
+    reviews_sub = reviews.add_subparsers(
+        dest="courses_reviews_command",
+        required=True,
+    )
+
+    list_parser = reviews_sub.add_parser(
+        "list",
+        help="List reviews for a course",
+        parents=[COMMON_PARSER],
+    )
+    list_parser.add_argument("course_id", metavar="COURSE_ID")
+    list_parser.add_argument("--version")
+    list_parser.add_argument("--limit", type=int, default=5)
+    list_parser.add_argument("--cursor")
+    list_parser.set_defaults(handler=handle_reviews_list)
+
+    mine = reviews_sub.add_parser(
+        "mine",
+        help="Get your review for a course version",
+        parents=[COMMON_PARSER],
+    )
+    mine.add_argument("course_id", metavar="COURSE_ID")
+    mine.add_argument("--version-id")
+    mine.set_defaults(handler=handle_reviews_mine)
+
+    upsert = reviews_sub.add_parser(
+        "upsert",
+        help="Create or update a review for a course version",
+        parents=[COMMON_PARSER],
+    )
+    upsert.add_argument("course_id", metavar="COURSE_ID")
+    upsert.add_argument("version_id", metavar="VERSION_ID")
+    upsert.add_argument("--rating", type=int, required=True)
+    upsert.add_argument("--body")
+    add_tristate_flag(upsert, "--completed-task", dest="completed_task")
+    upsert.add_argument("--reliability", type=float)
+    upsert.add_argument("--usefulness", type=float)
+    upsert.add_argument("--tool-safety", type=float)
+    upsert.add_argument("--token-efficiency", type=float)
+    upsert.set_defaults(handler=handle_reviews_upsert)
+
+    summary = reviews_sub.add_parser(
+        "summary",
+        help="Show aggregate review statistics for a course",
+        parents=[COMMON_PARSER],
+    )
+    summary.add_argument("course_id", metavar="COURSE_ID")
+    summary.add_argument("--version")
+    summary.add_argument("--limit", type=int, default=5)
+    summary.set_defaults(handler=handle_reviews_summary)
+
+
+def register_purchase(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``courses purchase`` subcommand."""
+    purchase = subparsers.add_parser(
+        "purchase",
+        help=CMD_HELP["purchase"],
+        parents=[COMMON_PARSER],
+    )
+    purchase.add_argument("course_id", metavar="COURSE_ID")
+    purchase.add_argument(
+        "--expected-price-cents",
+        dest="expected_price_cents",
+        type=int,
+        default=None,
+        help=(
+            "Price guard: fail if the course price has"
+            " changed. Omit to skip the guard (the --yes"
+            " confirmation still protects against"
+            " accidental purchases)."
+        ),
+    )
+    purchase.add_argument(
+        "--idempotency-key",
+        dest="idempotency_key",
+        default=None,
+        help="Optional idempotency key to safely retry a purchase.",
+    )
+    purchase.add_argument(
+        "--yes",
+        action="store_true",
+        default=False,
+        help="Confirm the purchase without prompting.",
+    )
+    purchase.set_defaults(handler=handle_purchase)

cli/commands/courses/parser_uploads.py

@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for ``courses uploads`` subcommands.
+
+Lives in its own module so :mod:`parser_sections` stays under the
+per-file line budget.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from ._uploads_push import handle_uploads_push
+from .handlers import handle_uploads_complete, handle_uploads_create
+
+
+def register_uploads(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``uploads`` subcommand group."""
+    uploads = subparsers.add_parser("uploads", help="Manage course uploads")
+    uploads_sub = uploads.add_subparsers(
+        dest="courses_uploads_command",
+        required=True,
+    )
+
+    create = uploads_sub.add_parser(
+        "create",
+        help="Create an upload session for a course version",
+        parents=[COMMON_PARSER],
+    )
+    create.add_argument("course_id", metavar="COURSE_ID")
+    create.add_argument(
+        "--file",
+        action="append",
+        dest="files",
+        default=[],
+        help=(
+            "File path to include in the upload session. "
+            "Use FILE_PATH or UPLOAD_PATH=FILE_PATH to override the upload "
+            "path. When omitted, only the basename is used and directory "
+            "structure is flattened."
+        ),
+    )
+    create.set_defaults(handler=handle_uploads_create)
+
+    complete = uploads_sub.add_parser(
+        "complete",
+        help="Complete an upload session",
+        parents=[COMMON_PARSER],
+    )
+    complete.add_argument("course_id", metavar="COURSE_ID")
+    complete.add_argument("version_id", metavar="VERSION_ID")
+    complete.set_defaults(handler=handle_uploads_complete)
+
+    push = uploads_sub.add_parser(
+        "push",
+        help="PUT each file in an upload session to its presigned URL",
+        parents=[COMMON_PARSER],
+    )
+    push.add_argument("course_id", metavar="COURSE_ID")
+    push.add_argument("version_id", metavar="VERSION_ID")
+    push.add_argument(
+        "--session-file",
+        required=True,
+        help=(
+            "Path to the JSON returned by `uploads create`; use '-' to read "
+            "from stdin."
+        ),
+    )
+    push.add_argument(
+        "--file",
+        action="append",
+        dest="files",
+        default=[],
+        help=(
+            "Local file to push. Use UPLOAD_PATH=LOCAL_PATH (matched against "
+            "the session's `filename`) or LOCAL_PATH for basename matching. "
+            "Repeatable."
+        ),
+    )
+    # --max-retries and --timeout come from COMMON_PARSER; defaults are
+    # applied in the handler so push has sensible behaviour even when
+    # the caller omits them.
+    push.set_defaults(handler=handle_uploads_push)

cli/commands/courses/parser_utils.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+"""Shared parser helpers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def add_tag_arguments(
+    parser: argparse.ArgumentParser,
+    *,
+    default: list[str] | None,
+) -> None:
+    """Add ``--tag`` and ``--clear-tags`` arguments."""
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        "--tag",
+        action="append",
+        dest="tags",
+        default=default,
+        help="Tag to add (can be specified multiple times)",
+    )
+    if default is None:
+        group.add_argument(
+            "--clear-tags",
+            action="store_true",
+            help="Remove all tags from the course",
+        )
+
+
+def add_category_argument(
+    parser: argparse.ArgumentParser,
+) -> None:
+    """Add ``--category`` argument to a create or update parser."""
+    parser.add_argument(
+        "--category",
+        default=None,
+        help=(
+            "Course category slug (e.g. devops, security, writing). "
+            "Unknown slugs are rejected by the API."
+        ),
+    )
+
+
+def add_tristate_flag(
+    parser: argparse.ArgumentParser,
+    flag: str,
+    *,
+    dest: str,
+) -> None:
+    """Add a three-state boolean flag."""
+    base = flag.removeprefix("--")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument(
+        flag,
+        dest=dest,
+        action="store_true",
+        default=None,
+    )
+    group.add_argument(
+        f"--no-{base}",
+        dest=dest,
+        action="store_false",
+        default=None,
+    )

cli/commands/courses/publication.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+"""Publication handlers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error, validate_uuid_id
+from cli._output import emit, emit_json, to_data
+from cli._utils import only_not_none
+
+
+def handle_publication_request(args: argparse.Namespace) -> int:
+    """Execute publication request."""
+    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.request_publication_review(
+            course_id=args.course_id,
+        )
+        if config.json_output:
+            emit_json("logion.courses.publication.request", 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_publication_latest(args: argparse.Namespace) -> int:
+    """Execute publication latest."""
+    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:
+        kwargs = only_not_none(
+            {"course_id": args.course_id},
+            include_pass=args.include_pass,
+        )
+        result = client.v1.courses.get_latest_publication_review(**kwargs)
+        if config.json_output:
+            emit_json("logion.courses.publication.latest", to_data(result))
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()