@pageai/ralph-loop 1.7.0 → 1.8.0

package/.agent/STEERING.md

@@ -4,22 +4,41 @@
 
 This sandbox runs emulated aarch64 Linux. Apply as needed:
 
-- **Node >= 22 (if required):** Install nvm, persist to `/etc/sandbox-persistent.sh` with `unset NPM_CONFIG_PREFIX` before
-the nvm source line. Never add bash_completion to that file.
-
-- **Native binary SIGILL crashes (npm):** `npm install` may produce broken arm64 binaries (esbuild, rollup, tailwindcss oxide, unrs resolver, etc). Fix: `npm pack <pkg>@<same-version>`, extract tarball, copy the binary over the installed one.
-
-- **If using TanStack Start:** Check that `src/integrations/tanstack-query/root-provider.tsx` has a default export
-  wrapping children with `QueryClientProvider`. The starter template ships without it, causing a 500 on load.
-
-- **If using any React-based project:** Install all shadcn/ui components: run npx shadcn@latest add --all in the project root (where components.json exists). Accept all defaults when prompted.
+- **Node >= 22 (if required):** Install nvm, persist to `/etc/sandbox-persistent.sh` with `unset NPM_CONFIG_PREFIX` before the nvm source line. Never add bash_completion to that file.
+
+- **Native binary SIGILL crashes (npm):** `npm install` will produce broken arm64 binaries. Follow this exact sequence:
+
+  1. Run `npm install --ignore-scripts` (prevents SIGILL during install)
+  2. Fix **all** known native binaries — for each package below, run:
+     ```
+     cd /tmp && npm pack <pkg>@<version> && tar xzf <tarball> && cp package/<binary> <node_modules_path> && rm -rf package
+     ```
+     Known SIGILL packages (check versions in node_modules):
+     - `@esbuild/linux-arm64` → `bin/esbuild`
+     - `@rollup/rollup-linux-arm64-gnu` → `rollup.linux-arm64-gnu.node`
+     - `@tailwindcss/oxide-linux-arm64-gnu` → `tailwindcss-oxide.linux-arm64-gnu.node`
+     - `@unrs/resolver-binding-linux-arm64-gnu` → `resolver.linux-arm64-gnu.node`
+     - `lightningcss-linux-arm64-gnu` → `lightningcss.linux-arm64-gnu.node`
+  3. **Verify each binary** before proceeding: `node -e "require('<pkg>')"` (for esbuild, use `node_modules/@esbuild/linux-arm64/bin/esbuild --version` instead since it's a standalone binary, not a requireable module)
+  4. **Scan for corrupted files** — `--ignore-scripts` can produce JS files with null bytes:
+     ```
+     find node_modules -name '*.js' -size +50k | while read f; do
+       if od -c "$f" | grep -q '\\0'; then echo "CORRUPT: $f"; fi
+     done
+     ```
+     Fix: `rm -rf node_modules/<corrupt-pkg> && npm install --ignore-scripts`
+     Re-scan until clean. Only then start the dev server.
+
+- **If using TanStack Start:** Check that `src/integrations/tanstack-query/root-provider.tsx` has a default export wrapping children with `QueryClientProvider`. The starter template ships without it, causing a 500 on load.
 
 ## Main Tasks
 
-Install dependencies, then install Playwright system dependencies: `sudo npx playwright install-deps chromium 2>&1`
+Install dependencies (using the sequence above), then install Playwright system dependencies: `sudo npx playwright install-deps chromium 2>&1`. Allow up to 10 minutes for tasks to complete.
+
+Then install the Playwright browser: `npx playwright install chromium`
 
 Start the dev server and take a screenshot. Save it to the `.agent/screenshots` directory.
 
 ---
 
-After you complete this work, exit with message `Steering complete`.
+After you finish this work, exit with message `Steering complete`.

package/.mcp.json

@@ -8,6 +8,7 @@
         "@playwright/mcp@latest",
         "--headless",
         "--no-sandbox",
+        "--install",
         "--executable-path",
         "/home/agent/.cache/ms-playwright/chromium-1208/chrome-linux/chrome"
       ],

