codec-cortex 0.3.2__py3-none-any.whl

cortex/cli/commands/add.py

@@ -0,0 +1,89 @@
+"""``cortex add`` (alias: ``cortex patch_add``) — add a new entry to a .cortex file.
+
+v1.1.2: post-mutation validation via :func:`~cortex.cli.commands.post_mutation_gate`.
+v1.1.4 P0-3: ``--unsafe-allow-secret-forensics`` now marks the artefact as
+``non_conformant_forensic_artifact`` via a ``STAT:forensic_quarantine`` entry,
+so the file is explicitly flagged even though it's written.
+"""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...core.parser import build_entry_from_value
+from ...crud.mutations import add_entry
+from ...crud.transactions import atomic_write_cortex
+from ..commands import load_doc, post_mutation_gate
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        entry = add_entry(
+            doc,
+            section=args.section,
+            sigil=args.sigil,
+            name=args.name,
+            value=args.value,
+            create_section=args.create_section,
+            allow_duplicate=args.allow_duplicate,
+            allow_unknown_sigil=getattr(args, "allow_unknown_sigil", False),
+        )
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+
+    if args.dry_run:
+        print(json.dumps({
+            "ok": True,
+            "dry_run": True,
+            "entry": entry.to_dict(),
+        }, indent=2, default=str))
+        return 0
+
+    # Post-mutation validation gate (shared with update/delete/move).
+    err = post_mutation_gate(doc, args)
+    if err is not None:
+        print(json.dumps(err, indent=2, default=str))
+        return 1
+
+    # v1.1.4 P0-3: if --unsafe-allow-secret-forensics was used, mark the
+    # artefact as non_conformant_forensic_artifact before writing.
+    unsafe = getattr(args, "unsafe_allow_secret_forensics", False)
+    if unsafe:
+        # Ensure STAT is declared in $0
+        if "STAT" not in doc.glossary.sigils:
+            from ...glossary.minimal import brain_sigils
+            canonical = {sd.sigil: sd for sd in brain_sigils()}
+            if "STAT" in canonical:
+                doc.glossary.add_sigil(canonical["STAT"])
+        # Add forensic quarantine marker
+        stat_sec = doc.get_or_create_section("$9", title="FORENSIC QUARANTINE")
+        stat_sec.entries.append(build_entry_from_value(
+            "$9", "STAT", "forensic_quarantine", "attrs",
+            {
+                "conformity": "non_conformant_forensic_artifact",
+                "reason": "contains clear-text secret persisted via --unsafe-allow-secret-forensics",
+                "status": "deprecated",
+                "survive": "min",
+            },
+        ))
+
+    result = atomic_write_cortex(
+        doc, args.input, force=args.force,
+        unsafe_allow_secret_forensics=unsafe,
+    )
+
+    payload = {
+        "ok": True,
+        "entry": entry.to_dict(),
+        "written": result.to_dict(),
+    }
+    if unsafe:
+        payload["warning"] = (
+            "ARTEFACT MARKED AS non_conformant_forensic_artifact — "
+            "contains clear-text secret; do NOT use as operational memory"
+        )
+    print(json.dumps(payload, indent=2, default=str))
+    return 0

cortex/cli/commands/compile.py

@@ -0,0 +1,31 @@
+"""``cortex compile`` — compile HCORTEX-EDIT markdown back to .cortex."""
+
+from __future__ import annotations
+
+import os
+
+from ...core.errors import CortexError
+from ...core.parser import parse_cortex
+from ...core.writer import write_cortex
+from ...crud.transactions import atomic_write_text
+from ...hcortex import parse_hcortex_edit
+from ..commands import emit
+
+
+def run(args) -> int:
+    if not os.path.exists(args.input):
+        raise CortexError("E013_NOT_FOUND", f"file not found: {args.input}")
+    with open(args.input, "r", encoding="utf-8") as f:
+        text = f.read()
+    doc = parse_hcortex_edit(text, source=args.input)
+    cortex_text = write_cortex(doc)
+    # Re-parse to verify compile output is itself valid
+    parse_cortex(cortex_text, path=args.out)
+    result = atomic_write_text(cortex_text, args.out, keep_backup=False)
+    emit({
+        "text": f"compiled {args.input} → {args.out} ({result.bytes_written} bytes)",
+        "input": args.input,
+        "out": args.out,
+        "bytes": result.bytes_written,
+    }, json_mode=False)
+    return 0

