substratum-cli 0.2.8__tar.gz → 0.2.9__tar.gz

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substratum-cli
-Version: 0.2.8
+Version: 0.2.9
 Summary: Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.
 Author: Substratum
 License: LicenseRef-Proprietary

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli/__init__.py

@@ -5,4 +5,4 @@ Import budget: this package is stdlib-only; the ONLY module reaching into backen
 """
 # SINGLE SOURCE OF TRUTH for the release version. pyproject reads this (dynamic version), the boot shows
 # it, and the update-check compares against it. To cut a release, bump ONLY this line, then publish.
-__version__ = "0.2.8"
+__version__ = "0.2.9"

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli/_boot.py

@@ -86,9 +86,8 @@ def render(name, census, langs, substrate, substrate_note, substrate_ok, standin
 
     # ---- WORDMARK + tagline ----
     wm = " ".join("SUBSTRATUM")
-    tag = "proof-carrying code engine" + c(CH, "  ·  ") + "zero-LLM" + c(CH, "  ·  ") + "deterministic"
-    out += ["", "  " + c(L + B, wm) + "      " + c(LAB, "proof-carrying code engine")
-            + c(CH, f"  {dot}  ") + c(LAB, "zero-LLM") + c(CH, f"  {dot}  ") + c(LAB, "deterministic"), ""]
+    out += ["", "  " + c(L + B, wm) + "      " + c(LAB, "Proof-Carrying Code Engine")
+            + c(CH, f"  {dot}  ") + c(LAB, "Zero-LLM") + c(CH, f"  {dot}  ") + c(LAB, "Deterministic"), ""]
 
     # ---- the CERTIFICATE ----
     tl, tr, bl, br, h_, v_, ml, mr = ("+", "+", "+", "+", "-", "|", "+", "+") if ascii_mode \

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli/commands/auth.py

@@ -1,6 +1,7 @@
 """`login` / `logout` / `whoami` -- connect the thin client to the hosted engine via GitHub."""
 from __future__ import annotations
 
+import os
 import sys
 
 from .. import account, remote
@@ -23,7 +24,14 @@ def cmd_login() -> int:
 
 
 def cmd_logout() -> int:
+    if not account.is_logged_in():
+        sys.stdout.write("  not logged in -- nothing to disconnect.\n")
+        return 0
     account.clear()
+    if os.environ.get("SUBSTRATUM_TOKEN"):
+        sys.stdout.write("  saved login cleared, but SUBSTRATUM_TOKEN is set in this shell and "
+                         "still authenticates -- unset it to fully disconnect.\n")
+        return 0
     sys.stdout.write("  logged out (local commands still work offline).\n")
     return 0
 

substratum_cli-0.2.9/substratum_cli/commands/where.py

@@ -0,0 +1,137 @@
+"""`where <words>` -- ground plain-English domain terms against THIS repo: which files and lines
+carry the feature the user named. The answer to "can we remove the spending check option from the
+workflows section?" is never "not a command": it is WHERE that feature lives, plus the honest
+ladder to a verified change (scaffold-test pins the behavior -> fix derives against it).
+
+Deterministic and engine-free: term extraction is closed-class (stopwords out, identifier variants
+generated -- snake/camel/pascal/kebab/joined), the search is `git grep` at the working tree, and
+ranking is by variant specificity (a compound identifier hit outweighs a bare word). Results are a
+first-class stored run.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+
+from .. import codes, run_store, runid
+from .. import result as _result
+
+_STOP = frozenset("""a an the can could we you i it is are was be do does did please help want
+need from in on of to for and or with our my your this that these those app application website
+site page section sections option options button tab menu part area remove delete disable enable
+add create rename move change modify update refactor hide show make let lets get put set fix
+""".split())
+
+_MAX_FILES = 8
+_MAX_HITS_PER_FILE = 3
+
+
+def extract_terms(text: str) -> list:
+    """Content words, in order, stopwords and non-words dropped."""
+    words = re.findall(r"[A-Za-z][A-Za-z0-9_-]{2,}", (text or "").lower())
+    return [w for w in words if w not in _STOP]
+
+
+def identifier_variants(terms: list) -> list:
+    """The code shapes adjacent term pairs (and singles) take: spending+check ->
+    spending_check / spendingCheck / SpendingCheck / spending-check / spendingcheck.
+    Compounds first (highest specificity), then the singles."""
+    out, seen = [], set()
+
+    def add(v, weight):
+        if v.lower() not in seen:
+            seen.add(v.lower())
+            out.append((v, weight))
+
+    for a, b in zip(terms, terms[1:]):
+        add(f"{a}_{b}", 5)
+        add(f"{a}{b[:1].upper()}{b[1:]}", 5)
+        add(f"{a[:1].upper()}{a[1:]}{b[:1].upper()}{b[1:]}", 5)
+        add(f"{a}-{b}", 5)
+        add(f"{a} {b}", 4)
+    for t in terms:
+        add(t, 1)
+    return out
+
+
+def _git_grep(repo: str, needle: str) -> list:
+    """[(path, line_no, line_text)] for a fixed-string, case-insensitive working-tree grep."""
+    r = subprocess.run(["git", "grep", "-I", "-i", "-n", "-F", needle],
+                       cwd=repo, capture_output=True, text=True, errors="replace", timeout=30)
+    hits = []
+    for ln in r.stdout.splitlines()[:400]:
+        parts = ln.split(":", 2)
+        if len(parts) == 3 and parts[1].isdigit():
+            if len(parts[2]) > 500:      # a line that long is a data blob or minified, not code
+                continue
+            hits.append((parts[0], int(parts[1]), parts[2].strip()[:100]))
+    return hits
+
+
+def ground_terms(repo: str, text: str) -> dict:
+    """The grounding: variants -> git grep -> files ranked by RARITY-WEIGHTED presence. A variant
+    hitting 3 files is a signal; one hitting 80 files ('check') is noise -- its weight is divided
+    by its spread. Presence counts once per (file, variant); sample lines come from the strongest
+    variant that hit the file, so the display shows the most specific evidence."""
+    terms = extract_terms(text)
+    variants = identifier_variants(terms)
+    per_variant: dict = {}
+    matched_variants: list = []
+    for needle, weight in variants:
+        hits = _git_grep(repo, needle)
+        if not hits:
+            continue
+        matched_variants.append(needle)
+        by_file: dict = {}
+        for path, line_no, line in hits:
+            by_file.setdefault(path, []).append({"line": line_no, "text": line, "term": needle})
+        per_variant[needle] = (weight, by_file)
+    file_score: dict = {}
+    file_best: dict = {}          # path -> (effective weight of its strongest variant, samples)
+    for needle, (weight, by_file) in per_variant.items():
+        spread = len(by_file)
+        eff = weight if spread <= 3 else weight * 3.0 / spread    # rarity: spread dilutes weight
+        for path, samples in by_file.items():
+            file_score[path] = file_score.get(path, 0.0) + eff
+            if path not in file_best or eff > file_best[path][0]:
+                file_best[path] = (eff, samples[:_MAX_HITS_PER_FILE])
+    ranked = sorted(file_score.items(), key=lambda kv: -kv[1])[:_MAX_FILES]
+    if ranked:                    # a file at <5% of the leader is a substring accident, not a place
+        floor = ranked[0][1] / 20.0
+        ranked = [(p, s) for p, s in ranked if s >= floor]
+    return {"terms": terms, "variants_matched": matched_variants,
+            "files": [{"path": p, "score": round(s, 2), "hits": file_best[p][1]}
+                      for p, s in ranked]}
+
+
+def next_steps(files: list) -> list:
+    """The engineer's honest path from here. `open <n>` is the concrete move that works today: go to
+    the strongest match and make the change. The PROOF path is stated truthfully -- `verify` gates an
+    edit only against a test that pins the intended behavior (a bare verify on a hand edit reports,
+    it never proves), so the warrant step is named, not skipped. No `commit` here: commit follows a
+    PASS, and nothing is proven yet."""
+    if not files:
+        return []
+    top = files[0]
+    hits = top.get("hits") or []
+    name = top["path"].rsplit("/", 1)[-1]
+    loc = f"{name}:{hits[0]['line']}" if hits else name
+    return [
+        {"cmd": "open 1", "note": f"the strongest match ({loc}); open it and make the change"},
+        {"cmd": "verify --test <t>",
+         "note": "prove the edit against a test that pins the behavior (scaffold-test writes one)"},
+    ]
+
+
+def cmd_where(repo: str, text: str) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, key = runid.compute(repo, "where", {"text": " ".join(extract_terms(text))})
+    g = ground_terms(repo, text)
+    res = _result.make(codes.PASS, rid, "where",
+                       data={"query": text, **g,
+                             "next_steps": next_steps(g["files"]),
+                             "ladder": ("scaffold-test pins the wanted behavior as a failing "
+                                        "test; fix then derives a verified change against it")})
+    run_store.store_run(repo, res, run_key=key)
+    return res

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli/render.py

