veyra-proof 0.3.0__tar.gz

veyra_proof-0.3.0/.cursor/skills/veyra-proof/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: veyra-proof
+description: >-
+  Audits a Rust Cargo workspace by actually running the real toolchain (fmt,
+  clippy, test, llvm-cov, cargo-deny, cargo-geiger, machete, semver-checks,
+  miri, cargo-fuzz, kani, mutants) plus anti-theater heuristics, then writes
+  reproducible evidence. Use when the user asks to audit, scan, or check a
+  Rust/Cargo workspace, run veyra doctor/plan/audit, wire it into a repo, or
+  wants a CI-grade pass/fail verdict. Reports MISSING or SKIPPED instead of a
+  green checkmark it cannot justify.
+---
+
+# Veyra Proof
+
+Evidence-based auditor for local Rust Cargo workspaces. Results come only from tools that actually ran.
+
+This folder is the **canonical copy**. It follows the open `SKILL.md` standard, so the same file works in Cursor, Claude Code, Codex, Antigravity, Freebuff, OpenCode, Copilot, and Windsurf. Maintainers: see the repository README for the fan-out command.
+
+<!-- HARD_RULES_START -->
+## Hard rules
+
+The block between `HARD_RULES_START` and `HARD_RULES_END` is frozen. No automated mutation — skill optimizer, `mcp_mutate_skill`, self-revision, or linter — may edit, reorder, reword, or drop anything inside it. Only a human may change it, deliberately, in a reviewable diff.
+
+- Never invent tool output, pass/fail, versions, or evidence.
+- Never `curl | sh`, never arbitrary download installers, never disable lints or tests to pass.
+- Never mutate `Cargo.toml` (V1 has no automatic manifest edits).
+- Never run `cargo update` unless the user explicitly asked for `--update-lockfile`.
+- `--install-missing` only when the user confirmed installs **or** passed `--yes`.
+- If Cargo or rustup is missing, stop and report; do not install Rust toolchains via scripts.
+- Quote real exit codes and paths from the run; say SKIPPED or MISSING when that is what happened.
+- Never report a tool as OK when it was not run, not installed, or timed out.
+<!-- HARD_RULES_END -->
+
+## Resolve the CLI (`VEYRA`)
+
+Pick the first that works:
+
+1. `veyra` on PATH — check with `command -v veyra`
+2. Env `VEYRA_PROOF_BIN` — absolute path to the binary
+3. Env `VEYRA_PROOF_HOME` — then `"$VEYRA_PROOF_HOME/.venv/bin/python" -m veyra_proof` (Windows: `.venv\Scripts\python`)
+4. A clone in the current repo — `.venv/bin/python -m veyra_proof` (Windows: `.venv\Scripts\python`), after confirming `.venv` exists
+5. `python3 -m veyra_proof` if the package is importable
+
+Set the shell variable `VEYRA` to the winning invocation. Examples: `VEYRA="veyra"`, `VEYRA=".venv/bin/python -m veyra_proof"`.
+
+Never hardcode a machine-specific absolute path. If none of the five resolve, ask the user for the clone path or binary, then export one of the two env vars.
+
+**Done when:** `$VEYRA --version` prints a version, or the install branch is required.
+
+## Branch: install
+
+When the user wants Veyra available (any project, this machine):
+
+1. If resolution already works, run `$VEYRA doctor` and stop. Print cargo and rustc status honestly.
+2. Otherwise ask once for the source: **editable clone path** or **existing PyInstaller binary**.
+3. Editable install (preferred for agents):
+   ```bash
+   cd "$CLONE" && python3 -m venv .venv
+   .venv/bin/pip install -e .
+   export VEYRA_PROOF_HOME="$CLONE"
+   ```
+4. Binary: copy or symlink `veyra` onto PATH, or set `VEYRA_PROOF_BIN`.
+5. Re-resolve `VEYRA`, run `$VEYRA doctor`. If cargo is missing, give guidance only — no rustup bootstrap scripts.
+
+**Done when:** `$VEYRA doctor` returns JSON and cargo is OK, or you reported the exact blocker.
+
+## Branch: audit
+
+Target is a path containing `Cargo.toml` (workspace or package). Default profile is `standard` unless the user asked for `quick` or `hardened`.
+
+1. Resolve `VEYRA` (use the install branch if missing).
+2. `$VEYRA plan "$TARGET" --profile <profile>`
+3. If the plan shows pending installs:
+   - The user already said yes, or `--yes` was passed — add `--install-missing --yes`, plus `--verbose` and a higher `--timeout` when installs will compile.
+   - Otherwise list the pending tools and **ask** before installing.
+4. Run:
+   ```bash
+   $VEYRA audit "$TARGET" --profile <profile> [flags]
+   ```
+5. Report from real output only: the decision, the exit code, and the evidence dir under `$TARGET/.veyra/evidence/<UTC>/` (or wherever `--evidence-dir` pointed).
+6. If the project declares `[[e2e.scenarios]]` in `veyra.toml`, `veyra-e2e` builds the workspace and drives the produced binary through each declared journey. Report what each scenario observed — exit code and printed output, from its log — not only the tool's status. No declared scenarios means SKIPPED: say the behavior was not verified instead of implying it was.
+7. Say `INCONCLUSIVE` in words. It covers a stale lockfile, a nightly-only target and a timeout — each one means a check did not complete. Never describe an accepted run as "clean" without naming what was skipped, inconclusive or informational; the anti-theater log opens with a rule histogram of everything it noticed.
+
+**Done when:** the audit finished (or dry-run / plan-only if that is what was asked) and the user sees the real verdict plus the evidence path.
+
+Useful flags, profiles, and exit codes live in [reference.md](reference.md).
+
+## Branch: wire
+
+Lightweight project wiring, with no `Cargo.toml` edits:
+
+1. Confirm the target is a Cargo root.
+2. Only if the user asked for config, write a minimal `veyra.toml`. Do not invent fuzz targets, CodeQL databases, or mutants paths.
+3. Optionally add a short note to the project README: how to run `$VEYRA doctor` and `$VEYRA audit . --profile quick`.
+4. Do **not** auto-commit. Do **not** add CI secrets or remote download steps.
+
+Minimal optional `veyra.toml` skeleton — edit only what the user wants:
+
+```toml
+[project]
+critical_paths = []
+
+[policy]
+# leave defaults unless the user specifies policy knobs
+```
+
+**Done when:** the requested files exist and the commands to run are stated, with no "wired and passing" claim that no audit run supports.
+
+## Honesty checklist
+
+- [ ] Every claimed status came from a real command
+- [ ] Missing tools are reported as MISSING or SKIPPED, never OK
+- [ ] Installs happened only with confirmation or `--yes`
+- [ ] The evidence path is cited whenever an audit ran
+- [ ] No "verified end to end" claim without a scenario that observed it