cortex/cli/commands/delete.py

@@ -0,0 +1,44 @@
+"""``cortex delete`` (alias: ``cortex patch_remove``) — delete an entry.
+
+v1.1.2: post-mutation validation via :func:`~cortex.cli.commands.post_mutation_gate`
+(so deleting a critical FCS in a brain is rejected unless ``--force``).
+"""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...crud.mutations import delete_entry
+from ...crud.transactions import atomic_write_cortex
+from ..commands import load_doc, post_mutation_gate
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        entry = delete_entry(doc, args.selector, force=args.force)
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+
+    if args.dry_run:
+        print(json.dumps({
+            "ok": True, "dry_run": True,
+            "deleted": entry.to_dict(),
+        }, indent=2, default=str))
+        return 0
+
+    # v1.1.2: post-mutation validation gate (same as add).
+    err = post_mutation_gate(doc, args)
+    if err is not None:
+        print(json.dumps(err, indent=2, default=str))
+        return 1
+
+    result = atomic_write_cortex(doc, args.input, force=args.force)
+    print(json.dumps({
+        "ok": True,
+        "deleted": entry.to_dict(),
+        "written": result.to_dict(),
+    }, indent=2, default=str))
+    return 0

cortex/cli/commands/diagram.py

@@ -0,0 +1,130 @@
+"""``cortex diagram`` — DIAG bloque operations (list, extract, validate).
+
+Closes audit gap B-010: the SKILL plans ``diagram list/extract/validate``
+(Section 22.2). This module implements them as thin wrappers over the AST.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from ...core.ast import CortexDocument
+from ...core.errors import CortexError, NotFoundError
+from ..commands import load_doc
+
+
+def _find_diagrams(doc: CortexDocument, name: str | None = None) -> list:
+    """Return all DIAG entries (optionally filtered by name)."""
+
+    out = []
+    for sec, entry in doc.iter_entries():
+        if entry.sigil != "DIAG":
+            continue
+        if name and entry.name != name:
+            continue
+        out.append((sec, entry))
+    return out
+
+
+def run_list(args) -> int:
+    doc = load_doc(args.input)
+    diags = _find_diagrams(doc)
+    if args.format == "json":
+        print(json.dumps({
+            "ok": True,
+            "count": len(diags),
+            "diagrams": [
+                {
+                    "section": sec.id,
+                    "name": e.name,
+                    "hash": e.hash,
+                    "bytes": len(str(e.value or "").encode("utf-8")),
+                }
+                for sec, e in diags
+            ],
+        }, indent=2, default=str))
+    else:
+        if not diags:
+            print("(no DIAG entries)")
+            return 0
+        print(f"{'SECTION':<8} {'NAME':<24} {'BYTES':<8} HASH")
+        print("-" * 70)
+        for sec, e in diags:
+            nbytes = len(str(e.value or "").encode("utf-8"))
+            print(f"{sec.id:<8} {e.name:<24} {nbytes:<8} {e.hash[:16]}")
+    return 0
+
+
+def run_extract(args) -> int:
+    """Extract a DIAG bloque verbatim.
+
+    Re-audit H-RA-04: the previous implementation appended a trailing
+    newline, which broke byte-exact preservation.  Now we write the
+    value as-is.  Use ``--print-newline`` to add a trailing newline on
+    stdout output for terminal friendliness.
+    """
+
+    doc = load_doc(args.input)
+    diags = _find_diagrams(doc, name=args.name)
+    if not diags:
+        raise NotFoundError(f"DIAG:{args.name}")
+    if len(diags) > 1:
+        raise CortexError(
+            "E014_AMBIGUOUS_SELECTOR",
+            f"multiple DIAG entries named {args.name!r}",
+        )
+    _, entry = diags[0]
+    text = str(entry.value or "")
+    if args.out:
+        # Write exactly the bytes — no appended newline.
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(text)
+        print(f"extracted DIAG:{args.name} → {args.out} ({len(text)} bytes, verbatim)")
+    else:
+        # Default: write exactly the bytes (no trailing newline)
+        sys.stdout.write(text)
+        if getattr(args, "print_newline", False):
+            sys.stdout.write("\n")
+    return 0
+
+
+def run_validate(args) -> int:
+    doc = load_doc(args.input)
+    diags = _find_diagrams(doc, name=args.name)
+    if not diags:
+        if args.format == "json":
+            print(json.dumps({"ok": False, "error": "no DIAG entries found"}))
+        else:
+            print("no DIAG entries found")
+        return 1
+    findings = []
+    for sec, entry in diags:
+        text = str(entry.value or "")
+        issues = []
+        # Heuristics: check for balanced @startuml/@enduml, balanced braces
+        if "@startuml" in text and "@enduml" not in text:
+            issues.append("missing @enduml")
+        if "@enduml" in text and "@startuml" not in text:
+            issues.append("missing @startuml")
+        if text.count("{") != text.count("}"):
+            issues.append(f"unbalanced braces ({text.count('{')} '{{' vs {text.count('}')} '}}')")
+        findings.append({
+            "section": sec.id,
+            "name": entry.name,
+            "bytes": len(text),
+            "issues": issues,
+            "valid": len(issues) == 0,
+        })
+    if args.format == "json":
+        print(json.dumps({"ok": all(f["valid"] for f in findings), "diagrams": findings},
+                         indent=2, default=str))
+    else:
+        all_valid = all(f["valid"] for f in findings)
+        print(f"validation: {'OK' if all_valid else 'ISSUES'}")
+        for f in findings:
+            status = "✓" if f["valid"] else "✗"
+            print(f"  {status} {f['section']}/DIAG:{f['name']} ({f['bytes']} bytes)")
+            for issue in f["issues"]:
+                print(f"      - {issue}")
+    return 0 if all(f["valid"] for f in findings) else 2

cortex/cli/commands/diff.py

@@ -0,0 +1,135 @@
+"""``cortex diff`` — structural/semantic/governance diff between two .cortex files.
+
+v1.1.2: ``--profile governance`` redefinido.  Antes comparaba sólo los
+``findings`` de ``validate_level_policy`` (ambos archivos válidos → rc=0
+aun si cambiaron restricciones críticas).  Ahora compara los **cambios
+reales** en entradas de gobernanza (FCS, OBJ, CNST, RSK, AUD, CLAIM,
+LIM) entre los dos archivos, además de los findings.  Retorna non-zero
+si hay cualquier cambio en gobernanza.
+"""
+
+from __future__ import annotations
+
+import json
+
+from ...core.compare import compare_ast
+from ...core.document_kind import infer_document_kind, validate_level_policy
+from ..commands import load_doc
+
+
+# Sigilos que constituyen "gobernanza" — cualquier cambio en estas
+# entradas afecta las invariantes cognitivas del protocolo.
+GOVERNANCE_SIGILS = frozenset({
+    "FCS", "OBJ", "WRK", "STP", "NXT",      # working state
+    "CNST", "AXM", "!",                       # hard constraints
+    "RSK", "AUD", "CLAIM", "LIM",            # risk / audit / limits
+    "KNW",                                     # promoted knowledge
+})
+
+
+def _extract_governance_changes(left, right) -> list:
+    """Return a list of governance-relevant diffs between two ASTs.
+
+    Filters :func:`~cortex.core.compare.compare_ast` results to only
+    those affecting governance sigils.  This is the real "governance
+    diff": did any constraint, risk, audit or working-state entry
+    change between the two files?
+    """
+
+    result = compare_ast(left, right)
+    gov_diffs = []
+    for d in result.diffs:
+        path = d.path or ""
+        # path is like "$2/FCS:primary" or "sigils.FCS"
+        # We consider it governance-relevant if any GOVERNANCE_SIGILS
+        # appears in the path.
+        path_upper = path.upper()
+        if any(sig in path_upper for sig in GOVERNANCE_SIGILS):
+            gov_diffs.append(d.to_dict())
+        # Glossary changes to governance sigils also count
+        if path.startswith("sigils."):
+            sig = path.split(".", 1)[1]
+            if sig in GOVERNANCE_SIGILS:
+                gov_diffs.append(d.to_dict())
+    return gov_diffs
+
+
+def run(args) -> int:
+    left = load_doc(args.left)
+    right = load_doc(args.right)
+    profile = getattr(args, "profile", "structural")
+
+    json_mode = getattr(args, "_json_mode", False)
+    if args.format == "json" or json_mode:
+        if profile == "governance":
+            # v1.1.2: governance diff = real changes in governance entries
+            # + level-policy findings on both sides
+            left_kind = infer_document_kind(left, args.left)
+            right_kind = infer_document_kind(right, args.right)
+            left_findings = validate_level_policy(left, left_kind)
+            right_findings = validate_level_policy(right, right_kind)
+            gov_changes = _extract_governance_changes(left, right)
+            ok = (not gov_changes) and (not left_findings) and (not right_findings)
+            print(json.dumps({
+                "ok": ok,
+                "profile": profile,
+                "left": {
+                    "kind": left_kind.kind,
+                    "findings": left_findings,
+                },
+                "right": {
+                    "kind": right_kind.kind,
+                    "findings": right_findings,
+                },
+                "governance_changes": gov_changes,
+                "summary": {
+                    "governance_changes_count": len(gov_changes),
+                    "left_findings_count": len(left_findings),
+                    "right_findings_count": len(right_findings),
+                },
+            }, indent=2, default=str))
+            return 0 if ok else 1
+        else:
+            result = compare_ast(left, right)
+            print(json.dumps({
+                "ok": result.equal,
+                "profile": profile,
+                "left": args.left,
+                "right": args.right,
+                "diffs": [d.to_dict() for d in result.diffs],
+            }, indent=2, default=str))
+            return 0 if result.equal else 1
+
+    # Text mode
+    if profile == "governance":
+        left_kind = infer_document_kind(left, args.left)
+        right_kind = infer_document_kind(right, args.right)
+        left_findings = validate_level_policy(left, left_kind)
+        right_findings = validate_level_policy(right, right_kind)
+        gov_changes = _extract_governance_changes(left, right)
+        ok = (not gov_changes) and (not left_findings) and (not right_findings)
+        if ok:
+            print(f"✓ {args.left} and {args.right} are governance-equal "
+                  f"(no changes in governance entries, no findings)")
+        else:
+            print(f"✗ governance diff between {args.left} and {args.right}:")
+            print(f"  left kind:  {left_kind.kind} ({len(left_findings)} finding(s))")
+            print(f"  right kind: {right_kind.kind} ({len(right_findings)} finding(s))")
+            print(f"  governance entry changes: {len(gov_changes)}")
+            for c in gov_changes[:10]:
+                print(f"  [{c.get('kind')}] {c.get('path')}: {c.get('message')}")
+            for f in left_findings:
+                print(f"  [L] [{f.get('code')}] {f.get('message')}")
+            for f in right_findings:
+                print(f"  [R] [{f.get('code')}] {f.get('message')}")
+        return 0 if ok else 1
+
+    # structural / semantic
+    result = compare_ast(left, right)
+    if result.equal:
+        print(f"✓ {args.left} and {args.right} are structurally equal (profile={profile})")
+    else:
+        print(f"✗ {args.left} and {args.right} differ ({len(result.diffs)} diff(s), profile={profile}):")
+        for d in result.diffs:
+            print(f"  [{d.kind}] {d.path}: {d.message}")
+    return 0 if result.equal else 1

cortex/cli/commands/doctor.py

@@ -0,0 +1,74 @@
+"""``cortex doctor`` — deep diagnostic of a .cortex file."""
+
+from __future__ import annotations
+
+import json
+
+from ...core.document_kind import infer_document_kind
+from ...core.validator import validate
+from ..commands import load_doc
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    strict = getattr(args, "strict", False)
+
+    # Apply explicit kind if provided (audit gap H-01/H-02)
+    kind = None
+    if getattr(args, "kind", None):
+        from ...core.document_kind import DocumentKind
+        kind = DocumentKind(kind=args.kind, source="cli")
+    if kind is None:
+        kind = infer_document_kind(doc, args.input)
+
+    diagnostics = validate(doc, strict=strict, kind=kind)
+    errors = [d for d in diagnostics if d.get("severity") == "error"]
+    warnings = [d for d in diagnostics if d.get("severity") == "warning"]
+    sections = doc.sections
+    sigils = list(doc.glossary.sigils.values())
+    types = list(doc.glossary.types.values())
+    micro = list(doc.glossary.micro.values())
+    entries = [(s.id, e) for s in sections if s.id != "$0" for e in s.entries]
+
+    json_mode = getattr(args, "_json_mode", False)
+    if args.format == "json" or json_mode:
+        print(json.dumps({
+            "ok": len(errors) == 0,
+            "input": args.input,
+            "kind": kind.kind,
+            "kind_source": kind.source,
+            "sections": len(sections),
+            "entries": len(entries),
+            "sigils": len(sigils),
+            "types": len(types),
+            "micro": len(micro),
+            "strict": strict,
+            "errors": errors,
+            "warnings": warnings,
+            "section_ids": [s.id for s in sections],
+            "sigil_names": [s.sigil for s in sigils],
+        }, indent=2, default=str))
+    else:
+        lines = []
+        lines.append(f"doctor: {args.input}")
+        lines.append(f"  kind:         {kind.kind} (inferred via {kind.source})")
+        lines.append(f"  strict:       {strict}")
+        lines.append(f"  sections:     {len(sections)}  ({', '.join(s.id for s in sections)})")
+        lines.append(f"  entries:      {len(entries)}")
+        lines.append(f"  sigils:       {len(sigils)}")
+        lines.append(f"  types:        {len(types)}")
+        lines.append(f"  micro:        {len(micro)}")
+        lines.append(f"  errors:       {len(errors)}")
+        lines.append(f"  warnings:     {len(warnings)}")
+        if errors:
+            lines.append("")
+            lines.append("errors:")
+            for e in errors:
+                lines.append(f"  [{e.get('code')}] {e.get('message')}")
+        if warnings:
+            lines.append("")
+            lines.append("warnings:")
+            for w in warnings:
+                lines.append(f"  [{w.get('code')}] {w.get('message')}")
+        print("\n".join(lines))
+    return 1 if errors else 0

cortex/cli/commands/format.py

@@ -0,0 +1,29 @@
+"""``cortex format`` — re-serialize a .cortex file canonically."""
+
+from __future__ import annotations
+
+import json
+
+from ...crud.transactions import atomic_write_cortex
+from ...core.writer import write_cortex
+from ..commands import load_doc
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    out_path = args.out or args.input
+    if args.dry_run:
+        text = write_cortex(doc)
+        print(json.dumps({
+            "ok": True,
+            "dry_run": True,
+            "bytes": len(text.encode("utf-8")),
+            "preview": text[:500],
+        }, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, out_path, force=args.force)
+    print(json.dumps({
+        "ok": True,
+        "written": result.to_dict(),
+    }, indent=2, default=str))
+    return 0

cortex/cli/commands/get.py

@@ -0,0 +1,45 @@
+"""``cortex get`` — fetch a single entry by selector."""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...crud.selectors import select_one
+from ..commands import load_doc
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        entry = select_one(doc, args.selector)
+    except CortexError as e:
+        if args.format == "json":
+            print(json.dumps({"ok": False, "error": {"code": e.code, "message": e.message}}))
+        else:
+            print(f"error: {e}")
+        return 1
+    if args.format == "json":
+        print(json.dumps({
+            "ok": True,
+            "entry": entry.to_dict(),
+        }, indent=2, ensure_ascii=False, default=str))
+    else:
+        lines = []
+        lines.append(f"section: {entry.section}")
+        lines.append(f"sigil:   {entry.sigil}")
+        lines.append(f"name:    {entry.name}")
+        lines.append(f"type:    {entry.type}")
+        lines.append(f"hash:    {entry.hash}")
+        lines.append(f"lines:   {entry.line_start}-{entry.line_end}")
+        lines.append("")
+        lines.append("value:")
+        if isinstance(entry.value, dict):
+            for k, v in entry.value.items():
+                lines.append(f"  {k}: {v!r}")
+        else:
+            lines.append(f"  {entry.value}")
+        lines.append("")
+        lines.append(f"raw: {entry.raw}")
+        print("\n".join(lines))
+    return 0

cortex/cli/commands/glossary.py

@@ -0,0 +1,98 @@
+"""``cortex glossary`` — glossary CRUD (list/add/update/delete sigils)."""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...crud.mutations import (
+    add_sigil_to_glossary,
+    delete_sigil_from_glossary,
+    update_sigil_in_glossary,
+)
+from ...crud.transactions import atomic_write_cortex
+from ..commands import load_doc
+
+
+def run_list(args) -> int:
+    doc = load_doc(args.input)
+    sigils = list(doc.glossary.sigils.values())
+    if args.format == "json":
+        print(json.dumps({
+            "ok": True,
+            "count": len(sigils),
+            "sigils": [s.to_dict() for s in sigils],
+        }, indent=2, default=str))
+    else:
+        if not sigils:
+            print("(no sigils declared)")
+            return 0
+        lines = [
+            f"{'SIGIL':<6} {'NAME':<12} {'TYPE':<10} {'RISK':<4} {'LAYER':<14} DESCRIPTION",
+            "-" * 80,
+        ]
+        for s in sigils:
+            lines.append(f"{s.sigil:<6} {s.name:<12} {s.type:<10} {s.risk:<4} {s.layer:<14} {s.description}")
+        print("\n".join(lines))
+    return 0
+
+
+def run_add(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        add_sigil_to_glossary(
+            doc,
+            sigil=args.sigil,
+            name=args.name,
+            type_=args.type,
+            risk=args.risk,
+            layer=args.layer,
+            description=args.description,
+            force_governance=args.force_governance,
+        )
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "sigil": args.sigil}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "sigil": args.sigil, "written": result.to_dict()}, indent=2, default=str))
+    return 0
+
+
+def run_update(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        update_sigil_in_glossary(
+            doc,
+            sigil=args.sigil,
+            description=args.description,
+            risk=args.risk,
+            layer=args.layer,
+            force_governance=args.force_governance,
+        )
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "sigil": args.sigil}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "sigil": args.sigil, "written": result.to_dict()}, indent=2, default=str))
+    return 0
+
+
+def run_delete(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        delete_sigil_from_glossary(doc, sigil=args.sigil, force=args.force)
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "sigil": args.sigil}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "sigil": args.sigil, "written": result.to_dict()}, indent=2, default=str))
+    return 0