@@ -347,6 +347,27 @@ def render_human(res: SubstratumResult, stream=None, color: str | None = None) -
                  lab_col=(S.verdict_color(codes.FAIL) if st == "regressed" else None))
         out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
 
+    # ---- where: domain terms grounded in this repo ----
+    if res.operation == "where" and res.data:
+        d = res.data
+        files = d.get("files") or []
+        body("WHERE", f"{len(files)} place(s) carry {', '.join(d.get('variants_matched') or d.get('terms') or [])[:60]}"
+             if files else f"nothing in this repo matches {', '.join(d.get('terms') or [])[:60]}")
+        for i, f in enumerate(files, 1):
+            out.append(f"{rail}   {p(str(i).rjust(2), S.CHROME)}  {p(f['path'], S.PROVEN)}")
+            for h in f.get("hits", [])[:2]:
+                out.append(f"{rail}       {p('L' + str(h['line']) + '  ' + h['text'][:68], S.CHROME)}")
+        out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
+        if files:
+            steps = d.get("next_steps") or []
+            cw = max((len(s["cmd"]) for s in steps), default=8)   # align notes to the widest command
+            for i, stp in enumerate(steps):
+                lead = p("next".ljust(6), S.LABEL) if i == 0 else " " * 6
+                out.append(f"  {lead} {p(stp['cmd'].ljust(cw), S.GOLD)}  {p(stp['note'], S.CHROME)}")
+            if not steps:   # runs stored before next_steps existed
+                out.append(f"  {p('next'.ljust(6), S.LABEL)} "
+                           f"{p('scaffold-test pins the wanted behavior; fix derives against it', S.GOLD)}")
+
     # ---- rules: standing preferences (intent made cumulative, recalled every build) ----
     if res.operation == "rules" and res.data:
         d = res.data
