raise-cli 2.2.1__py3-none-any.whl

raise_cli/cli/commands/_resolve.py

@@ -0,0 +1,153 @@
+"""Generic entry-point resolver for adapters and targets.
+
+Parametrized auto-detect logic:
+- 1 registered → auto-select
+- 0 registered → error with install guidance
+- 2+ registered → error listing names, request flag
+- flag → select by name (override)
+
+Auto-wraps async implementations with the provided sync wrapper.
+
+Replaces ``_adapter_resolve.py`` (S301.4, D7 — DRY).
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+
+from raise_cli.adapters.protocols import DocumentationTarget, ProjectManagementAdapter
+from raise_cli.adapters.registry import get_doc_targets, get_pm_adapters
+from raise_cli.adapters.sync import SyncDocsAdapter, SyncPMAdapter
+from raise_cli.onboarding.manifest import load_manifest
+
+logger = logging.getLogger(__name__)
+
+console = Console()
+
+
+def resolve_entrypoint(
+    discover: Callable[[], dict[str, Callable[[], Any]]],
+    sync_wrapper: type | None,
+    async_check_method: str,
+    group_label: str,
+    flag_name: str,
+    selected: str | None,
+) -> Any:
+    """Resolve and instantiate an adapter/target from entry points and YAML configs.
+
+    Args:
+        discover: Function returning {name: factory} from entry points and/or YAML.
+        sync_wrapper: Wrapper class for async→sync bridging (or None).
+        async_check_method: Method name to check for async (e.g., "get_issue").
+        group_label: Human label for error messages (e.g., "PM adapter").
+        flag_name: CLI flag name for error messages (e.g., "--adapter").
+        selected: Explicit selection by name, or None for auto-detect.
+
+    Returns:
+        An instantiated adapter/target, wrapped if async.
+
+    Raises:
+        SystemExit: If resolution fails.
+    """
+    entries = discover()
+
+    if selected is not None:
+        cls = entries.get(selected)
+        if cls is None:
+            available = ", ".join(sorted(entries)) if entries else "none"
+            console.print(
+                f"[red]Error:[/red] {group_label} '{selected}' not found. "
+                f"Available: {available}"
+            )
+            sys.exit(1)
+    elif len(entries) == 0:
+        console.print(
+            f"[red]Error:[/red] No {group_label} installed.\n"
+            f"Install one or register via entry points. Use {flag_name} to select."
+        )
+        sys.exit(1)
+    elif len(entries) == 1:
+        cls = next(iter(entries.values()))
+    else:
+        names = ", ".join(sorted(entries))
+        console.print(
+            f"[red]Error:[/red] Multiple {group_label}s found: {names}.\n"
+            f"Use {flag_name} <name> to select."
+        )
+        sys.exit(1)
+
+    try:
+        instance = cls()
+    except Exception as exc:
+        name = selected or next(iter(entries))
+        console.print(
+            f"[red]Error:[/red] Failed to instantiate {group_label} '{name}': {exc}"
+        )
+        sys.exit(1)
+
+    # Auto-wrap async implementations for sync CLI consumption
+    if sync_wrapper and inspect.iscoroutinefunction(
+        getattr(instance, async_check_method, None)
+    ):
+        instance = sync_wrapper(instance)
+
+    return instance
+
+
+def _discover_pm() -> dict[str, Callable[[], Any]]:
+    """Merge YAML and entry point PM adapters. EP wins on name collision."""
+    from raise_cli.adapters.declarative.discovery import discover_yaml_adapters
+
+    return {**discover_yaml_adapters("pm"), **get_pm_adapters()}
+
+
+def _discover_docs() -> dict[str, Callable[[], Any]]:
+    """Merge YAML and entry point docs targets. EP wins on name collision."""
+    from raise_cli.adapters.declarative.discovery import discover_yaml_adapters
+
+    return {**discover_yaml_adapters("docs"), **get_doc_targets()}
+
+
+def resolve_adapter(adapter_name: str | None) -> ProjectManagementAdapter:
+    """Resolve a ProjectManagementAdapter from entry points and YAML configs.
+
+    Resolution priority:
+    1. Explicit adapter_name (from -a/--adapter flag) → use it
+    2. Manifest backlog.adapter_default → use it
+    3. Auto-detect (single adapter) or error (0 / 2+)
+    """
+    effective = adapter_name
+
+    if effective is None:
+        manifest = load_manifest(Path.cwd())
+        if manifest and manifest.backlog and manifest.backlog.adapter_default:
+            effective = manifest.backlog.adapter_default
+            logger.debug("Using manifest default adapter: %s", effective)
+
+    return resolve_entrypoint(
+        discover=_discover_pm,
+        sync_wrapper=SyncPMAdapter,
+        async_check_method="get_issue",
+        group_label="PM adapter",
+        flag_name="--adapter",
+        selected=effective,
+    )
+
+
+def resolve_docs_target(target_name: str | None) -> DocumentationTarget:
+    """Resolve a DocumentationTarget from entry points and YAML configs."""
+    return resolve_entrypoint(
+        discover=_discover_docs,
+        sync_wrapper=SyncDocsAdapter,
+        async_check_method="get_page",
+        group_label="docs target",
+        flag_name="--target",
+        selected=target_name,
+    )

raise_cli/cli/commands/adapters.py

@@ -0,0 +1,362 @@
+"""CLI commands for adapter discovery and validation.
+
+Provides `rai adapter list`, `rai adapter check`, `rai adapter validate`,
+and `rai adapter status` for inspecting, checking, and validating adapter
+configurations.
+
+Architecture: ADR-033 (PM), ADR-034 (Governance), ADR-036 (Graph Backend), ADR-041 (Declarative)
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from raise_cli.adapters.protocols import (
+    DocumentationTarget,
+    GovernanceParser,
+    GovernanceSchemaProvider,
+    ProjectManagementAdapter,
+)
+from raise_cli.adapters.registry import (
+    EP_DOC_TARGETS,
+    EP_GOVERNANCE_PARSERS,
+    EP_GOVERNANCE_SCHEMAS,
+    EP_GRAPH_BACKENDS,
+    EP_PM_ADAPTERS,
+)
+from raise_cli.hooks.emitter import create_emitter
+from raise_cli.hooks.events import AdapterFailedEvent, AdapterLoadedEvent
+from raise_cli.output.formatters.adapters import (
+    format_check_human,
+    format_check_json,
+    format_list_human,
+    format_list_json,
+    format_validate_human,
+)
+from raise_cli.tier.context import TierContext
+from raise_core.graph.backends.protocol import KnowledgeGraphBackend
+
+adapters_app = typer.Typer(
+    name="adapter",
+    help="Inspect and validate registered adapters",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+# Group → (Protocol display name, Protocol class).
+# Only consumer of this mapping — lives here per arch review Q1.
+ADAPTER_GROUPS: dict[str, tuple[str, type]] = {
+    EP_GOVERNANCE_PARSERS: ("GovernanceParser", GovernanceParser),
+    EP_GRAPH_BACKENDS: ("KnowledgeGraphBackend", KnowledgeGraphBackend),
+    EP_PM_ADAPTERS: ("ProjectManagementAdapter", ProjectManagementAdapter),
+    EP_GOVERNANCE_SCHEMAS: ("GovernanceSchemaProvider", GovernanceSchemaProvider),
+    EP_DOC_TARGETS: ("DocumentationTarget", DocumentationTarget),
+}
+
+
+def _get_dist_name(ep: Any) -> str:
+    """Best-effort extraction of distribution name from an entry point."""
+    try:
+        return ep.dist.name  # type: ignore[union-attr]
+    except AttributeError:
+        return "unknown"
+
+
+def _collect_groups() -> list[dict[str, Any]]:
+    """Collect adapter info for all entry point groups."""
+    groups: list[dict[str, Any]] = []
+    for group, (proto_name, _proto_cls) in ADAPTER_GROUPS.items():
+        adapters: list[dict[str, str]] = []
+        for ep in entry_points(group=group):
+            adapters.append({"name": ep.name, "package": _get_dist_name(ep)})
+        groups.append(
+            {
+                "group": group,
+                "protocol_name": proto_name,
+                "adapters": adapters,
+            }
+        )
+    return groups
+
+
+def _get_tier() -> str:
+    """Get current tier level string."""
+    ctx = TierContext.from_manifest(Path.cwd())
+    return ctx.tier.value
+
+
+@adapters_app.command("list")
+def list_command(
+    format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: human or json",
+        ),
+    ] = "human",
+) -> None:
+    """List all registered adapters by entry point group.
+
+    Shows each entry point group with its registered adapters and
+    their source package.
+
+    Examples:
+        $ rai adapter list
+        $ rai adapter list --format json
+    """
+    tier = _get_tier()
+    groups = _collect_groups()
+
+    if format == "json":
+        typer.echo(format_list_json(tier, groups))
+    else:
+        format_list_human(tier, groups, console)
+
+
+@adapters_app.command("check")
+def check_command(
+    format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: human or json",
+        ),
+    ] = "human",
+) -> None:
+    """Validate adapters against their Protocol contracts.
+
+    Loads each registered adapter and checks compliance via isinstance()
+    against its corresponding @runtime_checkable Protocol.
+
+    Examples:
+        $ rai adapter check
+        $ rai adapter check --format json
+    """
+    results: list[dict[str, Any]] = []
+    emitter = create_emitter()
+
+    for group, (proto_name, proto_cls) in ADAPTER_GROUPS.items():
+        for ep in entry_points(group=group):
+            try:
+                loaded: Any = ep.load()
+            except Exception as exc:  # noqa: BLE001
+                emitter.emit(
+                    AdapterFailedEvent(
+                        adapter_name=ep.name,
+                        group=group,
+                        error=str(exc),
+                    )
+                )
+                results.append(
+                    {
+                        "group": group,
+                        "name": ep.name,
+                        "package": _get_dist_name(ep),
+                        "protocol_name": proto_name,
+                        "compliant": False,
+                        "error": f"Failed to load: {exc}",
+                    }
+                )
+                continue
+
+            compliant = inspect.isclass(loaded) and issubclass(loaded, proto_cls)
+            error = None if compliant else f"Not a {proto_name} subclass"
+            if compliant:
+                emitter.emit(
+                    AdapterLoadedEvent(
+                        adapter_name=ep.name,
+                        group=group,
+                        adapter_type=type(loaded).__name__,
+                    )
+                )
+            else:
+                emitter.emit(
+                    AdapterFailedEvent(
+                        adapter_name=ep.name,
+                        group=group,
+                        error=error or "",
+                    )
+                )
+            results.append(
+                {
+                    "group": group,
+                    "name": ep.name,
+                    "package": _get_dist_name(ep),
+                    "protocol_name": proto_name,
+                    "compliant": compliant,
+                    "error": error,
+                }
+            )
+
+    if format == "json":
+        typer.echo(format_check_json(results))
+    else:
+        format_check_human(results, console)
+
+
+@adapters_app.command("validate")
+def validate_command(
+    file: Annotated[
+        Path,
+        typer.Argument(help="Path to YAML adapter config file"),
+    ],
+) -> None:
+    """Validate a declarative YAML adapter config.
+
+    Checks that the YAML file conforms to the DeclarativeAdapterConfig
+    schema. Reports adapter name, protocol, and method counts on success,
+    or specific field errors on failure.
+
+    Examples:
+        $ rai adapter validate .raise/adapters/github.yaml
+        $ rai adapter validate my-adapter.yaml
+    """
+    import yaml
+    from pydantic import ValidationError
+
+    from raise_cli.adapters.declarative.schema import DeclarativeAdapterConfig
+
+    if not file.exists():
+        console.print(f"[red]Error:[/red] File not found: {file}")
+        raise typer.Exit(1)
+
+    try:
+        raw = yaml.safe_load(file.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        console.print(f"[red]✗ Invalid adapter config:[/red] {file.name}")
+        console.print(f"  Cannot parse YAML: {exc}")
+        raise typer.Exit(1) from None
+
+    if not isinstance(raw, dict):
+        console.print(f"[red]✗ Invalid adapter config:[/red] {file.name}")
+        console.print("  YAML content is not a mapping")
+        raise typer.Exit(1)
+
+    try:
+        config = DeclarativeAdapterConfig.model_validate(raw)
+    except ValidationError as exc:
+        console.print(f"[red]✗ Invalid adapter config:[/red] {file.name}")
+        for err in exc.errors():
+            loc = ".".join(str(p) for p in err["loc"])
+            console.print(f"  {loc}")
+            console.print(f"    {err['msg']}")
+        raise typer.Exit(1) from None
+
+    format_validate_human(config, console)
+
+
+# ---------------------------------------------------------------------------
+# rai adapter status — show configuration status for known adapters
+# ---------------------------------------------------------------------------
+
+# Jira env var names expected by McpJiraAdapter._create_bridge
+_JIRA_ENV_VARS: list[tuple[str, str]] = [
+    ("JIRA_URL", "Jira instance URL"),
+    ("JIRA_USERNAME", "Jira user email"),
+    ("JIRA_API_TOKEN", "Jira API token (or JIRA_TOKEN)"),
+]
+
+
+def _check_jira_config(project_root: Path) -> dict[str, Any]:
+    """Collect Jira adapter configuration status.
+
+    Returns a dict with keys: yaml_path, yaml_exists, env_vars (list of
+    dicts with name, set, description), and ready (bool).
+    """
+    yaml_path = project_root / ".raise" / "jira.yaml"
+    env_results: list[dict[str, Any]] = []
+    for var_name, description in _JIRA_ENV_VARS:
+        if var_name == "JIRA_API_TOKEN":
+            is_set = bool(os.environ.get("JIRA_API_TOKEN") or os.environ.get("JIRA_TOKEN"))
+        else:
+            is_set = bool(os.environ.get(var_name))
+        env_results.append({"name": var_name, "set": is_set, "description": description})
+
+    all_env_set = all(e["set"] for e in env_results)
+    return {
+        "yaml_path": str(yaml_path),
+        "yaml_exists": yaml_path.exists(),
+        "env_vars": env_results,
+        "ready": yaml_path.exists() and all_env_set,
+    }
+
+
+@adapters_app.command("status")
+def status_command(
+    format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            "-f",
+            help="Output format: human or json",
+        ),
+    ] = "human",
+) -> None:
+    """Show configuration status for known adapters.
+
+    Checks that required config files exist and environment variables
+    are set. Useful for verifying setup after configuring an adapter.
+
+    Examples:
+        $ rai adapter status
+        $ rai adapter status --format json
+    """
+    import json as json_mod
+
+    project_root = Path.cwd()
+    jira_status = _check_jira_config(project_root)
+
+    if format == "json":
+        typer.echo(json_mod.dumps({"jira": jira_status}, indent=2))
+        return
+
+    console.print("[bold]Adapter Configuration Status[/bold]\n")
+
+    # --- Jira ---
+    console.print("[bold]Jira[/bold]")
+
+    yaml_path = jira_status["yaml_path"]
+    if jira_status["yaml_exists"]:
+        console.print(f"  [green]\u2713[/green] Config: {yaml_path}")
+    else:
+        console.print(f"  [red]\u2717[/red] Config: {yaml_path} [red](not found)[/red]")
+        console.print(
+            "    [dim]Create .raise/jira.yaml with status_mapping and project config.[/dim]"
+        )
+
+    for env_var in jira_status["env_vars"]:
+        if env_var["set"]:
+            console.print(f"  [green]\u2713[/green] {env_var['name']}: set")
+        else:
+            console.print(
+                f"  [red]\u2717[/red] {env_var['name']}: [red]not set[/red]"
+                f"  [dim]({env_var['description']})[/dim]"
+            )
+
+    console.print()
+    if jira_status["ready"]:
+        console.print("[green]Jira adapter is fully configured.[/green]")
+    else:
+        missing: list[str] = []
+        if not jira_status["yaml_exists"]:
+            missing.append(".raise/jira.yaml")
+        for env_var in jira_status["env_vars"]:
+            if not env_var["set"]:
+                missing.append(env_var["name"])
+        console.print(
+            f"[yellow]Jira adapter is not ready.[/yellow] Missing: {', '.join(missing)}"
+        )
+        console.print(
+            "\n[dim]Set env vars in .env or shell. "
+            "See CLAUDE.md 'Jira Access' section for details.[/dim]"
+        )

