@lnilluv/pi-ralph-loop 0.3.0 → 1.0.0

package/.github/workflows/release.yml

@@ -71,54 +71,23 @@ jobs:
           fi
 
           branch="${GITHUB_REF_NAME}"
-          current_version="$(node -p "require('./package.json').version")"
-          new_version="$(node - "$current_version" "$branch" "$bump" <<'NODE'
-          const [current, branch, bump] = process.argv.slice(2);
-          const match = current.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
-          if (!match) throw new Error(`Unsupported version: ${current}`);
-
-          let major = Number(match[1]);
-          let minor = Number(match[2]);
-          let patch = Number(match[3]);
-          const prerelease = match[4];
-
-          if (branch === 'dev') {
-            if (prerelease && prerelease.startsWith('dev.')) {
-              const currentN = Number(prerelease.split('.')[1] ?? '0');
-              process.stdout.write(`${major}.${minor}.${patch}-dev.${currentN + 1}`);
-            } else {
-              if (bump === 'major') { major += 1; minor = 0; patch = 0; }
-              else if (bump === 'minor') { minor += 1; patch = 0; }
-              else { patch += 1; }
-              process.stdout.write(`${major}.${minor}.${patch}-dev.0`);
-            }
-          } else {
-            if (bump === 'major') { major += 1; minor = 0; patch = 0; }
-            else if (bump === 'minor') { minor += 1; patch = 0; }
-            else { patch += 1; }
-            process.stdout.write(`${major}.${minor}.${patch}`);
-          }
-          NODE
-          )"
+          npm_versions="$(npm view @lnilluv/pi-ralph-loop versions --json)"
+          git_tags="$(git tag --list)"
+          new_version="$(node --experimental-strip-types ./scripts/version-helper.ts "$branch" "$bump" "$npm_versions" "$git_tags")"
 
           echo "should_release=true" >> "$GITHUB_OUTPUT"
           echo "bump=$bump" >> "$GITHUB_OUTPUT"
           echo "new_version=$new_version" >> "$GITHUB_OUTPUT"
 
-      - name: Bump version (main)
-        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
-        run: npm version ${{ steps.bump.outputs.bump }} --no-git-tag-version
-
-      - name: Bump version (dev)
-        if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'dev'
-        run: npm version prerelease --preid dev --no-git-tag-version
+      - name: Bump version
+        if: steps.bump.outputs.should_release == 'true'
+        run: npm version ${{ steps.bump.outputs.new_version }} --no-git-tag-version
 
       - name: Capture version tag
         if: steps.bump.outputs.should_release == 'true'
         id: version
         run: |
-          VERSION=$(node -p "require('./package.json').version")
-          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "tag=v${{ steps.bump.outputs.new_version }}" >> "$GITHUB_OUTPUT"
 
       - name: Publish (main)
         if: steps.bump.outputs.should_release == 'true' && github.ref_name == 'main'
@@ -133,7 +102,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          VERSION=$(node -p "require('./package.json').version")
+          VERSION="${{ steps.bump.outputs.new_version }}"
           git add package.json package-lock.json
           git commit -m "chore(release): v${VERSION}"
           git tag "v${VERSION}"

package/README.md

@@ -1,188 +1,78 @@
 # pi-ralph
+Autonomous coding loops for pi with task folders, editable drafts, durable state, and per-iteration supervision.
 
-Autonomous coding loops for pi with mid-turn supervision.
+## Why use it
+- Keep work in a task folder instead of a single chat turn.
+- Re-run commands each iteration and feed the output back into the prompt.
+- Keep short rolling memory in `RALPH_PROGRESS.md`.
+- Store durable loop state in `.ralph-runner/`.
+- Draft from plain language, then review before starting.
 
 ## Install
-
 ```bash
 pi install npm:@lnilluv/pi-ralph-loop
 ```
 
 ## Quick start
+1. Create `work/RALPH.md`.
+2. Run `/ralph --path work --arg owner="Ada Lovelace"`.
+3. If you want a draft first, use `/ralph-draft fix flaky auth tests`.
 
