@john-ezra/openralph 0.1.1

package/container/Dockerfile

@@ -0,0 +1,58 @@
+FROM oven/bun:1.2.22-debian
+
+ARG OPENCODE_VERSION=1.15.13
+ARG CHROME_DEVTOOLS_MCP_VERSION=1.1.1
+ARG NODE_MAJOR=22
+
+ENV BUN_INSTALL=/usr/local
+ENV PATH=/opt/openralph/bin:/usr/local/bin:${PATH}
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates curl git gnupg \
+  && mkdir -p /etc/apt/keyrings \
+  && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+  && printf 'deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_%s.x nodistro main\n' "${NODE_MAJOR}" > /etc/apt/sources.list.d/nodesource.list \
+  && curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | gpg --dearmor -o /etc/apt/keyrings/google-linux.gpg \
+  && printf 'deb [arch=amd64 signed-by=/etc/apt/keyrings/google-linux.gpg] https://dl.google.com/linux/chrome/deb/ stable main\n' > /etc/apt/sources.list.d/google-chrome.list \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends \
+    build-essential \
+    fonts-dejavu \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    fonts-noto-core \
+    google-chrome-stable \
+    nodejs \
+    pkg-config \
+    python3 \
+    python3-pip \
+    python3-venv \
+    ripgrep \
+  && corepack enable \
+  && npm install --global chrome-devtools-mcp@${CHROME_DEVTOOLS_MCP_VERSION} \
+  && npm cache clean --force \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN bun install --global opencode-ai@${OPENCODE_VERSION}
+
+WORKDIR /opt/openralph
+
+COPY package.json bun.lock tsconfig.json ./
+COPY src ./src
+COPY container/bin ./bin
+COPY bin/openralph ./bin/openralph
+COPY AGENTS.md README.md PROMPT_build.md PROMPT_plan.md ./
+
+RUN bun install --production --frozen-lockfile
+
+RUN chmod +x /opt/openralph/bin/chrome-devtools-mcp-wrapper /opt/openralph/bin/openralph
+
+RUN useradd --create-home --shell /bin/bash opencode \
+  && mkdir -p /home/opencode/.local/share/opencode /workspace \
+  && chmod -R 0777 /home/opencode /workspace
+
+ENV HOME=/home/opencode
+
+USER opencode
+
+WORKDIR /workspace

package/container/bin/chrome-devtools-mcp-wrapper

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+profile="$(mktemp -d "${TMPDIR:-/tmp}/openralph-chrome-profile.XXXXXX")"
+log_file="${TMPDIR:-/tmp}/openralph-chrome-$$.log"
+chrome_pid=""
+port=""
+ready="false"
+
+cleanup() {
+  if [ -n "${chrome_pid}" ] && kill -0 "${chrome_pid}" 2>/dev/null; then
+    kill "${chrome_pid}" 2>/dev/null || true
+    wait "${chrome_pid}" 2>/dev/null || true
+  fi
+  rm -rf "${profile}" 2>/dev/null || true
+}
+
+trap cleanup EXIT INT TERM
+
+google-chrome \
+  --headless \
+  --disable-gpu \
+  --no-sandbox \
+  --remote-debugging-address=127.0.0.1 \
+  --remote-debugging-port=0 \
+  --user-data-dir="${profile}" \
+  --window-size=1440,1000 \
+  about:blank >"${log_file}" 2>&1 &
+chrome_pid=$!
+
+port_file="${profile}/DevToolsActivePort"
+attempts=0
+while [ "${attempts}" -lt 100 ]; do
+  attempts=$((attempts + 1))
+  if [ -s "${port_file}" ]; then
+    IFS= read -r port <"${port_file}"
+    if [ -n "${port}" ] && curl -fsS "http://127.0.0.1:${port}/json/version" >/dev/null 2>&1; then
+      ready="true"
+      break
+    fi
+  fi
+
+  if ! kill -0 "${chrome_pid}" 2>/dev/null; then
+    sed -n '1,120p' "${log_file}" >&2 || true
+    exit 1
+  fi
+
+  sleep 0.1
+done
+
+if [ "${ready}" != "true" ]; then
+  sed -n '1,120p' "${log_file}" >&2 || true
+  printf 'Chrome did not start remote debugging for Chrome DevTools MCP.\n' >&2
+  exit 1
+fi
+
+chrome-devtools-mcp --browser-url="http://127.0.0.1:${port}" "$@"

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@john-ezra/openralph",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Light opencode plugin for the Ralph workflow.",
+  "license": "MIT",
+  "main": "./src/plugin.ts",
+  "exports": {
+    ".": "./src/plugin.ts",
+    "./server": "./src/plugin.ts",
+    "./tui": "./src/tui.ts",
+    "./cli": "./src/cli.ts",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "openralph": "./bin/openralph"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "files": [
+    ".dockerignore",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "PROMPT_build.md",
+    "PROMPT_plan.md",
+    "bin/openralph",
+    "bun.lock",
+    "container/",
+    "src/",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "release:check": "bun src/release-check.ts",
+    "validate": "bun run typecheck && bun test && bun run release:check",
+    "prepublishOnly": "bun run validate"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.15.13",
+    "@types/bun": "latest",
+    "typescript": "latest"
+  }
+}