raise_cli/cli/commands/artifact.py

@@ -0,0 +1,137 @@
+"""CLI commands for artifact validation.
+
+Provides ``rai artifact validate`` for checking YAML artifacts
+against the Pydantic type registry.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+
+from raise_cli.artifacts.reader import read_artifact
+
+artifact_app = typer.Typer(
+    name="artifact",
+    help="Manage skill artifacts",
+    no_args_is_help=True,
+)
+
+console = Console()
+
+
+def _resolve_project_root() -> Path:
+    """Resolve the project root from env or cwd."""
+    env_root = os.environ.get("RAI_PROJECT_ROOT")
+    if env_root:
+        return Path(env_root)
+    return Path.cwd()
+
+
+@artifact_app.command("validate")
+def validate_command(
+    file: Annotated[
+        str | None,
+        typer.Option("--file", help="Path to a single artifact file to validate"),
+    ] = None,
+    format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format: human or json"),
+    ] = "human",
+) -> None:
+    """Validate YAML artifacts against their Pydantic schemas.
+
+    Reads all .yaml files from .raise/artifacts/ (or a single file with --file)
+    and validates each against the type registry.
+
+    Exit code 0 if all pass, 1 if any fail.
+
+    Examples:
+        $ rai artifact validate
+        $ rai artifact validate --file .raise/artifacts/s354.1-design.yaml
+        $ rai artifact validate --format json
+    """
+    if file:
+        paths = _resolve_single_file(Path(file), format)
+    else:
+        paths = _resolve_all_artifacts(format)
+
+    if paths is None:
+        return  # Already handled (exit raised)
+
+    results: list[dict[str, object]] = []
+    for path in paths:
+        try:
+            read_artifact(path)
+            results.append({"file": path.name, "passed": True, "error": None})
+        except (ValidationError, Exception) as exc:  # noqa: BLE001
+            results.append({"file": path.name, "passed": False, "error": str(exc)})
+
+    failed = [r for r in results if not r["passed"]]
+
+    if format == "json":
+        typer.echo(
+            json.dumps(
+                {"results": results, "all_passed": len(failed) == 0},
+                indent=2,
+            )
+        )
+    else:
+        for r in results:
+            marker = "[green]✓[/green]" if r["passed"] else "[red]✗[/red]"
+            console.print(f"  {marker} {r['file']}")
+            if r["error"]:
+                # Show first line of error only
+                first_line = str(r["error"]).split("\n")[0]
+                console.print(f"    {first_line}")
+        console.print()
+        if failed:
+            console.print(
+                f"[red bold]FAILED:[/red bold] {len(failed)} of {len(results)} artifacts invalid"
+            )
+        else:
+            console.print(
+                f"[green bold]PASSED:[/green bold] {len(results)} artifact(s) valid"
+            )
+
+    raise typer.Exit(1 if failed else 0)
+
+
+def _resolve_single_file(path: Path, fmt: str) -> list[Path] | None:
+    """Resolve a single file path, handling not-found."""
+    if not path.exists():
+        if fmt == "json":
+            typer.echo(json.dumps({"error": f"File not found: {path}"}))
+        else:
+            console.print(f"[red]Error:[/red] File not found: {path}")
+        raise typer.Exit(1)
+    return [path]
+
+
+def _resolve_all_artifacts(fmt: str) -> list[Path] | None:
+    """Resolve all artifact files from .raise/artifacts/."""
+    root = _resolve_project_root()
+    artifacts_dir = root / ".raise" / "artifacts"
+
+    if not artifacts_dir.is_dir():
+        if fmt == "json":
+            typer.echo(json.dumps({"results": [], "all_passed": True, "message": "No artifacts found"}))
+        else:
+            console.print("No artifacts found in .raise/artifacts/")
+        raise typer.Exit(0)
+
+    paths = sorted(artifacts_dir.glob("*.yaml"))
+    if not paths:
+        if fmt == "json":
+            typer.echo(json.dumps({"results": [], "all_passed": True, "message": "No artifacts found"}))
+        else:
+            console.print("No artifacts found in .raise/artifacts/")
+        raise typer.Exit(0)
+
+    return paths