ralph-cli-sandboxed 0.4.2 → 0.5.0

package/dist/utils/config.js

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
-import { getCliProviders } from "../templates/prompts.js";
+import { getCliProviders, DEFAULT_PRD_YAML, DEFAULT_PROGRESS } from "../templates/prompts.js";
 export const DEFAULT_CLI_CONFIG = {
     command: "claude",
     args: [],
@@ -41,8 +41,70 @@ export function getCliConfig(config) {
 const RALPH_DIR = ".ralph";
 const CONFIG_FILE = "config.json";
 const PROMPT_FILE = "prompt.md";
-const PRD_FILE = "prd.json";
+const PRD_FILE_JSON = "prd.json";
+const PRD_FILE_YAML = "prd.yaml";
 const PROGRESS_FILE = "progress.txt";
+/**
+ * Gets the PRD file path(s) that exist.
+ * Returns an object with:
+ * - primary: The main PRD file path to use (yaml preferred over json)
+ * - secondary: The secondary PRD file path if both exist (for merging)
+ * - jsonOnly: True if only prd.json exists (shows migration notice)
+ * - yamlOnly: True if only prd.yaml exists (happy path)
+ * - both: True if both files exist (merge mode)
+ * - none: True if no PRD file exists
+ */
+export function getPrdFiles() {
+    const ralphDir = getRalphDir();
+    const jsonPath = join(ralphDir, PRD_FILE_JSON);
+    const yamlPath = join(ralphDir, PRD_FILE_YAML);
+    const hasJson = existsSync(jsonPath);
+    const hasYaml = existsSync(yamlPath);
+    if (hasYaml && hasJson) {
+        // Both exist - merge mode (YAML is primary)
+        return {
+            primary: yamlPath,
+            secondary: jsonPath,
+            jsonOnly: false,
+            yamlOnly: false,
+            both: true,
+            none: false,
+        };
+    }
+    else if (hasYaml) {
+        // Only YAML exists - happy path
+        return {
+            primary: yamlPath,
+            secondary: null,
+            jsonOnly: false,
+            yamlOnly: true,
+            both: false,
+            none: false,
+        };
+    }
+    else if (hasJson) {
+        // Only JSON exists - show migration notice
+        return {
+            primary: jsonPath,
+            secondary: null,
+            jsonOnly: true,
+            yamlOnly: false,
+            both: false,
+            none: false,
+        };
+    }
+    else {
+        // No PRD file exists
+        return {
+            primary: null,
+            secondary: null,
+            jsonOnly: false,
+            yamlOnly: false,
+            both: false,
+            none: true,
+        };
+    }
+}
 export function getRalphDir() {
     return join(process.cwd(), RALPH_DIR);
 }
@@ -66,20 +128,38 @@ export function checkFilesExist() {
     if (!existsSync(ralphDir)) {
         throw new Error(".ralph/ directory not found. Run 'ralph init' first.");
     }
-    const requiredFiles = [CONFIG_FILE, PROMPT_FILE, PRD_FILE, PROGRESS_FILE];
+    // Check config and prompt files (these are critical and must exist)
+    const requiredFiles = [CONFIG_FILE, PROMPT_FILE];
     for (const file of requiredFiles) {
         if (!existsSync(join(ralphDir, file))) {
             throw new Error(`.ralph/${file} not found. Run 'ralph init' first.`);
         }
     }
+    // Create progress.txt if it doesn't exist (user may have cleaned up)
+    const progressPath = join(ralphDir, PROGRESS_FILE);
+    if (!existsSync(progressPath)) {
+        writeFileSync(progressPath, DEFAULT_PROGRESS);
+        console.log(`Created ${progressPath}`);
+    }
+    // Create prd.yaml if no PRD file exists (user may have cleaned up)
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
+        const prdPath = join(ralphDir, PRD_FILE_YAML);
+        writeFileSync(prdPath, DEFAULT_PRD_YAML);
+        console.log(`Created ${prdPath}`);
+    }
 }
 export function getPaths() {
     const ralphDir = getRalphDir();
+    const prdFiles = getPrdFiles();
+    // Use the primary PRD file path (yaml preferred over json, fallback to json for backwards compat)
+    const prdPath = prdFiles.primary || join(ralphDir, PRD_FILE_JSON);
     return {
         dir: ralphDir,
         config: join(ralphDir, CONFIG_FILE),
         prompt: join(ralphDir, PROMPT_FILE),
-        prd: join(ralphDir, PRD_FILE),
+        prd: prdPath,
+        prdSecondary: prdFiles.secondary, // Second PRD file if merging
         progress: join(ralphDir, PROGRESS_FILE),
     };
 }

package/dist/utils/prd-validator.d.ts

@@ -40,11 +40,13 @@ export declare function smartMerge(original: PrdEntry[], corrupted: unknown): Me
 export declare function attemptRecovery(corrupted: unknown): PrdEntry[] | null;
 /**
  * Creates a timestamped backup of the PRD file.
+ * Preserves the original file extension (.json or .yaml/.yml).
  * Returns the backup path.
  */
 export declare function createBackup(prdPath: string): string;
 /**
  * Finds the most recent backup file.
+ * Searches for both .json and .yaml/.yml backup files.
  * Returns the path or null if no backups exist.
  */
 export declare function findLatestBackup(prdPath: string): string | null;
@@ -55,7 +57,16 @@ export declare function findLatestBackup(prdPath: string): string | null;
  */
 export declare function createTemplatePrd(backupPath?: string): PrdEntry[];
 /**
- * Reads and parses a PRD file, handling potential JSON errors.
+ * Reads and parses a YAML PRD file.
+ * Returns the parsed content or null if it couldn't be parsed.
+ */
+export declare function readYamlPrdFile(prdPath: string): {
+    content: unknown;
+    raw: string;
+} | null;
+/**
+ * Reads and parses a PRD file, handling potential JSON/YAML errors.
+ * Detects file format based on extension (.yaml/.yml uses YAML, .json uses JSON).
  * Returns the parsed content or null if it couldn't be parsed.
  */
 export declare function readPrdFile(prdPath: string): {
@@ -63,9 +74,17 @@ export declare function readPrdFile(prdPath: string): {
     raw: string;
 } | null;
 /**
- * Writes a PRD to file.
+ * Writes a PRD to file in JSON format.
  */
 export declare function writePrd(prdPath: string, entries: PrdEntry[]): void;
+/**
+ * Writes a PRD to file in YAML format.
+ */
+export declare function writePrdYaml(prdPath: string, entries: PrdEntry[]): void;
+/**
+ * Writes a PRD to file, detecting format from file extension.
+ */
+export declare function writePrdAuto(prdPath: string, entries: PrdEntry[]): void;
 /**
  * Expands @{filepath} patterns in a string with actual file contents.
  * Similar to curl's @ syntax for including file contents.

package/dist/utils/prd-validator.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, extname } from "path";
+import YAML from "yaml";
 const VALID_CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
 /**
  * Validates that a PRD structure is correct.
@@ -340,18 +341,23 @@ function attemptArrayRecovery(items) {
 }
 /**
  * Creates a timestamped backup of the PRD file.
+ * Preserves the original file extension (.json or .yaml/.yml).
  * Returns the backup path.
  */
 export function createBackup(prdPath) {
     const content = readFileSync(prdPath, "utf-8");
     const dir = dirname(prdPath);
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const backupPath = join(dir, `backup.prd.${timestamp}.json`);
+    const ext = extname(prdPath).toLowerCase();
+    // Preserve original extension, default to .json if unknown
+    const backupExt = ext === ".yaml" || ext === ".yml" ? ext : ".json";
+    const backupPath = join(dir, `backup.prd.${timestamp}${backupExt}`);
     writeFileSync(backupPath, content);
     return backupPath;
 }
 /**
  * Finds the most recent backup file.
+ * Searches for both .json and .yaml/.yml backup files.
  * Returns the path or null if no backups exist.
  */
 export function findLatestBackup(prdPath) {
@@ -361,7 +367,8 @@ export function findLatestBackup(prdPath) {
     }
     const files = readdirSync(dir);
     const backups = files
-        .filter((f) => f.startsWith("backup.prd.") && f.endsWith(".json"))
+        .filter((f) => f.startsWith("backup.prd.") &&
+        (f.endsWith(".json") || f.endsWith(".yaml") || f.endsWith(".yml")))
         .sort()
         .reverse();
     if (backups.length === 0) {
@@ -384,7 +391,7 @@ export function createTemplatePrd(backupPath) {
                 description: "Fix the PRD entries",
                 steps: [
                     `Recreate PRD entries based on this corrupted backup content:\n\n@{${absolutePath}}`,
-                    "Write valid entries to .ralph/prd.json with format: category (string), description (string), steps (array of strings), passes (boolean)",
+                    "Write valid entries to .ralph/prd.yaml with format: category (string), description (string), steps (array of strings), passes (boolean)",
                 ],
                 passes: false,
             },
@@ -395,7 +402,7 @@ export function createTemplatePrd(backupPath) {
             category: "setup",
             description: "Add PRD entries",
             steps: [
-                "Add requirements using 'ralph add' or edit .ralph/prd.json directly",
+                "Add requirements using 'ralph add' or edit .ralph/prd.yaml directly",
                 "Verify format: category (string), description (string), steps (array of strings), passes (boolean)",
             ],
             passes: false,
@@ -403,13 +410,37 @@ export function createTemplatePrd(backupPath) {
     ];
 }
 /**
- * Reads and parses a PRD file, handling potential JSON errors.
+ * Reads and parses a YAML PRD file.
+ * Returns the parsed content or null if it couldn't be parsed.
+ */
+export function readYamlPrdFile(prdPath) {
+    try {
+        const raw = readFileSync(prdPath, "utf-8");
+        const content = YAML.parse(raw);
+        return { content, raw };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reads and parses a PRD file, handling potential JSON/YAML errors.
+ * Detects file format based on extension (.yaml/.yml uses YAML, .json uses JSON).
  * Returns the parsed content or null if it couldn't be parsed.
  */
 export function readPrdFile(prdPath) {
     try {
         const raw = readFileSync(prdPath, "utf-8");
-        const content = JSON.parse(raw);
+        const ext = extname(prdPath).toLowerCase();
+        // Parse based on file extension
+        let content;
+        if (ext === ".yaml" || ext === ".yml") {
+            content = YAML.parse(raw);
+        }
+        else {
+            // Default to JSON for .json or any other extension
+            content = JSON.parse(raw);
+        }
         return { content, raw };
     }
     catch {
@@ -417,17 +448,39 @@ export function readPrdFile(prdPath) {
     }
 }
 /**
- * Writes a PRD to file.
+ * Writes a PRD to file in JSON format.
  */
 export function writePrd(prdPath, entries) {
     writeFileSync(prdPath, JSON.stringify(entries, null, 2) + "\n");
 }
+/**
+ * Writes a PRD to file in YAML format.
+ */
+export function writePrdYaml(prdPath, entries) {
+    writeFileSync(prdPath, YAML.stringify(entries));
+}
+/**
+ * Writes a PRD to file, detecting format from file extension.
+ */
+export function writePrdAuto(prdPath, entries) {
+    const ext = extname(prdPath).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+        writePrdYaml(prdPath, entries);
+    }
+    else {
+        writePrd(prdPath, entries);
+    }
+}
 /**
  * Expands @{filepath} patterns in a string with actual file contents.
  * Similar to curl's @ syntax for including file contents.
  * Paths are resolved relative to the .ralph directory.
  */
 export function expandFileReferences(text, baseDir) {
+    // Handle null/undefined text
+    if (typeof text !== "string") {
+        return text ?? "";
+    }
     // Match @{filepath} patterns
     const pattern = /@\{([^}]+)\}/g;
     return text.replace(pattern, (match, filepath) => {

package/docs/HOW-TO-WRITE-PRDs.md

@@ -4,19 +4,16 @@ This guide explains how to write Product Requirement Documents (PRDs) that Ralph
 
 ## PRD Structure
 
-Each PRD item is a JSON object with four fields:
-
-```json
-{
-  "category": "feature",
-  "description": "Short imperative description of what to implement",
-  "steps": [
-    "First concrete action to take",
-    "Second concrete action to take",
-    "Verification step to confirm completion"
-  ],
-  "passes": false
-}
+Each PRD entry is a YAML object with four fields:
+
+```yaml
+- category: feature
+  description: Short imperative description of what to implement
+  steps:
+    - First concrete action to take
+    - Second concrete action to take
+    - Verification step to confirm completion
+  passes: false
 ```
 
 ## Categories
@@ -74,90 +71,80 @@ Steps tell the AI agent exactly **how** to verify or implement the requirement.
 ### Step Patterns
 
 **For features:**
-```json
-"steps": [
-  "Implement X in src/path/file.ts",
-  "Add Y functionality that does Z",
-  "Run `command` and confirm expected output"
-]
+```yaml
+steps:
+  - Implement X in src/path/file.ts
+  - Add Y functionality that does Z
+  - Run `command` and confirm expected output
 ```
 
 **For bug fixes:**
-```json
-"steps": [
-  "Identify the cause of X in src/path/file.ts",
-  "Fix by doing Y",
-  "Run `command` and verify the bug is resolved"
-]
+```yaml
+steps:
+  - Identify the cause of X in src/path/file.ts
+  - Fix by doing Y
+  - Run `command` and verify the bug is resolved
 ```
 
 **For documentation:**
-```json
-"steps": [
-  "Add section 'X' to README.md",
-  "Include explanation of Y",
-  "Include example showing Z"
-]
+```yaml
+steps:
+  - Add section 'X' to README.md
+  - Include explanation of Y
+  - Include example showing Z
 ```
 
 **For releases:**
-```json
-"steps": [
-  "Update version in package.json to 'X.Y.Z'",
-  "Run `npm run build` to verify no errors",
-  "Run `command --version` and confirm it shows X.Y.Z"
-]
+```yaml
+steps:
+  - Update version in package.json to 'X.Y.Z'
+  - Run `npm run build` to verify no errors
+  - Run `command --version` and confirm it shows X.Y.Z
 ```
 
 ## Anti-Patterns to Avoid
 
 ### Vague Steps
-```json
-// Bad
-"steps": [
-  "Make it work",
-  "Test it",
-  "Verify it's good"
-]
-
-// Good
-"steps": [
-  "Add error handling for null input in parseConfig()",
-  "Run `npm test` and confirm all tests pass",
-  "Run `ralph init` with missing config and verify helpful error message"
-]
+```yaml
+# Bad
+steps:
+  - Make it work
+  - Test it
+  - Verify it's good
+
+# Good
+steps:
+  - Add error handling for null input in parseConfig()
+  - Run `npm test` and confirm all tests pass
+  - Run `ralph init` with missing config and verify helpful error message
 ```
 
 ### Steps That Require Human Judgment
-```json
-// Bad
-"steps": [
-  "Understand the codebase",
-  "Decide the best approach",
-  "Implement your solution"
-]
-
-// Good
-"steps": [
-  "Add retry logic with exponential backoff to fetchData() in src/api.ts",
-  "Set max retries to 3 with initial delay of 1000ms",
-  "Run `npm test` and verify retry tests pass"
-]
+```yaml
+# Bad
+steps:
+  - Understand the codebase
+  - Decide the best approach
+  - Implement your solution
+
+# Good
+steps:
+  - Add retry logic with exponential backoff to fetchData() in src/api.ts
+  - Set max retries to 3 with initial delay of 1000ms
+  - Run `npm test` and verify retry tests pass
 ```
 
 ### Missing Verification
-```json
-// Bad
-"steps": [
-  "Update the version number"
-]
-
-// Good
-"steps": [
-  "Update version in package.json to '1.2.3'",
-  "Run `npm run build` to verify no errors",
-  "Run `ralph --version` and confirm output shows '1.2.3'"
-]
+```yaml
+# Bad
+steps:
+  - Update the version number
+
+# Good
+steps:
+  - Update version in package.json to '1.2.3'
+  - Run `npm run build` to verify no errors
+  - Run `ralph --version` and confirm output shows '1.2.3'
 ```
 
 ## Priority Through Ordering
@@ -176,39 +163,34 @@ Recommended ordering:
 
 Break large features into smaller, independently completable items. Each item should be achievable in a single Ralph iteration.
 
-```json
-// Too large
-{
-  "description": "Implement user authentication system",
-  "steps": ["Add login, logout, registration, password reset, OAuth..."]
-}
-
-// Better: Split into multiple items
-{
-  "description": "Add user registration endpoint POST /api/register",
-  "steps": [...]
-},
-{
-  "description": "Add user login endpoint POST /api/login",
-  "steps": [...]
-},
-{
-  "description": "Add JWT token generation and validation",
-  "steps": [...]
-}
+```yaml
+# Too large
+- description: Implement user authentication system
+  steps:
+    - Add login, logout, registration, password reset, OAuth...
+
+# Better: Split into multiple items
+- description: Add user registration endpoint POST /api/register
+  steps:
+    - ...
+
+- description: Add user login endpoint POST /api/login
+  steps:
+    - ...
+
+- description: Add JWT token generation and validation
+  steps:
+    - ...
 ```
 
 ## Quick Reference
 
-```json
-{
-  "category": "setup|feature|bugfix|refactor|docs|test|release|config|ui|integration",
-  "description": "Imperative verb + specific what + where (context)",
-  "steps": [
-    "Concrete action with `commands` and file paths",
-    "Another specific action",
-    "Verification: Run `command` and confirm expected result"
-  ],
-  "passes": false
-}
+```yaml
+- category: setup|feature|bugfix|refactor|docs|test|release|config|ui|integration
+  description: Imperative verb + specific what + where (context)
+  steps:
+    - Concrete action with `commands` and file paths
+    - Another specific action
+    - Verification: Run `command` and confirm expected result
+  passes: false
 ```