@dungle-scrubs/tallow 0.8.27 → 0.9.0

package/extensions/loop/__tests__/loop.test.ts

@@ -2,16 +2,19 @@
  * Unit tests for the loop extension's pure helpers.
  *
  * Tests interval parsing, countdown formatting, argument parsing,
- * max iterations, and until-condition extraction.
+ * max iterations, until-condition extraction, natural-language parsing,
+ * and command building.
  */
 
 import { describe, expect, test } from "bun:test";
 import {
+	buildLoopCommand,
 	extractUntilCondition,
 	formatCountdown,
 	parseInterval,
 	parseLoopArgs,
 	parseMaxIterations,
+	parseNaturalLanguageLoop,
 } from "../index.js";
 
 describe("parseInterval", () => {
@@ -322,3 +325,364 @@ describe("parseLoopArgs", () => {
 		});
 	});
 });
+
+// ── Natural language parsing ─────────────────────────────────────────────
+
+describe("parseNaturalLanguageLoop", () => {
+	// ── Interval extraction ──────────────────────────────────────────
+
+	test("extracts 'every N minutes'", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2 minutes");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'every N seconds'", () => {
+		const result = parseNaturalLanguageLoop("run tests every 30 seconds");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 30_000,
+			intervalLabel: "30s",
+			prompt: "run tests",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'every N hrs'", () => {
+		const result = parseNaturalLanguageLoop("check logs every 2 hrs");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 7_200_000,
+			intervalLabel: "2h",
+			prompt: "check logs",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'every minute' (no number → 1)", () => {
+		const result = parseNaturalLanguageLoop("check deploy every minute");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 60_000,
+			intervalLabel: "1m",
+			prompt: "check deploy",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'every hour'", () => {
+		const result = parseNaturalLanguageLoop("summarize logs every hour");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 3_600_000,
+			intervalLabel: "1h",
+			prompt: "summarize logs",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'every Nm' shorthand", () => {
+		const result = parseNaturalLanguageLoop("check ci every 5m");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 300_000,
+			intervalLabel: "5m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts bare interval without 'every'", () => {
+		const result = parseNaturalLanguageLoop("check ci 2m");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("returns null when no interval found", () => {
+		expect(parseNaturalLanguageLoop("check ci please")).toBeNull();
+	});
+
+	test("returns null when no prompt remains", () => {
+		expect(parseNaturalLanguageLoop("every 2m")).toBeNull();
+	});
+
+	// ── Condition extraction ─────────────────────────────────────────
+
+	test("extracts 'until' condition at end", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2 minutes until it passes");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "it passes",
+		});
+	});
+
+	test("extracts 'stop when' condition at end", () => {
+		const result = parseNaturalLanguageLoop("run tests every 30s, stop when they pass");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 30_000,
+			intervalLabel: "30s",
+			prompt: "run tests",
+			maxIterations: null,
+			untilCondition: "they pass",
+		});
+	});
+
+	test("extracts condition at start with comma separator", () => {
+		const result = parseNaturalLanguageLoop("until the build passes, check ci every 2m");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "the build passes",
+		});
+	});
+
+	test("strips quotes from NL condition", () => {
+		const result = parseNaturalLanguageLoop('check ci every 2m until "the build is green"');
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "the build is green",
+		});
+	});
+
+	test("strips trailing punctuation from condition", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2m until it passes.");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "it passes",
+		});
+	});
+
+	// ── Max iterations extraction ────────────────────────────────────
+
+	test("extracts 'N times'", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2m 10 times");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: 10,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'max N'", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2m max 20");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: 20,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'max N tries'", () => {
+		const result = parseNaturalLanguageLoop("monitor deploy health every minute, max 20 tries");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 60_000,
+			intervalLabel: "1m",
+			prompt: "monitor deploy health",
+			maxIterations: 20,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts 'at most N'", () => {
+		const result = parseNaturalLanguageLoop("check ci every 5m at most 15");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 300_000,
+			intervalLabel: "5m",
+			prompt: "check ci",
+			maxIterations: 15,
+			untilCondition: null,
+		});
+	});
+
+	test("extracts x<N> in NL context", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2m x10");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: 10,
+			untilCondition: null,
+		});
+	});
+
+	// ── Combined: all features ───────────────────────────────────────
+
+	test("extracts interval + condition + max iterations", () => {
+		const result = parseNaturalLanguageLoop(
+			"run tests every 30 seconds, max 20, until they all pass"
+		);
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 30_000,
+			intervalLabel: "30s",
+			prompt: "run tests",
+			maxIterations: 20,
+			untilCondition: "they all pass",
+		});
+	});
+
+	test("handles realistic CI monitoring request", () => {
+		const result = parseNaturalLanguageLoop(
+			"check the latest GitHub Actions run for this branch every 2 minutes until the latest CI run is green"
+		);
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check the latest GitHub Actions run for this branch",
+			maxIterations: null,
+			untilCondition: "the latest CI run is green",
+		});
+	});
+
+	test("handles 'stop when' with comma", () => {
+		const result = parseNaturalLanguageLoop("run the test suite every 30s, stop when tests pass");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 30_000,
+			intervalLabel: "30s",
+			prompt: "run the test suite",
+			maxIterations: null,
+			untilCondition: "tests pass",
+		});
+	});
+
+	// ── Interval position doesn't matter ─────────────────────────────
+
+	test("interval at start of text", () => {
+		const result = parseNaturalLanguageLoop("every 5 minutes check if the build finished");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 300_000,
+			intervalLabel: "5m",
+			prompt: "check if the build finished",
+			maxIterations: null,
+			untilCondition: null,
+		});
+	});
+
+	test("interval in middle of text", () => {
+		const result = parseNaturalLanguageLoop("check ci every 2m until it's green");
+		expect(result).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "it's green",
+		});
+	});
+});
+
+// ── buildLoopCommand ─────────────────────────────────────────────────────
+
+describe("buildLoopCommand", () => {
+	test("builds simple command", () => {
+		expect(
+			buildLoopCommand({
+				action: "start",
+				intervalMs: 300_000,
+				intervalLabel: "5m",
+				prompt: "check deploy",
+				maxIterations: null,
+				untilCondition: null,
+			})
+		).toBe("/loop 5m check deploy");
+	});
+
+	test("includes max iterations", () => {
+		expect(
+			buildLoopCommand({
+				action: "start",
+				intervalMs: 60_000,
+				intervalLabel: "1m",
+				prompt: "run tests",
+				maxIterations: 10,
+				untilCondition: null,
+			})
+		).toBe("/loop 1m x10 run tests");
+	});
+
+	test("includes until condition", () => {
+		expect(
+			buildLoopCommand({
+				action: "start",
+				intervalMs: 120_000,
+				intervalLabel: "2m",
+				prompt: "check ci",
+				maxIterations: null,
+				untilCondition: "build is green",
+			})
+		).toBe('/loop 2m until "build is green" check ci');
+	});
+
+	test("includes both max iterations and condition", () => {
+		expect(
+			buildLoopCommand({
+				action: "start",
+				intervalMs: 30_000,
+				intervalLabel: "30s",
+				prompt: "run the test suite",
+				maxIterations: 50,
+				untilCondition: "tests pass",
+			})
+		).toBe('/loop 30s x50 until "tests pass" run the test suite');
+	});
+
+	test("round-trips through parseLoopArgs", () => {
+		const nl = parseNaturalLanguageLoop("check ci every 2 minutes until the build passes");
+		if (!nl) throw new Error("Expected NL parse to succeed");
+		const command = buildLoopCommand(nl);
+		const strict = parseLoopArgs(command.replace(/^\/loop\s+/, ""));
+		expect(strict).toEqual({
+			action: "start",
+			intervalMs: 120_000,
+			intervalLabel: "2m",
+			prompt: "check ci",
+			maxIterations: null,
+			untilCondition: "the build passes",
+		});
+	});
+});

