logion-cli 0.1.0__py3-none-any.whl

cli/_options.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+"""Shared CLI option definitions."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def build_common_parser() -> argparse.ArgumentParser:
+    """Build a parent parser with shared CLI options.
+
+    Use this via ``parents=[build_common_parser()]`` on leaf subcommands
+    so that argparse merges common options correctly without overwriting
+    user-supplied values.
+    """
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument("--api-key")
+    parent.add_argument("--base-url")
+    parent.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+    )
+    parent.add_argument("--timeout", type=float)
+    parent.add_argument("--max-retries", type=int)
+    parent.add_argument(
+        "--no-onboarding",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="Never run first-run onboarding for this invocation.",
+    )
+    return parent
+
+
+# Module-level singleton so the parent parser is built once.
+COMMON_PARSER = build_common_parser()

cli/_output.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+"""Output helpers — JSON and human-readable formatting."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def to_data(value: Any) -> Any:
+    """Recursively convert Pydantic models to plain JSON-safe data."""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, list):
+        return [to_data(item) for item in value]
+    if isinstance(value, dict):
+        return {key: to_data(item) for key, item in value.items()}
+    return value
+
+
+def emit_json(kind: str, data: Any) -> None:
+    """Print a v1 JSON envelope with version, kind, and data."""
+    payload = {"version": "v1", "kind": kind, "data": to_data(data)}
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+def truncate_summary(text: str | None, max_len: int = 120) -> str:
+    """Truncate *text* to *max_len* chars, appending ``…`` if truncated."""
+    if not text:
+        return ""
+    return text if len(text) <= max_len else text[: max_len - 1] + "…"
+
+
+def emit(value: Any, *, json_output: bool) -> None:
+    """Print *value* as JSON.
+
+    In JSON mode the output is sorted and indented for scripts.
+    In human mode the output is indented but preserves natural key order
+    for readability.
+    """
+    data = to_data(value)
+    if json_output:
+        print(json.dumps(data, indent=2, sort_keys=True))
+    else:
+        print(json.dumps(data, indent=2))

cli/_parser.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+"""Argparse parser factory for the Logion CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._version import __version__
+from cli.commands import (
+    admin,
+    bounties,
+    course_reviews,
+    courses,
+    docs,
+    health,
+    identity,
+    listings,
+    notifications,
+    payments,
+    recall,
+    reports,
+    skills,
+)
+from cli.commands import (
+    credits as credits_mod,
+)
+from cli.commands import (
+    referrals as referrals_mod,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="logion",
+        description="Logion CLI for AI agents and marketplace operators.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "--no-onboarding",
+        action="store_true",
+        default=argparse.SUPPRESS,
+        help="Never run first-run onboarding for this invocation.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    health.register(subparsers)
+    identity.register(subparsers)
+    listings.register(subparsers)
+    notifications.register(subparsers)
+    courses.register(subparsers)
+    docs.register(subparsers)
+    payments.register(subparsers)
+    credits_mod.register(subparsers)
+    referrals_mod.register(subparsers)
+    reports.register(subparsers)
+    course_reviews.register(subparsers)
+    admin.register(subparsers)
+    bounties.register(subparsers)
+    skills.register(subparsers)
+    recall.register(subparsers)
+
+    # Top-level `logion onboarding` alias — same handler as
+    # `logion identity onboarding`.
+    from cli.commands.identity.onboarding import register_onboarding
+
+    register_onboarding(subparsers)
+
+    return parser

cli/_recall_calibration.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+"""Confidence calibration helpers for local recall.
+
+Maps raw similarity scores to calibrated confidence values and
+categorical bands used by the companion's decision policy.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+
+
+def _parse_last_success_at(value: str | None) -> _dt.datetime | None:
+    if not value:
+        return None
+
+    normalized = value.strip()
+    if not normalized:
+        return None
+    if normalized.endswith("Z"):
+        normalized = f"{normalized[:-1]}+00:00"
+
+    try:
+        parsed = _dt.datetime.fromisoformat(normalized)
+    except (ValueError, TypeError):
+        return None
+
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=_dt.UTC)
+    return parsed
+
+
+def calibrate_installed_confidence(query_similarity: float) -> float:
+    """Installed capabilities have no prior beyond presence.
+
+    The query similarity is the entire signal.
+    """
+    return query_similarity
+
+
+def calibrate_workflow_confidence(
+    query_similarity: float,
+    success_count: int = 0,
+    last_success_at: str | None = None,
+) -> float:
+    """Combine query similarity with persisted workflow prior and recency.
+
+    ``final = clamp(
+        0, 1,
+        0.6 * query_similarity
+        + 0.3 * persisted_prior
+        + 0.1 * recency_boost,
+    )``
+    """
+    persisted_prior = min(success_count / 10, 1.0)
+
+    recency_boost = 0.0
+    last = _parse_last_success_at(last_success_at)
+    if last is not None:
+        now = _dt.datetime.now(_dt.UTC)
+        if last > now:
+            last = now
+        days_ago = (now - last).days
+        if days_ago <= 30:
+            recency_boost = 1.0
+        elif days_ago <= 365:
+            recency_boost = 1.0 - (days_ago - 30) / (365 - 30)
+        # beyond 365 days → 0.0
+
+    final = (
+        0.6 * query_similarity + 0.3 * persisted_prior + 0.1 * recency_boost
+    )
+    return max(0.0, min(1.0, final))
+
+
+def band_for(confidence: float) -> str:
+    """Return the categorical band for a confidence value.
+
+    - HIGH   : confidence >= 0.80
+    - MEDIUM : 0.50 <= confidence < 0.80
+    - LOW    : 0.20 <= confidence < 0.50
+    - NONE   : confidence < 0.20
+    """
+    if confidence >= 0.80:
+        return "HIGH"
+    if confidence >= 0.50:
+        return "MEDIUM"
+    if confidence >= 0.20:
+        return "LOW"
+    return "NONE"

