opencode-waitfor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zjc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# opencode-waitfor
+
+A zero-dependency opencode plugin that adds a `wait_for` tool to poll HTTP, TCP, or shell command targets until they are ready or a timeout elapses.
+
+Replaces the manual `for i in $(seq 1 40); do sleep 3; curl ...; done` polling loops that agents write by hand.
+
+## Install
+
+Add `"opencode-waitfor"` to the `plugin` array in your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-waitfor"]
+}
+```
+
+Then restart opencode.
+
+## Tool: `wait_for`
+
+Poll a target until it meets a readiness condition or the timeout expires. The condition type is **inferred from `target`**:
+
+| `target` pattern | Condition type |
+|---|---|
+| Contains `://` (e.g. `http://localhost:3000`) | HTTP |
+| Bare `host:port` (e.g. `localhost:5432`) | TCP |
+| Anything else | Shell command |
+
+### Args
+
+| Arg | Type | Default | Description |
+|---|---|---|---|
+| `target` | string | *(required)* | URL (with scheme), host:port, or shell command |
+| `timeout` | number | `60` | Total seconds to wait |
+| `interval` | number | `2` | Seconds between attempts |
+| `expect.status` | number \| number[] | any 2xx | HTTP only — acceptable status code(s) |
+| `expect.json_match` | `{path: value}` | — | HTTP only — dot-path → expected value (compared as strings) |
+| `expect.exit_code` | number | `0` | Command only — required exit code |
+
+### Result
+
+Returns `{ title, output, metadata }` with `metadata.{ success, type, target, elapsed_seconds, attempts, last, reason? }`.
+
+On timeout, `metadata.success` is `false`, `metadata.reason` is `"timeout"`, and `metadata.last` contains the final probe's state (last HTTP status + body, last command exit + output, etc.) — enough to diagnose the failure without re-probing.
+
+Invalid inputs (e.g. `interval > timeout`, `expect.exit_code` on an HTTP target) throw an error immediately.
+
+## Examples
+
+### Wait for a dev server
+
+```
+wait_for http://localhost:3000
+```
+
+### Deploy verify — health endpoint version check
+
+After deploying commit `abc123`:
+
+```
+wait_for http://host/api/health
+  timeout 30 interval 3
+  expect { json_match: { status: ok, version: abc123 } }
+```
+
+### Wait for a database port
+
+```
+wait_for localhost:5432
+  timeout 10
+```
+
+### Wait for Docker container health
+
+```
+wait_for 'docker inspect -f "{{.State.Health.Status}}" pg | grep -q healthy'
+  timeout 60 interval 5
+```
+
+## Sharp edges
+
+- **HTTP targets MUST include the scheme** (`http://` or `https://`). A schemeless URL like `localhost:3000/health` is treated as a shell command (and will fail to run).
+- **`json_match` compares stringified values only** — no deep equality, numeric comparison, or regex. Exact string match.
+- **`command` runs through the shell** and inherits the agent's environment/cwd. The caller is responsible for command safety.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "opencode-waitfor",
+  "version": "0.1.0",
+  "description": "opencode plugin: a wait_for tool that polls HTTP/TCP/command targets until ready or timeout.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": { ".": "./src/index.ts" },
+  "files": ["src", "README.md", "LICENSE"],
+  "keywords": ["opencode", "opencode-plugin", "wait", "healthcheck", "poll"],
+  "license": "MIT",
+  "peerDependencies": { "@opencode-ai/plugin": "*", "zod": "*" },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.18",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "zod": "^3.23.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/dotpath.ts

@@ -0,0 +1,16 @@
+export function resolve(obj: unknown, path: string): unknown {
+  const segments = path.split(".")
+  let current: unknown = obj
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(seg)) return undefined
+      current = current[Number(seg)]
+    } else if (typeof current === "object") {
+      current = (current as Record<string, unknown>)[seg]
+    } else {
+      return undefined
+    }
+  }
+  return current
+}

package/src/format.ts

