fuzzprep 0.1.0__py3-none-any.whl

fuzzprep/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

fuzzprep/__main__.py

@@ -0,0 +1,4 @@
+from fuzzprep.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fuzzprep/agents/harness_builder/SKILL.md

@@ -0,0 +1,156 @@
+You are helping debug and fix a failed harness compilation/link probe for a C/C++ library.
+
+Your goal: make compile_harness.sh succeed so that a supplied harness compiles and links
+against the library's static artifacts, producing a binary in out/.
+
+## What you have
+
+The failure context will be appended below. It includes:
+- The install directory containing static libraries (install/lib/*.a) and headers (install/include/)
+- The work directory containing compile_harness.sh and harness_source/
+- The static libraries already discovered
+- Any link flags already auto-resolved from known symbol patterns
+- Any missing system libraries already reported by the linker
+- The complete stderr from the failed compile/link attempt (last 200 lines)
+
+workdir is not a scratch directory — it is the real project directory that generation
+copies its final output from (for oss-fuzz, it's the same directory that becomes the
+shipped project). Edits you make here to compile_harness.sh, a Dockerfile, or other
+files persist into that output.
+
+## Reproducibility
+
+The verification command — and every future rebuild of this project, on any machine,
+months from now — only ever sees the files saved in workdir plus a fresh `git clone` of
+the library's source. Two rules follow from that:
+
+- **Persist every fix to disk, and only to disk.** Nothing outside what's saved in
+  `compile_harness.sh` (or a Dockerfile/patch file it invokes) survives to the next
+  run — not a command typed directly in this shell, not an exported env var, not a
+  file edited by hand outside what the script itself does. The script must succeed
+  standalone against a fresh `install/`, with no leftover state from this or any prior
+  session. If a fix needs an env var, a package, or a symlink, encode it into
+  compile_harness.sh (or the Dockerfile) so a fresh checkout reproduces it identically.
+- **Hand-edits to the source tree do not persist.** Both the local `setup.sh` and the
+  shipped oss-fuzz `Dockerfile` re-clone the library from git at build time — the copy
+  of the source sitting in workdir right now is discarded the moment you exit. If a fix
+  genuinely requires changing a source file (e.g. a missing header the harness needs),
+  encode that change as a step compile_harness.sh performs itself — e.g. a `sed -i`
+  invocation, or `patch < "$SCRIPT_DIR/some.patch"` where the patch file lives next to
+  compile_harness.sh — not a one-off edit to the file in the source directory.
+
+Also: use the script's own `$SCRIPT_DIR`/`$BUILD_PREFIX`/`$INSTALL_DIR` variables
+(already defined near the top of compile_harness.sh) instead of baking in this
+session's actual filesystem paths (e.g. `/home/user/.fuzzprep/...`) — those paths
+won't exist on a different machine or in a fresh container.
+
+## What to do
+
+1. Read compile_harness.sh in the work directory to understand the link command that was
+   attempted (STATIC_LIBS array, EXTRA_LINK_FLAGS, compiler invocation).
+2. Read the linker/compiler errors in the failure context to identify unresolved symbols
+   or missing libraries.
+3. Diagnose the failure:
+   - Undefined symbols usually mean a transitive dependency's `-lXXX` flag is missing from
+     EXTRA_LINK_FLAGS, or static library link order matters for this linker.
+   - "library not found" / "cannot find -lXXX" errors mean a system library isn't
+     installed on this machine.
+4. Decide how to fix it, based on whether the library is resolvable on this machine:
+   - **If adding a `-lXXX` flag lets the build compile and link successfully right now**
+     (the library is already present on this machine, or an alternative like a static
+     archive already in install/lib, or a different link order resolves it): make the
+     fix yourself — edit EXTRA_LINK_FLAGS, include paths, or static library link order
+   directly in compile_harness.sh — and verify it. Still report the flag in
+     `missing_libs`/`missing_apt_packages` in `agent_report.json` (see below), even though
+     it already worked here — FuzzPrep needs the package name recorded for portability
+     to environments that don't already have it.
+   - **If the library isn't resolvable on this machine at all** (nothing to link
+     against; installing a system package is unavoidable): do not edit
+   EXTRA_LINK_FLAGS yourself, since you cannot verify a fix you cannot compile.
+     Instead, identify the bare library name and report it via `missing_libs` (see
+     below), determine the actual apt package name (see `agent_report.json` fields), and
+     say in your own reply text:
+     "ACTION REQUIRED: Missing system packages detected. Please review agent_report.json
+      and install the listed packages, then re-run this agent."
+     Write that line yourself — not through `echo` or any other command, and not only
+     inside a file. The caller reads the marker from your response text only.
+     Write `agent_report.json`, and do not proceed further.
+5. Once you've made a fix, run the verification command given in the failure context below
+   (not compile_harness.sh directly) to confirm it now succeeds in the selected target
+   environment and a binary appears in out/.
+
+## `agent_report.json`
+
+Before exiting — on **every** outcome, success or stop-for-human-action — write
+`agent_report.json` to the work directory (the directory containing compile_harness.sh)
+with this shape:
+
+```json
+{
+  "summary": "libfoo.a alone is missing zlib symbols; linked against the system zlib at /usr/lib/x86_64-linux-gnu instead of requesting a new package.",
+  "missing_libs": [],
+  "missing_apt_packages": [],
+  "extra_include_paths": ["./src"],
+  "extra_library_paths": ["./src/build"]
+}
+```
+
+- `summary` (string): plain-language description of what you diagnosed/did. Always
+  include this, on both success and failure. If uncertain of an exact package name,
+  say so here rather than asserting it confidently.
+- `missing_libs` (array of strings): bare library name(s) — the part after `-l` — for
+  every new `-lXXX` flag you added to EXTRA_LINK_FLAGS, whether or not installing a
+  package was needed to make it work. Empty array if you added no new flags.
+- `missing_apt_packages` (array of strings): Debian/Ubuntu `apt-get install` package
+  names that provide the libraries above (e.g. `"libldap2-dev"` for `-lldap`), reported
+  alongside every entry in `missing_libs` — including ones already present on this
+  machine, for portability to environments that aren't. Every name here reaches the
+  generated `setup.sh` and Dockerfile, so this is how the package gets installed wherever
+  the output is used.
+- `extra_include_paths` (array of strings): relative paths, outside `install/include`,
+  that you added to the harness compile command's `-I` search path to make the fix work.
+  Empty array if none.
+- `extra_library_paths` (array of strings): relative paths, outside `install/lib`, that
+  you added to the harness link command's `-L` search path to make the fix work (e.g. a
+  system library location). Empty array if none.
+
+Omit fields you have nothing to report for — they default to empty/absent on the
+reading side.
+
+## Stopping conditions
+
+You cannot signal an outcome through your process exit code — the runner invokes you via
+`claude --print`, which exits 0 whenever the CLI itself ran, no matter how you decided to
+stop. The `ACTION REQUIRED` line and `agent_report.json` are the only signals the caller
+reads, so a stop that needs human action is detected *only* if you write that exact
+marker.
+
+The caller scans your response text for the marker — not the command output or file
+contents in your transcript. So the marker counts only when *you* write it, and quoting
+it while explaining something (including quoting this document) does not accidentally
+signal a stop.
+
+**Success** — the verification command exits 0. Write `agent_report.json` first, then
+give a short success summary.
+
+**Blocked on human action** (a library that must be installed) — write the exact
+`ACTION REQUIRED:` line from step 4 and write `agent_report.json` with the package names.
+
+**Unresolvable failure** — if the verification command still fails after your fix
+attempt, or if you cannot determine a fix, stop immediately. Write `agent_report.json`
+first, then report:
+- What you diagnosed as the root cause
+- What fix(es) you attempted (if any)
+- The exact error from the build output
+
+Do not retry indefinitely or attempt speculative fixes beyond what the evidence supports.
+The caller detects this case by checking `out/` for a linked binary itself, so no marker is
+needed — but put the diagnosis in `summary` so it reaches the failure report.
+
+## Important: non-interactive execution
+
+This agent may be run non-interactively (e.g. via `claude --print`). In that
+mode there is no user to respond to mid-run prompts. Never pause to ask the
+user a question. If human input is required (e.g. to install packages), put all
+necessary context in your reply, write any helper scripts to disk, and write the
+`ACTION REQUIRED` marker yourself so the caller can detect and surface the situation.

fuzzprep/agents/library_builder/SKILL.md

@@ -0,0 +1,147 @@
+You are helping debug and fix a failed C/C++ static library build.
+
+Your goal: make the build_library.sh script succeed so that:
+- static libraries (*.a) are installed to install/lib/
+- headers are installed to install/include/
+
+## What you have
+
+The build failure context will be appended below. It includes:
+- The source directory path
+- The detected build system
+- The build command that was run
+- The complete stdout/stderr from the failed build
+- The expected install directory paths
+
+workdir (the directory build_library.sh lives in) is not a scratch directory — it is the
+real project directory that generation copies its final output from (for oss-fuzz, it's
+the same directory that becomes the shipped project). Edits you make here to
+build_library.sh, a Dockerfile, or other files persist into that output.
+
+## Reproducibility
+
+The verification command — and every future rebuild of this project, on any machine,
+months from now — only ever sees the files saved in workdir plus a fresh `git clone` of
+the library's source. Two rules follow from that:
+
+- **Persist every fix to disk, and only to disk.** Nothing outside what's saved in
+  `build_library.sh` (or a Dockerfile/patch file it invokes) survives to the next run —
+  not a command typed directly in this shell, not an exported env var, not a file
+  edited by hand outside what the script itself does. The script must succeed
+  standalone against a freshly cloned source tree, with no leftover state from this or
+  any prior attempt (a partially-built `build/` directory, a file created by hand). If
+  a fix needs an env var, a package, or a symlink, encode it into build_library.sh (or
+  the Dockerfile) so a fresh checkout reproduces it identically.
+- **Hand-edits to the source tree do not persist.** Both the local `setup.sh` and the
+  shipped oss-fuzz `Dockerfile` re-clone the library from git at build time — the copy
+  of the source sitting in workdir right now is discarded the moment you exit. If a fix
+  genuinely requires changing a source file (a broken CMakeLists.txt, a workaround for a
+  compiler-version bug in a `.c` file), encode that change as a step build_library.sh
+  performs itself — e.g. a `sed -i` invocation, or `patch < "$SCRIPT_DIR/some.patch"`
+  where the patch file lives next to build_library.sh — not a one-off edit to the file
+  in the source directory.
+
+Also: use the script's own `$SCRIPT_DIR`/`$BUILD_PREFIX`/`$INSTALL_DIR` variables
+(already defined near the top of build_library.sh) instead of baking in this session's
+actual filesystem paths (e.g. `/home/user/.fuzzprep/...`) — those paths won't exist
+on a different machine or in a fresh container.
+
+## What to do
+
+1. Read build_library.sh in the work directory to understand what was attempted.
+2. Read the relevant build files (CMakeLists.txt, Makefile, configure.ac, meson.build, etc.).
+3. Diagnose the failure from the build output.
+4. Fix the problem: modify build_library.sh or other build files as needed.
+   Common fixes: wrong static library flags, configure options, disabling optional features.
+5. If missing system packages are the root cause, first try to disable the feature that
+   requires them via build flags (e.g. -DWITH_SSL=OFF, --disable-ssl, -Doption=disabled).
+   Prefer this over requesting package installation — optional features are not needed for
+   the core static library. Only escalate to package installation if the missing dependency
+   is critical to the library's core functionality (not just for optional functionality).
+6. If a required package cannot be avoided:
+   - Determine the actual installable Debian/Ubuntu (`apt-get`) package name from your own
+     knowledge. It is frequently different from the library name itself — e.g. OpenLDAP is
+     `libldap2-dev`. If uncertain of the exact package name, say so in `summary` rather
+     than asserting it confidently. Do not install anything yourself.
+   - Say clearly, in your own reply text, what is needed:
+     "ACTION REQUIRED: Missing system packages detected. Please review agent_report.json
+      and install the listed packages, then re-run this agent."
+     Write that line yourself — not through `echo` or any other command, and not only
+     inside a file. The caller reads the marker from your response text only.
+   - Write `agent_report.json` (see below), listing the package names, before exiting.
+   - Do not proceed further.
+7. Once any required packages are installed, run the verification command given in the
+   failure context below (not build_library.sh directly) to confirm the fix works in the
+   selected target environment. It is the authoritative check — it also compiles a stub
+   harness against your install/ output — so trust its exit code over eyeballing
+   install/lib and install/include yourself.
+
+## `agent_report.json`
+
+Before exiting — on **every** outcome, success or stop-for-human-action — write
+`agent_report.json` to the work directory (the directory containing build_library.sh,
+**not** the source directory) with this shape:
+
+```json
+{
+  "summary": "Disabled optional SSL support via -DWITH_SSL=OFF; libssl-dev was unavailable.",
+  "missing_apt_packages": ["libssl-dev", "libz-dev"],
+  "extra_include_paths": ["./src/"],
+  "extra_library_paths": ["./src/build"]
+}
+```
+
+- `summary` (string): plain-language description of what you diagnosed/did. Always
+  include this, on both success and failure.
+- `missing_apt_packages` (array of strings): Debian/Ubuntu `apt-get install` package
+  names still needed (e.g. `"libssl-dev"`). Empty array if none. Correctness is of
+  utmost importance — do not list a package unless you are sure it exists. Every name here
+  reaches the generated `setup.sh` and Dockerfile, so this is how a package you needed gets
+  installed wherever the output is used.
+- `extra_include_paths` (array of strings): relative paths, outside `install/include`,
+  that a downstream harness-compilation step should add to its `-I` search path if you
+  discovered the build needs one. Empty array if none.
+- `extra_library_paths` (array of strings): relative paths, outside `install/lib`, that
+  a downstream harness-compilation step should add to its `-L` search path if you
+  discovered the build needs one. Empty array if none.
+
+Omit fields you have nothing to report for a given field — they default to empty/absent
+on the reading side. This is the only machine-readable report file you should write.
+
+## Stopping conditions
+
+You cannot signal an outcome through your process exit code — the runner invokes you via
+`claude --print`, which exits 0 whenever the CLI itself ran, no matter how you decided to
+stop. The `ACTION REQUIRED` line and `agent_report.json` are the only signals the caller
+reads, so a stop that needs human action is detected *only* if you write that exact
+marker.
+
+The caller scans your response text for the marker — not the command output or file
+contents in your transcript. So the marker counts only when *you* write it, and quoting
+it while explaining something (including quoting this document) does not accidentally
+signal a stop.
+
+**Success** — the verification command exits 0. Write `agent_report.json` first, then
+give a short success summary.
+
+**Blocked on human action** (a package that must be installed) — write the exact
+`ACTION REQUIRED:` line from step 6 and write `agent_report.json` with the package names.
+
+**Unresolvable failure** — if the verification command still fails after your fix
+attempt, or if you cannot determine a fix, stop immediately. Write `agent_report.json`
+first, then report:
+- What you diagnosed as the root cause
+- What fix(es) you attempted (if any)
+- The exact error from the build output
+
+Do not retry indefinitely or attempt speculative fixes beyond what the evidence supports.
+The caller detects this case by checking `install/lib` and `install/include` itself, so no
+marker is needed — but put the diagnosis in `summary` so it reaches the failure report.
+
+## Important: non-interactive execution
+
+This agent may be run non-interactively (e.g. via `claude --print`). In that
+mode there is no user to respond to mid-run prompts. Never pause to ask the
+user a question. If human input is required (e.g. to install packages), put all
+necessary context in your reply, write any helper scripts to disk, and write the
+`ACTION REQUIRED` marker yourself so the caller can detect and surface the situation.

fuzzprep/agents/scripts/check_build.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# The single definition of "the build passed", for every environment.
+#
+# Runs the project's own build.sh (build_library.sh then compile_harnesses.sh) from nothing and
+# asserts the artifacts that make the output worth shipping. The pipeline and every repair agent
+# invoke this same script, so a fix an agent verifies is a fix the pipeline accepts.
+#
+# --keep-artifacts keeps install/ and build/, which skips the library rebuild. See the comment
+# on the deletion below for who is allowed to pass it.
+#
+# Two fallbacks let one script text run unchanged on the host and in the OSS-Fuzz container:
+# $OUT falls back to <workspace>/out, and the build is entered through `compile` wherever that
+# exists and through build.sh otherwise.
+set -euo pipefail
+
+if [[ $# -lt 1 || $# -gt 2 ]]; then
+  echo "Usage: $0 <workspace> [--keep-artifacts]" >&2
+  exit 1
+fi
+
+workspace=$1
+keep_artifacts=0
+if [[ $# -eq 2 ]]; then
+  if [[ $2 != "--keep-artifacts" ]]; then
+    echo "Unknown option: $2 (expected --keep-artifacts)" >&2
+    exit 1
+  fi
+  keep_artifacts=1
+fi
+
+cd "$workspace"
+
+OUT="${OUT:-$PWD/out}"
+export OUT
+
+# Deleting install/ and build/ is what makes this a from-scratch check. --keep-artifacts drops
+# that, leaving build_library.sh's own skip-if-already-built guard to short-circuit the library
+# build. Only a caller that already built the library from nothing may pass it -- the pipeline
+# does so on the lane where explore() just did exactly that. A repair agent never passes it,
+# because its whole job is changing the build, so its fix has to survive a real cold build.
+if [[ $keep_artifacts -eq 0 ]]; then
+  rm -rf install build
+fi
+# $OUT is emptied rather than removed: check_build_in_container.sh bind-mounts the host's out/
+# there, and a mountpoint cannot be unlinked from inside the container ("Device or resource
+# busy"), which under set -e would fail the gate before the build even started.
+#
+# Emptied even under --keep-artifacts: compile_harnesses.sh always runs, so the $OUT assertion
+# below stays a real check on this invocation rather than on a leftover binary.
+mkdir -p "$OUT"
+find "$OUT" -mindepth 1 -delete
+
+# `compile` runs build.sh, but only after assembling what the base image half-provides:
+# SANITIZER_FLAGS resolved into CFLAGS/CXXFLAGS, and LIB_FUZZING_ENGINE=-fsanitize=fuzzer in
+# place of the deprecated archive path its ENV names. Running build.sh directly in that image
+# links against an archive that does not exist yet, and working that around yields an
+# uninstrumented target. A host has no `compile` and nothing to assemble.
+build_command=(bash build.sh)
+if command -v compile > /dev/null 2>&1; then
+  build_command=(compile)
+fi
+
+echo "=== build.sh ==="
+if command -v bear > /dev/null 2>&1; then
+  # Captures compile_commands.json for Make/Autotools, which have no build-system equivalent.
+  # Harmless for the others, which emit their own.
+  bear -- "${build_command[@]}"
+else
+  "${build_command[@]}"
+fi
+
+if ! compgen -G "install/lib/*.a" > /dev/null; then
+  echo "FAILED: no static libraries (*.a) found in install/lib" >&2
+  exit 1
+fi
+
+if [[ ! -d install/include ]] || [[ -z "$(ls -A install/include)" ]]; then
+  echo "FAILED: install/include is missing or empty" >&2
+  exit 1
+fi
+
+if [[ ! -d "$OUT" ]] || [[ -z "$(ls -A "$OUT")" ]]; then
+  echo "FAILED: $OUT is missing or empty — no harness binary was produced" >&2
+  exit 1
+fi
+
+echo "OK: build.sh succeeded and install/ plus $OUT are populated"

fuzzprep/agents/scripts/check_build_in_container.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Run check_build.sh inside the workspace's own OSS-Fuzz image.
+#
+# Rebuilds the image from the workspace Dockerfile first, so an edit to it takes effect;
+# Docker's layer cache makes that cheap when nothing changed. The workspace is then
+# bind-mounted at /src, the path OSS-Fuzz tooling expects, so install/ and
+# compile_commands.json land on the host for the next stage to use. The harness binaries need
+# a mount of their own, since they go to the image's own $OUT=/out, outside /src — so
+# <workspace>/out is bound there too, as OSS-Fuzz's helper.py does. Without it they would be
+# discarded with the container, and a repair that linked something would look like one that
+# only said so.
+#
+# This decides only where the gate runs. The assertions live in check_build.sh alone.
+set -euo pipefail
+
+if [[ $# -lt 2 || $# -gt 3 ]]; then
+  echo "Usage: $0 <workspace> <project_name> [--keep-artifacts]" >&2
+  exit 1
+fi
+
+workspace=$1
+project_name=$2
+# Passed straight through to check_build.sh inside the container, which validates it.
+check_build_options=("${@:3}")
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+tag="fuzzprep-dev/${project_name}:latest"
+
+cd "$workspace"
+
+if ! docker build -t "$tag" .; then
+  echo "FAILED: docker build failed for $workspace" >&2
+  exit 1
+fi
+
+# Created before the mount so it belongs to the invoking user; Docker would otherwise create
+# it root-owned, which the chown below cannot reach from the host side.
+mkdir -p out
+
+mounts=(
+  -v "$PWD:/src"
+  -v "$PWD/out:/out"
+  -v "$script_dir/check_build.sh:/usr/local/bin/check_build.sh:ro"
+)
+
+# The workspace mount covers /src whole, shadowing the source tree the image cloned there, so
+# the container reads <workspace>/src from the host. An oss-fuzz run over a local path leaves
+# that a symlink out of the workspace, which dangles in the container unless its target is
+# mounted too — at its own path, which is what the symlink resolves to.
+if [[ -L src ]]; then
+  source_target="$(readlink -f src)"
+  if [[ -n $source_target ]]; then
+    mounts+=(-v "$source_target:$source_target")
+  fi
+fi
+
+status=0
+docker run --rm "${mounts[@]}" -w /src --entrypoint bash \
+  "$tag" /usr/local/bin/check_build.sh /src "${check_build_options[@]}" || status=$?
+
+# The container runs as root, so install/, build/, and out/ come back root-owned and the next
+# run cannot delete them. -h stops at the symlink above rather than following it into the
+# source tree, which belongs to the user. /out is named explicitly rather than left to
+# the walk of /src: it is the same host directory as /src/out, but naming it does not depend
+# on chown descending into a nested bind mount.
+docker run --rm "${mounts[@]}" --entrypoint chown \
+  "$tag" -Rh "$(id -u):$(id -g)" /src /out > /dev/null 2>&1 || true
+
+if [[ $status -ne 0 ]]; then
+  echo "FAILED: check_build.sh did not succeed inside the container" >&2
+  exit 1
+fi
+
+echo "OK: check_build.sh succeeded inside the container"

fuzzprep/agents/scripts/check_dockerfile_from_scratch.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Prove the shipped Dockerfile builds and compiles with nothing mounted.
+#
+# The gate (check_build_in_container.sh) mounts the workspace, which is what makes the artifacts
+# reachable — but a mounted run can pass while the Dockerfile's own clone or apt layers are
+# broken, since the mount supplies what the image failed to. This runs the real thing:
+# `docker build`, then `compile`, no mounts, then a check for a harness binary in /out.
+#
+# Runs once, as the last step before generation, for an oss-fuzz target.
+set -euo pipefail
+
+if [[ $# -ne 2 ]]; then
+  echo "Usage: $0 <project_dir> <project_name>" >&2
+  exit 1
+fi
+
+project_dir=$1
+project_name=$2
+tag="${project_name}:fuzzprep-from-scratch"
+
+cd "$project_dir"
+
+if ! docker build -t "$tag" .; then
+  echo "FAILED: docker build failed for $project_dir" >&2
+  exit 1
+fi
+
+if ! docker run --rm --entrypoint bash "$tag" -c 'compile && test -n "$(ls -A /out)"'; then
+  echo "FAILED: compile (build.sh) or the /out check failed inside the container" >&2
+  exit 1
+fi
+
+echo "OK: from-scratch docker build and in-container compile succeeded"