substratum-cli 0.1.0__tar.gz → 0.2.1__tar.gz

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/PKG-INFO

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

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "substratum-cli"
-version = "0.1.0"
+dynamic = ["version"]                        # read from substratum_cli.__version__ (the single source)
 description = "Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine."
 readme = "substratum_cli/README.md"
 license = { text = "LicenseRef-Proprietary" }
@@ -35,5 +35,8 @@ Homepage = "https://substratum-api.fly.dev"
 [tool.setuptools]
 packages = ["substratum_cli", "substratum_cli.commands", "substratum_cli._vendor"]
 
+[tool.setuptools.dynamic]
+version = { attr = "substratum_cli.__version__" }
+
 [tool.pytest.ini_options]
 markers = ["slow: loads the full production library (minutes); excluded from the fast gate"]

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/substratum_cli/__init__.py

@@ -3,4 +3,6 @@
 Import budget: this package is stdlib-only; the ONLY module reaching into backend.* is
 `engine.py`, lazily. Importing substratum_cli (or any light command) opens nothing heavy.
 """
-__version__ = "0.1.0"
+# 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.1"

substratum_cli-0.2.1/substratum_cli/_boot.py

@@ -0,0 +1,166 @@
+"""The Substratum boot identity: THE PROOF SEAL.
+
+Not a wordmark splash -- a self-certifying certificate. The seal (a hash of engine build + substrate +
+scheme, with ZERO time/session input) prints byte-identical on every boot, because the engine that
+draws it is deterministic. A token-streaming tool cannot render a stable self-certificate; the sameness
+IS the demonstration. Below the emblem (the logo: a flat plane struck by two rays converging on one lime
+node) sits a structured, color-hierarchied ledger. Stdlib only; pure given its inputs.
+
+Color law: lime(154)=brand/identity only, 190=the ONE bright spark (the convergence node), green(42)=
+proven, gold(179)=the single next move, grey(245 label / 240 chrome / 252 data)=structure + values.
+"""
+from __future__ import annotations
+
+import hashlib
+
+# The PUBLIC substrate release name -- what the product shows, like a model version (GPT-5.2, Opus 4.8).
+# Decoupled from the internal mining tag (pattern_library_scaled_v15): that tag still drives the seal
+# hash (the seal must certify the ACTUAL build), but users see this. Bump only on a real public release.
+RELEASE = "Substrate 1.0 Preview"
+
+L = "\033[38;5;154m"      # brand lime
+LB = "\033[1;38;5;190m"   # the one bright spark
+GR = "\033[38;5;42m"      # proven green
+GO = "\033[38;5;179m"     # the next move
+LAB = "\033[38;5;245m"    # labels
+CH = "\033[38;5;240m"     # chrome rails
+DAT = "\033[38;5;252m"    # data values
+B = "\033[1m"
+R = "\033[0m"
+
+# the emblem: THE STRUCK-BY-LIGHT SLAB (founder pick). A flat substrate plane seen edge-on where the
+# light is literal -- a brightness gradient (█▓▒░) converging from the solid lit edges to one bright ◇
+# node at the core. Built ONLY from cell-filling block glyphs so it renders as one connected shape;
+# diagonal box-drawing (╱ ╲) was tried and FRAGMENTS in real terminal fonts (it does not tile).
+_EMBLEM = [
+    "▄███████████████████▄",
+    "███▓▓▓▒▒░░◇░░▒▒▓▓▓███",
+    "▀███████████████████▀",
+]
+_EMBLEM_ASCII = [
+    "#####################",
+    "###+++==--*--==+++###",
+    "#####################",
+]
+
+
+def seal(lib_name: str, version: str) -> tuple[str, str]:
+    """(sigil, digest) -- a deterministic self-certificate. No time/session input, so it is byte-identical
+    every boot. The digest is a stable proof that this engine+substrate render the same thing every run."""
+    h = hashlib.sha256(f"substratum|scheme:sub1|{version}|{lib_name}".encode()).hexdigest()
+    sigil = "".join(chr(0x2800 + int(h[i:i + 2], 16)) for i in range(0, 8, 2))   # 4 braille glyphs
+    digest = f"{h[0:4]} {h[4:8]} {h[8:12]} {h[12:16]}"
+    return sigil, digest
+
+
+def render(name, census, langs, libname, patterns, warm, standing, version,
+           color=True, ascii_mode=False, logged_in=True, update_to="") -> list[str]:
+    """Return the boot lines. `standing` is build_state.standing() (may be {})."""
+    def c(code, s):
+        return f"{code}{s}{R}" if color else s
+
+    sig, dig = seal(libname, version)
+    if ascii_mode:
+        sig = "#" + dig.split()[0]
+    dot = "-" if ascii_mode else "·"          # separators degrade with the glyph set
+    if ascii_mode:                            # the renderer guarantees ascii output regardless of input
+        name, census, langs, libname = (str(s).replace("·", "-") for s in (name, census, langs, libname))
+    W = 78                                    # certificate inner width
+    out = ["", ""]
+
+    # ---- EMBLEM (the struck plane) ----
+    emb = _EMBLEM_ASCII if ascii_mode else _EMBLEM
+    spark = "*" if ascii_mode else "◇"
+    for ln in emb:
+        if color:
+            body = (L + ln.replace(spark, R + LB + spark + R + L) + R) if spark in ln else (L + ln + R)
+        else:
+            body = ln
+        out.append("  " + body)
+
+    # ---- 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"), ""]
+
+    # ---- the CERTIFICATE ----
+    tl, tr, bl, br, h_, v_, ml, mr = ("+", "+", "+", "+", "-", "|", "+", "+") if ascii_mode \
+        else ("┌", "┐", "└", "┘", "─", "│", "├", "┤")
+
+    def bar(top=False, bottom=False, label=""):
+        if label:                                    # section divider: measure the PLAIN label width
+            dashes = h_ * max(0, W - len(label) - 3)
+            return c(CH, ml + h_ + " ") + c(LAB + B, label) + c(CH, " " + dashes + mr)
+        lc, rc = (tl, tr) if top else (bl, br)
+        return c(CH, lc + h_ * W + rc)
+
+    def rowline(inner_plain, inner_colored):
+        pad = " " * max(0, W - 1 - _vis(inner_plain))
+        return c(CH, v_) + " " + inner_colored + pad + c(CH, v_)
+
+    lamp = (("*" if ascii_mode else "●") + " ready") if warm else (dot + " loading")
+    lampc = c(GR, lamp) if warm else c(CH, lamp)
+    st = standing or {}
+    runs, ver = st.get("runs", 0), st.get("verified", 0)
+    unsaved = st.get("unapplied_total", 0)
+
+    box = [bar(top=True)]
+    seal_inner_p = f"SEAL   {sig}   sub1{dot}{dig}"
+    seal_inner_c = c(LAB, "SEAL") + "   " + c(L, sig) + "   " + c(L, f"sub1{dot}") + c(LAB, dig)
+    right_p = f"deterministic {dot} replayable"
+    right_c = c(GR, "deterministic") + c(CH, f" {dot} ") + c(GR, "replayable")
+    pad = " " * max(1, W - 1 - _vis(seal_inner_p) - _vis(right_p))
+    box.append(c(CH, v_) + " " + seal_inner_c + pad + right_c + c(CH, v_))
+
+    box.append(bar(label="SUBSTRATE"))
+    box.append(rowline(f"  release   {RELEASE}      {lamp}",
+                       c(LAB, "  release   ") + c(DAT, RELEASE) + "      " + lampc))
+    box.append(rowline(f"  covers    {langs}", c(LAB, "  covers    ") + c(DAT, langs)))
+    box.append(bar(label="REPO"))
+    box.append(rowline(f"  project   {name}", c(LAB, "  project   ") + c(DAT, name)))
+    box.append(rowline(f"  files     {census}", c(LAB, "  files     ") + c(DAT, census)))
+    box.append(bar(label="SESSION"))
+    ok_p = "✓" if not ascii_mode else "[ok]"
+    sess_p = f"  runs {runs}      verified {ver} {ok_p}      refused 0      unsaved {unsaved}"
+    ok = c(GR, "✓") if not ascii_mode else "[ok]"
+    sess_c = (c(LAB, "  runs ") + c(DAT, str(runs)) + c(LAB, "      verified ") + c(GR, str(ver)) + " " + ok
+              + c(LAB, "      refused ") + c(DAT, "0")
+              + c(LAB, "      unsaved ") + (c(GO, str(unsaved)) if unsaved else c(DAT, "0")))
+    box.append(rowline(sess_p, sess_c))
+    box.append(bar(bottom=True))
+    out += ["  " + b for b in box]
+
+    # ---- the PROVABLE RESUME (only when there is verified, unapplied work) ----
+    up = (st.get("unapplied") or [])
+    if up:
+        r0 = up[0]
+        what = f"{r0['operation']} {r0.get('target', '')}".strip()
+        out += ["", "  " + c(GO, ">" if ascii_mode else "▸") + c(LAB, " welcome back")
+                + c(CH, " -- ") + c(LAB, f"{unsaved} verified change from a prior session is unsaved"),
+                "    " + c(GO, "apply " + r0["run_id"]) + c(CH, "   writes ") + c(DAT, what)
+                + c(CH, f" into your files  {dot}  ") + c(GR, "byte-identical")]
+
+    # ---- the SIGNPOST: never leave a user guessing what they can do, or unaware they must connect.
+    # fix + write run on the hosted engine; summarize/failing/verify run offline. Say so BEFORE they hit
+    # a NO_ENGINE refusal, and pick an ask-example that actually works in their current state.
+    ask_ex = '"fix the failing test"' if logged_in else '"what does this codebase do?"'
+    # the signpost text aligns at col 4 -- the same column as the welcome-back text -- so the whole bottom
+    # "here is what you can do" region reads as one clean left edge instead of jutting out under the box.
+    out += [""]
+    if update_to:                           # a pip package cannot self-update; hand over the one command
+        arrow = "^" if ascii_mode else "↑"
+        out += ["    " + c(GO, f"{arrow} update") + c(LAB, f"  Substratum {update_to} is available")
+                + c(CH, f"   {dot}   ") + c(GO, "pip install --upgrade substratum-cli")]
+    if not logged_in:
+        out += ["    " + c(GO, "login") + c(LAB, "  to ") + c(DAT, "fix") + c(LAB, " and ") + c(DAT, "write")
+                + c(LAB, " code (connects the engine)")
+                + c(CH, f"   {dot}   ") + c(LAB, "summarize, failing, verify work offline")]
+    out += ["    " + c(GO, "help") + c(LAB, "  see everything you can do")
+            + c(CH, f"   {dot}   ") + c(LAB, "or just ask: ") + c(GO, ask_ex)]
+    return out
+
+
+def _vis(s: str) -> int:
+    import re
+    return len(re.sub(r"\033\[[0-9;]*m", "", s))

substratum_cli-0.2.1/substratum_cli/_update.py

@@ -0,0 +1,58 @@
+"""Best-effort update signpost. A pip package cannot push itself to an installed user, so the most we can
+do is tell them, on boot, that a newer version exists and hand them the one command that gets it. That way
+every iteration we publish is picked up by the user's next session -- they just run the upgrade.
+
+Design guarantees: NEVER blocks boot, NEVER raises, NEVER sends user code anywhere (it reads one version
+string from the single host we already talk to). The read is instant (from a tiny cache under
+~/.substratum/); a background thread refreshes that cache for the next session. So the nag is at most one
+session behind a publish -- the industry-standard pattern (npm/gh do the same)."""
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+
+
+def _cache_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".substratum", "update.json")
+
+
+def _version_tuple(s: str) -> tuple:
+    """Compare X.Y.Z numerically; non-numeric suffixes (a 'Preview' etc.) reduce to their digits or 0."""
+    out = []
+    for part in str(s or "").split("."):
+        digits = "".join(ch for ch in part if ch.isdigit())
+        out.append(int(digits) if digits else 0)
+    return tuple(out)
+
+
+def available(current: str) -> str:
+    """The newer published version if the cache knows of one, else "". Pure, instant, no network."""
+    try:
+        latest = str(json.load(open(_cache_path(), encoding="utf-8")).get("latest") or "")
+    except Exception:
+        return ""
+    return latest if latest and _version_tuple(latest) > _version_tuple(current) else ""
+
+
+def refresh_async() -> None:
+    """Fire-and-forget: ask the server for the latest published client and cache it for next session.
+    The server sources this from PyPI, so publishing is all it takes -- no redeploy, no constant to bump."""
+    def _w():
+        try:
+            from . import remote
+            info = remote.server_info() or {}
+            latest = str(info.get("latest_client") or "")
+            if not latest:
+                return
+            path = _cache_path()
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8") as fh:
+                json.dump({"latest": latest, "t": int(time.time())}, fh)
+        except Exception:
+            pass
+    try:
+        threading.Thread(target=_w, daemon=True).start()
+    except Exception:
+        pass

substratum_cli-0.2.1/substratum_cli/_wordmark.py

@@ -0,0 +1,12 @@
+"""The SUBSTRATUM wordmark (figlet ansi_shadow), generated OFFLINE and stored as a plain
+string so the CLI stays zero-dependency. The brand mark: bold blocks, brand-lime (#C9FF3E)."""
+WORDMARK = [
+    '███████╗██╗   ██╗██████╗ ███████╗████████╗██████╗  █████╗ ████████╗██╗   ██╗███╗   ███╗',
+    '██╔════╝██║   ██║██╔══██╗██╔════╝╚══██╔══╝██╔══██╗██╔══██╗╚══██╔══╝██║   ██║████╗ ████║',
+    '███████╗██║   ██║██████╔╝███████╗   ██║   ██████╔╝███████║   ██║   ██║   ██║██╔████╔██║',
+    '╚════██║██║   ██║██╔══██╗╚════██║   ██║   ██╔══██╗██╔══██║   ██║   ██║   ██║██║╚██╔╝██║',
+    '███████║╚██████╔╝██████╔╝███████║   ██║   ██║  ██║██║  ██║   ██║   ╚██████╔╝██║ ╚═╝ ██║',
+    '╚══════╝ ╚═════╝ ╚═════╝ ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝     ╚═╝',
+    '                                                                                       ',
+]
+WIDTH = 87

substratum_cli-0.2.1/substratum_cli/build_state.py

@@ -0,0 +1,118 @@
+"""The build ledger: `.substratum/ledger.jsonl`. A build is a long working-through, not isolated
+commands -- so every query, decision, and apply is recorded, perfectly, for the life of the build.
+This is NOT a context window (nothing is summarized or forgotten); it is durable, addressable state
+that persists across sessions and grows into grounding. The run store holds the PROOFS; this holds
+the DECISION TRAIL over them and the standing state a session reads on open. Stdlib only, append-only,
+atomic. Complements run_store; never touches the engine (zero-wrong unaffected)."""
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Optional
+
+from . import run_store
+
+
+def _path(repo: str) -> str:
+    return os.path.join(run_store.store_dir(repo), "ledger.jsonl")
+
+
+def record(repo: str, kind: str, ts: Optional[int] = None, **fields) -> None:
+    """Append one event. kind: 'query' | 'decision' | 'apply' | 'commit'. Never raises."""
+    try:
+        rec = {"t": int(ts if ts is not None else time.time()), "kind": kind, **fields}
+        os.makedirs(os.path.dirname(_path(repo)), exist_ok=True)
+        with open(_path(repo), "a", encoding="utf-8") as fh:
+            fh.write(json.dumps(rec) + "\n")
+    except Exception:
+        pass
+
+
+def _events(repo: str) -> list:
+    p = _path(repo)
+    if not os.path.exists(p):
+        return []
+    out = []
+    for line in open(p, encoding="utf-8", errors="replace"):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            out.append(json.loads(line))
+        except Exception:
+            continue
+    return out
+
+
+def queries(repo: str, limit: int = 200) -> list:
+    """The persistent query/command history (oldest->newest) so recall (!!, !N, up-arrow) survives
+    across sessions -- the keystroke trail of the whole build, not just this process."""
+    q = [e.get("text", "") for e in _events(repo) if e.get("kind") == "query" and e.get("text")]
+    return q[-limit:]
+
+
+def applied_run_ids(repo: str) -> set:
+    return {e.get("run_id") for e in _events(repo) if e.get("kind") == "apply" and e.get("run_id")}
+
+
+def decision_count(repo: str) -> int:
+    return sum(1 for e in _events(repo) if e.get("kind") == "decision")
+
+
+def _norm_intent(s: str) -> str:
+    return " ".join((s or "").lower().split())      # prose: case-insensitive
+
+
+def _norm_sig(s: str) -> str:
+    return " ".join((s or "").split())              # code: case-PRESERVED (Python is case-sensitive)
+
+
+def record_decision(repo: str, intent: str, sig: str, purpose: str, into: str = None) -> None:
+    """Persist a disambiguation the user EXPLICITLY resolved to a VERIFIED output. Keyed on the full
+    disambiguating context (intent + signature + target file) so it is only recalled in the same
+    situation. Only ever recorded on an emit that carried an explicit pick."""
+    if not (intent and purpose):
+        return
+    record(repo, "decision", intent_n=_norm_intent(intent), sig_n=_norm_sig(sig),
+           into=(into or ""), purpose=str(purpose))
+
+
+def recall_decision(repo: str, intent: str, sig: str, into: str = None) -> str:
+    """The purpose chosen LAST TIME for this EXACT (normalized) intent+signature+target, or "" if none.
+
+    SAFETY: this is used ONLY to PRESELECT a choice inside a clarification ASK -- it NEVER auto-forces
+    a reading and NEVER suppresses the ASK for a genuinely ambiguous intent (that would silently steer
+    the output away from the user's session intent and break cross-engineer determinism). It is a
+    surfaced hint the user re-confirms; the gate is untouched and the ASK is never deleted. The match
+    is a conservative EXACT (normalized, context-keyed) match; no fuzzy matching."""
+    inn, sn, it = _norm_intent(intent), _norm_sig(sig), (into or "")
+    got = ""
+    for e in _events(repo):
+        if (e.get("kind") == "decision" and e.get("intent_n") == inn and e.get("sig_n") == sn
+                and (e.get("into") or "") == it):
+            got = str(e.get("purpose") or "")   # scan in order -> most-recent match wins
+    return got
+
+
+def standing(repo: str) -> dict:
+    """The welcome-back summary a session shows on open, so the persistent state is FELT, not just
+    queryable: how much has been built, the last run, any verified work still waiting to be applied,
+    and how many decisions the build carries forward. Empty dict on a fresh repo."""
+    runs = run_store.list_runs(repo, limit=500)
+    if not runs and not os.path.exists(_path(repo)):
+        return {}
+    applied = applied_run_ids(repo)
+    unapplied = [r for r in runs
+                 if r.get("verdict") in ("VERIFIED", "PASS")
+                 and r.get("operation") in ("fix", "write")
+                 and r.get("run_id") not in applied]
+    verified = sum(1 for r in runs if r.get("verdict") in ("VERIFIED", "PASS"))
+    return {
+        "runs": len(runs),
+        "verified": verified,
+        "last": runs[0] if runs else None,
+        "unapplied": unapplied[:3],
+        "unapplied_total": len(unapplied),
+        "decisions": decision_count(repo),
+    }

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/substratum_cli/cli.py

@@ -54,6 +54,7 @@ def build_parser() -> argparse.ArgumentParser:
         ("runs", "run history + the refusal->verified conversion ledger (the proof store)"),
         ("undo", "reverse-apply a run (the inverse of apply)"),
         ("commit", "proof-carrying git commit of a verified, applied run"),
+        ("pr", "open a proof-carrying pull request (pushes with your git; proof in the body)"),
         ("failing", "run the suite and list failing tests (each becomes a fix target)"),
     ]:
         p = sub.add_parser(name, help=help_)