@@ -0,0 +1,29 @@
+import type { WaitType } from "./infer"
+import type { PollResult } from "./poll"
+
+export function formatResult(input: {
+  type: WaitType
+  target: string
+  poll: PollResult
+}): { title: string; output: string; metadata: Record<string, unknown> } {
+  const { type, target, poll } = input
+  const elapsed_seconds = Math.round((poll.elapsedMs / 1000) * 100) / 100
+  const metadata: Record<string, unknown> = {
+    success: poll.success,
+    type,
+    target,
+    elapsed_seconds,
+    attempts: poll.attempts,
+    last: poll.last,
+  }
+  if (!poll.success) metadata.reason = "timeout"
+
+  const title = poll.success
+    ? `${type} target ready after ${elapsed_seconds}s`
+    : `${type} target NOT ready (timed out after ${elapsed_seconds}s)`
+  const output = poll.success
+    ? `Target "${target}" became ready after ${poll.attempts} attempt(s), ${elapsed_seconds}s.\nLast observation: ${JSON.stringify(poll.last)}`
+    : `Timed out waiting for "${target}" after ${poll.attempts} attempt(s), ${elapsed_seconds}s.\nLast observation: ${JSON.stringify(poll.last)}`
+
+  return { title, output, metadata }
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+import { type Plugin, tool } from "@opencode-ai/plugin"
+import { formatResult } from "./format"
+import { poll, type Probe } from "./poll"
+import { commandProbe } from "./probes/command"
+import { httpProbe } from "./probes/http"
+import { tcpProbe } from "./probes/tcp"
+import { validate, type WaitArgs } from "./validate"
+
+const MAX_BYTES = 2048
+
+const WaitForPlugin: Plugin = async ({ directory }) => {
+  return {
+    tool: {
+      wait_for: tool({
+        description:
+          "Poll a target until it is ready or a timeout elapses. " +
+          "The condition type is inferred from `target`: a URL with scheme (http:// or https://) is polled over HTTP; " +
+          "a bare host:port is polled as a TCP connection; anything else is run as a shell command. " +
+          "Use this instead of writing manual sleep/curl loops. Returns success or a timeout result with the last observed state. " +
+          "Examples: wait_for a dev server (http://localhost:3000), a deployed /health version (target http://host/health, expect.json_match {status: ok, version: <sha>}), " +
+          "a database port (localhost:5432), or docker health (target: docker inspect -f '{{.State.Health.Status}}' pg | grep -q healthy).",
+        args: {
+          target: tool.schema
+            .string()
+            .describe("URL (with scheme), host:port, or a shell command."),
+          timeout: tool.schema
+            .number()
+            .positive()
+            .optional()
+            .describe("Total seconds to wait. Default 60."),
+          interval: tool.schema
+            .number()
+            .positive()
+            .optional()
+            .describe("Seconds between attempts. Default 2."),
+          expect: tool.schema
+            .object({
+              status: tool.schema
+                .union([tool.schema.number(), tool.schema.array(tool.schema.number())])
+                .optional()
+                .describe("HTTP only: acceptable status code(s). Default any 2xx."),
+              json_match: tool.schema
+                .record(tool.schema.string(), tool.schema.string())
+                .optional()
+                .describe("HTTP only: dot-path -> expected value (compared as strings)."),
+              exit_code: tool.schema
+                .number()
+                .optional()
+                .describe("Command only: required exit code. Default 0."),
+            })
+            .optional(),
+        },
+        async execute(args, context) {
+          const { type, timeoutMs, intervalMs } = validate(args as WaitArgs)
+          const perAttemptMs = Math.min(intervalMs, 10000)
+
+          let probe: Probe
+          if (type === "http") {
+            probe = httpProbe(args.target, args.expect, { perAttemptMs, maxBytes: MAX_BYTES })
+          } else if (type === "tcp") {
+            const m = args.target.match(/^([\w.-]+):(\d+)$/)!
+            probe = tcpProbe(m[1], Number(m[2]), { perAttemptMs })
+          } else {
+            probe = commandProbe(args.target, args.expect, {
+              cwd: context.directory ?? directory,
+              maxBytes: MAX_BYTES,
+              timeoutMs,
+            })
+          }
+
+          const result = await poll({ probe, timeoutMs, intervalMs, signal: context.abort })
+          return formatResult({ type, target: args.target, poll: result })
+        },
+      }),
+    },
+  }
+}
+
+export default WaitForPlugin

package/src/infer.ts

@@ -0,0 +1,7 @@
+export type WaitType = "http" | "tcp" | "command"
+
+export function inferType(target: string): WaitType {
+  if (target.includes("://")) return "http"
+  if (/^[\w.-]+:\d+$/.test(target)) return "tcp"
+  return "command"
+}

package/src/poll.ts

@@ -0,0 +1,66 @@
+export interface ProbeResult {
+  ok: boolean
+  snapshot: Record<string, unknown>
+}
+export type Probe = (signal: AbortSignal) => Promise<ProbeResult>
+export interface PollResult {
+  success: boolean
+  attempts: number
+  elapsedMs: number
+  last: Record<string, unknown>
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((res) => {
+    if (signal.aborted) return res()
+    const onAbort = () => {
+      clearTimeout(t)
+      signal.removeEventListener("abort", onAbort)
+      res()
+    }
+    const t = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort)
+      res()
+    }, ms)
+    signal.addEventListener("abort", onAbort)
+  })
+}
+
+export async function poll(opts: {
+  probe: Probe
+  timeoutMs: number
+  intervalMs: number
+  signal?: AbortSignal
+}): Promise<PollResult> {
+  const { probe, timeoutMs, intervalMs, signal: external } = opts
+  const controller = new AbortController()
+  const onExternalAbort = () => controller.abort()
+  if (external) {
+    if (external.aborted) controller.abort()
+    else external.addEventListener("abort", onExternalAbort)
+  }
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  const start = Date.now()
+  let attempts = 0
+  let last: Record<string, unknown> = {}
+
+  try {
+    while (true) {
+      if (controller.signal.aborted) break
+      attempts++
+      const result = await probe(controller.signal)
+      last = result.snapshot
+      if (result.ok) {
+        return { success: true, attempts, elapsedMs: Date.now() - start, last }
+      }
+      if (controller.signal.aborted) break
+      const elapsed = Date.now() - start
+      if (elapsed + intervalMs > timeoutMs) break
+      await sleep(intervalMs, controller.signal)
+    }
+    return { success: false, attempts, elapsedMs: Date.now() - start, last }
+  } finally {
+    clearTimeout(timer)
+    if (external) external.removeEventListener("abort", onExternalAbort)
+  }
+}