@@ -480,7 +501,7 @@ def render_human(res: SubstratumResult, stream=None, color: str | None = None) -
 
         out.append(p(S.g("foot") + S.g("bar") * 2, vcol))
         if not sm.get("full"):                     # the map is the summary; --full is the full reference
-            out.append(f"  {p('detail'.ljust(6), S.LABEL)} {p('substratum summarize --full', S.GOLD)}"
+            out.append(f"  {p('next'.ljust(6), S.LABEL)} {p('summarize --full'.ljust(8), S.GOLD)}"
                        + p(f"   every one of {sm['functions']} functions {S.g('dot')} {sm['types']} types",
                            S.CHROME))
         return "\n".join(out) + "\n"

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli/session.py

@@ -38,7 +38,8 @@ _ALL_COMMANDS = set(_COMMANDS) | {"summary", "scaffold", "log", "hist", "tests",
                                   "login", "logout", "whoami", "?", "h",
                                   # session-state (the project-memory moat)
                                   "why", "blame-decision", "blame", "recheck",
-                                  "remember", "forget", "rules", "sessions", "gc"}
+                                  "remember", "forget", "rules", "sessions", "gc",
+                                  "where", "locate", "open"}
 
 # commands whose argument is a run-id (for tab-completion + defaulting to the last run)
 _RUNID_CMDS = {"apply", "undo", "commit", "show", "explain", "replay", "attest"}
@@ -63,6 +64,7 @@ class Session:
         self.last_run: Optional[str] = None
         self.last_applied: Optional[str] = None
         self.last_op: Optional[str] = None
+        self._last_places: list = []           # files from the last `where`, for `open <n>`
         # PERSISTENT recall: the build's query trail carries across sessions (!N / !! / up-arrow see the
         # whole build, not just this process). Seeded from the ledger; appended to it on every query.
         from . import build_state
@@ -249,7 +251,7 @@ class Session:
         rail = ("\033[38;5;154m▌\033[0m" if (self.color and not ascii_mode) else "|")
         brand = (f"\033[38;5;154m{S.g('brand')}\033[0m" if (self.color and not ascii_mode)
                  else pn(S.g("brand"), S.PROVEN))
-        self._say(brand + " " + pn("SUBSTRATUM", S.BOLD) + pn("   proof-carrying · deterministic", S.LABEL))
+        self._say(brand + " " + pn("SUBSTRATUM", S.BOLD) + pn("   Proof-Carrying · Deterministic", S.LABEL))
         self._say(f"  {rail} " + pn(name, S.BOLD) + "  " + pn(census, S.LABEL))
         self._say(f"  {rail} " + pn(substrate, S.LABEL) + "  " + state)
         if st:
