ralph-codex 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-01-21
+- Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ralph Codex
+
+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,216 @@
+# ralph-codex
+
+Codex-first Ralph-style planning and run loops.
+
+## What it does
+
+- Turns an idea into a task plan (`tasks.md`) with one round of questions.
+- Runs the loop until completion, keeping state in `.ralph/`.
+- Optional Docker mode for reproducible runs.
+- Colorized Codex output in TTY for easier scanning (disable with `NO_COLOR=1`).
+
+## Requirements
+
+- Node.js >= 18
+- Codex CLI installed and authenticated (`codex` available in PATH)
+- Docker (optional, only for Docker mode)
+
+## Install
+
+```bash
+npm install -g ralph-codex
+# or
+npx ralph-codex --help
+```
+
+## Quick start
+
+```bash
+ralph-codex init
+ralph-codex plan "Add screenshot flow for /demo" --output tasks.md
+ralph-codex run
+ralph-codex revise "Improve the flow after QA"
+ralph-codex view
+ralph-codex reset
+```
+
+## Command reference
+
+Use `--help` with any command to see its available options.
+
+### init
+
+Create `ralph.config.yml` and add `.ralph` to `.gitignore`.
+Init is interactive and prompts for Codex settings and Docker usage.
+
+```bash
+ralph-codex init [--force] [--config <path>] [--no-gitignore]
+```
+
+### plan
+
+Generate `tasks.md` with one round of questions.
+
+```bash
+ralph-codex plan "<idea>" [--output <path>] [--tasks <path>] [--max-iterations <n>]
+```
+
+Common options:
+
+- `--output <path>` write tasks to a custom file (alias of `--tasks`).
+- `--config <path>` use a custom config file.
+- `--model <name>` or `-m` set the Codex model.
+- `--profile <name>` or `-p` use a Codex CLI profile.
+- `--sandbox <mode>` set sandbox mode.
+- `--ask-for-approval <mode>` set approval policy.
+- `--full-auto` use workspace-write + on-request.
+- `--reasoning [effort]` override reasoning effort; omit value to pick from a list (defaults to medium).
+- `--detect-success-criteria` add auto-detected checks to the success list.
+- `--no-detect-success-criteria` disable auto-detect (overrides config).
+- In the interactive checklist, choose `Ask Codex to choose` to let Codex derive success criteria.
+
+### run
+
+Execute the loop until completion.
+
+```bash
+ralph-codex run [--input <path>] [--tasks <path>] [--max-iterations <n>]
+```
+
+Useful options:
+
+- `--input <path>` read tasks from a custom file (alias of `--tasks`).
+- `--quiet` reduce output.
+- `--max-iteration-seconds <n>` soft per-iteration limit (stop after current loop).
+- `--max-total-seconds <n>` hard total limit (kills in-flight loop).
+- `--completion-promise <text>` change the completion marker.
+- `--stop-on-error` stop on the first error.
+- `--no-tail` disable log/scratchpad tailing.
+- `--reasoning [effort]` override reasoning effort; omit value to pick from a list (defaults to medium).
+
+### revise
+
+Add new tasks from feedback without changing existing tasks (alias: `refine`).
+
+```bash
+ralph-codex revise "<feedback>" [--tasks <path>] [--run]
+```
+
+Useful options:
+
+- `--tasks <path>` point to a custom tasks file.
+- `--config <path>` use a custom config file.
+- `--reasoning [effort]` override reasoning effort; omit value to pick from a list.
+- `--run` run after approving the changes.
+
+### view
+
+Show tasks, success criteria, and config summaries.
+
+```bash
+ralph-codex view [section] [--format table|list|json]
+```
+
+Sections:
+
+- `tasks` shows task status counts and list.
+- `criteria` shows the success criteria list.
+- `config` shows effective config values.
+
+Useful options:
+
+- `--tasks <path>` point to a custom tasks file.
+- `--config <path>` use a custom config file.
+- `--format <format>` table | list | json (default: table).
+- `--only <filter>` pending | blocked | done (tasks only).
+- `--limit <n>` limit task rows (0 = no limit).
+- `--watch`, `-w` watch for changes and refresh the view.
+
+### reset
+
+Reset all tasks in `tasks.md` to `[ ]`.
+Uses `plan.tasks_path` or `run.tasks_path` when set, unless overridden.
+
+```bash
+ralph-codex reset [--tasks <path>] [--config <path>]
+```
+
+### docker
+
+Ask Codex for a base image and update Docker config.
+
+```bash
+ralph-codex docker [--config <path>]
+```
+
+## Configuration
+
+The CLI reads `ralph.config.yml` in the project root. Use `--config <path>` to point elsewhere.
+Run `ralph-codex init` to generate the full config. Example of the most common fields:
+
+```yaml
+version: 1
+
+codex:
+  model: gpt-5-codex
+  profile: default
+  sandbox: workspace-write
+  ask_for_approval: on-request
+  model_reasoning_effort: medium # or null to use Codex default
+
+docker:
+  enabled: false
+  use_for_plan: false
+  base_image: node:20-bullseye
+  codex_install: npm install -g @openai/codex
+
+plan:
+  auto_detect_success_criteria: false
+  tasks_path: tasks.md
+
+run:
+  max_iterations: 15
+  max_iteration_seconds: null
+  max_total_seconds: null
+```
+
+Codex settings quick guide:
+- `profile` selects a Codex CLI profile (default `null`, uses Codex default).
+- `sandbox` sets permission mode (`read-only`, `workspace-write`, `danger-full-access`; default `null`).
+- `ask_for_approval` controls prompt behavior (`untrusted`, `on-failure`, `on-request`, `never`; default `null`).
+- `full_auto` is a convenience preset for `workspace-write` + `on-request` (default `false`).
+- `model_reasoning_effort` chooses reasoning level (`low`, `medium`, `high`, `xhigh`; default `null`).
+
+Enable `plan.auto_detect_success_criteria` to add detected checks based on repo files.
+
+CLI flags always override config values.
+
+## Docker mode
+
+1. Run `ralph-codex docker` to pick a base image.
+2. Set `docker.codex_install` so Codex is available inside the container.
+3. Run `ralph-codex plan` and `ralph-codex run` as usual. Enable `docker.use_for_plan`
+   if you want planning to happen inside Docker as well.
+
+`Dockerfile.ralph` is generated automatically when Docker is enabled.
+
+## Files created
+
+- `ralph.config.yml` default config file.
+- `tasks.md` planning output (configurable).
+- `.ralph/` run state, summaries, and logs.
+
+## Output styling
+
+Codex output is colorized when stdout is a TTY. Plan uses spinners and run shows a task
+progress bar when interactive. Set `NO_COLOR=1` to disable color styling.
+
+## Troubleshooting
+
+- `codex: command not found` -> install Codex CLI and ensure it is in PATH.
+- Docker errors -> start Docker Desktop/Colima and retry.
+- Plan/run fail to read config -> verify `ralph.config.yml` path or pass `--config`.
+
+## License
+
+MIT

