@accidentally-awesome-labs/opencode-bestest 0.4.3

package/payload/templates/RUNBOOK.md

@@ -0,0 +1,24 @@
+# RUNBOOK — <project name>
+<!-- Stack-agnostic checklist: fill every section for the stack SPEC §5 derived.
+     'n/a' requires a one-line reason. Rehearsed means actually executed once. -->
+
+## Deploy
+<!-- exact commands/pipeline; config + secrets source; migration order -->
+
+## Rollback (REHEARSED — paste the rehearsal transcript, not the theory)
+<!-- steps + how long it took + what state is lost/kept -->
+
+## Dependency timeouts
+<!-- | dependency | timeout | retry policy | behavior when down | — audit every external call -->
+
+## Observability floor
+<!-- named logs (where), metrics (which), alerts (threshold + who is paged) -->
+
+## Security smoke (negative paths)
+<!-- auth-required route without auth; malformed input; injection probe on entry points; secrets not in logs -->
+
+## Restore drill
+<!-- backup source -> restore command -> verified-by; last drilled date -->
+
+## Spend
+<!-- ceiling per month | alert threshold | where the alert lands -->

package/payload/templates/SPEC.md

@@ -0,0 +1,35 @@
+# SPEC — <project name>
+<!-- Frozen at P2: sha256 recorded in .bestest/LOCKS; the lock-guard hook then
+     blocks edits. Amendments: D-ID in DECISIONS.md -> Bash gate step -> re-hash. -->
+
+## 1. Premise Verdict
+<!-- one paragraph: the real problem, for whom, why now, why not an existing tool.
+     Every factual claim tagged [user] / [cited:URL] / [assumed]. -->
+
+## 2. Requirements — EARS acceptance criteria
+<!-- one sentence each, numbered R-N.M, observable behavior only:
+R-1.1 WHEN <trigger> [WHILE <state>] THE SYSTEM SHALL <observable behavior>. -->
+
+## 3. Anti-goals (≥3)
+<!-- things this project deliberately will NOT do, each with the failure it prevents -->
+
+## 4. Out of scope
+<!-- non-empty. Each line: item — reason — Include/Defer/Cut/Hold. Deferred items = parking lot. -->
+
+## 5. Stack (derived, cited)
+<!-- | layer | choice | why | evidence | — every row [cited:URL] from P1 research -->
+
+## 6. Assets
+<!-- data, images, fixtures, credentials the build needs; who/what produces each -->
+
+## 7. Risks
+<!-- from pre-mortem + vague-answer probes; each with likelihood, blast, tripwire -->
+
+## 8. Doneness function
+<!-- the falsifiable test of "this project succeeded" — used verbatim at P5 go/no-go -->
+
+## 9. Autonomy Contract
+- **PROCEED silently:** weight<4 decisions; fixes inside the active card's `files:` blast radius.
+- **INTERRUPT the user:** weight≥4; spec contradiction; unachievable criterion; docs-vs-reality mismatch; security concern; out-of-scope diff.
+- **GATED (never without explicit user approval):** deploy, spend money, destructive ops, credentials, publishing.
+- Out-of-blast-radius discoveries → DISCOVERED.md. Never fixed silently, never dropped.

package/payload/templates/STATE.md

@@ -0,0 +1,20 @@
+# STATE — <project name>
+<!-- Overwritten at every gate/task boundary. Hard cap 60 lines: the SessionStart
+     hook injects lines 1-60 verbatim. Machine-read fields below must keep their
+     exact key names. -->
+
+phase: P0            # P0 interrogate | P1 research | P2 spec | P3 plan | P4 build | P5 ship | done
+milestone: v1        # archived to .bestest/milestones/<milestone>/ at rollover
+stage: 0             # interrogation stage 0-6, or task id T-## during P4
+spec_hash: none      # sha256 recorded in .bestest/LOCKS at P2 freeze
+card: none           # project-relative path to the active task card (lock-guard reads this)
+
+## Now
+- next action: <one imperative sentence — what the very next tool call should do>
+- blocked on: none
+
+## Gates passed
+<!-- append one line per gate: date · gate · evidence pointer -->
+
+## Open interrupts / escalations
+<!-- anything awaiting the user; empty means full autonomy within the contract -->

package/payload/templates/UAT.md

@@ -0,0 +1,10 @@
+# UAT — one question per acceptance criterion
+<!-- Filled at P5. One row per R-N.M from SPEC §2. The user answers the question;
+     'pass' requires their yes plus the evidence pointer. -->
+
+| R-ID | question to user (restates the EARS criterion as a check) | evidence | result |
+|------|-----------------------------------------------------------|----------|--------|
+| R-1.1 | | | pending |
+
+## Doneness function verdict
+<!-- SPEC §8 evaluated verbatim: PASS / FAIL + why -->

package/payload/templates/report.md

