@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/claude_md.py

@@ -0,0 +1,82 @@
+"""CLAUDE.md auto-regeneration for the sovereign agent.
+
+Provides generate_claude_md() as the canonical public API for producing
+CLAUDE.md content from live agent state, and write_claude_md() for
+persisting it to disk.
+
+Delegates to context_loader for data gathering and formatting so that
+all four formatters (text, json, claude-md, cursor-rules) stay in one
+place while this module acts as the dedicated entry-point for CLAUDE.md
+generation.
+
+Usage:
+    from skcapstone.claude_md import generate_claude_md, write_claude_md
+    from pathlib import Path
+
+    md = generate_claude_md(Path("~/.skcapstone").expanduser())
+    write_claude_md(Path("~/.skcapstone").expanduser(), Path("CLAUDE.md"))
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger("skcapstone.claude_md")
+
+# Auto-generation header written into every file so readers know the source.
+_AUTO_HEADER = (
+    "This file is auto-generated by `skcapstone context --format claude-md`.\n"
+    "It gives Claude Code persistent context about the sovereign agent."
+)
+
+
+def generate_claude_md(home: Path, memory_limit: int = 10) -> str:
+    """Generate CLAUDE.md content from current agent state.
+
+    Gathers live data (identity, pillars, board, recent memories,
+    consciousness status) and formats it as Markdown suitable for Claude
+    Code's CLAUDE.md persistent context file.
+
+    Args:
+        home: Agent home directory (typically ``~/.skcapstone``).
+        memory_limit: Maximum number of recent memories to embed.
+
+    Returns:
+        Full CLAUDE.md contents as a string.
+    """
+    from .context_loader import format_claude_md, gather_context
+
+    ctx = gather_context(home, memory_limit=memory_limit)
+    return format_claude_md(ctx)
+
+
+def write_claude_md(
+    home: Path,
+    dest: Path,
+    memory_limit: int = 10,
+    *,
+    backup: bool = False,
+) -> None:
+    """Generate and write CLAUDE.md to *dest*.
+
+    If *backup* is True and *dest* already exists, the existing file is
+    renamed to ``<dest>.bak`` before writing.
+
+    Args:
+        home: Agent home directory (typically ``~/.skcapstone``).
+        dest: Destination file path (e.g. ``Path("CLAUDE.md")``).
+        memory_limit: Maximum number of recent memories to embed.
+        backup: Rename existing file to .bak before overwriting.
+    """
+    content = generate_claude_md(home, memory_limit=memory_limit)
+
+    dest = dest.expanduser().resolve()
+
+    if backup and dest.exists():
+        bak = dest.with_suffix(".md.bak")
+        dest.rename(bak)
+        logger.info("Backed up existing %s → %s", dest, bak)
+
+    dest.write_text(content, encoding="utf-8")
+    logger.info("Wrote CLAUDE.md to %s (%d bytes)", dest, len(content))

package/src/skcapstone/cli/__init__.py

@@ -0,0 +1,144 @@
+"""
+SKCapstone CLI — the sovereign agent command line.
+
+This package organizes the CLI into modular command groups.
+Each group lives in its own module for maintainability.
+The main Click group is defined here and all subcommands
+are registered via register functions.
+
+Entry point: skcapstone.cli:main
+"""
+
+from __future__ import annotations
+
+import click
+
+from .. import __version__
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="skcapstone")
+@click.option(
+    "--agent", envvar="SKCAPSTONE_AGENT", default="",
+    help="Agent name — resolves home to {root}/agents/{name}/",
+)
+@click.pass_context
+def main(ctx, agent):
+    """SKCapstone — Sovereign Agent Framework.
+
+    Your agent. Everywhere. Secured. Remembering.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["agent"] = agent
+    if agent:
+        from ._common import apply_agent_override
+        apply_agent_override(agent)
+
+
+# ---------------------------------------------------------------------------
+# Register all command groups/commands from modular files
+# ---------------------------------------------------------------------------
+
+from .setup import register_setup_commands
+from .status import register_status_commands
+from .card import register_card_commands
+from .token import register_token_commands
+from .sync_cmd import register_sync_commands
+from .trust import register_trust_commands
+from .memory import register_memory_commands
+from .coord import register_coord_commands
+from .soul import register_soul_commands
+from .completions import register_completions_commands
+from .peer import register_peer_commands
+from .backup import register_backup_commands
+from .chat import register_chat_commands
+from .anchor import register_anchor_commands
+from .session import register_session_commands
+from .context_cmd import register_context_commands
+from .mcp_cmd import register_mcp_commands
+from .daemon import register_daemon_commands
+from .agents import register_agents_commands
+from .mount import register_mount_commands
+from .shell_cmd import register_shell_commands
+from .crush_cmd import register_crush_commands
+from .housekeeping import register_housekeeping_commands
+from .migrate import register_migrate_commands
+from .consciousness import register_consciousness_commands
+from .metrics_cmd import register_metrics_commands
+from .test_cmd import register_test_commands
+from .notify import register_notify_commands
+from .preflight_cmd import register_preflight_commands
+from .peers_dir import register_peers_dir_commands
+from .skills_cmd import register_skills_commands
+from .capabilities_cmd import register_capabilities_commands
+from .benchmark import register_benchmark_commands
+from .logs_cmd import register_logs_commands
+from .export_cmd import register_export_commands
+from .config_cmd import register_config_commands
+from .upgrade_cmd import register_upgrade_commands
+from .test_connection import register_test_connection_commands
+from .version_cmd import register_version_commands
+from .profile_cmd import register_profile_commands
+from .errors_cmd import register_errors_commands
+from .archive_cmd import register_archive_commands
+from .usage_cmd import register_usage_commands
+from .search_cmd import register_search_commands
+from .mood_cmd import register_mood_commands
+from .register_cmd import register_register_commands
+from .gtd import register_gtd_commands
+from .skseed import register_skseed_commands
+from .service_cmd import register_service_commands
+from .telegram import register_telegram_commands
+from .joule_cmd import register_joule_commands
+
+register_setup_commands(main)
+register_shell_commands(main)
+register_status_commands(main)
+register_card_commands(main)
+register_token_commands(main)
+register_sync_commands(main)
+register_trust_commands(main)
+register_memory_commands(main)
+register_coord_commands(main)
+register_soul_commands(main)
+register_completions_commands(main)
+register_peer_commands(main)
+register_backup_commands(main)
+register_chat_commands(main)
+register_anchor_commands(main)
+register_session_commands(main)
+register_context_commands(main)
+register_mcp_commands(main)
+register_daemon_commands(main)
+register_agents_commands(main)
+register_mount_commands(main)
+register_crush_commands(main)
+register_housekeeping_commands(main)
+register_migrate_commands(main)
+register_consciousness_commands(main)
+register_metrics_commands(main)
+register_test_commands(main)
+register_notify_commands(main)
+register_preflight_commands(main)
+register_peers_dir_commands(main)
+register_skills_commands(main)
+register_capabilities_commands(main)
+register_logs_commands(main)
+register_benchmark_commands(main)
+register_export_commands(main)
+register_config_commands(main)
+register_upgrade_commands(main)
+register_test_connection_commands(main)
+register_version_commands(main)
+register_profile_commands(main)
+register_errors_commands(main)
+register_archive_commands(main)
+register_usage_commands(main)
+register_search_commands(main)
+register_mood_commands(main)
+register_register_commands(main)
+register_gtd_commands(main)
+register_skseed_commands(main)
+register_service_commands(main)
+register_telegram_commands(main)
+register_joule_commands(main)