package/src/probes/command.ts

@@ -0,0 +1,40 @@
+import { exec } from "node:child_process"
+import type { Probe, ProbeResult } from "../poll"
+
+export interface CommandExpect {
+  exit_code?: number
+}
+
+export function commandProbe(
+  command: string,
+  expect: CommandExpect | undefined,
+  opts: { cwd: string; maxBytes: number; timeoutMs: number },
+): Probe {
+  const wanted = expect?.exit_code ?? 0
+  return (signal: AbortSignal): Promise<ProbeResult> => {
+    return new Promise<ProbeResult>((res) => {
+      const child = exec(
+        command,
+        { cwd: opts.cwd, timeout: opts.timeoutMs, maxBuffer: 1024 * 1024 },
+        (err, stdout, stderr) => {
+          signal.removeEventListener("abort", onAbort)
+          const code =
+            err && typeof (err as { code?: unknown }).code === "number"
+              ? (err as { code: number }).code
+              : err
+                ? 1
+                : 0
+          const snapshot = {
+            exitCode: code,
+            stdoutPreview: String(stdout).slice(0, opts.maxBytes),
+            stderrPreview: String(stderr).slice(0, opts.maxBytes),
+          }
+          res({ ok: code === wanted, snapshot })
+        },
+      )
+      const onAbort = () => child.kill()
+      if (signal.aborted) child.kill()
+      else signal.addEventListener("abort", onAbort)
+    })
+  }
+}

package/src/probes/http.ts