@@ -0,0 +1,15 @@
+# Report — T-00
+<!-- Written by the builder subagent; the orchestrator trusts nothing in it
+     until verify commands are re-run and the diff-scope gate passes. -->
+
+## Claim → evidence
+<!-- | claim | evidence (command + output excerpt, diff hunk, or [cited:URL]) | -->
+
+## Verify output
+<!-- paste actual output of each card verify: command -->
+
+## FRICTION
+<!-- REQUIRED. Failed commands, backtracking, wrong card assumptions, environment surprises — or exactly 'None'. The orchestrator patches remaining cards + LESSONS.md from this before the next dispatch. -->
+
+## Discovered
+<!-- out-of-blast-radius items appended to DISCOVERED.md this task, or 'None' -->

package/payload/templates/task-card.md

@@ -0,0 +1,24 @@
+---
+id: T-00
+title: <imperative, one clause — needing "and" means split it>
+status: todo            # todo | doing | done
+files: src/example.py   # comma-separated blast radius; diffs outside = revert or INTERRUPT
+requirements: R-1.1     # comma-separated R-IDs this card advances
+weight: 3               # irreversibility x scope; >=4 -> full adversarial review
+complexity: 3           # 1 + 2/extra file + 2/verify cmd + 3 if title needs "and" + 2/new interface; >6 split
+blocked_by: none        # comma-separated T-IDs
+may_edit_tests: false   # true only on test-author cards (lock-guard enforces)
+verify:
+  - <command that proves this card done — orchestrator re-runs it>
+---
+
+## Context (zero-context contract)
+<!-- Everything a fresh subagent needs: exact paths, function signatures, data shapes,
+     relevant D-IDs, LESSONS to read first. No placeholders, no "see above". -->
+
+## Steps
+<!-- numbered, concrete; TDD: failing test exists before implementation -->
+
+## Done means
+<!-- observable end state, restated from the R-IDs, plus: report written to
+     .bestest/reports/T-00.md; commit carries trailer 'Bestest-Req: R-1.1' -->

package/src/guards.ts

