wizard-central-toolkit 0.2.0__py3-none-any.whl

wiz_central_toolkit/codeguardwiz/static_engine.py

@@ -0,0 +1,307 @@
+"""codeguardwiz static engine — the built-in, seatless audit.
+
+Standard library only. Real rules over Python source: `ast` where the
+tree can see, text patterns where it cannot (comments and markers).
+This is the always-available half of codeguardwiz (AVS's R1 ruling:
+both engines, the user's choice). It never calls a model, never
+writes a file, and everything it produces is labelled as its own.
+
+Findings are plain dicts:
+  {"path", "line", "rule", "name", "severity", "detail"}
+with severity one of "high" | "medium" | "low".
+"""
+import ast
+import re
+from pathlib import Path
+
+ENGINE_LABEL = "static (built-in rules)"
+
+# ---------------------------------------------------------------- rules
+
+_RULE_DEFS = [
+    ("CG001", "syntax-error", "high",
+     "The file does not parse as Python at all, so nothing in it can "
+     "run. Every other check is blind until this is fixed: a file "
+     "that cannot compile cannot be trusted to do what it says."),
+    ("CG002", "hardcoded-secret", "high",
+     "A password, token, or key written as a string literal directly "
+     "in the source. Anyone who can read the code owns the secret, "
+     "and the secret travels with every copy of the file. Move it to "
+     "the environment or a config the code reads at runtime."),
+    ("CG003", "eval-exec", "high",
+     "eval() or exec() runs a string as code. If any part of that "
+     "string can be influenced from outside, the caller can run "
+     "anything. Parse the data instead (ast.literal_eval for "
+     "literals), or dispatch to named functions."),
+    ("CG004", "shell-execution", "high",
+     "A shell interprets this command (os.system, os.popen, or a "
+     "subprocess call with shell=True), so metacharacters in the "
+     "arguments become commands. Pass an argument list with "
+     "shell=False and let the program, not a shell, run."),
+    ("CG005", "pickle-load", "medium",
+     "pickle.load/loads rebuilds objects from bytes and will run "
+     "whatever the bytes say. Never unpickle data that crossed a "
+     "trust boundary; use a data format (JSON) for anything "
+     "untrusted."),
+    ("CG006", "weak-hash", "medium",
+     "MD5 and SHA-1 are broken for security use: collisions are "
+     "cheap to manufacture. For integrity or password work use "
+     "SHA-256 or better (hashlib.sha256, or a password KDF such as "
+     "hashlib.pbkdf2_hmac)."),
+    ("CG007", "bare-except", "medium",
+     "A bare `except:` catches everything — including "
+     "KeyboardInterrupt, SystemExit, and the very bugs you are "
+     "hunting — and hides them all alike. Name the exceptions you "
+     "expect (`except Exception:` at the widest). This is the one "
+     "finding the static engine can rewrite deterministically."),
+    ("CG008", "swallowed-exception", "low",
+     "An except block whose whole body is `pass` (or `...`) makes "
+     "the failure vanish silently: the program continues as if "
+     "nothing happened, in a state nobody checked. Log it, count "
+     "it, or let it propagate — but decide on purpose."),
+    ("CG009", "todo-marker", "low",
+     "A TODO or FIXME comment is a promise the code has not kept "
+     "yet. Not a defect by itself — it is listed so the promise "
+     "stays visible instead of sinking into the file."),
+]
+
+
+class Rule:
+    __slots__ = ("id", "name", "severity", "explanation")
+
+    def __init__(self, rid, name, severity, explanation):
+        self.id = rid
+        self.name = name
+        self.severity = severity
+        self.explanation = explanation
+
+
+RULES = [Rule(*d) for d in _RULE_DEFS]
+RULE_BY_ID = {r.id: r for r in RULES}
+
+
+def find_rule(query):
+    """Look a rule up by id (CG002), exact name, or name fragment."""
+    q = str(query).strip()
+    if not q:
+        return None
+    if q.upper() in RULE_BY_ID:
+        return RULE_BY_ID[q.upper()]
+    ql = q.lower()
+    for r in RULES:
+        if r.name == ql:
+            return r
+    for r in RULES:
+        if ql in r.name:
+            return r
+    return None
+
+
+# ---------------------------------------------------------------- scanning
+
+_SECRET_NAME = re.compile(
+    r"(password|passwd|pwd|secret|api[_-]?key|access[_-]?token"
+    r"|auth[_-]?token|private[_-]?key)", re.IGNORECASE)
+_TODO = re.compile(r"#\s*(TODO|FIXME)\b")
+_BARE_EXCEPT = re.compile(r"^(\s*)except\s*:\s*(#.*)?$")
+
+_KNOWN_MODULES = ("os", "subprocess", "pickle", "hashlib")
+
+
+def _finding(path, line, rule, detail):
+    return {"path": str(path), "line": line, "rule": rule.id,
+            "name": rule.name, "severity": rule.severity,
+            "detail": detail}
+
+
+def _is_secret_name(name):
+    return bool(_SECRET_NAME.search(name)) or name.lower() == "token" \
+        or name.lower().endswith("_token")
+
+
+def _imports(tree):
+    """Map local names back to the modules they came from."""
+    modules = {}   # local name -> top module ("pickle", "os", ...)
+    funcs = {}     # local func name -> (module, attr)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for a in node.names:
+                top = a.name.split(".")[0]
+                modules[a.asname or top] = top
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            top = node.module.split(".")[0]
+            for a in node.names:
+                funcs[a.asname or a.name] = (top, a.name)
+    return modules, funcs
+
+
+def _call_target(func, modules, funcs):
+    """Resolve a call's func to (module, attr) where determinable."""
+    if isinstance(func, ast.Attribute):
+        base = func.value
+        if isinstance(base, ast.Name):
+            mod = modules.get(base.id, base.id)
+            return mod, func.attr
+        return None, func.attr
+    if isinstance(func, ast.Name):
+        if func.id in funcs:
+            return funcs[func.id]
+        return None, func.id
+    return None, None
+
+
+def scan_source(source, path="<source>"):
+    """All findings in one Python source string, sorted by line."""
+    findings = []
+    lines = source.splitlines()
+
+    # text lane: markers live in comments, which the AST drops
+    for i, text in enumerate(lines, 1):
+        m = _TODO.search(text)
+        if m:
+            findings.append(_finding(
+                path, i, RULE_BY_ID["CG009"],
+                f"{m.group(1)} marker left in the code"))
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError as e:
+        findings.append(_finding(
+            path, e.lineno or 1, RULE_BY_ID["CG001"],
+            f"{e.msg} (line {e.lineno or 1})"))
+        findings.sort(key=lambda f: (f["line"], f["rule"]))
+        return findings
+
+    modules, funcs = _imports(tree)
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Assign, ast.AnnAssign)):
+            value = node.value
+            targets = node.targets if isinstance(node, ast.Assign) \
+                else [node.target]
+            if isinstance(value, ast.Constant) \
+                    and isinstance(value.value, str) and value.value:
+                for t in targets:
+                    if isinstance(t, ast.Name) and _is_secret_name(t.id):
+                        findings.append(_finding(
+                            path, node.lineno, RULE_BY_ID["CG002"],
+                            f"string literal assigned to '{t.id}'"))
+        elif isinstance(node, ast.Dict):
+            for k, v in zip(node.keys, node.values):
+                if isinstance(k, ast.Constant) and isinstance(k.value, str) \
+                        and _is_secret_name(k.value) \
+                        and isinstance(v, ast.Constant) \
+                        and isinstance(v.value, str) and v.value:
+                    findings.append(_finding(
+                        path, v.lineno, RULE_BY_ID["CG002"],
+                        f"string literal under key '{k.value}'"))
+        elif isinstance(node, ast.Call):
+            mod, attr = _call_target(node.func, modules, funcs)
+            bare = node.func.id if isinstance(node.func, ast.Name) else None
+            if bare in ("eval", "exec"):
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG003"],
+                    f"{bare}() executes a string as code"))
+            if mod == "os" and attr in ("system", "popen"):
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG004"],
+                    f"os.{attr}() always runs through a shell"))
+            if mod == "subprocess":
+                for kw in node.keywords:
+                    if kw.arg == "shell" \
+                            and isinstance(kw.value, ast.Constant) \
+                            and kw.value.value is True:
+                        findings.append(_finding(
+                            path, node.lineno, RULE_BY_ID["CG004"],
+                            "subprocess call with shell=True"))
+            if mod == "pickle" and attr in ("load", "loads"):
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG005"],
+                    f"pickle.{attr}() deserializes arbitrary objects"))
+            if mod == "hashlib" and attr in ("md5", "sha1"):
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG006"],
+                    f"hashlib.{attr}() is a broken hash for security use"))
+            if mod == "hashlib" and attr == "new" and node.args:
+                first = node.args[0]
+                if isinstance(first, ast.Constant) \
+                        and isinstance(first.value, str) \
+                        and first.value.lower().replace("-", "") \
+                        in ("md5", "sha1"):
+                    findings.append(_finding(
+                        path, node.lineno, RULE_BY_ID["CG006"],
+                        f"hashlib.new({first.value!r}) is a broken hash "
+                        "for security use"))
+        elif isinstance(node, ast.ExceptHandler):
+            if node.type is None:
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG007"],
+                    "bare except: catches everything, names nothing"))
+            elif len(node.body) == 1 and (
+                    isinstance(node.body[0], ast.Pass) or (
+                        isinstance(node.body[0], ast.Expr)
+                        and isinstance(node.body[0].value, ast.Constant)
+                        and node.body[0].value.value is Ellipsis)):
+                findings.append(_finding(
+                    path, node.lineno, RULE_BY_ID["CG008"],
+                    "except block swallows the exception silently"))
+
+    findings.sort(key=lambda f: (f["line"], f["rule"]))
+    return findings
+
+
+def scan_file(path):
+    """Findings for one file on disk. Raises OSError if unreadable."""
+    source = Path(path).read_text(encoding="utf-8", errors="ignore")
+    return scan_source(source, str(path))
+
+
+def collect_files(target):
+    """The .py files a file-or-dir target names (model scan's own set)."""
+    p = Path(target)
+    if p.is_file():
+        return [p] if p.suffix == ".py" else []
+    if p.is_dir():
+        return sorted(f for f in p.rglob("*.py")
+                      if "__pycache__" not in str(f)
+                      and ".venv" not in str(f))
+    return []
+
+
+def counts(findings):
+    out = {"high": 0, "medium": 0, "low": 0}
+    for f in findings:
+        out[f["severity"]] += 1
+    return out
+
+
+# ---------------------------------------------------------------- fixing
+
+FIXABLE_RULES = ("CG007",)
+
+
+def apply_fixes(source, findings):
+    """Deterministically rewrite what has a defensible rewrite.
+
+    CG007 only: a line that is exactly a bare `except:` (plus optional
+    trailing comment) becomes `except Exception:` with the same
+    indentation. Line count never changes. Returns (new_source, n).
+    """
+    lines = source.splitlines(keepends=True)
+    applied = 0
+    for f in findings:
+        if f["rule"] not in FIXABLE_RULES:
+            continue
+        idx = f["line"] - 1
+        if not (0 <= idx < len(lines)):
+            continue
+        raw = lines[idx]
+        body = raw.rstrip("\r\n")
+        ending = raw[len(body):]
+        m = _BARE_EXCEPT.match(body)
+        if not m:
+            continue
+        comment = f"  {m.group(2)}" if m.group(2) else ""
+        lines[idx] = f"{m.group(1)}except Exception:{comment}{ending}"
+        applied += 1
+    return "".join(lines), applied