package/README.md

@@ -12,7 +12,7 @@ This is an implementation that actually works, containing a hackable script so y
   - [2️⃣ Step 2: Create a PRD + task list](#2️⃣-step-2-create-a-prd--task-list)
   - [3️⃣ Step 3: Set up the agent inside Docker sandbox](#3️⃣-step-3-set-up-the-agent-inside-docker-sandbox)
   - [4️⃣ Step 4: Run Ralph](#4️⃣-step-4-run-ralph)
-- [Run the loop](#run-the-loop)
+- [Running the Ralph Loop with custom options](#running-the-ralph-loop-with-custom-options)
   - [(Optional) Adjusting to your language/framework](#optional-adjusting-to-your-languageframework)
 - [How It Works](#how-it-works)
 - [How Is This Different from Other Ralphs?](#how-is-this-different-from-other-ralphs)
@@ -41,7 +41,7 @@ This is an implementation that actually works, containing a hackable script so y
 I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:
 
 ```bash
-npx @tanstack/cli create lib --add-ons shadcn,eslint,form,tanstack-query --no-git --no-install
+npx @tanstack/cli create lib --add-ons shadcn,eslint,form,tanstack-query --no-git
 ```
 
 > If you must start from a blank slate, which is not recommended, see [Starting from scratch](#starting-from-scratch). You can also go for a more barebone start by running `npx create-vite@latest src --template react-ts`
@@ -115,7 +115,9 @@ And follow the instructions to log in into Claude Code.
 ./ralph.sh -n 50 # Run Ralph Loop with 50 iterations
 ```
 
-## Run the loop
+> ✍️ Note: the first iteration will be spent on ensuring the sandbox environment is set up correctly. Expect 5 minutes to complete.
+
+## Running the Ralph Loop with custom options
 
 ```bash
 # Run the agent loop (default: 10 iterations)

package/bin/cli.js

@@ -152,15 +152,6 @@ async function main() {
 
   display.printLocation(TARGET_DIR);
 
-  // Initialize git repository if not present
-  if (!isGitRepo(TARGET_DIR)) {
-    try {
-      initGitRepo(TARGET_DIR);
-    } catch {
-      // Non-critical — continue setup even if git init fails
-    }
-  }
-
   // Copy individual files
   display.printStep('📄', 'Core files');
   for (const file of FILES_TO_COPY) {
@@ -344,14 +335,32 @@ async function main() {
     }
   }
 
-  // Install all shadcn/ui components if project uses shadcn
+  // Final setup steps (git init, shadcn install)
   const appDirPath = path.join(TARGET_DIR, appDir);
-  if (isShadcnProject(appDirPath)) {
-    try {
-      installAllComponents(appDirPath);
-    } catch {
-      // Non-critical — continue setup even if shadcn install fails
+  const needsGit = !isGitRepo(TARGET_DIR);
+  const needsShadcn = isShadcnProject(appDirPath);
+
+  if (needsGit || needsShadcn) {
+    const s = clack.spinner();
+    s.start('Finishing up...');
+
+    if (needsGit) {
+      try {
+        initGitRepo(TARGET_DIR);
+      } catch {
+        // Non-critical — continue setup even if git init fails
+      }
+    }
+
+    if (needsShadcn) {
+      try {
+        installAllComponents(appDirPath);
+      } catch {
+        // Non-critical — continue setup even if shadcn install fails
+      }
     }
+
+    s.stop('Done');
   }
 
   // Success message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pageai/ralph-loop",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/assets/playwright.config.ts

@@ -14,6 +14,7 @@ export default defineConfig({
   use: {
     baseURL: 'http://localhost:3000',
     trace: 'on-first-retry',
+    viewport: { width: 1366, height: 768 },
   },