OpenNoodl/dev-docs/tasks/phase-0-foundation-stabilisation/TASK-010-project-creation-bug-fix/CHANGELOG.md

TASK-010: Project Creation Bug Fix - CHANGELOG

Status: ✅ COMPLETED
Date: January 9, 2026
Priority: P0 - Critical Blocker

---

Summary

Fixed critical bug preventing new project creation. The issue was an incorrect project.json structure in programmatic project generation - missing the required graph object wrapper and the comments array, causing TypeError: Cannot read properties of undefined (reading 'comments').

---

Changes Made

1. Fixed Project Structure in LocalProjectsModel.ts

File: packages/noodl-editor/src/editor/src/utils/LocalProjectsModel.ts

Problem: The programmatically generated project.json had an incorrect structure:

• Used nodes array directly in component (should be graph.roots)
• Missing graph object wrapper
• Missing comments array (causing the error)
• Missing connections array
• Missing component id field

Solution: Corrected the structure to match the schema:

// BEFORE (INCORRECT)
{
  name: 'App',
  ports: [],
  visual: true,
  visualStateTransitions: [],
  nodes: [...]  // ❌ Wrong location
}

// AFTER (CORRECT)
{
  name: 'App',
  id: guid(),      // ✅ Added
  graph: {         // ✅ Added wrapper
    roots: [...],  // ✅ Renamed from 'nodes'
    connections: [], // ✅ Added
    comments: []   // ✅ Added (was causing error)
  },
  metadata: {}     // ✅ Added
}

Lines Modified: 288-321

2. Added Debug Logging

Added console logging for better debugging:

• Success message: "Project created successfully: {name}"
• Error messages for failure cases

---

Root Cause Analysis

The Error Chain

ProjectModel.fromJSON(json)
  → ComponentModel.fromJSON(json.components[i])
    → NodeGraphModel.fromJSON(json.graph)  // ← json.graph was undefined!
      → accesses json.comments             // ← BOOM: Cannot read properties of undefined

Why Previous Attempts Failed

1. Attempt 1 (Path resolution with __dirname): Webpack bundling issue
2. Attempt 2 (Path resolution with process.cwd()): Wrong directory
3. Attempt 3 (Programmatic creation): Incomplete structure (this attempt)

The Final Solution

Understanding that the schema requires:

• Component needs id field
• Component needs graph object (not nodes array)
• graph must contain roots, connections, and comments arrays

---

Testing

Manual Testing Performed

1. ✅ Created new project from dashboard
2. ✅ Project opened without errors
3. ✅ Console showed: "Project created successfully: alloha"
4. ✅ Component "App" visible in editor
5. ✅ Text node with "Hello World!" present
6. ✅ Project can be saved and reopened

Success Criteria Met

• New users can create projects successfully
• No console errors during project creation
• Projects load correctly after creation
• All components are visible in the editor
• Error message resolved: "Cannot read properties of undefined (reading 'comments')"

---

Files Modified

1. packages/noodl-editor/src/editor/src/utils/LocalProjectsModel.ts
   • Lines 288-321: Fixed project.json structure
   • Lines 324-345: Added better error logging

---

Documentation Updates

1. dev-docs/reference/LEARNINGS.md
   • Added comprehensive entry documenting the project.json structure
   • Included prevention checklist for future programmatic project creation
   • Documented the error chain and debugging journey

---

Impact

Before: P0 blocker - New users could not create projects at all
After: ✅ Project creation works correctly

User Experience:

• No more cryptic error messages
• Smooth onboarding for new users
• Reliable project creation

---

Related Issues

• Unblocks user onboarding
• Prerequisite for TASK-009 (template system refactoring)
• Fixes recurring issue that had three previous failed attempts

---

Notes for Future Developers

Project.json Schema Requirements

When creating projects programmatically, always include:

{
  name: string,
  components: [{
    name: string,
    id: string,              // Required
    graph: {                 // Required wrapper
      roots: [...],          // Not "nodes"
      connections: [],       // Required (can be empty)
      comments: []          // Required (can be empty)
    },
    metadata: {}            // Required (can be empty)
  }],
  settings: {},             // Required
  metadata: {               // Project metadata
    title: string,
    description: string
  }
}

Prevention Checklist

Before creating a project programmatically:

• Component has id field
• Component has graph object (not nodes)
• graph.roots array exists
• graph.connections array exists
• graph.comments array exists
• Component has metadata object
• Project has settings object
• Project has metadata with title/description

---

Lessons Learned

1. Schema documentation is critical: The lack of formal project.json schema documentation made this harder to debug
2. Error messages can be misleading: "reading 'comments'" suggested comments were the problem, not the missing graph object
3. Test end-to-end: Don't just test file writing - test loading the created project
4. Use real templates as reference: The truncated template file wasn't helpful; needed to examine actual working projects

---

Completed by: Cline (AI Assistant)
Reviewed by: Richard (User)
Date Completed: January 9, 2026