robo-cortex 0.4.0__py3-none-any.whl

robo_cortex/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.4.0"
+
+from robo_cortex.sdk import RoboCortex, retrieve, record, search
+
+__all__ = ["RoboCortex", "retrieve", "record", "search"]

robo_cortex/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI module — entry point for robo-cortex command."""
+
+from robo_cortex.cli.app import main
+
+__all__ = ["main"]

robo_cortex/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running CLI as: python -m robo_cortex.cli"""
+
+import sys
+from robo_cortex.cli import main
+
+sys.exit(main())

robo_cortex/cli/_common.py

@@ -0,0 +1,72 @@
+"""CLI common utilities: context managers, decorators, constants."""
+
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+
+from robo_cortex.core.errors import RoboCortexError
+from robo_cortex.core.store import open_global_store, open_store
+
+
+def _get_cmd_name():
+    """Extract the command name from sys.argv[0]"""
+    cmd = Path(sys.argv[0]).name
+    if cmd.endswith('.py') or '/' in cmd:
+        return 'robo-cortex'
+    return cmd
+
+
+@contextmanager
+def _store(repo_arg):
+    repo_root, conn = open_store(repo_arg)
+    try:
+        yield repo_root, conn
+    finally:
+        conn.close()
+
+
+@contextmanager
+def _global_store():
+    conn = open_global_store()
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+
+@contextmanager
+def _store_conn(repo_arg):
+    """Same as `_store`, but yields only the connection, not (repo_root, conn).
+
+    Exists for call sites (currently: import) that need a connection-only
+    context manager to pass around -- e.g. as one of two interchangeable
+    factories alongside `_global_store`. Using `_store` directly there would
+    silently yield a 2-tuple where a connection is expected (that mismatch
+    was exactly the `'tuple' object has no attribute 'execute'` bug in the
+    original `roco import` implementation).
+    """
+    with _store(repo_arg) as (_repo_root, conn):
+        yield conn
+
+
+LINK_TYPE_ARGS = {"contradicts": "contradicts", "duplicate-of": "duplicate_of"}
+
+
+def cli_command(name: str):
+    """Decorator: wrap command handler to catch RoboCortexError and return exit code.
+
+    Usage:
+        @cli_command("record")
+        def run(args) -> int:
+            ...result = record_memory(...)...
+            return 0
+    """
+    def wrap(fn):
+        def inner(args):
+            try:
+                return fn(args)
+            except RoboCortexError as error:
+                print(f"{_get_cmd_name()} {name}: {error}", file=sys.stderr)
+                return error.exit_code
+        return inner
+    return wrap

robo_cortex/cli/_output.py

@@ -0,0 +1,76 @@
+"""CLI output formatting utilities."""
+
+import os
+import sys
+
+_ANSI_CODES = {
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "red": "\033[31m",
+}
+_ANSI_RESET = "\033[0m"
+
+# Terminal (superseded/invalidated/abandoned/archived) statuses render red;
+# active is green; everything still under review (provisional/needs_review)
+# is yellow. Unknown/future status strings pass through uncolored rather
+# than raising -- this is display-only, never a source of truth.
+_STATUS_COLORS = {
+    "active": "green",
+    "provisional": "yellow",
+    "needs_review": "yellow",
+    "superseded": "red",
+    "invalidated": "red",
+    "abandoned": "red",
+    "archived": "red",
+}
+
+
+def _color_enabled(stream) -> bool:
+    """NO_COLOR (no-color.org: disable on presence, regardless of value)
+    and non-tty output (pipes, redirects, captured subprocess output in
+    tests) both suppress color -- only an interactive terminal gets ANSI
+    codes.
+    """
+    if "NO_COLOR" in os.environ:
+        return False
+    try:
+        return stream.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def format_status(status: str, *, width: int | None = None, stream=None) -> str:
+    """Color-wrap a memory status for terminal display.
+
+    `width` pads the plain text first, then wraps it in the ANSI codes --
+    padding after coloring would count the invisible escape bytes toward
+    the field width and break column alignment in `list`'s output.
+    """
+    text = f"{status:<{width}s}" if width else status
+    if not _color_enabled(stream or sys.stdout):
+        return text
+    color = _STATUS_COLORS.get(status)
+    if color is None:
+        return text
+    return f"{_ANSI_CODES[color]}{text}{_ANSI_RESET}"
+
+
+def _format_score_breakdown(components: dict) -> str:
+    """Human-readable --explain / --explain-against output. assumptions_gate
+    (present only for scope='global' items, ARCHITECTURE.md §5.4) is a
+    nested dict, not a float -- formatted on its own, never blindly run
+    through the same `:.3f` as the six numeric components.
+    """
+    numeric = " ".join(
+        f"{key}={value:.3f}" for key, value in components.items()
+        if key not in ("total", "assumptions_gate")
+    )
+    parts = [numeric]
+    if "assumptions_gate" in components:
+        gate = components["assumptions_gate"]
+        phrases = ", ".join(
+            f"{p['text']!r}:{'matched' if p['matched'] else 'not matched'}"
+            for p in gate["phrases"]
+        )
+        parts.append(f"assumptions_gate=[{phrases}] passed={gate['passed']}")
+    return "  ".join(parts) + f"  total={components['total']:.3f}"

