chore(selfhost): deduplicate the Docker prune scripts

[JSONbored]

Summary

Two Docker-prune scripts had accidentally accumulated at scripts/ from two separate PRs, doing overlapping jobs:

• scripts/selfhost-docker-prune.sh (PR chore(selfhost): automate Docker disk hygiene for the self-host stack #2576) — the canonical one: systemd-timer-integrated (systemd/gittensory-docker-prune.{service,timer}.example), documented in the self-hosting operations docs, and covered by test/unit/selfhost-docker-prune-script.test.ts. Age-filtered (GITTENSORY_DOCKER_PRUNE_RETAIN_HOURS, default 7 days) so nothing built/pulled recently is touched.
• scripts/docker-prune.sh (PR feat(selfhost): defer maintenance work under runtime pressure #2717) — added without noticing the above already existed. Manual/compose-oriented, dry-run-by-default, not referenced by any docs, no dedicated test.

This PR keeps the canonical script and folds in the genuinely useful behavior the other one had, then deletes it:

• Stopped-container pruning (docker container prune), age-filtered the same way images/build cache already were — a real capability gap the canonical script was missing.
• An opt-in --dry-run preview mode that reports disk usage without deleting anything. The systemd timer's zero-argument default call is unchanged — it still prunes for real, so this is purely additive for manual/interactive use.
• A root filesystem usage report (df -h /) alongside the existing docker system df.
• A docker-on-PATH presence check before doing anything.

Also fixes every reference to the deleted script name (docker-compose.yml, docker-compose.override.yml.example, .env.example) to point at scripts/selfhost-docker-prune.sh, and documents the previously-undocumented GITTENSORY_DOCKER_PRUNE_RETAIN_HOURS env var in .env.example.

Why this isn't a behavior change for existing deployments

The systemd timer already installed on any self-host box calls sh scripts/selfhost-docker-prune.sh with zero arguments — that exact invocation's behavior (age-filtered image + build-cache pruning) is unchanged. The new container-pruning step and --dry-run flag are additive; nothing about the default unattended run regressed.

Validation

• docker compose --profile runners -f docker-compose.yml config --quiet (also with every profile active)
• npm run typecheck
• shellcheck scripts/selfhost-docker-prune.sh — clean
• Extended test/unit/selfhost-docker-prune-script.test.ts (3 → 6 cases): stopped-container pruning, --dry-run issues no destructive call and never touches volumes, --dry-run still honors the retain-hours env var, and an unrecognized argument is rejected rather than silently ignored.
• npm run test:ci (full local gate) — 7113 tests passed, fully green.
• npm audit --audit-level=moderate — 0 vulnerabilities.
• Regenerated apps/gittensory-ui/src/lib/selfhost-env-reference.ts (npm run selfhost:env-reference) — picked up unrelated line-number drift from a recently-merged PR, included here since the check requires it to be current.
• No src/** files touched; the changed/extended shell script and test live under scripts/**/test/**, both Codecov-ignored per codecov.yml, but the extended test suite still gives real regression coverage for every new behavior.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	69cb9fc	Commit Preview URL Branch Preview URL	Jul 03 2026, 09:12 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.03%. Comparing base (86dde13) to head (69cb9fc).
⚠️ Report is 7 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2721      +/-   ##
==========================================
+ Coverage   96.01%   96.03%   +0.02%     
==========================================
  Files         244      245       +1     
  Lines       27300    27340      +40     
  Branches     9919     9930      +11     
==========================================
+ Hits        26211    26255      +44     
+ Misses        462      460       -2     
+ Partials      627      625       -2     

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-03 09:33:46 UTC}

7 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review

Review summary
The PR consolidates the Docker prune entry point, preserves the existing image/build-cache age filters, and adds stopped-container pruning based on actual stop time instead of Docker's creation-time prune filter. The main shell logic is coherent and the tests exercise the real script via PATH-stubbed docker/date binaries, including dry-run and removal-failure behavior. The visible docs/reference updates consistently point at the canonical script, so I do not see a merge-blocking defect in this diff.

Nits — 6 non-blocking

• nit: scripts/selfhost-docker-prune.sh:51 leaves the mktemp file behind if `docker ps` or the loop aborts under `set -e`; add a trap or cleanup-on-return so failed Docker calls do not accumulate temp files.
• nit: scripts/selfhost-docker-prune.sh:44 relies on `RETAIN_HOURS` being a valid non-negative integer before shell arithmetic; validate it up front so a bad env value produces a clear operator error instead of an arithmetic expansion failure.
• nit: test/unit/selfhost-docker-prune-script.test.ts:103 builds a shell command string for the capture helper; the quoting is careful, but using `execFileSync("sh", ["scripts/selfhost-docker-prune.sh", ...args], { stdio })` with separate stderr capture would avoid adding another shell-parsing surface to the test helper.
• Add `trap 'rm -f "$container_list"' EXIT HUP INT TERM` or a function-local cleanup pattern in `scripts/selfhost-docker-prune.sh` around the temporary container list.
• Validate `GITTENSORY_DOCKER_PRUNE_RETAIN_HOURS` in `scripts/selfhost-docker-prune.sh` with a numeric case check before calculating `cutoff_epoch`.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ No-issue rationale	PR body explains why no issue is linked.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 61 registered-repo PR(s), 52 merged, 478 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 61 PR(s), 478 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 61 PR(s), 478 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• No action.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review