@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/cli/record_cmd.py

@@ -0,0 +1,238 @@
+"""Session record/replay commands.
+
+    skcapstone record [--output FILE.jsonl]
+        Start the MCP server in recording mode.  All tool calls +
+        responses are captured as JSONL.  Sessions are also auto-saved
+        to ~/.skcapstone/sessions/ (last 5 kept).
+
+    skcapstone replay FILE.jsonl [--dry-run]
+        Play back a recorded session.  --dry-run prints what would
+        be called without executing any handlers.
+
+    skcapstone sessions list
+        List all auto-saved sessions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+
+
+def register_record_commands(main: click.Group) -> None:
+    """Register record, replay, and sessions commands."""
+
+    # ------------------------------------------------------------------
+    # skcapstone record
+    # ------------------------------------------------------------------
+
+    @main.command("record")
+    @click.option(
+        "--output", "-o",
+        default=None,
+        type=click.Path(),
+        help="Write tool calls to this JSONL file (in addition to auto-session).",
+    )
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def record(output: str | None, home: str) -> None:
+        """Start MCP server in recording mode.
+
+        Every tool call and its response is captured as a JSONL line.
+        Sessions are also auto-saved to ~/.skcapstone/sessions/ with
+        the last 5 retained.
+
+        \b
+        Examples:
+            skcapstone record
+            skcapstone record --output /tmp/debug.jsonl
+            SKCAPSTONE_RECORD_FILE=/tmp/debug.jsonl skcapstone mcp serve
+        """
+        if output:
+            os.environ["SKCAPSTONE_RECORD_FILE"] = str(Path(output).expanduser())
+            console.print(f"  [green]Recording to:[/] {output}")
+
+        home_path = Path(home).expanduser()
+        if not home_path.exists():
+            console.print(
+                "[bold red]No agent found.[/] Run [cyan]skcapstone init[/] first."
+            )
+            sys.exit(1)
+
+        console.print(
+            "  [dim]Auto-session saved to[/] "
+            f"[cyan]{home_path / 'sessions'}[/]  (last 5 kept)"
+        )
+        console.print("  [dim]Starting MCP server … (Ctrl-C to stop)[/]\n")
+
+        import asyncio
+        from ..mcp_server import _run_server
+        try:
+            asyncio.run(_run_server())
+        except KeyboardInterrupt:
+            console.print("\n  [yellow]Recording stopped.[/]")
+
+    # ------------------------------------------------------------------
+    # skcapstone replay
+    # ------------------------------------------------------------------
+
+    @main.command("replay")
+    @click.argument("session_file", type=click.Path(exists=True))
+    @click.option(
+        "--dry-run", "dry_run",
+        is_flag=True,
+        default=False,
+        help="Print what would be called without executing handlers.",
+    )
+    @click.option(
+        "--format", "fmt",
+        type=click.Choice(["text", "json"]),
+        default="text",
+        help="Output format.",
+    )
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    def replay(
+        session_file: str,
+        dry_run: bool,
+        fmt: str,
+        home: str,
+    ) -> None:
+        """Replay a recorded JSONL session.
+
+        \b
+        Modes:
+            --dry-run   Print tool names + arguments only (no execution).
+            (default)   Execute each tool call against the live handlers
+                        and compare results to the recording.
+
+        \b
+        Examples:
+            skcapstone replay session-20260302T120000.jsonl --dry-run
+            skcapstone replay /tmp/debug.jsonl
+            skcapstone replay /tmp/debug.jsonl --format json
+        """
+        from ..session_replayer import SessionReplayer
+
+        path = Path(session_file).expanduser()
+        replayer = SessionReplayer(path, dry_run=dry_run)
+        results = list(replayer.replay())
+
+        if fmt == "json":
+            # Pure JSON output — no decorative header so callers can parse stdout.
+            rows = []
+            for r in results:
+                rows.append({
+                    "index": r.index,
+                    "tool": r.tool,
+                    "arguments": r.arguments,
+                    "recorded_result": r.recorded_result,
+                    "replayed_result": r.replayed_result,
+                    "duration_ms": r.duration_ms,
+                    "match": r.match,
+                    "error": r.error,
+                })
+            click.echo(json.dumps(rows, indent=2, default=str))
+            return
+
+        # Text output
+        mode_label = "[yellow]DRY-RUN[/]" if dry_run else "[green]LIVE[/]"
+        console.print(f"\n  Replaying [bold]{path.name}[/]  {mode_label}\n")
+        if not results:
+            console.print("  [dim]Session file is empty.[/]\n")
+            return
+
+        mismatches = 0
+        errors = 0
+        for r in results:
+            args_preview = json.dumps(r.arguments, ensure_ascii=False)
+            if len(args_preview) > 80:
+                args_preview = args_preview[:77] + "..."
+
+            if dry_run:
+                status = "[dim]SKIP[/]"
+            elif r.error:
+                status = "[red]ERROR[/]"
+                errors += 1
+            elif r.match is True:
+                status = "[green]MATCH[/]"
+            elif r.match is False:
+                status = "[yellow]DIFF[/]"
+                mismatches += 1
+            else:
+                status = "[dim]?[/]"
+
+            console.print(
+                f"  [{r.index:>3}] {status}  [cyan]{r.tool}[/]"
+                f"  [dim]{args_preview}[/]"
+                f"  [dim]{r.duration_ms}ms[/]"
+            )
+            if r.error:
+                console.print(f"        [red]{r.error}[/]")
+
+        total = len(results)
+        console.print(f"\n  {total} call(s) replayed", end="")
+        if not dry_run:
+            if mismatches:
+                console.print(f"  [yellow]{mismatches} diff(s)[/]", end="")
+            if errors:
+                console.print(f"  [red]{errors} error(s)[/]", end="")
+        console.print("\n")
+
+        if not dry_run and (mismatches or errors):
+            sys.exit(1)
+
+    # ------------------------------------------------------------------
+    # skcapstone sessions
+    # ------------------------------------------------------------------
+
+    @main.group("sessions")
+    def sessions_group() -> None:
+        """Manage auto-saved MCP sessions."""
+
+    @sessions_group.command("list")
+    @click.option("--home", default=AGENT_HOME, type=click.Path())
+    @click.option("--limit", default=10, help="Max sessions to show.")
+    def sessions_list(home: str, limit: int) -> None:
+        """List auto-saved session files newest-first.
+
+        \b
+        Example:
+            skcapstone sessions list
+            skcapstone sessions list --limit 3
+        """
+        from ..session_recorder import list_sessions, load_session
+
+        home_path = Path(home).expanduser()
+        files = list_sessions(home_path)
+
+        if not files:
+            console.print("\n  [dim]No sessions found in "
+                          f"{home_path / 'sessions'}[/]\n")
+            return
+
+        console.print(f"\n  [bold]{len(files)}[/] session(s) found "
+                      f"(showing up to {limit}):\n")
+        for f in files[:limit]:
+            try:
+                entries = load_session(f)
+                count = len(entries)
+                tools = list({e.get("tool", "?") for e in entries})
+                tools_str = ", ".join(sorted(tools)[:5])
+                if len(tools) > 5:
+                    tools_str += f" +{len(tools) - 5}"
+            except Exception:
+                count = 0
+                tools_str = "[dim]unreadable[/]"
+
+            size_kb = f.stat().st_size / 1024
+            console.print(
+                f"  [cyan]{f.name}[/]  "
+                f"[dim]{count} calls  {size_kb:.1f}KB  {tools_str}[/]"
+            )
+            console.print(f"    [dim]{f}[/]")
+        console.print()

package/src/skcapstone/cli/register_cmd.py

@@ -0,0 +1,159 @@
+"""Register command — auto-register SK* skills and MCP servers.
+
+Detects the user's environments (OpenClaw, Claude Code, Cursor, VS Code,
+OpenCode CLI, mcporter) and registers SKILL.md symlinks + MCP server entries.
+
+Commands:
+    skcapstone register              — register all SK* packages
+    skcapstone register --dry-run    — show what would be done
+    skcapstone register --env claude-code  — target specific environment
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from ._common import AGENT_HOME, console
+
+
+def register_register_commands(main: click.Group) -> None:
+    """Register the 'register' command on the main CLI group."""
+
+    @main.command()
+    @click.option(
+        "--workspace",
+        default=None,
+        help="Workspace root directory (default: ~/clawd/).",
+        type=click.Path(),
+    )
+    @click.option(
+        "--env",
+        "target_env",
+        default=None,
+        help="Target a specific environment (e.g. claude-code, cursor, mcporter).",
+    )
+    @click.option(
+        "--dry-run",
+        is_flag=True,
+        default=False,
+        help="Show what would be done without making changes.",
+    )
+    def register(
+        workspace: Optional[str],
+        target_env: Optional[str],
+        dry_run: bool,
+    ) -> None:
+        """Register all SK* skills and MCP servers in detected environments.
+
+        Auto-detects your development environments (Claude Code, Cursor,
+        VS Code, OpenClaw, OpenCode, mcporter) and ensures all SK* skill
+        manifests and MCP server entries are properly configured.
+
+        Examples:
+
+          skcapstone register                  # auto-detect and register
+          skcapstone register --dry-run        # preview what would happen
+          skcapstone register --env claude-code # target Claude Code only
+        """
+        from skmemory.register import detect_environments
+        from skcapstone.register import register_all
+
+        workspace_path = Path(workspace).expanduser() if workspace else None
+        environments = [target_env] if target_env else None
+
+        console.print()
+        console.print("[bold cyan]SK* Registration[/]")
+        console.print()
+
+        # Show detected environments
+        detected = detect_environments()
+        console.print("  [bold]Detected environments:[/]")
+        for env in detected:
+            marker = "[green]●[/]" if (environments is None or env in environments) else "[dim]○[/]"
+            console.print(f"    {marker} {env}")
+        if not detected:
+            console.print("    [dim]None detected[/]")
+            console.print()
+            console.print("  [yellow]Tip:[/] Install OpenClaw, Claude Code, or Cursor to enable registration.")
+        console.print()
+
+        if dry_run:
+            console.print("  [yellow]Dry run — no changes will be made.[/]")
+            console.print()
+
+        # Run registration
+        results = register_all(
+            workspace=workspace_path,
+            environments=environments,
+            dry_run=dry_run,
+        )
+
+        # Display results
+        from rich.table import Table
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Package", style="cyan")
+        table.add_column("Skill", style="dim")
+        table.add_column("MCP")
+        table.add_column("OpenClaw Plugin")
+
+        for name, pkg_result in results.get("packages", {}).items():
+            skill_info = pkg_result.get("skill", {})
+            skill_action = skill_info.get("action", "—")
+
+            if skill_action == "created":
+                skill_str = "[green]created[/]"
+            elif skill_action == "exists":
+                skill_str = "[dim]exists[/]"
+            elif skill_action == "error":
+                skill_str = f"[red]{skill_info.get('error', 'error')}[/]"
+            elif skill_action == "dry-run":
+                skill_str = "[yellow]would create[/]"
+            else:
+                skill_str = f"[dim]{skill_action}[/]"
+
+            mcp_info = pkg_result.get("mcp", {})
+            if not mcp_info:
+                mcp_str = "[dim]—[/]"
+            elif isinstance(mcp_info, dict):
+                parts = []
+                for env_name, action in mcp_info.items():
+                    if action == "created":
+                        parts.append(f"[green]{env_name}[/]")
+                    elif action == "exists":
+                        parts.append(f"[dim]{env_name}[/]")
+                    elif action == "dry-run":
+                        parts.append(f"[yellow]{env_name}[/]")
+                    else:
+                        parts.append(f"{env_name}:{action}")
+                mcp_str = ", ".join(parts) if parts else "[dim]—[/]"
+            else:
+                mcp_str = str(mcp_info)
+
+            plugin_action = pkg_result.get("openclaw_plugin", "")
+            if plugin_action == "created":
+                plugin_str = "[green]created[/]"
+            elif plugin_action == "exists":
+                plugin_str = "[dim]exists[/]"
+            elif plugin_action == "dry-run":
+                plugin_str = "[yellow]would create[/]"
+            elif plugin_action and plugin_action.startswith("error"):
+                plugin_str = f"[red]{plugin_action}[/]"
+            elif not plugin_action:
+                plugin_str = "[dim]—[/]"
+            else:
+                plugin_str = f"[dim]{plugin_action}[/]"
+
+            table.add_row(name, skill_str, mcp_str, plugin_str)
+
+        console.print(table)
+        console.print()
+
+        if dry_run:
+            console.print("  [yellow]No changes made (dry run).[/]")
+        else:
+            console.print("  [green]Registration complete.[/]")
+        console.print()