@@ -0,0 +1,80 @@
+// tool.execute.before/after -> the shared bash hook scripts.
+// Contract (same one tests/bench.sh proves): stdin {"tool_input":{...}},
+// exit 0 = pass, exit 2 = block with the model-facing reason on stderr.
+// guard/lock CANNOT fail open: any failure to run them throws (blocks).
+// syntax-check is advisory by design: only a real exit-2 throws.
+import { hookScript } from "./resolve"
+
+export const WRITE_TOOLS = ["write", "edit", "apply_patch"] as const
+
+type Envelope = { tool_input: Record<string, string> }
+
+function envelopeFor(tool: string, args: Record<string, unknown>): Envelope | null {
+  if (tool === "bash" && typeof args.command === "string") {
+    return { tool_input: { command: args.command } }
+  }
+  if (tool === "apply_patch" && typeof args.patchText === "string") {
+    // lock-guard/syntax-check parse '*** Add/Update/Delete File:' headers from .command
+    return { tool_input: { command: args.patchText } }
+  }
+  if ((tool === "write" || tool === "edit") && typeof args.filePath === "string") {
+    return { tool_input: { file_path: args.filePath } }
+  }
+  return null
+}
+
+async function runHook(script: string, envelope: Envelope, projectRoot: string) {
+  const proc = Bun.spawn(["bash", hookScript(script)], {
+    stdin: new TextEncoder().encode(JSON.stringify(envelope)),
+    cwd: projectRoot,
+    env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+    stdout: "ignore",
+    stderr: "pipe",
+  })
+  const stderr = await new Response(proc.stderr).text()
+  const code = await proc.exited
+  return { code, stderr }
+}
+
+export function makeGuards(projectRoot: string, bashOk: boolean) {
+  const enforce = async (script: string, envelope: Envelope) => {
+    if (!bashOk) {
+      throw new Error(
+        `bestest ${script}: bash not found — guards cannot run and will not fail open. Install bash (Git Bash on Windows) or remove opencode-bestest from opencode.json.`,
+      )
+    }
+    let res
+    try {
+      res = await runHook(script, envelope, projectRoot)
+    } catch (e) {
+      throw new Error(`bestest ${script}: failed to run (${e}) — refusing to fail open.`)
+    }
+    if (res.code === 2) throw new Error(res.stderr.trim() || `bestest ${script}: blocked`)
+    if (res.code !== 0) throw new Error(`bestest ${script}: exited ${res.code} — refusing to fail open.`)
+  }
+
+  return {
+    before: async (tool: string, args: Record<string, unknown>) => {
+      if (tool === "bash") {
+        const env = envelopeFor(tool, args)
+        if (env) await enforce("guard.sh", env)
+      } else if ((WRITE_TOOLS as readonly string[]).includes(tool)) {
+        const env = envelopeFor(tool, args)
+        if (env) await enforce("lock-guard.sh", env)
+      }
+    },
+    after: async (tool: string, args: Record<string, unknown>) => {
+      if (!(WRITE_TOOLS as readonly string[]).includes(tool) || !bashOk) return
+      const env = envelopeFor(tool, args)
+      if (!env) return
+      let res
+      try {
+        res = await runHook("syntax-check.sh", env, projectRoot)
+      } catch {
+        return // advisory gate: a failure to RUN the checker never blocks
+      }
+      // exit 2 = genuine syntax failure -> feed back to the model (write already persisted)
+      if (res.code === 2) throw new Error(res.stderr.trim() || "bestest syntax-check: failed")
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { makeGuards } from "./guards"
+import { makeSession } from "./session"
+
+export const BestestPlugin: Plugin = async ({ directory, worktree }) => {
+  const projectRoot = worktree ?? directory
+  const bashOk = Bun.which("bash") !== null
+  if (!bashOk) {
+    console.error(
+      "opencode-bestest: bash not found — guard/lock/drift enforcement is DISABLED-CLOSED (guarded tools will be refused). Install bash (Git Bash on Windows).",
+    )
+  }
+  const guards = makeGuards(projectRoot, bashOk)
+  const session = makeSession(projectRoot, bashOk)
+  await session.regen() // server start == session boundary for the digest
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      await guards.before(input.tool, output.args ?? {})
+    },
+    "tool.execute.after": async (input, _output) => {
+      await guards.after(input.tool, (input as { args?: Record<string, unknown> }).args ?? {})
+    },
+    event: async ({ event }) => {
+      await session.onEvent(event.type, event)
+    },
+    // Layer 2: re-inject state across compaction (experimental API, feature-detected
+    // by opencode itself — unknown hook keys are simply never called).
+    "experimental.session.compacting": async (_input, output) => {
+      const d = await session.digest()
+      if (d) output.context.push(d)
+    },
+  }
+}

package/src/resolve.ts

@@ -0,0 +1,22 @@
+// Locates the shared bash sources. Two tiers:
+//   1. payload/ next to src/ — the published npm tarball (prepack.sh snapshot)
+//   2. the repo root two levels up — running from a clone (dev, gauntlet)
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const srcDir = dirname(fileURLToPath(import.meta.url))
+
+export function sourceRoot(): string {
+  const payload = join(srcDir, "..", "payload")
+  if (existsSync(join(payload, "hooks", "guard.sh"))) return payload
+  const repo = join(srcDir, "..", "..", "..")
+  if (existsSync(join(repo, "hooks", "guard.sh"))) return repo
+  throw new Error(
+    "opencode-bestest: cannot locate bundled hook scripts (payload/ missing and not in a repo clone) — reinstall the package",
+  )
+}
+
+export function hookScript(name: string): string {
+  return join(sourceRoot(), "hooks", name)
+}

package/src/session.ts

@@ -0,0 +1,57 @@
+// Session-state machinery. OpenCode has no SessionStart stdout injection, so:
+//   digest file .bestest/.context.md  <- session-start.sh start   (regenerated
+//     at plugin init, session.created, session.idle, .bestest edits)
+//   opencode.json instructions: [".bestest/.context.md"]  <- passive injection
+//   session.idle -> session-start.sh stop  (drift snapshot), then regen digest
+//   experimental.session.compacting -> push the digest (feature-detected layer 2)
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import { hookScript } from "./resolve"
+
+async function runSessionScript(mode: "start" | "stop", projectRoot: string): Promise<string> {
+  const proc = Bun.spawn(["bash", hookScript("session-start.sh"), mode], {
+    cwd: projectRoot,
+    env: { ...process.env, CLAUDE_PROJECT_DIR: projectRoot },
+    stdout: "pipe",
+    stderr: "ignore",
+  })
+  const out = await new Response(proc.stdout).text()
+  await proc.exited
+  return out
+}
+
+export function makeSession(projectRoot: string, bashOk: boolean) {
+  const digestPath = join(projectRoot, ".bestest", ".context.md")
+  const isBestest = () => existsSync(join(projectRoot, ".bestest"))
+
+  const regen = async () => {
+    if (!bashOk || !isBestest()) return
+    const out = await runSessionScript("start", projectRoot)
+    if (out.trim().length > 0) await Bun.write(digestPath, out)
+  }
+
+  const snapshot = async () => {
+    if (!bashOk || !isBestest()) return
+    await runSessionScript("stop", projectRoot)
+    await regen() // snapshot changes drift state; keep the digest current
+  }
+
+  const digest = async (): Promise<string | null> => {
+    try {
+      return existsSync(digestPath) ? await Bun.file(digestPath).text() : null
+    } catch {
+      return null
+    }
+  }
+
+  const onEvent = async (type: string, raw: unknown) => {
+    if (type === "session.created") await regen()
+    else if (type === "session.idle") await snapshot()
+    else if (type === "file.edited") {
+      const s = JSON.stringify(raw ?? "")
+      if (s.includes(".bestest/STATE.md") || s.includes(".bestest/LOCKS")) await regen()
+    }
+  }
+
+  return { regen, snapshot, digest, onEvent }
+}