wiz_central_toolkit/common/__init__.py

@@ -0,0 +1 @@
+"""Shared helpers (keep minimal)."""

wiz_central_toolkit/debugwiz/__init__.py

@@ -0,0 +1 @@
+"""debugwiz — part of Wizard Central Toolkit."""

wiz_central_toolkit/debugwiz/__main__.py

@@ -0,0 +1,360 @@
+"""debugwiz — the diagnosis oracle. Ported from wizard_central's debug-wizard (with the locate-dispatch fix applied)."""
+import sys
+from pathlib import Path
+
+from .debug_wizard import (
+    DEBUG_LAW,
+    add_ignore,
+    audit_dir,
+    classify_file,
+    count_dir,
+    hotspot,
+    imports,
+    load_ignored,
+    locate,
+    names,
+    report_json,
+    signatures,
+    stack_digest,
+    stats_fleet,
+    suggest_fix,
+    timeline,
+    trace,
+)
+
+USAGE = """Debug Wizard — the diagnosis oracle
+alias: debugwiz
+usage: debug_wizard law                     print the DEBUG LAW alone
+       debug_wizard trace <file>            traceback autopsy
+       debug_wizard locate <dir> <pattern>  find files with error pattern
+       debug_wizard classify <file>         error type breakdown
+       debug_wizard stack [file]            stack digest of a traceback (file or stdin)
+       debug_wizard count <dir>             errors by category
+       debug_wizard hotspot <dir>           files with most errors
+       debug_wizard timeline <dir>          error frequency by mtime
+       debug_wizard imports <file>          missing import detection
+       debug_wizard names <file>            undefined name detection
+       debug_wizard signatures <file>       signature mismatch detection
+       debug_wizard suggest <file>          heuristic fix suggestion
+       debug_wizard propose <file>          stage fix via write_wizard
+       debug_wizard preview <file>          show staged proposal
+       debug_wizard explain <file>          human-readable explanation
+       debug_wizard audit <dir>             full error census
+       debug_wizard report <dir>            JSON report for CI/CD
+       debug_wizard log <dir>               write error log (staged via write_wizard)
+       debug_wizard ignore <path>           add to ignore list
+       debug_wizard ignored                 show ignored paths
+       debug_wizard stats                   error census of the current directory
+       debug_wizard versions                law/version drift detection
+exit codes: 0 ok | 1 failed | 2 out of scope"""
+
+CMDS = ("law", "trace", "locate", "classify", "stack", "count", "hotspot",
+        "timeline", "imports", "names", "signatures", "suggest", "propose",
+        "preview", "explain", "audit", "report", "log", "ignore", "ignored",
+        "stats", "versions")
+
+
+def _fix_target(p: Path) -> Path:
+    """Where a fix proposal for file p would land, if the Governor commits it."""
+    return Path.home() / ".debug-wizard" / f"fix_{p.stem}.txt"
+
+
+def _stage_via_writewiz(target: Path, content: str):
+    """Stage content through writewiz, the fleet sibling in this same package.
+
+    Import lane first (writewiz ships inside this toolkit); fall back to
+    the resolved writewiz executable — the same two lanes the fleet
+    itself uses. Staging only: the commit keystroke stays the Governor's.
+    Returns (ok, detail).
+    """
+    try:
+        from wiz_central_toolkit.writewiz.write_wizard import propose as _propose
+        draft, _meta, t = _propose(str(target), content)
+        return True, f"{draft.name} -> {t} ({len(content)} chars quarantined)"
+    except ImportError:
+        pass
+    import shutil
+    import subprocess
+    exe = shutil.which("write_wizard") or shutil.which("writewiz")
+    if exe is None:
+        for home_name in ("write_wizard", "writewiz"):
+            home_exe = Path.home() / "bin" / home_name
+            if home_exe.exists():
+                exe = str(home_exe)
+                break
+    if exe is None:
+        return False, "write_wizard not found (package import or PATH)"
+    try:
+        r = subprocess.run([exe, "propose", str(target)], input=content,
+                           capture_output=True, text=True, timeout=60)
+    except OSError as e:
+        return False, f"write_wizard unreachable: {e}"
+    if r.returncode != 0:
+        return False, (r.stdout + r.stderr).strip() or "write_wizard propose failed"
+    return True, (r.stdout.strip() or f"staged -> {target}")
+
+
+def _preview_via_writewiz(target: Path):
+    """(report_lines, hard_fail) for the draft staged for target, or None."""
+    try:
+        from wiz_central_toolkit.writewiz import write_wizard as _ww
+        draft, _meta = _ww._draft_path(Path(target))
+        if not draft.exists():
+            return None
+        return _ww.gate_and_diff(draft, Path(target))
+    except ImportError:
+        pass
+    import shutil
+    import subprocess
+    exe = shutil.which("write_wizard") or shutil.which("writewiz")
+    if exe is None:
+        return None
+    try:
+        r = subprocess.run([exe, "preview", str(target)],
+                           capture_output=True, text=True, timeout=60)
+    except OSError:
+        return None
+    out = (r.stdout + r.stderr).strip()
+    if "no quarantined draft" in out:
+        return None
+    return out.splitlines(), r.returncode != 0
+
+
+def main(argv=None) -> int:
+    try:
+        return _dispatch(argv)
+    except Exception as e:
+        print(f"[FAIL] {type(e).__name__}: {e}")
+        return 1
+
+
+def _dispatch(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+    if not args:
+        print(USAGE)
+        return 0
+    if args[0] not in CMDS:
+        print(USAGE)
+        return 2
+
+    cmd = args[0]
+
+    if cmd == "law":
+        print(DEBUG_LAW)
+        return 0
+    if cmd == "versions":
+        import hashlib
+        print("debug_law_sha256:", hashlib.sha256(DEBUG_LAW.encode()).hexdigest())
+        return 0
+    if cmd == "ignored":
+        ign = load_ignored()
+        if not ign:
+            print("(nothing ignored)")
+            return 0
+        for p in ign:
+            print(f"[IGNORED] {p}")
+        return 0
+    if cmd == "ignore":
+        if len(args) < 2:
+            return 2
+        r = add_ignore(args[1])
+        if r["ok"]:
+            print(f"[OK] ignored: {r['ignored']}")
+            return 0
+        print(f"[FAIL] {r['error']}")
+        return 1
+    if cmd == "stats":
+        for path, r in stats_fleet().items():
+            healthy = r.get("healthy", "?")
+            checked = r.get("files_checked", "?")
+            pct = r.get("health_pct", "?")
+            print(f"{path}: {healthy}/{checked} healthy ({pct}%)")
+        return 0
+
+    # --- locate: two args (dir, pattern) ---
+    if cmd == "locate":
+        if len(args) < 3:
+            print("[FAIL] locate requires a directory and a pattern")
+            return 2
+        d = Path(args[1]).expanduser()
+        pattern = args[2]
+        hits = locate(d, pattern)
+        if not hits:
+            print(f"(no files matching {pattern!r})")
+            return 0
+        for f in hits:
+            print(f"[MATCH] {f}")
+        return 1
+
+    # --- stack: a traceback digest; file argument or stdin ---
+    if cmd == "stack":
+        if len(args) >= 2 and args[1] != "-":
+            src = Path(args[1]).expanduser()
+            try:
+                text = src.read_text(encoding="utf-8", errors="replace")
+            except OSError as e:
+                print(f"[FAIL] cannot read {src}: {e}")
+                return 1
+            label = str(src)
+        else:
+            text = sys.stdin.read()
+            label = "stdin"
+        d = stack_digest(text)
+        if d is None:
+            print(f"[FAIL] no traceback found in {label}")
+            return 1
+        print(f"[OK] stack digest — {label}")
+        exc = d["type"] + (f": {d['message']}" if d["message"] else "")
+        print(f"  exception: {exc}")
+        print(f"  frames: {len(d['frames'])}")
+        for fr in d["frames"]:
+            print(f"    File \"{fr['file']}\", line {fr['line']}, "
+                  f"in {fr['func']} ({fr['home']})")
+        deep = d["deepest"]
+        print(f"  deepest frame: File \"{deep['file']}\", "
+              f"line {deep['line']}, in {deep['func']}")
+        dp = d["deepest_project"]
+        if dp is not None:
+            print(f"  deepest project frame: File \"{dp['file']}\", "
+                  f"line {dp['line']}, in {dp['func']}")
+        else:
+            print("  deepest project frame: none — every frame is library code")
+        for (ff, ln, fn), c in d["repeated"]:
+            print(f"  [RECURSION?] frame repeats {c} times: "
+                  f"File \"{ff}\", line {ln}, in {fn}")
+        return 0
+
+    # --- path-taking commands ---
+    if len(args) < 2:
+        print(f"[FAIL] {cmd} requires a path")
+        return 2
+    p = Path(args[1]).expanduser()
+
+    if cmd == "trace":
+        r = trace(p)
+        if r["ok"]:
+            print(f"[OK] {p}: no errors")
+            return 0
+        tb = r.get("traceback")
+        if tb:
+            print(f"[TRACE] {p}: {len(tb['frames'])} frame(s)")
+            for fr in tb["frames"]:
+                print(f"  File \"{fr['file']}\", line {fr['line']}, in {fr['func']}")
+        for e in r["errors"]:
+            print(f"[ERR] line {e['line']}: {e['type']} — {e['message']}")
+        return 1
+    if cmd == "classify":
+        r = classify_file(p)
+        print(f"[SUMMARY] {r['total']} errors")
+        for t, c in r["classification"].items():
+            print(f"  {t}: {c}")
+        return 1 if r["total"] else 0
+    if cmd == "count":
+        r = count_dir(p)
+        print(f"files={r['files_checked']} total_errors={r['totals']}")
+        return 0
+    if cmd == "hotspot":
+        hits = hotspot(p)
+        if not hits:
+            print("(all files healthy)")
+            return 0
+        for f, cnt in hits:
+            print(f"[HOT] {cnt} errors  {f}")
+        return 1 if hits else 0
+    if cmd == "timeline":
+        data = timeline(p)
+        for entry in data[:10]:
+            print(f"{entry['errors']} errors  {entry['mtime']}  {entry['file']}")
+        return 0
+    if cmd == "imports":
+        r = imports(p)
+        print(f"[IMPORTS] {p}")
+        if not r["likely_missing"]:
+            print("(no likely missing imports)")
+            return 0
+        for m in r["likely_missing"]:
+            print(f"  ? {m}")
+        return 1 if r["likely_missing"] else 0
+    if cmd == "names":
+        r = names(p)
+        if not r:
+            print("(no undefined names)")
+            return 0
+        for n in r:
+            print(f"  ? {n}")
+        return 1
+    if cmd == "signatures":
+        iss = signatures(p)
+        if not iss:
+            print("(no signature issues)")
+            return 0
+        for i in iss:
+            print(f"[WARN] line {i['line']}: {i['message']}")
+        return 1
+    if cmd == "suggest":
+        print(suggest_fix(p))
+        return 0
+    if cmd == "explain":
+        print(suggest_fix(p))
+        return 0
+    if cmd == "audit":
+        r = audit_dir(p)
+        print(f"[HEALTH] {r['healthy']}/{r['files_checked']} ({r['health_pct']}%)")
+        if r["unhealthy"]:
+            print(f"[FAIL] {r['unhealthy']} files with errors")
+            return 1
+        print("[OK] all files healthy")
+        return 0
+    if cmd == "report":
+        print(report_json(str(p)))
+        return 0
+    if cmd == "log":
+        r = audit_dir(p)
+        lines = [f"debug_wizard error log — {p}",
+                 f"files checked: {r['files_checked']}",
+                 f"healthy: {r['healthy']}  unhealthy: {r['unhealthy']}  "
+                 f"total errors: {r['total_errors']}"]
+        for f, cnt in hotspot(p):
+            lines.append(f"[HOT] {cnt} errors  {f}")
+            for e in trace(Path(f))["errors"]:
+                lines.append(f"  line {e['line']}: {e['type']} — {e['message']}")
+        target = (p / "debug-error-log.txt") if p.is_dir() \
+            else p.with_name(p.stem + "-error-log.txt")
+        ok, detail = _stage_via_writewiz(target, "\n".join(lines) + "\n")
+        if not ok:
+            print(f"[FAIL] 'log' could not stage via write_wizard: {detail}")
+            return 1
+        print(f"[STAGED] error log for {p} — {detail}")
+        print(f"to write it: write_wizard commit {target}   # your keystroke, Governor")
+        return 0
+    if cmd == "propose":
+        content = suggest_fix(p)
+        if not content.endswith("\n"):
+            content += "\n"
+        target = _fix_target(p)
+        ok, detail = _stage_via_writewiz(target, content)
+        if not ok:
+            print(f"[FAIL] propose could not stage via write_wizard: {detail}")
+            return 1
+        print(f"[STAGED] fix proposal for {p} — {detail}")
+        print(f"preview it: debug_wizard preview {p}")
+        return 0
+    if cmd == "preview":
+        got = _preview_via_writewiz(_fix_target(p))
+        if got is None:
+            print("(no staged proposal — use debugwiz propose first)")
+            return 0
+        report, hard_fail = got
+        for line in report:
+            print(line)
+        return 1 if hard_fail else 0
+
+    print("out of scope")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())