becwright 0.1.0__tar.gz → 0.2.1__tar.gz

{becwright-0.1.0/src/becwright.egg-info → becwright-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: becwright
-Version: 0.1.0
+Version: 0.2.1
 Summary: Deterministically enforces constraints (BECs) on your code, blocking commits that violate them.
 Author: Alonso David De Leon Rodarte
 License: MIT
@@ -18,6 +18,11 @@ Requires-Dist: pyyaml>=6
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: mcp>=1.2; extra == "dev"
+Provides-Extra: build
+Requires-Dist: pyinstaller>=6; extra == "build"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
 Dynamic: license-file
 
 > **English** · [Español](README.es.md)
@@ -72,26 +77,53 @@ becwright is installed once as a tool; each repo only contributes its own
 `.bec/rules.yaml`.
 
 ```bash
-# 1. Install the engine (once, global)
-pipx install git+https://github.com/DataDave-Dev/becwright.git   # or local: pipx install .
+# 1. Install the engine. Pick your ecosystem — no Python needed via npm/pnpm,
+#    which ship a self-contained binary:
+npm install --save-dev becwright    # or global: npm install -g becwright
+pnpm add -D becwright
+pipx install becwright              # or: pip install becwright
 
-# 2. In the repo where you want the rules, install the git hook
-becwright install                   # writes .git/hooks/pre-commit
+# 2. In your repo, scaffold rules + install the hook
+becwright init                      # detects your language, writes .bec/rules.yaml, installs the hook
 
-# 3. Write your rules in .bec/rules.yaml (see examples below)
-# 4. Done: each commit runs the checks; if a blocking rule fails, it stops.
+# 3. Done: each commit runs the checks; if a blocking rule fails, it stops.
 ```
 
+Installed as a devDependency, the pre-commit hook resolves the local binary from
+`node_modules/.bin`, so it works without a global install. The npm packages cover
+`linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64` and `win32-x64`; on any
+other platform use `pipx install becwright`.
+
 Available commands:
 
 | Command | What it does |
 |---|---|
+| `becwright init` | Scaffold a starter `.bec/rules.yaml` and install the hook |
+| `becwright list` | List the built-in checks |
 | `becwright check` | Runs the rules over the staged files |
 | `becwright install` | Installs the native `pre-commit` hook |
 | `becwright uninstall` | Removes the hook |
 | `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
 | `becwright import <file\|URL>` | Imports a BEC from another repo |
 
+### Use with AI agents (Claude Code)
+
+becwright is the deterministic net for what an AI agent lets slip. There is a
+Claude Code plugin so an agent can install and drive it for you:
+
+```text
+/plugin marketplace add DataDave-Dev/becwright
+/plugin install becwright@becwright
+```
+
+It adds a `becwright` skill and a `/becwright` command. See
+[`integrations/claude-code/`](integrations/claude-code/).
+
+For structured results, `becwright check --json` prints a machine-readable
+summary, and `becwright mcp` (install the `mcp` extra: `pipx install
+"becwright[mcp]"`) runs an MCP server exposing `check` and `list_checks` to any
+agent. See [`documentation/mcp.md`](documentation/mcp.md).
+
 A rule in `.bec/rules.yaml`:
 
 ```yaml
@@ -103,7 +135,7 @@ rules:
       If a token shows up in the logs, anyone with access to them can steal a
       user's session.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.no_token_in_logs"
+    check: "becwright run no_token_in_logs"
     severity: blocking   # blocking = stops the commit | warning = only warns
 ```
 
@@ -134,7 +166,7 @@ rules:
       A secret in the repo stays in git history forever and is visible to
       anyone with access to the code.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.hardcoded_secrets"
+    check: "becwright run hardcoded_secrets"
     severity: blocking
 
   - id: no-debug-remnants
@@ -143,7 +175,7 @@ rules:
     why_it_matters: >
       A forgotten breakpoint hangs the process in production or CI.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.debug_remnants"
+    check: "becwright run debug_remnants"
     severity: blocking
 
   - id: no-dangerous-eval
@@ -152,7 +184,7 @@ rules:
     why_it_matters: >
       eval/exec on untrusted input is remote code execution.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.dangerous_eval"
+    check: "becwright run dangerous_eval"
     severity: blocking
 
   - id: no-wildcard-imports
@@ -162,7 +194,7 @@ rules:
       Wildcard imports hide where each name comes from and break static
       analysis.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.wildcard_imports"
+    check: "becwright run wildcard_imports"
     severity: warning
 ```
 
@@ -183,7 +215,7 @@ rules:
     why_it_matters: >
       A forgotten 'debugger' halts execution and should not reach production.
     paths: ["**/*.js", "**/*.ts"]
-    check: "python3 -m becwright.checks.forbid --pattern '\\bdebugger\\b'"
+    check: "becwright run forbid --pattern '\\bdebugger\\b'"
     severity: blocking
 ```
 
@@ -214,10 +246,18 @@ Use `--yes` to skip the confirmation in automated environments.
 There is a **catalog of ready-to-use BECs** in [`becs/`](becs/) that you can
 import directly from their raw URL.
 
-Built-in checks (`python3 -m becwright.checks.*`) travel with the package, so
+Built-in checks (`becwright run *`) travel with the package, so
 the bundle only stores their name. A **custom** check (`.bec/checks/foo.py`)
 travels with its code embedded and lands in `.bec/checks/` of the target repo.
 
+## Documentation
+
+Technical documentation lives in [`documentation/`](documentation/):
+[architecture & flow](documentation/architecture.md),
+[usage & rules schema](documentation/usage.md),
+[writing checks](documentation/writing-checks.md), and
+[portability](documentation/portability.md).
+
 ## Current status
 
 The **installable MVP** is built and verified end-to-end: packaged engine

{becwright-0.1.0 → becwright-0.2.1}/README.md

@@ -50,26 +50,53 @@ becwright is installed once as a tool; each repo only contributes its own
 `.bec/rules.yaml`.
 
 ```bash
-# 1. Install the engine (once, global)
-pipx install git+https://github.com/DataDave-Dev/becwright.git   # or local: pipx install .
+# 1. Install the engine. Pick your ecosystem — no Python needed via npm/pnpm,
+#    which ship a self-contained binary:
+npm install --save-dev becwright    # or global: npm install -g becwright
+pnpm add -D becwright
+pipx install becwright              # or: pip install becwright
 
-# 2. In the repo where you want the rules, install the git hook
-becwright install                   # writes .git/hooks/pre-commit
+# 2. In your repo, scaffold rules + install the hook
+becwright init                      # detects your language, writes .bec/rules.yaml, installs the hook
 
-# 3. Write your rules in .bec/rules.yaml (see examples below)
-# 4. Done: each commit runs the checks; if a blocking rule fails, it stops.
+# 3. Done: each commit runs the checks; if a blocking rule fails, it stops.
 ```
 
+Installed as a devDependency, the pre-commit hook resolves the local binary from
+`node_modules/.bin`, so it works without a global install. The npm packages cover
+`linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64` and `win32-x64`; on any
+other platform use `pipx install becwright`.
+
 Available commands:
 
 | Command | What it does |
 |---|---|
+| `becwright init` | Scaffold a starter `.bec/rules.yaml` and install the hook |
+| `becwright list` | List the built-in checks |
 | `becwright check` | Runs the rules over the staged files |
 | `becwright install` | Installs the native `pre-commit` hook |
 | `becwright uninstall` | Removes the hook |
 | `becwright export <id>` | Exports a BEC to a `.bec.yaml` file |
 | `becwright import <file\|URL>` | Imports a BEC from another repo |
 
+### Use with AI agents (Claude Code)
+
+becwright is the deterministic net for what an AI agent lets slip. There is a
+Claude Code plugin so an agent can install and drive it for you:
+
+```text
+/plugin marketplace add DataDave-Dev/becwright
+/plugin install becwright@becwright
+```
+
+It adds a `becwright` skill and a `/becwright` command. See
+[`integrations/claude-code/`](integrations/claude-code/).
+
+For structured results, `becwright check --json` prints a machine-readable
+summary, and `becwright mcp` (install the `mcp` extra: `pipx install
+"becwright[mcp]"`) runs an MCP server exposing `check` and `list_checks` to any
+agent. See [`documentation/mcp.md`](documentation/mcp.md).
+
 A rule in `.bec/rules.yaml`:
 
 ```yaml
@@ -81,7 +108,7 @@ rules:
       If a token shows up in the logs, anyone with access to them can steal a
       user's session.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.no_token_in_logs"
+    check: "becwright run no_token_in_logs"
     severity: blocking   # blocking = stops the commit | warning = only warns
 ```
 
@@ -112,7 +139,7 @@ rules:
       A secret in the repo stays in git history forever and is visible to
       anyone with access to the code.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.hardcoded_secrets"
+    check: "becwright run hardcoded_secrets"
     severity: blocking
 
   - id: no-debug-remnants
@@ -121,7 +148,7 @@ rules:
     why_it_matters: >
       A forgotten breakpoint hangs the process in production or CI.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.debug_remnants"
+    check: "becwright run debug_remnants"
     severity: blocking
 
   - id: no-dangerous-eval
@@ -130,7 +157,7 @@ rules:
     why_it_matters: >
       eval/exec on untrusted input is remote code execution.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.dangerous_eval"
+    check: "becwright run dangerous_eval"
     severity: blocking
 
   - id: no-wildcard-imports
@@ -140,7 +167,7 @@ rules:
       Wildcard imports hide where each name comes from and break static
       analysis.
     paths: ["src/**/*.py"]
-    check: "python3 -m becwright.checks.wildcard_imports"
+    check: "becwright run wildcard_imports"
     severity: warning
 ```
 
@@ -161,7 +188,7 @@ rules:
     why_it_matters: >
       A forgotten 'debugger' halts execution and should not reach production.
     paths: ["**/*.js", "**/*.ts"]
-    check: "python3 -m becwright.checks.forbid --pattern '\\bdebugger\\b'"
+    check: "becwright run forbid --pattern '\\bdebugger\\b'"
     severity: blocking
 ```
 
@@ -192,10 +219,18 @@ Use `--yes` to skip the confirmation in automated environments.
 There is a **catalog of ready-to-use BECs** in [`becs/`](becs/) that you can
 import directly from their raw URL.
 
-Built-in checks (`python3 -m becwright.checks.*`) travel with the package, so
+Built-in checks (`becwright run *`) travel with the package, so
 the bundle only stores their name. A **custom** check (`.bec/checks/foo.py`)
 travels with its code embedded and lands in `.bec/checks/` of the target repo.
 
+## Documentation
+
+Technical documentation lives in [`documentation/`](documentation/):
+[architecture & flow](documentation/architecture.md),
+[usage & rules schema](documentation/usage.md),
+[writing checks](documentation/writing-checks.md), and
+[portability](documentation/portability.md).
+
 ## Current status
 
 The **installable MVP** is built and verified end-to-end: packaged engine

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

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "becwright"
-version = "0.1.0"
+version = "0.2.1"
 description = "Deterministically enforces constraints (BECs) on your code, blocking commits that violate them."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,7 +28,11 @@ classifiers = [
 becwright = "becwright.cli:main"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-cov>=5"]
+dev = ["pytest>=8", "pytest-cov>=5", "mcp>=1.2"]
+# Used to freeze the standalone binary distributed via npm (see packaging/).
+build = ["pyinstaller>=6"]
+# MCP server for AI agents: `becwright mcp` (see src/becwright/mcp_server.py).
+mcp = ["mcp>=1.2"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

becwright-0.2.1/src/becwright/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

becwright-0.2.1/src/becwright/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/bundle.py

@@ -11,7 +11,11 @@ from .rules import Rule
 
 BUNDLE_VERSION = 1
 
-_BUILTIN = re.compile(r"^python3?\s+-m\s+becwright\.checks\.(\w+)(?:\s+(.*))?$")
+# Accept the current `becwright run <module>` form and the legacy
+# `python3 -m becwright.checks.<module>` form so older bundles still import.
+_BUILTIN = re.compile(
+    r"^(?:becwright\s+run\s+(\w+)|python3?\s+-m\s+becwright\.checks\.(\w+))(?:\s+(.*))?$"
+)
 _PY_PATH = re.compile(r"[\w./-]+\.py")
 _ITEM_INDENT = re.compile(r"^([ \t]+)-\s", re.MULTILINE)
 _EMPTY_RULES = re.compile(r"^rules:[ \t]*(?:\[[ \t]*\]|\{[ \t]*\})[ \t]*$", re.MULTILINE)
@@ -41,9 +45,9 @@ def classify_check(command: str, root: Path) -> dict:
     command = command.strip()
     builtin = _BUILTIN.match(command)
     if builtin:
-        out = {"kind": "builtin", "module": builtin.group(1)}
-        if builtin.group(2):
-            out["args"] = builtin.group(2).strip()
+        out = {"kind": "builtin", "module": builtin.group(1) or builtin.group(2)}
+        if builtin.group(3):
+            out["args"] = builtin.group(3).strip()
         return out
     for token in _PY_PATH.findall(command):
         candidate = root / token
@@ -108,7 +112,7 @@ def materialize(bundle: dict, root: Path) -> dict:
     check = bundle["check"]
     kind = check.get("kind")
     if kind == "builtin":
-        command = f"python3 -m becwright.checks.{check['module']}"
+        command = f"becwright run {check['module']}"
         if check.get("args"):
             command += f" {check['args']}"
     elif kind == "script":

becwright-0.2.1/src/becwright/checks/_ignore.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import re
+
+# A line carrying this marker (inside a comment, in any language) is exempt from
+# any check: `# becwright: ignore`, `// becwright: ignore`, etc.
+_MARKER = re.compile(r"becwright:\s*ignore\b", re.IGNORECASE)
+
+
+def is_ignored(line: str) -> bool:
+    return bool(_MARKER.search(line))

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/dangerous_eval.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import sys
 
+from ._ignore import is_ignored
+
 PATTERN = re.compile(r"\b(?:eval|exec)\s*\(")
 
 
@@ -15,7 +17,7 @@ def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if PATTERN.search(line):
+                    if PATTERN.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/debug_remnants.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import sys
 
+from ._ignore import is_ignored
+
 PATTERN = re.compile(
     r"\bbreakpoint\s*\(|\b(?:i?pdb)\.set_trace\s*\(|\bimport\s+i?pdb\b"
 )
@@ -17,7 +19,7 @@ def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if PATTERN.search(line):
+                    if PATTERN.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/forbid.py

@@ -4,6 +4,8 @@ import argparse
 import re
 import sys
 
+from ._ignore import is_ignored
+
 
 def find_violations(paths: list[str], pattern: str, flags: int = 0) -> list[tuple[str, int, str]]:
     rx = re.compile(pattern, flags)
@@ -15,7 +17,7 @@ def find_violations(paths: list[str], pattern: str, flags: int = 0) -> list[tupl
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if rx.search(line):
+                    if rx.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/hardcoded_secrets.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import sys
 
+from ._ignore import is_ignored
+
 _AWS_KEY = r"AKIA[0-9A-Z]{16}"
 _PRIVATE_KEY = r"-----BEGIN [A-Z ]*PRIVATE KEY-----"
 _ASSIGNMENT = (
@@ -27,7 +29,7 @@ def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if PATTERN.search(line) and not _PLACEHOLDER.search(line):
+                    if PATTERN.search(line) and not _PLACEHOLDER.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/no_token_in_logs.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import sys
 
+from ._ignore import is_ignored
+
 SENSITIVE = r"(token|password|passwd|secret|api[_-]?key|credential|session[_-]?id)"
 LOG_CALL = r"(log\.|logger\.|logging\.|print\s*\()"
 # A log call that mentions something sensitive on the same line.
@@ -18,7 +20,7 @@ def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if PATTERN.search(line):
+                    if PATTERN.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue

{becwright-0.1.0 → becwright-0.2.1}/src/becwright/checks/wildcard_imports.py

@@ -3,6 +3,8 @@ from __future__ import annotations
 import re
 import sys
 
+from ._ignore import is_ignored
+
 PATTERN = re.compile(r"^\s*from\s+[\w.]+\s+import\s+\*")
 
 
@@ -15,7 +17,7 @@ def find_violations(paths: list[str]) -> list[tuple[str, int, str]]:
         try:
             with open(path, encoding="utf-8") as f:
                 for lineno, line in enumerate(f, start=1):
-                    if PATTERN.search(line):
+                    if PATTERN.search(line) and not is_ignored(line):
                         violations.append((path, lineno, line.strip()))
         except (FileNotFoundError, IsADirectoryError, UnicodeDecodeError):
             continue