robo_cortex/cli/app.py

@@ -0,0 +1,74 @@
+"""CLI main application and dispatcher."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from robo_cortex import __version__
+from robo_cortex.cli._common import _get_cmd_name
+from robo_cortex.cli.commands import ALL_COMMANDS
+
+
+def build_parser(cmd_name: str) -> argparse.ArgumentParser:
+    """Construct the full argument parser, every subcommand registered.
+
+    Extracted from `main()` so anything that needs the real command
+    surface -- currently `roco completion` -- introspects the same parser
+    tree the CLI actually dispatches through, instead of a second,
+    driftable description of it.
+    """
+    parser = argparse.ArgumentParser(prog=cmd_name)
+    parser.add_argument(
+        "--version", action="version", version=f"{cmd_name} {__version__}"
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    for command in ALL_COMMANDS:
+        command.register(subparsers)
+
+    return parser
+
+
+def main(argv=None):
+    """Main CLI entry point."""
+    # Extract command name (roco or robo-cortex) from argv[0]
+    if argv is None:
+        argv = sys.argv[1:]
+        cmd_name = Path(sys.argv[0]).name
+    else:
+        cmd_name = Path(argv[0]).name if argv else "robo-cortex"
+
+    # Fallback if invoked as a Python script
+    if cmd_name.endswith('.py') or '/' in cmd_name:
+        cmd_name = 'robo-cortex'
+
+    parser = build_parser(cmd_name)
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help(sys.stderr)
+        return 1
+
+    try:
+        return args.func(args)
+    except Exception as error:
+        # Last-resort net: every expected failure mode is already a
+        # RoboCortexError caught by @cli_command inside args.func, printed
+        # cleanly with the right exit code. Anything that reaches here is
+        # unexpected -- still no raw traceback by default (that's an
+        # implementation detail leaking into a CLI's stdout/stderr contract),
+        # but ROBO_CORTEX_DEBUG=1 gets the real one back for debugging.
+        if os.environ.get("ROBO_CORTEX_DEBUG"):
+            raise
+        print(f"{cmd_name}: internal error: {error}", file=sys.stderr)
+        print(
+            f"{cmd_name}: this is unexpected -- set ROBO_CORTEX_DEBUG=1 for "
+            "a full traceback, and please report it",
+            file=sys.stderr,
+        )
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

robo_cortex/cli/commands/__init__.py

@@ -0,0 +1,36 @@
+"""CLI commands registry."""
+
+# Import all command modules
+from robo_cortex.cli.commands import (
+    init,
+    record,
+    show,
+    list_cmd,
+    retrieve,
+    search,
+    affected,
+    status,
+    evidence,
+    link,
+    mcp,
+    transfer,
+    hooks,
+    completion,
+)
+
+ALL_COMMANDS = [
+    init,
+    record,
+    show,
+    list_cmd,
+    retrieve,
+    search,
+    affected,
+    status,
+    evidence,
+    link,
+    mcp,
+    transfer,
+    hooks,
+    completion,
+]

robo_cortex/cli/commands/affected.py

@@ -0,0 +1,40 @@
+"""Command: roco affected"""
+
+import json
+import sys
+
+from robo_cortex.core.invalidate import affected
+from robo_cortex.cli._common import _get_cmd_name, _store, cli_command
+
+
+@cli_command("affected")
+def run(args) -> int:
+    with _store(args.repo) as (repo_root, conn):
+        result = affected(
+            conn,
+            repo_root,
+            diff_range=args.diff_range,
+            staged=args.staged,
+            working=args.working,
+        )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        if not result["data"]:
+            print("No memories affected.")
+        for item in result["data"]:
+            print(f"[{item['id']}] {item['reason']}  {item['statement']}")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "affected", help="List memories put at risk by recent changes or a diff"
+    )
+    p.add_argument("--repo", default=None)
+    p.add_argument("--diff-range", default=None)
+    p.add_argument("--staged", action="store_true")
+    p.add_argument("--working", action="store_true")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=run)

robo_cortex/cli/commands/completion.py

@@ -0,0 +1,94 @@
+"""Command: roco completion"""
+
+import argparse
+
+from robo_cortex.cli._common import cli_command
+
+_TEMPLATE = """# roco / robo-cortex bash completion
+# Generated by `roco completion bash`. Install with:
+#   roco completion bash >> ~/.bashrc
+# or system-wide (Debian/Ubuntu):
+#   roco completion bash | sudo tee /etc/bash_completion.d/roco
+# Regenerate after upgrading robo-cortex, to pick up new commands or flags.
+_roco_completions()
+{
+    local cur commands
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+
+    commands="__COMMANDS__"
+
+    if [ "$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+        return 0
+    fi
+
+    case "${COMP_WORDS[1]}" in
+__CASES__
+    esac
+}
+complete -F _roco_completions roco
+complete -F _roco_completions robo-cortex
+"""
+
+
+def _bash_completion_script() -> str:
+    """Introspect the real argparse tree (same one `main()` dispatches
+    through -- see `cli.app.build_parser`) rather than hand-maintaining a
+    second, driftable list of commands and flags.
+
+    Only two levels are completed: the subcommand name, and that
+    subcommand's own flags -- not nested sub-subcommands (`hooks install`,
+    `evidence add`) or flag *values* (paths, statuses). Documented
+    limitation, not an oversight: extend only if it proves to matter in
+    practice (KISS).
+    """
+    from robo_cortex.cli.app import build_parser  # deferred: app.py imports
+    # cli.commands at module load time, which imports this module -- a
+    # top-level import here would be circular.
+
+    parser = build_parser("roco")
+    subparsers_action = next(
+        action for action in parser._actions
+        if isinstance(action, argparse._SubParsersAction)
+    )
+    command_names = sorted(subparsers_action.choices)
+
+    case_blocks = []
+    for name in command_names:
+        subparser = subparsers_action.choices[name]
+        flags = sorted({
+            option
+            for action in subparser._actions
+            for option in action.option_strings
+        })
+        flags_str = " ".join(flags)
+        case_blocks.append(
+            f'        {name})\n'
+            f'            COMPREPLY=( $(compgen -W "{flags_str}" -- "$cur") )\n'
+            f'            ;;'
+        )
+
+    return (
+        _TEMPLATE
+        .replace("__COMMANDS__", " ".join(command_names))
+        .replace("__CASES__", "\n".join(case_blocks))
+    )
+
+
+@cli_command("completion")
+def run(args) -> int:
+    if args.shell == "bash":
+        print(_bash_completion_script(), end="")
+    return 0
+
+
+def register(subparsers):
+    p = subparsers.add_parser(
+        "completion", help="Generate a shell completion script"
+    )
+    p.add_argument(
+        "shell", choices=["bash"],
+        help="Shell to generate a completion script for",
+    )
+    p.set_defaults(func=run)

robo_cortex/cli/commands/evidence.py

@@ -0,0 +1,110 @@
+"""Command: roco evidence (add / verify)"""
+
+import json
+import sys
+
+from robo_cortex.core.errors import NotFoundError, RoboCortexError
+from robo_cortex.core.evidence import EVIDENCE_KINDS, attach_evidence, verify_evidence
+from robo_cortex.core.memory import find_memory_store
+from robo_cortex.cli._common import _get_cmd_name, _store, _global_store, cli_command
+
+
+@cli_command("evidence add")
+def run_add(args) -> int:
+    with _store(args.repo) as (repo_root, conn), _global_store() as global_conn:
+        store = find_memory_store(conn, global_conn, args.id, scope=args.scope)
+        result = attach_evidence(
+            store,
+            repo_root,
+            args.id,
+            kind=args.kind,
+            description=args.description,
+            command=args.evidence_command_text,
+            expected_outcome=args.expected,
+            ref=args.ref,
+            cold_storage_content=args.cold_storage_content,
+        )
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(
+            f"Attached evidence {result['evidence_id']} "
+            f"(memory evidence strength: {result['memory_evidence_strength']:.2f})"
+        )
+    return 0
+
+
+@cli_command("evidence verify")
+def run_verify(args) -> int:
+    with _store(args.repo) as (repo_root, conn), _global_store() as global_conn:
+        # evidence rows live in whichever store their memory lives in;
+        # id sequences are independent per store. --scope disambiguates
+        # an id that collides between stores, same as for memory ids.
+        # repo_root is passed regardless of which store the evidence
+        # lives in: it's this invocation's ambient repo context, used to
+        # resolve the Gitea owner/repo via the local git remote
+        # (Stage 10) for gitea_pr/gitea_issue evidence specifically.
+        if args.scope == "repo":
+            result = verify_evidence(conn, args.evidence_id, repo_root)
+        elif args.scope == "global":
+            result = verify_evidence(global_conn, args.evidence_id, repo_root)
+        else:
+            try:
+                result = verify_evidence(conn, args.evidence_id, repo_root)
+            except NotFoundError:
+                result = verify_evidence(global_conn, args.evidence_id, repo_root)
+
+    print(json.dumps(result) if args.json else json.dumps(result, indent=2))
+    return 0
+
+
+def run_no_subcommand(args) -> int:
+    """Called when 'evidence' is invoked without add/verify."""
+    # This will be set as the default func for the evidence parser itself
+    print("error: evidence requires a subcommand (add or verify)", file=sys.stderr)
+    return 1
+
+
+def register(subparsers):
+    p = subparsers.add_parser("evidence", help="Attach or verify evidence")
+    evidence_subparsers = p.add_subparsers(dest="evidence_command")
+
+    # add subcommand
+    p_add = evidence_subparsers.add_parser("add", help="Attach evidence to a memory")
+    p_add.add_argument("id", type=int)
+    p_add.add_argument("--kind", choices=sorted(EVIDENCE_KINDS), required=False, default=None)
+    p_add.add_argument("--description", default=None)
+    # dest="evidence_command_text": argparse shares one flat Namespace across
+    # nested subparsers, so a plain --command flag here would silently
+    # overwrite the top-level dest="command" used for dispatch (every
+    # parser's defaults get written into the same object, whether or not
+    # the flag was actually passed) -- caught by a real CLI invocation
+    # returning the top-level help instead of running, not by inspection.
+    p_add.add_argument(
+        "--command", dest="evidence_command_text", default=None
+    )
+    p_add.add_argument("--expected", default=None)
+    p_add.add_argument("--ref", default=None)
+    p_add.add_argument("--cold-storage-content", dest="cold_storage_content", default=None)
+    p_add.add_argument("--repo", default=None)
+    p_add.add_argument(
+        "--scope", choices=["repo", "global"], default=None,
+        help="Disambiguate a memory id that collides between the repo and global stores",
+    )
+    p_add.add_argument("--json", action="store_true")
+    p_add.set_defaults(func=run_add)
+
+    # verify subcommand
+    p_verify = evidence_subparsers.add_parser("verify", help="Re-verify one evidence row")
+    p_verify.add_argument("evidence_id", type=int)
+    p_verify.add_argument("--repo", default=None)
+    p_verify.add_argument(
+        "--scope", choices=["repo", "global"], default=None,
+        help="Disambiguate an evidence id that collides between the repo and global stores",
+    )
+    p_verify.add_argument("--json", action="store_true")
+    p_verify.set_defaults(func=run_verify)
+
+    # Default handler when no subcommand is given
+    p.set_defaults(func=run_no_subcommand)

robo_cortex/cli/commands/hooks.py

@@ -0,0 +1,149 @@
+"""Command: roco hooks (install / uninstall / status / check)"""
+
+import json
+import sys
+
+from robo_cortex.core.hooks import HOOK_FILENAME, POST_COMMIT_HOOK_FILENAME
+from robo_cortex.core.hooks import install as core_install
+from robo_cortex.core.hooks import status as core_status
+from robo_cortex.core.hooks import uninstall as core_uninstall
+from robo_cortex.core.invalidate import affected as core_affected
+from robo_cortex.cli._common import _get_cmd_name, _store, cli_command
+
+
+def _hook_name(args) -> str:
+    return POST_COMMIT_HOOK_FILENAME if args.post_commit else HOOK_FILENAME
+
+
+@cli_command("hooks install")
+def run_install(args) -> int:
+    hook_name = _hook_name(args)
+    with _store(args.repo) as (repo_root, _conn):
+        result = core_install(repo_root, force=args.force, hook_name=hook_name)
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"Installed {hook_name} hook at {result['path']}")
+        if result["chained"]:
+            print(f"Chained after your existing {hook_name} hook (it still runs first).")
+        if hook_name == POST_COMMIT_HOOK_FILENAME:
+            print("Informational only -- reports affected memories after each commit, never blocks.")
+        else:
+            print("Bypass any time with: git commit --no-verify")
+    return 0
+
+
+@cli_command("hooks uninstall")
+def run_uninstall(args) -> int:
+    hook_name = _hook_name(args)
+    with _store(args.repo) as (repo_root, _conn):
+        result = core_uninstall(repo_root, hook_name=hook_name)
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        if not result["uninstalled"]:
+            print(f"Nothing to remove: {result['reason']}")
+        elif result["deleted"]:
+            print(f"Removed {hook_name} hook at {result['path']}")
+        else:
+            print(f"Removed robo-cortex's block from {result['path']} (your own hook content remains)")
+    return 0
+
+
+@cli_command("hooks status")
+def run_status(args) -> int:
+    hook_name = _hook_name(args)
+    with _store(args.repo) as (repo_root, _conn):
+        result = core_status(repo_root, hook_name=hook_name)
+
+    if args.json:
+        print(json.dumps(result))
+    else:
+        if not result["installed"]:
+            reason = result.get("note", "not installed")
+            print(f"{hook_name} hook: {reason}")
+        else:
+            chained = " (chained after another hook)" if result["chained"] else ""
+            print(f"{hook_name} hook: installed at {result['path']}{chained}")
+    return 0
+
+
+@cli_command("hooks check")
+def run_check(args) -> int:
+    """Run by the installed pre-commit hook itself -- not usually invoked
+    by hand. Checks staged changes against `affected`; exits nonzero (and
+    prints a review block to stderr) only if something needs review.
+    """
+    with _store(args.repo) as (repo_root, conn):
+        result = core_affected(conn, repo_root, staged=True)
+
+    if not result["data"]:
+        return 0
+
+    print(
+        "robo-cortex: this commit touches code linked to memories that need review:",
+        file=sys.stderr,
+    )
+    for item in result["data"]:
+        print(f"  [{item['id']}] {item['reason']}  {item['statement']}", file=sys.stderr)
+    print("", file=sys.stderr)
+    print("Review with: roco show <id>", file=sys.stderr)
+    print(
+        "Then either re-verify (roco status <id> activate --reason \"...\") "
+        "or supersede it, and commit again.",
+        file=sys.stderr,
+    )
+    print("To bypass this check: git commit --no-verify", file=sys.stderr)
+    return 1
+
+
+def register(subparsers):
+    p = subparsers.add_parser("hooks", help="Manage robo-cortex's git hooks (pre-commit, post-commit)")
+    hooks_subparsers = p.add_subparsers(dest="hooks_command")
+
+    p_install = hooks_subparsers.add_parser(
+        "install", help="Install the pre-commit hook (blocks commits touching unreviewed memories)"
+    )
+    p_install.add_argument("--repo", default=None)
+    p_install.add_argument(
+        "--force", action="store_true",
+        help="Chain after an existing non-robo-cortex hook instead of refusing to install",
+    )
+    p_install.add_argument(
+        "--post-commit", action="store_true",
+        help="Install the post-commit hook instead (informational report after each commit, never blocks)",
+    )
+    p_install.add_argument("--json", action="store_true")
+    p_install.set_defaults(func=run_install)
+
+    p_uninstall = hooks_subparsers.add_parser("uninstall", help="Remove robo-cortex's pre-commit hook")
+    p_uninstall.add_argument("--repo", default=None)
+    p_uninstall.add_argument(
+        "--post-commit", action="store_true",
+        help="Remove the post-commit hook instead",
+    )
+    p_uninstall.add_argument("--json", action="store_true")
+    p_uninstall.set_defaults(func=run_uninstall)
+
+    p_status = hooks_subparsers.add_parser("status", help="Show whether the pre-commit hook is installed")
+    p_status.add_argument("--repo", default=None)
+    p_status.add_argument(
+        "--post-commit", action="store_true",
+        help="Report on the post-commit hook instead",
+    )
+    p_status.add_argument("--json", action="store_true")
+    p_status.set_defaults(func=run_status)
+
+    p_check = hooks_subparsers.add_parser(
+        "check", help="Check staged changes against affected memories (used by the installed hook itself)"
+    )
+    p_check.add_argument("--repo", default=None)
+    p_check.set_defaults(func=run_check)
+
+    def _no_subcommand(args) -> int:
+        print("error: hooks requires a subcommand (install, uninstall, status, or check)", file=sys.stderr)
+        return 1
+
+    p.set_defaults(func=_no_subcommand)