@kjerneverk/riotplan 1.0.8 → 1.0.9-dev.0

package/BUG-FIX-STEP-ADD-DIRECTORY.md

@@ -0,0 +1,76 @@
+# Bug Fix: riotplan_step_add Creates Files in Wrong Directory
+
+## Issue
+`riotplan_step_add` was creating step files directly in the plan root directory instead of in the `plan/` subdirectory when the `plan/` subdirectory didn't exist.
+
+## Root Cause
+The `getPlanDir()` helper function in `src/steps/operations.ts` would fall back to the plan root directory if the `plan/` subdirectory didn't exist, rather than creating it.
+
+```typescript
+// OLD BEHAVIOR (BUGGY)
+async function getPlanDir(planPath: string): Promise<string> {
+    const standardDir = join(planPath, PLAN_CONVENTIONS.standardDirs.plan);
+    try {
+        await readdir(standardDir);
+        return standardDir;
+    } catch {
+        return planPath;  // ❌ Falls back to root instead of creating plan/
+    }
+}
+```
+
+## Solution
+Modified `getPlanDir()` to create the `plan/` subdirectory if it doesn't exist:
+
+```typescript
+// NEW BEHAVIOR (FIXED)
+async function getPlanDir(planPath: string): Promise<string> {
+    const standardDir = join(planPath, PLAN_CONVENTIONS.standardDirs.plan);
+    try {
+        await readdir(standardDir);
+        return standardDir;
+    } catch {
+        // Create plan/ subdirectory if it doesn't exist
+        await mkdir(standardDir, { recursive: true });
+        return standardDir;  // ✅ Always returns plan/ subdirectory
+    }
+}
+```
+
+## Files Changed
+1. **src/steps/operations.ts**
+   - Added `mkdir` to imports from `node:fs/promises`
+   - Modified `getPlanDir()` to create `plan/` subdirectory if missing
+   - Updated function documentation
+
+2. **tests/step-operations.test.ts**
+   - Added new test suite: "plan/ subdirectory creation"
+   - Test 1: Verifies `plan/` is created when it doesn't exist
+   - Test 2: Verifies existing `plan/` is used correctly
+
+## Test Results
+- All 666 tests pass (4 skipped)
+- Coverage for `operations.ts`: 98.6% (improved from 97.2%)
+- Overall coverage: 92.61% statements, 80.07% branches, 92.77% functions, 93.6% lines
+
+## Impact
+- ✅ New plans now have consistent structure
+- ✅ Step files are always created in `plan/` subdirectory
+- ✅ Matches existing plan conventions across the repository
+- ✅ No breaking changes - existing plans continue to work
+- ✅ Backward compatible - handles both scenarios correctly
+
+## Verification
+The fix was verified with:
+1. Existing test suite (40 original tests)
+2. New regression tests (2 additional tests)
+3. Manual verification of plan structure consistency
+
+## Related Files
+All existing plans in the repository use the `plan/` subdirectory pattern:
+- `mcp-integration/env-var-config-implementation/plan/`
+- `done/config-discovery-locations/plan/`
+- `done/config-format-support/plan/`
+- `future/server-runtime-support/plan/`
+
+This fix ensures all new plans follow the same convention.

package/MCP-ERROR-HANDLING-FIX.md

@@ -0,0 +1,62 @@
+# MCP Server Stdout Pollution Fix
+
+## Issue
+
+The RiotPlan MCP server was crashing with the error:
+
+```
+Unexpected token 'C', "Config fil"... is not valid JSON
+```
+
+This was caused by stdout pollution corrupting the MCP JSON-RPC protocol stream.
+
+## Root Cause
+
+MCP uses stdio (stdin/stdout) for JSON-RPC communication. Any output to stdout - even from dependencies like CardiganTime - corrupts the protocol stream, causing the client to receive invalid JSON.
+
+The error message `"Config fil"...` was actually the beginning of a log message like "Config file not found..." that was being written to stdout and mixing with the JSON-RPC messages.
+
+## Solution
+
+### Stdout Suppression
+
+Redirected all stdout to stderr in MCP mode to prevent pollution of the JSON-RPC stream:
+
+```typescript
+// Suppress stdout to prevent pollution of MCP JSON-RPC stream
+const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+process.stdout.write = (chunk: any, encoding?: any, callback?: any): boolean => {
+    // Redirect to stderr instead
+    return process.stderr.write(chunk, encoding, callback);
+};
+```
+
+This ensures:
+- MCP JSON-RPC protocol remains clean on stdout
+- All logs (from RiotPlan and dependencies) go to stderr
+- No corruption of the protocol stream
+
+### Enhanced Error Handling
+
+Also improved error messages throughout:
+
+1. **Better Config Error Messages** (`src/config/loader.ts`)
+   - Specific error handling for JSON parsing errors
+   - Specific error handling for validation errors
+   - Helpful troubleshooting tips
+   - Full error context
+
+2. **Improved Server Error Handling** (`src/mcp/server.ts`)
+   - Centralized error logging with timestamps
+   - Try-catch wrapper around tool execution
+   - Global process error handlers
+   - Full stack traces in error responses
+
+## Files Changed
+
+- `src/mcp/server.ts` - Stdout suppression and error handling
+- `src/config/loader.ts` - Enhanced error messages
+
+## Testing
+
+All 666 tests pass. The MCP server now properly isolates stdout for the JSON-RPC protocol.

package/README.md

