DonutBot/AGENTS.md

AGENTS

Guidance for future coding/automation agents working in this repository.

Goal

Maintain and improve a Mineflayer bot that automates a spawner and order loop with strict security shutdown behavior.

Primary Files

• index.js: main bot logic, event handlers, security flow, web API.
• web/index.html: local control panel UI.
• allowed_players.txt: allow-list consumed at startup.

Behavioral Guardrails

• Do not remove or weaken security triggers without explicit user request.
• On emergency path, preserve order:
  • stop loop
  • break/remove spawner
  • try ender chest stash
  • send webhook
  • quit
• Keep movement guard behavior intact unless asked to modify it.

Code Change Rules

• Prefer small, focused functions and reuse existing helpers.
• Keep logs user-readable (pushLog) and reserve noisy details for debugLog.
• Avoid introducing new dependencies unless needed.
• Keep constants near top-level config section.

Validation Checklist

After edits:

1. Run syntax check:
   • node --check index.js
2. Start bot locally:
   • node index.js
3. Verify HTTP server starts on :3008.
4. Verify no regressions in emergency shutdown sequence.

Common Pitfalls

• GUI slot interactions can desync if cursor item is not returned.
• Custom server GUIs may use non-standard item labels.
• window.inventoryStart may be missing; use fallback logic already in file.

Suggested Future Improvements

• Make ender chest search distance configurable via env.
• Add health/status endpoint with loop and security state.
• Add integration-safe dry-run mode for UI logic testing.