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

wiz_central_toolkit/pythonwiz/lib/python_wizard.py

@@ -0,0 +1,353 @@
+"""python-wizard core: standalone syntax doctor for Python files."""
+import ast
+import re
+import shutil
+import sys
+from pathlib import Path
+
+SKIP_DIRS = {".venv", ".git", "__pycache__", ".bootstrap", "node_modules"}
+STDLIB = set(sys.stdlib_module_names)
+
+class PythonWizard:
+    """AST analysis engine. Never executes the target code — parse only."""
+
+    # ---------- existing ----------
+    def check_file(self, path: Path) -> dict:
+        try:
+            ast.parse(path.read_text())
+            return {"file": str(path), "valid": True}
+        except FileNotFoundError:
+            return {"file": str(path), "valid": False, "error": "file not found"}
+        except SyntaxError as e:
+            return {"file": str(path), "valid": False, "line": e.lineno,
+                    "col": e.offset, "error": e.msg}
+
+    def check_dir(self, root: Path) -> list:
+        results = []
+        for py in self.py_files(root):
+            results.append(self.check_file(py))
+        return results
+
+    def check_entry(self, path: Path) -> dict:
+        if not path.exists():
+            return {"file": str(path), "valid": False, "error": "file not found"}
+        content = path.read_text()
+        first = content.splitlines()[0] if content else ""
+        if not first.startswith("#!"):
+            return {"file": str(path), "valid": False, "error": "no shebang line"}
+        parts = first[2:].split()
+        if not parts:
+            return {"file": str(path), "valid": False, "error": "empty shebang line"}
+        exe = parts[0]
+        if Path(exe).name == "env":
+            # env form: #!/usr/bin/env [-flags] [VAR=value ...] <interpreter> [args]
+            cmd = None
+            for tok in parts[1:]:
+                if tok.startswith("-"):
+                    continue
+                if "=" in tok and "/" not in tok.split("=")[0]:
+                    continue  # VAR=value assignment, not the command
+                cmd = tok
+                break
+            if cmd is None:
+                return {"file": str(path), "valid": False,
+                        "error": f"interpreter missing: {first[2:]}"}
+            found = shutil.which(cmd)
+            if not found:
+                return {"file": str(path), "valid": False,
+                        "error": f"interpreter missing: {cmd}"}
+            return {"file": str(path), "valid": True, "interpreter": found}
+        interp = Path(exe)
+        if interp.is_absolute():
+            if not interp.exists():
+                return {"file": str(path), "valid": False,
+                        "error": f"interpreter missing: {exe}"}
+            return {"file": str(path), "valid": True, "interpreter": str(interp)}
+        found = shutil.which(exe)
+        if not found:
+            return {"file": str(path), "valid": False,
+                    "error": f"interpreter missing: {exe}"}
+        return {"file": str(path), "valid": True, "interpreter": found}
+
+    # ---------- helpers ----------
+    @staticmethod
+    def py_files(root: Path) -> list:
+        return [p for p in sorted(root.rglob("*.py"))
+                if not any(part in SKIP_DIRS for part in p.parts)]
+
+    @staticmethod
+    def parse(path: Path) -> ast.Module:
+        return ast.parse(path.read_text())
+
+    # ---------- new commands ----------
+    def outline(self, path: Path) -> list:
+        tree = self.parse(path)
+        symbols = []
+
+        def visit(node, prefix=""):
+            for child in ast.iter_child_nodes(node):
+                if isinstance(child, ast.ClassDef):
+                    symbols.append(("class", prefix + child.name, child.lineno))
+                    visit(child, prefix + child.name + ".")
+                elif isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    symbols.append(("def", prefix + child.name, child.lineno))
+
+        visit(tree)
+        return symbols
+
+    def imports_of(self, path: Path) -> dict:
+        tree = self.parse(path)
+        siblings = {p.stem for p in path.parent.glob("*.py")}
+        result = {"stdlib": set(), "third_party": set(), "local": set(), "relative": set()}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for a in node.names:
+                    top = a.name.split(".")[0]
+                    if top in STDLIB:
+                        result["stdlib"].add(a.name)
+                    elif top in siblings:
+                        result["local"].add(a.name)
+                    else:
+                        result["third_party"].add(a.name)
+            elif isinstance(node, ast.ImportFrom):
+                if node.level > 0:
+                    result["relative"].add("." * node.level + (node.module or ""))
+                elif node.module:
+                    top = node.module.split(".")[0]
+                    if top in siblings:
+                        result["local"].add(node.module)
+                    elif top in STDLIB:
+                        result["stdlib"].add(node.module)
+                    else:
+                        result["third_party"].add(node.module)
+        return {k: sorted(v) for k, v in result.items()}
+
+    def todos_of(self, path: Path) -> list:
+        pat = re.compile(r"#\s*(TODO|FIXME|XXX|BUG|HACK)\b[:]?(.*)", re.I)
+        out = []
+        for i, line in enumerate(path.read_text().splitlines(), 1):
+            m = pat.search(line)
+            if m:
+                out.append((i, m.group(1).upper(), m.group(2).strip()))
+        return out
+
+    def deadcode(self, path: Path) -> list:
+        """Candidates only: names defined but never referenced by name.
+        Attribute-called methods may appear here — static analysis limit."""
+        tree = self.parse(path)
+        defined = {}
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                defined[node.name] = node.lineno
+        used = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+        dead = [(n, ln) for n, ln in defined.items()
+                if n not in used and not n.startswith("__")]
+        return sorted(dead, key=lambda x: x[1])
+
+    def complexity(self, path: Path) -> list:
+        tree = self.parse(path)
+        out = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                c = 1
+                for sub in ast.walk(node):
+                    if isinstance(sub, (ast.If, ast.For, ast.While,
+                                        ast.ExceptHandler, ast.With)):
+                        c += 1
+                    elif isinstance(sub, ast.BoolOp):
+                        c += len(sub.values) - 1
+                out.append((node.name, node.lineno, c))
+        return sorted(out, key=lambda x: -x[2])
+
+    def loc_stats(self, path: Path) -> dict:
+        lines = path.read_text().splitlines()
+        code = blank = comment = 0
+        for l in lines:
+            s = l.strip()
+            if not s:
+                blank += 1
+            elif s.startswith("#"):
+                comment += 1
+            else:
+                code += 1
+        tree = self.parse(path)
+        funcs = sum(1 for n in ast.walk(tree)
+                   if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)))
+        classes = sum(1 for n in ast.walk(tree) if isinstance(n, ast.ClassDef))
+        return {"lines": len(lines), "code": code, "blank": blank,
+                "comment": comment, "functions": funcs, "classes": classes}
+
+    def docstring_report(self, path: Path) -> list:
+        tree = self.parse(path)
+        out = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                if ast.get_docstring(node) is None:
+                    out.append((node.lineno, node.name))
+        return sorted(out)
+
+    def explain_error(self, path: Path) -> dict:
+        try:
+            ast.parse(path.read_text())
+            return {"valid": True}
+        except SyntaxError as e:
+            lines = path.read_text().splitlines()
+            ctx = []
+            lo = max(0, (e.lineno or 1) - 2)
+            hi = min(len(lines), (e.lineno or 1) + 1)
+            for i in range(lo, hi):
+                mark = "->" if i + 1 == e.lineno else "  "
+                ctx.append(f"{mark} {i+1:4d}| {lines[i]}")
+            return {"valid": False, "line": e.lineno, "col": e.offset,
+                    "error": e.msg, "context": ctx}
+
+    def shebangs_dir(self, root: Path) -> list:
+        results = []
+        for p in self.py_files(root):
+            with p.open() as f:
+                first = f.readline().strip()
+            if first.startswith("#!"):
+                interp = first[2:]
+                ok = Path(interp).is_absolute() and Path(interp).exists()
+                results.append((p, interp, ok))
+        return results
+
+    def deps(self, path: Path) -> list:
+        return self.imports_of(path)["third_party"]
+
+    def call_map(self, path: Path) -> dict:
+        tree = self.parse(path)
+        m = {}
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                calls = set()
+                for n in ast.walk(node):
+                    if isinstance(n, ast.Call):
+                        if isinstance(n.func, ast.Name):
+                            calls.add(n.func.id)
+                        elif isinstance(n.func, ast.Attribute):
+                            calls.add("." + getattr(n.func, "attr", "?"))
+                m[node.name] = sorted(calls)
+        return m
+
+    def longest_functions(self, path: Path) -> list:
+        tree = self.parse(path)
+        out = []
+        for n in ast.walk(tree):
+            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)) and n.end_lineno:
+                out.append((n.name, n.lineno, (n.end_lineno - n.lineno) + 1))
+        return sorted(out, key=lambda x: -x[2])
+
+    def bare_excepts(self, path: Path) -> list:
+        tree = self.parse(path)
+        out = []
+        for n in ast.walk(tree):
+            if isinstance(n, ast.ExceptHandler):
+                name = n.type.id if isinstance(n.type, ast.Name) else None
+                if n.type is None or name in ("Exception", "BaseException"):
+                    swallows = any(isinstance(s, ast.Pass) for s in n.body)
+                    out.append((n.lineno, "bare" if n.type is None else name, swallows))
+        return out
+
+    def secrets_scan(self, path: Path, show_secrets: bool = False) -> list:
+        """Hardcoded-credential findings as (lineno, kind, text) rows.
+
+        Redaction is the default (AVS ruling, 2026-11-09 — the RS006
+        paste-safety standard applied toolkit-wide): `text` is the
+        source line with the secret value replaced by <redacted>, so
+        the value appears nowhere in the report; `kind` names the
+        credential pattern matched. Only the deliberate opt-in
+        show_secrets=True returns the line exactly as written.
+        """
+        pat = re.compile(
+            r"(?i)(password|passwd|pwd|token|secret|api[_-]?key)"
+            r"\s*[=:]\s*(['\"])([^'\"]{3,})")
+        out = []
+        for i, line in enumerate(path.read_text().splitlines(), 1):
+            m = pat.search(line)
+            if not m:
+                continue
+            kind = m.group(1).lower().replace("-", "_")
+            if kind == "apikey":
+                kind = "api_key"
+            text = line.strip()
+            if not show_secrets:
+                lead = len(line) - len(line.lstrip())
+                start = m.start(3) - lead
+                end = m.end(3) - lead
+                text = text[:start] + "<redacted>" + text[end:]
+            out.append((i, kind, text))
+        return out
+
+    def main_guard(self, path: Path) -> dict:
+        tree = self.parse(path)
+        has = False
+        for node in ast.walk(tree):
+            if isinstance(node, ast.If):
+                src = ast.dump(node.test)
+                if "__name__" in src and "__main__" in src:
+                    has = True
+        return {"has_main_guard": has}
+
+    def globals_audit(self, path: Path) -> list:
+        tree = self.parse(path)
+        out = []
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                val = node.value
+                mutable = isinstance(val, (ast.List, ast.Dict, ast.Set,
+                                           ast.ListComp, ast.DictComp, ast.SetComp))
+                names = [t.id for t in node.targets if isinstance(t, ast.Name)]
+                out.append((node.lineno, ", ".join(names),
+                            "mutable" if mutable else "immutable"))
+        return out
+
+    def magic_numbers(self, path: Path) -> list:
+        COMMON = {0, 1, 2, -1, 3, 4, 8, 10, 16, 32, 64, 100, 1000}
+        tree = self.parse(path)
+        found = []
+        for node in ast.walk(tree):
+            if (isinstance(node, ast.Constant)
+                    and isinstance(node.value, (int, float))
+                    and not isinstance(node.value, bool)
+                    and node.value not in COMMON):
+                found.append((node.lineno, node.value))
+        return sorted(set(found), key=lambda x: x[0])
+
+    def compare_symbols(self, a: Path, b: Path) -> dict:
+        try:
+            sa = {(k, n) for k, n, _ in self.outline(a)}
+            sb = {(k, n) for k, n, _ in self.outline(b)}
+        except SyntaxError as e:
+            return {"error": f"line {e.lineno}, col {e.offset}: {e.msg}"}
+        return {"only_a": sorted(sa - sb), "only_b": sorted(sb - sa),
+                "common": sorted(sa & sb)}
+
+    def tree_summary(self, root: Path) -> dict:
+        files = self.py_files(root)
+        total_lines = funcs = classes = invalid = 0
+        for p in files:
+            if not self.check_file(p)["valid"]:
+                invalid += 1
+                continue
+            text = p.read_text()
+            total_lines += len(text.splitlines())
+            for n in ast.walk(ast.parse(text)):
+                if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    funcs += 1
+                elif isinstance(n, ast.ClassDef):
+                    classes += 1
+        return {"files": len(files), "lines": total_lines,
+                "functions": funcs, "classes": classes, "invalid": invalid}
+
+    def health_score(self, path: Path) -> dict:
+        r = self.check_file(path)
+        if not r["valid"]:
+            return {"score": 0, "reason": f"syntax error at line {r.get('line')}"}
+        docs_missing = len(self.docstring_report(path))
+        bare = len(self.bare_excepts(path))
+        td = len(self.todos_of(path))
+        hotspots = len([c for _, _, c in self.complexity(path) if c > 10])
+        penalty = 5 * docs_missing + 10 * bare + 3 * td + 10 * hotspots
+        return {"score": max(0, 100 - penalty), "docstrings_missing": docs_missing,
+                "bare_excepts": bare, "todos": td, "complexity_hotspots": hotspots}