-### Run an existing task folder
-
+## Concise `RALPH.md`
 ```md
-# my-task/RALPH.md
 ---
+args:
+  - owner
 commands:
   - name: tests
     run: npm test
     timeout: 60
----
-Fix failing tests using this output:
-
-{{ commands.tests }}
-```
-
-Run:
-
-```text
-/ralph my-task
-```
-
-### Draft a loop from natural language
-
-```text
-/ralph reverse engineer this app
-```
-
-pi drafts `./reverse-engineer-this-app/RALPH.md`, shows a short Mission Brief, lets you edit the file, and only starts after you confirm.
-
-### Draft without starting
-
-```text
-/ralph-draft fix flaky auth tests
-```
-
-That saves the draft but does not launch the loop.
-
-## How it works
-
-On each iteration, pi-ralph reads `RALPH.md`, runs the configured commands, injects their output into the prompt through `{{ commands.<name> }}` placeholders, starts a fresh session, sends the prompt, and waits for completion. Failed command output appears in the next iteration, which creates a self-healing loop.
-
-## Smart `/ralph` behavior
-
-`/ralph` is path-first:
-
-- task folder with `RALPH.md` -> runs it
-- direct `RALPH.md` path -> runs it
-- no args in a folder without `RALPH.md` -> asks what the loop should work on, drafts `./RALPH.md`, then asks before starting
-- natural-language task -> drafts `./<slug>/RALPH.md`, then asks before starting
-- unresolved path-like input like `foo/bar` or `notes.md` -> offers recovery choices and normalizes missing markdown targets to `./<folder>/RALPH.md`
-- arbitrary markdown files like `README.md` -> rejected instead of auto-run
-
-### Explicit flags
-
-Use these when you want to skip heuristics:
-
-```text
-/ralph --path my-task
-/ralph --task "reverse engineer the billing flow"
-/ralph-draft --path my-task
-/ralph-draft --task "fix flaky auth tests"
-```
-
-### Interactive review
-
-Draft flows require an interactive UI because the extension uses a Mission Brief and editor dialog before saving or starting. In non-interactive contexts, pass an existing task folder or `RALPH.md` path instead.
-
-## RALPH.md format
-
-```md
----
-commands:
-  - name: tests
-    run: npm test
-    timeout: 90
-  - name: lint
-    run: npm run lint
+  - name: verify
+    run: ./scripts/verify.sh
     timeout: 60
 max_iterations: 25
 timeout: 300
-completion_promise: "DONE"
-guardrails:
-  block_commands:
-    - "rm\\s+-rf\\s+/"
-    - "git\\s+push"
-  protected_files:
-    - ".env*"
-    - "**/secrets/**"
+completion_promise: DONE
 ---
-You are fixing flaky tests in the auth module.
-
-<!-- This comment is stripped before sending to the agent -->
-
-Latest test output:
-{{ commands.tests }}
+Fix the failing auth tests for {{ args.owner }}.
 
-Latest lint output:
-{{ commands.lint }}
-
-Iteration {{ ralph.iteration }} of {{ ralph.name }}.
-Apply the smallest safe fix and explain why it works.
+Use {{ commands.tests }} and {{ commands.verify }} as evidence.
+Stop with <promise>DONE</promise> only when the gate passes.
 ```
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `commands` | array | `[]` | Commands to run each iteration |
-| `commands[].name` | string | required | Key for `{{ commands.<name> }}` |
-| `commands[].run` | string | required | Shell command |
-| `commands[].timeout` | number | `60` | Seconds before kill |
-| `max_iterations` | number | `50` | Stop after N iterations |
-| `timeout` | number | `300` | Per-iteration timeout in seconds; stops the loop if the agent is stuck |
-| `completion_promise` | string | — | Agent signals completion by sending `<promise>DONE</promise>`; loop breaks on match |
-| `guardrails.block_commands` | string[] | `[]` | Regex patterns to block in bash |
-| `guardrails.protected_files` | string[] | `[]` | Glob patterns enforced on `write`/`edit` tool calls |
-
-### Placeholders
-
-| Placeholder | Description |
-|-------------|-------------|
-| `{{ commands.<name> }}` | Output from the named command |
-| `{{ ralph.iteration }}` | Current 1-based iteration number |
-| `{{ ralph.name }}` | Directory name containing the `RALPH.md` |
-
-HTML comments (`<!-- ... -->`) are stripped from the prompt body after placeholder resolution, so you can annotate your `RALPH.md` freely. Generated drafts also escape literal `<!--` and `-->` in the visible task line, and the leading metadata comment is URL-encoded so task text can safely contain comment-like sequences.
+## Key features
+- `/ralph` runs an existing task folder or `RALPH.md`, or drafts a new loop from plain language.
+- `/ralph-draft` saves the draft without starting the loop.
+- `/ralph-stop` writes a stop flag under `.ralph-runner/` so the loop exits after the current iteration.
+- Frontmatter can declare `args` and `{{ args.name }}` placeholders; `--arg name=value` fills them when you run an existing task folder with `/ralph --path`.
+- Commands that start with `./` run from the task directory, so checked-in helper scripts work.
+- `RALPH_PROGRESS.md` is injected as short rolling memory and excluded from progress snapshots.
+- The runner stores status, iteration records, events, transcripts, and stop signals in `.ralph-runner/`.
+- Completion gating only stops early when the promise is seen and the readiness checks pass; a clear no-progress result will not trigger early stop.
+- The loop can use a selected model and thinking level; if interactive draft strengthening has no authenticated model, it falls back to the deterministic draft path.
 
 ## Commands
