@pageai/ralph-loop 1.6.0 → 1.8.0

package/.agent/STEERING.md

@@ -1,6 +1,44 @@
 # **Critical Steering Work**
 
-Go to the source code directory and install dependencies.
+## Ensure the sandbox is running correctly
 
-Check that Playwright is installed, then start the dev server and take a screenshot.
-Save the screenshot to the .agent/screenshots directory.
+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` 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 (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 finish this work, exit with message `Steering complete`.

package/.mcp.json

@@ -6,7 +6,11 @@
       "args": [
         "-y",
         "@playwright/mcp@latest",
-        "--headless"
+        "--headless",
+        "--no-sandbox",
+        "--install",
+        "--executable-path",
+        "/home/agent/.cache/ms-playwright/chromium-1208/chrome-linux/chrome"
       ],
       "env": {}
     },

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)
@@ -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

@@ -12,6 +12,7 @@ const { execSync } = require('child_process');
 const display = require('./lib/display');
 const { copyFile, copyDir, mergeDir, exists, ensureDir } = require('./lib/copy');
 const { isGitRepo, initGitRepo } = require('./lib/git');
+const { isShadcnProject, installAllComponents } = require('./lib/shadcn');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TARGET_DIR = process.cwd();
@@ -151,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) {
@@ -343,6 +335,34 @@ async function main() {
     }
   }
 
+  // Final setup steps (git init, shadcn install)
+  const appDirPath = path.join(TARGET_DIR, appDir);
+  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
   display.showComplete();
   clack.outro('Happy looping!');

package/bin/lib/shadcn.js

@@ -0,0 +1,44 @@
+/**
+ * shadcn/ui module for Ralph Loop CLI
+ * Detects shadcn config and installs all components
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { exists } = require('./copy');
+
+const SHADCN_SCHEMA = 'https://ui.shadcn.com/schema.json';
+
+/**
+ * Checks if a directory has a shadcn components.json with the expected schema
+ * @param {string} dir - Directory path to check
+ * @returns {boolean}
+ */
+function isShadcnProject(dir) {
+  const configPath = path.join(dir, 'components.json');
+  if (!exists(configPath)) return false;
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    return config.$schema === SHADCN_SCHEMA;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Installs all shadcn/ui components in the given directory
+ * @param {string} dir - Directory path to run the install in
+ */
+function installAllComponents(dir) {
+  execSync('npx shadcn@latest add --all --yes 2>&1', {
+    cwd: dir,
+    stdio: 'pipe',
+  });
+}
+
+module.exports = {
+  isShadcnProject,
+  installAllComponents,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pageai/ralph-loop",
-  "version": "1.6.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 },
   },