@@ -66,6 +67,9 @@ def build_parser() -> argparse.ArgumentParser:
             p.add_argument("--failing-test", action="append", default=[])
             p.add_argument("--intent", default="")
             p.add_argument("--test-command", default=None)
+        if name == "summarize":
+            p.add_argument("--full", action="store_true",
+                           help="list every symbol (lift the one-screen cap)")
         if name == "write":
             p.add_argument("intent", help="what the code should do, in plain language")
             p.add_argument("--sig", required=True, help="target signature, e.g. \"clamp(x, lo, hi)\"")
@@ -79,6 +83,9 @@ def build_parser() -> argparse.ArgumentParser:
             p.add_argument("--commit", default=None)
             p.add_argument("--test", action="append", default=[])
             p.add_argument("--test-command", default=None)
+        if name == "pr":
+            p.add_argument("run_id", nargs="?", default=None)
+            p.add_argument("--title", default=None)
         if name in ("apply", "show", "replay", "attest", "explain", "undo", "commit"):
             p.add_argument("run_id")
         if name == "commit":
@@ -126,7 +133,7 @@ def dispatch(args) -> "_result.SubstratumResult":
         return cmd_scaffold_test(args.repo, getattr(args, "target", None) or "")
     if cmd == "summarize":
         from . import product_ops
