mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-03-07 17:43:28 +01:00
10cf761d52
Branch: cline-dev-dishant Cross-branch notes: Richard completed STYLE-001 Phase 3+4 and CLEANUP-000H (Phase 9 styles only). No shared dependencies with Phase 11 or Phase 10 scope.
555 lines
16 KiB
Plaintext
555 lines
16 KiB
Plaintext
# Cline Development Guidelines for OpenNoodl
|
|
|
|
## Communication Style
|
|
|
|
**You are assisting Richard**, an experienced CTO and full-stack developer. Communication should be:
|
|
|
|
- **Direct and technical** - Skip basic explanations, use proper terminology
|
|
- **Practical and actionable** - Focus on working solutions over theory
|
|
- **Concise but complete** - Respect time while providing necessary context
|
|
- **Honest about limitations** - Say "I don't know" rather than guess
|
|
- **Assumes competence** - Richard understands development fundamentals
|
|
- **Casual and humorous when appropriate** - Use slang, informal expressions, and humor to keep things human
|
|
|
|
**Tone**: Professional peer who doesn't take themselves too seriously. "Hold the front door" > "Please wait a moment". Explain _why_ when context helps, not _what_ when it's obvious. Be precise about technical details, relaxed about everything else.
|
|
|
|
---
|
|
|
|
## 🚨 CRITICAL REQUIREMENTS
|
|
|
|
### 1. Testing & Verification Are Mandatory
|
|
|
|
**Code written ≠ Feature working**
|
|
|
|
- ✅ **ALWAYS prefer unit tests** - Write tests that prove functionality works
|
|
- ✅ **If tests aren't feasible** - Explicitly ask Richard to verify changes before marking complete
|
|
- ❌ **NEVER declare "done" without proof** - Either tests pass or user confirms it works
|
|
|
|
```markdown
|
|
## Before marking any task complete:
|
|
|
|
- [ ] Unit tests added and passing, OR
|
|
- [ ] User has verified changes work as expected
|
|
- [ ] No assumptions that "code compiles = feature works"
|
|
```
|
|
|
|
### 2. Break Out of Loops
|
|
|
|
**When you're stuck (same error 3+ times, repeated attempts failing):**
|
|
|
|
```markdown
|
|
I'm hitting a wall with [specific issue]. This needs dedicated research.
|
|
|
|
Should I create a research task doc to:
|
|
|
|
1. [Investigate root cause]
|
|
2. [Explore alternatives]
|
|
3. [Document solution for future reference]
|
|
|
|
This will prevent wasting time on trial-and-error.
|
|
```
|
|
|
|
**Do NOT** keep trying variations of the same approach. Recognize the pattern and escalate.
|
|
|
|
### 3. Document Discoveries Systematically
|
|
|
|
**When you learn something important about the codebase:**
|
|
|
|
```markdown
|
|
## Discovered: [Brief Title]
|
|
|
|
**Context**: [What were you trying to do?]
|
|
**Discovery**: [What did you learn?]
|
|
**Location**: [What files/systems does this affect?]
|
|
**Action**: [Added to LEARNINGS.md / COMMON-ISSUES.md]
|
|
```
|
|
|
|
**Important = Worth documenting:**
|
|
|
|
- Non-obvious behavior or gotchas
|
|
- Error solutions that took time to figure out
|
|
- Undocumented dependencies between systems
|
|
- Patterns you had to reverse-engineer
|
|
- Anything the next developer shouldn't have to rediscover
|
|
|
|
**Update these files as you learn:**
|
|
|
|
- `dev-docs/reference/LEARNINGS.md` - General discoveries
|
|
- `dev-docs/reference/COMMON-ISSUES.md` - Error solutions
|
|
- Task `CHANGELOG.md` - Task-specific progress
|
|
|
|
---
|
|
|
|
## Project Context
|
|
|
|
### What is OpenNoodl
|
|
|
|
OpenNoodl is an **Electron desktop application** (not a web app) for visual programming. Key facts:
|
|
|
|
- **Editor**: Electron app (never opens in browser)
|
|
- **Viewer**: Generates web applications
|
|
- **Runtime**: JavaScript execution engine for node graphs
|
|
- Run with `npm run dev` (launches Electron, not a web server)
|
|
- Debug with Electron DevTools (View → Toggle Developer Tools)
|
|
|
|
### Codebase Structure
|
|
|
|
```
|
|
packages/
|
|
├── noodl-editor/ # Electron editor application
|
|
│ ├── src/editor/src/ # Main editor code
|
|
│ │ ├── models/ # Data models (ProjectModel, NodeGraph)
|
|
│ │ ├── views/ # React UI components
|
|
│ │ ├── store/ # State management
|
|
│ │ └── utils/ # Utilities
|
|
│ └── tests/ # Test files
|
|
│
|
|
├── noodl-runtime/ # Node execution engine
|
|
│ └── src/nodes/ # Runtime node definitions
|
|
│
|
|
├── noodl-viewer-react/ # React-based visual nodes
|
|
│ └── src/nodes/ # Visual components
|
|
│
|
|
└── noodl-core-ui/ # Shared UI components
|
|
└── src/components/ # Reusable UI
|
|
```
|
|
|
|
### Key Documentation
|
|
|
|
**Read these FIRST for relevant tasks:**
|
|
|
|
- `dev-docs/reference/CODEBASE-MAP.md` - Navigation guide
|
|
- `dev-docs/reference/COMMON-ISSUES.md` - Known problems/solutions
|
|
- `dev-docs/reference/NODE-PATTERNS.md` - How to create/modify nodes
|
|
- `dev-docs/reference/LEARNINGS.md` - Accumulated knowledge
|
|
- `dev-docs/reference/UI-STYLING-GUIDE.md` - Styling rules (NO hardcoded colors!)
|
|
- `dev-docs/reference/PANEL-UI-STYLE-GUIDE.md` - **Panels & Modals (READ BEFORE making UI!)**
|
|
- `dev-docs/reference/LEARNINGS-NODE-CREATION.md` - Node creation gotchas
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### 1. Before Starting Any Task
|
|
|
|
```bash
|
|
# Check context
|
|
git branch
|
|
git status
|
|
git log --oneline -10
|
|
|
|
# Read relevant docs
|
|
# - Check LEARNINGS.md for related discoveries
|
|
# - Check COMMON-ISSUES.md for known problems
|
|
# - Review referenced files in dev-docs/
|
|
```
|
|
|
|
### 2. Understanding Before Coding
|
|
|
|
- Read JSDoc comments on functions you'll modify
|
|
- Check for existing test files
|
|
- Search for usage patterns: `grep -r "functionName" packages/`
|
|
- Understand dependencies: `grep -r "from.*filename" packages/`
|
|
|
|
### 3. Implementation Standards
|
|
|
|
**TypeScript**:
|
|
|
|
- Explicit types always (no `any`, no `TSFixme`)
|
|
- Use interfaces for complex types
|
|
- Document public APIs with JSDoc
|
|
|
|
**React**:
|
|
|
|
- Functional components (no class components unless required)
|
|
- Use hooks properly (`useCallback`, `useMemo` for optimization)
|
|
- NEVER use direct EventDispatcher `.on()` - ALWAYS use `useEventListener` hook
|
|
|
|
**Node Creation**:
|
|
|
|
- Signal inputs use `valueChangedToTrue`, not `set`
|
|
- NEVER override `setInputValue` in `prototypeExtensions`
|
|
- Dynamic ports must include static ports when updating
|
|
- Export format: `module.exports = { node: NodeDef, setup: fn }`
|
|
|
|
### 4. Critical Patterns
|
|
|
|
**EventDispatcher in React** (Phase 0 Critical):
|
|
|
|
```typescript
|
|
// ✅ CORRECT - Always use this
|
|
import { useEventListener } from '@noodl-hooks/useEventListener';
|
|
|
|
useEventListener(ProjectModel.instance, 'componentRenamed', (data) => {
|
|
// This works!
|
|
});
|
|
|
|
// ❌ BROKEN - Never do this (silently fails)
|
|
useEffect(() => {
|
|
ProjectModel.instance.on('event', handler, context);
|
|
return () => ProjectModel.instance.off(context);
|
|
}, []);
|
|
```
|
|
|
|
**UI Styling**:
|
|
|
|
```scss
|
|
// ❌ NEVER - Hardcoded colors
|
|
.Card {
|
|
background-color: #27272a;
|
|
color: #b8b8b8;
|
|
}
|
|
|
|
// ✅ ALWAYS - Design tokens
|
|
.Card {
|
|
background-color: var(--theme-color-bg-3);
|
|
color: var(--theme-color-fg-default);
|
|
}
|
|
```
|
|
|
|
### 5. Testing Requirements
|
|
|
|
```typescript
|
|
// Test file structure
|
|
import { describe, it, expect, beforeEach } from '@jest/globals';
|
|
|
|
describe('FeatureName', () => {
|
|
beforeEach(() => {
|
|
// Setup
|
|
});
|
|
|
|
describe('when condition X', () => {
|
|
it('should do Y', () => {
|
|
// Arrange
|
|
// Act
|
|
// Assert
|
|
});
|
|
});
|
|
});
|
|
```
|
|
|
|
**What to test** (Priority order):
|
|
|
|
1. Utility functions
|
|
2. Data transformations
|
|
3. State management logic
|
|
4. React hooks
|
|
5. Component behavior
|
|
|
|
### 6. Git Workflow
|
|
|
|
**Branch naming**:
|
|
|
|
```bash
|
|
feature/add-vercel-deployment
|
|
fix/page-router-scroll
|
|
refactor/remove-tsfixme-panels
|
|
docs/update-node-api
|
|
```
|
|
|
|
**Commit messages** (Conventional Commits):
|
|
|
|
```bash
|
|
feat(editor): add breakpoint support for node connections
|
|
fix(viewer): resolve scroll position reset in nested Page Router
|
|
refactor(runtime): replace TSFixme with proper types in node processor
|
|
docs(api): add JSDoc to all public node methods
|
|
test(editor): add unit tests for node selection hook
|
|
chore(deps): update react to 19.0.0
|
|
```
|
|
|
|
**Commit frequency**: After each logical change (tests should pass)
|
|
|
|
---
|
|
|
|
## Task Sizing & Context Management
|
|
|
|
### Recognizing Tasks That Are Too Large
|
|
|
|
**Signs you'll hit API limits:**
|
|
|
|
- Modifying 10+ files in one go
|
|
- Reading entire large files multiple times
|
|
- Converting 50+ Storybook stories
|
|
- Refactoring a whole subsystem
|
|
- Adding features across multiple packages
|
|
|
|
**Size estimation**:
|
|
|
|
| Scope | Files | Safety | Action |
|
|
| -------------- | ----- | ------------ | ------------------- |
|
|
| Bug fix | 1-3 | ✅ Safe | Proceed |
|
|
| Small feature | 3-5 | ✅ Safe | Proceed |
|
|
| Medium feature | 5-10 | ⚠️ Watch | Monitor context |
|
|
| Large feature | 10-20 | ❌ Risky | Split into subtasks |
|
|
| Refactoring | 20+ | ❌ Too large | Must split |
|
|
|
|
### When You Hit API Limits
|
|
|
|
**DO NOT** retry the same scope. **IMMEDIATELY**:
|
|
|
|
```markdown
|
|
I've hit an API context limit. This task is too large.
|
|
|
|
I was attempting to: [describe scope]
|
|
|
|
Breaking into subtasks:
|
|
|
|
**Subtask 1**: [Specific scope - 2-4 files max]
|
|
|
|
- File A: [specific changes]
|
|
- File B: [specific changes]
|
|
|
|
**Subtask 2**: [Next logical chunk]
|
|
|
|
- File C: [specific changes]
|
|
|
|
Starting with Subtask 1 now...
|
|
```
|
|
|
|
### How to Split Tasks
|
|
|
|
**Strategies**:
|
|
|
|
1. **By package/module** - Runtime changes, then editor changes, then integration
|
|
2. **By feature slice** - Core logic, then UI, then validation/error handling
|
|
3. **By file groups** - Batch similar components (5-7 at a time)
|
|
4. **By logical phases** - Audit, then core changes, then secondary changes, then verification
|
|
|
|
**Each subtask must be**:
|
|
|
|
- Complete and working (no placeholders)
|
|
- Independently testable
|
|
- Fully documented
|
|
- Quality standards maintained
|
|
|
|
---
|
|
|
|
## Debugging & Troubleshooting
|
|
|
|
### Cache Issues
|
|
|
|
**If code changes don't appear**:
|
|
|
|
```bash
|
|
# 1. Nuclear option first
|
|
npm run clean:all
|
|
|
|
# 2. Restart dev server (don't just refresh)
|
|
|
|
# 3. Check build canary in console
|
|
# Should see: 🔥 BUILD TIMESTAMP: [recent time]
|
|
|
|
# 4. Add distinctive log to verify code loaded
|
|
console.log('🔥 MY CHANGE LOADED:', Date.now());
|
|
```
|
|
|
|
**Never debug without verifying fresh code is running.**
|
|
|
|
### Foundation Health Check
|
|
|
|
Run when things "feel broken":
|
|
|
|
```bash
|
|
npm run health:check
|
|
```
|
|
|
|
Checks:
|
|
|
|
- Cache state
|
|
- Webpack config
|
|
- useEventListener hook presence
|
|
- Direct EventDispatcher anti-patterns
|
|
- Build canary
|
|
- Package versions
|
|
|
|
### React Migration Issues
|
|
|
|
**UI doesn't update after action:**
|
|
|
|
1. Check if action succeeded (console logs)
|
|
2. Check if event was emitted (log in model method)
|
|
3. Check if event was received (log in useEventListener callback)
|
|
4. Check if component re-rendered (log in component body)
|
|
|
|
**Usually the problem**:
|
|
|
|
- Using direct `.on()` instead of `useEventListener`
|
|
- Cached old code running
|
|
- Event name mismatch
|
|
|
|
---
|
|
|
|
## Pre-Completion Checklist
|
|
|
|
Before marking any task complete:
|
|
|
|
### Code Quality
|
|
|
|
- [ ] No `TSFixme` types added
|
|
- [ ] All new functions have JSDoc comments
|
|
- [ ] Complex logic has explanatory comments
|
|
- [ ] No console.log statements (except errors/warnings)
|
|
- [ ] No unused imports or variables
|
|
- [ ] No hardcoded colors (use `var(--theme-color-*)` tokens)
|
|
|
|
### Testing & Verification
|
|
|
|
- [ ] **Unit tests added and passing, OR user verified changes work**
|
|
- [ ] Existing tests still pass
|
|
- [ ] Manual testing completed (document steps taken)
|
|
|
|
### React + EventDispatcher (Critical)
|
|
|
|
- [ ] Using `useEventListener` hook for ALL EventDispatcher subscriptions
|
|
- [ ] Singleton instances in useEffect dependencies
|
|
- [ ] No direct EventDispatcher `.on()` calls in React components
|
|
|
|
### Node Creation (If applicable)
|
|
|
|
- [ ] Signal inputs use `valueChangedToTrue` (not `set`)
|
|
- [ ] No `setInputValue` override in `prototypeExtensions`
|
|
- [ ] Dynamic ports include static ports
|
|
- [ ] Config inputs explicitly registered
|
|
|
|
### Documentation
|
|
|
|
- [ ] README updated if needed
|
|
- [ ] JSDoc added to public APIs
|
|
- [ ] **Discoveries added to LEARNINGS.md or COMMON-ISSUES.md**
|
|
- [ ] Task CHANGELOG.md updated with progress
|
|
|
|
### Visual Components (Panels, Modals, Forms)
|
|
|
|
**MUST read `dev-docs/reference/PANEL-UI-STYLE-GUIDE.md` before building UI!**
|
|
|
|
- [ ] NO emojis in buttons, labels, or headers
|
|
- [ ] Using CSS variables for ALL colors (`var(--theme-color-*)`)
|
|
- [ ] Using `Text` component with proper `textType` for typography
|
|
- [ ] Using `PrimaryButton` with correct variant (Cta/Muted/Ghost/Danger)
|
|
- [ ] Panel structure: Header → Toolbar → Content → Footer
|
|
- [ ] Modal structure: Overlay → Modal → Header → Body → Footer
|
|
- [ ] Form inputs styled with proper tokens (bg-1, bg-3 borders)
|
|
- [ ] Empty states, loading states, and error states handled
|
|
- [ ] Dark theme first - ensure contrast with light text
|
|
|
|
### Git
|
|
|
|
- [ ] Meaningful commit messages (conventional commits format)
|
|
- [ ] No unrelated changes in commits
|
|
- [ ] Branch named correctly
|
|
- [ ] Based on latest main branch
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Common Commands
|
|
|
|
```bash
|
|
# Development
|
|
npm run dev # Start Electron editor
|
|
npm run test:editor # Run tests
|
|
npm run build:editor # Production build
|
|
npm run clean:all # Clear all caches
|
|
|
|
# Code Quality
|
|
npx eslint packages/noodl-editor/src --fix
|
|
npx prettier --write "packages/**/*.{ts,tsx}"
|
|
npx tsc --noEmit # Type check
|
|
|
|
# Debugging
|
|
DEBUG=* npm run dev # Verbose logging
|
|
npm run test:editor -- --verbose
|
|
|
|
# Finding Issues
|
|
grep -r "TSFixme" packages/
|
|
grep -rn "TODO\|FIXME" packages/noodl-editor/src
|
|
find packages/ -name "*.test.ts"
|
|
```
|
|
|
|
### Design Token Reference
|
|
|
|
| Purpose | Token |
|
|
| ----------------- | ------------------------------ |
|
|
| Panel backgrounds | `--theme-color-bg-2` |
|
|
| Card backgrounds | `--theme-color-bg-3` |
|
|
| Normal text | `--theme-color-fg-default` |
|
|
| Secondary text | `--theme-color-fg-default-shy` |
|
|
| Emphasized text | `--theme-color-fg-highlight` |
|
|
| Primary buttons | `--theme-color-primary` |
|
|
| Borders | `--theme-color-border-default` |
|
|
|
|
### Node Input Handler Reference
|
|
|
|
| Input Type | Handler | Callback |
|
|
| ---------- | --------------------- | --------------------------- |
|
|
| Signal | `valueChangedToTrue` | `function() { ... }` |
|
|
| Value | `set` | `function(value)` |
|
|
| Enum | `set` | `function(value)` |
|
|
| StringList | Explicit registration | Via `registerInputIfNeeded` |
|
|
|
|
---
|
|
|
|
## When to Ask Richard
|
|
|
|
- Task scope genuinely unclear (multiple valid approaches)
|
|
- Dependencies block all split strategies
|
|
- Still hitting limits after splitting subtasks
|
|
- Stuck in loop despite trying multiple approaches (offer to create research task doc)
|
|
|
|
---
|
|
|
|
_Last Updated: January 2026_
|
|
|
|
---
|
|
|
|
# ===== DISHANT (cline-dev-dishant) =====
|
|
|
|
## Sprint 1 Context
|
|
|
|
**Developer:** Dishant
|
|
**Branch:** `cline-dev-dishant`
|
|
**Other branch:** `cline-dev-richard`
|
|
**Sprint doc:** `dev-docs/sprints/sprint-1-18-feb-26/SPRINT-001-parallel-dev-protocol.md`
|
|
|
|
## Assigned Phases
|
|
|
|
- **Primary:** Phase 11 (Cloud Functions), Phase 10 (AI-Powered Development)
|
|
- **If time permits:** Phase 7 (Code Export)
|
|
|
|
## Task Order This Sprint
|
|
|
|
1. CF11-006 — Execution History Panel UI (Phase 11, unblocked)
|
|
2. CF11-007 — Canvas Execution Overlay (Phase 11, after CF11-006)
|
|
3. STRUCT-001 — JSON Schema Definition (Phase 10A, critical path start)
|
|
4. STRUCT-002 — Export Engine Core (Phase 10A, after STRUCT-001)
|
|
|
|
## Files I Own
|
|
|
|
- `dev-docs/tasks/phase-11-cloud-functions/PROGRESS-dishant.md` — my progress file
|
|
- `dev-docs/tasks/phase-10-ai-powered-development/PROGRESS-dishant.md` — my progress file
|
|
- All Phase 11 and Phase 10 task files
|
|
|
|
## Files I Must NOT Touch
|
|
|
|
- `dev-docs/tasks/phase-9-styles-overhaul/` — Richard's phase
|
|
- `dev-docs/tasks/phase-6-uba-system/` — Richard's phase
|
|
- `PROGRESS-richard.md` files — read only
|
|
|
|
## Pre-Task Protocol (Sprint 1)
|
|
|
|
Before each task, run:
|
|
```
|
|
git fetch origin
|
|
git log origin/cline-dev-richard --oneline --since="24 hours ago" --no-pager
|
|
```
|
|
Then read Richard's PROGRESS files for any shared utility/infra changes.
|
|
|
|
## Communication Style Override
|
|
|
|
**You are assisting Dishant**, a developer working in parallel with Richard on Sprint 1.
|
|
Same tone as Richard's section — direct, technical, casual, no hand-holding.
|
|
|
|
# ===== END DISHANT =====
|