core-runtime 0.1.1__py3-none-any.whl

cli/logic/byor.py

@@ -0,0 +1,148 @@
+# src/cli/logic/byor.py
+
+"""
+Implements the 'byor-init' command to analyze external repositories and scaffold minimal CORE governance structures.
+
+CONSTITUTIONAL FIX:
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Centralizes mutation logic via the Body layer for auditability.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+
+from shared.infrastructure.knowledge_graph_service import KnowledgeGraphBuilder
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+CORE_ROOT = Path(__file__).resolve().parents[2]
+TEMPLATES_DIR = (
+    CORE_ROOT / "src" / "features" / "project_lifecycle" / "starter_kits" / "default"
+)
+
+
+# ID: 8b2ee927-9c35-4125-b291-22669733e531
+def initialize_repository(
+    path: Path = typer.Argument(
+        ...,
+        help="The path to the external repository to analyze.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    dry_run: bool = typer.Option(
+        True,
+        "--dry-run/--write",
+        help="Show the proposed .intent/ scaffold without writing files. Use --write to apply.",
+    ),
+):
+    """
+    Analyzes an external repository and scaffolds a minimal `.intent/` constitution.
+    """
+    logger.info("🚀 Starting analysis of repository at: %s", path)
+    logger.info("   -> Step 1: Building Knowledge Graph of the target repository...")
+    try:
+        builder = KnowledgeGraphBuilder(root_path=path)
+        graph = builder.build()
+        total_symbols = len(graph.get("symbols", {}))
+        logger.info(
+            "   -> ✅ Knowledge Graph built successfully. Found %s symbols.",
+            total_symbols,
+        )
+    except Exception as e:
+        logger.error("   -> ❌ Failed to build Knowledge Graph: %s", e, exc_info=True)
+        raise typer.Exit(code=1)
+
+    logger.info("   -> Step 2: Generating starter constitution from analysis...")
+    domains = builder.domain_map
+    source_structure_content = {
+        "structure": [
+            {
+                "domain": name,
+                "path": path_str,
+                "description": f"Domain for '{name}' inferred by CORE.",
+                "allowed_imports": [name, "shared"],
+            }
+            for path_str, name in domains.items()
+        ]
+    }
+    discovered_capabilities = sorted(
+        list(
+            set(
+                s["capability"]
+                for s in graph.get("symbols", {}).values()
+                if s.get("capability") != "unassigned"
+            )
+        )
+    )
+    project_manifest_content = {
+        "name": path.name,
+        "version": "0.1.0-core-scaffold",
+        "intent": "A high-level description of what this project is intended to do.",
+        "required_capabilities": discovered_capabilities,
+    }
+
+    # Pre-flight check on template availability
+    tag_template_path = TEMPLATES_DIR / "capability_tags.yaml.template"
+    if not tag_template_path.exists():
+        logger.warning("Template missing: %s", tag_template_path)
+
+    capability_tags_content = {
+        "tags": [
+            {
+                "name": cap,
+                "description": "A clear explanation of what this capability does.",
+            }
+            for cap in discovered_capabilities
+        ]
+    }
+
+    files_to_generate = {
+        ".intent/knowledge/source_structure.yaml": source_structure_content,
+        ".intent/project_manifest.yaml": project_manifest_content,
+        ".intent/knowledge/capability_tags.yaml": capability_tags_content,
+        ".intent/mission/principles.yaml": (
+            TEMPLATES_DIR / "principles.yaml"
+        ).read_text(encoding="utf-8"),
+        ".intent/policies/safety_policies.yaml": (
+            TEMPLATES_DIR / "safety_policies.yaml"
+        ).read_text(encoding="utf-8"),
+    }
+
+    if dry_run:
+        logger.info("\n💧 Dry Run Mode: No files will be written.")
+        for rel_path, content in files_to_generate.items():
+            typer.secho(f"\n📄 Proposed `{rel_path}`:", fg=typer.colors.YELLOW)
+            if isinstance(content, dict):
+                typer.echo(yaml.dump(content, indent=2, sort_keys=False))
+            else:
+                typer.echo(content)
+    else:
+        logger.info("\n💾 **Write Mode:** Applying changes to disk.")
+
+        fh = FileHandler(str(path))
+
+        for rel_path, content in files_to_generate.items():
+            if isinstance(content, dict):
+                output_content = yaml.dump(content, indent=2, sort_keys=False)
+            else:
+                output_content = content
+
+            try:
+                # Use governed mutation surface instead of Path.write_text
+                fh.write_runtime_text(rel_path, output_content)
+                typer.secho(
+                    f"   -> ✅ Wrote starter file: {rel_path}", fg=typer.colors.GREEN
+                )
+            except Exception as e:
+                logger.error("   -> ❌ Failed to write %s: %s", rel_path, e)
+
+    logger.info("\n🎉 BYOR initialization complete.")

cli/logic/capability.py

@@ -0,0 +1,27 @@
+# src/cli/logic/capability.py
+"""
+Provides the 'core-admin capability' command group for managing capabilities
+in a constitutionally-aligned way. THIS MODULE IS NOW DEPRECATED and will be
+removed after the DB-centric migration is complete.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+
+
+logger = logging.getLogger(__name__)
+
+capability_app = typer.Typer(help="[DEPRECATED] Create and manage capabilities.")
+
+
+@capability_app.command("new")
+# ID: c2111920-a102-52e0-b8f5-1278411d4bae
+def capability_new_deprecated():
+    """[DEPRECATED] This command is now obsolete. Use 'knowledge sync' instead."""
+    logger.warning("This command is deprecated and will be removed.")
+    logger.info(
+        "Please use 'poetry run core-admin knowledge sync' to synchronize symbols."
+    )

cli/logic/cli_utils.py

@@ -0,0 +1,210 @@
+# src/cli/logic/cli_utils.py
+"""
+Provides centralized, reusable utilities for standardizing the console output
+and execution of all `core-admin` commands.
+
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Enforces IntentGuard and audit logging for all CLI helper operations.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import typer
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.infrastructure.storage.file_handler import FileHandler
+
+logger = getLogger(__name__)
+
+# Directories we should not traverse when doing broad filesystem scans.
+_DEFAULT_EXCLUDE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "build",
+    "site",
+    ".venv",
+    "venv",
+    ".tox",
+}
+
+
+def _is_excluded_dir(path: str) -> bool:
+    parts = {p for p in Path(path).parts if p}
+    return bool(parts & _DEFAULT_EXCLUDE_DIRS)
+
+
+async def _find_test_file_for_capability_async(
+    capability_name: str,
+    search_paths: list[str] | None = None,
+) -> Path | None:
+    """
+    Asynchronously find a test file associated with a given capability name.
+    """
+    if search_paths is None:
+        search_paths = ["tests", "test", "src/tests"]
+
+    capability_lower = capability_name.lower()
+
+    patterns = {
+        f"test_{capability_name}.py",
+        f"{capability_name}_test.py",
+        f"test{capability_name}.py",
+    }
+
+    for base in search_paths:
+        base_path = Path(base)
+        if not base_path.exists():
+            continue
+
+        for root, _dirs, files in os.walk(base_path):
+            if _is_excluded_dir(root):
+                continue
+
+            for pattern in patterns:
+                if pattern in files:
+                    return Path(root) / pattern
+
+            for filename in files:
+                if not filename.endswith(".py"):
+                    continue
+                if capability_lower in filename.lower():
+                    return Path(root) / filename
+
+    return None
+
+
+# ID: fe11b579-66f5-4aaf-bd91-636ce01604ad
+def find_source_file(
+    symbol_name: str,
+    search_paths: list[str] | None = None,
+) -> Path | None:
+    """
+    Find the source file containing a given symbol.
+    """
+    if search_paths is None:
+        search_paths = ["src", "lib"]
+
+    def_markers = (f"def {symbol_name}", f"class {symbol_name}")
+
+    for base in search_paths:
+        base_path = Path(base)
+        if not base_path.exists():
+            continue
+
+        for root, _dirs, files in os.walk(base_path):
+            if "test" in root.lower():
+                continue
+            if _is_excluded_dir(root):
+                continue
+
+            for filename in files:
+                if not filename.endswith(".py"):
+                    continue
+
+                file_path = Path(root) / filename
+                try:
+                    with file_path.open("r", encoding="utf-8") as f:
+                        for line in f:
+                            if def_markers[0] in line or def_markers[1] in line:
+                                return file_path
+                except (OSError, UnicodeDecodeError) as e:
+                    logger.debug("Error reading %s: %s", file_path, e, exc_info=True)
+                    continue
+
+    return None
+
+
+# ID: a3d61adf-6e42-4854-a028-89a73d47c667
+def save_yaml_file(path: Path, data: dict[str, Any], file_handler: FileHandler) -> None:
+    """Saves data to a YAML file via the governed FileHandler."""
+    import yaml
+
+    try:
+        rel_path = str(path.resolve().relative_to(file_handler.repo_path.resolve()))
+        content = yaml.dump(data, sort_keys=True)
+        file_handler.write_runtime_text(rel_path, content)
+    except ValueError:
+        logger.error(
+            "Attempted to save YAML file outside repository boundary: %s", path
+        )
+        raise
+
+
+# ID: 4e814eab-bdc4-4d68-b13e-8c4c53269a68
+def load_private_key(repo_root: Path) -> ed25519.Ed25519PrivateKey:
+    """
+    Loads the operator's private key.
+    Requires repo_root to locate var/keys/private.key without global settings.
+    """
+    key_path = repo_root / "var" / "keys" / "private.key"
+    if not key_path.exists():
+        logger.error(
+            "Private key not found at %s. Please run 'core-admin manage keys generate' to create one.",
+            key_path,
+        )
+        raise typer.Exit(code=1)
+    return serialization.load_pem_private_key(key_path.read_bytes(), password=None)
+
+
+# ID: f803faac-7a8d-40b1-84cb-659379a4b512
+def archive_rollback_plan(
+    proposal_name: str,
+    proposal: dict[str, Any],
+    file_handler: FileHandler,
+) -> None:
+    """Archives a proposal's rollback plan via the governed FileHandler."""
+    rollback_plan = proposal.get("rollback_plan")
+    if not rollback_plan:
+        return
+
+    rel_rollbacks_dir = "var/mind/rollbacks"
+    file_handler.ensure_dir(rel_rollbacks_dir)
+
+    timestamp = datetime.utcnow().strftime("%Y%m%d%H%M%S")
+    archive_filename = f"{timestamp}-{proposal_name}.json"
+    rel_archive_path = f"{rel_rollbacks_dir}/{archive_filename}"
+
+    payload = {
+        "proposal_name": proposal_name,
+        "target_path": proposal.get("target_path"),
+        "justification": proposal.get("justification"),
+        "rollback_plan": rollback_plan,
+    }
+
+    file_handler.write_runtime_json(rel_archive_path, payload)
+    logger.info("Rollback plan archived to %s", rel_archive_path)
+
+
+# ID: 0babc74d-bd4e-4cbd-8cd6-bc955b32967e
+def should_fail(report: dict[str, Any], fail_on: str) -> bool:
+    """
+    Determines if the CLI should exit with an error code based on drift.
+    """
+    missing_in_code = bool(report.get("missing_in_code"))
+    undeclared_in_manifest = bool(report.get("undeclared_in_manifest"))
+    mismatched_mappings = bool(report.get("mismatched_mappings"))
+
+    if fail_on == "missing":
+        return missing_in_code
+    if fail_on == "undeclared":
+        return undeclared_in_manifest
+
+    return missing_in_code or undeclared_in_manifest or mismatched_mappings