cli/_recall_ranker.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+"""Deterministic ranker for the local recall index.
+
+Pure function: given a query and a list of compact recall entries,
+returns a sorted, top-k list with per-entry similarity in [0, 1].
+
+Uses ``rapidfuzz.fuzz.partial_token_set_ratio`` when available, falls
+back to ``difflib.SequenceMatcher.ratio()`` otherwise. The fallback
+must produce stable (but possibly lower-quality) rankings.
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+try:
+    from rapidfuzz import fuzz as _rapidfuzz_fuzz
+
+    _rf_fuzz: Any | None = _rapidfuzz_fuzz
+    _HAS_RAPIDFUZZ = True
+except ImportError:  # pragma: no cover
+    _rf_fuzz = None
+    _HAS_RAPIDFUZZ = False
+
+
+_MINIMUM_SIMILARITY = 0.10
+
+
+def _compute_similarity(query: str, composed: str) -> float:
+    """Return similarity in [0, 1] between *query* and *composed* string."""
+    if _HAS_RAPIDFUZZ and _rf_fuzz is not None:
+        return _rf_fuzz.partial_token_set_ratio(query, composed) / 100.0
+    return difflib.SequenceMatcher(None, query, composed).ratio()
+
+
+def _compose_entry_text(entry: dict[str, Any]) -> str:
+    """Build a single lowercase string from entry fields for matching."""
+    title = entry.get("title", "")
+    summary = entry.get("summary", "")
+    tokens = entry.get("tokens") or []
+    return f"{title} {summary} {' '.join(tokens)}".lower()
+
+
+def rank(
+    query: str,
+    entries: list[dict[str, Any]],
+    limit: int = 5,
+) -> list[tuple[float, dict[str, Any]]]:
+    """Return up to *limit* ``(similarity, entry)`` tuples, sorted desc.
+
+    Ranking is deterministic: entries with equal similarity are ordered
+    by ``id`` ascending for stability.
+    """
+    if not entries or not query:
+        return []
+
+    q = query.strip().lower()
+    if not q:
+        return []
+
+    scored: list[tuple[float, str, dict[str, Any]]] = []
+    for entry in entries:
+        composed = _compose_entry_text(entry)
+        similarity = _compute_similarity(q, composed)
+        if similarity < _MINIMUM_SIMILARITY:
+            continue
+        entry_id = entry.get("id", "")
+        scored.append((similarity, entry_id, entry))
+
+    # Sort by similarity desc, then id asc for tie-breaking stability
+    scored.sort(key=lambda t: (-t[0], t[1]))
+
+    return [(s, e) for s, _eid, e in scored[:limit]]

cli/_taxonomy.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+"""CLI-side taxonomy helpers mirroring the backend normalization rules.
+
+These are duplicated rather than imported from the backend so the CLI
+can validate locally without a network round-trip. The rules must stay
+in sync with the backend taxonomy module.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+CATEGORY_SLUGS: frozenset[str] = frozenset({
+    "automation",
+    "code-review",
+    "data",
+    "devops",
+    "documentation",
+    "finance",
+    "marketing",
+    "media",
+    "productivity",
+    "research",
+    "security",
+    "testing",
+    "writing",
+    "other",
+})
+DEFAULT_CATEGORY = "other"
+
+RESERVED_TAG_SLUGS: frozenset[str] = frozenset({
+    "official",
+    "verified",
+    "trusted",
+    "featured",
+    "logion",
+    "admin",
+    "staff",
+    "platform",
+    "security-audited",
+})
+
+TAG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+
+
+class TaxonomyValidationError(ValueError):
+    """Raised when a category or tag fails normalization."""
+
+
+def normalize_category(value: str | None) -> str:
+    """Return a validated category slug, defaulting to ``other``."""
+    if value is None:
+        return DEFAULT_CATEGORY
+    slug = value.strip().lower()
+    if not slug:
+        return DEFAULT_CATEGORY
+    if slug not in CATEGORY_SLUGS:
+        raise TaxonomyValidationError(f"Unknown category: {value}")
+    return slug
+
+
+def normalize_tag(value: str) -> str:
+    """Normalize a single tag slug and reject reserved/invalid labels."""
+    if value is None:
+        raise TaxonomyValidationError("Invalid tag after normalization: None")
+    tag = value.strip().lower()
+    tag = tag.replace(" ", "-").replace("_", "-")
+    # Collapse repeated hyphens that the above may have introduced.
+    tag = re.sub(r"-+", "-", tag)
+    tag = tag.strip("-")
+    if not tag:
+        raise TaxonomyValidationError("Invalid tag after normalization: empty")
+    if tag in RESERVED_TAG_SLUGS:
+        raise TaxonomyValidationError(f"Reserved tag is not allowed: {tag}")
+    if not TAG_RE.match(tag):
+        raise TaxonomyValidationError(
+            f"Invalid tag after normalization: {tag}"
+        )
+    return tag
+
+
+def normalize_tags(
+    values: Sequence[str],
+    *,
+    max_count: int = 20,
+) -> list[str]:
+    """Normalize a sequence of tags, preserving first-seen order.
+
+    Duplicates (after normalization) collapse. Raises if the normalized
+    set exceeds *max_count* or if any tag is reserved/invalid.
+    """
+    seen: set[str] = set()
+    result: list[str] = []
+    for raw in values:
+        tag = normalize_tag(raw)
+        if tag in seen:
+            continue
+        seen.add(tag)
+        result.append(tag)
+    if len(result) > max_count:
+        raise TaxonomyValidationError(
+            f"Too many tags: {len(result)} (max {max_count})"
+        )
+    return result
+
+
+def tag_search_tokens(tag: str) -> set[str]:
+    """Return the full normalized tag plus each hyphen segment.
+
+    ``pr-review`` yields ``{"pr-review", "pr", "review"}``. The backend
+    uses these segments for relevance-search eligibility (not for tag
+    filters, which are prefix-only); the CLI mirrors it for local
+    suggestion expansion.
+    """
+    normalized = normalize_tag(tag)
+    segments = normalized.split("-")
+    tokens: set[str] = {normalized}
+    tokens.update(seg for seg in segments if seg)
+    return tokens