package/extensions/loop/index.ts

@@ -10,7 +10,7 @@
  *   - `until "<condition>"` — the model evaluates the condition each
  *     iteration and calls the `loop_stop` tool when it's met
  *
- * Usage:
+ * Usage (strict syntax):
  *   /loop 5m check the deploy status
  *   /loop 1m x10 run the test suite
  *   /loop 2m until "build is done" check fuse index progress
@@ -18,6 +18,11 @@
  *   /loop 30s /stats
  *   /loop stop
  *   /loop status
+ *
+ * Natural language (auto-parsed → prefilled for confirmation):
+ *   /loop check ci every 2 minutes until it passes
+ *   /loop run tests every 30 seconds, stop when they pass
+ *   /loop monitor deploy health every minute, max 20 tries
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
@@ -277,6 +282,201 @@ export function parseLoopArgs(args: string): LoopArgs | { action: "error"; messa
 	};
 }
 
+// ── Natural Language Parsing ──────────────────────────────────────────────────
+
+/** Map from human-readable unit names to short suffixes. */
+const UNIT_ALIASES: Readonly<Record<string, string>> = {
+	s: "s",
+	sec: "s",
+	secs: "s",
+	second: "s",
+	seconds: "s",
+	m: "m",
+	min: "m",
+	mins: "m",
+	minute: "m",
+	minutes: "m",
+	h: "h",
+	hr: "h",
+	hrs: "h",
+	hour: "h",
+	hours: "h",
+};
+
+/**
+ * Attempt to parse a natural-language loop description into structured params.
+ *
+ * Extracts interval, condition, max iterations, and prompt from free-form
+ * text using regex heuristics. Returns null if no interval can be identified.
+ *
+ * This is a best-effort parser — the result is prefilled in the editor for
+ * the user to review, not executed directly.
+ *
+ * @param text - Free-form loop description
+ * @returns Parsed start params, or null if no interval was found
+ */
+export function parseNaturalLanguageLoop(
+	text: string
+): Extract<LoopArgs, { action: "start" }> | null {
+	let work = text;
+
+	// ── Interval extraction ──────────────────────────────────────────
+
+	let intervalMs: number | null = null;
+	let intervalLabel: string | null = null;
+
+	// "every <N> <unit-word>" — e.g. "every 2 minutes", "every 30 seconds"
+	const everyLong = work.match(
+		/\bevery\s+(\d+)\s+(seconds?|secs?|sec|minutes?|mins?|min|hours?|hrs?|hr)\b/i
+	);
+	if (everyLong) {
+		const val = parseInt(everyLong[1], 10);
+		const unit = UNIT_ALIASES[everyLong[2].toLowerCase()];
+		if (unit && val > 0) {
+			intervalMs = val * UNIT_MS[unit];
+			intervalLabel = `${val}${unit}`;
+			work = work.replace(everyLong[0], " ");
+		}
+	}
+
+	// "every <unit-word>" without number → 1 unit. e.g. "every minute"
+	if (!intervalMs) {
+		const everyBare = work.match(/\bevery\s+(second|minute|hour)\b/i);
+		if (everyBare) {
+			const unit = UNIT_ALIASES[everyBare[1].toLowerCase()];
+			if (unit) {
+				intervalMs = UNIT_MS[unit];
+				intervalLabel = `1${unit}`;
+				work = work.replace(everyBare[0], " ");
+			}
+		}
+	}
+
+	// "every <N><short-unit>" — e.g. "every 2m"
+	if (!intervalMs) {
+		const everyShort = work.match(/\bevery\s+(\d+)(s|m|h)\b/i);
+		if (everyShort) {
+			const val = parseInt(everyShort[1], 10);
+			const unit = everyShort[2].toLowerCase();
+			if (val > 0) {
+				intervalMs = val * UNIT_MS[unit];
+				intervalLabel = `${val}${unit}`;
+				work = work.replace(everyShort[0], " ");
+			}
+		}
+	}
+
+	// Bare "<N><short-unit>" without "every" — e.g. "2m"
+	if (!intervalMs) {
+		const bare = work.match(/\b(\d+)(s|m|h)\b/);
+		if (bare) {
+			const val = parseInt(bare[1], 10);
+			const unit = bare[2].toLowerCase();
+			if (val > 0) {
+				intervalMs = val * UNIT_MS[unit];
+				intervalLabel = `${val}${unit}`;
+				work = work.replace(bare[0], " ");
+			}
+		}
+	}
+
+	if (!intervalMs || !intervalLabel) return null;
+
+	// ── Max iterations extraction ────────────────────────────────────
+
+	let maxIterations: number | null = null;
+
+	// "x<N>"
+	const xN = work.match(/\bx(\d+)\b/);
+	if (xN) {
+		const n = parseInt(xN[1], 10);
+		if (n > 0) {
+			maxIterations = n;
+			work = work.replace(xN[0], " ");
+		}
+	}
+
+	// "<N> times" / "max <N> [times|tries|iterations]" / "at most <N> [...]"
+	if (maxIterations === null) {
+		const alt = work.match(
+			/\b(?:(\d+)\s+times|max\s+(\d+)(?:\s+(?:times|tries|iterations))?|at\s+most\s+(\d+)(?:\s+(?:times|tries|iterations))?)\b/i
+		);
+		if (alt) {
+			const n = parseInt(alt[1] || alt[2] || alt[3], 10);
+			if (n > 0) {
+				maxIterations = n;
+				work = work.replace(alt[0], " ");
+			}
+		}
+	}
+
+	// ── Condition extraction ─────────────────────────────────────────
+	// Uses greedy match for the prompt prefix so multi-"until" text picks
+	// the last occurrence (the actual condition marker).
+
+	let untilCondition: string | null = null;
+	let promptText: string;
+
+	// Case 1: condition at end (most common) — "check ci until it passes"
+	const endMatch = work.match(/^(.*)\s*[,;]?\s*\b(until|stop\s+when)\s+(.+?)[\s,;.!]*$/i);
+
+	if (endMatch?.[1].trim()) {
+		promptText = endMatch[1];
+		untilCondition = endMatch[3].replace(/^["']|["']$/g, "");
+	} else {
+		// Case 2: condition at start with comma — "until it passes, check ci"
+		const startMatch = work.match(/^\s*\b(until|stop\s+when)\s+(.+?)\s*[,;]\s+(.+?)[\s,;.!]*$/i);
+
+		if (startMatch) {
+			untilCondition = startMatch[2].replace(/^["']|["']$/g, "");
+			promptText = startMatch[3];
+		} else {
+			// No condition marker, or condition-only with no prompt
+			promptText = work;
+		}
+	}
+
+	// ── Clean up ─────────────────────────────────────────────────────
+
+	const prompt = promptText.replace(/[,;]+/g, " ").replace(/\s+/g, " ").trim();
+
+	if (!prompt) return null;
+
+	if (untilCondition) {
+		untilCondition = untilCondition.replace(/\s+/g, " ").trim();
+		if (!untilCondition) untilCondition = null;
+	}
+
+	return {
+		action: "start",
+		intervalMs,
+		intervalLabel,
+		prompt,
+		maxIterations,
+		untilCondition,
+	};
+}
+
+/**
+ * Build a `/loop` command string from structured params.
+ *
+ * Produces valid strict syntax that `parseLoopArgs` can parse.
+ *
+ * @param params - Parsed loop start parameters
+ * @returns Command string like `/loop 2m until "it passes" check ci`
+ */
+export function buildLoopCommand(params: Extract<LoopArgs, { action: "start" }>): string {
+	let cmd = `/loop ${params.intervalLabel}`;
+	if (params.maxIterations !== null) {
+		cmd += ` x${params.maxIterations}`;
+	}
+	if (params.untilCondition) {
+		cmd += ` until "${params.untilCondition}"`;
+	}
+	cmd += ` ${params.prompt}`;
+	return cmd;
+}
+
 // ── Loop Lifecycle ───────────────────────────────────────────────────────────
 
 /**
@@ -469,14 +669,24 @@ export default function loopExtension(pi: ExtensionAPI): void {
 	pi.registerCommand("loop", {
 		description:
 			"Run a prompt on a recurring interval. " +
-			'Syntax: /loop <interval> [x<N>] [until "<condition>"] <prompt>',
+			'Syntax: /loop <interval> [x<N>] [until "<condition>"] <prompt> — ' +
+			"or describe in natural language: /loop check ci every 2m until it passes",
 		handler: async (args, ctx) => {
 			const parsed = parseLoopArgs(args);
 
 			switch (parsed.action) {
-				case "error":
+				case "error": {
+					// Try natural-language fallback before showing the error
+					const nlResult = parseNaturalLanguageLoop(args);
+					if (nlResult) {
+						const command = buildLoopCommand(nlResult);
+						ctx.ui.setEditorText(command);
+						ctx.ui.notify("Loop command generated — review and press Enter to start", "info");
+						return;
+					}
 					ctx.ui.notify(parsed.message, "error");
 					return;
+				}
 
 				case "stop":
 					if (!activeLoop) {