package/src/skcapstone/cli/search_cmd.py

@@ -0,0 +1,156 @@
+"""Search command: full-text search across memories, conversations, and messages."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.table import Table
+from rich.text import Text
+
+from ._common import AGENT_HOME, console
+
+
+# Source icons shown in the table
+_SOURCE_ICON = {
+    "memory": "🧠",
+    "conversation": "💬",
+    "message": "📨",
+    "journal": "📓",
+}
+
+_SOURCE_COLOR = {
+    "memory": "cyan",
+    "conversation": "green",
+    "message": "yellow",
+    "journal": "magenta",
+}
+
+_VALID_SOURCES = ("memory", "conversation", "message", "journal")
+
+
+def _fmt_ts(ts) -> str:
+    """Format a datetime for display, returning '--' for None."""
+    if ts is None:
+        return "--"
+    return ts.strftime("%Y-%m-%d %H:%M")
+
+
+def register_search_commands(main: click.Group) -> None:
+    """Register the top-level ``search`` command."""
+
+    @main.command("search")
+    @click.argument("query")
+    @click.option(
+        "--home",
+        default=AGENT_HOME,
+        type=click.Path(),
+        help="Agent home directory.",
+    )
+    @click.option(
+        "--type", "-t",
+        "source_types",
+        multiple=True,
+        type=click.Choice(_VALID_SOURCES),
+        help=(
+            "Restrict search to a specific source type. "
+            "May be repeated: -t memory -t conversation"
+        ),
+    )
+    @click.option(
+        "--limit", "-n",
+        default=20,
+        show_default=True,
+        help="Maximum number of results.",
+    )
+    @click.option(
+        "--json-out",
+        is_flag=True,
+        help="Output results as JSON.",
+    )
+    def search_cmd(query, home, source_types, limit, json_out):
+        """Search across memories, conversations, and messages.
+
+        QUERY is matched case-insensitively against all data stores.
+        Results are ranked by relevance and recency.
+
+        Examples:\n
+          skcapstone search "consciousness"\n
+          skcapstone search "Opus" --type conversation\n
+          skcapstone search "trust" -t memory -t journal -n 10\n
+          skcapstone search "sprint" --json-out | jq .[].preview
+        """
+        from ..unified_search import search as unified_search, SOURCE_ALL
+
+        home_path = Path(home).expanduser()
+        if not home_path.exists():
+            if json_out:
+                print(json.dumps([]))
+                return
+            console.print(
+                "[bold red]No agent found.[/] Run [cyan]skcapstone init[/] first."
+            )
+            sys.exit(1)
+
+        sources = frozenset(source_types) if source_types else SOURCE_ALL
+
+        results = unified_search(home=home_path, query=query, sources=sources, limit=limit)
+
+        if json_out:
+            output = [
+                {
+                    "source": r.source,
+                    "id": r.result_id,
+                    "title": r.title,
+                    "preview": r.preview,
+                    "score": round(r.score, 4),
+                    "timestamp": r.timestamp.isoformat() if r.timestamp else None,
+                    "metadata": r.metadata,
+                }
+                for r in results
+            ]
+            print(json.dumps(output, indent=2))
+            return
+
+        if not results:
+            console.print(
+                f"\n  [dim]No results for '[/]{query}[dim]'[/] "
+                f"across {', '.join(sorted(sources))}.\n"
+            )
+            return
+
+        source_label = (
+            ", ".join(sorted(sources))
+            if len(sources) < len(SOURCE_ALL)
+            else "all sources"
+        )
+        console.print(
+            f"\n  [bold]{len(results)}[/] result"
+            f"{'s' if len(results) != 1 else ''} for "
+            f"[bold cyan]'{query}'[/] in {source_label}:\n"
+        )
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("Type", max_width=14)
+        table.add_column("Title", max_width=30)
+        table.add_column("Preview", max_width=55)
+        table.add_column("Score", justify="right", max_width=7)
+        table.add_column("Date", justify="right", style="dim", max_width=16)
+
+        for r in results:
+            icon = _SOURCE_ICON.get(r.source, "?")
+            color = _SOURCE_COLOR.get(r.source, "white")
+            source_text = Text(f"{icon} {r.source}", style=color)
+            preview_clipped = r.preview[:110] + ("…" if len(r.preview) > 110 else "")
+            table.add_row(
+                source_text,
+                r.title,
+                preview_clipped,
+                f"{r.score:.2f}",
+                _fmt_ts(r.timestamp),
+            )
+
+        console.print(table)
+        console.print()

package/src/skcapstone/cli/service_cmd.py

@@ -0,0 +1,91 @@
+"""CLI command: skcapstone service check — service health checks."""
+
+from __future__ import annotations
+
+import json
+
+import click
+from rich.table import Table
+
+from ._common import console
+
+
+def register_service_commands(main: click.Group) -> None:
+    """Register the ``service`` command group on the main CLI."""
+
+    @main.group()
+    def service():
+        """Service infrastructure commands."""
+
+    @service.command("check")
+    @click.option("--json-out", is_flag=True, help="Output as machine-readable JSON.")
+    def service_check(json_out: bool):
+        """Check health of all services in the sovereign stack.
+
+        Pings SKVector (Qdrant), SKGraph (FalkorDB), Syncthing,
+        skcapstone daemon, and skchat daemon.  Reports status,
+        latency, and any errors.
+        """
+        from ..service_health import check_all_services
+
+        results = check_all_services()
+
+        if json_out:
+            up = sum(1 for r in results if r["status"] == "up")
+            down = sum(1 for r in results if r["status"] == "down")
+            data = {
+                "summary": {
+                    "total": len(results),
+                    "up": up,
+                    "down": down,
+                    "unknown": len(results) - up - down,
+                },
+                "services": results,
+            }
+            click.echo(json.dumps(data, indent=2))
+            return
+
+        console.print()
+
+        table = Table(
+            show_header=True, header_style="bold", box=None, padding=(0, 2),
+        )
+        table.add_column("Service", style="cyan", no_wrap=True)
+        table.add_column("URL", style="dim", no_wrap=True)
+        table.add_column("Status")
+        table.add_column("Latency", justify="right", style="dim")
+        table.add_column("Version", style="dim")
+        table.add_column("Error", style="dim")
+
+        status_styles = {
+            "up": "[green]UP[/]",
+            "down": "[red]DOWN[/]",
+            "unknown": "[yellow]UNKNOWN[/]",
+        }
+
+        for r in results:
+            status_str = status_styles.get(r["status"], r["status"])
+            latency_str = f"{r['latency_ms']:.0f}ms" if r["latency_ms"] else "-"
+            version_str = str(r["version"]) if r["version"] else "-"
+            error_str = r["error"][:50] if r["error"] else "-"
+            table.add_row(
+                r["name"], r["url"], status_str,
+                latency_str, version_str, error_str,
+            )
+
+        console.print(table)
+
+        up_count = sum(1 for r in results if r["status"] == "up")
+        down_count = sum(1 for r in results if r["status"] == "down")
+        total = len(results)
+
+        console.print()
+        if down_count == 0:
+            console.print(f"  [green]All {up_count}/{total} reachable services are healthy.[/]")
+        else:
+            console.print(
+                f"  [green]{up_count}[/] up, "
+                f"[red]{down_count}[/] down "
+                f"out of {total} services."
+            )
+        console.print()