ducoterra
209f167e43
The explainer for questions about a flag, a config key, a refusal, a mechanism or a security boundary. ai-sandbox generates its own Containerfile, entrypoint, squid config and netfilter rules from one script, so the text of the program is the documentation of the version the user will run: the skill sets a strict ground-truth order -- the installed script and --help, then the repo docs, then the tests as the executable spec -- and its own fact sheet last, overridden by all of them. scripts/locate.sh resolves that order on an arbitrary machine: the installed script and its version, the source tree behind it (via $AISB_REPO, the script's own parent, $PWD, the git root), the docs with their line counts, and the config/state/cache locations. references/source-map.md maps a question topic to the function, doc and test that hold the answer, plus the vocabulary (split_target, classify_allows, gate vs --no-gate vs --proxy, POL[]/P_*/OPT_*) and the FAQ. The skill names which safe surface answers what: the --dry-run, --print-entrypoint, --print-containerfile and --print-policy previews build nothing and reach no registry, while inspect, doctor --deep, build, update and gate up do change the machine and are not for an explanation. It records the two honest exceptions rather than overclaiming -- --print-policy ensures the home volume, and --no-gate hits DNS. Read-only by construction: no build, no container, no network call, and it reads pi_config_bridge() rather than a models.json holding a live key. Its worst failure mode is an invented flag, so the answer format requires the real spelling, the source it came from, what the thing does not do, and a plain "no" plus the closest real thing when the answer is no. LLM-Generated: true
76 lines
3.7 KiB
Bash
Executable File
76 lines
3.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# locate.sh -- where the ground truth for an ai-sandbox question lives on THIS machine.
|
|
#
|
|
# Read-only, prints no secrets, starts nothing. Answers questions about ai-sandbox from the
|
|
# program's own text and its docs, never from memory -- so first find them.
|
|
#
|
|
# bash locate.sh
|
|
|
|
set -uo pipefail
|
|
|
|
section() { printf '\n== %s\n' "$1"; }
|
|
note() { printf ' %s\n' "$1"; }
|
|
found() { printf ' [x] %s\n' "$1"; }
|
|
warn() { printf ' [!] %s\n' "$1"; }
|
|
|
|
BIN="$(command -v ai-sandbox 2>/dev/null || true)"
|
|
[[ -n "$BIN" ]] || BIN="$(command -v ai-sandbox-autophase 2>/dev/null || true)"
|
|
|
|
section "the program (the authority on flags and behaviour)"
|
|
if [[ -n "$BIN" ]]; then
|
|
real="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
|
|
found "$real"
|
|
note "version: $("$BIN" version 2>/dev/null || printf 'unknown -- older than the version subcommand')"
|
|
note "flags for this exact build: $BIN --help"
|
|
else
|
|
warn "ai-sandbox is not on PATH -- answer from the repository instead, and say so"
|
|
fi
|
|
|
|
# A candidate is the script itself, or a repo holding it (bin/ai-sandbox with README.md beside).
|
|
SCRIPT=""
|
|
[[ -n "$BIN" ]] && SCRIPT="$(readlink -f "$BIN" 2>/dev/null || printf '%s' "$BIN")"
|
|
|
|
candidates=()
|
|
[[ -n "${AISB_REPO:-}" ]] && candidates+=("$AISB_REPO")
|
|
[[ -n "${SCRIPT:-}" ]] && candidates+=("$(dirname "$(dirname "$SCRIPT")")")
|
|
candidates+=("$PWD" "$(git rev-parse --show-toplevel 2>/dev/null || true)")
|
|
|
|
REPO=""
|
|
for c in ${candidates[@]+"${candidates[@]}"}; do
|
|
[[ -n "$c" && -d "$c" ]] || continue
|
|
if [[ -f "$c/bin/ai-sandbox" && -f "$c/docs/threat-model.md" ]]; then REPO="$c"; break; fi
|
|
done
|
|
|
|
section "the source tree (the authority on why)"
|
|
if [[ -n "$REPO" ]]; then
|
|
found "$REPO"
|
|
for f in README.md AGENTS.md docs/networking.md docs/threat-model.md docs/recipes.md bin/ai-sandbox bin/ai-sandbox-autophase; do
|
|
[[ -f "$REPO/$f" ]] && note "$(printf '%-32s %s lines' "$f" "$(wc -l < "$REPO/$f")")"
|
|
done
|
|
[[ -d "$REPO/tests" ]] && note "tests/ -- the executable spec: unit/ needs no containers, e2e/ runs real ones"
|
|
[[ -z "$BIN" ]] && note "not installed, but this tree runs: $REPO/bin/ai-sandbox --help"
|
|
note "if the installed script and this tree differ, say which one you read"
|
|
else
|
|
note "no repository found (tried \$AISB_REPO, the installed script's parent, \$PWD, the git root)"
|
|
note "the installed script alone answers most questions: it is one file, and it generates"
|
|
note "the Containerfile, the entrypoint and the squid config from itself"
|
|
fi
|
|
|
|
section "read the machine, or read the script"
|
|
note "safe, deterministic, no build / container / state / registry:"
|
|
note " ai-sandbox --help every flag, this version"
|
|
note " ai-sandbox version"
|
|
note " ai-sandbox --dry-run the exact podman invocation, secret values redacted"
|
|
note " ai-sandbox --print-policy effective policy as key=value -- but it also ensures the"
|
|
note " home volume exists, so it needs podman on the host"
|
|
note " ai-sandbox --print-entrypoint the enforcement script baked into the image"
|
|
note " ai-sandbox --print-containerfile the generated Containerfile"
|
|
note "asks the machine now (may reach the registry, starts nothing): ai-sandbox inspect"
|
|
note "touches the host: doctor [--deep], build, update, gate up, clean, and any real run"
|
|
|
|
section "state a run leaves behind"
|
|
note "config: ${AISB_CONFIG_DIR:-$HOME/.config/ai-sandbox}/{config,allow}"
|
|
note "state: ${AISB_STATE_DIR:-$HOME/.local/state/ai-sandbox}/log (every run, no secret values)"
|
|
note "cache: ${AISB_CACHE_DIR:-$HOME/.cache/ai-sandbox}/base/ (the recorded base digests)"
|
|
note "repo: ./.ai-sandbox/{config,allow}"
|