pre-push(17.6): install, Docker wrapper and first-run docs

`ousast pre-push install|uninstall [REPO] [--force] [--docker]` ships in the
wheel with the hook as package data; it honours core.hooksPath, refuses an
existing hook unless --force (which chains it as pre-push.before-ousast), and
uninstall restores the chained hook. ops/ousast-docker is a hook-callable
script: the repository read-only and the artifact directory at their own
paths, stdin passed through, no network, --memory 3g, the GHCR 2.0.1 image by
default, advisory exit unless blocking. Help text for every pre-push flag; a
first-run guide, settings, skip-reason glossary, CI recipe and full --help in
docs/scanning.md; README tiers 1 and 2 pull the published image. The image
was not rebuilt: 1.1 GB free, below the 4 GB threshold. Requirements 7.4, 9.6.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

ops/README.md

@@ -291,13 +291,20 @@ The default capability registry is empty pending independent qualification. Inst
 this interface does not make the project rollout-ready. Advisory is the default;
 blocking and strict incomplete-coverage handling are separate explicit choices.
 
-Put the installed `ousast` executable on the Git process's PATH. From this tool's
-checkout, explicitly install into the desired repository:
+The supported install is `ousast pre-push install [REPO] [--force] [--docker]`, shipped in
+the wheel; `ousast pre-push uninstall [REPO]` removes it. The first-run guide, settings, skip
+reasons and a CI recipe are in [Scanning](../scanning.md#first-run-install-the-hook-on-any-repository).
+If `ousast` is not on the Git process's PATH, the hook prints one line and lets the push through.
+From this tool's checkout, the script installer remains available:
 
 ```sh
 ops/install-pre-push /absolute/path/to/repository
 ```
 
+`ops/ousast-docker` is the hook-callable Docker wrapper (`OUSAST_COMMAND=/path/to/ops/ousast-docker`,
+or installed beside the hook by `--docker`). It is a script, not a shell function, so Git can run
+it. It passes the push input through and mounts the artifact directory at its own path.
+
 The installer resolves Git's effective hook directory (including `core.hooksPath`),
 leaves that configuration untouched, and refuses to overwrite any existing hook.
 For an existing hook, inspect it and explicitly move it aside **before** installation:

ops/ousast-docker

@@ -0,0 +1,61 @@
+#!/bin/sh
+# OpenUltraSAST in Docker, callable from a Git hook. A script, not a shell function: Git runs
+# hooks non-interactively and never sees functions from ~/.bashrc.
+#
+#   OUSAST_COMMAND=/path/to/ousast-docker git push      # or: ousast pre-push install --docker
+#
+# The repository is mounted READ-ONLY at its own absolute path and the artifact directory
+# read-write at its own path, so every path in the arguments and in the output ("Details: ...")
+# means the same thing inside and outside the container. The push input on stdin is passed
+# through (-i). The container runs as your user, with no network and --memory 3g.
+#
+# Advisory like the hook: when Docker or the image is missing, it says the check did not run
+# and exits 0. Pull the image once first; a hook never downloads ~3 GB on its own:
+#
+#   docker pull ghcr.io/norandom/openultrasast:2.0.1
+#
+# --engine background does not work through this wrapper: the container ends with the hook.
+image=${OUSAST_IMAGE:-ghcr.io/norandom/openultrasast:2.0.1}
+if ! command -v docker >/dev/null 2>&1; then
+    echo "ousast-docker: check did not run: docker is not installed. Push continues."
+    exit 0
+fi
+if ! docker image inspect "$image" >/dev/null 2>&1; then
+    echo "ousast-docker: check did not run: image $image is not present." \
+        "Run 'docker pull $image' once. Push continues."
+    exit 0
+fi
+repo=$(pwd -P)
+artifact_dir=${OUSAST_ARTIFACT_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/openultrasast/push}
+previous=
+for argument in "$@"; do
+    if [ "$previous" = "--artifact" ]; then
+        artifact_dir=$(dirname -- "$argument")
+    fi
+    previous=$argument
+done
+mkdir -p -- "$artifact_dir" || exit 0
+artifact_dir=$(cd -- "$artifact_dir" && pwd -P)
+# A linked worktree keeps its objects in the main repository's git directory: mount that too.
+common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null || echo "$repo/.git")
+case "$common" in
+    "$repo"/*) extra_mount= ;;
+    *) extra_mount="-v $common:$common:ro" ;;
+esac
+# shellcheck disable=SC2086 # OUSAST_DOCKER_ARGS and extra_mount are deliberately word-split
+docker run --rm -i --network none --memory "${OUSAST_DOCKER_MEMORY:-3g}" \
+    --user "$(id -u):$(id -g)" -e HOME=/tmp -e TMPDIR=/work --tmpfs /work:size=4g \
+    -v "$repo:$repo:ro" -w "$repo" -v "$artifact_dir:$artifact_dir" $extra_mount \
+    ${OUSAST_DOCKER_ARGS:-} "$image" "$@"
+status=$?
+if [ "$status" -ge 125 ]; then
+    echo "ousast-docker: check did not run: the container could not start (docker exit $status). Push continues."
+    exit 0
+fi
+# Only an explicit blocking opt-in may turn the container's exit into a rejected push; an older
+# image that rejects a newer argument must not block either.
+if [ "$status" -ne 0 ] && [ "${OUSAST_PUSH_MODE:-advisory}" != blocking ]; then
+    echo "ousast-docker: the check exited with status $status; push continues (advisory)."
+    exit 0
+fi
+exit "$status"

ops/pre-push

@@ -5,6 +5,11 @@
 # A prior hook is chained only after it was moved to the sibling path "$0.before-ousast".
 artifact_dir=${OUSAST_ARTIFACT_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/openultrasast/push}
 prior="$0.before-ousast"
+# The Docker wrapper installed beside this hook (`ousast pre-push install --docker`) is used
+# unless OUSAST_COMMAND names another command; otherwise `ousast` from PATH.
+if [ -z "${OUSAST_COMMAND:-}" ] && [ -x "$(dirname -- "$0")/ousast-docker" ]; then
+    OUSAST_COMMAND="$(dirname -- "$0")/ousast-docker"
+fi
 command=${OUSAST_COMMAND:-ousast}
 if ! command -v "$command" >/dev/null 2>&1; then
     echo "ousast: pre-push check did not run: '$command' is not on PATH." \
@@ -19,8 +24,11 @@ remote_url=$2
 set -- pre-push . --artifact "$artifact_dir/push-$$.json" \
     --deadline "${OUSAST_PUSH_DEADLINE:-30}" \
     --mode "${OUSAST_PUSH_MODE:-advisory}" \
-    --incomplete-coverage "${OUSAST_INCOMPLETE_COVERAGE:-allow}" \
-    --engine "${OUSAST_PUSH_ENGINE:-inline}"
+    --incomplete-coverage "${OUSAST_INCOMPLETE_COVERAGE:-allow}"
+# Optional settings are passed only when set, so an older ousast (or image) still runs.
+if [ -n "${OUSAST_PUSH_ENGINE:-}" ]; then
+    set -- "$@" --engine "$OUSAST_PUSH_ENGINE"
+fi
 if [ -n "${OUSAST_COMPARISON_BASE:-}" ]; then
     set -- "$@" --comparison-base "$OUSAST_COMPARISON_BASE"
 fi