wiz_central_toolkit/readwiz/__init__.py

@@ -0,0 +1,5 @@
+"""Readwiz package exports."""
+
+from .lib import read_wizard
+
+__all__ = ["read_wizard"]

wiz_central_toolkit/readwiz/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point for readwiz dispatch."""
+import sys
+from .lib import cli as internal_cli
+
+def main(argv=None):
+    old_argv = sys.argv
+    if argv is not None:
+        sys.argv = [sys.argv[0]] + list(argv)
+    try:
+        return internal_cli.main()
+    finally:
+        sys.argv = old_argv
+
+if __name__ == "__main__":
+    sys.exit(main())

wiz_central_toolkit/readwiz/cli.py

@@ -0,0 +1,46 @@
+"""read-wizard face — thin CLI over the policy brain."""
+
+import sys
+
+from .lib.read_wizard import check_command, LAW_TEXT, ALLOW_VERBS, DENY_VERBS
+
+USAGE = """Read Wizard — read-only mode policy engine (verb gate)
+usage: readwiz check "<raw shell command>"
+       readwiz verbs          dump the allow/deny tables
+       readwiz law            print the READ LAW alone
+verdicts: ALLOW / DENIED | exit 0 = allow, 1 = denied, 2 = usage error"""
+
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in ("-h", "--help"):
+        print(USAGE)
+        return 0
+    if not args or args[0] not in ("check", "verbs", "law"):
+        print(USAGE)
+        return 2
+
+    if args[0] == "law":
+        print(LAW_TEXT)
+        return 0
+
+    if args[0] == "verbs":
+        print("[ALLOW]")
+        for v in sorted(ALLOW_VERBS):
+            print(f"  {v}")
+        print("[DENY]")
+        for v in sorted(DENY_VERBS):
+            print(f"  {v}")
+        return 0
+
+    # check mode
+    if len(args) < 2:
+        print("[FAIL] readwiz check requires a quoted command string")
+        return 2
+
+    verdict, reason = check_command(" ".join(args[1:]))
+    if verdict == "ALLOW":
+        print(f"[ALLOW] {reason}")
+        return 0
+    print(f"[DENIED] {reason}")
+    return 1

wiz_central_toolkit/readwiz/lib/__init__.py

@@ -0,0 +1 @@
+# wizard package init

wiz_central_toolkit/readwiz/lib/cli.py

@@ -0,0 +1,47 @@
+"""read-wizard face — thin CLI over the policy brain."""
+
+import sys
+
+from .read_wizard import check_command, LAW_TEXT, ALLOW_VERBS, DENY_VERBS
+
+USAGE = """Read Wizard — read-only mode policy engine (verb gate)
+alias: readwiz
+usage: read_wizard check "<raw shell command>"
+       read_wizard verbs          dump the allow/deny tables
+       read_wizard law            print the READ LAW alone
+verdicts: ALLOW / DENIED | exit 0 = allow, 1 = denied, 2 = usage error"""
+
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+    if not args or args[0] not in ("check", "verbs", "law"):
+        print(USAGE)
+        return 2
+
+    if args[0] == "law":
+        print(LAW_TEXT)
+        return 0
+
+    if args[0] == "verbs":
+        print("[ALLOW]")
+        for v in sorted(ALLOW_VERBS):
+            print(f"  {v}")
+        print("[DENY]")
+        for v in sorted(DENY_VERBS):
+            print(f"  {v}")
+        return 0
+
+    # check mode
+    if len(args) < 2:
+        print("[FAIL] read_wizard check requires a quoted command string")
+        return 2
+
+    verdict, reason = check_command(" ".join(args[1:]))
+    if verdict == "ALLOW":
+        print(f"[ALLOW] {reason}")
+        return 0
+    print(f"[DENIED] {reason}")
+    return 1

wiz_central_toolkit/readwiz/lib/read_wizard.py

@@ -0,0 +1,121 @@
+"""read-wizard brain — the read-only policy engine.
+
+READ LAW:
+  This wizard judges, it never acts. Given a raw shell command,
+  it answers ALLOW / DENIED / out of scope. Its tables are the
+  single source of truth for read-only mode in every REPL that
+  binds it. Mortal and stateless: one verdict per invocation.
+"""
+
+import shlex
+
+# ------------------------------------------------------------------
+# THE VERB TABLES — the law itself. Amend only by Governor decree.
+# ------------------------------------------------------------------
+
+ALLOW_VERBS = frozenset({
+    # observation
+    "ls", "ll", "la", "cat", "head", "tail", "less", "more", "wc",
+    "file", "stat", "du", "df", "tree", "find", "locate", "which",
+    "whereis", "type", "echo", "date", "whoami", "hostname", "pwd",
+    "uname", "uptime", "env", "printenv", "id", "groups", "history",
+    # search
+    "grep", "rg", "fgrep", "ag", "awk", "cut", "sort", "uniq", "nl",
+    "column", "strings",
+    # fleet read-only citizens — other wizards ARE read verbs
+    "helpwiz", "pythonwiz", "diffwiz", "jsonwiz", "cmdwiz", "manualwiz",
+    "gitwiz", "mapwiz",   # Governor decree 2026-09-18 — newborn inspectors admitted
+    "gitwiz", "mapwiz",   # Governor decree 2026-09-18 — newborn inspectors admitted
+    "truthwiz", "ollamawiz", "probewiz", "rustwiz", "readwiz",
+    "benchwiz", "modelfilewiz",  # exam/show/hash/verify/list only
+    # introspection
+    "jq", "git",          # git gated separately (see GIT_DENY_SUBS)
+    "python3",             # gated: only with -c check or read scripts
+})
+
+# git subverbs that mutate — git itself is allowed, these are not
+GIT_DENY_SUBS = frozenset({
+    "push", "commit", "add", "reset", "checkout", "merge", "rebase",
+    "cherry-pick", "stash", "clean", "rm", "mv", "apply", "tag",
+    "restore", "switch", "worktree",
+})
+
+# absolute denies — anything touching these dies regardless of position
+DENY_VERBS = frozenset({
+    "rm", "rmdir", "mv", "cp", "ln", "touch", "mkdir", "tee", "truncate",
+    "dd", "shred", "chmod", "chown", "chattr", "setfacl", "install",
+    "kill", "pkill", "shutdown", "reboot", "poweroff", "systemctl",
+    "service", "crontab", "useradd", "userdel", "passwd", "sudo", "su",
+    "doas", "mount", "umount", "umount", "mkfs", "pip", "pip3", "apt",
+    "apt-get", "snap", "npm", "curl", "wget", "scp", "rsync", "ssh",
+    "sftp", "nc", "socat", "bootwiz",  # birthing citizens is Tier 2
+})
+
+# raw-string tokens that mean writing no matter which verb fronts them
+WRITE_MARKERS = (">>", ">", "$(", "`")
+
+
+def _first_verb(segment):
+    """Peel the first word of one pipe-segment, tolerating quoting."""
+    try:
+        words = shlex.split(segment)
+    except ValueError:
+        return None
+    words = [w for w in words if w and w != "sudo"]
+    return words[0] if words else None
+
+
+def check_command(raw):
+    """Judge one raw shell line. Returns (verdict, reason).
+
+    verdict: 'ALLOW' | 'DENIED'
+    """
+    if not raw or not raw.strip():
+        return "DENIED", "empty command"
+    raw = raw.strip()
+
+    # stage 1 — write markers anywhere in the raw line
+    for marker in WRITE_MARKERS:
+        if marker in raw:
+            return "DENIED", f"write marker '{marker}' present"
+
+    # stage 2 — judge every segment of every pipe
+    for segment in raw.split("|"):
+        seg = segment.strip()
+        if not seg:
+            continue
+        verb = _first_verb(seg)
+        if verb is None:
+            return "DENIED", "unparseable segment"
+        # peel path prefixes: /usr/bin/grep -> grep
+        verb_clean = verb.rsplit("/", 1)[-1]
+
+        if verb_clean in DENY_VERBS:
+            return "DENIED", f"verb '{verb_clean}' is a write/mutate verb"
+        if verb_clean not in ALLOW_VERBS:
+            return "DENIED", f"verb '{verb_clean}' not on the read allowlist"
+
+        # git subverb gate
+        if verb_clean in ("git", "/usr/bin/git"):
+            try:
+                words = shlex.split(seg)
+            except ValueError:
+                return "DENIED", "unparseable git command"
+            subs = [w for w in words[1:] if not w.startswith("-")]
+            if subs and subs[0] in GIT_DENY_SUBS:
+                return "DENIED", f"git subverb '{subs[0]}' mutates state"
+
+    return "ALLOW", "read-only"
+
+
+# ---------------- charter text ----------------
+
+LAW_TEXT = """READ LAW (Read Wizard, the verb gate)
+1. The Read Wizard judges; it never executes. REPLs bind it as policy engine.
+2. ALLOW means read-only: observation, search, fleet read-only citizens.
+3. Redirection (>, >>), substitution ($(), `) and every write verb: DENIED.
+4. Unknown verbs default DENIED — absence from the table is not permission.
+5. git is read-only ONLY for its observing subverbs (status, log, diff, show...).
+6. Tables amend only by Governor decree, witnessed by commit.
+7. Mortal and stateless: one verdict, then death. No memory of commands seen.
+"""

wiz_central_toolkit/rustwiz/__init__.py

@@ -0,0 +1,5 @@
+"""Rustwiz package exports."""
+
+from .lib import rust_wizard
+
+__all__ = ["rust_wizard"]

wiz_central_toolkit/rustwiz/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for wiz dispatch."""
+import sys
+from .lib.cli import main
+from .lib.rust_wizard import RustWizard  # noqa: F401 (re-exported for tests)
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

wiz_central_toolkit/rustwiz/cli.py

@@ -0,0 +1,4 @@
+"""rustwiz CLI entry point; the implementation lives in lib/cli.py."""
+from .lib.cli import main
+
+__all__ = ["main"]

wiz_central_toolkit/rustwiz/lib/__init__.py

@@ -0,0 +1 @@
+# wizard package init

wiz_central_toolkit/rustwiz/lib/cli.py

@@ -0,0 +1,53 @@
+import sys
+try:
+    from .rust_wizard import LAW_TEXT, RustWizard, package_version
+except ImportError:  # run directly as a script, outside the package
+    sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
+    from rust_wizard import LAW_TEXT, RustWizard, package_version
+
+USAGE = """Rust Wizard — Rust project checker
+alias: rustwiz
+usage: rust_wizard check <file.rs|dir> ...
+       rust_wizard build <crate-dir>    cargo check the crate
+       rust_wizard run <crate-dir>      build and run the crate's binary
+       rust_wizard test <crate-dir>     cargo test
+       rust_wizard clippy <crate-dir>   cargo clippy lints
+       rust_wizard fmt <crate-dir>      cargo fmt --check (reports drift only)
+       rust_wizard doc <crate-dir>      cargo doc --no-deps
+       rust_wizard clean <crate-dir>    cargo clean (removes target/ only)
+       rust_wizard law                  print the RUST LAW alone
+       rust_wizard version              print the version
+       rust_wizard --help | --version"""
+
+CRATE_COMMANDS = ("build", "run", "test", "clippy", "fmt", "doc", "clean")
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] in ("-h", "--help", "help"):
+        print(USAGE)
+        return 0
+    if argv and argv[0] == "--version":
+        print(f"rust_wizard {package_version()}")
+        return 0
+    if not argv:
+        print(f"out of scope - usage:\n{USAGE}")
+        return 2
+    cmd, args = argv[0], argv[1:]
+    if cmd == "law":
+        print(LAW_TEXT)
+        return 0
+    if cmd == "version":
+        print(f"rust_wizard {package_version()}")
+        return 0
+    wz = RustWizard()
+    if cmd == "check" and args:
+        return wz.check(args)
+    if cmd in CRATE_COMMANDS and args:
+        return getattr(wz, cmd)(args[0])
+    print(f"out of scope - unknown or incomplete command: {' '.join(argv)}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())