package/bin/ralph-codex.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+import { colors } from "../src/ui/terminal.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const args = argv.slice(1);
+
+const showHelp = () => {
+  process.stdout.write(
+    `\n${colors.cyan("ralph-codex <command> [options]")}\n\n` +
+      `${colors.yellow("Commands:")}\n` +
+      `  ${colors.green("init")}        Create ralph.config.yml and update .gitignore\n` +
+      `  ${colors.green("plan")}        Generate tasks.md with a single round of questions\n` +
+      `  ${colors.green("run")}         Execute the loop until completion\n` +
+      `  ${colors.green("revise")}      Add new tasks from feedback (alias: refine)\n` +
+      `  ${colors.green("view")}        Show tasks, criteria, and config summaries\n` +
+      `  ${colors.green("reset")}       Reset all tasks in tasks.md to [ ]\n` +
+      `  ${colors.green("docker")}      Pick a Docker base image via Codex and update config\n\n` +
+      `${colors.yellow("Examples:")}\n` +
+      `  ralph-codex init\n` +
+      `  ralph-codex plan "Add screenshot flow"\n` +
+      `  ralph-codex run --max-iterations 15\n` +
+      `  ralph-codex revise "Improve copy"\n` +
+      `  ralph-codex view tasks --only pending\n` +
+      `  ralph-codex reset\n\n` +
+      `${colors.gray('Tip: run "ralph-codex <command> --help" for command options.')}\n\n`
+  );
+};
+
+if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+  showHelp();
+  process.exit(0);
+}
+
+if (cmd === "-v" || cmd === "--version") {
+  const pkg = require(path.join(__dirname, "..", "package.json"));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+const scriptPath = path.join(__dirname, "..", "src", "commands", `${cmd}.js`);
+const result = spawnSync(process.execPath, [scriptPath, ...args], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+
+process.exit(result.status ?? 0);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ralph-codex",
+  "version": "0.1.0",
+  "description": "Codex-first Ralph-style planning and run loops",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vhmartinezm/ralph-codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/vhmartinezm/ralph-codex/issues"
+  },
+  "homepage": "https://github.com/vhmartinezm/ralph-codex#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ralph-codex": "bin/ralph-codex.js"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "npm@10.8.2",
+  "dependencies": {
+    "cli-progress": "^3.12.0",
+    "enquirer": "^2.4.1",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1",
+    "picocolors": "^1.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "codex",
+    "ralph",
+    "cli",
+    "automation"
+  ]
+}

package/src/commands/docker.js

