clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/commands/tridb_cmd.py

@@ -0,0 +1,319 @@
+"""Tri-Database Subcommand Handlers.
+
+Sprint 412 / DEL-412-04.
+Normative Spec: docs/spec/30-interfaces/universal_subcommand_grammar.md §2.3 - §2.6
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.utils import resolve_clm_path
+from clm.layer2.storage import (
+    CLMDB,
+    init_tridb,
+    memorize_mcard,
+    register_handle,
+    resolve_handle_content,
+    resolve_handle_hash,
+)
+from clm.layer4.commands.envelope import format_error, format_failure, format_success
+
+_logger = get_logger("clm.layer4.commands.tridb")
+
+
+def init_tridb_cmd(args: list[str]) -> int:
+    """Handle 'init-tridb' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm init-tridb [--memory] [--path <dir>] [--json]")
+        return 0
+
+    as_json = "--json" in args
+    is_memory = "--memory" in args
+    target_path: str | None = None
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--path":
+            if i + 1 >= len(args):
+                if as_json:
+                    print(format_error("MISSING_ARG", "Option --path requires a directory argument"))
+                else:
+                    print("Error: Option --path requires a directory argument", file=sys.stderr)
+                return 2
+            target_path = args[i + 1]
+            i += 2
+        else:
+            i += 1
+
+    if target_path is not None:
+        if not os.path.exists(target_path):
+            try:
+                os.makedirs(target_path, exist_ok=True)
+            except Exception as e:
+                if as_json:
+                    print(format_error("INVALID_PATH", f"Cannot access path: {target_path} ({e})"))
+                else:
+                    print(f"Error: Invalid directory path: {target_path} ({e})", file=sys.stderr)
+                return 2
+
+    clm_root = target_path or os.environ.get("CLM_ROOT") or os.getcwd()
+    if is_memory:
+        os.environ["CLM_ZERO_FS"] = "1"
+
+    try:
+        rc = init_tridb(clm_root)
+        if rc == 0:
+            if as_json:
+                data = {
+                    "pillars": ["agent_identities", "content_memory", "execution_log"],
+                    "path": clm_root,
+                    "memory": is_memory,
+                    "initialized": True,
+                }
+                print(format_success(data))
+            return 0
+        else:
+            if as_json:
+                print(format_failure("TRIDB_INIT_FAILED", "Database initialization returned non-zero code"))
+            return 1
+    except Exception as e:
+        if as_json:
+            print(format_failure("TRIDB_INIT_EXCEPTION", str(e)))
+        else:
+            _logger.error(f"Failed to initialize Tri-Database: {e}")
+        return 1
+
+
+def memorize_mcard_cmd(args: list[str]) -> int:
+    """Handle 'memorize-mcard' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm memorize-mcard <file> [--pillar <name>] [--handle <name>] [--json]")
+        return 0
+
+    as_json = "--json" in args
+    clean_args = [a for a in args if a != "--json"]
+
+    pillar = "auto"
+    handle: str | None = None
+    pos_args: list[str] = []
+
+    i = 0
+    while i < len(clean_args):
+        if clean_args[i] == "--pillar" and i + 1 < len(clean_args):
+            pillar = clean_args[i + 1]
+            i += 2
+        elif clean_args[i] == "--handle" and i + 1 < len(clean_args):
+            handle = clean_args[i + 1]
+            i += 2
+        elif clean_args[i].startswith("--"):
+            i += 1
+        else:
+            pos_args.append(clean_args[i])
+            i += 1
+
+    if not pos_args:
+        if as_json:
+            print(format_error("MISSING_ARG", "Usage: memorize-mcard <file> [pillar]"))
+        else:
+            print("Usage: memorize-mcard <file> [pillar]", file=sys.stderr)
+        return 2
+
+    file_path = pos_args[0]
+    if len(pos_args) > 1 and pillar == "auto":
+        pillar = pos_args[1]
+
+    clm_root = os.environ.get("CLM_ROOT") or os.getcwd()
+    resolved_path = resolve_clm_path(clm_root, file_path)
+
+    if not os.path.exists(resolved_path):
+        if as_json:
+            print(format_error("FILE_NOT_FOUND", f"File not found: {file_path}"))
+        else:
+            print(f"File not found: {file_path}", file=sys.stderr)
+        return 2
+
+    try:
+        rc = memorize_mcard(clm_root, resolved_path, pillar)
+        if handle and rc in (0, 2):
+            register_handle(clm_root, handle, resolved_path)
+
+        if rc in (0, 2):
+            if as_json:
+                from clm.layer0.hash import compute_blake3
+                with open(resolved_path, "rb") as f:
+                    h = compute_blake3(f.read())
+                sz = os.path.getsize(resolved_path)
+                data = {
+                    "hash": h,
+                    "bytes": sz,
+                    "handle": handle,
+                    "pillar": pillar,
+                }
+                print(format_success(data))
+            return 0 if as_json else rc
+        else:
+            if as_json:
+                print(format_failure("STORAGE_ERROR", f"Failed to memorize {file_path}"))
+            return 1
+    except Exception as e:
+        if as_json:
+            print(format_failure("STORAGE_EXCEPTION", str(e)))
+        else:
+            _logger.error(f"Error memorizing card {file_path}: {e}")
+        return 1
+
+
+def resolve_handle_cmd(args: list[str]) -> int:
+    """Handle 'resolve-handle' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm resolve-handle <handle> [--pillar <name>] [--hash-only] [--json]")
+        return 0
+
+    as_json = "--json" in args
+    hash_only = "--hash-only" in args
+    clean_args = [a for a in args if a not in ("--json", "--hash-only")]
+
+    pillar = "content_memory"
+    pos_args: list[str] = []
+
+    i = 0
+    while i < len(clean_args):
+        if clean_args[i] == "--pillar" and i + 1 < len(clean_args):
+            pillar = clean_args[i + 1]
+            i += 2
+        elif clean_args[i].startswith("--"):
+            i += 1
+        else:
+            pos_args.append(clean_args[i])
+            i += 1
+
+    if not pos_args:
+        if as_json:
+            print(format_error("MISSING_ARG", "Usage: resolve-handle <handle> [pillar]"))
+        else:
+            print("Usage: resolve-handle <handle> [pillar]", file=sys.stderr)
+        return 2
+
+    handle = pos_args[0]
+    if len(pos_args) > 1:
+        pillar = pos_args[1]
+
+    clm_root = os.environ.get("CLM_ROOT") or os.getcwd()
+    try:
+        h = resolve_handle_hash(clm_root, handle, pillar)
+        if not h:
+            if as_json:
+                print(format_failure("HANDLE_NOT_FOUND", f"Handle '{handle}' not found in pillar '{pillar}'"))
+            else:
+                print(f"Handle '{handle}' not found in pillar '{pillar}'", file=sys.stderr)
+            return 1
+
+        content = resolve_handle_content(clm_root, handle, pillar)
+        if as_json:
+            print(format_success({"handle": handle, "hash": h, "content": content, "pillar": pillar}))
+        elif hash_only:
+            print(h)
+        else:
+            print(content)
+        return 0
+    except Exception as e:
+        if as_json:
+            print(format_failure("RESOLVE_EXCEPTION", str(e)))
+        else:
+            _logger.error(f"Error resolving handle '{handle}': {e}")
+        return 1
+
+
+def resolve_handle_hash_cmd(args: list[str]) -> int:
+    """Handle 'resolve-handle-hash' subcommand (backward compatibility)."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm resolve-handle-hash <handle> [pillar]")
+        return 0
+
+    if not args:
+        print("Usage: resolve-handle-hash <handle> [pillar]", file=sys.stderr)
+        return 2
+
+    handle = args[0]
+    pillar = args[1] if len(args) > 1 else "content_memory"
+    clm_root = os.environ.get("CLM_ROOT") or os.getcwd()
+    try:
+        h = resolve_handle_hash(clm_root, handle, pillar)
+        print(h)
+        return 0
+    except Exception as e:
+        _logger.error(f"Error resolving handle hash: {e}")
+        return 1
+
+
+def register_handle_cmd(args: list[str]) -> int:
+    """Handle 'register-handle' subcommand (backward compatibility)."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm register-handle <handle> <content_source>")
+        return 0
+
+    if len(args) < 2:
+        print("Usage: register-handle <handle> <content_source>", file=sys.stderr)
+        return 2
+
+    handle = args[0]
+    source = args[1]
+    clm_root = os.environ.get("CLM_ROOT") or os.getcwd()
+    try:
+        return register_handle(clm_root, handle, source)
+    except Exception as e:
+        _logger.error(f"Error registering handle: {e}")
+        return 1
+
+
+def sql_cmd(args: list[str]) -> int:
+    """Handle 'sql' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm sql <pillar> <sql_query> [params...] [--json]")
+        return 0
+
+    as_json = "--json" in args
+    clean_args = [a for a in args if a != "--json"]
+
+    if len(clean_args) < 2:
+        if as_json:
+            print(format_error("MISSING_ARG", "Usage: sql <pillar> <sql_query> [params...]"))
+        else:
+            print("Usage: sql <pillar> <sql_query> [params...]", file=sys.stderr)
+        return 2
+
+    pillar = clean_args[0]
+    query = clean_args[1]
+    params = clean_args[2:] if len(clean_args) > 2 else None
+
+    known_pillars = {"content_memory", "execution_log", "agent_identities"}
+    if pillar not in known_pillars:
+        if as_json:
+            print(format_error("INVALID_PILLAR", f"Unknown pillar '{pillar}', expected one of {sorted(known_pillars)}"))
+        else:
+            print(f"Unknown pillar '{pillar}', expected one of {sorted(known_pillars)}", file=sys.stderr)
+        return 2
+
+    clm_root = os.environ.get("CLM_ROOT") or os.getcwd()
+    try:
+        db = CLMDB(clm_root)
+        raw_res = db.execute(pillar, query, params, as_json)
+        if as_json:
+            try:
+                parsed = json.loads(raw_res) if isinstance(raw_res, str) else raw_res
+                print(format_success(parsed))
+            except Exception:
+                print(format_success(raw_res))
+        else:
+            print(raw_res)
+        return 0
+    except Exception as e:
+        if as_json:
+            print(format_failure("SQL_ERROR", str(e)))
+        else:
+            _logger.error(f"SQL execution error: {e}")
+        return 1

clm/layer4/commands/version_cmd.py

@@ -0,0 +1,27 @@
+"""Version Subcommand Handler.
+
+Sprint 412 / DEL-412-04.
+Normative Spec: docs/spec/30-interfaces/universal_subcommand_grammar.md §2.12
+"""
+
+from __future__ import annotations
+
+from clm.layer4.commands.envelope import format_success
+
+
+def version_cmd(args: list[str]) -> int:
+    """Handle 'version' subcommand."""
+    as_json = "--json" in args
+    version_info = {
+        "runtime": "python",
+        "version": "0.4.0",
+        "layers": [0, 1, 2, 3, 4, 5],
+        "blake3": True,
+        "features": ["cpn_vm", "baldwin_algebra", "pocketflow", "satori", "continuous_learning"],
+    }
+
+    if as_json:
+        print(format_success(version_info))
+    else:
+        print("clm (runtime: python, version: 0.4.0, layers: [0, 1, 2, 3, 4, 5], blake3: true)")
+    return 0

clm/layer4/diff_commands.py

@@ -0,0 +1,167 @@
+"""CLI Subcommands for MCard Diffing and Merkle Lineage (Sprint 396 / DEL-396-01).
+
+Provides:
+- clm mcard diff <uri1> <uri2> [--json]
+- clm mcard lineage <uri> [--mermaid] [--dot] [--json]
+
+Acceptance Criteria:
+- AC-396-01-04: clm mcard diff prints structured diff (columns/keys added, removed, modified).
+- Lineage tree visualizer prints ASCII or Mermaid provenance.
+
+Layer 4 module.
+"""
+
+from __future__ import annotations
+
+import csv
+import difflib
+import io
+import json
+from typing import Any
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer2.ingest import get_default_fs
+from clm.layer2.lineage import get_mcard_lineage
+from clm.layer2.mcard_fs import MCardFileSystem
+
+_logger = get_logger("clm.layer4.diff_commands")
+
+
+def _clean_uri(uri: str) -> str:
+    if uri.startswith("mcard://"):
+        return "mcard:" + uri[len("mcard://"):]
+    return uri
+
+
+def mcard_diff_cmd(
+    uri1: str,
+    uri2: str,
+    as_json: bool = False,
+    fs: MCardFileSystem | None = None,
+) -> int:
+    """Compute and display structural and semantic diff between two MCards."""
+    target_fs = fs or get_default_fs()
+    try:
+        card1 = target_fs.read_file(_clean_uri(uri1))
+        card2 = target_fs.read_file(_clean_uri(uri2))
+    except Exception as e:
+        _logger.error(f"Failed to read MCard for diff: {e}")
+        return 1
+
+    diff_report: dict[str, Any] = {
+        "uri1": uri1,
+        "uri2": uri2,
+        "hash_match": str(getattr(card1, "hash", None)) == str(getattr(card2, "hash", None)),
+        "metadata_diff": {},
+        "content_diff": {},
+    }
+
+    # 1. Metadata diff
+    meta1 = card1.metadata or {}
+    meta2 = card2.metadata or {}
+    all_keys = set(meta1.keys()).union(set(meta2.keys()))
+    for k in sorted(all_keys):
+        v1 = meta1.get(k)
+        v2 = meta2.get(k)
+        if v1 != v2:
+            diff_report["metadata_diff"][k] = {"card1": v1, "card2": v2}
+
+    # 2. Content diff
+    p1 = card1.payload
+    p2 = card2.payload
+
+    if isinstance(p1, str) and isinstance(p2, str):
+        # Check if CSV
+        if meta1.get("format") == "csv" or meta2.get("format") == "csv" or ("," in p1 and "\n" in p1):
+            try:
+                r1 = list(csv.reader(io.StringIO(p1.strip())))
+                r2 = list(csv.reader(io.StringIO(p2.strip())))
+                h1 = r1[0] if r1 else []
+                h2 = r2[0] if r2 else []
+
+                diff_report["content_diff"]["type"] = "tabular"
+                diff_report["content_diff"]["columns_removed"] = [c for c in h1 if c not in h2]
+                diff_report["content_diff"]["columns_added"] = [c for c in h2 if c not in h1]
+                diff_report["content_diff"]["row_count_delta"] = (len(r2) - 1) - (len(r1) - 1)
+            except Exception:
+                diff_report["content_diff"]["type"] = "text"
+                diff_lines = list(difflib.unified_diff(p1.splitlines(), p2.splitlines(), fromfile=uri1, tofile=uri2))
+                diff_report["content_diff"]["unified_diff"] = diff_lines[:50]
+        else:
+            diff_report["content_diff"]["type"] = "text"
+            diff_lines = list(difflib.unified_diff(p1.splitlines(), p2.splitlines(), fromfile=uri1, tofile=uri2))
+            diff_report["content_diff"]["unified_diff"] = diff_lines[:50]
+
+    elif isinstance(p1, dict) and isinstance(p2, dict):
+        diff_report["content_diff"]["type"] = "structured"
+        diff_report["content_diff"]["keys_removed"] = [k for k in p1 if k not in p2]
+        diff_report["content_diff"]["keys_added"] = [k for k in p2 if k not in p1]
+        diff_report["content_diff"]["keys_modified"] = [k for k in p1 if k in p2 and p1[k] != p2[k]]
+
+    elif isinstance(p1, bytes) and isinstance(p2, bytes):
+        diff_report["content_diff"]["type"] = "binary"
+        diff_report["content_diff"]["size_delta"] = len(p2) - len(p1)
+
+    if as_json:
+        print(json.dumps(diff_report, indent=2, default=str))
+    else:
+        print("=== MCard Diff ===")
+        print(f"Card 1: {uri1} [{str(getattr(card1, 'hash', ''))[:10]}]")
+        print(f"Card 2: {uri2} [{str(getattr(card2, 'hash', ''))[:10]}]")
+        print(f"Identical: {diff_report['hash_match']}")
+
+        if diff_report["metadata_diff"]:
+            print("\nMetadata Differences:")
+            for k, diff in diff_report["metadata_diff"].items():
+                print(f"  {k}: {diff['card1']} -> {diff['card2']}")
+
+        cdiff = diff_report["content_diff"]
+        print(f"\nContent Diff ({cdiff.get('type', 'unknown')}):")
+        if cdiff.get("type") == "tabular":
+            if cdiff.get("columns_removed"):
+                print(f"  - Removed columns: {cdiff['columns_removed']}")
+            if cdiff.get("columns_added"):
+                print(f"  + Added columns:   {cdiff['columns_added']}")
+            print(f"  Rows delta: {cdiff.get('row_count_delta', 0):+d}")
+        elif cdiff.get("type") == "structured":
+            if cdiff.get("keys_removed"):
+                print(f"  - Removed keys: {cdiff['keys_removed']}")
+            if cdiff.get("keys_added"):
+                print(f"  + Added keys:   {cdiff['keys_added']}")
+            if cdiff.get("keys_modified"):
+                print(f"  ~ Modified keys: {cdiff['keys_modified']}")
+        elif cdiff.get("type") == "text":
+            for line in cdiff.get("unified_diff", []):
+                print(f"  {line}")
+
+    return 0
+
+
+def mcard_lineage_cmd(
+    uri: str,
+    as_mermaid: bool = False,
+    as_dot: bool = False,
+    as_json: bool = False,
+) -> int:
+    """Print causal lineage DAG for an MCard."""
+    try:
+        dag = get_mcard_lineage(uri)
+        if as_mermaid:
+            print(dag.to_mermaid())
+        elif as_dot:
+            print(dag.to_dot())
+        elif as_json:
+            nodes_data = [{"id": n.id, "type": n.type, "label": n.label, "hash": n.hash} for n in dag.nodes.values()]
+            edges_data = [{"source": e.source, "target": e.target, "relation": e.relation} for e in dag.edges]
+            print(json.dumps({"target": uri, "nodes": nodes_data, "edges": edges_data}, indent=2))
+        else:
+            print(f"=== Merkle Provenance Lineage for {uri} ===")
+            print(f"Reconstructed in: {dag.reconstruction_time_ms} ms")
+            print(f"Total Nodes: {len(dag.nodes)} | Total Edges: {len(dag.edges)}")
+            print(f"Root Inputs: {dag.get_root_inputs()}")
+            print("\nAncestry Graph (Mermaid):\n")
+            print(dag.to_mermaid())
+        return 0
+    except Exception as e:
+        _logger.error(f"Failed to retrieve lineage for '{uri}': {e}")
+        return 1