-
-- `/ralph [path-or-task]` - Start Ralph from a task folder or `RALPH.md`, or draft a new loop from natural language.
-- `/ralph-draft [path-or-task]` - Draft or edit a Ralph task without starting it.
-- `/ralph-stop` - Request a graceful stop after the current iteration.
-
-## Pi-only features
-
-### Guardrails
-
-`guardrails.block_commands` and `guardrails.protected_files` come from RALPH frontmatter. The extension enforces them in the `tool_call` hook — but only for sessions created by the loop, so they don't leak into unrelated conversations. Matching bash commands are blocked, and `write`/`edit` tool calls targeting protected file globs are denied.
-
-### Cross-iteration memory
-
-After each iteration, the extension stores a short summary with iteration number and duration. In `before_agent_start`, it injects that history into the system prompt so the next run can avoid repeating completed work.
-
-### Mid-turn steering
-
-In the `tool_result` hook, bash outputs are scanned for failure patterns. After three or more failures in the same iteration, the extension appends a stop-and-think warning to push root-cause analysis before another retry.
-
-### Completion promise
-
-When `completion_promise` is set (for example, `"DONE"`), the loop scans the agent's messages for `<promise>DONE</promise>` after each iteration. If found, the loop stops early.
-
-### Iteration timeout
-
-Each iteration has a configurable timeout (default 300 seconds). If the agent is stuck and doesn't become idle within the timeout, the loop stops with a warning.
-
-### Input validation
-
-The extension validates `RALPH.md` frontmatter before starting and on each re-parse: `max_iterations` must be a positive integer, `timeout` must be positive, `block_commands` regexes must compile, and commands must have non-empty names and run strings with positive timeouts.
-
-## Comparison table
-
-| Feature | **@lnilluv/pi-ralph-loop** | pi-ralph | pi-ralph-wiggum | ralphi | ralphify |
-|---------|----------------------------|----------|-----------------|--------|----------|
-| Command output injection | ✓ | ✗ | ✗ | ✗ | ✓ |
-| Fresh-context sessions | ✓ | ✓ | ✗ | ✓ | ✓ |
-| Mid-turn guardrails | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Cross-iteration memory | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Mid-turn steering | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Guided task drafting | ✓ | ✗ | ✗ | ✗ | separate scaffold |
-| Completion promise | ✓ | ✗ | ✗ | ✗ | ✓ |
-| Iteration timeout | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Session-scoped hooks | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Input validation | ✓ | ✗ | ✗ | ✗ | ✗ |
-| Setup required | task folder or draft flow | config | RALPH.md | PRD pipeline | scaffold + RALPH.md |
+| Command | Use |
+|---|---|
+| `/ralph [path-or-task]` | Run an existing task folder or `RALPH.md`, or draft a new loop from a task description. |
+| `/ralph-draft [path-or-task]` | Draft or edit a loop without starting it. |
+| `/ralph-stop [path-or-task]` | Request a graceful stop after the current iteration. |
+
+## Config reference
+| Field | Purpose |
+|---|---|
+| `commands` | Shell commands to run each iteration. |
+| `args` | Declared runtime parameters for `--arg`. |
+| `max_iterations` | Maximum iterations, from 1 to 50. |
+| `inter_iteration_delay` | Delay between iterations, in seconds. |
+| `timeout` | Per-iteration timeout, up to 300 seconds. |
+| `completion_promise` | Early-stop marker such as `DONE`. |
+| `required_outputs` | Files that must exist before early stop. |
+| `guardrails.block_commands` | Regexes blocked in bash commands. |
+| `guardrails.protected_files` | File globs protected from `write` and `edit`. |
+| Model selection | Use a selected model and optional thinking level; the runner applies it before the prompt. |
+
+Advanced behavior, validation, and edge cases live in `src/runner.ts`, `src/runner-state.ts`, `src/runner-rpc.ts`, `src/ralph.ts`, and `tests/`.
 
 ## License