@@ -434,16 +434,45 @@ Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
 
 **Zero-Config Experience:** If you don't set `RIOTPLAN_PLAN_DIRECTORY`, RiotPlan will automatically find your `plans/` directory by walking up from your workspace root. No configuration needed!
 
+The MCP server includes enhanced error handling and logging for better reliability and debugging.
+
 ### MCP Tools
 
-- **`riotplan_create`** - Create new plans with AI-generated steps
+**Lifecycle Management:**
+- **`riotplan_idea_create`** - Start exploring an idea (Idea stage)
+- **`riotplan_shaping_start`** - Begin shaping approaches (Shaping stage)
+- **`riotplan_build`** - Build plan from idea/shaping with AI generation (→ Built stage)
+- **`riotplan_transition`** - Move between lifecycle stages manually
+
+**Plan Management:**
+- **`riotplan_create`** - Create new plan directory with AI-generated steps
 - **`riotplan_status`** - Show plan status and progress
+- **`riotplan_validate`** - Validate plan structure
+- **`riotplan_generate`** - Generate plan content with AI
+
+**Step Management:**
 - **`riotplan_step_list`** - List all steps
 - **`riotplan_step_start`** - Mark step as started
 - **`riotplan_step_complete`** - Mark step as completed
 - **`riotplan_step_add`** - Add new steps dynamically
-- **`riotplan_validate`** - Validate plan structure
-- **`riotplan_generate`** - Generate plan content with AI
+
+**Idea Stage:**
+- **`riotplan_idea_add_note`** - Add notes during exploration
+- **`riotplan_idea_add_constraint`** - Document constraints
+- **`riotplan_idea_add_question`** - Raise questions
+- **`riotplan_idea_add_evidence`** - Attach supporting materials
+- **`riotplan_idea_kill`** - Abandon idea with reason
+
+**Shaping Stage:**
+- **`riotplan_shaping_add_approach`** - Propose solution approaches
+- **`riotplan_shaping_add_feedback`** - Add feedback on approaches
+- **`riotplan_shaping_compare`** - Compare all approaches
+- **`riotplan_shaping_select`** - Select best approach
+
+**History & Checkpoints:**
+- **`riotplan_checkpoint_create`** - Save state snapshots
+- **`riotplan_checkpoint_restore`** - Restore previous state
+- **`riotplan_history_show`** - View timeline of events
 
 ### MCP Resources
 

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { q as createProgram } from "./cli-BNnX3BBS.js";
+import { q as createProgram } from "./cli-gjREHy7E.js";
 const program = createProgram();
 program.parse();
 //# sourceMappingURL=bin.js.map

package/dist/{cli-BNnX3BBS.js → cli-gjREHy7E.js}

@@ -2352,7 +2352,8 @@ async function getPlanDir(planPath) {
     await readdir(standardDir);
     return standardDir;
   } catch {
-    return planPath;
+    await mkdir(standardDir, { recursive: true });
+    return standardDir;
   }
 }
 function generateStepFilename(number, code) {
@@ -4400,10 +4401,12 @@ async function loadProvider(config) {
         throw new Error(`Unknown provider: ${name}`);
     }
   } catch (error) {
-    if (error instanceof Error && error.message.includes("Cannot find package")) {
+    if (error instanceof Error && (error.message.includes("Cannot find package") || error.message.includes("Cannot find module"))) {
       throw new Error(
         `Provider '${name}' is not installed. Install it with:
-  npm install @kjerneverk/execution-${name}`
+  npm install @kjerneverk/execution-${name}
+
+Note: If you're using RiotPlan via MCP (e.g., in Cursor), consider using manual step creation with riotplan_step_add instead of riotplan_generate to avoid needing separate AI providers.`
       );
     }
     throw error;
@@ -6185,8 +6188,11 @@ const RiotPlanConfigSchema = z.object({
 const cardigantime = create({
   defaults: {
     configDirectory: process.cwd(),
-    isRequired: false
+    isRequired: false,
     // Config file is optional
+    pathResolution: {
+      pathFields: ["planDirectory", "templateDirectory"]
+    }
   },
   configShape: RiotPlanConfigSchema.shape,
   features: ["config"]
@@ -6212,7 +6218,37 @@ async function loadConfig() {
     if (error instanceof Error && error.message.includes("not found")) {
       return null;
     }
-    throw error;
+    if (error instanceof Error) {
+      if (error.message.includes("JSON") || error.message.includes("parse")) {
+        throw new Error(
+          `Failed to parse RiotPlan configuration file: ${error.message}
+
+Please check that your config file (riotplan.config.* or .riotplan/config.*) contains valid JSON/YAML/JS.
+Common issues:
+- Missing quotes around strings
+- Trailing commas in JSON
+- Invalid YAML indentation
+
+Original error: ${error.message}`
+        );
+      }
+      if (error.message.includes("validation") || error.message.includes("schema")) {
+        throw new Error(
+          `RiotPlan configuration validation failed: ${error.message}
+
+Valid configuration options:
+- planDirectory: string (path to plans directory)
+- defaultProvider: 'anthropic' | 'openai' | 'gemini'
+- defaultModel: string
+- templateDirectory: string (path to custom templates)
+
+Original error: ${error.message}`
+        );
+      }
+    }
+    throw new Error(
+      `Failed to load RiotPlan configuration: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 const walkUpCache = /* @__PURE__ */ new Map();
@@ -6561,4 +6597,4 @@ export {
   getFeedback as y,
   getReadySteps as z
 };
-//# sourceMappingURL=cli-BNnX3BBS.js.map
+//# sourceMappingURL=cli-gjREHy7E.js.map