package/src/args.ts

@@ -0,0 +1,236 @@
+export type LoopPhase = "plan" | "build"
+
+export const DEFAULT_DOCKER_IMAGE = "openralph:local"
+
+const DOCKER_DOMAIN_COMPONENT = "[a-z0-9](?:[a-z0-9-]*[a-z0-9])?"
+const DOCKER_NAME_COMPONENT = "[a-z0-9]+(?:(?:[._-]+|__)[a-z0-9]+)*"
+const DOCKER_IMAGE_PATTERN = new RegExp(
+  `^(?=.{1,255}$)(?:${DOCKER_DOMAIN_COMPONENT}(?:\\.${DOCKER_DOMAIN_COMPONENT})*(?::[0-9]+)?/)?${DOCKER_NAME_COMPONENT}(?:/${DOCKER_NAME_COMPONENT})*(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?(?:@sha256:[A-Fa-f0-9]{64})?$`,
+)
+
+export interface OpenRalphOptions {
+  defineModel?: string
+  planModel?: string
+  buildModel?: string
+  docker?: DockerOptions
+}
+
+export interface DockerOptions {
+  enabled?: boolean
+  image?: string
+  maskEnv?: boolean
+}
+
+export interface ResolvedDockerOptions {
+  enabled: boolean
+  image: string
+  maskEnv: boolean
+}
+
+export interface ParsedLoopArgs {
+  maxIterations?: number
+  model?: string
+  push: boolean
+  noDocker: boolean
+}
+
+export function validateOptions(input: unknown): OpenRalphOptions {
+  if (input == null) return {}
+  if (typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("OpenRalph plugin options must be an object")
+  }
+
+  const options = input as Record<string, unknown>
+  return {
+    defineModel: readOptionalModel(options, "defineModel"),
+    planModel: readOptionalModel(options, "planModel"),
+    buildModel: readOptionalModel(options, "buildModel"),
+    docker: readDockerOptions(options),
+  }
+}
+
+export function parseLoopArgs(phase: LoopPhase, raw: string): ParsedLoopArgs {
+  const tokens = splitArgs(raw)
+  const parsed: ParsedLoopArgs = { push: false, noDocker: false }
+  let hasMax = false
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+
+    if (token === "--model") {
+      if (parsed.model) throw new Error("--model can only be provided once")
+      const value = tokens[index + 1]
+      if (!value || !isValidModelValue(value)) {
+        throw new Error("--model requires a provider/model value")
+      }
+      parsed.model = value
+      index += 1
+      continue
+    }
+
+    if (token === "--push") {
+      if (phase !== "build") throw new Error("--push is only supported for OpenRalph Build")
+      if (parsed.push) throw new Error("--push can only be provided once")
+      parsed.push = true
+      continue
+    }
+
+    if (token === "--no-docker") {
+      if (parsed.noDocker) throw new Error("--no-docker can only be provided once")
+      parsed.noDocker = true
+      continue
+    }
+
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown flag: ${token}`)
+    }
+
+    if (!isPositiveIntegerToken(token)) {
+      throw new Error(`Unexpected argument: ${token}`)
+    }
+    if (hasMax) throw new Error("max iterations can only be provided once")
+
+    const maxIterations = Number(token)
+    if (!Number.isSafeInteger(maxIterations) || maxIterations < 1) {
+      throw new Error("max iterations must be a positive integer")
+    }
+
+    parsed.maxIterations = maxIterations
+    hasMax = true
+  }
+
+  return parsed
+}
+
+export function formatLoopArgsForReplay(args: ParsedLoopArgs): string {
+  const tokens: string[] = []
+  if (args.maxIterations !== undefined) tokens.push(String(args.maxIterations))
+  if (args.model) tokens.push("--model", args.model)
+  if (args.push) tokens.push("--push")
+  return tokens.map(quoteArg).join(" ")
+}
+
+export function resolveDockerOptions(options: OpenRalphOptions): ResolvedDockerOptions {
+  return {
+    enabled: options.docker?.enabled ?? false,
+    image: options.docker?.image ?? DEFAULT_DOCKER_IMAGE,
+    maskEnv: options.docker?.maskEnv ?? true,
+  }
+}
+
+export function validateDockerImageReference(value: string, label = "docker.image"): string {
+  if (!DOCKER_IMAGE_PATTERN.test(value)) {
+    throw new Error(`${label} must be a valid Docker image reference`)
+  }
+  return value
+}
+
+export function resolveModel(
+  phase: LoopPhase,
+  args: ParsedLoopArgs,
+  options: OpenRalphOptions,
+): string | undefined {
+  if (args.model) return args.model
+  return phase === "plan" ? options.planModel : options.buildModel
+}
+
+function readOptionalString(options: Record<string, unknown>, key: "defineModel" | "planModel" | "buildModel" | "image"): string | undefined {
+  const value = options[key]
+  if (value == null) return undefined
+  if (typeof value !== "string") throw new Error(`${key} must be a string when provided`)
+  if (value.trim() === "") throw new Error(`${key} must not be empty when provided`)
+  return value
+}
+
+function readOptionalModel(options: Record<string, unknown>, key: "defineModel" | "planModel" | "buildModel"): string | undefined {
+  const value = readOptionalString(options, key)
+  if (value === undefined) return undefined
+  if (!isValidModelValue(value)) throw new Error(`${key} must be a provider/model value`)
+  return value
+}
+
+function readDockerOptions(options: Record<string, unknown>): DockerOptions | undefined {
+  const value = options.docker
+  if (value == null) return undefined
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("docker must be an object when provided")
+  }
+
+  const docker = value as Record<string, unknown>
+  const image = readOptionalString(docker, "image")
+  return {
+    enabled: readOptionalBoolean(docker, "enabled"),
+    image: image === undefined ? undefined : validateDockerImageReference(image),
+    maskEnv: readOptionalBoolean(docker, "maskEnv"),
+  }
+}
+
+function readOptionalBoolean(options: Record<string, unknown>, key: "enabled" | "maskEnv"): boolean | undefined {
+  const value = options[key]
+  if (value == null) return undefined
+  if (typeof value !== "boolean") throw new Error(`docker.${key} must be a boolean when provided`)
+  return value
+}
+
+function isPositiveIntegerToken(token: string): boolean {
+  return /^[0-9]+$/.test(token) && Number(token) > 0
+}
+
+function isValidModelValue(value: string): boolean {
+  const slash = value.indexOf("/")
+  if (slash <= 0 || slash === value.length - 1) return false
+  const provider = value.slice(0, slash)
+  const model = value.slice(slash + 1)
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(provider) && !model.startsWith("-") && !/[,\s]/.test(model)
+}
+
+function splitArgs(input: string): string[] {
+  const tokens: string[] = []
+  let current = ""
+  let quote: '"' | "'" | undefined
+  let escaping = false
+
+  for (const char of input.trim()) {
+    if (escaping) {
+      current += char
+      escaping = false
+      continue
+    }
+
+    if (char === "\\" && quote !== "'") {
+      escaping = true
+      continue
+    }
+
+    if (quote) {
+      if (char === quote) quote = undefined
+      else current += char
+      continue
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char
+      continue
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current)
+        current = ""
+      }
+      continue
+    }
+
+    current += char
+  }
+
+  if (escaping) current += "\\"
+  if (quote) throw new Error("Unterminated quoted argument")
+  if (current) tokens.push(current)
+  return tokens
+}
+
+function quoteArg(token: string): string {
+  if (/^[^\s"'\\]+$/.test(token)) return token
+  return `"${token.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+}

package/src/artifacts.ts

@@ -0,0 +1,183 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import type { LoopPhase } from "./args.ts"
+import type { CommandOutputEvent, CommandResult } from "./exec.ts"
+import { createTimestampId } from "./tags.ts"
+
+export interface CreateRunArtifactsInput {
+  projectRoot: string
+  phase: LoopPhase
+  rawArgs: string
+  date?: Date
+}
+
+export interface RunArtifacts {
+  phase: LoopPhase
+  timestampId: string
+  runName: string
+  dir: string
+  logPath: string
+}
+
+export interface IterationArtifacts {
+  index: number
+  jsonlPath: string
+  textPath: string
+  recordOutput: (event: CommandOutputEvent) => void
+  finish: (outcome: IterationOutcome) => Promise<void>
+}
+
+export interface IterationOutcome {
+  result?: Pick<CommandResult, "exitCode" | "signal">
+  status?: string
+  error?: unknown
+  sentinel?: string
+}
+
+export interface RunArtifactSummary {
+  phase: LoopPhase
+  status: string
+  message: string
+  launched: number
+  tagged: number
+  blocked: number
+  warnings: string[]
+}
+
+export async function createRunArtifacts(input: CreateRunArtifactsInput): Promise<RunArtifacts> {
+  const timestampId = createTimestampId(input.date)
+  const runsDir = join(input.projectRoot, "runs")
+  await mkdir(runsDir, { recursive: true })
+  await ensureRunsIgnored(runsDir)
+
+  const runName = createRunArtifactName(input.phase, timestampId)
+  const dir = join(runsDir, runName)
+  const logPath = join(dir, "ralph.log")
+  const run: RunArtifacts = { phase: input.phase, timestampId, runName, dir, logPath }
+
+  await mkdir(dir, { recursive: true })
+  await appendRunLog(run, [
+    `OpenRalph ${input.phase} run started`,
+    `time: ${(input.date ?? new Date()).toISOString()}`,
+    `project: ${input.projectRoot}`,
+    `args: ${input.rawArgs.trim() || "(default)"}`,
+    "",
+  ])
+
+  return run
+}
+
+export function createRunArtifactName(phase: LoopPhase, timestampId: string): string {
+  return `openralph-${phase}-${timestampId}`
+}
+
+export async function startIterationArtifacts(run: RunArtifacts, index: number, childArgs: string[]): Promise<IterationArtifacts> {
+  const iteration = formatIteration(index)
+  const jsonlPath = join(run.dir, `${iteration}.jsonl`)
+  const textPath = join(run.dir, `${iteration}.txt`)
+  let queue = Promise.resolve()
+  let writeError: unknown
+
+  await writeFile(jsonlPath, "")
+  await writeFile(textPath, "")
+  await appendRunLog(run, [
+    `${iteration} started`,
+    `time: ${new Date().toISOString()}`,
+    `command: opencode ${childArgs.map(quoteArg).join(" ")}`,
+    "",
+  ])
+
+  const enqueue = (write: () => Promise<void>) => {
+    queue = queue.then(write, write).catch((error) => {
+      writeError ??= error
+    })
+  }
+
+  return {
+    index,
+    jsonlPath,
+    textPath,
+    recordOutput: (event) => {
+      const entry = JSON.stringify({
+        time: new Date().toISOString(),
+        iteration: index,
+        type: "output",
+        stream: event.stream,
+        chunk: event.chunk,
+      })
+
+      enqueue(async () => {
+        await appendFile(jsonlPath, `${entry}\n`)
+        await appendFile(textPath, event.chunk)
+      })
+    },
+    finish: async (outcome) => {
+      await queue
+      if (writeError) throw writeError
+
+      await appendRunLog(run, [
+        `${iteration} finished`,
+        `time: ${new Date().toISOString()}`,
+        `status: ${formatOutcomeStatus(outcome)}`,
+        ...(outcome.sentinel ? [`sentinel: ${outcome.sentinel}`] : []),
+        "",
+      ])
+    },
+  }
+}
+
+export async function finishRunArtifacts(run: RunArtifacts, summary: RunArtifactSummary): Promise<void> {
+  await appendRunLog(run, [
+    `OpenRalph ${summary.phase} run finished`,
+    `time: ${new Date().toISOString()}`,
+    `status: ${summary.status}`,
+    `message: ${summary.message}`,
+    `launched iterations: ${summary.launched}`,
+    ...(summary.phase === "build" ? [`tagged iterations: ${summary.tagged}`, `blocked iterations: ${summary.blocked}`] : []),
+    ...summary.warnings,
+    "",
+  ])
+}
+
+async function ensureRunsIgnored(runsDir: string): Promise<void> {
+  const ignorePath = join(runsDir, ".gitignore")
+  const ignoreAll = "*"
+
+  try {
+    const current = await readFile(ignorePath, "utf8")
+    if (current.split(/\r?\n/).some((line) => line.trim() === ignoreAll)) return
+    await appendFile(ignorePath, `${current.endsWith("\n") || current.length === 0 ? "" : "\n"}${ignoreAll}\n`)
+  } catch (error) {
+    if (!isNotFound(error)) throw error
+    await writeFile(ignorePath, `${ignoreAll}\n`)
+  }
+}
+
+async function appendRunLog(run: RunArtifacts, lines: string[]): Promise<void> {
+  await appendFile(run.logPath, `${lines.join("\n")}\n`)
+}
+
+function formatIteration(index: number): string {
+  return `iter-${String(index).padStart(3, "0")}`
+}
+
+function formatOutcomeStatus(outcome: IterationOutcome): string {
+  if (outcome.error) return `error: ${formatError(outcome.error)}`
+  if (outcome.status) return outcome.status
+  if (!outcome.result) return "unknown"
+  if (outcome.result.exitCode === 0) return "exit 0"
+  return outcome.result.exitCode === null ? `signal ${outcome.result.signal ?? "unknown"}` : `exit ${outcome.result.exitCode}`
+}
+
+function quoteArg(arg: string): string {
+  if (/^[^\s"'\\]+$/.test(arg)) return arg
+  return `"${arg.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT"
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}