@canivel/ralph 0.2.0

package/skills/dev-browser/src/snapshot/index.ts

@@ -0,0 +1,14 @@
+/**
+ * ARIA Snapshot module for dev-browser.
+ *
+ * Provides Playwright-compatible ARIA snapshots with cross-connection ref persistence.
+ * Refs are stored on window.__devBrowserRefs and survive across Playwright reconnections.
+ *
+ * Usage:
+ *   import { getSnapshotScript } from './snapshot';
+ *   const script = getSnapshotScript();
+ *   await page.evaluate(script);
+ *   // Now window.__devBrowser_getAISnapshot() and window.__devBrowser_selectSnapshotRef(ref) are available
+ */
+
+export { getSnapshotScript, clearSnapshotScriptCache } from "./browser-script";

package/skills/dev-browser/src/snapshot/inject.ts

@@ -0,0 +1,13 @@
+/**
+ * Injectable snapshot script for browser context.
+ *
+ * This module provides the getSnapshotScript function that returns a
+ * self-contained JavaScript string for injection into browser contexts.
+ *
+ * The script is injected via page.evaluate() and exposes:
+ * - window.__devBrowser_getAISnapshot(): Returns ARIA snapshot YAML
+ * - window.__devBrowser_selectSnapshotRef(ref): Returns element for given ref
+ * - window.__devBrowserRefs: Map of ref -> Element (persists across connections)
+ */
+
+export { getSnapshotScript, clearSnapshotScriptCache } from "./browser-script";

package/skills/dev-browser/src/types.ts

@@ -0,0 +1,34 @@
+// API request/response types - shared between client and server
+
+export interface ServeOptions {
+  port?: number;
+  headless?: boolean;
+  cdpPort?: number;
+  /** Directory to store persistent browser profiles (cookies, localStorage, etc.) */
+  profileDir?: string;
+}
+
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+
+export interface GetPageRequest {
+  name: string;
+  /** Optional viewport size for new pages */
+  viewport?: ViewportSize;
+}
+
+export interface GetPageResponse {
+  wsEndpoint: string;
+  name: string;
+  targetId: string; // CDP target ID for reliable page matching
+}
+
+export interface ListPagesResponse {
+  pages: string[];
+}
+
+export interface ServerInfoResponse {
+  wsEndpoint: string;
+}

package/skills/dev-browser/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Path aliases
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src/**/*", "scripts/**/*"]
+}

package/skills/dev-browser/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    testTimeout: 60000, // Playwright tests can be slow
+    hookTimeout: 60000,
+    teardownTimeout: 60000,
+  },
+});