cli/logic/context.py

@@ -0,0 +1,7 @@
+# src/cli/logic/context.py
+"""
+This module is being phased out in favor of direct context injection in admin_cli.py.
+It is kept for backward compatibility during the transition.
+"""
+
+from __future__ import annotations

cli/logic/db.py

@@ -0,0 +1,154 @@
+# src/cli/logic/db.py
+
+"""
+Registers the top-level 'db' command group for managing the CORE operational database.
+
+- Aligned with 'governance.artifact_mutation.traceable'.
+- Replaced direct Path writes with governed FileHandler mutations.
+- Redirected Mind-layer exports to the 'var/' runtime directory to maintain
+  the read-only boundary of '.intent/'.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+import yaml
+from sqlalchemy import text
+
+from shared.context import CoreContext
+from shared.infrastructure.database.session_manager import get_session
+from shared.infrastructure.storage.file_handler import FileHandler
+from shared.logger import getLogger
+from shared.path_resolver import PathResolver
+
+from .sync_domains import sync_domains
+
+
+logger = getLogger(__name__)
+db_app = typer.Typer(
+    help="Commands for managing the CORE operational database (migrations, syncs, status, exports)."
+)
+
+
+async def _export_domains(file_handler: FileHandler):
+    """Fetches domains from the DB and writes them to the runtime knowledge directory."""
+    logger.info("Exporting `core.domains` to YAML...")
+    async with get_session() as session:
+        result = await session.execute(
+            text(
+                "SELECT key as name, title, description FROM core.domains ORDER BY key"
+            )
+        )
+        domains_data = [dict(row._mapping) for row in result]
+
+    # The Body layer must never write directly to the Constitution.
+    yaml_content = {"version": 2, "domains": domains_data}
+    content_str = yaml.dump(yaml_content, indent=2, sort_keys=False)
+
+    # Resolve the relative path under the project root
+    # Note: var/mind/knowledge/ is the canonical home for runtime knowledge artifacts.
+    rel_path = "var/mind/knowledge/domains.yaml"
+
+    # Governed write: checks IntentGuard and logs the action
+    file_handler.write_runtime_text(rel_path, content_str)
+
+    logger.info(
+        "Wrote %s domains to %s",
+        len(domains_data),
+        rel_path,
+    )
+
+
+async def _export_vector_metadata(file_handler: FileHandler, repo_root: Path):
+    """Fetches vector metadata from the DB and writes it to a report."""
+    logger.info("Exporting vector metadata from database to YAML...")
+    async with get_session() as session:
+        result = await session.execute(
+            text(
+                "\n                SELECT s.id as uuid, s.symbol_path, l.vector_id\n                FROM core.symbols s\n                JOIN core.symbol_vector_links l ON s.id = l.symbol_id\n                ORDER BY s.symbol_path;\n                "
+            )
+        )
+        vector_data = []
+        for row in result:
+            row_dict = dict(row._mapping)
+            if "uuid" in row_dict and row_dict["uuid"] is not None:
+                row_dict["uuid"] = str(row_dict["uuid"])
+            if "vector_id" in row_dict and row_dict["vector_id"] is not None:
+                row_dict["vector_id"] = str(row_dict["vector_id"])
+            vector_data.append(row_dict)
+
+    content_str = yaml.dump(vector_data, indent=2, sort_keys=False)
+    rel_path = str(
+        (
+            PathResolver.from_repo(repo_root).reports_dir
+            / "vector_metadata_export.yaml"
+        ).relative_to(repo_root)
+    )
+
+    file_handler.write_runtime_text(rel_path, content_str)
+
+    logger.info(
+        "Wrote metadata for %s vectors to %s",
+        len(vector_data),
+        rel_path,
+    )
+
+
+@db_app.command(
+    "export", help="Export operational data from the database to read-only files."
+)
+# ID: 86554413-b670-4c62-80eb-31bab9a05edf
+async def export_data(ctx: typer.Context) -> None:
+    """Exports DB tables to their canonical, read-only YAML file representations."""
+    core_context: CoreContext = ctx.obj
+    logger.info("Exporting operational data from Database to files...")
+
+    # Create the governed mutation surface
+    file_handler = FileHandler(str(core_context.git_service.repo_path))
+
+    await _export_domains(file_handler)
+    await _export_vector_metadata(file_handler, core_context.git_service.repo_path)
+    logger.info("Export complete.")
+
+
+db_app.command("sync-domains")(sync_domains)
+
+
+@db_app.command("migrate")
+# ID: e8d94b4b-0257-4b03-8c83-03f04d8fb2a8
+async def migrate_db_command(
+    apply: bool = typer.Option(
+        False, "--apply", help="(Currently inert — framework is dormant.)"
+    ),
+) -> None:
+    """Show the current migration-framework status (currently dormant).
+
+    The repo operates under a schema-as-truth model — `infra/sql/db_schema_live.sql`
+    is the canonical schema. One-off SQL files under `infra/scripts/migrations/`
+    are historical record and are NOT replayed through this CLI. See #438.
+    """
+    _ = apply  # currently unused; kept for forward-compat
+    from rich.console import Console
+
+    _console = Console()
+    _console.print()
+    _console.print("[yellow]⏸  Migration framework is currently dormant.[/yellow]")
+    _console.print()
+    _console.print("Schema-as-truth model is in effect:")
+    _console.print("  • Canonical schema:  [cyan]infra/sql/db_schema_live.sql[/cyan]")
+    _console.print(
+        "  • Regenerate via:    [cyan]pg_dump --schema-only --schema=core[/cyan]"
+    )
+    _console.print(
+        "  • One-off SQL files: [cyan]infra/scripts/migrations/[/cyan] (historical record)"
+    )
+    _console.print()
+    _console.print(
+        "This command will be revived if ledger-based migrations are reintroduced."
+    )
+    _console.print("See #438 for the framework-orphan history.")
+
+
+db_app.command("migrate")(migrate_db_command)

cli/logic/db_manage.py

@@ -0,0 +1,22 @@
+# src/cli/logic/db_manage.py
+"""Provides functionality for the db_manage module."""
+
+from __future__ import annotations
+
+import typer
+
+from .db import app as db_app
+from .db import app as knowledge_db_app
+
+
+# Top-level Typer app exposed by this module
+app = typer.Typer(help="Database management meta-commands")
+
+# Mount groups
+app.add_typer(db_app, name="db")
+
+knowledge_app = typer.Typer(help="Knowledge operations")
+knowledge_app.add_typer(knowledge_db_app, name="db")
+app.add_typer(knowledge_app, name="knowledge")
+
+__all__ = ["app"]

cli/logic/decision_inspect_logic.py

@@ -0,0 +1,62 @@
+# src/cli/logic/decision_inspect_logic.py
+"""
+Logic specialist for inspecting autonomous decision traces.
+Handles database queries and Rich-table formatting.
+"""
+
+from __future__ import annotations
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+from rich.console import Console
+from rich.table import Table
+
+from body.infrastructure.repositories.decision_trace_repository import (
+    DecisionTraceRepository,
+)
+
+
+console = Console()
+
+
+# ID: 832820bd-1e00-453b-979c-5ad702814e25
+async def show_session_trace_logic(
+    repo: DecisionTraceRepository, session_id: str, details: bool
+):
+    """Deep inspection of a single session."""
+    trace = await repo.get_by_session_id(session_id)
+    if not trace:
+        console.print(f"[yellow]No trace found for session: {session_id}[/yellow]")
+        return
+    console.print(f"\n[bold cyan]Session: {trace.session_id}[/bold cyan]")
+    logger.info("Agent: %s | Decisions: %s", trace.agent_name, trace.decision_count)
+    if details:
+        for i, d in enumerate(trace.decisions or [], 1):
+            console.print(
+                f"\n[cyan]{i}. {d.get('agent')} - {d.get('decision_type')}[/cyan]"
+            )
+            logger.info("   Rationale: %s", d.get("rationale"))
+
+
+# ID: 3818285c-c8c9-4727-8792-d47371ee64f3
+async def list_recent_traces_logic(
+    repo: DecisionTraceRepository, limit: int, agent: str | None, failures_only: bool
+):
+    """Builds a summary table of recent decisions."""
+    traces = await repo.get_recent(
+        limit=limit, agent_name=agent, failures_only=failures_only
+    )
+    if not traces:
+        console.print("[yellow]No traces found.[/yellow]")
+        return
+    table = Table(title=f"Recent Decision Traces ({len(traces)})")
+    table.add_column("Session", style="cyan")
+    table.add_column("Agent", style="green")
+    table.add_column("Decisions", justify="right")
+    table.add_column("Status")
+    for t in traces:
+        status = "❌ Violations" if t.has_violations == "true" else "✅ Clean"
+        table.add_row(t.session_id[:12], t.agent_name, str(t.decision_count), status)
+    console.print(table)