veyra_proof-0.3.0/.cursor/skills/veyra-proof/reference.md

@@ -0,0 +1,103 @@
+# Veyra reference
+
+## Profiles
+
+| Profile | Intent |
+|---------|--------|
+| `quick` | rustfmt, cargo-check, clippy `-D warnings`, cargo-test, audit, veyra-anti-theater, veyra-e2e (if scenarios declared) |
+| `standard` | quick + nextest, llvm-cov, deny, geiger, machete, dylint (if configured), semver-checks (libs) |
+| `hardened` | standard + miri, mutants (configured paths), fuzz (configured targets), kani, vet, check-external-types, reproducible-build |
+
+Heavy tools SKIP with an explicit reason when config/targets are missing.
+
+`reproducible-build` runs two clean builds and compares the final artifacts; it is
+the most expensive check in `hardened` and `--exclude reproducible-build` turns it
+off. Differing hashes are `INCONCLUSIVE` with both digests, never a pass, and are
+informational unless `policy.require_reproducible_build = true`.
+
+Every tool records its own duration: `report.json` has a `timing` block and
+`report.md` a `## Time` table with per-tool seconds, the total and the wall clock.
+Quote it when someone asks why an audit took minutes — on a real crate the cost is
+usually its own test suite. Veyra neither caches builds across runs nor skips checks
+to go faster.
+
+## Verdicts that are not passes
+
+| Situation | Verdict |
+|-----------|---------|
+| `Cargo.lock` out of date with `Cargo.toml` | `INCONCLUSIVE` — cargo runs with `--locked`, and Veyra will not rewrite the lockfile |
+| Manifest declares dependencies, no lockfile | `SKIPPED` + `unlocked-dependencies` — dependency safety is unknown |
+| A target needs nightly (`#![feature]`) | `INCONCLUSIVE`, naming the files not verified; lib/bins/tests are still checked |
+| Scenario timed out, tool timed out | `INCONCLUSIVE` |
+
+## Heuristic policy (`veyra.toml` `[policy]`)
+
+`todo!()` / `unimplemented!()` in a production path are blockers. Everything else is
+reported and only blocks when asked for: `fail_on_ignored_tests`, `fail_on_panic`,
+`fail_on_lint_allow`, `fail_on_weak_oracles`, `fail_on_cfg_tricks`, `deny_unsafe`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Required checks completed without blocking findings |
+| 1 | Problems / findings / rejection |
+| 2 | Missing prerequisites, unauthorized install, or required tools not executable |
+| 3 | Internal application error |
+
+## End-to-end behavior (`veyra-e2e`)
+
+Builds the workspace with the real toolchain and runs the binary cargo produced through the journeys declared in `veyra.toml`, comparing exit code, stdout, stderr and written files with what was declared. It only proves what the scenarios cover.
+
+```toml
+[e2e]
+build_profile = "release"     # or "debug"
+features = []                 # feature flags of the shipped configuration
+no_default_features = false
+binaries = []                 # defaults to the workspace's first built bin target
+timeout_seconds = 60
+
+[[e2e.scenarios]]
+name = "add sums two integers"
+argv = ["add", "1", "2"]
+expect_exit = 0
+expect_stdout_regex = '^3\r?\n?$'
+# stdin = ""
+# expect_stderr_regex = 'division by zero'
+# expect_files = ["out/report.txt"]
+# expect_failure = true       # any non-zero exit; set expect_exit for an exact one
+```
+
+| Outcome | Meaning |
+|---------|---------|
+| `OK` | every scenario observed what it declared |
+| `FINDINGS` | `E2E00` vacuous scenario, `E2E01` exit mismatch, `E2E02` output/file mismatch, `E2ECFG` invalid configuration, `E2E03` informational reachability note |
+| `INCONCLUSIVE` | the build or a scenario timed out, or the workspace builds no binary |
+| `SKIPPED` | no scenarios declared: behavior was **not** verified |
+| `ERROR` | `cargo build` failed; nothing was executed |
+
+Required in every profile exactly when scenarios are declared (and available to `--include`). `E2E03` never blocks a verdict.
+
+## Evidence
+
+Default: `PATH/.veyra/evidence/<UTC_TIMESTAMP>/` with `report.md`, `report.json`, `manifest.json`, per-tool logs, hashes.
+
+Every log a tool writes — `stdout.log`, `stderr.log`, and `skip.txt` when a tool skips after running — is pinned by its sha256 in that tool's `artifact_hashes`, so the report states what its own evidence held. `scripts/ci_assert_evidence.py` recomputes those digests and fails a report whose log changed after the run, was deleted, or is not pinned at all for an `OK` verdict.
+
+## Safety defaults
+
+| Action | Default |
+|--------|---------|
+| Modify `Cargo.toml` | Forbidden |
+| Rewrite `Cargo.lock` during a run | Forbidden — cargo runs with `--locked` |
+| `cargo update` | Needs `--update-lockfile` |
+| Install tools | Needs `--install-missing` + confirm or `--yes` |
+| `curl \| sh` | Never |
+
+`--fail-on none` accepts the run whatever it found; the findings stay in `report.json`.
+It is the only value that disables rejection, and it cannot excuse an unauthorized
+project file change.
+
+## Packaging note
+
+PyInstaller binaries are OS/arch-specific. Build on the target host; unsigned macOS binaries may need Gatekeeper “Open anyway.”

