1  # Git Hooks Test Procedure
  2  
  3  ## Overview
  4  This document provides a manual test procedure for validating the git hooks system that enables bidirectional supermodule relationship tracking.
  5  
  6  ## Test Setup
  7  
  8  ### Prerequisites
  9  - InterBrain plugin installed in Obsidian
 10  - Development vault with at least 3 DreamNodes (A, B, C)
 11  - DreamNode A will be the parent (contains DreamSong canvas)
 12  - DreamNodes B and C will be children (contain DreamTalk media)
 13  
 14  ### Create Test DreamNodes
 15  
 16  1. **Create DreamNode A** (parent):
 17     - Use InterBrain "Create DreamNode" command
 18     - Title: "Test Parent Node"
 19     - Type: dream
 20     - Note its UUID from `.udd` file
 21  
 22  2. **Create DreamNode B** (child 1):
 23     - Create another DreamNode
 24     - Title: "Test Child B"
 25     - Type: dream
 26     - Add some DreamTalk media (image, video, etc.)
 27     - Note its UUID
 28  
 29  3. **Create DreamNode C** (child 2):
 30     - Create another DreamNode
 31     - Title: "Test Child C"
 32     - Type: dream
 33     - Add some DreamTalk media
 34     - Note its UUID
 35  
 36  ## Test 1: Supermodule Tracking on Submodule Addition
 37  
 38  ### Steps
 39  
 40  1. **Create DreamSong canvas in Node A**:
 41     - Select DreamNode A
 42     - Run "Create DreamSong Canvas" command
 43     - Canvas should open in split view
 44  
 45  2. **Add external media to canvas**:
 46     - Drag DreamTalk media from Node B into the canvas
 47     - Drag DreamTalk media from Node C into the canvas
 48     - Save the canvas file
 49  
 50  3. **Sync submodules**:
 51     - Run "Sync Canvas Submodules" command (Ctrl+Shift+S)
 52     - Verify console logs show submodules imported
 53     - Verify canvas paths updated to reference submodules
 54  
 55  4. **Check git status**:
 56     - Open terminal in DreamNode A directory
 57     - Run `git log -1 --oneline`
 58     - Should see commit: "Sync submodules for canvas DreamSong: +2"
 59  
 60  5. **Verify post-commit hook ran**:
 61     - Run `git log -2 --oneline`
 62     - Should see TWO commits:
 63       - First: "Sync submodules for canvas DreamSong: +2"
 64       - Second: "Update submodule relationships"
 65  
 66  6. **Check parent's .udd file**:
 67     - Open `DreamNode A/.udd`
 68     - Verify `submodules` array contains UUIDs for B and C
 69     ```json
 70     {
 71       "submodules": ["uuid-of-B", "uuid-of-C"],
 72       ...
 73     }
 74     ```
 75  
 76  7. **Check child B's .udd file**:
 77     - Open `DreamNode B/.udd`
 78     - Verify `supermodules` array contains UUID of A
 79     ```json
 80     {
 81       "supermodules": ["uuid-of-A"],
 82       ...
 83     }
 84     ```
 85  
 86  8. **Check child C's .udd file**:
 87     - Open `DreamNode C/.udd`
 88     - Verify `supermodules` array contains UUID of A
 89     ```json
 90     {
 91       "supermodules": ["uuid-of-A"],
 92       ...
 93     }
 94     ```
 95  
 96  9. **Verify commits in child repos**:
 97     - Terminal in DreamNode B: `git log -1 --oneline`
 98     - Should see: "Add supermodule relationship: Test Parent Node"
 99     - Repeat for DreamNode C