-
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lnilluv/pi-ralph-loop",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Pi-native ralph loop — autonomous coding iterations with mid-turn supervision",
   "type": "module",
   "pi": {
@@ -20,6 +20,7 @@
     "url": "git+https://github.com/lnilluv/pi-ralph-loop.git"
   },
   "dependencies": {
+    "@mariozechner/pi-ai": "0.66.1",
     "minimatch": "10.2.3",
     "yaml": "2.8.3"
   },
@@ -28,7 +29,6 @@
   },
   "keywords": [
     "pi-extension",
-    "pi-package",
     "ralph",
     "autonomous",
     "loop"

package/scripts/version-helper.ts

@@ -0,0 +1,210 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type VersionBump = "major" | "minor" | "patch";
+export type ReleaseBranch = "main" | "dev";
+
+export interface ReleaseVersionRequest {
+  branch: ReleaseBranch;
+  bump: VersionBump;
+  npmVersions: readonly string[] | string;
+  gitTags: readonly string[] | string;
+}
+
+type ParsedVersion = {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease?: string;
+};
+
+const STABLE_VERSION = /^\d+\.\d+\.\d+$/;
+const SEMVER_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+const DEV_PRERELEASE = /^dev\.(\d+)$/;
+
+function normalizeVersionList(input: readonly string[] | string): string[] {
+  if (Array.isArray(input)) {
+    return input.map((version) => version.trim()).filter(Boolean);
+  }
+
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    if (Array.isArray(parsed)) {
+      return parsed.map((value) => String(value).trim()).filter(Boolean);
+    }
+
+    if (typeof parsed === "string") {
+      return parsed.trim() ? [parsed.trim()] : [];
+    }
+  } catch {
+    // Fall through to line-based parsing.
+  }
+
+  return trimmed
+    .split(/[\r\n,]+/)
+    .map((version) => version.trim())
+    .filter(Boolean);
+}
+
+function stripGitTagPrefix(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+function parseVersion(version: string): ParsedVersion | null {
+  const match = version.match(SEMVER_VERSION);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4],
+  };
+}
+
+function isStableVersion(version: string): boolean {
+  return STABLE_VERSION.test(version);
+}
+
+function compareVersions(left: string, right: string): number {
+  const leftParsed = parseVersion(left);
+  const rightParsed = parseVersion(right);
+
+  if (!leftParsed || !rightParsed) {
+    return 0;
+  }
+
+  if (leftParsed.major !== rightParsed.major) {
+    return leftParsed.major - rightParsed.major;
+  }
+
+  if (leftParsed.minor !== rightParsed.minor) {
+    return leftParsed.minor - rightParsed.minor;
+  }
+
+  return leftParsed.patch - rightParsed.patch;
+}
+
+function maxVersion(versions: string[]): string | null {
+  return versions.reduce<string | null>((currentMax, version) => {
+    if (!currentMax) {
+      return version;
+    }
+
+    return compareVersions(version, currentMax) > 0 ? version : currentMax;
+  }, null);
+}
+
+function incStable(version: string, bump: VersionBump): string {
+  const parsed = parseVersion(version);
+  if (!parsed) {
+    throw new Error(`Unsupported version: ${version}`);
+  }
+
+  if (bump === "major") {
+    return `${parsed.major + 1}.0.0`;
+  }
+
+  if (bump === "minor") {
+    return `${parsed.major}.${parsed.minor + 1}.0`;
+  }
+
+  return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+}
+
+function collectStableVersions(input: readonly string[] | string): string[] {
+  return normalizeVersionList(input)
+    .map(stripGitTagPrefix)
+    .filter(isStableVersion);
+}
+
+function highestStableVersion(npmVersions: readonly string[] | string, gitTags: readonly string[] | string): string {
+  const stableNpm = collectStableVersions(npmVersions);
+  const stableTags = collectStableVersions(gitTags);
+  const highest = maxVersion([...stableNpm, ...stableTags]);
+  return highest ?? "0.0.0";
+}
+
+function stableReleaseExistsAtOrAboveOne(npmVersions: readonly string[] | string, gitTags: readonly string[] | string): boolean {
+  return [...collectStableVersions(npmVersions), ...collectStableVersions(gitTags)].some(
+    (version) => compareVersions(version, "1.0.0") >= 0,
+  );
+}
+
+function nextPrereleaseNumber(targetStable: string, npmVersions: readonly string[] | string, gitTags: readonly string[] | string): number {
+  const used = new Set<number>();
+
+  for (const rawVersion of [...normalizeVersionList(npmVersions), ...normalizeVersionList(gitTags)]) {
+    const version = stripGitTagPrefix(rawVersion);
+    const parsed = parseVersion(version);
+    if (!parsed || `${parsed.major}.${parsed.minor}.${parsed.patch}` !== targetStable) {
+      continue;
+    }
+
+    const prerelease = parsed.prerelease;
+    if (!prerelease) {
+      continue;
+    }
+
+    const match = prerelease.match(DEV_PRERELEASE);
+    if (!match) {
+      continue;
+    }
+
+    used.add(Number(match[1]));
+  }
+
+  let next = 0;
+  while (used.has(next)) {
+    next += 1;
+  }
+
+  return next;
+}
+
+export function computeReleaseVersion({ branch, bump, npmVersions, gitTags }: ReleaseVersionRequest): string {
+  const baseStable = highestStableVersion(npmVersions, gitTags);
+  let targetStable = incStable(baseStable, bump);
+
+  if (!stableReleaseExistsAtOrAboveOne(npmVersions, gitTags)) {
+    targetStable = compareVersions(targetStable, "1.0.0") < 0 ? "1.0.0" : targetStable;
+  }
+
+  if (branch === "main") {
+    return targetStable;
+  }
+
+  const prereleaseNumber = nextPrereleaseNumber(targetStable, npmVersions, gitTags);
+  return `${targetStable}-dev.${prereleaseNumber}`;
+}
+
+export const nextReleaseVersion = computeReleaseVersion;
+
+function isReleaseBranch(value: string): value is ReleaseBranch {
+  return value === "main" || value === "dev";
+}
+
+function isVersionBump(value: string): value is VersionBump {
+  return value === "major" || value === "minor" || value === "patch";
+}
+
+function main(argv: string[]): void {
+  const [branch, bump, npmVersions, gitTags] = argv;
+
+  if (!branch || !bump || !npmVersions || !gitTags || !isReleaseBranch(branch) || !isVersionBump(bump)) {
+    throw new Error("Usage: version-helper <main|dev> <major|minor|patch> <npm-versions> <git-tags>");
+  }
+
+  process.stdout.write(computeReleaseVersion({ branch, bump, npmVersions, gitTags }));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main(process.argv.slice(2));
+}