@@ -0,0 +1,174 @@
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import enquirer from "enquirer";
+import yaml from "js-yaml";
+
+const { Confirm } = enquirer;
+
+const root = process.cwd();
+const defaultConfigPath = path.join(root, "ralph.config.yml");
+
+const argv = process.argv.slice(2);
+let configPath = null;
+
+for (let i = 0; i < argv.length; i += 1) {
+  const arg = argv[i];
+  if (arg === "--config") {
+    configPath = argv[i + 1];
+    i += 1;
+    continue;
+  }
+}
+
+const resolvedConfigPath = configPath || defaultConfigPath;
+
+function loadConfig(configFilePath) {
+  if (!fs.existsSync(configFilePath)) return {};
+  try {
+    const content = fs.readFileSync(configFilePath, "utf8");
+    return yaml.load(content) || {};
+  } catch (error) {
+    console.error(
+      `Failed to read config at ${configFilePath}: ${error?.message || error}`
+    );
+    process.exit(1);
+  }
+}
+
+function parseBaseImage(output) {
+  const match = output.match(/BASE_IMAGE:\s*([^\r\n]+)/i);
+  if (!match) return null;
+  const line = match[1].trim();
+  const image = line.split(/\s+/)[0].replace(/[`"'(),.]+$/g, "");
+  return image || null;
+}
+
+function updateDockerConfigText(content, baseImage) {
+  const lines = content.split(/\r?\n/);
+  let dockerStart = lines.findIndex((line) => /^docker:\s*$/.test(line));
+  const topLevel = (line) => /^[A-Za-z_][A-Za-z0-9_-]*:\s*$/.test(line);
+
+  if (dockerStart === -1) {
+    lines.push(
+      "",
+      "docker:",
+      "  enabled: true",
+      `  base_image: ${baseImage}`
+    );
+    return lines.join("\n");
+  }
+
+  let end = lines.length;
+  for (let i = dockerStart + 1; i < lines.length; i += 1) {
+    if (topLevel(lines[i]) && !lines[i].startsWith("  ")) {
+      end = i;
+      break;
+    }
+  }
+
+  let hasEnabled = false;
+  let hasBase = false;
+  for (let i = dockerStart + 1; i < end; i += 1) {
+    if (/^\s+enabled:\s*/.test(lines[i])) {
+      lines[i] = "  enabled: true";
+      hasEnabled = true;
+    }
+    if (/^\s+base_image:\s*/.test(lines[i])) {
+      lines[i] = `  base_image: ${baseImage}`;
+      hasBase = true;
+    }
+  }
+
+  const insertAt = dockerStart + 1;
+  const insertLines = [];
+  if (!hasEnabled) insertLines.push("  enabled: true");
+  if (!hasBase) insertLines.push(`  base_image: ${baseImage}`);
+  if (insertLines.length > 0) {
+    lines.splice(insertAt, 0, ...insertLines);
+  }
+
+  return lines.join("\n");
+}
+
+function runCodex(prompt, codexConfig) {
+  const args = ["exec"];
+  if (codexConfig.model) args.push("--model", codexConfig.model);
+  if (codexConfig.profile) args.push("--profile", codexConfig.profile);
+  if (codexConfig.full_auto) args.push("--full-auto");
+  if (codexConfig.ask_for_approval) {
+    args.push("--config", `ask_for_approval=${codexConfig.ask_for_approval}`);
+  }
+  if (codexConfig.model_reasoning_effort) {
+    args.push(
+      "--config",
+      `model_reasoning_effort=${codexConfig.model_reasoning_effort}`
+    );
+  }
+  if (codexConfig.sandbox) args.push("--sandbox", codexConfig.sandbox);
+  args.push("-");
+
+  const result = spawnSync("codex", args, {
+    input: prompt,
+    encoding: "utf8",
+    cwd: root,
+    env: process.env,
+  });
+
+  const combined = `${result.stdout || ""}\n${result.stderr || ""}`.trim();
+  if (combined) process.stdout.write(`${combined}\n`);
+  return combined;
+}
+
+function buildPrompt(nodeVersion) {
+  const nodeLine = nodeVersion ? `Node version: ${nodeVersion}` : "Node 20+";
+  return `Encuentra la mejor imagen base de Docker para este proyecto.
+Considera que necesita ejecutar npm scripts, módulos nativos y evitar Alpine.
+${nodeLine}
+
+Responde SOLO con una línea en este formato:
+BASE_IMAGE: <imagen>`;
+}
+
+async function main() {
+  const config = loadConfig(resolvedConfigPath);
+  const codexConfig = config?.codex || {};
+
+  const nodeVersionPath = path.join(root, ".nvmrc");
+  const nodeVersion = fs.existsSync(nodeVersionPath)
+    ? fs.readFileSync(nodeVersionPath, "utf8").trim()
+    : "";
+
+  const prompt = buildPrompt(nodeVersion);
+  const output = runCodex(prompt, codexConfig);
+  const baseImage = parseBaseImage(output);
+
+  if (!baseImage) {
+    console.error("Could not parse BASE_IMAGE from Codex output.");
+    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();
+  if (!approved) {
+    process.stdout.write("Aborted by user.\n");
+    process.exit(1);
+  }
+
+  const content = fs.existsSync(resolvedConfigPath)
+    ? fs.readFileSync(resolvedConfigPath, "utf8")
+    : "";
+  const updated = updateDockerConfigText(content, baseImage);
+  fs.writeFileSync(resolvedConfigPath, updated, "utf8");
+
+  process.stdout.write(
+    `Updated ${path.relative(root, resolvedConfigPath)} with docker.enabled=true and base_image=${baseImage}.\n`
+  );
+}
+
+void main();