@@ -314,6 +316,9 @@ class Session:
             # balanced quotes and never take this path.
             parts = line.split()
         cmd, args = parts[0], parts[1:]
+        # the pasted shell form ('substratum summarize --full') works verbatim in-session, flags kept
+        if cmd.lower() == "substratum" and args:
+            cmd, args = args[0], args[1:]
         slashed = bool(cmd) and cmd[0] in "/:\\"    # /exit, :q -- an explicit control command
         if slashed:
             cmd = cmd[1:]
@@ -364,6 +369,19 @@ class Session:
                 else:
                     self._say("  usage: why <file-or-symbol>   (e.g.  why auth.py)", _CYAN)
                     return None, True
+            # `open` takes a result number or a path -- a sentence ('open a pull request') is not a
+            # target; re-route it so prose beginning with 'open' never hits the editor door. A bare
+            # token that is a real file (Makefile, LICENSE) counts as a target even without a dot.
+            elif cmd == "open" and (not args or not (
+                    args[0].isdigit()
+                    or any(c in args[0] for c in "./_:\\")
+                    or os.path.exists(os.path.join(self.repo, args[0].split(":", 1)[0])))):
+                rerouted = self._route_nl(line)
+                if rerouted is not None:
+                    cmd, args = rerouted
+                else:
+                    self._say("  usage: open <n>  (a number from the last where)  or  open <file[:line]>", _CYAN)
+                    return None, True
 
         if cmd in ("help", "?", "h"):
             self._help(" ".join(args))
@@ -463,6 +481,39 @@ class Session:
         if cmd == "rules":
             from .commands.rules import cmd_rules
             return cmd_rules(self.repo), True
+        if cmd in ("where", "locate"):
+            # 'where did we leave off' is the catch-up idiom, not a grounding query
+            if cmd == "where" and re.search(r"^(did\s+|do\s+)?we\s+(left|leave)\s+off", " ".join(args).lower()):
+                from .commands.history import cmd_runs
+                return cmd_runs(self.repo), True
+            if not args:
+                self._say('  usage: where <what you are looking for>   (e.g.  where rate limiter)', _CYAN)
+                return None, True
+            from .commands.where import cmd_where
+            res = cmd_where(self.repo, " ".join(args))
+            if res is not None:
+                self._last_places = list((res.data or {}).get("files") or [])   # `open <n>` targets
+            return res, True
+        if cmd == "open":
+            target = args[0]
+            if target.isdigit():
+                n = int(target)
+                if not self._last_places:
+                    self._say("  nothing to open yet -- run  where <words>  first", _CYAN)
+                    return None, True
+                if not 1 <= n <= len(self._last_places):
+                    self._say(f"  open takes 1..{len(self._last_places)} (from the last where)", _CYAN)
+                    return None, True
+                place = self._last_places[n - 1]
+                hits = place.get("hits") or []
+                self._open_file(place["path"], hits[0]["line"] if hits else None)
+                return None, True
+            path, _, ln = target.rpartition(":")
+            if path and ln.isdigit():
+                self._open_file(path, int(ln))
+            else:
+                self._open_file(target, None)
+            return None, True
         if cmd == "sessions":
             from .commands.history import cmd_sessions
             return cmd_sessions(self.repo), True
@@ -582,6 +633,10 @@ class Session:
         if re.search(r"\b(summar\w+|tl;?dr)\b", low) or \
            re.search(r"\b(describe|explain|overview|walk me through|what(?:'s| is| does| do| are)?)\b"
                      r".{0,40}\b(code|codebase|repo|repository|project|module|files?)\b", low):
+            # 'the FULL summary' / 'every function' carries through to --full, never silently dropped
+            if re.search(r"\bfull\b|\bevery\w*\b|\ball of it\b|\bin depth\b|\bdetailed?\b", low):
+                interp("summarize the codebase (full: every symbol)")
+                return ("summarize", ["--full"])
             interp("summarize the codebase")
             return ("summarize", [])
         # verify current changes -- 'verify' is unambiguous; gate/check/review/validate need a change object
@@ -657,6 +712,15 @@ class Session:
         if m:
             interp(f"why {m.group(1)} (the decisions that shaped it)")
             return ("why", [m.group(1)])
