@john-ezra/openralph 0.1.1 → 0.1.2

package/AGENTS.md

@@ -8,7 +8,7 @@ OpenRalph is a light opencode plugin that implements the Ralph workflow from Cla
 - Preserve Ralph's central mechanism: one fresh top-level opencode run per loop iteration.
 - Use disk files as persistent state: `specs/*`, `AGENTS.md`, `IMPLEMENTATION_PLAN.md`, `PROMPT_plan.md`, and `PROMPT_build.md`; use `runs/*` only for durable local run artifacts and audit/debug output.
 - Do not turn OpenRalph into a general sandbox or orchestration platform.
-- Safety strategy is the user's responsibility. OpenRalph provides only lightweight guardrails and optional Dockerized loop execution.
+- Safety strategy is the user's responsibility. OpenRalph provides only lightweight guardrails and default Dockerized loop execution with explicit host-mode opt-out.
 - Avoid complex modes, safety matrices, Podman requirements, or heavy process abstractions.
 
 ## Ralph Phases
@@ -38,7 +38,7 @@ The server plugin should inject these commands only for authorized loop child pr
 - Never use `--continue` for child runs.
 - Always pass `--dir <project-root>` to child runs.
 - Plan/build child runs use `--dangerously-skip-permissions`.
-- When Docker mode is enabled, host plan/build commands launch one Docker container and the full loop runs inside it.
+- Docker mode is enabled by default; host plan/build commands launch one Docker container and the full loop runs inside it unless `--no-docker` or `docker.enabled: false` is used.
 - Docker mode runs the container `openralph plan` or `openralph build` CLI entrypoint, never public prompt command replay.
 - Container loops set `OPENRALPH_IN_DOCKER=1` and require token-backed Docker attestation before running.
 - Docker mode disables project OpenCode config and injects config that loads only image-bundled OpenRalph.