-        return product_ops.op_summarize_repo(args.repo)
+        return product_ops.op_summarize_repo(args.repo, full=getattr(args, "full", False))
     if cmd == "runs":
         from .commands.history import cmd_runs
         return cmd_runs(args.repo)
@@ -136,6 +143,9 @@ def dispatch(args) -> "_result.SubstratumResult":
     if cmd == "commit":
         from .commands.commit import cmd_commit
         return cmd_commit(args.repo, args.run_id, getattr(args, "message", None))
+    if cmd == "pr":
+        from .commands.pr import cmd_pr
+        return cmd_pr(args.repo, getattr(args, "run_id", None), getattr(args, "title", None))
     if cmd == "failing":
         from .commands.failing import cmd_failing
         return cmd_failing(args.repo, path=getattr(args, "target", None),

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/substratum_cli/codes.py

@@ -38,12 +38,13 @@ FLAKY_OR_VACUOUS_WARRANT = "FLAKY_OR_VACUOUS_WARRANT"  # 14: tests pass at base
 FLAKY_TEST = "FLAKY_TEST"                           # 14: quarantined nondeterministic test
 RUN_NOT_FOUND = "RUN_NOT_FOUND"                     # 11: show/explain/replay on an unknown id
 NO_ENGINE = "NO_ENGINE"                             # 12: synthesis needs the engine; login or [engine]
+NO_TEST_RUNNER = "NO_TEST_RUNNER"                   # 12: `failing` found no test runner to launch here
 
 REFUSAL_CODES = (
     NO_GROUNDED_CANDIDATE, GATE_PRECONDITION, NO_WARRANT_TESTS, HUNK_CONTEXT_STALE,
     APPLY_STATE_DRIFT, REPLAY_STATE_DRIFT, NO_DRIVER, AUTONOMY_LOCKED,
     UNDERDETERMINED_INTENT, FLAKY_OR_VACUOUS_WARRANT, FLAKY_TEST, RUN_NOT_FOUND,
-    NO_ENGINE,
+    NO_ENGINE, NO_TEST_RUNNER,
 )
 
 # ---- the exit-code table (closed; the machine contract) ----------------------
@@ -63,6 +64,7 @@ _REFUSAL_EXIT = {
     NO_DRIVER: 12,
     AUTONOMY_LOCKED: 12,
     NO_ENGINE: 12,
+    NO_TEST_RUNNER: 12,
     UNDERDETERMINED_INTENT: 13,
     FLAKY_OR_VACUOUS_WARRANT: 14,
     FLAKY_TEST: 14,

{substratum_cli-0.1.0 → substratum_cli-0.2.1}/substratum_cli/commands/apply.py

@@ -45,5 +45,7 @@ def cmd_apply(repo: str, run_id: str) -> "_result.SubstratumResult":
                                                            ctx={"target": run_id, "run_id": run_id}))
     finally:
         os.unlink(patch)
