ralph-codex 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.3] - 2026-01-22
+- Added comprehensive CLI test suite with vitest, harness, and fixtures.
+- Added GitHub Actions CI for Node 18/20/22.
+- Guarded run completion to require all tasks checked off.
+
 ## [0.1.2] - 2026-01-22
 - Improved README with setup, defaults, Docker guidance, and troubleshooting.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-codex",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Codex-first Ralph-style planning and run loops",
   "repository": {
     "type": "git",
@@ -25,6 +25,10 @@
     "node": ">=18"
   },
   "packageManager": "npm@10.8.2",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "dependencies": {
     "cli-progress": "^3.12.0",
     "enquirer": "^2.4.1",
@@ -32,6 +36,9 @@
     "ora": "^5.4.1",
     "picocolors": "^1.0.0"
   },
+  "devDependencies": {
+    "vitest": "^1.6.0"
+  },
   "files": [
     "bin",
     "src",

package/src/commands/completion.js

@@ -130,9 +130,9 @@ _ralph_codex_completion_promise_list() {
 
 _ralph_codex() {
   local cur prev cmd
-  cur="\\${COMP_WORDS[COMP_CWORD]}"
-  prev="\\${COMP_WORDS[COMP_CWORD-1]}"
-  cmd="\\${COMP_WORDS[1]}"
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  cmd="\${COMP_WORDS[1]}"
 
   local commands="init plan run revise refine view reset docker completion help"
   local root_opts="--help -h --version -v"
@@ -174,6 +174,10 @@ _ralph_codex() {
           COMPREPLY=( $(compgen -W "$tasks" -- "$cur") $(compgen -f -- "$cur") )
           return 0
           ;;
+        --idea-file)
+          COMPREPLY=( $(compgen -f -- "$cur") )
+          return 0
+          ;;
         --sandbox)
           COMPREPLY=( $(compgen -W "read-only workspace-write danger-full-access" -- "$cur") )
           return 0
@@ -199,7 +203,7 @@ _ralph_codex() {
           return 0
           ;;
       esac
-      local opts="--output --tasks --max-iterations --config --model -m --profile -p --sandbox --no-sandbox --ask-for-approval --full-auto --reasoning --detect-success-criteria --no-detect-success-criteria --help -h"
+      local opts="--output --tasks --idea-file --stdin --max-iterations --config --model -m --profile -p --sandbox --no-sandbox --ask-for-approval --full-auto --reasoning --detect-success-criteria --no-detect-success-criteria --help -h"
       COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
       return 0
       ;;
@@ -525,6 +529,8 @@ _ralph_codex() {
           _arguments \\
             '--output[Write tasks to a custom file]:path:_ralph_codex_tasks' \\
             '--tasks[Write tasks to a custom file]:path:_ralph_codex_tasks' \\
+            '--idea-file[Read idea from a markdown file]:file:_files' \\
+            '--stdin[Read idea from stdin]' \\
             '--max-iterations[Max planning iterations]:number:' \\
             '--config[Path to ralph.config.yml]:file:_ralph_codex_configs' \\
             '(-m --model)'{-m,--model}'[Codex model]:model:_ralph_codex_models' \\
@@ -745,6 +751,8 @@ complete -c ralph-codex -n '__fish_seen_subcommand_from init' -l no-gitignore -d
 
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l output -r -a '(__ralph_codex_tasks)' -d 'Write tasks to a custom file'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l tasks -r -a '(__ralph_codex_tasks)' -d 'Write tasks to a custom file'
+complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l idea-file -r -a '(__fish_complete_path)' -d 'Read idea from a markdown file'
+complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l stdin -d 'Read idea from stdin'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l max-iterations -r -d 'Max planning iterations'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -l config -r -a '(__ralph_codex_configs)' -d 'Path to ralph.config.yml'
 complete -c ralph-codex -n '__fish_seen_subcommand_from plan' -s m -l model -r -a '(__ralph_codex_models)' -d 'Codex model'

package/src/commands/docker.js

@@ -8,6 +8,7 @@ const { Confirm } = enquirer;
 
 const root = process.cwd();
 const defaultConfigPath = path.join(root, "ralph.config.yml");
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 const argv = process.argv.slice(2);
 let configPath = null;
@@ -148,13 +149,13 @@ async function main() {
     process.exit(1);
   }
 
-  const confirm = new Confirm({
-    name: "confirm",
-    message: `Set docker.enabled=true and base_image=${baseImage}?`,
-    initial: true,
-  });
-
-  const approved = await confirm.run();
+  const approved = isTestMode
+    ? true
+    : await new Confirm({
+        name: "confirm",
+        message: `Set docker.enabled=true and base_image=${baseImage}?`,
+        initial: true,
+      }).run();
   if (!approved) {
     process.stdout.write("Aborted by user.\n");
     process.exit(1);

package/src/commands/init.js

@@ -7,6 +7,7 @@ const { AutoComplete, Confirm, Input, Toggle } = enquirer;
 
 const root = process.cwd();
 const argv = process.argv.slice(2);
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 let force = false;
 let configPath = null;
@@ -42,6 +43,7 @@ const targetPath = configPath
   : path.join(root, "ralph.config.yml");
 
 async function confirmOverwrite() {
+  if (isTestMode) return true;
   const confirm = new Confirm({
     name: "overwrite",
     message: `Overwrite existing ${path.relative(root, targetPath)}?`,
@@ -224,6 +226,16 @@ async function promptModelChoice() {
 }
 
 async function collectCodexConfig() {
+  if (isTestMode) {
+    return {
+      model: null,
+      profile: null,
+      sandbox: null,
+      ask_for_approval: null,
+      full_auto: false,
+      model_reasoning_effort: null,
+    };
+  }
   const model = await promptModelChoice();
   const profile = await promptOptionalInput(
     "Codex CLI profile (optional; leave blank to use Codex default)",
@@ -359,13 +371,15 @@ async function main() {
 
   const content = fs.readFileSync(templatePath, "utf8");
   const codexConfig = await collectCodexConfig();
-  const useDocker = await new Toggle({
-    name: "use_docker",
-    message: "Use Docker for the loop? (adds a docker section)",
-    enabled: "Yes",
-    disabled: "No",
-    initial: false,
-  }).run();
+  const useDocker = isTestMode
+    ? process.env.RALPH_TEST_USE_DOCKER === "1"
+    : await new Toggle({
+        name: "use_docker",
+        message: "Use Docker for the loop? (adds a docker section)",
+        enabled: "Yes",
+        disabled: "No",
+        initial: false,
+      }).run();
 
   let updated = content;
   updated = setYamlValue(updated, "model", codexConfig.model);

package/src/commands/plan.js

@@ -10,10 +10,13 @@ const { AutoComplete, Confirm, Editor, Input, MultiSelect } = enquirer;
 
 const root = process.cwd();
 const agentDir = path.join(root, ".ralph");
+const isTestMode = process.env.RALPH_TEST_MODE === "1";
 
 const argv = process.argv.slice(2);
 let maxIterations = "1";
 let tasksPath = "tasks.md";
+let ideaFile = null;
+let readStdin = false;
 let noSandbox = false;
 let sandbox = null;
 let fullAuto = false;
@@ -27,6 +30,7 @@ let autoDetectSuccessCriteria = null;
 let reasoningChoice;
 let showHelp = false;
 const ideaParts = [];
+let idea = "";
 
 for (let i = 0; i < argv.length; i += 1) {
   const arg = argv[i];
@@ -49,6 +53,20 @@ for (let i = 0; i < argv.length; i += 1) {
     i += 1;
     continue;
   }
+  if (arg === "--idea-file") {
+    const value = argv[i + 1];
+    if (!value || (value.startsWith("-") && value !== "-")) {
+      console.error("Missing --idea-file <path>.");
+      process.exit(1);
+    }
+    ideaFile = value;
+    i += 1;
+    continue;
+  }
+  if (arg === "--stdin") {
+    readStdin = true;
+    continue;
+  }
   if (arg === "--no-sandbox") {
     noSandbox = true;
     continue;
@@ -109,6 +127,8 @@ function printHelp() {
       `${colors.yellow("Options:")}\n` +
       `  ${colors.green("--output <path>")}                 Write tasks to a custom file (alias of --tasks)\n` +
       `  ${colors.green("--tasks <path>")}                  Write tasks to a custom file (default: tasks.md)\n` +
+      `  ${colors.green("--idea-file <path>")}              Read idea from a markdown file ('-' for stdin)\n` +
+      `  ${colors.green("--stdin")}                         Read idea from stdin (paste then Ctrl-D)\n` +
       `  ${colors.green("--max-iterations <n>")}            Max planning iterations (default: 1)\n` +
       `  ${colors.green("--config <path>")}                 Path to ralph.config.yml\n` +
       `  ${colors.green("--model <name>, -m")}              Codex model\n` +
@@ -129,16 +149,24 @@ if (showHelp) {
   process.exit(0);
 }
 
-const idea = ideaParts.join(" ").trim();
+const promptPath = path.join(agentDir, "ralph-plan-prompt.md");
 
-if (!idea) {
-  console.error(
-    'Usage: ralph-codex plan "<idea>" [--output <path>] [--tasks <path>] [--max-iterations <n>]',
-  );
-  process.exit(1);
+function readIdeaFromStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (_) {
+    return "";
+  }
 }
 
-const promptPath = path.join(agentDir, "ralph-plan-prompt.md");
+function readIdeaFromFile(filePath) {
+  const resolved = path.resolve(root, filePath);
+  if (!fs.existsSync(resolved)) {
+    console.error(`Missing idea file: ${filePath}`);
+    process.exit(1);
+  }
+  return fs.readFileSync(resolved, "utf8");
+}
 function loadConfig(configFilePath) {
   if (!configFilePath) return {};
   if (!fs.existsSync(configFilePath)) return {};
@@ -175,7 +203,7 @@ function resolveDockerConfig(config) {
       ? dockerConfig.pip_packages
       : [],
     useForPlan: Boolean(dockerConfig.use_for_plan),
-    tty: dockerConfig.tty ?? "auto",
+    tty: dockerConfig.tty ?? false,
   };
 }
 
@@ -862,6 +890,13 @@ async function selectSuccessCriteria(
   standardChoices,
   detectedChoices = []
 ) {
+  if (isTestMode) {
+    const safeDefaults =
+      defaultCriteria && defaultCriteria.length > 0
+        ? defaultCriteria
+        : standardChoices;
+    return { mode: "manual", criteria: safeDefaults || [] };
+  }
   const autoChoiceValue = "__auto__";
   const customChoiceValue = "__custom__";
   const defaults =
@@ -955,6 +990,7 @@ async function selectSuccessCriteria(
 }
 
 async function confirmPlan(tasksFile) {
+  if (isTestMode) return true;
   const content = fs.readFileSync(tasksFile, "utf8");
   process.stdout.write(`\n${colors.cyan("--- Proposed tasks.md ---")}\n\n`);
   process.stdout.write(content);
@@ -978,6 +1014,7 @@ async function readRevisionFeedback() {
 }
 
 async function confirmResetState(tasksFilePath, agentPath) {
+  if (isTestMode) return false;
   const hasTasks = fs.existsSync(tasksFilePath);
   const hasAgent = fs.existsSync(agentPath);
   if (!hasTasks && !hasAgent) return false;
@@ -1000,6 +1037,23 @@ function resetState(tasksFilePath, agentPath) {
 }
 
 async function main() {
+  const ideaFromArgs = ideaParts.join(" ").trim();
+  if (ideaFile) {
+    idea = ideaFile === "-" ? readIdeaFromStdin() : readIdeaFromFile(ideaFile);
+  } else if (readStdin || (!ideaFromArgs && !process.stdin.isTTY)) {
+    idea = readIdeaFromStdin();
+  } else {
+    idea = ideaFromArgs;
+  }
+
+  idea = String(idea || "").trim();
+  if (!idea) {
+    console.error(
+      'Usage: ralph-codex plan "<idea>" [--idea-file <path>] [--stdin] [--output <path>] [--tasks <path>] [--max-iterations <n>]',
+    );
+    process.exit(1);
+  }
+
   const resolvedConfigPath = configPath || path.join(root, "ralph.config.yml");
   const config = loadConfig(resolvedConfigPath);
   const codexConfig = config?.codex || {};

package/src/commands/revise.js

@@ -4,6 +4,12 @@ import path from "path";
 import enquirer from "enquirer";
 import yaml from "js-yaml";
 import { colors, createLogStyler, createSpinner } from "../ui/terminal.js";
+import {
+  diffCriteria,
+  diffTasks,
+  parseSuccessCriteria,
+  parseTasks,
+} from "../lib/tasks.js";
 
 const { AutoComplete, Confirm, Editor, Input } = enquirer;
 
@@ -223,91 +229,6 @@ async function readFeedback(promptMessage) {
   return input.run();
 }
 
-function parseTasks(content) {
-  const tasks = [];
-  const lines = content.split(/\r?\n/);
-  for (const line of lines) {
-    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
-    if (!match) continue;
-    const statusToken = match[1].toLowerCase();
-    const status =
-      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
-    tasks.push({
-      status,
-      text: match[2].trim(),
-      raw: line.trim(),
-    });
-  }
-  return tasks;
-}
-
-function normalizeTaskText(text) {
-  return String(text || "")
-    .toLowerCase()
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-function parseSuccessCriteria(content) {
-  const lines = content.split(/\r?\n/);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return [];
-  const items = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    if (/^#+\s+/.test(line)) break;
-    if (line.startsWith("- ")) items.push(line.slice(2).trim());
-    if (line.startsWith("* ")) items.push(line.slice(2).trim());
-  }
-  return items;
-}
-
-function diffTasks(oldTasks, newTasks) {
-  const oldSet = new Set(oldTasks.map((task) => normalizeTaskText(task.text)));
-  const newSet = new Set(newTasks.map((task) => normalizeTaskText(task.text)));
-
-  const additions = newTasks.filter(
-    (task) => !oldSet.has(normalizeTaskText(task.text))
-  );
-  const removals = oldTasks.filter(
-    (task) => !newSet.has(normalizeTaskText(task.text))
-  );
-
-  const modified = [];
-  const compareCount = Math.min(oldTasks.length, newTasks.length);
-  for (let i = 0; i < compareCount; i += 1) {
-    const before = oldTasks[i];
-    const after = newTasks[i];
-    if (
-      before.status !== after.status ||
-      normalizeTaskText(before.text) !== normalizeTaskText(after.text)
-    ) {
-      modified.push({
-        index: i + 1,
-        before,
-        after,
-      });
-    }
-  }
-
-  return { additions, removals, modified };
-}
-
-function diffCriteria(oldCriteria, newCriteria) {
-  const oldSet = new Set(oldCriteria);
-  const newSet = new Set(newCriteria);
-  const added = newCriteria.filter((item) => !oldSet.has(item));
-  const removed = oldCriteria.filter((item) => !newSet.has(item));
-  return { added, removed };
-}
-
 function renderChanges(changes) {
   if (changes.additions.length > 0) {
     process.stdout.write(`${colors.cyan("Proposed new tasks:")}\n`);

package/src/commands/run.js

@@ -278,7 +278,7 @@ function resolveDockerConfig(config) {
     fixAttempts: Number(dockerConfig.fix_attempts || 2),
     fixUseHost: dockerConfig.fix_use_host !== false,
     fixLog: dockerConfig.fix_log || ".ralph/docker-build.log",
-    tty: dockerConfig.tty ?? "auto",
+    tty: dockerConfig.tty ?? false,
     cleanup: dockerConfig.cleanup || "none",
   };
 }
@@ -1144,8 +1144,33 @@ async function main() {
     }
 
     if (hasCompletion(result.output)) {
-      completed = true;
-      break;
+      const completionProgress = getTaskProgress(tasksFile);
+      if (
+        completionProgress.total > 0 &&
+        completionProgress.completed === completionProgress.total
+      ) {
+        completed = true;
+        break;
+      }
+
+      const pendingCount = Math.max(
+        0,
+        completionProgress.total -
+          completionProgress.completed -
+          completionProgress.blocked,
+      );
+      const reason =
+        completionProgress.total === 0
+          ? "no tasks detected"
+          : `${pendingCount} pending, ${completionProgress.blocked} blocked`;
+      notes.push(
+        `Completion token received but tasks remain incomplete (${reason}).`,
+      );
+      process.stdout.write(
+        `${colors.yellow(
+          "Completion token received but tasks remain incomplete; continuing.",
+        )}\n`,
+      );
     }
 
     if (iterationTimedOut) {

package/src/commands/view.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
 import { colors } from "../ui/terminal.js";
+import { parseSuccessCriteria, parseTasks } from "../lib/tasks.js";
 
 const root = process.cwd();
 const argv = process.argv.slice(2);
@@ -156,21 +157,6 @@ function formatStatus(status) {
   return { raw, display: colors.gray(raw) };
 }
 
-function parseTasks(content) {
-  const tasks = [];
-  const lines = content.split(/\r?\n/);
-  let index = 0;
-  for (const line of lines) {
-    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
-    if (!match) continue;
-    index += 1;
-    const statusToken = match[1].toLowerCase();
-    const status =
-      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
-    tasks.push({ index, status, text: match[2].trim() });
-  }
-  return tasks;
-}
 
 function summarizeTasks(tasks) {
   const total = tasks.length;
@@ -186,26 +172,6 @@ function filterTasks(tasks, filter) {
   return tasks.filter((task) => task.status === filter);
 }
 
-function extractSuccessCriteria(content) {
-  const lines = content.split(/\r?\n/);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return [];
-  const items = [];
-  for (let i = start + 1; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (!line) continue;
-    if (/^#+\s+/.test(line)) break;
-    if (line.startsWith("- ")) items.push(line.slice(2).trim());
-    if (line.startsWith("* ")) items.push(line.slice(2).trim());
-  }
-  return items;
-}
 
 function getLastBlocker(logPath) {
   if (!fs.existsSync(logPath)) return "";
@@ -339,6 +305,7 @@ function getConfigRows(config) {
       use_for_plan: false,
       base_image: "node:20-bullseye",
       codex_install: "",
+      tty: false,
     },
     plan: {
       tasks_path: "tasks.md",
@@ -468,7 +435,7 @@ function renderOnce({ allowMissingTasks }) {
     const summary = summarizeTasks(allTasks);
     const filtered = filterTasks(allTasks, only);
     const sliced = limit > 0 ? filtered.slice(0, limit) : filtered;
-    const criteria = extractSuccessCriteria(tasksContent);
+    const criteria = parseSuccessCriteria(tasksContent);
 
     tasksData = {
       path: resolvedTasksPath,

package/src/lib/tasks.js

@@ -0,0 +1,97 @@
+function parseTasks(content) {
+  const tasks = [];
+  const lines = String(content || "").split(/\r?\n/);
+  let index = 0;
+
+  for (const line of lines) {
+    const match = line.match(/^\s*[-*]\s+\[([ x~])\]\s+(.*)$/);
+    if (!match) continue;
+    index += 1;
+    const statusToken = match[1].toLowerCase();
+    const status =
+      statusToken === "x" ? "done" : statusToken === "~" ? "blocked" : "pending";
+    tasks.push({
+      index,
+      status,
+      text: match[2].trim(),
+      raw: line.trim(),
+    });
+  }
+
+  return tasks;
+}
+
+function parseSuccessCriteria(content) {
+  const lines = String(content || "").split(/\r?\n/);
+  let start = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^(#+\s*)?success criteria\b/i.test(lines[i].trim())) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return [];
+  const items = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    if (/^#+\s+/.test(line)) break;
+    if (line.startsWith("- ")) items.push(line.slice(2).trim());
+    if (line.startsWith("* ")) items.push(line.slice(2).trim());
+  }
+  return items;
+}
+
+function normalizeTaskText(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function diffTasks(oldTasks, newTasks) {
+  const oldSet = new Set(oldTasks.map((task) => normalizeTaskText(task.text)));
+  const newSet = new Set(newTasks.map((task) => normalizeTaskText(task.text)));
+
+  const additions = newTasks.filter(
+    (task) => !oldSet.has(normalizeTaskText(task.text))
+  );
+  const removals = oldTasks.filter(
+    (task) => !newSet.has(normalizeTaskText(task.text))
+  );
+
+  const modified = [];
+  const compareCount = Math.min(oldTasks.length, newTasks.length);
+  for (let i = 0; i < compareCount; i += 1) {
+    const before = oldTasks[i];
+    const after = newTasks[i];
+    if (
+      before.status !== after.status ||
+      normalizeTaskText(before.text) !== normalizeTaskText(after.text)
+    ) {
+      modified.push({
+        index: i + 1,
+        before,
+        after,
+      });
+    }
+  }
+
+  return { additions, removals, modified };
+}
+
+function diffCriteria(oldCriteria, newCriteria) {
+  const oldSet = new Set(oldCriteria);
+  const newSet = new Set(newCriteria);
+  const added = newCriteria.filter((item) => !oldSet.has(item));
+  const removed = oldCriteria.filter((item) => !newSet.has(item));
+  return { added, removed };
+}
+
+export {
+  diffCriteria,
+  diffTasks,
+  normalizeTaskText,
+  parseSuccessCriteria,
+  parseTasks,
+};

package/templates/ralph.config.yml

@@ -18,7 +18,7 @@ docker:
   codex_install: npm install -g @openai/codex
   codex_home: .ralph/codex # Writable codex home inside the repo
   mount_codex_config: true # Seed codex_home from host ~/.codex if empty
-  tty: auto # auto | true | false
+  tty: false # auto | true | false
   pass_env:
     - OPENAI_API_KEY
   apt_packages: