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:

```typescript
// 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

- [x] New users can create projects successfully
- [x] No console errors during project creation
- [x] Projects load correctly after creation
- [x] All components are visible in the editor
- [x] 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:

```typescript
{
  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