+    from .. import build_state
+    build_state.record(repo, "apply", run_id=run_id, files=list(res.files))   # standing-state feed
     return _result.make(codes.PASS, run_id, "apply", files=res.files,
                         data={"applied": list(res.files)})

substratum_cli-0.2.1/substratum_cli/commands/failing.py

@@ -0,0 +1,149 @@
+"""`failing` / `tests` -- discover failing tests in the repo by RUNNING its own suite and collecting
+the failed node-ids. This is an OBSERVATION (read-only; runs the user's existing test command), not a
+guess -- the failing tests are facts from the runner, and each becomes a ready `fix <id>` target.
+
+Detects the harness per language: pytest (Python), go test (Go), vitest / jest / the project's own
+`test` script (JS/TS). Failed ids are parsed reliably for pytest + go; for JS runners we report the
+failed COUNT from the summary (never invent node-ids -- zero-wrong)."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys as _sys
+from typing import Optional
+
+from .. import codes, refusals, runid
+from .. import result as _result
+
+# reliable, format-stable id parsers
+_ID_PARSERS = {
+    "pytest": re.compile(r"^(?:FAILED|ERROR)\s+(\S+)", re.M),   # FAILED path::test - reason
+    "go": re.compile(r"^\s*--- FAIL:\s+(\S+)", re.M),           # --- FAIL: TestName (0.00s)
+}
+# JS runners: parse the failed COUNT from the summary (names vary by reporter; do not fabricate ids)
+_COUNT_PARSERS = {
+    "vitest": re.compile(r"Tests\s+(\d+)\s+failed", re.I),
+    "jest": re.compile(r"Tests:\s+(\d+)\s+failed", re.I),
+    "node": re.compile(r"(\d+)\s+failed", re.I),
+}
+
+
+def _read(p: str) -> str:
+    try:
+        return open(p, encoding="utf-8", errors="replace").read()
+    except Exception:
+        return ""
+
+
+def _pkg(repo: str):
+    p = os.path.join(repo, "package.json")
+    if not os.path.isfile(p):
+        return None
+    try:
+        return json.loads(_read(p))
+    except Exception:
+        return {}
+
+
+def _node_pm(repo: str) -> str:
+    if os.path.exists(os.path.join(repo, "pnpm-lock.yaml")):
+        return "pnpm"
+    if os.path.exists(os.path.join(repo, "yarn.lock")):
+        return "yarn"
+    return "npm"
+
+
+def _detect_command(repo: str):
+    """Return (argv, kind) where kind selects the failure parser, or None if no runner is found."""
+    j = os.path.join
+    # ---- Python: pytest ----
+    for marker in ("pytest.ini", "conftest.py", "tox.ini"):
+        if os.path.exists(j(repo, marker)):
+            return [_sys.executable, "-m", "pytest"], "pytest"
+    for cfg in ("pyproject.toml", "setup.cfg"):
+        if os.path.isfile(j(repo, cfg)) and "pytest" in _read(j(repo, cfg)).lower():
+            return [_sys.executable, "-m", "pytest"], "pytest"
+    if os.path.isdir(j(repo, "tests")):
+        return [_sys.executable, "-m", "pytest"], "pytest"
+    try:
+        if any(f.startswith("test_") and f.endswith(".py") for f in os.listdir(repo)):
+            return [_sys.executable, "-m", "pytest"], "pytest"
+    except Exception:
+        pass
+    # ---- Go ----
+    if os.path.exists(j(repo, "go.mod")):
+        return ["go", "test", "./..."], "go"
+    # ---- JS / TS: vitest, jest, or the project's own `test` script ----
+    pkg = _pkg(repo)
+    if pkg is not None:
+        deps = {**(pkg.get("devDependencies") or {}), **(pkg.get("dependencies") or {})}
+        pm = _node_pm(repo)
+        has_test = "test" in (pkg.get("scripts") or {})
+        is_vitest = ("vitest" in deps or any(os.path.exists(j(repo, f))
+                     for f in ("vitest.config.ts", "vitest.config.js", "vitest.config.mts")))
+        is_jest = ("jest" in deps or any(os.path.exists(j(repo, f))
+                   for f in ("jest.config.js", "jest.config.ts", "jest.config.mjs")))
+        kind = "vitest" if is_vitest else ("jest" if is_jest else "node")
+        if has_test:                                   # the project's OWN command -- most faithful
+            return ([pm, "test"] if pm != "npm" else ["npm", "test", "--silent"]), kind
+        if is_vitest:
+            return ([pm, "exec", "vitest", "run"] if pm != "npm" else ["npx", "vitest", "run"]), "vitest"
+        if is_jest:
+            return ([pm, "exec", "jest"] if pm != "npm" else ["npx", "jest"]), "jest"
+    return None
+
+
+def _refuse(rid, code, engine_code):
+    ref = refusals.build(code, engine_code=engine_code, ctx={"target": "the test suite", "run_id": rid})
+    return _result.make(codes.REFUSED, rid, "failing", code=code, refusal=ref)
+
+
+def cmd_failing(repo: str, path: Optional[str] = None, test_command: Optional[str] = None,
+                timeout: int = 300) -> "_result.SubstratumResult":
+    repo = os.path.abspath(repo)
+    rid, _key = runid.compute(repo, "failing", {"path": path or ""})
+    if test_command:
+        argv, kind = shlex.split(test_command), "pytest"   # user-named cmd: try the reliable parser too
+    else:
+        detected = _detect_command(repo)
+        if not detected:
+            return _refuse(rid, codes.NO_TEST_RUNNER, "no pytest / go test / vitest / jest / test script found")
+        argv, kind = detected
+    is_pytest = kind == "pytest"
+    run_argv = list(argv) + (["-q", "-p", "no:cacheprovider"] if is_pytest else [])
+    if path:
+        run_argv.append(path)
+    try:
+        r = subprocess.run(run_argv, cwd=repo, capture_output=True, text=True, timeout=timeout,
+                           env={**os.environ, "TMPDIR": "/tmp", "CI": "1", "NO_COLOR": "1"})
+    except subprocess.TimeoutExpired:
+        return _refuse(rid, codes.GATE_PRECONDITION, f"the test suite did not finish within {timeout}s")
+    except (FileNotFoundError, PermissionError) as e:
+        return _refuse(rid, codes.NO_TEST_RUNNER, f"could not launch the runner ({e})")
+    out = (r.stdout or "") + "\n" + (r.stderr or "")
+    out = re.sub(r"\033\[[0-9;]*m", "", out)           # strip ANSI so parsers see plain text
+
+    # reliable id parsing (pytest, go); otherwise a trustworthy failed-count from the summary
+    failing, count = [], 0
+    id_re = _ID_PARSERS.get(kind)
+    if id_re:
+        for m in id_re.finditer(out):
+            nid = m.group(1)
+            if nid not in failing:
+                failing.append(nid)
+        count = len(failing)
+    else:
+        cm = _COUNT_PARSERS.get(kind, _COUNT_PARSERS["node"]).search(out)
+        count = int(cm.group(1)) if cm else 0
+
+    all_pass = (count == 0) and r.returncode == 0
+    excerpt = ""
+    if not failing and not all_pass:                   # no ids to list -> surface the tail as evidence
+        excerpt = "\n".join(out.strip().splitlines()[-8:])
+    return _result.make(codes.PASS, rid, "failing",
+                        data={"failing": failing, "count": count, "harness": kind,
+                              "command": " ".join(run_argv), "all_pass": all_pass,
+                              "excerpt": excerpt, "rc": r.returncode})