pybun-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{pybun_cli-0.2.0/pybun_cli.egg-info → pybun_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybun-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: PyBun shim bootstrapper for signed releases
 Author: PyBun Authors
 License-Expression: MIT
@@ -271,6 +271,18 @@ pybun x cowsay==6.1
 pybun x black -- --check .
 ```
 
+### Affected Tests
+
+```bash
+pybun test --affected
+pybun test --affected --since main --format=json
+pybun test --affected --discover --format=json
+```
+
+`--changed` is an alias for `--affected`. Selection is repository-wide and cannot be combined with explicit paths or `--member`. MCP `pybun_test` uses the same service with `{"changed": true, "since": "main"}`.
+
+JSON includes `selection` with `direct`, `transitive`, or `conservative` reasons and import chains. The target Python's standard AST parser reads project source without executing it. Imports and ancestor `conftest.py` dependencies are modeled; uncertain parsing, known dynamic imports, or non-Python/configuration changes conservatively select all tests. Import-root ambiguity may select extra tests. Arbitrary runtime file dependencies are not inferred. Unavailable git/runtime evidence returns an error rather than a verified empty selection.
+
 ### Python Version Management
 
 ```bash
@@ -368,6 +380,8 @@ pybun audit --severity-threshold=medium
 pybun audit --fail-on=high
 ```
 
+The scanner follows OSV batch pagination and fetches advisory details before filtering or suggesting fixes. Missing severity is reported as `unknown`, remains visible at every threshold, and fails any `--fail-on` gate. Failed advisory lookups fail the scan. `PYBUN_OSV_URL` can point to a mirror's batch endpoint; its sibling `vulns/<id>` endpoint must serve full advisories.
+
 ### Profile Management
 
 ```bash
@@ -438,6 +452,8 @@ pybun self update --dry-run
 pybun self update --channel nightly
 ```
 
+MCP exposes the same doctor remediation plan: call `pybun_doctor` with `{"fix": true}` to preview, or `{"fix": true, "apply": true}` to apply low-risk, auto-applicable fixes. `applied_fixes` includes before/after cache counts; `skipped_fixes` explains candidates requiring manual action. The existing `pybun_fix` tool continues to fix lint violations with Ruff.
+
 ## Sandbox usage
 
 Use the sandbox for untrusted scripts or PEP 723 snippets:
@@ -445,7 +461,34 @@ Use the sandbox for untrusted scripts or PEP 723 snippets:
 pybun --format=json run --sandbox examples/hello.py
 pybun --format=json run --sandbox --allow-network -c "print('net ok')"
 ```
-The sandbox isolates file and network access; add `--allow-network` only when required. Combine with `--profile=prod` for production-like runs.
+Use repeatable `--allow-net=host[:port]` to permit selected network destinations
+and `--allow-run=executable-name-or-path` to permit trusted executables. For example:
+
+```bash
+pybun --format=json run --sandbox --allow-net=pypi.org:443 script.py
+pybun --format=json run --sandbox --allow-run=/usr/bin/git script.py
+```
+
+`--allow-network` retains unrestricted network access. Hostnames are resolved
+once at startup; permission includes those IP addresses (and hosts sharing them).
+Ports are exact when provided; omit the port to allow all ports for that host.
+Use brackets for IPv6, for example `[::1]:8080`. TCP and UDP sends, direct
+connects, and DNS lookups are checked. Denials identify the target with
+`E_SANDBOX_NET_DENIED` or `E_SANDBOX_RUN_DENIED` and a permission hint.
+MCP `sandbox_policy` supports matching `allow_net` and `allow_run` arrays.
+
+Executable names are resolved from the initial PATH and pinned to their real
+paths. Subprocess PATH/cwd overrides cannot authorize a different executable.
+Use explicit paths for direct exec/posix_spawn calls; raw fork and shell-command
+APIs remain denied. An allowed executable is trusted: it can launch children and
+access the host independently of Python guards. When `allow_run` is nonempty,
+the blanket zero-child OS process limit is not applied; `resource_limits.unsupported`
+reports `process`. Existing parent OS limits still apply.
+
+These are Python runtime guards plus supported resource limits, not a kernel
+containment boundary. Native extensions and trusted external programs require
+an OS/container sandbox when hostile code containment is needed. Combine with
+`--profile=prod` for production-like runs.
 
 ## Profiles
 
@@ -513,6 +556,121 @@ Requires `pip install pybun-cli`.
 ```
 *Note: If `pybun` is not in the PATH, provide the absolute path (e.g., `/Users/username/bin/pybun`).*
 
+### Server policy
+
+MCP execution requires an operator-owned security policy. Configure it before
+starting the server; requests cannot reload or override it. The server freezes
+one configuration at startup, with this precedence: `PYBUN_MCP_POLICY` file,
+then `.pybun/config.toml`, then `pyproject.toml`. A selected file with a missing
+or malformed policy fails closed; it does not fall back to another file.
+`pyproject.toml` and explicit files use `[tool.pybun.mcp.policy]`;
+`.pybun/config.toml` also accepts `[mcp.policy]`.
+
+For a restricted native execution server:
+
+```toml
+[tool.pybun.mcp.policy]
+default_sandbox = true
+require_sandbox = true
+allow_network = false
+max_execution_time_s = 30
+max_memory_mb = 0                 # Linux supports a nonzero memory cap
+max_cpu_time_s = 0
+allowed_working_directories = ["."]
+allowed_backends = ["native"]
+denied_tools = ["pybun_gc"]
+```
+
+Start it with `PYBUN_BACKEND=native pybun mcp serve --stdio`. Relative boundaries
+are resolved against the startup directory; start at the workspace root or
+explicitly authorize its ancestor workspace. Keep policy files under operator
+control, outside agent-writable paths for deployments. Audit logs must also be
+outside the effective writable project roots.
+
+Every tool and its resource aliases pass through authorization before audit
+setup, filesystem snapshots or execution. Responses expose `policy_applied` and
+stable `E_MCP_POLICY_*` denial codes. Requested limits may be stricter; zero
+(unlimited) cannot relax an operator cap. Required sandboxing and active caps
+prevent `unsafe_no_sandbox` from bypassing enforcement. Disallowed network
+permission also removes granular network and executable grants. Sandbox reads
+and writes default to the startup project boundary; explicit paths, symlinks,
+backend-derived workspaces and environment/lock outputs are checked against the
+operator's authorized directories. System-environment installation is denied.
+Write snapshots skip symlinks and generated trees (`target`, `.git`, `.venv`,
+`venv`, `__pycache__`, `node_modules`), and are bounded to 2,000 entries, depth
+32, 4 MiB per file and 16 MiB read per snapshot. Audit records expose
+`file_snapshot_complete=false` whenever evidence is skipped or bounded; their
+`file_writes` then describes only observed changes, not a complete write trace.
+Pure in-memory environment comparisons remain available without execution policy.
+
+Enforcement support is explicit: native inline code and ordinary scripts support
+these execution limits. Bounded uv preparation and native PEP 723 preparation
+cannot currently propagate all server limits, so incompatible calls return
+`E_MCP_POLICY_UNSUPPORTED` before preparation. Other tool handlers that cannot
+enforce a requested sandbox/network/resource restriction also return that code.
+Memory caps are unavailable on macOS/Windows; CPU caps require Unix. A dry run
+can preview a bounded uv call without starting the backend.
+
+Operators who authorize trusted uv project operations can set
+`require_sandbox=false`, `allow_network=true`, `max_execution_time_s=0`,
+`max_memory_mb=0`, and `max_cpu_time_s=0`; execution-time restrictions that a tool
+cannot enforce must be disabled explicitly. Its existing backend deadlines still
+apply. This does not grant requests permission to escape working-directory or
+backend boundaries. The Python guard's documented containment limits still apply.
+
+### Previewing execution
+
+Call `pybun_run` with `dry_run: true` to return `would_execute`,
+`estimated_risk` (`low`, `medium`, or `high`), `risk_reasons`, and
+`sandbox_policy_that_would_apply` without executing code or preparing a backend.
+The existing `risk_level` and `sandbox_policy` fields remain equivalent aliases.
+The response also includes server policy and admission limits; previews consume
+normal tool quota. Previewing an unsupported bounded backend reports
+`policy_applied.execution_supported=false` and its denial code.
+
+Risk is a substring heuristic over inline code or at most 2 MiB of regular UTF-8
+script source. Missing script targets are rejected. Non-text, oversized or unreadable source reports
+uncertainty as `medium`; filenames are not treated as source. If both are supplied,
+inline code takes precedence, matching execution. `low` is not proof of safety:
+dynamic imports, called code and later file changes can alter behavior. A preview
+does not grant execution permission; the actual call is authorized independently.
+
+### Tool rate limits
+
+The same frozen configuration accepts `[tool.pybun.mcp.rate_limit]` (or
+`[mcp.rate_limit]` in `.pybun/config.toml`):
+
+```toml
+[tool.pybun.mcp.rate_limit]
+calls_per_minute = 60             # all calls in one stdio session
+global_calls_per_minute = 600     # all sessions in this process/configuration
+pybun_run_per_minute = 10
+pybun_install_per_hour = 20
+
+[tool.pybun.mcp.rate_limit.per_tool.pybun_lock]
+calls = 5
+window_secs = 60
+```
+
+These are token buckets: each starts with a full window's burst and refills
+continuously using monotonic time. All applicable buckets are checked and debited
+atomically after policy authorization, before filesystem snapshots, backend work
+or subprocesses. Resource aliases share the corresponding tool's bucket. A denied
+call debits no bucket; cancelling an admitted call retains its debit. Rejections
+return `mcp.rate_limit_exceeded`, positive `retry_after_ms`, scope and applicable
+limits in `rate_limit_applied`, and write a security audit event without invoking
+the tool or producing its success receipt. Admitted responses expose their limits.
+
+One stdio server owns one generated session UUID for its lifetime; client IDs and
+arguments cannot change it. Global/per-tool quotas are shared by server instances
+in the same process with the same canonical startup directory and frozen rate
+configuration. Separate processes and restarts do not share quota state. State
+is bounded to 64 configurations and 512 sessions per configuration; live entries
+are never evicted to reset a quota. Idle sessions expire after two minutes and
+configurations after twice their longest tool window (at least two hours).
+Capacity exhaustion returns a retry hint. Configuration rejects unknown tool names
+and fields, zero or more than 1,000,000 calls, and windows outside 1–86,400 seconds.
+
 ## JSON output examples
 
 All commands support the `--format=json` option (schema v1). Examples:
@@ -686,3 +844,65 @@ Environment override: `PYBUN_TELEMETRY=0|1`
 ## License
 
 MIT
+
+### Local execution history
+
+`pybun history --since 20m --format=json` queries CLI receipts for `run`, `test`,
+`install`, `add`, and `remove`, including failed invocations. Receipts are appended
+under `PYBUN_HOME/history.jsonl` (default `~/.cache/pybun/history.jsonl`), with a
+private file mode on Unix and a file lock for concurrent writers. Existing files
+with group/other permissions are rejected for appends; restrict them to mode 600. Set
+`PYBUN_HISTORY=0` to disable recording. History queries never record themselves;
+recording failures warn without changing the command's exit code.
+
+Records contain timestamps, duration, exit code, lock digest when available,
+backend identity, Python version/ABI, and known cache/policy/profile evidence.
+Python observations identify whether they describe the execution interpreter or
+the selected environment observed after the command; unavailable evidence is
+`null`. Daemon use is false for the current direct execution paths. Inline code
+and credential option values are removed, and the existing output redaction rules
+apply before persistence and on reads. Program output and environment variables
+are never stored. Arbitrary positional secrets cannot be inferred; disable
+history when arguments contain such values. Queries accept positive `s`, `m`,
+`h`, or `d` durations, report corrupt/partial lines without echoing them, and
+reject files over 32 MiB; archive the local log when needed.
+
+### Comparing captured environments
+
+`pybun why <package> --format=json` explains every known declaration path to a
+locked distribution. MCP `pybun_why` takes a `package` string and uses the same
+service. The uv backend reads frozen, offline `uv workspace metadata`; it does
+not resolve, install, or synchronize an environment. Paths retain markers and
+classify direct, transitive, extra, dependency-group, and workspace provenance.
+They describe lock alternatives rather than the currently active environment.
+Results include backend/version, lock digest, `complete`, and diagnostics. An
+unreachable or unavailable locked variant is explicitly `unknown`. Native
+provenance uses current declarations with its lock and always reports partial
+evidence. Traversal is bounded (10,000 nodes, 100,000 expansions, depth 256,
+1,000 paths); reaching a bound also reports partial evidence.
+
+`pybun environment diff before.json after.json --format=json` compares two JSON
+captures, raw execution receipts, or JSON command envelopes. The MCP equivalent is
+`pybun_environment_diff` with `before` and `after` objects; both use the same
+read-only service. To compare CLI history entries, save the chosen `records[]`
+objects from `pybun history --format=json` as the input files. Each input file is
+limited to 4 MiB.
+
+The response reports deterministic `changes` with reason codes for Python,
+backend, lock, package, policy, profile and project evidence. `installed_packages`
+describes interpreter-site inventory; `packages` separately describes a backend's
+resolved lock inventory, which does not prove installation. History captures
+standard isolated-venv site packages by reading distribution metadata without
+importing project packages or running site hooks. System Python and venvs that
+include system/user sites leave the installed inventory unavailable. Executable
+digests are captured when readable; wheel artifact hashes remain unavailable
+unless supplied by a capture.
+
+Missing, masked and explicitly unknown values appear in `unavailable` and warning
+diagnostics. They do not establish equality or a runtime state change. An identical
+partial capture has an empty `changes` array while still reporting missing evidence.
+Array ordering and normalized package spelling do not create differences. Only
+typed, allowlisted metadata is compared; unrestricted environment variables and
+unknown configuration keys are excluded, and existing redaction applies before
+comparison. `causality: "not_inferred"` means the result describes recorded state
+changes and never claims that they caused a program's output to change.

{pybun_cli-0.2.0 → pybun_cli-0.2.1}/README.md

@@ -251,6 +251,18 @@ pybun x cowsay==6.1
 pybun x black -- --check .
 ```
 
+### Affected Tests
+
+```bash
+pybun test --affected
+pybun test --affected --since main --format=json
+pybun test --affected --discover --format=json
+```
+
+`--changed` is an alias for `--affected`. Selection is repository-wide and cannot be combined with explicit paths or `--member`. MCP `pybun_test` uses the same service with `{"changed": true, "since": "main"}`.
+
+JSON includes `selection` with `direct`, `transitive`, or `conservative` reasons and import chains. The target Python's standard AST parser reads project source without executing it. Imports and ancestor `conftest.py` dependencies are modeled; uncertain parsing, known dynamic imports, or non-Python/configuration changes conservatively select all tests. Import-root ambiguity may select extra tests. Arbitrary runtime file dependencies are not inferred. Unavailable git/runtime evidence returns an error rather than a verified empty selection.
+
 ### Python Version Management
 
 ```bash
@@ -348,6 +360,8 @@ pybun audit --severity-threshold=medium
 pybun audit --fail-on=high
 ```
 
+The scanner follows OSV batch pagination and fetches advisory details before filtering or suggesting fixes. Missing severity is reported as `unknown`, remains visible at every threshold, and fails any `--fail-on` gate. Failed advisory lookups fail the scan. `PYBUN_OSV_URL` can point to a mirror's batch endpoint; its sibling `vulns/<id>` endpoint must serve full advisories.
+
 ### Profile Management
 
 ```bash
@@ -418,6 +432,8 @@ pybun self update --dry-run
 pybun self update --channel nightly
 ```
 
+MCP exposes the same doctor remediation plan: call `pybun_doctor` with `{"fix": true}` to preview, or `{"fix": true, "apply": true}` to apply low-risk, auto-applicable fixes. `applied_fixes` includes before/after cache counts; `skipped_fixes` explains candidates requiring manual action. The existing `pybun_fix` tool continues to fix lint violations with Ruff.
+
 ## Sandbox usage
 
 Use the sandbox for untrusted scripts or PEP 723 snippets:
@@ -425,7 +441,34 @@ Use the sandbox for untrusted scripts or PEP 723 snippets:
 pybun --format=json run --sandbox examples/hello.py
 pybun --format=json run --sandbox --allow-network -c "print('net ok')"
 ```
-The sandbox isolates file and network access; add `--allow-network` only when required. Combine with `--profile=prod` for production-like runs.
+Use repeatable `--allow-net=host[:port]` to permit selected network destinations
+and `--allow-run=executable-name-or-path` to permit trusted executables. For example:
+
+```bash
+pybun --format=json run --sandbox --allow-net=pypi.org:443 script.py
+pybun --format=json run --sandbox --allow-run=/usr/bin/git script.py
+```
+
+`--allow-network` retains unrestricted network access. Hostnames are resolved
+once at startup; permission includes those IP addresses (and hosts sharing them).
+Ports are exact when provided; omit the port to allow all ports for that host.
+Use brackets for IPv6, for example `[::1]:8080`. TCP and UDP sends, direct
+connects, and DNS lookups are checked. Denials identify the target with
+`E_SANDBOX_NET_DENIED` or `E_SANDBOX_RUN_DENIED` and a permission hint.
+MCP `sandbox_policy` supports matching `allow_net` and `allow_run` arrays.
+
+Executable names are resolved from the initial PATH and pinned to their real
+paths. Subprocess PATH/cwd overrides cannot authorize a different executable.
+Use explicit paths for direct exec/posix_spawn calls; raw fork and shell-command
+APIs remain denied. An allowed executable is trusted: it can launch children and
+access the host independently of Python guards. When `allow_run` is nonempty,
+the blanket zero-child OS process limit is not applied; `resource_limits.unsupported`
+reports `process`. Existing parent OS limits still apply.
+
+These are Python runtime guards plus supported resource limits, not a kernel
+containment boundary. Native extensions and trusted external programs require
+an OS/container sandbox when hostile code containment is needed. Combine with
+`--profile=prod` for production-like runs.
 
 ## Profiles
 
@@ -493,6 +536,121 @@ Requires `pip install pybun-cli`.
 ```
 *Note: If `pybun` is not in the PATH, provide the absolute path (e.g., `/Users/username/bin/pybun`).*
 
+### Server policy
+
+MCP execution requires an operator-owned security policy. Configure it before
+starting the server; requests cannot reload or override it. The server freezes
+one configuration at startup, with this precedence: `PYBUN_MCP_POLICY` file,
+then `.pybun/config.toml`, then `pyproject.toml`. A selected file with a missing
+or malformed policy fails closed; it does not fall back to another file.
+`pyproject.toml` and explicit files use `[tool.pybun.mcp.policy]`;
+`.pybun/config.toml` also accepts `[mcp.policy]`.
+
+For a restricted native execution server:
+
+```toml
+[tool.pybun.mcp.policy]
+default_sandbox = true
+require_sandbox = true
+allow_network = false
+max_execution_time_s = 30
+max_memory_mb = 0                 # Linux supports a nonzero memory cap
+max_cpu_time_s = 0
+allowed_working_directories = ["."]
+allowed_backends = ["native"]
+denied_tools = ["pybun_gc"]
+```
+
+Start it with `PYBUN_BACKEND=native pybun mcp serve --stdio`. Relative boundaries
+are resolved against the startup directory; start at the workspace root or
+explicitly authorize its ancestor workspace. Keep policy files under operator
+control, outside agent-writable paths for deployments. Audit logs must also be
+outside the effective writable project roots.
+
+Every tool and its resource aliases pass through authorization before audit
+setup, filesystem snapshots or execution. Responses expose `policy_applied` and
+stable `E_MCP_POLICY_*` denial codes. Requested limits may be stricter; zero
+(unlimited) cannot relax an operator cap. Required sandboxing and active caps
+prevent `unsafe_no_sandbox` from bypassing enforcement. Disallowed network
+permission also removes granular network and executable grants. Sandbox reads
+and writes default to the startup project boundary; explicit paths, symlinks,
+backend-derived workspaces and environment/lock outputs are checked against the
+operator's authorized directories. System-environment installation is denied.
+Write snapshots skip symlinks and generated trees (`target`, `.git`, `.venv`,
+`venv`, `__pycache__`, `node_modules`), and are bounded to 2,000 entries, depth
+32, 4 MiB per file and 16 MiB read per snapshot. Audit records expose
+`file_snapshot_complete=false` whenever evidence is skipped or bounded; their
+`file_writes` then describes only observed changes, not a complete write trace.
+Pure in-memory environment comparisons remain available without execution policy.
+
+Enforcement support is explicit: native inline code and ordinary scripts support
+these execution limits. Bounded uv preparation and native PEP 723 preparation
+cannot currently propagate all server limits, so incompatible calls return
+`E_MCP_POLICY_UNSUPPORTED` before preparation. Other tool handlers that cannot
+enforce a requested sandbox/network/resource restriction also return that code.
+Memory caps are unavailable on macOS/Windows; CPU caps require Unix. A dry run
+can preview a bounded uv call without starting the backend.
+
+Operators who authorize trusted uv project operations can set
+`require_sandbox=false`, `allow_network=true`, `max_execution_time_s=0`,
+`max_memory_mb=0`, and `max_cpu_time_s=0`; execution-time restrictions that a tool
+cannot enforce must be disabled explicitly. Its existing backend deadlines still
+apply. This does not grant requests permission to escape working-directory or
+backend boundaries. The Python guard's documented containment limits still apply.
+
+### Previewing execution
+
+Call `pybun_run` with `dry_run: true` to return `would_execute`,
+`estimated_risk` (`low`, `medium`, or `high`), `risk_reasons`, and
+`sandbox_policy_that_would_apply` without executing code or preparing a backend.
+The existing `risk_level` and `sandbox_policy` fields remain equivalent aliases.
+The response also includes server policy and admission limits; previews consume
+normal tool quota. Previewing an unsupported bounded backend reports
+`policy_applied.execution_supported=false` and its denial code.
+
+Risk is a substring heuristic over inline code or at most 2 MiB of regular UTF-8
+script source. Missing script targets are rejected. Non-text, oversized or unreadable source reports
+uncertainty as `medium`; filenames are not treated as source. If both are supplied,
+inline code takes precedence, matching execution. `low` is not proof of safety:
+dynamic imports, called code and later file changes can alter behavior. A preview
+does not grant execution permission; the actual call is authorized independently.
+
+### Tool rate limits
+
+The same frozen configuration accepts `[tool.pybun.mcp.rate_limit]` (or
+`[mcp.rate_limit]` in `.pybun/config.toml`):
+
+```toml
+[tool.pybun.mcp.rate_limit]
+calls_per_minute = 60             # all calls in one stdio session
+global_calls_per_minute = 600     # all sessions in this process/configuration
+pybun_run_per_minute = 10
+pybun_install_per_hour = 20
+
+[tool.pybun.mcp.rate_limit.per_tool.pybun_lock]
+calls = 5
+window_secs = 60
+```
+
+These are token buckets: each starts with a full window's burst and refills
+continuously using monotonic time. All applicable buckets are checked and debited
+atomically after policy authorization, before filesystem snapshots, backend work
+or subprocesses. Resource aliases share the corresponding tool's bucket. A denied
+call debits no bucket; cancelling an admitted call retains its debit. Rejections
+return `mcp.rate_limit_exceeded`, positive `retry_after_ms`, scope and applicable
+limits in `rate_limit_applied`, and write a security audit event without invoking
+the tool or producing its success receipt. Admitted responses expose their limits.
+
+One stdio server owns one generated session UUID for its lifetime; client IDs and
+arguments cannot change it. Global/per-tool quotas are shared by server instances
+in the same process with the same canonical startup directory and frozen rate
+configuration. Separate processes and restarts do not share quota state. State
+is bounded to 64 configurations and 512 sessions per configuration; live entries
+are never evicted to reset a quota. Idle sessions expire after two minutes and
+configurations after twice their longest tool window (at least two hours).
+Capacity exhaustion returns a retry hint. Configuration rejects unknown tool names
+and fields, zero or more than 1,000,000 calls, and windows outside 1–86,400 seconds.
+
 ## JSON output examples
 
 All commands support the `--format=json` option (schema v1). Examples:
@@ -666,3 +824,65 @@ Environment override: `PYBUN_TELEMETRY=0|1`
 ## License
 
 MIT
+
+### Local execution history
+
+`pybun history --since 20m --format=json` queries CLI receipts for `run`, `test`,
+`install`, `add`, and `remove`, including failed invocations. Receipts are appended
+under `PYBUN_HOME/history.jsonl` (default `~/.cache/pybun/history.jsonl`), with a
+private file mode on Unix and a file lock for concurrent writers. Existing files
+with group/other permissions are rejected for appends; restrict them to mode 600. Set
+`PYBUN_HISTORY=0` to disable recording. History queries never record themselves;
+recording failures warn without changing the command's exit code.
+
+Records contain timestamps, duration, exit code, lock digest when available,
+backend identity, Python version/ABI, and known cache/policy/profile evidence.
+Python observations identify whether they describe the execution interpreter or
+the selected environment observed after the command; unavailable evidence is
+`null`. Daemon use is false for the current direct execution paths. Inline code
+and credential option values are removed, and the existing output redaction rules
+apply before persistence and on reads. Program output and environment variables
+are never stored. Arbitrary positional secrets cannot be inferred; disable
+history when arguments contain such values. Queries accept positive `s`, `m`,
+`h`, or `d` durations, report corrupt/partial lines without echoing them, and
+reject files over 32 MiB; archive the local log when needed.
+
+### Comparing captured environments
+
+`pybun why <package> --format=json` explains every known declaration path to a
+locked distribution. MCP `pybun_why` takes a `package` string and uses the same
+service. The uv backend reads frozen, offline `uv workspace metadata`; it does
+not resolve, install, or synchronize an environment. Paths retain markers and
+classify direct, transitive, extra, dependency-group, and workspace provenance.
+They describe lock alternatives rather than the currently active environment.
+Results include backend/version, lock digest, `complete`, and diagnostics. An
+unreachable or unavailable locked variant is explicitly `unknown`. Native
+provenance uses current declarations with its lock and always reports partial
+evidence. Traversal is bounded (10,000 nodes, 100,000 expansions, depth 256,
+1,000 paths); reaching a bound also reports partial evidence.
+
+`pybun environment diff before.json after.json --format=json` compares two JSON
+captures, raw execution receipts, or JSON command envelopes. The MCP equivalent is
+`pybun_environment_diff` with `before` and `after` objects; both use the same
+read-only service. To compare CLI history entries, save the chosen `records[]`
+objects from `pybun history --format=json` as the input files. Each input file is
+limited to 4 MiB.
+
+The response reports deterministic `changes` with reason codes for Python,
+backend, lock, package, policy, profile and project evidence. `installed_packages`
+describes interpreter-site inventory; `packages` separately describes a backend's
+resolved lock inventory, which does not prove installation. History captures
+standard isolated-venv site packages by reading distribution metadata without
+importing project packages or running site hooks. System Python and venvs that
+include system/user sites leave the installed inventory unavailable. Executable
+digests are captured when readable; wheel artifact hashes remain unavailable
+unless supplied by a capture.
+
+Missing, masked and explicitly unknown values appear in `unavailable` and warning
+diagnostics. They do not establish equality or a runtime state change. An identical
+partial capture has an empty `changes` array while still reporting missing evidence.
+Array ordering and normalized package spelling do not create differences. Only
+typed, allowlisted metadata is compared; unrestricted environment variables and
+unknown configuration keys are excluded, and existing redaction applies before
+comparison. `causality: "not_inferred"` means the result describes recorded state
+changes and never claims that they caused a program's output to change.

{pybun_cli-0.2.0 → pybun_cli-0.2.1/pybun_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybun-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: PyBun shim bootstrapper for signed releases
 Author: PyBun Authors
 License-Expression: MIT
@@ -271,6 +271,18 @@ pybun x cowsay==6.1
 pybun x black -- --check .
 ```
 
+### Affected Tests
+
+```bash
+pybun test --affected
+pybun test --affected --since main --format=json
+pybun test --affected --discover --format=json
+```
+
+`--changed` is an alias for `--affected`. Selection is repository-wide and cannot be combined with explicit paths or `--member`. MCP `pybun_test` uses the same service with `{"changed": true, "since": "main"}`.
+
+JSON includes `selection` with `direct`, `transitive`, or `conservative` reasons and import chains. The target Python's standard AST parser reads project source without executing it. Imports and ancestor `conftest.py` dependencies are modeled; uncertain parsing, known dynamic imports, or non-Python/configuration changes conservatively select all tests. Import-root ambiguity may select extra tests. Arbitrary runtime file dependencies are not inferred. Unavailable git/runtime evidence returns an error rather than a verified empty selection.
+
 ### Python Version Management
 
 ```bash
@@ -368,6 +380,8 @@ pybun audit --severity-threshold=medium
 pybun audit --fail-on=high
 ```
 
+The scanner follows OSV batch pagination and fetches advisory details before filtering or suggesting fixes. Missing severity is reported as `unknown`, remains visible at every threshold, and fails any `--fail-on` gate. Failed advisory lookups fail the scan. `PYBUN_OSV_URL` can point to a mirror's batch endpoint; its sibling `vulns/<id>` endpoint must serve full advisories.
+
 ### Profile Management
 
 ```bash
@@ -438,6 +452,8 @@ pybun self update --dry-run
 pybun self update --channel nightly
 ```
 
+MCP exposes the same doctor remediation plan: call `pybun_doctor` with `{"fix": true}` to preview, or `{"fix": true, "apply": true}` to apply low-risk, auto-applicable fixes. `applied_fixes` includes before/after cache counts; `skipped_fixes` explains candidates requiring manual action. The existing `pybun_fix` tool continues to fix lint violations with Ruff.
+
 ## Sandbox usage
 
 Use the sandbox for untrusted scripts or PEP 723 snippets:
@@ -445,7 +461,34 @@ Use the sandbox for untrusted scripts or PEP 723 snippets:
 pybun --format=json run --sandbox examples/hello.py
 pybun --format=json run --sandbox --allow-network -c "print('net ok')"
 ```
-The sandbox isolates file and network access; add `--allow-network` only when required. Combine with `--profile=prod` for production-like runs.
+Use repeatable `--allow-net=host[:port]` to permit selected network destinations
+and `--allow-run=executable-name-or-path` to permit trusted executables. For example:
+
+```bash
+pybun --format=json run --sandbox --allow-net=pypi.org:443 script.py
+pybun --format=json run --sandbox --allow-run=/usr/bin/git script.py
+```
+
+`--allow-network` retains unrestricted network access. Hostnames are resolved
+once at startup; permission includes those IP addresses (and hosts sharing them).
+Ports are exact when provided; omit the port to allow all ports for that host.
+Use brackets for IPv6, for example `[::1]:8080`. TCP and UDP sends, direct
+connects, and DNS lookups are checked. Denials identify the target with
+`E_SANDBOX_NET_DENIED` or `E_SANDBOX_RUN_DENIED` and a permission hint.
+MCP `sandbox_policy` supports matching `allow_net` and `allow_run` arrays.
+
+Executable names are resolved from the initial PATH and pinned to their real
+paths. Subprocess PATH/cwd overrides cannot authorize a different executable.
+Use explicit paths for direct exec/posix_spawn calls; raw fork and shell-command
+APIs remain denied. An allowed executable is trusted: it can launch children and
+access the host independently of Python guards. When `allow_run` is nonempty,
+the blanket zero-child OS process limit is not applied; `resource_limits.unsupported`
+reports `process`. Existing parent OS limits still apply.
+
+These are Python runtime guards plus supported resource limits, not a kernel
+containment boundary. Native extensions and trusted external programs require
+an OS/container sandbox when hostile code containment is needed. Combine with
+`--profile=prod` for production-like runs.
 
 ## Profiles
 
@@ -513,6 +556,121 @@ Requires `pip install pybun-cli`.
 ```
 *Note: If `pybun` is not in the PATH, provide the absolute path (e.g., `/Users/username/bin/pybun`).*
 
+### Server policy
+
+MCP execution requires an operator-owned security policy. Configure it before
+starting the server; requests cannot reload or override it. The server freezes
+one configuration at startup, with this precedence: `PYBUN_MCP_POLICY` file,
+then `.pybun/config.toml`, then `pyproject.toml`. A selected file with a missing
+or malformed policy fails closed; it does not fall back to another file.
+`pyproject.toml` and explicit files use `[tool.pybun.mcp.policy]`;
+`.pybun/config.toml` also accepts `[mcp.policy]`.
+
+For a restricted native execution server:
+
+```toml
+[tool.pybun.mcp.policy]
+default_sandbox = true
+require_sandbox = true
+allow_network = false
+max_execution_time_s = 30
+max_memory_mb = 0                 # Linux supports a nonzero memory cap
+max_cpu_time_s = 0
+allowed_working_directories = ["."]
+allowed_backends = ["native"]
+denied_tools = ["pybun_gc"]
+```
+
+Start it with `PYBUN_BACKEND=native pybun mcp serve --stdio`. Relative boundaries
+are resolved against the startup directory; start at the workspace root or
+explicitly authorize its ancestor workspace. Keep policy files under operator
+control, outside agent-writable paths for deployments. Audit logs must also be
+outside the effective writable project roots.
+
+Every tool and its resource aliases pass through authorization before audit
+setup, filesystem snapshots or execution. Responses expose `policy_applied` and
+stable `E_MCP_POLICY_*` denial codes. Requested limits may be stricter; zero
+(unlimited) cannot relax an operator cap. Required sandboxing and active caps
+prevent `unsafe_no_sandbox` from bypassing enforcement. Disallowed network
+permission also removes granular network and executable grants. Sandbox reads
+and writes default to the startup project boundary; explicit paths, symlinks,
+backend-derived workspaces and environment/lock outputs are checked against the
+operator's authorized directories. System-environment installation is denied.
+Write snapshots skip symlinks and generated trees (`target`, `.git`, `.venv`,
+`venv`, `__pycache__`, `node_modules`), and are bounded to 2,000 entries, depth
+32, 4 MiB per file and 16 MiB read per snapshot. Audit records expose
+`file_snapshot_complete=false` whenever evidence is skipped or bounded; their
+`file_writes` then describes only observed changes, not a complete write trace.
+Pure in-memory environment comparisons remain available without execution policy.
+
+Enforcement support is explicit: native inline code and ordinary scripts support
+these execution limits. Bounded uv preparation and native PEP 723 preparation
+cannot currently propagate all server limits, so incompatible calls return
+`E_MCP_POLICY_UNSUPPORTED` before preparation. Other tool handlers that cannot
+enforce a requested sandbox/network/resource restriction also return that code.
+Memory caps are unavailable on macOS/Windows; CPU caps require Unix. A dry run
+can preview a bounded uv call without starting the backend.
+
+Operators who authorize trusted uv project operations can set
+`require_sandbox=false`, `allow_network=true`, `max_execution_time_s=0`,
+`max_memory_mb=0`, and `max_cpu_time_s=0`; execution-time restrictions that a tool
+cannot enforce must be disabled explicitly. Its existing backend deadlines still
+apply. This does not grant requests permission to escape working-directory or
+backend boundaries. The Python guard's documented containment limits still apply.
+
+### Previewing execution
+
+Call `pybun_run` with `dry_run: true` to return `would_execute`,
+`estimated_risk` (`low`, `medium`, or `high`), `risk_reasons`, and
+`sandbox_policy_that_would_apply` without executing code or preparing a backend.
+The existing `risk_level` and `sandbox_policy` fields remain equivalent aliases.
+The response also includes server policy and admission limits; previews consume
+normal tool quota. Previewing an unsupported bounded backend reports
+`policy_applied.execution_supported=false` and its denial code.
+
+Risk is a substring heuristic over inline code or at most 2 MiB of regular UTF-8
+script source. Missing script targets are rejected. Non-text, oversized or unreadable source reports
+uncertainty as `medium`; filenames are not treated as source. If both are supplied,
+inline code takes precedence, matching execution. `low` is not proof of safety:
+dynamic imports, called code and later file changes can alter behavior. A preview
+does not grant execution permission; the actual call is authorized independently.
+
+### Tool rate limits
+
+The same frozen configuration accepts `[tool.pybun.mcp.rate_limit]` (or
+`[mcp.rate_limit]` in `.pybun/config.toml`):
+
+```toml
+[tool.pybun.mcp.rate_limit]
+calls_per_minute = 60             # all calls in one stdio session
+global_calls_per_minute = 600     # all sessions in this process/configuration
+pybun_run_per_minute = 10
+pybun_install_per_hour = 20
+
+[tool.pybun.mcp.rate_limit.per_tool.pybun_lock]
+calls = 5
+window_secs = 60
+```
+
+These are token buckets: each starts with a full window's burst and refills
+continuously using monotonic time. All applicable buckets are checked and debited
+atomically after policy authorization, before filesystem snapshots, backend work
+or subprocesses. Resource aliases share the corresponding tool's bucket. A denied
+call debits no bucket; cancelling an admitted call retains its debit. Rejections
+return `mcp.rate_limit_exceeded`, positive `retry_after_ms`, scope and applicable
+limits in `rate_limit_applied`, and write a security audit event without invoking
+the tool or producing its success receipt. Admitted responses expose their limits.
+
+One stdio server owns one generated session UUID for its lifetime; client IDs and
+arguments cannot change it. Global/per-tool quotas are shared by server instances
+in the same process with the same canonical startup directory and frozen rate
+configuration. Separate processes and restarts do not share quota state. State
+is bounded to 64 configurations and 512 sessions per configuration; live entries
+are never evicted to reset a quota. Idle sessions expire after two minutes and
+configurations after twice their longest tool window (at least two hours).
+Capacity exhaustion returns a retry hint. Configuration rejects unknown tool names
+and fields, zero or more than 1,000,000 calls, and windows outside 1–86,400 seconds.
+
 ## JSON output examples
 
 All commands support the `--format=json` option (schema v1). Examples:
@@ -686,3 +844,65 @@ Environment override: `PYBUN_TELEMETRY=0|1`
 ## License
 
 MIT
+
+### Local execution history
+
+`pybun history --since 20m --format=json` queries CLI receipts for `run`, `test`,
+`install`, `add`, and `remove`, including failed invocations. Receipts are appended
+under `PYBUN_HOME/history.jsonl` (default `~/.cache/pybun/history.jsonl`), with a
+private file mode on Unix and a file lock for concurrent writers. Existing files
+with group/other permissions are rejected for appends; restrict them to mode 600. Set
+`PYBUN_HISTORY=0` to disable recording. History queries never record themselves;
+recording failures warn without changing the command's exit code.
+
+Records contain timestamps, duration, exit code, lock digest when available,
+backend identity, Python version/ABI, and known cache/policy/profile evidence.
+Python observations identify whether they describe the execution interpreter or
+the selected environment observed after the command; unavailable evidence is
+`null`. Daemon use is false for the current direct execution paths. Inline code
+and credential option values are removed, and the existing output redaction rules
+apply before persistence and on reads. Program output and environment variables
+are never stored. Arbitrary positional secrets cannot be inferred; disable
+history when arguments contain such values. Queries accept positive `s`, `m`,
+`h`, or `d` durations, report corrupt/partial lines without echoing them, and
+reject files over 32 MiB; archive the local log when needed.
+
+### Comparing captured environments
+
+`pybun why <package> --format=json` explains every known declaration path to a
+locked distribution. MCP `pybun_why` takes a `package` string and uses the same
+service. The uv backend reads frozen, offline `uv workspace metadata`; it does
+not resolve, install, or synchronize an environment. Paths retain markers and
+classify direct, transitive, extra, dependency-group, and workspace provenance.
+They describe lock alternatives rather than the currently active environment.
+Results include backend/version, lock digest, `complete`, and diagnostics. An
+unreachable or unavailable locked variant is explicitly `unknown`. Native
+provenance uses current declarations with its lock and always reports partial
+evidence. Traversal is bounded (10,000 nodes, 100,000 expansions, depth 256,
+1,000 paths); reaching a bound also reports partial evidence.
+
+`pybun environment diff before.json after.json --format=json` compares two JSON
+captures, raw execution receipts, or JSON command envelopes. The MCP equivalent is
+`pybun_environment_diff` with `before` and `after` objects; both use the same
+read-only service. To compare CLI history entries, save the chosen `records[]`
+objects from `pybun history --format=json` as the input files. Each input file is
+limited to 4 MiB.
+
+The response reports deterministic `changes` with reason codes for Python,
+backend, lock, package, policy, profile and project evidence. `installed_packages`
+describes interpreter-site inventory; `packages` separately describes a backend's
+resolved lock inventory, which does not prove installation. History captures
+standard isolated-venv site packages by reading distribution metadata without
+importing project packages or running site hooks. System Python and venvs that
+include system/user sites leave the installed inventory unavailable. Executable
+digests are captured when readable; wheel artifact hashes remain unavailable
+unless supplied by a capture.
+
+Missing, masked and explicitly unknown values appear in `unavailable` and warning
+diagnostics. They do not establish equality or a runtime state change. An identical
+partial capture has an empty `changes` array while still reporting missing evidence.
+Array ordering and normalized package spelling do not create differences. Only
+typed, allowlisted metadata is compared; unrestricted environment variables and
+unknown configuration keys are excluded, and existing redaction applies before
+comparison. `causality: "not_inferred"` means the result describes recorded state
+changes and never claims that they caused a program's output to change.

{pybun_cli-0.2.0 → pybun_cli-0.2.1}/pyproject.toml

@@ -22,7 +22,7 @@ readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.8"
 license = "MIT"
 license-files = ["LICENSE"]
-version = "0.2.0"
+version = "0.2.1"
 
 [[project.authors]]
 name = "PyBun Authors"