feat: add single-task repeat mode and code cleanup

PRD.example.md

@@ -0,0 +1,27 @@
+# Example Project PRD
+
+Ein einfaches Beispiel-Projekt, um Ralphy zu demonstrieren.
+
+## Kontext
+
+Wir bauen eine kleine CLI-Anwendung, die Markdown-Dateien in HTML konvertiert.
+
+## Tasks
+
+- [ ] Projekt-Setup: package.json erstellen mit TypeScript und Vitest
+- [ ] Funktion schreiben, die Markdown-Headings (#, ##, ###) in HTML-Tags konvertiert
+- [ ] Funktion schreiben, die **bold** und *italic* Text konvertiert
+- [ ] Funktion schreiben, die Listen (- item) in HTML-Listen konvertiert
+- [ ] CLI-Entry-Point erstellen, der eine Datei einliest und konvertiert
+- [ ] README.md mit Nutzungsanleitung schreiben
+
+## Akzeptanzkriterien
+
+- Alle Tests gruen
+- TypeScript kompiliert ohne Fehler
+- CLI kann mit `npx ts-node src/index.ts input.md` ausgefuehrt werden
+
+## Notizen
+
+- Keine externen Markdown-Libraries verwenden (Lernzweck)
+- Einfache Regex-basierte Konvertierung reicht aus

README.md

@@ -28,14 +28,16 @@ cd ralphy && chmod +x ralphy.sh
 ./ralphy.sh --prd PRD.md
 ```
 
-Both versions have identical features. Examples below use `ralphy` (npm) - substitute `./ralphy.sh` if using the bash script.
+Examples below use `ralphy` (npm). Most commands also work with `./ralphy.sh`, but newer npm CLI features may land there first.
 
 ## Two Modes
 
 **Single task** - just tell it what to do:
 ```bash
 ralphy "add dark mode"
 ralphy "fix the auth bug"
+ralphy --repeat 3 "find and fix bugs"
+ralphy --repeat 5 --continue-on-failure "harden edge cases"
 ```
 
 **Task list** - work through a PRD:
@@ -319,6 +321,8 @@ ralphy --parallel --sandbox
 | `--max-retries N` | retries per task (default: 3) |
 | `--retry-delay N` | seconds between retries |
 | `--dry-run` | preview only |
+| `--repeat N` | repeat a single task N times (requires task argument) |
+| `--continue-on-failure` | in repeat mode, continue after non-fatal task failures |
 | `--browser` | enable browser automation |
 | `--no-browser` | disable browser automation |
 | `-v, --verbose` | debug output |
@@ -363,6 +367,7 @@ When an engine exits non-zero, ralphy includes the last lines of CLI output in t
 ## Changelog
 
 ### v4.7.2
+- **Single-task repeat mode**: added `--repeat <n>` with `--continue-on-failure` and fail-fast defaults; fatal errors still abort immediately
 - **Improved auth error detection**: simplified `extractAuthenticationError` function with better edge case handling (e.g., JSON dumps during login)
 - **Added project standards**: `CLAUDE.md`, `.cursorrules`, `CONTRIBUTING.md` for consistent AI-assisted development
 - **Enhanced default prompts**: enforce concise, focused code changes

cli/README.md

@@ -24,6 +24,8 @@ ralphy --prd PRD.md
 ```bash
 ralphy "add dark mode"
 ralphy "fix the auth bug"
+ralphy --repeat 3 "find and fix bugs"
+ralphy --repeat 5 --continue-on-failure "harden edge cases"
 ```
 
 **Task list** - work through a PRD:
@@ -307,6 +309,8 @@ ralphy --parallel --sandbox
 | `--max-retries N` | retries per task (default: 3) |
 | `--retry-delay N` | seconds between retries |
 | `--dry-run` | preview only |
+| `--repeat N` | repeat a single task N times (requires task argument) |
+| `--continue-on-failure` | in repeat mode, continue after non-fatal task failures |
 | `--browser` | enable browser automation |
 | `--no-browser` | disable browser automation |
 | `-v, --verbose` | debug output |

cli/src/cli/__tests__/args.test.ts

@@ -0,0 +1,83 @@
+import { beforeAll, describe, expect, it, mock } from "bun:test";
+
+let parseArgs: typeof import("../args.ts").parseArgs;
+
+beforeAll(async () => {
+	mock.module("../../version.ts", () => ({
+		VERSION: "test",
+	}));
+	({ parseArgs } = await import("../args.ts"));
+});
+
+function parseCliArgs(args: string[]) {
+	return parseArgs(["bun", "ralphy", ...args]);
+}
+
+describe("parseArgs repeat options", () => {
+	it("parses --repeat 5 with task", () => {
+		const { options, task } = parseCliArgs(["--repeat", "5", "do something"]);
+		expect(task).toBe("do something");
+		expect(options.repeatCount).toBe(5);
+		expect(options.continueOnFailure).toBe(false);
+	});
+
+	it("throws on --repeat 0", () => {
+		expect(() => parseCliArgs(["--repeat", "0", "task"])).toThrow(
+			"--repeat must be an integer between 1 and 10000",
+		);
+	});
+
+	it("throws on --repeat -1", () => {
+		expect(() => parseCliArgs(["--repeat", "-1", "task"])).toThrow(
+			"--repeat must be an integer between 1 and 10000",
+		);
+	});
+
+	it("throws on --repeat abc", () => {
+		expect(() => parseCliArgs(["--repeat", "abc", "task"])).toThrow(
+			"--repeat must be an integer between 1 and 10000",
+		);
+	});
+
+	it("throws on --repeat 1.5", () => {
+		expect(() => parseCliArgs(["--repeat", "1.5", "task"])).toThrow(
+			"--repeat must be an integer between 1 and 10000",
+		);
+	});
+
+	it("throws on --repeat 10001", () => {
+		expect(() => parseCliArgs(["--repeat", "10001", "task"])).toThrow(
+			"--repeat must be an integer between 1 and 10000",
+		);
+	});
+
+	it("parses --repeat with --continue-on-failure", () => {
+		const { options } = parseCliArgs(["--repeat", "3", "--continue-on-failure", "task"]);
+		expect(options.repeatCount).toBe(3);
+		expect(options.continueOnFailure).toBe(true);
+	});
+
+	it("throws when --repeat is used without task", () => {
+		expect(() => parseCliArgs(["--repeat", "3"])).toThrow(
+			"--repeat and --continue-on-failure require a task argument",
+		);
+	});
+
+	it("throws when --continue-on-failure is used without task", () => {
+		expect(() => parseCliArgs(["--continue-on-failure"])).toThrow(
+			"--repeat and --continue-on-failure require a task argument",
+		);
+	});
+
+	it("throws when repeat options are combined with task source flags", () => {
+		expect(() => parseCliArgs(["--repeat", "3", "--yaml", "tasks.yaml", "task"])).toThrow(
+			"--repeat and --continue-on-failure cannot be used with --prd, --yaml, --json, or --github",
+		);
+	});
+
+	it("defaults to repeatCount 1", () => {
+		const { options } = parseCliArgs(["task"]);
+		expect(options.repeatCount).toBe(1);
+		expect(options.continueOnFailure).toBe(false);
+	});
+});

cli/src/cli/args.ts

@@ -31,6 +31,8 @@ export function createProgram(): Command {
 		.option("--copilot", "Use GitHub Copilot")
 		.option("--gemini", "Use Gemini CLI")
 		.option("--dry-run", "Show what would be done without executing")
+		.option("--repeat <n>", "Repeat single task N times")
+		.option("--continue-on-failure", "Continue repeat loop on task failure")
 		.option("--max-iterations <n>", "Maximum iterations (0 = unlimited)", "0")
 		.option("--max-retries <n>", "Maximum retries per task", "3")
 		.option("--retry-delay <n>", "Delay between retries in seconds", "5")
@@ -62,6 +64,12 @@ export function createProgram(): Command {
 	return program;
 }
 
+function resolveBrowserEnabled(flag: boolean | undefined): "auto" | "true" | "false" {
+	if (flag === true) return "true";
+	if (flag === false) return "false";
+	return "auto";
+}
+
 /**
  * Parse command line arguments into RuntimeOptions
  */
@@ -88,7 +96,33 @@ export function parseArgs(args: string[]): {
 	const opts = program.opts();
 	const [task] = program.args;
 
-	// Determine AI engine (--sonnet implies --claude)
+	// --prd has a commander default, so opts.prd alone cannot detect explicit usage
+	const taskSourceFlags = ["--prd", "--yaml", "--json", "--github"];
+	const hasExplicitTaskSourceFlag = ralphyArgs.some((arg) =>
+		taskSourceFlags.some((flag) => arg === flag || arg.startsWith(`${flag}=`)),
+	);
+
+	const repeatProvided = opts.repeat !== undefined;
+	const repeatCount = repeatProvided ? Number(opts.repeat) : 1;
+	if (repeatProvided && (!Number.isInteger(repeatCount) || repeatCount < 1 || repeatCount > 10_000)) {
+		throw new Error("--repeat must be an integer between 1 and 10000");
+	}
+
+	const continueOnFailure = opts.continueOnFailure || false;
+	if (continueOnFailure && !repeatProvided && task) {
+		console.warn("Warning: --continue-on-failure has no effect without --repeat");
+	}
+	const hasRepeatOptions = repeatProvided || continueOnFailure;
+	if (hasRepeatOptions && !task) {
+		throw new Error("--repeat and --continue-on-failure require a task argument");
+	}
+	if (hasRepeatOptions && hasExplicitTaskSourceFlag) {
+		throw new Error(
+			"--repeat and --continue-on-failure cannot be used with --prd, --yaml, --json, or --github",
+		);
+	}
+
+	// --sonnet implies --claude and takes priority over other engine flags
 	let aiEngine = "claude";
 	if (opts.sonnet) aiEngine = "claude";
 	else if (opts.opencode) aiEngine = "opencode";
@@ -140,6 +174,8 @@ export function parseArgs(args: string[]): {
 		maxIterations: Number.parseInt(opts.maxIterations, 10) || 0,
 		maxRetries: Number.parseInt(opts.maxRetries, 10) || 3,
 		retryDelay: Number.parseInt(opts.retryDelay, 10) || 5,
+		repeatCount,
+		continueOnFailure,
 		verbose: opts.verbose || false,
 		branchPerTask: opts.branchPerTask || false,
 		baseBranch: opts.baseBranch || "",
@@ -154,7 +190,7 @@ export function parseArgs(args: string[]): {
 		githubLabel: opts.githubLabel || "",
 		syncIssue: opts.syncIssue ? Number.parseInt(opts.syncIssue, 10) || undefined : undefined,
 		autoCommit: opts.commit !== false,
-		browserEnabled: opts.browser === true ? "true" : opts.browser === false ? "false" : "auto",
+		browserEnabled: resolveBrowserEnabled(opts.browser),
 		modelOverride,
 		skipMerge: opts.merge === false,
 		useSandbox: opts.sandbox || false,

cli/src/cli/commands/single-task-loop.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "bun:test";
+import { DEFAULT_OPTIONS } from "../../config/types.ts";
+import { runSingleTaskLoop } from "./single-task-loop.ts";
+
+describe("runSingleTaskLoop", () => {
+	it("stops on first non-fatal failure in fail-fast mode", async () => {
+		let calls = 0;
+		const result = await runSingleTaskLoop(
+			"task",
+			{
+				...DEFAULT_OPTIONS,
+				repeatCount: 3,
+				continueOnFailure: false,
+			},
+			{
+				runTaskFn: async () => {
+					calls++;
+					return { success: false, fatal: false, error: "boom" };
+				},
+				logInfoFn: () => {},
+			},
+		);
+
+		expect(calls).toBe(1);
+		expect(result.completed).toBe(0);
+		expect(result.failed).toBe(1);
+		expect(result.total).toBe(3);
+	});
+
+	it("continues on non-fatal failures when continue-on-failure is enabled", async () => {
+		let call = 0;
+		const sequence = [
+			{ success: false, fatal: false, error: "first" },
+			{ success: true, fatal: false },
+			{ success: false, fatal: false, error: "last" },
+		] as const;
+
+		const result = await runSingleTaskLoop(
+			"task",
+			{
+				...DEFAULT_OPTIONS,
+				repeatCount: 3,
+				continueOnFailure: true,
+			},
+			{
+				runTaskFn: async () => sequence[call++] ?? sequence[sequence.length - 1],
+				logInfoFn: () => {},
+			},
+		);
+
+		expect(call).toBe(3);
+		expect(result.completed).toBe(1);
+		expect(result.failed).toBe(2);
+		expect(result.total).toBe(3);
+	});
+
+	it("always stops on fatal failures", async () => {
+		let calls = 0;
+		const result = await runSingleTaskLoop(
+			"task",
+			{
+				...DEFAULT_OPTIONS,
+				repeatCount: 5,
+				continueOnFailure: true,
+			},
+			{
+				runTaskFn: async () => {
+					calls++;
+					return { success: false, fatal: true, error: "auth failed" };
+				},
+				logInfoFn: () => {},
+			},
+		);
+
+		expect(calls).toBe(1);
+		expect(result.completed).toBe(0);
+		expect(result.failed).toBe(1);
+		expect(result.total).toBe(5);
+	});
+});

cli/src/cli/commands/single-task-loop.ts

@@ -0,0 +1,57 @@
+import type { RuntimeOptions } from "../../config/types.ts";
+import { logInfo } from "../../ui/logger.ts";
+import { type TaskRunResult, runTask } from "./task.ts";
+
+type TaskRunner = (task: string, options: RuntimeOptions) => Promise<TaskRunResult>;
+type InfoLogger = (message: string) => void;
+
+export interface SingleTaskLoopResult {
+	total: number;
+	completed: number;
+	failed: number;
+}
+
+/**
+ * Run the single-task flow with optional repeat behavior.
+ */
+export async function runSingleTaskLoop(
+	task: string,
+	options: RuntimeOptions,
+	deps?: {
+		runTaskFn?: TaskRunner;
+		logInfoFn?: InfoLogger;
+	},
+): Promise<SingleTaskLoopResult> {
+	const runTaskFn = deps?.runTaskFn ?? runTask;
+	const logInfoFn = deps?.logInfoFn ?? logInfo;
+
+	const total = options.repeatCount;
+	let completed = 0;
+	let failed = 0;
+
+	for (let i = 1; i <= total; i++) {
+		if (total > 1) {
+			logInfoFn(`[${i}/${total}] Executing: ${task}`);
+		}
+
+		const result = await runTaskFn(task, options);
+		if (result.success) {
+			completed++;
+			continue;
+		}
+
+		failed++;
+		if (result.fatal || !options.continueOnFailure) {
+			break;
+		}
+	}
+
+	if (total > 1) {
+		const skipped = total - completed - failed;
+		const parts = [`${completed} succeeded`, `${failed} failed`];
+		if (skipped > 0) parts.push(`${skipped} skipped`);
+		logInfoFn(`Done: ${parts.join(", ")} of ${total}`);
+	}
+
+	return { total, completed, failed };
+}