substratum-cli 0.1.0__py3-none-any.whl

substratum_cli/session.py

@@ -0,0 +1,558 @@
+"""The persistent session: `substratum` with no args. Two problems, one build.
+
+1. Warm library. The session is ONE process. It loads the v15 library once (in a background
+   thread at startup, via engine.warm()) and every command in the loop reuses it, so the second
+   fix and every fix after is fast. No per-invocation reload.
+2. Claude-Code-style loop. You cd into a repo, run `substratum`, and drive it interactively:
+   `fix <test>`, `verify`, `apply`, `show`, `scaffold-test`, etc., with history and streaming.
+
+The loop dispatches to the SAME command functions the one-shot CLI uses, so behavior, the object
+model, the run store, and the gate are all identical. The session adds no new engine path.
+"""
+from __future__ import annotations
+
+import os
+import shlex
+import sys
+import threading
+import types
+from typing import Optional
+
+from . import codes
+from . import config as _config
+from . import engine
+from . import gitio
+from . import render as _render
+from . import result as _result
+
+_GREEN = "\033[32m"; _CYAN = "\033[36m"; _DIM = "\033[2m"; _BOLD = "\033[1m"; _RESET = "\033[0m"
+
+_COMMANDS = ["fix", "failing", "write", "verify", "apply", "undo", "commit", "runs", "history",
+             "show", "explain", "replay", "attest", "scaffold-test", "summarize", "init", "doctor",
+             "coverage", "help", "exit", "quit"]
+
+_ALL_COMMANDS = set(_COMMANDS) | {"summary", "scaffold", "log", "hist", "tests",
+                                  "login", "logout", "whoami", "?", "h", "q", "e", "bye"}
+
+# commands whose argument is a run-id (for tab-completion + defaulting to the last run)
+_RUNID_CMDS = {"apply", "undo", "commit", "show", "explain", "replay", "attest"}
+
+
+class Session:
+    def __init__(self, repo: str, color: bool = True):
+        self.repo = os.path.abspath(repo)
+        self.color = color and sys.stdout.isatty()
+        self.last_run: Optional[str] = None
+        self.last_applied: Optional[str] = None
+        self._history: list = []          # session-scoped command history (bash-style !N / !! recall)
+        self._warm_done = threading.Event()
+        self._warm_ok = False
+
+    # ---- warm library (background) --------------------------------------
+    def start_warm(self) -> None:
+        def _w():
+            try:
+                self._warm_ok = engine.warm()
+            except Exception:
+                self._warm_ok = False
+            finally:
+                self._warm_done.set()
+                self._announce_warm()      # ALWAYS resolve: ready OR "loads on first use", never silent
+        threading.Thread(target=_w, daemon=True).start()
+
+    def _announce_warm(self) -> None:
+        """Print a one-line completion notice (on its own line) and redraw the prompt, so the banner's
+        background 'loading' state always resolves visibly instead of appearing stuck."""
+        from . import style as S
+        if self._warm_ok:
+            line = self._paint("  " + S.g("lamp") + " library ready", S.PROVEN)
+        else:
+            line = self._paint("  " + S.g("dot") + " library will load on first use", S.CHROME)
+        try:
+            sys.stdout.write("\n" + line + "\n")
+            sys.stdout.flush()
+            import readline
+            readline.redisplay()
+        except Exception:
+            pass
+
+    def _await_warm(self) -> None:
+        """fix needs the library; block on the warm if it is still loading, with a note."""
+        if not self._warm_done.is_set():
+            self._say("  loading the library (once per session)...", _DIM)
+            self._warm_done.wait()
+
+    # ---- rendering helpers ----------------------------------------------
+    def _paint(self, s: str, c: str) -> str:
+        return f"{c}{s}{_RESET}" if self.color else s
+
+    def _say(self, s: str, c: str = "") -> None:
+        sys.stdout.write((self._paint(s, c) if c else s) + "\n")
+        sys.stdout.flush()
+
+    def _render(self, res: "_result.SubstratumResult") -> None:
+        sys.stdout.write(_render.render_human(res, color="always" if self.color else "never"))
+        if res.verdict in (codes.VERIFIED, codes.PASS) and res.run_id.startswith("sub_"):
+            self.last_run = res.run_id
+
+    # ---- banner (the Sovereign Seal letterhead) --------------------------
+    def banner(self) -> None:
+        from . import style as S
+        c = self.color
+        pn = S.Painter(c)
+        name = os.path.basename(self.repo)
+        langs, files = self._repo_summary()
+        lib = engine.lib_roots.py_library_root()
+        libname = os.path.basename(lib) if lib else "none"
+        warm_lit = engine.is_warm()
+        dot = pn(S.g("dot"), S.CHROME)
+        # honest, self-resolving state: a live "warming" label the banner can never update reads as
+        # stuck; instead say it loads in the background (a "library ready" line prints when done).
+        if warm_lit:
+            state = pn(S.g("lamp") + " ready", S.PROVEN)
+        else:
+            state = pn("loading in background", S.CHROME)
+        self._say(pn(S.g("brand") + " SUBSTRATUM", S.BOLD) +
+                  pn(f"  proof-carrying code engine", S.LABEL))
+        self._say(pn(S.g("bar") * S.width(), S.CHROME))
+        self._say(f" {pn('REPO', S.LABEL)}     {name}  {pn(f'{files} files {dot} ' + (langs or ''), S.LABEL)}")
+        self._say(f" {pn('LIBRARY', S.LABEL)}  {libname}  {state}")
+        self._say(pn(S.g("bar") * S.width(), S.CHROME))
+        self._say(pn(" fix " + dot + " write " + dot + " verify " + dot + " summarize " + dot
+                     + " apply " + dot + " undo " + dot + " commit " + dot + " runs " + dot
+                     + " help " + dot + " /exit", S.LABEL))
+        self._say(pn(" new here? ", S.CHROME) + pn("just ask", S.GOLD)
+                  + pn(' — ', S.CHROME) + pn('"what does this codebase do?"', S.GOLD)
+                  + pn("   or type ", S.CHROME) + pn("summarize", S.GOLD))
+
+    def _repo_summary(self):
+        # SAME census as `summarize` (langscan.LANGS, prune dist/build) so the banner headline
+        # never contradicts the summarize CODEBASE line. Returns ("294 ts · 8 py · 2 js", total).
+        from . import langscan
+        counts: dict = {}
+        for root, dirs, fs in os.walk(self.repo):
+            dirs[:] = [d for d in dirs if d not in
+                       (".git", "node_modules", ".venv", "venv", "__pycache__", ".substratum",
+                        "dist", "build")]
+            for f in fs:
+                lang = langscan.LANGS.get(os.path.splitext(f)[1])
+                if lang:
+                    counts[lang] = counts.get(lang, 0) + 1
+        total = sum(counts.values())
+        brk = "  ".join(f"{n} {k}" for k, n in sorted(counts.items(), key=lambda x: -x[1]))
+        return brk, total
+
+    # ---- the dispatcher (pure; the REPL and tests both call this) --------
+    def handle(self, line: str):
+        """Return (result_or_None, keep_going). Streams stages for fix."""
+        line = line.strip()
+        if not line:
+            return None, True
+        # bash-style session-history recall: !!  (last), !N (by index), !<prefix> (last match)
+        if line.startswith("!") and line != "!":
+            recalled = self._recall(line[1:])
+            if recalled is None:
+                self._say(f"  no history match for  {line}", _CYAN)
+                return None, True
+            self._say("  " + self._paint(recalled, _DIM))       # echo what is being re-run
+            line = recalled
+        try:
+            parts = shlex.split(line)
+        except ValueError:
+            self._say("  parse error", _CYAN)
+            return None, True
+        cmd, args = parts[0], parts[1:]
+        if cmd and cmd[0] in "/:\\":       # Claude-Code-style slash/colon commands: /exit, :q, ...
+            cmd = cmd[1:]
+        # record every real command in the session history (not history/exit itself)
+        if cmd.lower() not in ("history", "hist", "exit", "quit", "q", "e", "bye"):
+            self._history.append(line)
+
+        # natural-language prompt ("can you summarize this codebase?") -> route to a command,
+        # deterministically (closed-class, no LLM), echoing the interpretation. Structured commands
+        # (a known leading verb) bypass this entirely.
+        if cmd.lower() not in _ALL_COMMANDS:
+            routed = self._route_nl(line)
+            if routed is None:
+                self._say("  not a command. try:  summarize " + "·" +
+                          " fix <test> · verify · write \"...\" · help", _CYAN)
+                return None, True
+            cmd, args = routed
+        else:
+            cmd = cmd.lower()
+
+        if cmd in ("exit", "quit", "q", "e", "bye"):
+            return None, False
+        if cmd in ("help", "?", "h"):
+            self._help()
+            return None, True
+        if cmd == "coverage" or cmd == "init":
+            from .commands.init_cmd import cmd_init
+            return cmd_init(self.repo, run_flake=(cmd == "init")), True
+        if cmd == "doctor":
+            from .commands.init_cmd import cmd_doctor
+            return cmd_doctor(self.repo), True
+        if cmd in ("failing", "tests"):
+            return self._failing(args), True
+        if cmd == "fix":
+            return self._fix(args), True
+        if cmd == "write":
+            return self._write(args), True
+        if cmd in ("summarize", "summary"):
+            from . import product_ops
+            self._say("  reading the codebase...", _DIM)
+            return product_ops.op_summarize_repo(self.repo), True
+        if cmd == "verify":
+            return self._verify(args), True
+        if cmd in ("login", "logout", "whoami"):
+            from .commands import auth
+            {"login": auth.cmd_login, "logout": auth.cmd_logout, "whoami": auth.cmd_whoami}[cmd]()
+            return None, True
+        if cmd in ("history", "hist"):
+            self._history_cmd()
+            return None, True
+        if cmd in ("runs", "log"):
+            from .commands.history import cmd_runs
+            return cmd_runs(self.repo), True
+        if cmd == "apply":
+            return self._run_id_cmd("apply", args), True
+        if cmd == "undo":
+            return self._run_id_cmd("undo", args), True
+        if cmd == "commit":
+            return self._run_id_cmd("commit", args), True
+        if cmd == "show":
+            return self._run_id_cmd("show", args), True
+        if cmd == "explain":
+            return self._run_id_cmd("explain", args), True
+        if cmd == "replay":
+            return self._run_id_cmd("replay", args), True
+        if cmd == "attest":
+            return self._run_id_cmd("attest", args), True
+        if cmd in ("scaffold-test", "scaffold"):
+            from .commands.scaffold import cmd_scaffold_test
+            if not args:
+                self._say("  usage: scaffold-test <file.py::fn>", _CYAN)
+                return None, True
+            return cmd_scaffold_test(self.repo, args[0]), True
+        self._say(f"  unknown command: {cmd}  (try `help`)", _CYAN)
+        return None, True
+
+    # ---- session-scoped command history (bash-style recall) -------------
+    def _recall(self, token: str):
+        h = self._history
+        if not h:
+            return None
+        token = token.strip()
+        if token in ("", "!"):                       # !!  -> the last command
+            return h[-1]
+        if token.lstrip("-").isdigit():              # !N (1-indexed) or !-N (from the end)
+            i = int(token)
+            idx = len(h) + i if i < 0 else i - 1
+            return h[idx] if 0 <= idx < len(h) else None
+        for c in reversed(h):                        # !<prefix> -> most recent match
+            if c.startswith(token):
+                return c
+        return None
+
+    def _history_cmd(self):
+        if not self._history:
+            self._say("  no commands yet this session", _DIM)
+            return
+        self._say(self._paint("  session history", _BOLD))
+        start = max(1, len(self._history) - 29)
+        for i, c in enumerate(self._history[-30:], start):
+            self._say(f"  {self._paint(str(i).rjust(3), _DIM)}  {c}")
+        self._say(self._paint("  re-run:  !<n>  ·  !!  ·  !<prefix>", _DIM))
+
+    # ---- natural-language router (closed-class, deterministic, no LLM) ----
+    def _route_nl(self, line: str):
+        """Map a plain prompt to (command, args). Regex/keyword only; echoes the INTERPRETATION
+        (the CSF parser discipline). Returns None if no confident route."""
+        import re
+        low = line.lower().strip().rstrip("?.! ")
+
+        def interp(text):
+            self._say(f"  interpreted as: {text}", _DIM)
+
+        # explicit `fix <id>` wins first, so a named test is never swallowed by summarize/verify.
+        # id = pytest nodeid / a .py path / a real test_* token (word-bounded, not any 'test' substring)
+        ids = [w for w in line.split()
+               if ("::" in w or w.endswith(".py") or re.search(r"(^|[/_])test_", w)
+                   or re.search(r"_test($|[.:])", w)) and not w.startswith("-")]
+        if re.search(r"\bfix\b", low) and ids:
+            interp("fix " + " ".join(ids))
+            return ("fix", ids)
+        # discover failing tests (an observation) -- distinct from `fix <id>` and from `verify`
+        if "fix" not in low and (
+                re.search(r"\bfailing tests?\b", low)
+                or re.search(r"\b(find|show|list|what|which|any|are there|run)\b"
+                             r".{0,24}\b(failing|broken|red|the)?\s*(tests?|suite)\b", low)
+                or re.search(r"\bwhat(?:'s| is| are)\b.{0,20}\b(failing|broken)\b", low)):
+            interp("find failing tests")
+            return ("failing", [])
+        # summarize the codebase -- bare describe/overview/what MUST name a codebase object
+        # (so "describe the algorithm" does NOT route); a literal 'summarize'/'tldr' is enough alone.
+        if re.search(r"\b(summar\w+|tl;?dr)\b", low) or \
+           re.search(r"\b(describe|overview|walk me through|what(?:'s| is| does| do| are)?)\b"
+                     r".{0,40}\b(code|codebase|repo|repository|project|module|files?)\b", low):
+            interp("summarize the codebase")
+            return ("summarize", [])
+        # verify current changes -- 'verify' is unambiguous; gate/check/review/validate need a change object
+        if re.search(r"\bverif(?:y|ies)\b", low) or \
+           re.search(r"\b(gate|check|review|validate)\b.{0,30}"
+                     r"\b(change|changes|diff|edit|edits|patch|work|code)\b", low):
+            interp("verify the current changes")
+            return ("verify", [])
+        # fix, no id named yet -- only on an explicit fix+failure phrase, not a bare 'fix'
+        if re.search(r"\bfix\b.{0,30}\b(test|tests|failing|failure|broken|red)\b", low) or \
+           re.search(r"\b(failing|broken)\b.{0,20}\btest", low):
+            interp("fix (name the failing test)")
+            return ("fix", [])
+        # run history / the proof ledger
+        if low in ("runs", "log") or \
+           re.search(r"\b(run history|recent runs|show (me )?(the )?runs|history of runs|"
+                     r"the ledger|what have you (done|run|fixed|verified))\b", low):
+            interp("show run history")
+            return ("runs", [])
+        # undo / revert the last applied run
+        if re.search(r"\b(undo|revert|roll\s?back|take (it|that) back)\b", low):
+            interp("undo the last applied run")
+            return ("undo", [])
+        # commit the last verified run
+        if re.search(r"\bcommit\b", low):
+            interp("commit the last verified run")
+            return ("commit", [])
+        # coverage / capabilities
+        if re.search(r"\b(coverage|what can you (do|gate|handle)|what do you (support|cover))\b", low):
+            interp("show the coverage contract")
+            return ("coverage", [])
+        if re.search(r"\b(^help$|how do i|what commands|list commands)\b", low) or low == "help":
+            interp("help")
+            return ("help", [])
+        # write intent needs a signature -> guide rather than guess it
+        if re.search(r"\b(write|create|build|make|generate|implement)\b.{0,40}"
+                     r"\b(function|method|class|code|helper)\b", low):
+            self._say('  to write from intent, name the shape:  '
+                      'write "<what it should do>" --sig "name(args)"', _CYAN)
+            return None
+        return None
+
+    # ---- command bodies --------------------------------------------------
+    def _failing(self, args):
+        """Discover failing tests by running the repo's suite, then offer to fix one/all inline."""
+        from .commands.failing import cmd_failing
+        path = args[0] if args else None
+        self._say("  running the test suite (read-only)...", _DIM)
+        res = cmd_failing(self.repo, path=path)
+        f = (res.data or {}).get("failing") or []
+        if not f:
+            return res                                   # all-pass / could-not-run -> just render it
+        self._render(res)                                # show the failing list
+        n = len(f)
+        try:
+            pick = input(self._paint(f"  fix which? [1-{n} / a=all / enter to skip] ",
+                                     _CYAN)).strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            sys.stdout.write("\n")
+            return None
+        if pick in ("a", "all"):
+            self._await_warm()
+            from . import product_ops
+
+            def emit(stage, text):
+                self._say(f"  {stage:7} {text}", _DIM)
+            return product_ops.op_fix_from_failing_test(self.repo, f, emit=emit)
+        if pick.isdigit() and 1 <= int(pick) <= n:
+            return self._fix([f[int(pick) - 1]])
+        return None                                      # skipped: the list was already shown
+
+    def _fix(self, args):
+        from . import product_ops
+        if not args:
+            self._say("  usage: fix <test-id> [<test-id> ...]", _CYAN)
+            return None
+        self._await_warm()
+
+        def emit(stage, text):
+            self._say(f"  {stage:7} {text}", _DIM)
+        return product_ops.op_fix_from_failing_test(self.repo, list(args), emit=emit)
+
+    def _write(self, args):
+        from . import product_ops
+        # write <intent...> --sig "name(args)" [--into file]
+        sig, into, words = "", None, []
+        i = 0
+        while i < len(args):
+            if args[i] == "--sig" and i + 1 < len(args):
+                sig = args[i + 1]; i += 2; continue
+            if args[i] == "--into" and i + 1 < len(args):
+                into = args[i + 1]; i += 2; continue
+            words.append(args[i]); i += 1
+        intent = " ".join(words).strip().strip('"').strip("'")
+        if not intent or not sig:
+            self._say('  usage: write "<intent>" --sig "name(args)" [--into <file>]', _CYAN)
+            return None
+        self._await_warm()
+
+        def emit(stage, text):
+            self._say(f"  {stage:7} {text}", _DIM)
+        res = product_ops.op_write_from_intent(self.repo, intent, sig, into=into, emit=emit)
+
+        # interactive clarification: show the plain-English options, take a pick, re-resolve
+        cl = res.data.get("clarify") if res.data else None
+        if cl and cl.get("options"):
+            self._render(res)
+            n = len(cl["options"])
+            try:
+                pick = input(self._paint(f"  which? [1-{n}] (enter to skip) ", _CYAN)).strip()
+            except (EOFError, KeyboardInterrupt):
+                sys.stdout.write("\n")
+                return None
+            if pick.isdigit() and 1 <= int(pick) <= n:
+                chosen = cl["options"][int(pick) - 1]
+                self._say(f"  resolving: {chosen['text']}", _DIM)
+                return product_ops.op_write_from_intent(
+                    self.repo, intent, sig, into=into, emit=emit,
+                    prefer_purpose=chosen.get("purpose"))
+            return None      # skipped: the ASK was already shown
+        return res
+
+    def _verify(self, args):
+        from .commands.verify import run_verify
+        # flags: --staged, --test <t> (repeatable). default = working-tree diff.
+        staged = "--staged" in args
+        tests = [args[i + 1] for i, a in enumerate(args) if a == "--test" and i + 1 < len(args)]
+        diff = gitio.staged_diff(self.repo) if staged else gitio.diff_head(self.repo)
+        if not diff.strip():
+            self._say("  no changes to verify (working tree clean)", _DIM)
+            return None
+        return run_verify(self.repo, diff, tuple(tests))
+
+    def _run_id_cmd(self, name, args):
+        rid = args[0] if args else (self.last_applied or self.last_run)
+        if not rid:
+            self._say(f"  usage: {name} <run-id>   (or run a fix first)", _CYAN)
+            return None
+        if name == "apply":
+            from .commands.apply import cmd_apply
+            res = cmd_apply(self.repo, rid)
+            if res.verdict in (codes.VERIFIED, codes.PASS):
+                self.last_applied = rid          # undo/commit default to the last applied run
+            return res
+        if name == "undo":
+            from .commands.undo import cmd_undo
+            res = cmd_undo(self.repo, rid)
+            if res.verdict in (codes.VERIFIED, codes.PASS):
+                self.last_applied = None
+            return res
+        if name == "commit":
+            from .commands.commit import cmd_commit
+            return cmd_commit(self.repo, rid)
+        if name == "show":
+            from .commands.show import cmd_show
+            return cmd_show(self.repo, rid)
+        if name == "replay":
+            from .commands.replay import cmd_replay
+            return cmd_replay(self.repo, rid)
+        from .commands.explain import cmd_explain, cmd_attest
+        return cmd_attest(self.repo, rid) if name == "attest" else cmd_explain(self.repo, rid)
+
+    def _help(self):
+        self._say(self._paint("  commands:", _BOLD))
+        for line in [
+            "  failing               run the suite, list failing tests, offer to fix one/all",
+            "  fix <test>            produce a verified fix for a failing test (or a named refusal)",
+            "  write \"<intent>\" --sig \"name(args)\"   derive code from intent (asks if ambiguous)",
+            "  summarize             describe this codebase in plain English",
+            "  verify [--staged]     gate your current changes (add --test <id> to name the warrant)",
+            "  apply [<run>]         apply a verified run (defaults to the last fix)",
+            "  undo / commit [<run>] revert an applied run, or commit it with a proof message",
+            "  runs                  the proof store: run history + refusal->verified ledger",
+            "  history               commands run this session   (re-run with  !<n> / !! / !<prefix>)",
+            "  show / explain / replay / attest [<run>]",
+            "  scaffold-test <t>     emit a runnable failing test that pins intent",
+            "  coverage | init       what this repo can gate vs refuse; init also flake-scans",
+            "  doctor                harness / env / air-gap checks",
+            "  help | /exit",
+            "",
+            "  or just ask: \"can you summarize this codebase?\"  \"verify my changes\"  \"fix <test>\"",
+        ]:
+            self._say(self._paint(line, _DIM))
+
+    # ---- the loop --------------------------------------------------------
+    def repl(self) -> int:
+        global _COMPLETER_REPO
+        _COMPLETER_REPO = self.repo      # so tab-completion can offer this repo's run ids
+        try:
+            import readline  # noqa: F401  (history + arrow keys, tab-complete below)
+            readline.set_completer(_completer)
+            readline.set_completer_delims(" \t")
+            readline.parse_and_bind("tab: complete")
+            # slash-preview: a single tab reveals + narrows the command menu as you type
+            readline.parse_and_bind("set show-all-if-ambiguous on")
+            readline.parse_and_bind("set show-all-if-unmodified on")
+            readline.parse_and_bind("set completion-ignore-case on")
+        except Exception:
+            pass
+        self.start_warm()
+        self.banner()
+        from . import style as S
+        prompt = (S.GOLD + S.g("brand") + " " + S.RESET) if self.color else (S.g("brand") + " ")
+        while True:
+            try:
+                line = input(prompt)
+            except EOFError:
+                sys.stdout.write("\n")
+                return 0
+            except KeyboardInterrupt:
+                sys.stdout.write("\n")
+                continue
+            try:
+                res, keep = self.handle(line)
+                if res is not None:
+                    self._render(res)
+            except KeyboardInterrupt:
+                # Ctrl-C cancels the CURRENT action and drops back to the prompt; the warm library
+                # (loaded once, the whole point of the session) survives. Never a traceback.
+                sys.stdout.write("\n")
+                self._say("  cancelled (session still warm)", _CYAN)
+                continue
+            except Exception as e:  # a command fault must not kill the session
+                self._say(f"  error: {e}", _CYAN)
+                continue
+            if not keep:
+                return 0
+
+
+_COMPLETER_REPO = None   # set by repl() so the completer can offer this repo's run ids
+
+
+def _completer(text, state):
+    # completing the ARGUMENT of a run-id command -> offer stored run ids
+    try:
+        import readline
+        line = readline.get_line_buffer()
+    except Exception:
+        line = text
+    parts = line.split()
+    first = parts[0].lstrip("/:\\").lower() if parts else ""
+    completing_arg = bool(parts) and (len(parts) >= 2 or line.endswith(" "))
+    if first in _RUNID_CMDS and completing_arg and _COMPLETER_REPO:
+        try:
+            from . import run_store
+            ids = [r for r in run_store.run_ids(_COMPLETER_REPO) if r.startswith(text)]
+        except Exception:
+            ids = []
+        return ids[state] if state < len(ids) else None
+    # otherwise complete the command verb (slash/colon-prefixed too: '/f' -> '/fix')
+    pfx = text[:1] if text[:1] in "/:" else ""
+    body = text[len(pfx):].lower()
+    opts = [pfx + c for c in _COMMANDS if c.startswith(body)]
+    return opts[state] if state < len(opts) else None
+
+
+def run_session(repo: str, color: bool = True) -> int:
+    if not gitio.is_git_repo(os.path.abspath(repo)):
+        sys.stderr.write("substratum: not a git repository. cd into a repo first.\n")
+        return codes.EXIT_USAGE
+    return Session(repo, color=color).repl()