package/skills/prd/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: prd
+description: "Generate a Product Requirements Document (PRD) as JSON for Ralph. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out."
+---
+
+# PRD Generator (JSON Only)
+
+Create a structured JSON PRD that Ralph can execute deterministically. This PRD is the **single source of truth** for stories, gates, and status.
+
+---
+
+## The Job
+
+1. Receive a feature description from the user
+2. Ask **5–10** clarifying questions (with lettered options), in batches of up to 5 at a time (ask 5, wait for answers, then ask the next batch if needed).
+3. **Always ask about quality gates** (commands that must pass)
+4. Generate a **detailed** JSON PRD and save it to the provided path
+
+**Important:** Do NOT implement anything. Only generate JSON.
+
+---
+
+## Step 1: Clarifying Questions
+
+Ask questions even if the prompt seems clear. The goal is to capture missing product details, stack choices, and UI/route structure so the PRD is implementable without guesswork. Focus on:
+
+- **Problem/Goal:** What problem does this solve?
+- **Core Functionality:** What are the key actions?
+- **Scope/Boundaries:** What should it NOT do?
+- **Success Criteria:** How do we know it's done?
+- **Stack + Environment:** frameworks, hosting, runtime, database, auth approach
+- **UI + Routes:** key screens, navigation, route map, layout constraints
+- **Data Model + Import Format:** entities, relationships, external data shape
+- **Rules/Calculations:** business logic, progression rules, edge cases
+- **Quality Gates:** tests, lint, typecheck, build/dev verification (REQUIRED)
+
+Always ask explicitly:
+- **Is this a new project or an existing codebase?**
+
+### Format Questions Like This:
+
+```
+1. What is the primary goal of this feature?
+   A. Improve user onboarding experience
+   B. Increase user retention
+   C. Reduce support burden
+   D. Other: [please specify]
+
+2. Who is the target user?
+   A. New users only
+   B. Existing users only
+   C. All users
+   D. Admin users only
+
+3. What quality commands must pass for each story?
+   A. npm test
+   B. npm run lint
+   C. npm run typecheck
+   D. Other: [specify]
+
+Note: All example questions and options in this section are illustrative only. Do not copy them verbatim into the PRD unless the user explicitly chooses them. Derive the final quality gates and requirements from the user's answers and the feature context.
+
+4. What stack + hosting are we using (and any constraints)?
+   A. React + Vite (static hosting)
+   B. Next.js (Node/Edge)
+   C. TanStack Start (Cloudflare)
+   D. Other: [specify]
+
+5. What UI screens/routes are required?
+   A. Minimal (1–2 pages)
+   B. Basic app shell (dashboard + detail pages)
+   C. Full routing map (list all routes)
+   D. Other: [specify]
+```
+
+---
+
+## Step 2: JSON Structure
+
+Output a JSON file with this shape (include detailed top-level fields so the PRD is fully self-contained):
+
+```json
+{
+  "version": 1,
+  "project": "Feature Name",
+  "overview": "Short problem + solution summary",
+  "goals": [
+    "Goal 1",
+    "Goal 2"
+  ],
+  "nonGoals": [
+    "Explicitly out of scope items"
+  ],
+  "successMetrics": [
+    "How success is measured"
+  ],
+  "openQuestions": [
+    "Remaining unknowns"
+  ],
+  "stack": {
+    "framework": "TanStack Start",
+    "hosting": "Cloudflare",
+    "database": "D1",
+    "auth": "describe approach"
+  },
+  "routes": [
+    { "path": "/", "name": "Home", "purpose": "..." }
+  ],
+  "uiNotes": [
+    "Layout or component requirements"
+  ],
+  "dataModel": [
+    { "entity": "Workout", "fields": ["id", "userId", "date", "notes"] }
+  ],
+  "importFormat": {
+    "description": "Expected JSON shape",
+    "example": { "programName": "..." }
+  },
+  "rules": [
+    "Key business rules / calculations"
+  ],
+  "qualityGates": ["npm run test:ping"],
+  "stories": [
+    {
+      "id": "US-001",
+      "title": "Short story title",
+      "status": "open",
+      "dependsOn": [],
+      "description": "As a [user], I want [feature] so that [benefit].",
+      "acceptanceCriteria": [
+        "Specific verifiable criterion",
+        "Another criterion"
+      ]
+    }
+  ]
+}
+```
+
+### Rules
+- **IDs**: Sequential (`US-001`, `US-002`, ...)
+- **Status**: Always `"open"` for new stories
+- **DependsOn**: Use IDs only; empty array if none
+- **Quality Gates**: Only at the top-level `qualityGates`
+- **Acceptance Criteria**: Verifiable, specific, testable
+- **Every story must include**: at least 1 example + 1 negative case
+- **UI stories**: include explicit routes, components, and UI states
+- **New projects**: include initial setup stories (scaffold, env/config, local dev, deploy basics, **package installs**)
+- **Dependencies**: any new package/library introduced must be called out with install commands in acceptance criteria (e.g., `npm install <pkg>`), plus any required config or scripts.
+- **Ordering**: if this is a new project, the **first story must be setup** (scaffold + installs + scripts + env/config). Migrations or data model work come after setup.
+
+---
+
+## Output Requirements
+
+- Save the JSON to the exact path provided in the prompt (e.g., `.agents/tasks/prd-<slug>.json`)
+- Output **only** the JSON file content (no Markdown PRD)
+- Do not include extra commentary in the file
+
+After saving, tell the user:
+`PRD JSON saved to <path>. Close this chat and run \`ralph build\`.`
+
+If the prompt provides a **directory** (not a filename), choose a short filename:
+- `prd-<short-slug>.json` where `<short-slug>` is 1–3 meaningful words (avoid filler like “i want to”).
+- Examples: `prd-workout-tracker.json`, `prd-usage-billing.json`
+
+---
+
+## Story Size (Critical)
+
+Each story must be completable in a **single Ralph iteration**.
+If a story feels too large, split it into multiple smaller stories with dependencies.
+
+---
+
+## Example Output (JSON)
+
+```json
+{
+  "version": 1,
+  "project": "Task Priority System",
+  "overview": "Add priority levels to tasks so users can focus on what matters most.",
+  "goals": [
+    "Allow assigning priority (high/medium/low) to any task",
+    "Enable filtering by priority"
+  ],
+  "nonGoals": [
+    "No automatic priority assignment"
+  ],
+  "successMetrics": [
+    "Users can change priority in under 2 clicks"
+  ],
+  "openQuestions": [
+    "Should priority affect ordering within a column?"
+  ],
+  "stack": {
+    "framework": "React",
+    "hosting": "Cloudflare Pages",
+    "database": "D1",
+    "auth": "single shared login"
+  },
+  "routes": [
+    { "path": "/tasks", "name": "Task List", "purpose": "View and filter tasks" },
+    { "path": "/tasks/:id", "name": "Task Detail", "purpose": "Edit task priority" }
+  ],
+  "uiNotes": [
+    "Priority badge colors: high=red, medium=yellow, low=gray"
+  ],
+  "dataModel": [
+    { "entity": "Task", "fields": ["id", "title", "priority"] }
+  ],
+  "importFormat": {
+    "description": "Not applicable",
+    "example": {}
+  },
+  "rules": [
+    "Priority defaults to medium when not set"
+  ],
+  "qualityGates": ["npm run test:ping"],
+  "stories": [
+    {
+      "id": "US-001",
+      "title": "Add priority field to database",
+      "status": "open",
+      "dependsOn": [],
+      "description": "As a developer, I want to store task priority so it persists across sessions.",
+      "acceptanceCriteria": [
+        "Add priority column with default 'medium'",
+        "Example: creating a task without priority -> defaults to 'medium'",
+        "Negative case: invalid priority 'urgent' -> validation error",
+        "Migration runs successfully"
+      ]
+    }
+  ]
+}
+```

