feat: document wrapping docket from ansible-dokku

[josegonzalez]

A new page maps each of the 27 ansible-dokku modules onto its docket task across the 73 registered task types, states where the two disagree on which fields are required, specifies the JSON payload a wrapper generates and pipes in, and names what cannot be delegated yet. apply gains --detailed-exitcode, mirroring plan, so a wrapper running one docket invocation per Ansible task reads changed off the exit code rather than parsing the event stream; without it apply still exits 0 whether or not anything changed. The validate --json problem schema was never written down and now sits alongside the apply and plan events, and all three streams ship JSON Schema files under docs/schemas/.

Writing the contract down surfaced one pre-existing gap that is documented but not fixed here: --list-tasks --json resolves the plan before any sensitive value is registered and does no masking, so an interpolated secret comes back verbatim in name. Both pages now warn against routing that stream anywhere a secret must not land.

The four things a wrapper cannot delegate are tracked in #414, #415, #416, and #417.

Closes #409.

[dokku-bot]

sh-checker report

To get the full details, please check in the job output.

shellcheck errors

shellcheck checking is disabled.

shfmt errors

'shfmt -l -d -i 2' returned error 1 finding the following formatting issues:

----------
tests/bats/ansible.bats
diff tests/bats/ansible.bats.orig tests/bats/ansible.bats
--- tests/bats/ansible.bats.orig
+++ tests/bats/ansible.bats
@@ -70,8 +70,8 @@
     [ -z "$line" ] && continue
     echo "$line" | jq . >/dev/null || fail "invalid JSON: $line"
   done <<<"$output"
-  echo "$output" | jq -e 'select(.type == "list_task") | .name == "set config on api"' >/dev/null \
-    || fail "expected the task name echoed back: $output"
+  echo "$output" | jq -e 'select(.type == "list_task") | .name == "set config on api"' >/dev/null ||
+    fail "expected the task name echoed back: $output"
 }
 
 @test "a bad payload reports validate_problem events a wrapper can branch on" {
----------

You can reformat the above files to meet shfmt's requirements by typing:

  shfmt -l -d -i 2 -w filename

[dokku-bot]

sh-checker report

To get the full details, please check in the job output.

shellcheck errors

shellcheck checking is disabled.

shfmt errors

'shfmt -l -d -i 2' returned error 1 finding the following formatting issues:

----------
install.sh
diff install.sh.orig install.sh
--- install.sh.orig
+++ install.sh
@@ -20,27 +20,27 @@
 
 os="$(uname -s | tr '[:upper:]' '[:lower:]')"
 case "$os" in
-  linux | darwin) ;;
-  mingw* | msys* | cygwin*) os="windows" ;;
-  *)
-    echo "error: unsupported OS: $os" >&2
-    exit 1
-    ;;
+linux | darwin) ;;
+mingw* | msys* | cygwin*) os="windows" ;;
+*)
+  echo "error: unsupported OS: $os" >&2
+  exit 1
+  ;;
 esac
 
 arch="$(uname -m)"
 case "$arch" in
-  x86_64 | amd64) arch="amd64" ;;
-  aarch64 | arm64) arch="arm64" ;;
-  *)
-    echo "error: unsupported architecture: $arch" >&2
-    exit 1
-    ;;
+x86_64 | amd64) arch="amd64" ;;
+aarch64 | arm64) arch="arm64" ;;
+*)
+  echo "error: unsupported architecture: $arch" >&2
+  exit 1
+  ;;
 esac
 
 if [ -z "${VERSION:-}" ]; then
-  VERSION="$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" \
-    | sed -n 's/.*"tag_name": "\(.*\)".*/\1/p' | head -n1)"
+  VERSION="$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" |
+    sed -n 's/.*"tag_name": "\(.*\)".*/\1/p' | head -n1)"
 fi
 
 if [ -z "$VERSION" ]; then
@@ -99,7 +99,7 @@
 
 echo "installed docket ${VERSION} to ${dest}"
 case ":${PATH}:" in
-  *":${BIN_DIR}:"*) ;;
-  *) echo "note: ${BIN_DIR} is not on your PATH; add it to run 'docket' directly" >&2 ;;
+*":${BIN_DIR}:"*) ;;
+*) echo "note: ${BIN_DIR} is not on your PATH; add it to run 'docket' directly" >&2 ;;
 esac
 echo "try: docket version"
tests/bats/ansible.bats
diff tests/bats/ansible.bats.orig tests/bats/ansible.bats
--- tests/bats/ansible.bats.orig
+++ tests/bats/ansible.bats
@@ -70,8 +70,8 @@
     [ -z "$line" ] && continue
     echo "$line" | jq . >/dev/null || fail "invalid JSON: $line"
   done <<<"$output"
-  echo "$output" | jq -e 'select(.type == "list_task") | .name == "set config on api"' >/dev/null \
-    || fail "expected the task name echoed back: $output"
+  echo "$output" | jq -e 'select(.type == "list_task") | .name == "set config on api"' >/dev/null ||
+    fail "expected the task name echoed back: $output"
 }
 
 @test "a bad payload reports validate_problem events a wrapper can branch on" {
----------

You can reformat the above files to meet shfmt's requirements by typing:

  shfmt -l -d -i 2 -w filename