veyra_proof-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: py${{ matrix.python }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      # One command per step: `&&` is not portable across the default shells
+      # of ubuntu, macos and windows runners.
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Tests
+        run: python -m pytest
+
+      - name: The console script is on PATH
+        run: veyra --version
+
+  audit:
+    name: live audit of the demo crate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      # `quick` makes cargo-audit required as soon as the target has a lockfile,
+      # and the runner images do not ship it. Without the binary the auditor
+      # exits 2 (missing prerequisites), which is not a verdict and fails here.
+      - name: Install cargo-audit
+        run: cargo install cargo-audit --locked
+
+      - name: Report the toolchain this run will use
+        run: |
+          cargo --version
+          rustc --version
+
+      # Unit tests mock subprocess, so they cannot catch a broken tool
+      # invocation. This runs the real thing: real cargo, real exit codes,
+      # and then a check that the evidence on disk matches the claim.
+      - name: Run the auditor and verify its evidence
+        run: python scripts/ci_assert_evidence.py tests/fixtures/demo_crate

veyra_proof-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish to PyPI
+
+# Publishing uses PyPI trusted publishing (OIDC): the `id-token: write`
+# permission below is what replaces an API token. Nothing secret lives in this
+# repository, and nothing needs rotating.
+#
+# One-time setup on PyPI, for the project `veyra-proof`:
+#   https://pypi.org/manage/account/publishing/ -> add a pending publisher
+#     owner:  ExyonQ
+#     repo:   Veyra-Proof
+#     workflow: publish.yml
+# The `pypi` environment referenced below must also exist on the repository.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Describe what will be published
+        run: ls -l dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

veyra_proof-0.3.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Antonio Cantallops Alba
+Contact: contact@exyonq.org
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

veyra_proof-0.3.0/MANIFEST.in

@@ -0,0 +1,28 @@
+# The published sdist should describe the whole product, not just the importable
+# package. Half of what this project ships is the agent skill, and the other
+# half is the tooling that keeps it honest.
+#
+# `.cursor` is listed file by file on purpose. A wildcard there would sweep up
+# editor and agent state that happens to sit in the working copy — brain
+# databases, hook scripts, local rule files — and none of that belongs on PyPI.
+
+include LICENSE
+include README.md
+include SECURITY.md
+include requirements-dev.txt
+include veyra-proof.spec
+include MANIFEST.in
+
+include .cursor/skills/veyra-proof/SKILL.md
+include .cursor/skills/veyra-proof/reference.md
+include Veyra/skills/veyra-proof/SKILL.md
+include Veyra/skills/veyra-proof/reference.md
+
+recursive-include scripts *.py
+recursive-include Veyra *.md *.py *.toml LICENSE
+recursive-include tests *.py *.json *.toml *.lock *.rs
+recursive-include .github *.yml
+
+global-exclude __pycache__/* *.py[cod] .DS_Store
+prune tests/fixtures/demo_crate/target
+prune tests/fixtures/demo_crate/.veyra