{"content":"# aux4/poller\n\nA versatile CLI polling utility for aux4 that repeatedly executes commands until they meet success conditions, fail criteria, or timeout.\n\nKey Features:\n\n- Poll any shell command until output matches expectations\n- Pattern matching with wildcards (*DONE*) and alternation (READY|COMPLETE)\n- Configurable intervals and timeouts\n- Fail-fast detection\n- Integration with aux4 workflows\n\n## Installation\n\n``bash\naux4 aux4 pkger install aux4/poller\n`\n\n## Quick Start\n\nWait for a service to be ready:\n\n`bash\naux4 poll --command=\"curl -s http://localhost:8080/health\" --expectation=\"OK\" --maxWait=60 --interval=5\n`\n\nThis polls every 5 seconds for up to 60 seconds, exiting successfully when the health endpoint returns \"OK\".\n\nSimple example:\n\n`bash\naux4 poll --command=\"echo READY\" --expectation=\"READY\" --maxWait=10 --interval=2\n`\n\nOutput:\n\n`\n[0 s] READY\nComplete\n`\n\n## Use Cases\n\n- **Service health checks** - Wait for services to become healthy before deploying\n- **Deployment monitoring** - Poll deployment status until complete\n- **File watching** - Monitor files or directories for specific content\n- **CI/CD pipelines** - Wait for build artifacts or test results\n- **Database migrations** - Check migration status before proceeding\n- **Container readiness** - Ensure containers are ready before integration tests\n\n## Command Reference\n\n### Parameters\n\n| Parameter | Description | Default | Required |\n| ------------- | ----------------------------------------------------------------- | ----------------- | -------- |\n| command | Shell command to execute on each poll | - | Yes |\n| expectation | Success pattern (exact, wildcard DONE, or alternation A\\|B) | - | Yes |\n| failValue | Pattern indicating immediate failure | __NEVER_MATCH__ | No |\n| maxWait | Maximum wait time in seconds | 900 | No |\n| interval | Polling interval in seconds | 30 | No |\n\n### Output Format\n\nEach poll prints:\n\n`\n[elapsed_seconds s] command_output\n`\n\nTerminal states print one of: Complete, Failed, or Timeout\n\nFor full command documentation see [aux4 poll](./commands/poll).\n\n## Pattern Matching\n\nThe expectation parameter supports flexible pattern matching:\n\n**Exact match:**\n\n`bash\naux4 poll --command=\"echo READY\" --expectation=\"READY\"\n`\n\n**Wildcard match:** Use * to match substrings\n\n`bash\naux4 poll --command=\"echo STATUS_DONE\" --expectation=\"*DONE*\"\n`\n\n**Alternation:** Use | to match multiple alternatives\n\n`bash\naux4 poll --command=\"echo TERMINATED\" --expectation=\"TERMINATED|SKIPPED\"\n`\n\n## Fail Detection\n\nSet failValue to exit immediately when a failure condition is detected:\n\n`bash\naux4 poll --command=\"kubectl get pod my-pod -o jsonpath='{.status.phase}'\" \\\n --expectation=\"Running\" \\\n --failValue=\"Failed|Error\" \\\n --maxWait=300 --interval=5\n`\n\nExit code 1 is returned when the fail value is matched.\n\n## Timeouts and Errors\n\n**Timeout:** If expectation is not met within maxWait seconds, the command prints Timeout and exits with code 1.\n\n**Command errors:** If the polled command fails (non-existent command, permission denied, etc.), ERROR is printed for that poll and polling continues until a terminal condition is reached.\n\n## Examples\n\n### Wait for HTTP endpoint\n\n`bash\naux4 poll \\\n --command=\"curl -s http://localhost:8080/health\" \\\n --expectation=\"healthy\" \\\n --maxWait=120 --interval=5\n`\n\n### Wait for Kubernetes pod\n\n`bash\naux4 poll \\\n --command=\"kubectl get pod my-app -o jsonpath='{.status.phase}'\" \\\n --expectation=\"Running\" \\\n --failValue=\"Failed|Error\" \\\n --maxWait=300 --interval=10\n`\n\n### Wait for file to contain specific text\n\n`bash\naux4 poll \\\n --command=\"cat /var/log/app.log\" \\\n --expectation=\"*Server started*\" \\\n --maxWait=60 --interval=2\n`\n\n### Poll with changing status (file-based)\n\n`bash\nSTATUS_FILE=\"/tmp/poll_status_$$\"\necho \"WAITING\" | tee \"$STATUS_FILE\" > /dev/null\n(sleep 3 && echo \"READY\" | tee \"$STATUS_FILE\" > /dev/null) &\naux4 poll --command=\"cat $STATUS_FILE\" --expectation=\"READY\" --maxWait=10 --interval=1\nrm -f \"$STATUS_FILE\"\n`\n\nOutput:\n\n`\n[0 s] WAITING\n[1 s] WAITING\n[2 s] WAITING\n[3 s] READY\nComplete\n`\n\n### Wait for Docker container\n\n`bash\naux4 poll \\\n --command=\"docker inspect -f '{{.State.Health.Status}}' my-container\" \\\n --expectation=\"healthy\" \\\n --failValue=\"unhealthy\" \\\n --maxWait=180 --interval=10\n`\n\n## Exit Codes\n\n| Exit Code | Meaning |\n| --------- | ---------------------------------------------- |\n| 0 | Success - expectation matched |\n| 1` | Failure - timeout reached or failValue matched |\n\n## License\n\nThis package is licensed under the Apache License, Version 2.0.\n\nSee LICENSE for details.\n"}