cli/_update_policy.py

@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: MIT
+"""Update policy gates for ``logion skills update``.
+
+Compares the locally installed manifest against a candidate remote
+manifest and decides whether the upgrade can be applied silently or
+must require explicit user approval.
+
+The plan calls out a closed set of manifest fields that, if they
+change between local and remote, require approval:
+
+- ``required_tools`` — the skill claims a new tool capability
+- ``permissions`` — declared OS / network / credential scopes
+- ``env_vars`` — environment variables the skill reads
+- ``execution_policy`` — auto-run vs. approval-required, danger flags
+
+Pricing is *not* gated here: the entitlement model grants the buyer
+ongoing access to the course (all versions) once purchased, so a
+seller raising the list price does not re-bill an existing user.  We
+surface a price change as an informational notice (``reasons``) but
+do not force approval on its account.
+
+``evaluate_update`` layers ``verify_installed_content`` on top of the
+base policy: a locally modified install always blocks silent
+overwrite, even when the manifest diff alone would have been safe.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cli._local_state import verify_installed_content
+
+# Fields that force ``requires_approval`` when local ≠ remote.
+GATED_FIELDS: tuple[str, ...] = (
+    "required_tools",
+    "permissions",
+    "env_vars",
+    "execution_policy",
+)
+
+# Fields surfaced as notices but that do NOT force approval.
+NOTICE_FIELDS: tuple[str, ...] = (
+    "price_cents_at_install",
+    "currency",
+)
+
+
+@dataclass
+class UpdatePolicyResult:
+    """Outcome of comparing a local manifest to a remote manifest."""
+
+    applicable: bool = False
+    requires_approval: bool = False
+    blocks_silent_overwrite: bool = False
+    reasons: list[str] = field(default_factory=list)
+    notices: list[str] = field(default_factory=list)
+    changed_fields: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "applicable": self.applicable,
+            "requires_approval": self.requires_approval,
+            "blocks_silent_overwrite": self.blocks_silent_overwrite,
+            "reasons": list(self.reasons),
+            "notices": list(self.notices),
+            "changed_fields": list(self.changed_fields),
+        }
+
+
+def _normalize(value: Any) -> Any:
+    """Make values comparable: lists become sorted tuples; dicts sort keys."""
+    if isinstance(value, list):
+        return tuple(sorted((_normalize(v) for v in value), key=repr))
+    if isinstance(value, dict):
+        return tuple(sorted((k, _normalize(v)) for k, v in value.items()))
+    return value
+
+
+def check_update_policy(
+    local_manifest: dict[str, Any],
+    remote_manifest: dict[str, Any],
+) -> UpdatePolicyResult:
+    """Diff gated manifest fields and return an :class:`UpdatePolicyResult`.
+
+    The result is *only* about the manifest diff; it does not look at
+    on-disk content.  Use :func:`evaluate_update` to add the
+    user-modification check.
+    """
+    result = UpdatePolicyResult()
+
+    local_version = local_manifest.get("version_id")
+    remote_version = remote_manifest.get("version_id")
+    if remote_version and remote_version != local_version:
+        result.applicable = True
+
+    content_changed = local_manifest.get(
+        "content_sha256"
+    ) != remote_manifest.get("content_sha256")
+    if content_changed:
+        result.applicable = True
+
+    for field_name in GATED_FIELDS:
+        if _normalize(local_manifest.get(field_name)) != _normalize(
+            remote_manifest.get(field_name)
+        ):
+            result.changed_fields.append(field_name)
+            result.requires_approval = True
+            result.reasons.append(
+                f"{field_name} changed between installed and remote manifest"
+            )
+
+    for field_name in NOTICE_FIELDS:
+        if _normalize(local_manifest.get(field_name)) != _normalize(
+            remote_manifest.get(field_name)
+        ):
+            result.notices.append(
+                f"{field_name} changed (informational; existing entitlement "
+                "is not re-billed)"
+            )
+
+    return result
+
+
+def evaluate_update(
+    course_id: str,
+    version_id: str,
+    remote_manifest: dict[str, Any],
+    local_manifest: dict[str, Any],
+    home: Path | None = None,
+) -> UpdatePolicyResult:
+    """Combine :func:`check_update_policy` with content verification.
+
+    If the installed files have been modified locally (i.e.
+    ``verify_installed_content`` reports ``user_modified=True``), the
+    update is forced to require approval *and*
+    ``blocks_silent_overwrite`` is set, regardless of how clean the
+    manifest diff was.
+    """
+    policy = check_update_policy(local_manifest, remote_manifest)
+
+    verification = verify_installed_content(course_id, version_id, home)
+    if verification["user_modified"]:
+        policy.requires_approval = True
+        policy.blocks_silent_overwrite = True
+        policy.reasons.append(
+            "installed content differs from manifest hash "
+            "(user modification detected)"
+        )
+
+    return policy

cli/_utils.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+"""CLI utility helpers — generic kwarg building, etc."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def only_not_none(
+    base: dict[str, Any],
+    **optional: Any,
+) -> dict[str, Any]:
+    """Return *base* merged with only the non-None *optional* entries."""
+    result = dict(base)
+    result.update({k: v for k, v in optional.items() if v is not None})
+    return result

cli/_version.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+"""Runtime-accessible package version.
+
+The source of truth is the wheel's metadata; this module reads it
+via importlib.metadata so editable installs and built wheels report
+the same string. When the package is not installed (e.g. running
+from a checkout without uv sync), falls back to reading
+pyproject.toml directly.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__: str = _pkg_version("logion-cli")
+except PackageNotFoundError:  # local checkout / sdist
+    import tomllib
+    from pathlib import Path
+
+    _pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    with _pyproject.open("rb") as _f:
+        __version__ = tomllib.load(_f)["project"]["version"]
+
+__all__ = ["__version__"]

cli/commands/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: MIT
+"""CLI command modules."""