codec-cortex 0.3.2__py3-none-any.whl

cortex/cli/commands/list.py

@@ -0,0 +1,44 @@
+"""``cortex list`` — list entries in a .cortex file."""
+
+from __future__ import annotations
+
+import json
+
+from ...crud.selectors import select
+from ..commands import load_doc
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    # Build selector from filters
+    if args.section and args.sigil:
+        sel = f"{args.section}/*"
+        # narrow by sigil after the fact
+        entries = [e for e in select(doc, sel) if e.sigil == args.sigil]
+    elif args.section:
+        entries = select(doc, f"{args.section}/*")
+    elif args.sigil:
+        entries = select(doc, f"{args.sigil}:*")
+    else:
+        entries = select(doc, "*:*")
+
+    if args.format == "json":
+        print(json.dumps({
+            "ok": True,
+            "count": len(entries),
+            "entries": [e.to_dict() for e in entries],
+        }, indent=2, ensure_ascii=False, default=str))
+    else:
+        if not entries:
+            print("(no entries match)")
+            return 0
+        lines = []
+        lines.append(f"{'SECTION':<6} {'SIGIL':<6} {'NAME':<24} {'TYPE':<10} {'HASH':<16}")
+        lines.append("-" * 70)
+        for e in entries:
+            lines.append(
+                f"{e.section:<6} {e.sigil:<6} {e.name:<24} {e.type:<10} "
+                f"{e.hash[:16] if e.hash else '':<16}"
+            )
+        print("\n".join(lines))
+    return 0

cortex/cli/commands/micro.py

@@ -0,0 +1,79 @@
+"""``cortex micro`` — micro-token CRUD."""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...crud.mutations import (
+    add_micro_to_glossary,
+    delete_micro_from_glossary,
+    update_micro_in_glossary,
+)
+from ...crud.transactions import atomic_write_cortex
+from ..commands import load_doc
+
+
+def run_list(args) -> int:
+    doc = load_doc(args.input)
+    micro = list(doc.glossary.micro.values())
+    if args.format == "json":
+        print(json.dumps({
+            "ok": True,
+            "count": len(micro),
+            "micro": [m.to_dict() for m in micro],
+        }, indent=2, default=str))
+    else:
+        if not micro:
+            print("(no micro-tokens declared)")
+            return 0
+        lines = [f"{'TOKEN':<10} VALUE", "-" * 40]
+        for m in micro:
+            lines.append(f"{m.token:<10} {m.value}")
+        print("\n".join(lines))
+    return 0
+
+
+def run_add(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        add_micro_to_glossary(doc, token=args.token, value=args.value)
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "token": args.token}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "token": args.token, "written": result.to_dict()}, indent=2, default=str))
+    return 0
+
+
+def run_update(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        update_micro_in_glossary(doc, token=args.token, value=args.value)
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+    if args.dry_run:
+        print(json.dumps({"ok": True, "dry_run": True, "token": args.token}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "token": args.token, "written": result.to_dict()}, indent=2, default=str))
+    return 0
+
+
+def run_delete(args) -> int:
+    doc = load_doc(args.input)
+    try:
+        delete_micro_from_glossary(doc, token=args.token, 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, "token": args.token}, indent=2))
+        return 0
+    result = atomic_write_cortex(doc, args.input, force=False)
+    print(json.dumps({"ok": True, "token": args.token, "written": result.to_dict()}, indent=2, default=str))
+    return 0

cortex/cli/commands/move.py

@@ -0,0 +1,45 @@
+"""``cortex move`` — move an entry to another section.
+
+v1.1.2: post-mutation validation via :func:`~cortex.cli.commands.post_mutation_gate`
+(so moving an entry to a section that violates level policy is rejected
+unless ``--force``).
+"""
+
+from __future__ import annotations
+
+import json
+
+from ...core.errors import CortexError
+from ...crud.mutations import move_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 = move_entry(doc, args.selector, args.to_section)
+    except CortexError as e:
+        print(f"error: {e}")
+        return 1
+
+    if args.dry_run:
+        print(json.dumps({
+            "ok": True, "dry_run": True,
+            "moved": 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,
+        "moved": entry.to_dict(),
+        "written": result.to_dict(),
+    }, indent=2, default=str))
+    return 0