package/tests/agent-loops.mjs

@@ -0,0 +1,79 @@
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const repoRoot = path.resolve(new URL("..", import.meta.url).pathname);
+const cliPath = path.join(repoRoot, "bin", "ralph");
+
+function run(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, { stdio: "inherit", ...options });
+  if (result.status !== 0) {
+    console.error(`Command failed: ${cmd} ${args.join(" ")}`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+function commandExists(cmd) {
+  const result = spawnSync(`command -v ${cmd}`, { shell: true, stdio: "ignore" });
+  return result.status === 0;
+}
+
+function setupTempProject() {
+  const base = mkdtempSync(path.join(tmpdir(), "ralph-smoke-"));
+  mkdirSync(path.join(base, ".agents", "tasks"), { recursive: true });
+  mkdirSync(path.join(base, ".ralph"), { recursive: true });
+  const prd = {
+    version: 1,
+    project: "Smoke Test",
+    qualityGates: [],
+    stories: [
+      {
+        id: "US-001",
+        title: "Smoke Test Story",
+        status: "open",
+        dependsOn: [],
+        acceptanceCriteria: [
+          "Example: input -> output",
+          "Negative case: bad input -> error",
+        ],
+      },
+    ],
+  };
+  writeFileSync(
+    path.join(base, ".agents", "tasks", "prd.json"),
+    `${JSON.stringify(prd, null, 2)}\n`,
+  );
+  return base;
+}
+
+const agents = ["codex", "claude", "droid"];
+const integration = process.env.RALPH_INTEGRATION === "1";
+
+for (const agent of agents) {
+  const projectRoot = setupTempProject();
+  try {
+    const env = { ...process.env };
+    if (!integration) {
+      env.RALPH_DRY_RUN = "1";
+    } else if (agent === "codex" && !commandExists("codex")) {
+      console.log(`Skipping codex integration test (missing codex).`);
+      continue;
+    } else if (agent === "claude" && !commandExists("claude")) {
+      console.log(`Skipping claude integration test (missing claude).`);
+      continue;
+    } else if (agent === "droid" && !commandExists("droid")) {
+      console.log(`Skipping droid integration test (missing droid).`);
+      continue;
+    }
+
+    run(process.execPath, [cliPath, "build", "1", "--no-commit", `--agent=${agent}`], {
+      cwd: projectRoot,
+      env,
+    });
+  } finally {
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+}
+
+console.log("Agent loop smoke tests passed.");

package/tests/agent-ping.mjs

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cliPath = path.join(repoRoot, "bin", "ralph");
+
+function run(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, { stdio: "inherit", ...options });
+  if (result.status !== 0) {
+    console.error(`Command failed: ${cmd} ${args.join(" ")}`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+const agents = [
+  { name: "codex", bin: "codex" },
+  { name: "claude", bin: "claude" },
+  { name: "droid", bin: "droid" },
+  { name: "opencode", bin: "opencode" },
+];
+const runnable = [];
+const skipped = [];
+for (const agent of agents) {
+  const check = spawnSync(`command -v ${agent.bin}`, { shell: true, stdio: "ignore" });
+  if (check.status === 0) {
+    runnable.push(agent.name);
+  } else {
+    skipped.push(agent.name);
+  }
+}
+if (skipped.length) {
+  console.log(`Skipping ping for missing agents: ${skipped.join(", ")}`);
+}
+for (const agent of runnable) {
+  run(process.execPath, [cliPath, "ping", `--agent=${agent}`]);
+}
+
+console.log("Agent ping tests passed.");

package/tests/audit.md

@@ -0,0 +1,56 @@
+# Ralph Test Coverage Audit
+
+## Scope reviewed
+- `bin/ralph`
+- `.agents/ralph/loop.sh`
+- `.agents/ralph/PROMPT_build.md`
+- `.agents/ralph/log-activity.sh`
+- `.agents/ralph/references/*`
+- `skills/*`
+- `tests/*`
+
+## Current test coverage
+
+### CLI
+- `tests/cli-smoke.mjs`
+  - Verifies `--help` output
+  - Verifies `ralph prd ... --out` creates a PRD JSON file (dry-run)
+  - Verifies `ralph overview --prd ...` creates an overview file
+
+### Loop (dry-run)
+- `tests/agent-loops.mjs`
+  - Runs `ralph build 1 --no-commit` with all agents using `RALPH_DRY_RUN=1`
+  - Confirms loops execute and log to stdout without real agent execution
+
+### Agent ping (fast, real)
+- `tests/agent-ping.mjs`
+  - Runs `ralph ping` for codex/claude/droid
+  - Verifies each agent responds with `<end>pong</end>`
+
+### Real integration (new)
+- `tests/real-agents.mjs`
+  - Creates a temp repo with a 2‑story JSON PRD and minimal AGENTS instructions
+  - Runs `ralph build 2 --agent=<codex|claude|droid>`
+  - Verifies:
+    - PRD stories are all marked `done`
+    - At least one git commit was created
+    - Progress log exists
+  - Cleans up the temp repo and logs after each agent run (pass or fail)
+
+## Gaps identified
+- **Interactive installs**: `ralph install` and `ralph install --skills` require prompts and are not exercised in automated tests.
+- **Skill installation paths**: Local vs global skill locations are not validated in tests.
+- **Failure logging**: `.ralph/errors.log` contents are not asserted.
+- **Activity logging**: Activity log presence is not asserted (only implied via run completion).
+- **Guardrails**: No test verifies that guardrails are created/updated.
+
+## Recommendations
+1. Keep default tests deterministic (`npm test`) and provide a separate real‑agent test (`npm run test:real`).
+2. Add a non‑interactive flag for skill install if you want it testable in CI.
+3. Add assertions for `.ralph/activity.log` and `.ralph/guardrails.md` creation in `tests/real-agents.mjs`.
+4. Consider adding coverage for PRD selection when multiple JSON files exist.
+
+## How to run
+- **Deterministic:** `npm test`
+- **Fast real agent check:** `npm run test:ping`
+- **Real agents:** `npm run test:real` (requires codex/claude/droid installed and authenticated)

package/tests/cli-smoke.mjs

@@ -0,0 +1,47 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function run(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, { stdio: "inherit", ...options });
+  if (result.status !== 0) {
+    console.error(`Command failed: ${cmd} ${args.join(" ")}`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cliPath = path.join(repoRoot, "bin", "ralph");
+
+run(process.execPath, [cliPath, "--help"]);
+
+const projectRoot = mkdtempSync(path.join(tmpdir(), "ralph-cli-"));
+try {
+  const outPath = path.join(projectRoot, "prd.json");
+  run(process.execPath, [cliPath, "prd", "Smoke test PRD", "--out", outPath], {
+    cwd: projectRoot,
+    env: { ...process.env, RALPH_DRY_RUN: "1" },
+  });
+
+  if (!existsSync(outPath)) {
+    console.error("PRD smoke test failed: output not created.");
+    process.exit(1);
+  }
+
+  run(process.execPath, [cliPath, "overview", "--prd", outPath], {
+    cwd: projectRoot,
+    env: { ...process.env },
+  });
+
+  const overviewPath = outPath.replace(/\.json$/i, ".overview.md");
+  if (!existsSync(overviewPath)) {
+    console.error("Overview smoke test failed: output not created.");
+    process.exit(1);
+  }
+} finally {
+  rmSync(projectRoot, { recursive: true, force: true });
+}
+
+console.log("CLI smoke test passed.");