@@ -0,0 +1,53 @@
+import type { Probe, ProbeResult } from "../poll"
+import { resolve } from "../dotpath"
+
+export interface HttpExpect {
+  status?: number | number[]
+  json_match?: Record<string, string>
+}
+
+function statusOk(status: number, expect: HttpExpect | undefined): boolean {
+  if (!expect || expect.status === undefined) return status >= 200 && status < 300
+  const wanted = Array.isArray(expect.status) ? expect.status : [expect.status]
+  return wanted.includes(status)
+}
+
+export function httpProbe(
+  target: string,
+  expect: HttpExpect | undefined,
+  opts: { perAttemptMs: number; maxBytes: number },
+): Probe {
+  return async (signal: AbortSignal): Promise<ProbeResult> => {
+    const ac = new AbortController()
+    const onAbort = () => ac.abort()
+    if (signal.aborted) ac.abort()
+    else signal.addEventListener("abort", onAbort)
+    const timer = setTimeout(() => ac.abort(), opts.perAttemptMs)
+    try {
+      const res = await fetch(target, { signal: ac.signal })
+      const text = await res.text()
+      const bodyPreview = text.slice(0, opts.maxBytes)
+      const snapshot: Record<string, unknown> = { status: res.status, bodyPreview }
+      if (!statusOk(res.status, expect)) return { ok: false, snapshot }
+      if (expect?.json_match) {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(text)
+        } catch {
+          return { ok: false, snapshot: { ...snapshot, error: "response not JSON" } }
+        }
+        for (const [path, want] of Object.entries(expect.json_match)) {
+          if (String(resolve(parsed, path)) !== String(want)) {
+            return { ok: false, snapshot }
+          }
+        }
+      }
+      return { ok: true, snapshot }
+    } catch (e) {
+      return { ok: false, snapshot: { error: (e as Error).message } }
+    } finally {
+      clearTimeout(timer)
+      signal.removeEventListener("abort", onAbort)
+    }
+  }
+}

package/src/probes/tcp.ts

@@ -0,0 +1,35 @@
+import { Socket } from "node:net"
+import type { Probe, ProbeResult } from "../poll"
+
+export function tcpProbe(
+  host: string,
+  port: number,
+  opts: { perAttemptMs: number },
+): Probe {
+  return (signal: AbortSignal): Promise<ProbeResult> => {
+    return new Promise<ProbeResult>((res) => {
+      const socket = new Socket()
+      let settled = false
+      const done = (result: ProbeResult) => {
+        if (settled) return
+        settled = true
+        clearTimeout(timer)
+        signal.removeEventListener("abort", onAbort)
+        socket.destroy()
+        res(result)
+      }
+      const onAbort = () => done({ ok: false, snapshot: { connected: false, error: "aborted" } })
+      const timer = setTimeout(
+        () => done({ ok: false, snapshot: { connected: false, error: "timeout" } }),
+        opts.perAttemptMs,
+      )
+      if (signal.aborted) return onAbort()
+      signal.addEventListener("abort", onAbort)
+      socket.once("connect", () => done({ ok: true, snapshot: { connected: true } }))
+      socket.once("error", (e) =>
+        done({ ok: false, snapshot: { connected: false, error: (e as Error).message } }),
+      )
+      socket.connect(port, host)
+    })
+  }
+}

package/src/validate.ts

@@ -0,0 +1,36 @@
+import { inferType, type WaitType } from "./infer"
+
+export interface WaitArgs {
+  target: string
+  timeout?: number
+  interval?: number
+  expect?: {
+    status?: number | number[]
+    json_match?: Record<string, string>
+    exit_code?: number
+  }
+}
+
+export function validate(args: WaitArgs): {
+  type: WaitType
+  timeoutMs: number
+  intervalMs: number
+} {
+  const timeout = args.timeout ?? 60
+  const interval = args.interval ?? 2
+  if (timeout <= 0) throw new Error("wait_for: timeout must be > 0 seconds")
+  if (interval <= 0) throw new Error("wait_for: interval must be > 0 seconds")
+  if (interval > timeout) throw new Error("wait_for: interval must be <= timeout")
+
+  const type = inferType(args.target)
+  const e = args.expect
+  if (e) {
+    if (e.exit_code !== undefined && type !== "command") {
+      throw new Error(`wait_for: expect.exit_code is only valid for command targets (inferred: ${type})`)
+    }
+    if ((e.status !== undefined || e.json_match !== undefined) && type !== "http") {
+      throw new Error(`wait_for: expect.status/json_match are only valid for http targets (inferred: ${type})`)
+    }
+  }
+  return { type, timeoutMs: timeout * 1000, intervalMs: interval * 1000 }
+}