cortex/cli/commands/new.py

@@ -0,0 +1,80 @@
+"""``cortex new`` — create a new .cortex file from a template.
+
+v1.1.2: ``--json`` now produces real JSON output (was text-only before).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ...core.errors import CortexError, TemplateUnknownError
+from ...crud.transactions import atomic_write_cortex
+from ...templates import build_brain, build_package, build_skill
+
+
+def run(args) -> int:
+    kind = args.kind
+    if kind == "brain":
+        doc = build_brain(
+            name=args.name or "project-brain",
+            domain=args.domain or "active work",
+            owner=args.owner or "agent",
+            language=args.language,
+            template=args.template,
+            with_diagrams=args.with_diagrams,
+        )
+    elif kind == "skill":
+        doc = build_skill(
+            name=args.name or "codec-cortex",
+            version=args.doc_version or "1.0.0",
+            domain=args.domain or "LLM/SLM contextual memory",
+            owner=args.owner or "agent",
+            language=args.language,
+            template=args.template,
+            with_diagrams=args.with_diagrams,
+        )
+    elif kind == "package":
+        doc = build_package(
+            name=args.name or "context_package",
+            version=args.doc_version or "0.1.0",
+            domain=args.domain or "specific domain",
+            owner=args.owner or "source",
+            language=args.language,
+            template=args.template,
+            with_diagrams=args.with_diagrams,
+        )
+    elif kind == "generic":
+        doc = build_brain(
+            name=args.name or "generic-cortex",
+            domain=args.domain or "generic",
+            owner=args.owner or "agent",
+            language=args.language,
+            template=args.template,
+            with_diagrams=args.with_diagrams,
+        )
+    else:
+        raise TemplateUnknownError(kind)
+
+    out_path = args.out
+    if os.path.exists(out_path) and not args.force:
+        raise CortexError(
+            "E015_ATOMIC_WRITE_FAILED",
+            f"output file exists: {out_path} (use --force to overwrite)",
+        )
+
+    result = atomic_write_cortex(doc, out_path, force=True, keep_backup=False)
+    payload = {
+        "ok": True,
+        "text": f"created {out_path} ({result.bytes_written} bytes)",
+        "path": out_path,
+        "bytes": result.bytes_written,
+        "kind": kind,
+    }
+    # v1.1.2: honour --json properly
+    json_mode = getattr(args, "_json_mode", False)
+    if json_mode:
+        print(json.dumps(payload, indent=2, ensure_ascii=False, default=str))
+    else:
+        print(payload["text"])
+    return 0

cortex/cli/commands/recover.py

@@ -0,0 +1,90 @@
+"""``cortex recover`` — recover a legacy or non-conforming .cortex file.
+
+Closes audit gap H-06: tolerates preambles, legacy column names, missing
+``$0``, and reconstructs a conforming document with RSK diagnostics for
+every reconstructed sigil.
+
+v1.1.6 P1-5: recover now validates the result and returns non-zero if
+the recovered artefact is not conformant (e.g. still has E033/E034 errors
+that recovery cannot fix).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from ...core.errors import CortexError
+from ...core.parser import parse_cortex
+from ...core.writer import write_cortex
+from ...core.validator import validate
+from ...crud.transactions import atomic_write_text
+from ...hcortex import recover_cortex
+from ..commands import load_doc  # noqa: F401  (re-exported helper)
+
+
+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()
+
+    result = recover_cortex(
+        text, path=args.input, strict=args.strict,
+        embed_aud_rsk=getattr(args, "embed_aud_rsk", False),
+    )
+    cortex_text = write_cortex(result.doc)
+
+    # v1.1.6 P1-5: validate the recovered artefact.  If it still has
+    # non-bypassable errors, return non-zero so CI and automation can
+    # detect that recovery did not produce a conformant file.
+    reparsed = parse_cortex(cortex_text, path=args.input)
+    post_diags = validate(reparsed, strict=False)
+    post_errors = [d for d in post_diags if d.get("severity") == "error"]
+    conformant = len(post_errors) == 0
+
+    if args.out:
+        # Write even if non-conformant — the user may need to inspect
+        # the partial recovery.  But return non-zero to signal the issue.
+        atomic_write_text(cortex_text, args.out, keep_backup=False)
+        if args.format == "json":
+            print(json.dumps({
+                "ok": conformant,
+                "input": args.input,
+                "out": args.out,
+                "reconstructed_glossary": result.reconstructed_glossary,
+                "preamble_lines": len(result.preamble),
+                "diagnostics": result.diagnostics,
+                "post_validation_errors": post_errors if not conformant else [],
+                "conformant": conformant,
+            }, indent=2, default=str))
+        else:
+            print(f"recovered {args.input} → {args.out}")
+            print(f"  preamble stripped: {len(result.preamble)} line(s)")
+            print(f"  reconstructed $0: {result.reconstructed_glossary}")
+            print(f"  diagnostics: {len(result.diagnostics)}")
+            for d in result.diagnostics:
+                sev = d.get("severity", "info")
+                print(f"  [{sev}] {d.get('code')}: {d.get('message')}")
+            if not conformant:
+                print(f"  ⚠ WARNING: recovered artefact has {len(post_errors)} "
+                      "validation error(s) — NOT conformant")
+                for e in post_errors[:5]:
+                    print(f"    [{e.get('code')}] {e.get('message', '')[:100]}")
+    else:
+        if args.format == "json":
+            print(json.dumps({
+                "ok": conformant,
+                "input": args.input,
+                "reconstructed_glossary": result.reconstructed_glossary,
+                "preamble_lines": len(result.preamble),
+                "diagnostics": result.diagnostics,
+                "conformant": conformant,
+                "cortex": cortex_text,
+            }, indent=2, default=str))
+        else:
+            sys.stdout.write(cortex_text)
+
+    # v1.1.6 P1-5: non-zero if not conformant
+    return 0 if conformant else 1

