ralph-cli-sandboxed 0.4.2 → 0.5.0

package/dist/commands/chat.js

@@ -3,9 +3,10 @@
  * Allows ralph to receive commands and send notifications via chat services.
  */
 import { existsSync, readFileSync, writeFileSync } from "fs";
-import { join, basename } from "path";
+import { join, basename, extname } from "path";
 import { spawn } from "child_process";
-import { loadConfig, getRalphDir, isRunningInContainer } from "../utils/config.js";
+import YAML from "yaml";
+import { loadConfig, getRalphDir, isRunningInContainer, getPrdFiles } from "../utils/config.js";
 import { createTelegramClient } from "../providers/telegram.js";
 import { createSlackClient } from "../providers/slack.js";
 import { createDiscordClient } from "../providers/discord.js";
@@ -53,18 +54,40 @@ function getOrCreateProjectId() {
 function getProjectName() {
     return basename(process.cwd());
 }
+/**
+ * Parse PRD file content based on file extension.
+ */
+function parsePrdContent(filePath, content) {
+    const ext = extname(filePath).toLowerCase();
+    try {
+        let parsed;
+        if (ext === ".yaml" || ext === ".yml") {
+            parsed = YAML.parse(content);
+        }
+        else {
+            parsed = JSON.parse(content);
+        }
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Get PRD status (completed/total tasks).
  */
 function getPrdStatus() {
-    const ralphDir = getRalphDir();
-    const prdPath = join(ralphDir, "prd.json");
-    if (!existsSync(prdPath)) {
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
         return { complete: 0, total: 0, incomplete: 0 };
     }
     try {
+        const prdPath = prdFiles.primary;
         const content = readFileSync(prdPath, "utf-8");
-        const items = JSON.parse(content);
+        const items = parsePrdContent(prdPath, content);
         if (!Array.isArray(items)) {
             return { complete: 0, total: 0, incomplete: 0 };
         }
@@ -81,14 +104,14 @@ function getPrdStatus() {
  * Returns unique categories that have at least one incomplete task.
  */
 function getOpenCategories() {
-    const ralphDir = getRalphDir();
-    const prdPath = join(ralphDir, "prd.json");
-    if (!existsSync(prdPath)) {
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
         return [];
     }
     try {
+        const prdPath = prdFiles.primary;
         const content = readFileSync(prdPath, "utf-8");
-        const items = JSON.parse(content);
+        const items = parsePrdContent(prdPath, content);
         if (!Array.isArray(items)) {
             return [];
         }
@@ -109,14 +132,14 @@ function getOpenCategories() {
  * Add a new task to the PRD.
  */
 function addPrdTask(description) {
-    const ralphDir = getRalphDir();
-    const prdPath = join(ralphDir, "prd.json");
-    if (!existsSync(prdPath)) {
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
         return false;
     }
     try {
+        const prdPath = prdFiles.primary;
         const content = readFileSync(prdPath, "utf-8");
-        const items = JSON.parse(content);
+        const items = parsePrdContent(prdPath, content);
         if (!Array.isArray(items)) {
             return false;
         }
@@ -126,7 +149,14 @@ function addPrdTask(description) {
             steps: [],
             passes: false,
         });
-        writeFileSync(prdPath, JSON.stringify(items, null, 2) + "\n");
+        // Write back in the same format as the source file
+        const ext = extname(prdPath).toLowerCase();
+        if (ext === ".yaml" || ext === ".yml") {
+            writeFileSync(prdPath, YAML.stringify(items));
+        }
+        else {
+            writeFileSync(prdPath, JSON.stringify(items, null, 2) + "\n");
+        }
         return true;
     }
     catch {

package/dist/commands/fix-prd.js

@@ -1,7 +1,8 @@
 import { existsSync, readFileSync, copyFileSync } from "fs";
-import { join, isAbsolute } from "path";
-import { getPaths, getRalphDir } from "../utils/config.js";
-import { validatePrd, attemptRecovery, createBackup, findLatestBackup, createTemplatePrd, readPrdFile, writePrd, } from "../utils/prd-validator.js";
+import { join, isAbsolute, extname } from "path";
+import { getPaths, getRalphDir, getPrdFiles } from "../utils/config.js";
+import { validatePrd, attemptRecovery, createBackup, findLatestBackup, createTemplatePrd, readPrdFile, writePrdAuto, } from "../utils/prd-validator.js";
+import YAML from "yaml";
 /**
  * Resolves a backup path - can be absolute, relative, or just a filename.
  */
@@ -17,8 +18,21 @@ function resolveBackupPath(backupArg) {
     // Otherwise treat as relative to cwd
     return join(process.cwd(), backupArg);
 }
+/**
+ * Parses a backup file content based on file extension.
+ * Supports both JSON and YAML formats.
+ */
+function parseBackupContent(backupPath, content) {
+    const ext = extname(backupPath).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+        return YAML.parse(content);
+    }
+    return JSON.parse(content);
+}
 /**
  * Restores PRD from a specific backup file.
+ * Supports restoring from both .json and .yaml/.yml backup files.
+ * Writes output in the same format as the target PRD file.
  */
 function restoreFromBackup(prdPath, backupPath) {
     if (!existsSync(backupPath)) {
@@ -27,7 +41,7 @@ function restoreFromBackup(prdPath, backupPath) {
     }
     try {
         const backupContent = readFileSync(backupPath, "utf-8");
-        const backupParsed = JSON.parse(backupContent);
+        const backupParsed = parseBackupContent(backupPath, backupContent);
         const validation = validatePrd(backupParsed);
         if (!validation.valid) {
             console.error("Error: Backup file contains invalid PRD structure:");
@@ -41,7 +55,8 @@ function restoreFromBackup(prdPath, backupPath) {
             const currentBackup = createBackup(prdPath);
             console.log(`Created backup of current PRD: ${currentBackup}`);
         }
-        writePrd(prdPath, validation.data);
+        // Write in the same format as the target PRD file
+        writePrdAuto(prdPath, validation.data);
         console.log(`\x1b[32m✓ PRD restored from: ${backupPath}\x1b[0m`);
         console.log(`  Restored ${validation.data.length} entries.`);
         return true;
@@ -52,13 +67,16 @@ function restoreFromBackup(prdPath, backupPath) {
     }
 }
 /**
- * Handles the case where the PRD file contains invalid JSON.
+ * Handles the case where the PRD file contains invalid JSON/YAML.
  * Attempts to restore from backup or reset to template.
+ * Preserves the original file format (JSON or YAML).
  */
 function handleBrokenPrd(prdPath) {
-    // Create backup of the broken file (preserving raw content)
+    // Create backup of the broken file (preserving raw content and extension)
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const backupPath = prdPath.replace("prd.json", `backup.prd.${timestamp}.json`);
+    const ext = extname(prdPath).toLowerCase();
+    const backupExt = ext === ".yaml" || ext === ".yml" ? ext : ".json";
+    const backupPath = join(getRalphDir(), `backup.prd.${timestamp}${backupExt}`);
     copyFileSync(prdPath, backupPath);
     console.log(`Created backup of broken file: ${backupPath}\n`);
     // Try to restore from a previous valid backup
@@ -67,10 +85,10 @@ function handleBrokenPrd(prdPath) {
         console.log(`Found previous backup: ${latestBackup}`);
         try {
             const backupContent = readFileSync(latestBackup, "utf-8");
-            const backupParsed = JSON.parse(backupContent);
+            const backupParsed = parseBackupContent(latestBackup, backupContent);
             const backupValidation = validatePrd(backupParsed);
             if (backupValidation.valid) {
-                writePrd(prdPath, backupValidation.data);
+                writePrdAuto(prdPath, backupValidation.data);
                 console.log("\x1b[32m✓ PRD restored from backup!\x1b[0m");
                 console.log(`  Restored ${backupValidation.data.length} entries.`);
                 console.log("\x1b[33m  Note: Recent changes may have been lost.\x1b[0m");
@@ -89,7 +107,7 @@ function handleBrokenPrd(prdPath) {
     }
     // Reset to template as last resort - with instructions to recover from backup
     console.log("Resetting PRD to recovery template...");
-    writePrd(prdPath, createTemplatePrd(backupPath));
+    writePrdAuto(prdPath, createTemplatePrd(backupPath));
     console.log("\x1b[33m✓ PRD reset with recovery task.\x1b[0m");
     console.log("  Next 'ralph run' will instruct the LLM to recover entries from backup.");
     console.log(`  Backup location: ${backupPath}`);
@@ -113,20 +131,26 @@ export async function fixPrd(args = []) {
         const success = restoreFromBackup(paths.prd, resolvedPath);
         process.exit(success ? 0 : 1);
     }
-    if (!existsSync(paths.prd)) {
-        console.error("Error: .ralph/prd.json not found. Run 'ralph init' first.");
+    // Detect which PRD files exist
+    const prdFiles = getPrdFiles();
+    if (prdFiles.none) {
+        console.error("Error: No PRD file found (.ralph/prd.yaml or .ralph/prd.json). Run 'ralph init' first.");
         process.exit(1);
     }
-    console.log("Checking PRD structure...\n");
+    // Use the primary PRD path (YAML preferred over JSON)
+    const prdPath = paths.prd;
+    const isYamlFile = extname(prdPath).toLowerCase() === ".yaml" || extname(prdPath).toLowerCase() === ".yml";
+    const fileFormatName = isYamlFile ? "YAML" : "JSON";
+    console.log(`Checking PRD structure (${fileFormatName})...\n`);
     // Step 1: Try to read and parse the file
-    const parsed = readPrdFile(paths.prd);
+    const parsed = readPrdFile(prdPath);
     if (!parsed) {
-        // JSON parsing failed - file is completely broken
-        console.log("\x1b[31m✗ PRD file contains invalid JSON.\x1b[0m\n");
+        // Parsing failed - file is completely broken
+        console.log(`\x1b[31m✗ PRD file contains invalid ${fileFormatName}.\x1b[0m\n`);
         if (verifyOnly) {
             process.exit(1);
         }
-        handleBrokenPrd(paths.prd);
+        handleBrokenPrd(prdPath);
         return;
     }
     // Step 2: Validate the structure
@@ -149,7 +173,7 @@ export async function fixPrd(args = []) {
         process.exit(1);
     }
     // Step 3: Create backup before any modifications
-    const backupPath = createBackup(paths.prd);
+    const backupPath = createBackup(prdPath);
     console.log(`Created backup: ${backupPath}\n`);
     // Step 4: Attempt recovery strategies
     console.log("Attempting recovery...\n");
@@ -159,7 +183,7 @@ export async function fixPrd(args = []) {
         // Validate the recovered data
         const recoveredValidation = validatePrd(recovered);
         if (recoveredValidation.valid) {
-            writePrd(paths.prd, recovered);
+            writePrdAuto(prdPath, recovered);
             console.log("\x1b[32m✓ PRD recovered successfully!\x1b[0m");
             console.log(`  Recovered ${recovered.length} entries by unwrapping/remapping fields.`);
             return;
@@ -167,15 +191,15 @@ export async function fixPrd(args = []) {
     }
     console.log("  Direct recovery failed.\n");
     // Strategy 2: Restore from backup
-    const latestBackup = findLatestBackup(paths.prd);
+    const latestBackup = findLatestBackup(prdPath);
     if (latestBackup && latestBackup !== backupPath) {
         console.log(`Found previous backup: ${latestBackup}`);
         try {
             const backupContent = readFileSync(latestBackup, "utf-8");
-            const backupParsed = JSON.parse(backupContent);
+            const backupParsed = parseBackupContent(latestBackup, backupContent);
             const backupValidation = validatePrd(backupParsed);
             if (backupValidation.valid) {
-                writePrd(paths.prd, backupValidation.data);
+                writePrdAuto(prdPath, backupValidation.data);
                 console.log("\x1b[32m✓ PRD restored from backup!\x1b[0m");
                 console.log(`  Restored ${backupValidation.data.length} entries.`);
                 console.log("\x1b[33m  Note: Recent changes may have been lost.\x1b[0m");
@@ -194,7 +218,7 @@ export async function fixPrd(args = []) {
     }
     // Strategy 3: Reset to recovery template - LLM will fix it on next run
     console.log("Resetting PRD to recovery template...");
-    writePrd(paths.prd, createTemplatePrd(backupPath));
+    writePrdAuto(prdPath, createTemplatePrd(backupPath));
     console.log("\x1b[33m✓ PRD reset with recovery task.\x1b[0m");
     console.log("  Next 'ralph run' will instruct the LLM to recover entries from backup.");
     console.log(`  Backup location: ${backupPath}`);

package/dist/commands/help.js

@@ -10,9 +10,10 @@ COMMANDS:
   run [n] [opts]    Run automation iterations (default: all tasks)
   add               Add a new PRD entry (interactive)
   list [opts]       List all PRD entries
-  status            Show PRD completion status
+  status [--head]   Show PRD completion status
   toggle <n>        Toggle passes status for entry n
   clean             Remove all passing entries from the PRD
+  reset             Reset all entries to incomplete (passes=false)
   fix-prd [opts]    Validate and recover corrupted PRD file
   fix-config [opts] Validate and recover corrupted config.json
   prompt [opts]     Display resolved prompt (for testing in Claude Code)
@@ -45,8 +46,12 @@ LIST OPTIONS:
   --passes                   Show only completed items (passes=true)
   --no-passes                Show only incomplete items (passes=false)
 
+STATUS OPTIONS:
+  --head                     Show only status summary without task headlines
+
 TOGGLE OPTIONS:
   <n> [n2] [n3]...           Toggle one or more entries by number
+  <start>-<end>              Toggle a range of entries (e.g., 1-18)
   --all, -a                  Toggle all PRD entries
 
 FIX-PRD OPTIONS:
@@ -105,11 +110,14 @@ EXAMPLES:
   ralph list -c feature      # Show only feature entries
   ralph list --passes        # Show only completed entries
   ralph list --no-passes     # Show only incomplete entries
-  ralph status               # Show completion summary
+  ralph status               # Show completion summary with task headlines
+  ralph status --head        # Show completion summary without task headlines
   ralph toggle 1             # Toggle entry #1
   ralph toggle 1 2 3         # Toggle multiple entries
+  ralph toggle 1-5           # Toggle entries 1 through 5
   ralph toggle --all         # Toggle all entries
   ralph clean                # Remove passing entries
+  ralph reset                # Reset all entries to incomplete
   ralph fix-prd              # Validate/recover corrupted PRD file
   ralph fix-prd --verify     # Check PRD format without fixing
   ralph fix-prd backup.prd.2024-01-15.json  # Restore from specific backup
@@ -133,7 +141,7 @@ CONFIGURATION:
   .ralph/
   ├── config.json      Project configuration (language, commands, cli)
   ├── prompt.md        Prompt template with $variables ($language, $checkCommand, etc.)
-  ├── prd.json         Product requirements document
+  ├── prd.yaml         Product requirements document
   └── progress.txt     Progress tracking file
 
 CLI CONFIGURATION:

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync, mkdirSync, copyFileSync, chmodSync } from "fs";
 import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
-import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders, getSkillsForLanguage, } from "../templates/prompts.js";
+import { getLanguages, generatePromptTemplate, DEFAULT_PRD_YAML, DEFAULT_PROGRESS, getCliProviders, getSkillsForLanguage, } from "../templates/prompts.js";
 import { generateGenXcodeScript, hasSwiftUI, hasFastlane, generateFastfile, generateAppfile, generateFastlaneReadmeSection, } from "../templates/macos-scripts.js";
 import { promptSelectWithArrows, promptConfirm, promptInput, promptMultiSelectWithArrows, } from "../utils/prompt.js";
 import { dockerInit } from "./docker.js";
@@ -13,7 +13,7 @@ const PACKAGE_ROOT = join(__dirname, "..", ".."); // dist/commands -> dist -> pa
 const RALPH_DIR = ".ralph";
 const CONFIG_FILE = "config.json";
 const PROMPT_FILE = "prompt.md";
-const PRD_FILE = "prd.json";
+const PRD_FILE = "prd.yaml";
 const PROGRESS_FILE = "progress.txt";
 const PRD_GUIDE_FILE = "HOW-TO-WRITE-PRDs.md";
 export async function init(args) {
@@ -339,14 +339,15 @@ export async function init(args) {
         writeFileSync(promptPath, prompt + "\n");
         console.log(`${existsSync(promptPath) ? "Updated" : "Created"} ${RALPH_DIR}/${PROMPT_FILE}`);
     }
-    // Create PRD if not exists
+    // Create PRD if not exists (check for both yaml and json)
     const prdPath = join(ralphDir, PRD_FILE);
-    if (!existsSync(prdPath)) {
-        writeFileSync(prdPath, DEFAULT_PRD + "\n");
+    const prdJsonPath = join(ralphDir, "prd.json");
+    if (!existsSync(prdPath) && !existsSync(prdJsonPath)) {
+        writeFileSync(prdPath, DEFAULT_PRD_YAML);
         console.log(`Created ${RALPH_DIR}/${PRD_FILE}`);
     }
     else {
-        console.log(`Skipped ${RALPH_DIR}/${PRD_FILE} (already exists)`);
+        console.log(`Skipped ${RALPH_DIR}/${PRD_FILE} (PRD already exists)`);
     }
     // Create progress file if not exists
     const progressPath = join(ralphDir, PROGRESS_FILE);
@@ -453,7 +454,7 @@ docker/.config-hash
     console.log("Created .ralph/docker/ files");
     console.log("\nRalph initialized successfully!");
     console.log("\nNext steps:");
-    console.log("  1. Edit .ralph/prd.json to add your project requirements");
+    console.log("  1. Edit .ralph/prd.yaml to add your project requirements");
     console.log("  2. Run 'ralph docker run' to start (auto-builds image on first run)");
     console.log("\nSee .ralph/HOW-TO-WRITE-PRDs.md for guidance on writing PRDs");
     console.log("To regenerate Docker files: ralph docker init");

package/dist/commands/prd-convert.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts prd.json to prd.yaml format.
+ * - Reads .ralph/prd.json
+ * - Converts to YAML format
+ * - Writes to .ralph/prd.yaml
+ * - Renames original prd.json to prd.json.pre-yaml
+ */
+export declare function prdConvert(args: string[]): Promise<void>;
+export declare function convert(args: string[]): Promise<void>;

package/dist/commands/prd-convert.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { join } from "path";
+import YAML from "yaml";
+import { getRalphDir } from "../utils/config.js";
+const PRD_JSON_FILE = "prd.json";
+const PRD_YAML_FILE = "prd.yaml";
+const PRD_BACKUP_SUFFIX = ".pre-yaml";
+function getPrdJsonPath() {
+    return join(getRalphDir(), PRD_JSON_FILE);
+}
+function getPrdYamlPath() {
+    return join(getRalphDir(), PRD_YAML_FILE);
+}
+/**
+ * Converts prd.json to prd.yaml format.
+ * - Reads .ralph/prd.json
+ * - Converts to YAML format
+ * - Writes to .ralph/prd.yaml
+ * - Renames original prd.json to prd.json.pre-yaml
+ */
+export async function prdConvert(args) {
+    const force = args.includes("--force") || args.includes("-f");
+    const dryRun = args.includes("--dry-run") || args.includes("-n");
+    const jsonPath = getPrdJsonPath();
+    const yamlPath = getPrdYamlPath();
+    const backupPath = jsonPath + PRD_BACKUP_SUFFIX;
+    // Check if prd.json exists
+    if (!existsSync(jsonPath)) {
+        console.error("Error: .ralph/prd.json not found.");
+        console.error("Run 'ralph init' first to create a project.");
+        process.exit(1);
+    }
+    // Check if prd.yaml already exists
+    if (existsSync(yamlPath) && !force) {
+        console.error("Error: .ralph/prd.yaml already exists.");
+        console.error("Use --force to overwrite the existing YAML file.");
+        process.exit(1);
+    }
+    // Check if backup already exists (previous conversion)
+    if (existsSync(backupPath) && !force) {
+        console.error("Error: .ralph/prd.json.pre-yaml already exists.");
+        console.error("It appears a previous conversion was performed.");
+        console.error("Use --force to overwrite existing files.");
+        process.exit(1);
+    }
+    // Read and parse JSON
+    let prdEntries;
+    try {
+        const jsonContent = readFileSync(jsonPath, "utf-8");
+        prdEntries = JSON.parse(jsonContent);
+        if (!Array.isArray(prdEntries)) {
+            throw new Error("PRD content is not an array");
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        console.error(`Error reading .ralph/prd.json: ${message}`);
+        console.error("Run 'ralph fix-prd' to attempt repair.");
+        process.exit(1);
+    }
+    // Convert to YAML
+    const yamlContent = YAML.stringify(prdEntries, {
+        indent: 2,
+        lineWidth: 0, // Don't wrap lines
+    });
+    if (dryRun) {
+        console.log("Dry run - no files will be modified.\n");
+        console.log("Would convert .ralph/prd.json to .ralph/prd.yaml:\n");
+        console.log("--- YAML Output ---");
+        console.log(yamlContent);
+        console.log("-------------------\n");
+        console.log(`Entries: ${prdEntries.length}`);
+        return;
+    }
+    // Write YAML file
+    writeFileSync(yamlPath, yamlContent);
+    console.log(`\x1b[32m✓\x1b[0m Created .ralph/prd.yaml`);
+    // Rename original JSON to backup
+    renameSync(jsonPath, backupPath);
+    console.log(`\x1b[32m✓\x1b[0m Renamed .ralph/prd.json to .ralph/prd.json.pre-yaml`);
+    // Success message
+    console.log(`\n\x1b[32mConversion complete!\x1b[0m`);
+    console.log(`  Converted ${prdEntries.length} PRD entries to YAML format.\n`);
+    console.log("Next steps:");
+    console.log("  1. Your PRD is now in .ralph/prd.yaml");
+    console.log("  2. The original JSON is preserved as .ralph/prd.json.pre-yaml");
+    console.log("  3. Ralph will automatically use the YAML file going forward");
+    console.log("");
+    console.log("To revert, simply rename the files back:");
+    console.log("  mv .ralph/prd.json.pre-yaml .ralph/prd.json");
+    console.log("  rm .ralph/prd.yaml");
+}
+function showHelp() {
+    console.log("Usage: ralph prd convert [options]\n");
+    console.log("Convert .ralph/prd.json to .ralph/prd.yaml format.\n");
+    console.log("Options:");
+    console.log("  --force, -f     Overwrite existing prd.yaml and backup files");
+    console.log("  --dry-run, -n   Show what would be converted without making changes");
+    console.log("  --help, -h      Show this help message\n");
+    console.log("The original prd.json will be renamed to prd.json.pre-yaml as a backup.");
+}
+export async function convert(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        showHelp();
+        return;
+    }
+    await prdConvert(args);
+}

package/dist/commands/prd.d.ts

@@ -1,8 +1,9 @@
 export declare function prdAdd(): Promise<void>;
 export declare function prdList(category?: string, passesFilter?: boolean): void;
-export declare function prdStatus(): void;
+export declare function prdStatus(headOnly?: boolean): void;
 export declare function prdToggle(args: string[]): void;
 export declare function prdClean(): void;
+export declare function prdReset(): Promise<void>;
 export declare function parseListArgs(args: string[]): {
     category?: string;
     passesFilter?: boolean;