opencode-agent-harness 0.0.0-stage → 0.3.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +288 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +187 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,185 @@
1
+ #!/usr/bin/env bash
2
+ #
3
+ # setup-nightly.sh — install the off-hours E2E cycle as a systemd --user timer.
4
+ #
5
+ # Runs `scripts/nightly.js run` on a schedule (default 02:00) in this project, so
6
+ # the full E2E battery test the day's landed code while nobody is working. The
7
+ # timer is `Persistent=true`: if the machine was off at the scheduled time it
8
+ # runs on the next boot. User units need lingering to fire without a login
9
+ # session, which `install` enables (loginctl enable-linger).
10
+ #
11
+ # setup-nightly.sh install [--time HH:MM] [--force] create + enable the timer
12
+ # setup-nightly.sh uninstall disable + remove it
13
+ # setup-nightly.sh status timer state + last run
14
+ # setup-nightly.sh run-now run the cycle immediately
15
+ # setup-nightly.sh --dry-run ... print what would change
16
+ #
17
+ # Overrides: AGENT_NIGHTLY_TIME (HH:MM, default 02:00), AGENT_NIGHTLY_UNIT,
18
+ # AGENT_NIGHTLY_UNIT_DIR, AGENT_NIGHTLY_ROOT (project root), AGENT_NIGHTLY_DRY_RUN=1.
19
+ # A machine without systemd --user falls back to a crontab line (printed, not
20
+ # installed).
21
+ set -u
22
+
23
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
24
+ ROOT="${AGENT_NIGHTLY_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
25
+ SLUG="$(basename "$ROOT" | tr 'A-Z' 'a-z' | tr -c 'a-z0-9' '-' | sed 's/-*$//')"
26
+ [ -n "$SLUG" ] || SLUG="project"
27
+ UNIT_NAME="${AGENT_NIGHTLY_UNIT:-agent-nightly-${SLUG}}"
28
+ UNIT_DIR="${AGENT_NIGHTLY_UNIT_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user}"
29
+ TIME="02:00"
30
+ DRY_RUN="${AGENT_NIGHTLY_DRY_RUN:-0}"
31
+
32
+ ACTION=""
33
+ WANT_TIME=""
34
+ FORCE=0
35
+ args=("$@")
36
+ for ((i = 0; i < ${#args[@]}; i++)); do
37
+ a="${args[$i]}"
38
+ case "$a" in
39
+ --dry-run) DRY_RUN=1 ;;
40
+ --time) WANT_TIME="${args[$((i + 1))]:-}"; i=$((i + 1)) ;;
41
+ --time=*) WANT_TIME="${a#--time=}" ;;
42
+ --force) FORCE=1 ;;
43
+ install | uninstall | status | run-now) ACTION="$a" ;;
44
+ -h | --help) ACTION="help" ;;
45
+ *) echo "setup-nightly: unknown argument: $a" >&2; ACTION="help" ;;
46
+ esac
47
+ done
48
+ [ -n "$WANT_TIME" ] && TIME="$WANT_TIME"
49
+
50
+ usage() {
51
+ sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
52
+ }
53
+
54
+ have() { command -v "$1" >/dev/null 2>&1; }
55
+
56
+ run() {
57
+ if [ "$DRY_RUN" = "1" ]; then
58
+ printf ' [dry-run] %s\n' "$*"
59
+ return 0
60
+ fi
61
+ "$@"
62
+ }
63
+
64
+ have_systemd() {
65
+ have systemctl && systemctl --user show-environment >/dev/null 2>&1
66
+ }
67
+
68
+ validate_time() {
69
+ case "$TIME" in
70
+ [0-2][0-9]:[0-5][0-9]) return 0 ;;
71
+ *) echo "setup-nightly: --time must be HH:MM (got '$TIME')" >&2; return 1 ;;
72
+ esac
73
+ }
74
+
75
+ write_units() {
76
+ run mkdir -p "$UNIT_DIR"
77
+ if [ "$DRY_RUN" = "1" ]; then
78
+ printf ' [dry-run] write %s/%s.{service,timer}\n' "$UNIT_DIR" "$UNIT_NAME"
79
+ return 0
80
+ fi
81
+ cat >"$UNIT_DIR/$UNIT_NAME.service" <<EOF
82
+ [Unit]
83
+ Description=agent-harness nightly E2E cycle for $SLUG
84
+ After=network-online.target
85
+ Wants=network-online.target
86
+
87
+ [Service]
88
+ Type=oneshot
89
+ WorkingDirectory=$ROOT
90
+ ExecStart=$(command -v node) $ROOT/scripts/nightly.js run --root $ROOT
91
+ TimeoutStartSec=infinity
92
+ Nice=10
93
+ EOF
94
+ cat >"$UNIT_DIR/$UNIT_NAME.timer" <<EOF
95
+ [Unit]
96
+ Description=Run the agent-harness nightly E2E cycle for $SLUG
97
+
98
+ [Timer]
99
+ OnCalendar=*-*-* $TIME:00
100
+ Persistent=true
101
+ RandomizedDelaySec=300
102
+ Unit=$UNIT_NAME.service
103
+
104
+ [Install]
105
+ WantedBy=timers.target
106
+ EOF
107
+ echo "setup-nightly: wrote $UNIT_DIR/$UNIT_NAME.{service,timer}"
108
+ }
109
+
110
+ remove_units() {
111
+ if [ "$DRY_RUN" != "1" ]; then
112
+ rm -f "$UNIT_DIR/$UNIT_NAME.service" "$UNIT_DIR/$UNIT_NAME.timer"
113
+ else
114
+ printf ' [dry-run] remove %s/%s.{service,timer}\n' "$UNIT_DIR" "$UNIT_NAME"
115
+ fi
116
+ }
117
+
118
+ enable_linger() {
119
+ if have loginctl; then
120
+ run loginctl enable-linger "$(id -un)" >/dev/null 2>&1 ||
121
+ run sudo -n loginctl enable-linger "$(id -un)" >/dev/null 2>&1 ||
122
+ echo "setup-nightly: could not enable linger automatically — run: sudo loginctl enable-linger $(id -un)"
123
+ fi
124
+ }
125
+
126
+ cmd_install() {
127
+ validate_time || return 1
128
+ if ! have systemd; then
129
+ echo "setup-nightly: no systemd --user bus on this host — install the cron fallback instead:"
130
+ echo " $TIME daily: cd $ROOT && node scripts/nightly.js run --root $ROOT"
131
+ return 1
132
+ fi
133
+ if [ "$FORCE" != "1" ] && [ -f "$UNIT_DIR/$UNIT_NAME.timer" ] && [ "$DRY_RUN" != "1" ]; then
134
+ echo "setup-nightly: $UNIT_NAME.timer already installed (pass --force to rewrite)."
135
+ fi
136
+ write_units
137
+ enable_linger
138
+ run systemctl --user daemon-reload
139
+ run systemctl --user enable --now "$UNIT_NAME.timer"
140
+ echo "setup-nightly: enabled $UNIT_NAME.timer for $TIME daily (Persistent=true)."
141
+ echo " next: systemctl --user list-timers $UNIT_NAME.timer"
142
+ echo " run now: $ROOT/scripts/setup-nightly.sh run-now"
143
+ echo " uninstall: $ROOT/scripts/setup-nightly.sh uninstall"
144
+ }
145
+
146
+ cmd_uninstall() {
147
+ if have systemd; then
148
+ run systemctl --user disable --now "$UNIT_NAME.timer" 2>/dev/null || true
149
+ fi
150
+ remove_units
151
+ if have systemd; then
152
+ run systemctl --user daemon-reload
153
+ fi
154
+ echo "setup-nightly: uninstalled $UNIT_NAME."
155
+ }
156
+
157
+ cmd_status() {
158
+ if [ -f "$UNIT_DIR/$UNIT_NAME.timer" ]; then
159
+ echo "timer: installed ($UNIT_DIR/$UNIT_NAME.timer)"
160
+ else
161
+ echo "timer: not installed"
162
+ fi
163
+ if have systemd; then
164
+ systemctl --user is-enabled "$UNIT_NAME.timer" 2>/dev/null | sed 's/^/enabled: /' || true
165
+ systemctl --user list-timers "$UNIT_NAME.timer" --no-pager 2>/dev/null | sed 's/^/ /' || true
166
+ fi
167
+ if [ -f "$ROOT/.agents/qa-runs/nightly/latest.json" ]; then
168
+ node "$ROOT/scripts/nightly.js" report --root "$ROOT" 2>/dev/null || true
169
+ else
170
+ echo "last run: none recorded"
171
+ fi
172
+ }
173
+
174
+ cmd_run_now() {
175
+ cd "$ROOT" || return 1
176
+ exec node "$ROOT/scripts/nightly.js" run --root "$ROOT"
177
+ }
178
+
179
+ case "$ACTION" in
180
+ help | "") usage ;;
181
+ install) cmd_install ;;
182
+ uninstall) cmd_uninstall ;;
183
+ status) cmd_status ;;
184
+ run-now) cmd_run_now ;;
185
+ esac
@@ -0,0 +1,374 @@
1
+ #!/usr/bin/env bash
2
+ #
3
+ # setup-tmpfs.sh — RAM-backed build/cache storage for WSL2 agent workspaces.
4
+ #
5
+ # ############################################################
6
+ # # WARNING: tmpfs is VOLATILE RAM. Its contents vanish on #
7
+ # # reboot, OOM, WSL restart, or `setup-tmpfs.sh down`. #
8
+ # # Put CACHES and BUILD ARTIFACTS here ONLY. #
9
+ # # NEVER source code, databases, secrets, or git state. #
10
+ # ############################################################
11
+ #
12
+ # Mounts a single tmpfs root (default /mnt/ramdisk) sized 25-40% of WSL RAM and
13
+ # points the cache/build env vars for ONLY the ecosystems actually installed:
14
+ # PIP_CACHE_DIR, npm_config_cache, PNPM_STORE_DIR, YARN_CACHE_FOLDER,
15
+ # CARGO_TARGET_DIR, GOCACHE, GRADLE_USER_HOME, CCACHE_DIR, SCCACHE_DIR,
16
+ # RUSTC_WRAPPER=sccache.
17
+ #
18
+ # It is idempotent (a no-op when the tmpfs is already mounted), no-ops outside
19
+ # WSL, and can persist across shells/boots via a ~/.bashrc hook and an optional
20
+ # systemd --user unit.
21
+ #
22
+ # Usage:
23
+ # setup-tmpfs.sh [up] mount + write env (default; idempotent)
24
+ # setup-tmpfs.sh ensure quiet idempotent variant (used by the hook)
25
+ # setup-tmpfs.sh env print `export ...` lines for `eval`
26
+ # setup-tmpfs.sh status show mount + env state
27
+ # setup-tmpfs.sh install persist: copy here + systemd unit + bashrc hook
28
+ # setup-tmpfs.sh down unmount + remove the persisted env file
29
+ # setup-tmpfs.sh uninstall down + remove unit + bashrc hook
30
+ # setup-tmpfs.sh --dry-run ... print what would happen; change nothing
31
+ #
32
+ # Overrides: AGENT_RAMDISK, AGENT_TMPFS_PERCENT (25-40), AGENT_TMPFS_CONFIG,
33
+ # AGENT_TMPFS_FORCE=1 (treat non-WSL as WSL), AGENT_TMPFS_DRY_RUN=1.
34
+ set -u
35
+
36
+ RAMDISK="${AGENT_RAMDISK:-/mnt/ramdisk}"
37
+ PERCENT="${AGENT_TMPFS_PERCENT:-30}"
38
+ CONFIG_DIR="${AGENT_TMPFS_CONFIG:-$HOME/.config/agent-harness}"
39
+ ENV_FILE="$CONFIG_DIR/tmpfs.env"
40
+ INSTALLED_SCRIPT="$CONFIG_DIR/setup-tmpfs.sh"
41
+ UNIT_DIR="${AGENT_TMPFS_UNIT_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user}"
42
+ UNIT_NAME="agent-tmpfs.service"
43
+ BASHRC="${AGENT_TMPFS_BASHRC:-$HOME/.bashrc}"
44
+ DRY_RUN="${AGENT_TMPFS_DRY_RUN:-0}"
45
+ BASHRC_MARKER="# agent-harness tmpfs caches (managed)"
46
+ BASHRC_END="# agent-harness tmpfs caches (managed end)"
47
+
48
+ ACTION="up"
49
+ for arg in "$@"; do
50
+ case "$arg" in
51
+ --dry-run) DRY_RUN=1 ;;
52
+ up | ensure | env | status | install | down | uninstall) ACTION="$arg" ;;
53
+ -h | --help) ACTION="help" ;;
54
+ *)
55
+ echo "setup-tmpfs: unknown argument: $arg" >&2
56
+ ACTION="help"
57
+ ;;
58
+ esac
59
+ done
60
+
61
+ usage() {
62
+ sed -n '2,/^set -u$/p' "$0" | sed 's/^# \{0,1\}//; /^set -u$/d'
63
+ }
64
+
65
+ have() { command -v "$1" >/dev/null 2>&1; }
66
+
67
+ run() {
68
+ if [ "$DRY_RUN" = "1" ]; then
69
+ printf ' [dry-run] %s\n' "$*"
70
+ return 0
71
+ fi
72
+ "$@"
73
+ }
74
+
75
+ as_root() {
76
+ if [ "$(id -u)" = "0" ]; then
77
+ "$@"
78
+ elif have sudo; then
79
+ sudo -n "$@"
80
+ else
81
+ "$@"
82
+ fi
83
+ }
84
+
85
+ is_wsl() {
86
+ # AGENT_TMPFS_FORCE can force the answer either way (0 = force off, 1 = force on).
87
+ [ "${AGENT_TMPFS_FORCE:-}" = "1" ] && return 0
88
+ [ "${AGENT_TMPFS_FORCE:-}" = "0" ] && return 1
89
+ [ -n "${WSL_DISTRO_NAME:-}" ] && return 0
90
+ grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null
91
+ }
92
+
93
+ is_mounted() {
94
+ awk -v p="$RAMDISK" '$2==p {f=1} END {exit(f?0:1)}' /proc/mounts 2>/dev/null
95
+ }
96
+
97
+ is_tmpfs() {
98
+ awk -v p="$RAMDISK" '$2==p && $3=="tmpfs" {f=1} END {exit(f?0:1)}' /proc/mounts 2>/dev/null
99
+ }
100
+
101
+ total_ram_mb() {
102
+ local kb
103
+ kb=$(awk '/^MemTotal:/{print $2}' /proc/meminfo 2>/dev/null)
104
+ [ -n "${kb:-}" ] || kb=$((4 * 1024 * 1024))
105
+ echo $((kb / 1024))
106
+ }
107
+
108
+ size_mb() {
109
+ local pct="$PERCENT" total
110
+ [ "$pct" -lt 25 ] 2>/dev/null && pct=25
111
+ [ "$pct" -gt 40 ] 2>/dev/null && pct=40
112
+ total=$(total_ram_mb)
113
+ echo $((total * pct / 100))
114
+ }
115
+
116
+ # Emit env vars for ecosystems actually present. Nothing is set for a toolchain
117
+ # that isn't installed (no phantom cache dirs).
118
+ env_lines() {
119
+ if have python3 || have python || have pip || have pip3; then
120
+ echo "export PIP_CACHE_DIR=$RAMDISK/cache/pip"
121
+ fi
122
+ if have npm; then
123
+ echo "export npm_config_cache=$RAMDISK/cache/npm"
124
+ fi
125
+ if have pnpm; then
126
+ echo "export PNPM_STORE_DIR=$RAMDISK/cache/pnpm"
127
+ fi
128
+ if have yarn; then
129
+ echo "export YARN_CACHE_FOLDER=$RAMDISK/cache/yarn"
130
+ fi
131
+ if have cargo || have rustc; then
132
+ echo "export CARGO_TARGET_DIR=$RAMDISK/cargo/target"
133
+ fi
134
+ if have go; then
135
+ echo "export GOCACHE=$RAMDISK/cache/go"
136
+ fi
137
+ if have gradle; then
138
+ echo "export GRADLE_USER_HOME=$RAMDISK/gradle"
139
+ fi
140
+ if have ccache; then
141
+ echo "export CCACHE_DIR=$RAMDISK/cache/ccache"
142
+ fi
143
+ if have sccache; then
144
+ echo "export SCCACHE_DIR=$RAMDISK/cache/sccache"
145
+ echo "export RUSTC_WRAPPER=sccache"
146
+ fi
147
+ }
148
+
149
+ ensure_dirs() {
150
+ local line dir
151
+ while IFS= read -r line; do
152
+ dir="${line#*=}"
153
+ case "$dir" in
154
+ "$RAMDISK"/*) run mkdir -p "$dir" ;;
155
+ esac
156
+ done < <(env_lines)
157
+ }
158
+
159
+ write_env_file() {
160
+ run mkdir -p "$CONFIG_DIR"
161
+ if [ "$DRY_RUN" = "1" ]; then
162
+ printf ' [dry-run] write %s\n' "$ENV_FILE"
163
+ return 0
164
+ fi
165
+ {
166
+ echo "# agent-harness RAM-backed build/cache env — generated by setup-tmpfs.sh."
167
+ echo "# WARNING: volatile tmpfs backing; caches/build artifacts only."
168
+ env_lines
169
+ } >"$ENV_FILE"
170
+ }
171
+
172
+ mount_opts() {
173
+ # Own the mount as the invoking user so cache subdirs are writable without
174
+ # root for every subsequent build.
175
+ echo "size=$(size_mb)M,mode=0755,uid=$(id -u),gid=$(id -g)"
176
+ }
177
+
178
+ guard_ramdisk() {
179
+ case "$RAMDISK" in
180
+ "" | / | /mnt | /home | "$HOME")
181
+ echo "setup-tmpfs: refusing unsafe AGENT_RAMDISK '$RAMDISK'." >&2
182
+ return 1
183
+ ;;
184
+ esac
185
+ return 0
186
+ }
187
+
188
+ cmd_up() {
189
+ is_wsl || {
190
+ echo "setup-tmpfs: not WSL — no-op."
191
+ return 0
192
+ }
193
+ guard_ramdisk || return 1
194
+ if is_mounted; then
195
+ if ! is_tmpfs; then
196
+ echo "setup-tmpfs: $RAMDISK is mounted but not tmpfs — refusing to touch it." >&2
197
+ return 1
198
+ fi
199
+ echo "setup-tmpfs: $RAMDISK already mounted (no-op mount)."
200
+ else
201
+ run as_root mkdir -p "$RAMDISK"
202
+ if [ "$DRY_RUN" = "1" ]; then
203
+ printf ' [dry-run] mount -t tmpfs -o %s tmpfs %s\n' "$(mount_opts)" "$RAMDISK"
204
+ else
205
+ if ! as_root mount -t tmpfs -o "$(mount_opts)" tmpfs "$RAMDISK"; then
206
+ echo "setup-tmpfs: mount failed (needs root) — retry with: sudo $0 up" >&2
207
+ return 1
208
+ fi
209
+ echo "setup-tmpfs: mounted tmpfs at $RAMDISK ($(mount_opts), ${PERCENT}% of RAM)."
210
+ fi
211
+ fi
212
+ ensure_dirs
213
+ write_env_file
214
+ echo
215
+ echo "# WARNING: $RAMDISK is RAM-backed and VOLATILE — a reboot, OOM, or"
216
+ echo "# 'setup-tmpfs.sh down' ERASES it. Caches and build artifacts only;"
217
+ echo "# NEVER source code, databases, or git state."
218
+ echo "# Activate in this shell with: eval \"\$($0 env)\""
219
+ }
220
+
221
+ cmd_ensure() {
222
+ is_wsl || return 0
223
+ guard_ramdisk || return 0
224
+ if ! is_mounted; then
225
+ as_root mkdir -p "$RAMDISK" >/dev/null 2>&1
226
+ as_root mount -t tmpfs -o "$(mount_opts)" tmpfs "$RAMDISK" >/dev/null 2>&1 || return 0
227
+ fi
228
+ ensure_dirs >/dev/null 2>&1
229
+ write_env_file >/dev/null 2>&1
230
+ return 0
231
+ }
232
+
233
+ cmd_status() {
234
+ if ! is_wsl; then
235
+ echo "setup-tmpfs: not WSL — tmpfs setup is a no-op here."
236
+ return 0
237
+ fi
238
+ if is_mounted; then
239
+ echo "mounted: yes"
240
+ awk -v p="$RAMDISK" '$2==p {print " fstype=" $3 " options=" $4}' /proc/mounts
241
+ df -h "$RAMDISK" | sed 's/^/ /'
242
+ else
243
+ echo "mounted: no ($RAMDISK)"
244
+ fi
245
+ echo "config: $CONFIG_DIR"
246
+ [ -f "$ENV_FILE" ] && echo "env: present ($ENV_FILE)" || echo "env: absent"
247
+ echo "env vars detected for this host:"
248
+ env_lines | sed 's/^/ /'
249
+ }
250
+
251
+ write_unit() {
252
+ if [ "$DRY_RUN" = "1" ]; then
253
+ printf ' [dry-run] write %s/%s\n' "$UNIT_DIR" "$UNIT_NAME"
254
+ return 0
255
+ fi
256
+ mkdir -p "$UNIT_DIR"
257
+ {
258
+ echo "[Unit]"
259
+ echo "Description=agent-harness RAM-backed build/cache tmpfs"
260
+ echo "After=default.target"
261
+ echo
262
+ echo "[Service]"
263
+ echo "Type=oneshot"
264
+ echo "RemainAfterExit=yes"
265
+ echo "Environment=AGENT_TMPFS_CONFIG=$CONFIG_DIR"
266
+ echo "ExecStart=$INSTALLED_SCRIPT up"
267
+ echo "ExecStop=$INSTALLED_SCRIPT down"
268
+ echo
269
+ echo "[Install]"
270
+ echo "WantedBy=default.target"
271
+ } >"$UNIT_DIR/$UNIT_NAME"
272
+ }
273
+
274
+ install_bashrc_hook() {
275
+ if [ "$DRY_RUN" = "1" ]; then
276
+ printf ' [dry-run] install bashrc hook in %s\n' "$BASHRC"
277
+ return 0
278
+ fi
279
+ touch "$BASHRC"
280
+ awk -v b="$BASHRC_MARKER" -v e="$BASHRC_END" '
281
+ $0==b {skip=1; next}
282
+ skip && $0==e {skip=0; next}
283
+ !skip {print}
284
+ ' "$BASHRC" >"$BASHRC.tmp.$$" && mv "$BASHRC.tmp.$$" "$BASHRC"
285
+ {
286
+ printf '%s\n' "$BASHRC_MARKER"
287
+ printf '%s\n' 'if [ -n "${WSL_DISTRO_NAME:-}" ] || grep -qiE "microsoft|wsl" /proc/version 2>/dev/null; then'
288
+ printf ' [ -x "%s" ] && "%s" ensure >/dev/null 2>&1\n' "$INSTALLED_SCRIPT" "$INSTALLED_SCRIPT"
289
+ printf ' [ -f "%s" ] && . "%s"\n' "$ENV_FILE" "$ENV_FILE"
290
+ printf '%s\n' 'fi'
291
+ printf '%s\n' "$BASHRC_END"
292
+ } >>"$BASHRC"
293
+ }
294
+
295
+ remove_bashrc_hook() {
296
+ [ -f "$BASHRC" ] || return 0
297
+ if [ "$DRY_RUN" = "1" ]; then
298
+ printf ' [dry-run] remove bashrc hook from %s\n' "$BASHRC"
299
+ return 0
300
+ fi
301
+ awk -v b="$BASHRC_MARKER" -v e="$BASHRC_END" '
302
+ $0==b {skip=1; next}
303
+ skip && $0==e {skip=0; next}
304
+ !skip {print}
305
+ ' "$BASHRC" >"$BASHRC.tmp.$$" && mv "$BASHRC.tmp.$$" "$BASHRC"
306
+ }
307
+
308
+ cmd_install() {
309
+ is_wsl || {
310
+ echo "setup-tmpfs: not WSL — install is a no-op."
311
+ return 0
312
+ }
313
+ guard_ramdisk || return 1
314
+ run mkdir -p "$CONFIG_DIR" "$UNIT_DIR"
315
+ if [ "$DRY_RUN" != "1" ] && [ "$(readlink -f "$0")" != "$(readlink -f "$INSTALLED_SCRIPT" 2>/dev/null)" ]; then
316
+ cp -f "$0" "$INSTALLED_SCRIPT"
317
+ chmod 0755 "$INSTALLED_SCRIPT"
318
+ fi
319
+ write_unit
320
+ install_bashrc_hook
321
+ if have systemctl && systemctl --user show-environment >/dev/null 2>&1; then
322
+ run systemctl --user daemon-reload
323
+ run systemctl --user enable --now "$UNIT_NAME"
324
+ echo "setup-tmpfs: systemd --user unit '$UNIT_NAME' enabled."
325
+ else
326
+ echo "setup-tmpfs: systemd --user unavailable — ~/.bashrc hook is the persistence path."
327
+ fi
328
+ cmd_up
329
+ echo
330
+ echo "setup-tmpfs: persisted. New shells mount on demand and source $ENV_FILE."
331
+ }
332
+
333
+ cmd_down() {
334
+ is_wsl || {
335
+ echo "setup-tmpfs: not WSL — no-op."
336
+ return 0
337
+ }
338
+ if is_mounted; then
339
+ if run as_root umount "$RAMDISK"; then
340
+ echo "setup-tmpfs: unmounted $RAMDISK."
341
+ else
342
+ echo "setup-tmpfs: umount failed for $RAMDISK." >&2
343
+ fi
344
+ else
345
+ echo "setup-tmpfs: $RAMDISK not mounted (no-op)."
346
+ fi
347
+ if [ "$DRY_RUN" != "1" ]; then
348
+ rm -f "$ENV_FILE"
349
+ fi
350
+ echo "setup-tmpfs: new shells no longer receive tmpfs env; run 'eval \"\$(setup-tmpfs.sh env)\"' after removing stale vars if needed."
351
+ }
352
+
353
+ cmd_uninstall() {
354
+ if have systemctl; then
355
+ run systemctl --user disable --now "$UNIT_NAME" 2>/dev/null || true
356
+ fi
357
+ if [ "$DRY_RUN" != "1" ]; then
358
+ rm -f "$UNIT_DIR/$UNIT_NAME" "$ENV_FILE" "$INSTALLED_SCRIPT"
359
+ fi
360
+ remove_bashrc_hook
361
+ cmd_down
362
+ echo "setup-tmpfs: uninstalled."
363
+ }
364
+
365
+ case "$ACTION" in
366
+ help) usage ;;
367
+ up) cmd_up ;;
368
+ ensure) cmd_ensure ;;
369
+ env) env_lines ;;
370
+ status) cmd_status ;;
371
+ install) cmd_install ;;
372
+ down) cmd_down ;;
373
+ uninstall) cmd_uninstall ;;
374
+ esac