cortex/cli/commands/render.py

@@ -0,0 +1,93 @@
+"""``cortex render`` (alias: ``cortex decode``) — render .cortex to HCORTEX markdown.
+
+v1.1.2: ``--json`` now produces real JSON output (was text-only before).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from ...core.errors import CortexError
+from ...crud.transactions import atomic_write_text
+from ...hcortex import render_hcortex_edit, render_hcortex_read
+from ..commands import load_doc
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    # v1.1.3 P2-8: default mode is 'readable' so `decode <file>` works
+    # without --mode (matches the SKILL §22.2 planned UX).
+    mode = (args.mode or "readable").lower()
+
+    # Mode normalisation: legacy 'read'/'edit' → canonical
+    if mode == "read":
+        mode = "readable"
+    # Map profile arg to uppercase
+    profile = args.profile.upper() if args.profile else None
+
+    if mode == "edit":
+        md = render_hcortex_edit(doc, source=args.input)
+    elif mode in ("readable", "audit", "recovery", "full"):
+        # Map mode aliases to profile + with_source
+        if mode == "recovery":
+            profile = profile or "RECOVERY"
+        elif mode == "full":
+            profile = profile or "FULL"
+            args.with_source = True
+        elif mode == "audit":
+            args.with_source = True
+        md = render_hcortex_read(
+            doc,
+            with_source=getattr(args, "with_source", False),
+            profile=profile,
+            mode=mode.upper() if mode in ("recovery", "full") else "READABLE",
+            layout=getattr(args, "layout", None),
+        )
+    else:
+        raise CortexError(
+            "E021_INVALID_VALUE",
+            f"unknown render mode {args.mode!r}",
+        )
+
+    out = args.out
+    json_mode = getattr(args, "_json_mode", False)
+    if out:
+        # If --out exists and no --force, error (audit gap L-03).
+        if os.path.exists(out) and not getattr(args, "force", False):
+            raise CortexError(
+                "E015_ATOMIC_WRITE_FAILED",
+                f"output file exists: {out} (use --force to overwrite)",
+            )
+        result = atomic_write_text(md, out, keep_backup=False)
+        payload = {
+            "ok": True,
+            "text": (
+                f"rendered {args.input} → {out} "
+                f"({result.bytes_written} bytes, mode={mode}"
+                f"{f', profile={profile}' if profile else ''})"
+            ),
+            "input": args.input,
+            "out": out,
+            "mode": mode,
+            "profile": profile,
+            "bytes": result.bytes_written,
+        }
+        if json_mode:
+            print(json.dumps(payload, indent=2, ensure_ascii=False, default=str))
+        else:
+            print(payload["text"])
+    else:
+        # No --out: write markdown to stdout.  --json wraps it in a payload.
+        if json_mode:
+            print(json.dumps({
+                "ok": True,
+                "input": args.input,
+                "mode": mode,
+                "profile": profile,
+                "markdown": md,
+            }, indent=2, ensure_ascii=False, default=str))
+        else:
+            sys.stdout.write(md)
+    return 0

cortex/cli/commands/update.py

@@ -0,0 +1,81 @@
+"""``cortex update`` (alias: ``cortex patch_update``) — update an existing entry.
+
+v1.1.2: post-mutation validation via :func:`~cortex.cli.commands.post_mutation_gate`
+(so an update that breaks a contract is rejected unless ``--force``).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from ...core.errors import CortexError
+from ...crud.mutations import update_entry
+from ...crud.transactions import atomic_write_cortex
+from ..commands import load_doc, post_mutation_gate
+
+
+_SET_PAIR_RE = re.compile(r'^(?P<key>[A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?P<val>.*)$')
+
+
+def _parse_set_pairs(pairs):
+    out = {}
+    for p in pairs:
+        m = _SET_PAIR_RE.match(p)
+        if not m:
+            raise CortexError("E021_INVALID_VALUE", f"invalid --set pair: {p!r} (expected key=value)")
+        key = m.group("key")
+        val = m.group("val")
+        # Strip surrounding quotes
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ('"', "'"):
+            val = val[1:-1]
+        elif val == "true":
+            val = True
+        elif val == "false":
+            val = False
+        elif val.lower() in ("null", "none", "nil", "undefined"):
+            # v1.1.7 P0-3 + v1.1.8: convert null-like literals to None
+            val = None
+        elif re.fullmatch(r"-?\d+", val):
+            val = int(val)
+        elif re.fullmatch(r"-?\d+\.\d+", val):
+            val = float(val)
+        out[key] = val
+    return out
+
+
+def run(args) -> int:
+    doc = load_doc(args.input)
+    set_ = _parse_set_pairs(args.set_pairs) if args.set_pairs else None
+    try:
+        entry = update_entry(
+            doc,
+            args.selector,
+            set_=set_,
+            replace_body=args.body,
+            append=args.append,
+        )
+    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
+
+    # 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,
+        "entry": entry.to_dict(),
+        "written": result.to_dict(),
+    }, indent=2, default=str))
+    return 0