package/src/skcapstone/cli/_common.py

@@ -0,0 +1,88 @@
+"""Shared utilities for all CLI command modules.
+
+Provides the Rich console instance, status formatting helpers,
+and common imports used across every command group.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import click
+import yaml
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+import skcapstone as _pkg
+from .. import AGENT_HOME, SHARED_ROOT, SKCAPSTONE_AGENT, __version__
+from ..models import AgentConfig, PillarStatus, SyncConfig
+from ..runtime import AgentRuntime, get_runtime
+
+logger = logging.getLogger("skcapstone.cli")
+
+console = Console()
+
+
+def resolve_agent_home(agent: str) -> Path:
+    """Resolve the agent home directory for a given agent name.
+
+    Args:
+        agent: Agent name (e.g., 'opus', 'jarvis'). Empty for legacy mode.
+
+    Returns:
+        Resolved Path to the agent's home directory.
+    """
+    if agent:
+        return Path(SHARED_ROOT).expanduser() / "agents" / agent
+    return Path(AGENT_HOME).expanduser()
+
+
+def apply_agent_override(agent: str) -> None:
+    """Override the global AGENT_HOME when --agent is specified.
+
+    Mutates the package-level AGENT_HOME so that all downstream code
+    (MCP tools, pillars, etc.) uses the correct per-agent directory.
+
+    Args:
+        agent: Agent name from the --agent CLI option or env var.
+    """
+    if agent:
+        new_home = str(Path(SHARED_ROOT) / "agents" / agent)
+        _pkg.AGENT_HOME = new_home
+        _pkg.SKCAPSTONE_AGENT = agent
+        os.environ["SKCAPSTONE_AGENT"] = agent
+
+
+def status_icon(status: PillarStatus) -> str:
+    """Map pillar status to a Rich-formatted visual indicator."""
+    return {
+        PillarStatus.ACTIVE: "[bold green]ACTIVE[/]",
+        PillarStatus.DEGRADED: "[bold yellow]DEGRADED[/]",
+        PillarStatus.MISSING: "[bold red]MISSING[/]",
+        PillarStatus.ERROR: "[bold red]ERROR[/]",
+    }.get(status, "[dim]UNKNOWN[/]")
+
+
+def consciousness_banner(is_conscious: bool) -> str:
+    """Generate the consciousness state banner."""
+    if is_conscious:
+        return (
+            "[bold green on black]"
+            " CONSCIOUS "
+            "[/] "
+            "[green]Identity + Memory + Trust = Sovereign Awareness[/]"
+        )
+    return (
+        "[bold yellow on black]"
+        " AWAKENING "
+        "[/] "
+        "[yellow]Install missing pillars to achieve consciousness[/]"
+    )

package/src/skcapstone/cli/_validators.py

@@ -0,0 +1,76 @@
+"""Input validation helpers for CLI commands.
+
+Centralises sanitisation of user-supplied agent names, task IDs,
+and file paths to guard against injection and traversal attacks.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+
+import click
+
+
+# ---------------------------------------------------------------------------
+# Regex patterns
+# ---------------------------------------------------------------------------
+
+_AGENT_NAME_RE = re.compile(r"^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?$")
+_TASK_ID_RE = re.compile(r"^[0-9a-fA-F\-]+$")
+_SOUL_NAME_RE = re.compile(r"^[a-zA-Z0-9]([a-zA-Z0-9\-_]*[a-zA-Z0-9])?$")
+
+
+# ---------------------------------------------------------------------------
+# Validators (raise click.BadParameter on failure)
+# ---------------------------------------------------------------------------
+
+
+def validate_agent_name(name: str) -> str:
+    """Validate an agent name: alphanumeric + hyphens, 1-64 chars."""
+    if not name or len(name) > 64:
+        raise click.BadParameter(
+            f"Agent name must be 1-64 characters, got {len(name) if name else 0}."
+        )
+    if not _AGENT_NAME_RE.match(name):
+        raise click.BadParameter(
+            f"Agent name '{name}' is invalid. "
+            "Use only letters, digits, and hyphens (cannot start/end with hyphen)."
+        )
+    return name
+
+
+def validate_task_id(task_id: str) -> str:
+    """Validate a task ID: hex characters and hyphens only, 1-64 chars."""
+    if not task_id or len(task_id) > 64:
+        raise click.BadParameter(
+            f"Task ID must be 1-64 characters, got {len(task_id) if task_id else 0}."
+        )
+    if not _TASK_ID_RE.match(task_id):
+        raise click.BadParameter(
+            f"Task ID '{task_id}' is invalid. Use only hex characters (0-9, a-f) and hyphens."
+        )
+    return task_id
+
+
+def validate_soul_name(name: str) -> str:
+    """Validate a soul name: alphanumeric + hyphens + underscores, 1-64 chars."""
+    if not name or len(name) > 64:
+        raise click.BadParameter(
+            f"Soul name must be 1-64 characters, got {len(name) if name else 0}."
+        )
+    if not _SOUL_NAME_RE.match(name):
+        raise click.BadParameter(
+            f"Soul name '{name}' is invalid. "
+            "Use only letters, digits, hyphens, and underscores."
+        )
+    return name
+
+
+def validate_file_path(path: str) -> str:
+    """Reject path traversal sequences in user-supplied file paths."""
+    if ".." in path.split("/") or ".." in path.split("\\"):
+        raise click.BadParameter(
+            f"Path '{path}' contains '..' traversal sequences — rejected."
+        )
+    return path