100  
101  ### Expected Results
102  ✅ Parent's `.udd` tracks children via `submodules` array
103  ✅ Each child's `.udd` tracks parent via `supermodules` array
104  ✅ Bidirectional relationship established automatically
105  ✅ Commits created in both parent and child repos
106  
107  ## Test 2: Supermodule Tracking on Submodule Removal
108  
109  ### Steps
110  
111  1. **Remove media from canvas**:
112     - Open DreamNode A's DreamSong.canvas
113     - Delete all nodes that reference DreamNode C
114     - Save canvas
115  
116  2. **Sync submodules**:
117     - Run "Sync Canvas Submodules" command
118     - Verify console shows "Removed 1 unused submodule(s)"
119  
120  3. **Check git commits**:
121     - Terminal in DreamNode A: `git log -2 --oneline`
122     - Should see:
123       - First: "Remove 1 unused submodule(s) from DreamSong"
124       - Second: "Update submodule relationships"
125  
126  4. **Check parent's .udd file**:
127     - Open `DreamNode A/.udd`
128     - Verify `submodules` array no longer contains C's UUID
129     - Should only contain B's UUID
130     ```json
131     {
132       "submodules": ["uuid-of-B"],
133       ...
134     }
135     ```
136  
137  5. **Check child C's .udd file**:
138     - Note: Since submodule was removed, we can't update C's repo automatically
139     - The relationship will be stale in C until it's used again
140     - This is acceptable behavior
141  
142  ### Expected Results
143  ✅ Parent's `.udd` no longer tracks removed child
144  ✅ Submodule properly removed from git
145  ⚠️  Child's `supermodules` array becomes stale (acceptable)
146  
147  ## Test 3: Pre-Commit Hook Validation
148  
149  ### Steps
150  
151  1. **Create canvas without syncing**:
152     - Open DreamNode A's DreamSong.canvas
153     - Add more external media references
154     - Save canvas
155  
156  2. **Try to commit without syncing**:
157     - Terminal in DreamNode A
158     - Run: `git add DreamSong.canvas`
159     - Run: `git commit -m "Test commit"`
160  
161  3. **Check hook warning**:
162     - Should see warning message:
163       ```
164       ⚠️  DreamNode Pre-Commit Hook: Canvas file(s) detected in commit
165          If your canvas references external DreamNodes, remember to:
166          1. Run 'Sync Canvas Submodules' command BEFORE committing
167          2. This ensures submodule relationships are properly tracked
168       ```
169  
170  4. **Verify commit still proceeds**:
171     - Commit should succeed (hooks don't block)
172     - This is just a reminder, not enforcement
173  
174  ### Expected Results
175  ✅ Warning message appears when committing canvas files
176  ✅ Commit still proceeds (non-blocking reminder)
177  
178  ## Test 4: First Commit Initialization
179  
180  ### Steps
181  
182  1. **Create a new DreamNode via git template**:
183     - Use InterBrain's git template system
184     - Terminal: `git init --template=<path-to-InterBrain>/DreamNode-template`
185     - Add some initial file: `echo "test" > test.txt`
186     - Stage and commit: `git add . && git commit -m "Initial commit"`
187  
188  2. **Check hook output**:
189     - Should see: "DreamNode Pre-Commit Hook: Initial setup - moving template files to working directory"
190     - Should see: "✓ Moved .git/udd to .udd"
191     - Should see: "✓ DreamNode initialization complete"
192  
193  3. **Verify .udd file exists**:
194     - Check that `.udd` file exists in working directory (not in .git/)
195     - File should be committed in initial commit
196  
197  ### Expected Results
198  ✅ Template files moved from `.git/` to working directory
199  ✅ Files automatically staged and committed
200  ✅ DreamNode ready to use
201  
202  ## Troubleshooting
203  
204  ### Hook not running
205  - Check hook file permissions: `ls -l .git/hooks/`
206  - Should be executable: `-rwxr-xr-x`
207  - If not: `chmod +x .git/hooks/post-commit`
208  
209  ### "hook-helper.js not found" error
210  - Verify `hook-helper.js` exists in `DreamNode-template/hooks/`
211  - Check it was copied to `.git/hooks/` during git init
212  - Re-run git template initialization if needed
213  
214  ### Node.js errors in hooks
215  - Check Node.js is installed: `node --version`
216  - Check hook-helper script is executable: `chmod +x hook-helper.js`
217  - Review stderr output for specific error messages
218  
219  ### Submodule changes not detected
220  - Verify `.gitmodules` file exists and contains submodule entries
221  - Check git log to confirm submodule commit actually happened
222  - Try running hook manually: `node .git/hooks/hook-helper.js update-supermodules`
223  
224  ## Success Criteria
225  
226  All tests passing means:
227  - ✅ Post-commit hook automatically tracks bidirectional relationships
228  - ✅ Pre-commit hook provides helpful reminders
229  - ✅ Template initialization works correctly
230  - ✅ Supermodule/submodule arrays stay synchronized
231  - ✅ Coherence Beacon foundation is operational