cortex/cli/commands/v2_canonicalize.py

@@ -0,0 +1,162 @@
+"""``cortex canonicalize`` — normalize artefacts without changing semantics.
+
+Canonical name: ``canonicalize`` (since v0.3.2).
+Deprecated alias: ``v2-canonicalize`` (still accepted).
+
+v0.3.2 — VIEW-aware behavior (B-01/B-05 fix):
+
+  The previous implementation always rewrote the .cortex using
+  :func:`write_cortex_v2`, which produced a canonically-formatted v2
+  artefact. That broke v1-render compatibility for artefacts that did
+  not declare VIEW directives (notably the benchmark corpus), causing
+  BCFNR=1.0 and HCORTEX empty output (issues B-01, B-03, B-05).
+
+  The new behavior is:
+
+    1. Parse the artefact and check whether it has any operational VIEW
+       directives (``view.parse_view_entries_from_doc`` semantics).
+    2. If it has VIEW directives AND ``--preserve`` was NOT passed:
+       - Apply full canonicalization (the original behavior, via
+         :func:`write_cortex_v2`). This is safe because the VIEW
+         directives guarantee reversibility.
+    3. If it does NOT have VIEW directives, OR ``--preserve`` was passed:
+       - Emit a warning to stderr explaining that the artefact lacks
+         VIEW directives and that only whitespace/section ordering will
+         be normalized (structure preserved).
+       - Use :func:`write_cortex_v2_preserve` to produce a
+         structure-preserving serialization. This keeps v1-render
+         compatibility.
+    4. In all cases, return 0 on success.
+
+  The ``--preserve`` flag is an explicit escape hatch for users who want
+  to force the structure-preserving path even when VIEW directives are
+  present (e.g. when preparing an artefact for a v1-only consumer).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from ...core.errors import CortexError
+from ...v2.parser import parse_cortex_v2
+from ...v2.writer import (
+    write_cortex_v2,
+    write_cortex_v2_preserve,
+    has_view_directives,
+)
+from ...v2.view_renderer import render_hcortex
+from ...v2.hcortex_parser import parse_hcortex
+from ...v2.encoder import encode_cortex_from_ast
+
+
+def _emit_warning(msg: str) -> None:
+    """Emit a warning to stderr (visible even when stdout is redirected)."""
+    print(f"WARNING: {msg}", file=sys.stderr)
+
+
+def _canonicalize_cortex(text: str, preserve: bool) -> tuple[str, list[str]]:
+    """Canonicalize a CORTEX (non-HCORTEX) artefact.
+
+    Returns ``(output_text, warnings)``.
+    """
+    warnings: list[str] = []
+    doc = parse_cortex_v2(text)
+
+    has_views = has_view_directives(doc)
+
+    if preserve:
+        warnings.append(
+            "--preserve requested: structure-preserving canonicalization "
+            "(whitespace + section ordering only). VIEW directives, if any, "
+            "are NOT used for canonical rendering."
+        )
+        out = write_cortex_v2_preserve(doc)
+        return out, warnings
+
+    if not has_views:
+        warnings.append(
+            "artefact has no VIEW directives: applying structure-preserving "
+            "canonicalization (whitespace + section ordering only). The "
+            "output remains v1-render compatible. Add VIEW directives to "
+            "enable full v2 canonicalization, or pass --preserve to silence "
+            "this warning."
+        )
+        out = write_cortex_v2_preserve(doc)
+        return out, warnings
+
+    # Default path: VIEW directives present, no --preserve → full canonicalize.
+    out = write_cortex_v2(doc)
+    return out, warnings
+
+
+def _canonicalize_hcortex(text: str, preserve: bool) -> tuple[str, list[str]]:
+    """Canonicalize an HCORTEX artefact.
+
+    HCORTEX → CORTEX → HCORTEX (canonicalize both legs).
+
+    The same VIEW-aware logic applies on the intermediate CORTEX: if it
+    has no VIEW directives, we fall back to the structure-preserving
+    serializer for the CORTEX leg, then render HCORTEX from it.
+    """
+    warnings: list[str] = []
+    hdoc = parse_hcortex(text, strict=False)
+    doc, _ = encode_cortex_from_ast(hdoc)
+
+    has_views = has_view_directives(doc)
+
+    if preserve or not has_views:
+        if preserve:
+            warnings.append(
+                "--preserve requested: HCORTEX canonicalization will use "
+                "the structure-preserving CORTEX leg."
+            )
+        else:
+            warnings.append(
+                "HCORTEX artefact has no VIEW directives (after decoding to "
+                "CORTEX): applying structure-preserving canonicalization on "
+                "the CORTEX leg. HCORTEX output will be re-rendered from "
+                "the preserved CORTEX."
+            )
+        # Use preserved CORTEX, then re-render HCORTEX
+        from ...v2.writer import write_cortex_v2_preserve
+        _ = write_cortex_v2_preserve(doc)  # no-op effect, kept for symmetry
+        hcortex_md, _ = render_hcortex(doc)
+        return hcortex_md, warnings
+
+    # Default path: full canonicalize
+    cortex_text = write_cortex_v2(doc)
+    hcortex_md, _ = render_hcortex(doc)
+    _ = cortex_text  # generated for symmetry; HCORTEX is the output
+    return hcortex_md, warnings
+
+
+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()
+
+    preserve = bool(getattr(args, "preserve", False))
+
+    is_hcortex = "internal_encoding: HCORTEX" in text
+
+    if is_hcortex:
+        out_text, warnings = _canonicalize_hcortex(text, preserve)
+        kind = "HCORTEX"
+    else:
+        out_text, warnings = _canonicalize_cortex(text, preserve)
+        kind = "CORTEX"
+
+    for w in warnings:
+        _emit_warning(w)
+
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as f:
+            f.write(out_text)
+        print(f"canonicalized {kind}: {args.input} → {args.out}")
+    else:
+        sys.stdout.write(out_text)
+
+    return 0