+        # a CHANGE REQUEST in domain language ('can we remove the spending check option from the
+        # workflows section?') -> ground the named terms in THIS repo + show the verified-change
+        # ladder. Never 'not a command' for legitimate engineering intent.
+        if re.search(r"\b(remove|delete|disable|enable|add|rename|move|change|modify|update|"
+                     r"refactor|implement|hide|show)\b", low):
+            from .commands.where import extract_terms
+            if len(extract_terms(low)) >= 1:
+                interp("ground it in this repo (where does that live?)")
+                return ("where", line.split())
         # a stated standing rule ('never use print statements here') -> suggest recording it, never
         # auto-record (setting a rule is deliberate; see remember/rules)
         if re.search(r"^(never|always|do not|don'?t)\b.*\b(use|using|write|import|call|commit|push|"
@@ -791,6 +855,40 @@ class Session:
             return None      # skipped: the ASK was already shown
         return res
 
+    def _open_file(self, path: str, line_no=None) -> None:
+        """Open a repo file in the user's editor, at the line when the editor can. Closed-class:
+        $VISUAL/$EDITOR first, then well-known GUI editors on PATH; the fallback is the path itself
+        (never an error -- the user came here to find a place, and the place is the answer)."""
+        import shutil
+        import subprocess
+        loc_note = f"{path}:{line_no}" if line_no else path
+        abspath = os.path.join(self.repo, path)
+        if not os.path.exists(abspath):
+            self._say(f"  {path} is not in this repo (was it moved since that where?)", _CYAN)
+            return
+        raw = os.environ.get("VISUAL") or os.environ.get("EDITOR") or ""
+        editor = shlex.split(raw) if raw else []
+        if not editor:
+            found = next((c for c in ("code", "cursor", "code-insiders", "subl", "zed")
+                          if shutil.which(c)), None)
+            editor = [found] if found else []
+        if not editor:
+            self._say(f"  no editor found ($EDITOR is unset) -- it lives at  {loc_note}", _CYAN)
+            return
+        base = os.path.basename(editor[0])
+        gui = {"code": "-g", "code-insiders": "-g", "cursor": "-g", "subl": "", "zed": ""}
+        try:
+            if base in gui:                      # GUI editors: path:line syntax, detached
+                loc = f"{abspath}:{line_no}" if line_no else abspath
+                cmd = editor + ([gui[base], loc] if gui[base] else [loc])
+                subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                self._say(f"  opened {loc_note} in {base}", _DIM)
+            else:                                # terminal editors: +line, and hand over the tty
+                cmd = editor + ([f"+{line_no}"] if line_no else []) + [abspath]
+                subprocess.run(cmd, check=False)
+        except OSError as e:
+            self._say(f"  could not start {base} ({e}) -- it lives at  {loc_note}", _CYAN)
+
     def _verify(self, args):
         from .commands.verify import run_verify
         # flags: --staged, --test <t> (repeatable). default = working-tree diff.
@@ -837,6 +935,8 @@ class Session:
         ("UNDERSTAND", "", [
             ("summarize", "describe this codebase  (add --full for every symbol)"),
             ("failing", "run the tests and list what is failing"),
+            ("where <words>", "find where something lives in this repo (grounds your words in code)"),
+            ("open <n|file[:line]>", "open a found place in your editor (n from the last where)"),
         ]),
         ("BUILD", "verified or refused, never a guess", [
             ("fix <test>", "a verified fix -- a failing test, a css file, or a css intent (help fix)"),
@@ -863,6 +963,8 @@ class Session:
             ("doctor", "check the environment, harness, and connection"),
             ("init", "map what this repo can gate (the coverage contract)"),
             ("login", "connect the hosted engine for fix and write"),
+            ("logout", "disconnect this machine (local commands keep working)"),
+            ("whoami", "who is logged in, and to which server"),
         ]),
     ]
     _HELP_ALSO = [

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: substratum-cli
-Version: 0.2.8
+Version: 0.2.9
 Summary: Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.
 Author: Substratum
 License: LicenseRef-Proprietary

{substratum_cli-0.2.8 → substratum_cli-0.2.9}/substratum_cli.egg-info/SOURCES.txt

@@ -56,6 +56,7 @@ substratum_cli/commands/scaffold.py
 substratum_cli/commands/show.py
 substratum_cli/commands/undo.py
 substratum_cli/commands/verify.py
+substratum_cli/commands/where.py
 substratum_cli/commands/write.py
 tests/test_adaptive_prior.py
 tests/test_alias_warrant_trace.py