@@ -71,9 +71,9 @@ Plugin options:
 
 ```json
 {
-  "defineModel": "heavy-model",
-  "planModel": "cheap-model",
-  "buildModel": "cheap-model",
+  "defineModel": "provider/heavy-model",
+  "planModel": "provider/cheap-model",
+  "buildModel": "provider/cheap-model",
   "docker": {
     "enabled": true,
     "image": "openralph:local",
@@ -112,7 +112,7 @@ Use tags only after a successful build iteration with a new commit and clean wor
 
 ## Safety Posture
 
-OpenRalph v1 supports optional Dockerized execution for Plan and Build.
+OpenRalph v1 defaults to Dockerized execution for Plan and Build, with explicit host-mode opt-out.
 
 Rationale:
 

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to OpenRalph will be documented in this file.
 
 The format is based on Keep a Changelog, and this project uses semantic versioning.
 
+## [Unreleased]
+
+## [0.1.2] - 2026-06-04
+
+### Changed
+
+- Docker mode is now the default for Plan and Build; host mode requires `--no-docker` or `docker.enabled: false`.
+- Missing default Docker images now fail before container launch with build and host-mode opt-out guidance.
+
+### Fixed
+
+- Normalized the CLI bin path so npm preserves the `openralph` executable during publish.
+
+## [0.1.1] - 2026-06-04
+
+### Fixed
+
+- Kept opencode plugin type definitions out of runtime dependencies.
+
 ## [0.1.0] - 2026-06-04
 
 ### Added

package/README.md

@@ -16,8 +16,9 @@ The normal install path is opencode's built-in plugin installer:
 2. Run `Install plugin` from the command palette/plugins UI.
 3. Enter `@john-ezra/openralph` at the `npm package name` prompt.
 4. Leave scope as `local` for a project install, or press `Tab` to toggle to `global`.
-5. Restart opencode if needed.
-6. Run `/ralph`.
+5. Build the default Docker image with `bunx @john-ezra/openralph docker build`.
+6. Restart opencode if needed.
+7. Run `/ralph`.
 
 CLI equivalent for non-TUI users:
 
@@ -80,11 +81,11 @@ TUI plugin in `tui.json`:
 
 All model options are optional. Command `--model` values override plugin options. If no model is resolved, OpenRalph omits `--model` and lets opencode use its default.
 
-Server and TUI plugin options use the same shape. Direct CLI/headless runs can pass the same launcher options through `OPENRALPH_OPTIONS_JSON`; without that env var, `openralph plan/build` uses default options, including Docker disabled.
+Server and TUI plugin options use the same shape. Direct CLI/headless runs can pass the same launcher options through `OPENRALPH_OPTIONS_JSON`; without that env var, `openralph plan/build` uses default options, including Docker enabled with image `openralph:local` and `.env*` masking enabled.
 
 ## Docker Mode
 
-Docker mode is optional. When `docker.enabled` is true, Plan and Build from `/ralph`, `openralph plan`, and `openralph build` launch one Docker container from the host and run the full Ralph loop inside it through the container `openralph` CLI entrypoint. Docker uses `--pull=never`, so build the default image locally before running Dockerized loops.
+Docker mode is the default for Plan and Build. Plan and Build from `/ralph`, `openralph plan`, and `openralph build` launch one Docker container from the host and run the full Ralph loop inside it through the container `openralph` CLI entrypoint. Docker uses `--pull=never`, so build the default image locally before running Dockerized loops. To intentionally run on the host, pass `--no-docker` for that run or set `"docker": { "enabled": false }` in plugin options.
 
 If you installed through opencode's plugin installer, the package bin may not be available on your shell `PATH`. Build the image with direct package execution:
 
@@ -134,7 +135,7 @@ Restart opencode after installing or changing `opencode.json`, `tui.json`, or pl
 
 OpenRalph Plan and Build child iterations run `opencode run --dangerously-skip-permissions`. Treat the agent's actions as untrusted.
 
-Host mode runs those child iterations directly on your machine with inherited environment variables, host filesystem access, and unrestricted network access. Direct CLI/headless runs use host mode unless Docker is enabled through plugin options or `OPENRALPH_OPTIONS_JSON`.
+Host mode runs those child iterations directly on your machine with inherited environment variables, host filesystem access, and unrestricted network access. Use `--no-docker` or `"docker": { "enabled": false }` only when you intentionally want that behavior.
 
 Docker mode reduces host filesystem blast radius, but it is not a formal sandbox. The agent can read the mounted repository and the read-only mounted OpenCode auth file, and Docker mode does not restrict network egress. The `.env*` masking feature only replaces files whose basename starts with `.env`, except `.env.example`, `.env.sample`, `.env.template`, and `.env.dist`; it does not mask other in-repo secrets such as `.npmrc`, private keys, cloud credentials, or service-account JSON.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@john-ezra/openralph",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Light opencode plugin for the Ralph workflow.",
   "license": "MIT",
@@ -13,7 +13,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "openralph": "./bin/openralph"
+    "openralph": "bin/openralph"
   },
   "engines": {
     "bun": ">=1.2.0"

package/src/args.ts

@@ -112,7 +112,7 @@ export function formatLoopArgsForReplay(args: ParsedLoopArgs): string {
 
 export function resolveDockerOptions(options: OpenRalphOptions): ResolvedDockerOptions {
   return {
-    enabled: options.docker?.enabled ?? false,
+    enabled: options.docker?.enabled ?? true,
     image: options.docker?.image ?? DEFAULT_DOCKER_IMAGE,
     maskEnv: options.docker?.maskEnv ?? true,
   }

package/src/docker.ts

@@ -187,6 +187,15 @@ export async function buildLocalDockerImage(input: BuildLocalDockerImageInput =
   }).result
 }
 
+export async function dockerImageExists(image: string, cwd = process.cwd()): Promise<boolean> {
+  const result = await startCommand("docker", ["image", "inspect", image], {
+    cwd,
+    streamOutput: false,
+    captureOutput: false,
+  }).result
+  return result.exitCode === 0
+}
+
 export function buildDockerArgs(input: BuildDockerArgsInput): string[] {
   const configContent = buildContainerConfig(input.options, input.docker, input.imagePluginPath)
   const args = [

package/src/launcher.ts

@@ -1,5 +1,5 @@
 import { formatLoopArgsForReplay, parseLoopArgs, resolveDockerOptions, validateOptions, type LoopPhase, type OpenRalphOptions, type ParsedLoopArgs } from "./args.ts"
-import { CONTAINER_WORKSPACE, runDockerLoop } from "./docker.ts"
+import { CONTAINER_WORKSPACE, dockerImageExists as defaultDockerImageExists, runDockerLoop } from "./docker.ts"
 import { commandExists as defaultCommandExists, type CommandOutputEvent, type CommandResult } from "./exec.ts"
 import { requireGitContext } from "./git.ts"
 import { formatSummary, runLoop, type LoopSummary } from "./loop.ts"
@@ -32,6 +32,7 @@ export interface RunLauncherDeps {
   runDockerLoop?: typeof runDockerLoop
   runLoop?: typeof runLoop
   commandExists?: typeof defaultCommandExists
+  dockerImageExists?: typeof defaultDockerImageExists
   trust?: TrustDeps
 }
 
@@ -55,6 +56,10 @@ export async function runOpenRalphLauncher(input: RunLauncherInput, deps: RunLau
   await preflightCommands(mode, deps.commandExists ?? defaultCommandExists)
 
   if (mode === "docker-host-launch") {
+    const docker = resolveDockerOptions(input.options)
+    const imageExists = await (deps.dockerImageExists ?? defaultDockerImageExists)(docker.image, input.cwd)
+    if (!imageExists) throw new Error(formatMissingDockerImage(input.phase, parsed, docker.image))
+
     const git = await (deps.requireGitContext ?? requireGitContext)(input.cwd)
     const result = await (deps.runDockerLoop ?? runDockerLoop)({
       phase: input.phase,
@@ -192,7 +197,7 @@ function formatMissingCommands(commands: string[]): string {
   const hints: Record<string, string> = {
     git: "Install git and ensure it is on PATH.",
     opencode: "Install opencode (https://opencode.ai) and ensure it is on PATH.",
-    docker: "Install Docker and ensure the docker executable is on PATH.",
+    docker: "Install Docker and ensure the docker executable is on PATH, or run this loop with --no-docker to opt into host mode.",
   }
 
   return [
@@ -201,9 +206,22 @@ function formatMissingCommands(commands: string[]): string {
   ].join("\n")
 }
 
+function formatMissingDockerImage(phase: LoopPhase, parsed: ParsedLoopArgs, image: string): string {
+  return [
+    `Docker image ${image} was not found.`,
+    "",
+    "OpenRalph defaults to Docker mode for safer loop execution and Docker runs with --pull=never.",
+    "Build the local image with:",
+    "  bunx @john-ezra/openralph docker build",
+    "",
+    "If you intentionally want to run this loop on the host, rerun with:",
+    `  ${noDockerCommand(phase, parsed)}`,
+  ].join("\n")
+}
+
 function noDockerCommand(phase: LoopPhase, parsed: ParsedLoopArgs): string {
   const replayArgs = formatLoopArgsForReplay(parsed)
-  return `/ralph-${phase}${replayArgs ? ` ${replayArgs}` : ""} --no-docker`
+  return `openralph ${phase}${replayArgs ? ` ${replayArgs}` : ""} --no-docker`
 }
 
 function commandOutput(result: CommandResult): string {