@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/cli/errors_cmd.py

@@ -0,0 +1,285 @@
+"""Error queue commands: list, retry, clear."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+import click
+from rich.table import Table
+from rich.text import Text
+
+from ._common import console
+
+
+def register_errors_commands(main: click.Group) -> None:
+    """Register the ``errors`` command group."""
+
+    @main.group("errors")
+    def errors_grp():
+        """Error recovery queue — inspect and replay failed operations.
+
+        Failed LLM calls, message sends, and sync operations land here
+        and are retried automatically with exponential backoff (max 3 times).
+        """
+
+    # ------------------------------------------------------------------
+    # errors list
+    # ------------------------------------------------------------------
+
+    @errors_grp.command("list")
+    @click.option(
+        "--path",
+        default=None,
+        type=click.Path(),
+        help="Override error queue JSON path.",
+    )
+    @click.option(
+        "--all", "show_all",
+        is_flag=True,
+        help="Include resolved entries.",
+    )
+    @click.option(
+        "--status",
+        type=click.Choice(["pending", "retrying", "exhausted", "resolved"]),
+        default=None,
+        help="Filter by status.",
+    )
+    def errors_list(path, show_all, status):
+        """List queued error entries."""
+        from ..error_queue import ErrorQueue
+
+        q = ErrorQueue(path=Path(path) if path else None)
+        entries = q.list_entries(status=status, include_resolved=show_all)
+
+        stats = q.stats()
+        console.print(
+            f"\n  Error queue — "
+            f"[yellow]{stats.get('pending', 0)}[/] pending  "
+            f"[red]{stats.get('exhausted', 0)}[/] exhausted  "
+            f"[green]{stats.get('resolved', 0)}[/] resolved  "
+            f"([dim]{stats.get('total', 0)} total[/])\n"
+        )
+
+        if not entries:
+            console.print("  [dim]Queue is empty.[/]\n")
+            return
+
+        table = Table(show_header=True, header_style="bold", box=None, padding=(0, 2))
+        table.add_column("ID", style="cyan", max_width=12)
+        table.add_column("Type")
+        table.add_column("Error", max_width=40)
+        table.add_column("Retries", justify="right")
+        table.add_column("Status")
+        table.add_column("Next retry", style="dim")
+
+        status_styles = {
+            "pending": "yellow",
+            "retrying": "blue",
+            "exhausted": "red",
+            "resolved": "green",
+        }
+
+        for entry in entries:
+            color = status_styles.get(entry.status, "dim")
+            table.add_row(
+                entry.entry_id[:10],
+                entry.operation_type,
+                entry.error_message[:60] + ("…" if len(entry.error_message) > 60 else ""),
+                str(entry.retry_count),
+                Text(entry.status, style=color),
+                entry.next_retry_at[:19].replace("T", " ") if entry.next_retry_at else "—",
+            )
+
+        console.print(table)
+        console.print()
+
+    # ------------------------------------------------------------------
+    # errors retry
+    # ------------------------------------------------------------------
+
+    @errors_grp.command("retry")
+    @click.argument("entry_id", required=False, default=None)
+    @click.option(
+        "--all", "retry_all",
+        is_flag=True,
+        help="Retry all due entries.",
+    )
+    @click.option(
+        "--path",
+        default=None,
+        type=click.Path(),
+        help="Override error queue JSON path.",
+    )
+    def errors_retry(entry_id, retry_all, path):
+        """Retry a specific entry or all due entries.
+
+        ENTRY_ID  Hex entry ID (or prefix) to retry.
+
+        Without --all, ENTRY_ID is required.
+        """
+        from ..error_queue import ErrorQueue
+
+        if not retry_all and not entry_id:
+            console.print("[red]Provide ENTRY_ID or use --all.[/]")
+            sys.exit(1)
+
+        q = ErrorQueue(path=Path(path) if path else None)
+
+        if retry_all:
+            results = q.retry_all_due()
+            if not results:
+                console.print("\n  [dim]No entries currently due for retry.[/]\n")
+                return
+            ok = sum(1 for v in results.values() if v)
+            fail = len(results) - ok
+            console.print(
+                f"\n  Retried [bold]{len(results)}[/] entries — "
+                f"[green]{ok} resolved[/]  [yellow]{fail} still pending[/]\n"
+            )
+            return
+
+        # Single entry: allow prefix matching
+        entries = q.list_entries(include_resolved=True)
+        matched = [e for e in entries if e.entry_id.startswith(entry_id)]
+        if not matched:
+            console.print(f"[red]No entry found matching '[/]{entry_id}[red]'.[/]")
+            sys.exit(1)
+        if len(matched) > 1:
+            console.print(
+                f"[yellow]Ambiguous prefix '[/]{entry_id}[yellow]' — "
+                f"matches {len(matched)} entries. Use more characters.[/]"
+            )
+            sys.exit(1)
+
+        success = q.retry(matched[0].entry_id)
+        if success:
+            console.print(f"\n  [green]Resolved:[/] {matched[0].entry_id[:10]}\n")
+        else:
+            console.print(
+                f"\n  [yellow]Retry recorded for:[/] {matched[0].entry_id[:10]} "
+                f"(retries={matched[0].retry_count})\n"
+            )
+
+    # ------------------------------------------------------------------
+    # errors clear
+    # ------------------------------------------------------------------
+
+    @errors_grp.command("clear")
+    @click.argument("entry_id", required=False, default=None)
+    @click.option(
+        "--all", "clear_all",
+        is_flag=True,
+        help="Clear all entries.",
+    )
+    @click.option(
+        "--exhausted",
+        is_flag=True,
+        help="Clear only exhausted entries.",
+    )
+    @click.option(
+        "--resolved",
+        is_flag=True,
+        help="Clear only resolved entries.",
+    )
+    @click.option(
+        "--path",
+        default=None,
+        type=click.Path(),
+        help="Override error queue JSON path.",
+    )
+    @click.option("--force", is_flag=True, help="Skip confirmation prompt.")
+    def errors_clear(entry_id, clear_all, exhausted, resolved, path, force):
+        """Remove entries from the queue.
+
+        ENTRY_ID  Hex entry ID (or prefix) to remove.
+
+        Use --all, --exhausted, or --resolved for bulk removal.
+        """
+        from ..error_queue import ErrorQueue, ErrorStatus
+
+        if not any([entry_id, clear_all, exhausted, resolved]):
+            console.print(
+                "[red]Provide ENTRY_ID, --all, --exhausted, or --resolved.[/]"
+            )
+            sys.exit(1)
+
+        q = ErrorQueue(path=Path(path) if path else None)
+
+        if exhausted:
+            if not force and not click.confirm("Clear all exhausted entries?"):
+                console.print("[yellow]Aborted.[/]")
+                return
+            removed = q.clear_all(status=ErrorStatus.EXHAUSTED)
+            console.print(f"\n  [red]Cleared[/] {removed} exhausted entr{'y' if removed == 1 else 'ies'}.\n")
+            return
+
+        if resolved:
+            if not force and not click.confirm("Clear all resolved entries?"):
+                console.print("[yellow]Aborted.[/]")
+                return
+            removed = q.clear_all(status=ErrorStatus.RESOLVED)
+            console.print(f"\n  [green]Cleared[/] {removed} resolved entr{'y' if removed == 1 else 'ies'}.\n")
+            return
+
+        if clear_all:
+            stats = q.stats()
+            total = stats.get("total", 0)
+            if not force and not click.confirm(f"Clear all {total} entries?"):
+                console.print("[yellow]Aborted.[/]")
+                return
+            removed = q.clear_all()
+            console.print(f"\n  Cleared [bold]{removed}[/] entr{'y' if removed == 1 else 'ies'}.\n")
+            return
+
+        # Single entry
+        entries = q.list_entries(include_resolved=True)
+        matched = [e for e in entries if e.entry_id.startswith(entry_id)]
+        if not matched:
+            console.print(f"[red]No entry found matching '[/]{entry_id}[red]'.[/]")
+            sys.exit(1)
+        if len(matched) > 1:
+            console.print(
+                f"[yellow]Ambiguous prefix '[/]{entry_id}[yellow]' — "
+                f"matches {len(matched)} entries.[/]"
+            )
+            sys.exit(1)
+
+        if not force and not click.confirm(f"Remove entry {matched[0].entry_id[:10]}?"):
+            console.print("[yellow]Aborted.[/]")
+            return
+
+        q.remove(matched[0].entry_id)
+        console.print(f"\n  [red]Removed:[/] {matched[0].entry_id[:10]}\n")
+
+    # ------------------------------------------------------------------
+    # errors stats
+    # ------------------------------------------------------------------
+
+    @errors_grp.command("stats")
+    @click.option(
+        "--path",
+        default=None,
+        type=click.Path(),
+        help="Override error queue JSON path.",
+    )
+    def errors_stats(path):
+        """Show error queue statistics."""
+        from ..error_queue import ErrorQueue
+        from rich.panel import Panel
+
+        q = ErrorQueue(path=Path(path) if path else None)
+        s = q.stats()
+
+        console.print()
+        console.print(Panel(
+            f"[bold]Total:[/]     {s.get('total', 0)}\n"
+            f"[yellow]Pending:[/]   {s.get('pending', 0)}\n"
+            f"[blue]Retrying:[/]  {s.get('retrying', 0)}\n"
+            f"[red]Exhausted:[/] {s.get('exhausted', 0)}\n"
+            f"[green]Resolved:[/]  {s.get('resolved', 0)}",
+            title="Error Queue",
+            border_style="bright_blue",
+        ))
+        console.print()

package/src/skcapstone/cli/export_cmd.py

@@ -0,0 +1,156 @@
+"""Export and import commands for portable agent state bundles."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from ._common import AGENT_HOME, console
+
+from rich.panel import Panel
+
+
+def register_export_commands(main: click.Group) -> None:
+    """Register the export and import commands."""
+
+    @main.command("export")
+    @click.option("--home", default=AGENT_HOME, type=click.Path(), help="Agent home directory.")
+    @click.option(
+        "--output", "-o", default=None, type=click.Path(),
+        help="Output file path. Defaults to stdout.",
+    )
+    @click.option(
+        "--pretty/--compact", default=True,
+        help="Pretty-print JSON (default) or compact output.",
+    )
+    def export_cmd(home: str, output: str | None, pretty: bool):
+        """Export the full agent state as a portable JSON bundle.
+
+        Collects identity, soul overlays, memories, conversations, and
+        config into a single JSON document. Use ``--output`` to write to
+        a file, or pipe stdout for use in scripts.
+
+        Examples:
+
+            skcapstone export
+
+            skcapstone export --output agent-snapshot.json
+
+            skcapstone export --compact | gzip > snapshot.json.gz
+        """
+        from ..export import export_bundle
+
+        home_path = Path(home).expanduser()
+        if not home_path.exists():
+            console.print(f"[red]Agent home not found: {home_path}[/]")
+            raise SystemExit(1)
+
+        try:
+            bundle = export_bundle(home_path)
+        except Exception as exc:
+            console.print(f"[red]Export failed: {exc}[/]")
+            raise SystemExit(1)
+
+        indent = 2 if pretty else None
+        serialized = json.dumps(bundle, indent=indent, ensure_ascii=False)
+
+        if output:
+            out_path = Path(output).expanduser()
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            out_path.write_text(serialized, encoding="utf-8")
+            size_kb = out_path.stat().st_size / 1024
+            console.print(Panel(
+                f"[bold green]Export complete[/]\n"
+                f"Agent: {bundle['agent_name']}\n"
+                f"Memories: {len(bundle['memories'])}\n"
+                f"Conversations: {len(bundle['conversations'])}\n"
+                f"Soul overlays: {len((bundle.get('soul') or {}).get('installed') or {})}\n"
+                f"Size: {size_kb:.1f} KB\n"
+                f"File: [cyan]{out_path}[/]",
+                title="Agent Bundle Exported",
+                border_style="green",
+            ))
+        else:
+            sys.stdout.write(serialized)
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+
+    @main.command("import")
+    @click.argument("bundle_file", metavar="BUNDLE")
+    @click.option("--home", default=AGENT_HOME, type=click.Path(), help="Target agent home directory.")
+    @click.option("--overwrite-identity", is_flag=True, help="Overwrite existing identity file.")
+    @click.option("--overwrite-config", is_flag=True, help="Overwrite existing config file.")
+    @click.option("--overwrite-soul", is_flag=True, help="Overwrite existing soul files.")
+    def import_cmd(
+        bundle_file: str,
+        home: str,
+        overwrite_identity: bool,
+        overwrite_config: bool,
+        overwrite_soul: bool,
+    ):
+        """Import an agent state bundle into a home directory.
+
+        Memories are always merged (existing memories with the same ID are
+        kept). Conversations are merged per peer. Identity, config, and soul
+        are only written when their target file is absent — unless the
+        corresponding ``--overwrite-*`` flag is passed.
+
+        Examples:
+
+            skcapstone import agent-snapshot.json
+
+            skcapstone import snapshot.json --home ~/.skcapstone-new
+
+            skcapstone import snapshot.json --overwrite-identity --overwrite-config
+        """
+        from ..export import import_bundle
+
+        bundle_path = Path(bundle_file).expanduser()
+        if not bundle_path.exists():
+            console.print(f"[red]Bundle file not found: {bundle_path}[/]")
+            raise SystemExit(1)
+
+        try:
+            bundle = json.loads(bundle_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            console.print(f"[red]Cannot read bundle: {exc}[/]")
+            raise SystemExit(1)
+
+        home_path = Path(home).expanduser()
+
+        try:
+            result = import_bundle(
+                home=home_path,
+                bundle=bundle,
+                overwrite_identity=overwrite_identity,
+                overwrite_config=overwrite_config,
+                overwrite_soul=overwrite_soul,
+            )
+        except ValueError as exc:
+            console.print(f"[red]Invalid bundle: {exc}[/]")
+            raise SystemExit(1)
+        except Exception as exc:
+            console.print(f"[red]Import failed: {exc}[/]")
+            raise SystemExit(1)
+
+        identity_status = "[green]written[/]" if result["identity_written"] else "[dim]skipped[/]"
+        config_status = "[green]written[/]" if result["config_written"] else "[dim]skipped[/]"
+
+        console.print(Panel(
+            f"[bold green]Import complete[/]\n"
+            f"Memories imported:      {result['memories_imported']}\n"
+            f"Conversations imported: {result['conversations_imported']}\n"
+            f"Soul files written:     {result['soul_files_written']}\n"
+            f"Identity:               {identity_status}\n"
+            f"Config:                 {config_status}",
+            title="Agent Bundle Imported",
+            border_style="green",
+        ))
+
+        if result["errors"]:
+            console.print("[yellow]Warnings:[/]")
+            for err in result["errors"]:
+                console.print(f"  [dim]{err}[/]")