memorylink 1.0.0

package/docs/FEATURE_1_GIT_SYNC_PLAN.md

@@ -0,0 +1,228 @@
+# 🎯 FEATURE 1: GIT SYNC COMMAND - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Create `memorylink sync` command that auto-stages, commits, and pushes `.memorylink/` files to Git.
+
+**Why:** Reduces friction for team collaboration - no manual `git add`, `git commit`, `git push` needed.
+
+**Priority:** 🔴 CRITICAL (Gemini flagged as critical blocker)  
+**Effort:** 1-2 hours  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTANCE CRITERIA
+
+### Must Have:
+- ✅ `memorylink sync` stages `.memorylink/` files
+- ✅ `memorylink sync` commits with descriptive message
+- ✅ `memorylink sync` pushes to remote (optional flag)
+- ✅ `memorylink sync --no-push` commits without pushing
+- ✅ `memorylink sync --check` shows conflicts/status
+- ✅ Clear error if Git not initialized
+- ✅ Clear error if no changes to commit
+- ✅ Works on Mac, Linux, Windows
+
+### Performance:
+- ✅ Operation completes in < 1 second
+- ✅ No memory leaks
+- ✅ Handles large `.memorylink/` directories
+
+### Error Handling:
+- ✅ Git not initialized → Clear error message
+- ✅ No changes → Informative message
+- ✅ Push fails → Clear error with suggestion
+- ✅ Conflicts → Show conflict status
+
+---
+
+## 🏗️ DESIGN
+
+### Command Structure:
+```bash
+memorylink sync [options]
+
+Options:
+  --no-push    Commit without pushing to remote
+  --check      Check sync status (conflicts, behind/ahead)
+  --message    Custom commit message (default: "Update MemoryLink logs")
+  --force      Force push (use with caution)
+```
+
+### Implementation Flow:
+```
+1. Check if Git is initialized
+   ├── If not → Error: "Git not initialized. Run: git init"
+   └── If yes → Continue
+
+2. Check if MemoryLink is initialized
+   ├── If not → Error: "MemoryLink not initialized. Run: memorylink init"
+   └── If yes → Continue
+
+3. Check for changes
+   ├── If no changes → Message: "No changes to commit"
+   └── If changes → Continue
+
+4. Stage .memorylink/ files
+   ├── git add .memorylink/
+   └── Handle errors
+
+5. Commit changes
+   ├── git commit -m "Update MemoryLink logs"
+   └── Handle errors
+
+6. Push to remote (if --no-push not set)
+   ├── git push
+   └── Handle errors
+```
+
+### Files to Create/Modify:
+- `src/commands/sync.ts` (NEW)
+- `src/cli.ts` (MODIFY - add sync command)
+- `src/commands/index.ts` (MODIFY - export sync command)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test `checkGitInitialized()` - returns true/false
+- [ ] Test `checkMemoryLinkInitialized()` - returns true/false
+- [ ] Test `checkForChanges()` - detects changes correctly
+- [ ] Test `stageFiles()` - stages .memorylink/ correctly
+- [ ] Test `commitChanges()` - commits with correct message
+- [ ] Test `pushChanges()` - pushes to remote
+- [ ] Test `checkSyncStatus()` - shows conflicts/status
+
+### Integration Tests:
+- [ ] Test full sync workflow (stage → commit → push)
+- [ ] Test sync with --no-push flag
+- [ ] Test sync with --check flag
+- [ ] Test sync with custom message
+- [ ] Test sync with no changes
+- [ ] Test sync with Git not initialized
+- [ ] Test sync with MemoryLink not initialized
+
+### End-to-End Tests:
+- [ ] Test in real Git repository
+- [ ] Test with actual .memorylink/ files
+- [ ] Test with remote repository
+- [ ] Test with conflicts
+- [ ] Test with no remote configured
+
+### Hard Tests (Edge Cases):
+- [ ] Test with large .memorylink/ directory (10k+ entries)
+- [ ] Test with network failure during push
+- [ ] Test with permission errors
+- [ ] Test with corrupted Git repository
+- [ ] Test with locked files
+- [ ] Test with concurrent Git operations
+- [ ] Test with rebase in progress
+- [ ] Test with merge conflicts
+
+### Performance Tests:
+- [ ] Test response time (< 1s for normal case)
+- [ ] Test with large files
+- [ ] Test memory usage
+
+### Cross-Platform Tests:
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows
+- [ ] Test path handling on all platforms
+
+### Manual Tests:
+- [ ] Real Git repository
+- [ ] Real .memorylink/ files
+- [ ] Real remote repository
+- [ ] Real user workflow
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Create sync.ts file
+- Create `src/commands/sync.ts`
+- Implement basic structure
+- Add error handling
+
+### Step 2: Implement Git operations
+- Check Git initialization
+- Check for changes
+- Stage files
+- Commit changes
+- Push changes
+
+### Step 3: Add CLI integration
+- Add command to `src/cli.ts`
+- Add export to `src/commands/index.ts`
+- Test command registration
+
+### Step 4: Write tests
+- Write unit tests
+- Write integration tests
+- Write E2E tests
+- Write hard tests
+
+### Step 5: Test everything
+- Run all tests
+- Manual testing
+- Cross-platform testing
+- Performance testing
+
+### Step 6: Verify
+- All tests pass
+- Performance acceptable
+- Code quality passes
+- Documentation updated
+
+---
+
+## 🚨 ERROR HANDLING
+
+### Error Cases:
+1. **Git not initialized**
+   - Error: "Git not initialized. Run: git init"
+   - Exit code: 1
+
+2. **MemoryLink not initialized**
+   - Error: "MemoryLink not initialized. Run: memorylink init"
+   - Exit code: 1
+
+3. **No changes to commit**
+   - Message: "No changes to commit"
+   - Exit code: 0 (not an error)
+
+4. **Push fails**
+   - Error: "Push failed: <reason>"
+   - Suggestion: "Run: git push manually"
+   - Exit code: 1
+
+5. **Conflicts detected**
+   - Warning: "Conflicts detected. Run: memorylink sync --check"
+   - Exit code: 1
+
+---
+
+## 📊 SUCCESS METRICS
+
+### Feature is Complete When:
+- ✅ All code written
+- ✅ All tests written
+- ✅ All tests pass (100%)
+- ✅ Performance < 1s
+- ✅ Code quality passes
+- ✅ Works on all platforms
+- ✅ Documentation updated
+- ✅ Manual testing done
+- ✅ No bugs found
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+

package/docs/FEATURE_2_AUTO_LOGGING_PLAN.md

@@ -0,0 +1,239 @@
+# 🎯 FEATURE 2: AUTO-LOGGING (GIT HOOKS) - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Automatically log file changes to `changes.log` via Git hooks when commits are made.
+
+**Why:** Reduces manual logging friction - users forget to log, leading to incomplete memories. Auto-logging ensures all changes are tracked.
+
+**Priority:** 🔴 CRITICAL (Gemini + Mistral flagged as critical blocker)  
+**Effort:** 1-2 days  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTANCE CRITERIA
+
+### Must Have:
+- ✅ `memorylink auto-log install` sets up Git post-commit hook
+- ✅ Post-commit hook automatically logs changes to `changes.log`
+- ✅ Commit messages parsed and included in log entries
+- ✅ File diffs captured (which files changed)
+- ✅ Works with regular commits, merge commits, rebase
+- ✅ `memorylink auto-log uninstall` removes hook
+- ✅ `memorylink auto-log status` shows hook status
+- ✅ Clear error if Git not initialized
+- ✅ Works on Mac, Linux, Windows
+
+### Performance:
+- ✅ Hook execution completes in < 500ms
+- ✅ No noticeable delay in git commit
+- ✅ Handles large commits (100+ files)
+
+### Error Handling:
+- ✅ Git not initialized → Clear error
+- ✅ Hook already exists → Warn and ask to overwrite
+- ✅ Hook execution fails → Log error but don't block commit
+- ✅ No changes → Skip logging
+
+---
+
+## 🏗️ DESIGN
+
+### Command Structure:
+```bash
+memorylink auto-log install [options]
+memorylink auto-log uninstall
+memorylink auto-log status
+```
+
+### Implementation Flow:
+```
+Post-Commit Hook Flow:
+1. Get commit hash (HEAD)
+2. Get commit message
+3. Get list of changed files
+4. Get file diffs (optional)
+5. For each changed file:
+   ├── Check if file is protected (skip if protected)
+   ├── Create changes.log entry
+   └── Append to changes.log
+6. Log commit summary
+```
+
+### Hook Template:
+```bash
+#!/bin/sh
+# MemoryLink Auto-Logging Hook
+# Automatically logs changes to changes.log
+
+# Get commit info
+COMMIT_HASH=$(git rev-parse HEAD)
+COMMIT_MSG=$(git log -1 --pretty=%B)
+CHANGED_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD)
+
+# Run memorylink auto-log
+memorylink auto-log commit "$COMMIT_HASH" "$COMMIT_MSG" "$CHANGED_FILES"
+```
+
+### Files to Create/Modify:
+- `src/commands/auto-log.ts` (NEW)
+- `src/cli.ts` (MODIFY - add auto-log command)
+- `src/commands/index.ts` (MODIFY - export auto-log command)
+- `templates/post-commit-hook` (NEW)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test `installHook()` - creates hook file correctly
+- [ ] Test `uninstallHook()` - removes hook file
+- [ ] Test `checkHookStatus()` - detects hook presence
+- [ ] Test `parseCommitMessage()` - parses commit message
+- [ ] Test `getChangedFiles()` - gets file list from commit
+- [ ] Test `createChangeEntries()` - creates log entries
+- [ ] Test `filterProtectedFiles()` - skips protected files
+- [ ] Test `executeHook()` - runs hook logic
+
+### Integration Tests:
+- [ ] Test full install → commit → auto-log workflow
+- [ ] Test uninstall removes hook
+- [ ] Test status shows correct state
+- [ ] Test hook with regular commit
+- [ ] Test hook with merge commit
+- [ ] Test hook with rebase
+- [ ] Test hook with multiple files
+- [ ] Test hook skips protected files
+
+### End-to-End Tests:
+- [ ] Test in real Git repository
+- [ ] Test with actual commits
+- [ ] Test with actual .memorylink/ files
+- [ ] Test hook execution timing
+- [ ] Test with large commits
+
+### Hard Tests (Edge Cases):
+- [ ] Test with 100+ files in commit
+- [ ] Test with very long commit message
+- [ ] Test with binary files
+- [ ] Test with deleted files
+- [ ] Test with renamed files
+- [ ] Test with merge conflicts
+- [ ] Test with rebase in progress
+- [ ] Test with corrupted Git repository
+- [ ] Test with no changes (empty commit)
+- [ ] Test with all files protected
+
+### Performance Tests:
+- [ ] Test hook execution time (< 500ms)
+- [ ] Test with large diffs
+- [ ] Test with many files
+- [ ] Test memory usage
+
+### Cross-Platform Tests:
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows
+- [ ] Test path handling on all platforms
+- [ ] Test hook permissions on all platforms
+
+### Manual Tests:
+- [ ] Real Git repository
+- [ ] Real commits
+- [ ] Real file changes
+- [ ] Real user workflow
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Create auto-log.ts file
+- Create `src/commands/auto-log.ts`
+- Implement install/uninstall/status commands
+- Add hook template generation
+
+### Step 2: Implement hook logic
+- Parse commit information
+- Get changed files
+- Create change entries
+- Filter protected files
+- Append to changes.log
+
+### Step 3: Create hook template
+- Create `templates/post-commit-hook`
+- Make it executable
+- Handle all platforms
+
+### Step 4: Add CLI integration
+- Add command to `src/cli.ts`
+- Add export to `src/commands/index.ts`
+- Test command registration
+
+### Step 5: Write tests
+- Write unit tests
+- Write integration tests
+- Write E2E tests
+- Write hard tests
+
+### Step 6: Test everything
+- Run all tests
+- Manual testing
+- Cross-platform testing
+- Performance testing
+
+### Step 7: Verify
+- All tests pass
+- Performance acceptable
+- Code quality passes
+- Documentation updated
+
+---
+
+## 🚨 ERROR HANDLING
+
+### Error Cases:
+1. **Git not initialized**
+   - Error: "Git not initialized. Run: git init"
+   - Exit code: 1
+
+2. **MemoryLink not initialized**
+   - Error: "MemoryLink not initialized. Run: memorylink init"
+   - Exit code: 1
+
+3. **Hook already exists**
+   - Warn: "Hook already exists. Overwrite? (y/n)"
+   - Option to backup existing hook
+
+4. **Hook execution fails**
+   - Log error to stderr
+   - Don't block commit (post-commit hook)
+   - Return exit code 0
+
+5. **No changes in commit**
+   - Skip logging
+   - Exit code 0 (not an error)
+
+---
+
+## 📊 SUCCESS METRICS
+
+### Feature is Complete When:
+- ✅ All code written
+- ✅ All tests written
+- ✅ All tests pass (100%)
+- ✅ Performance < 500ms
+- ✅ Code quality passes
+- ✅ Works on all platforms
+- ✅ Documentation updated
+- ✅ Manual testing done
+- ✅ No bugs found
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+

package/docs/FEATURE_3_CODE_SNIPPET_PLAN.md

@@ -0,0 +1,249 @@
+# 🎯 FEATURE 3: CODE SNIPPET DATA TYPE - IMPLEMENTATION PLAN
+
+## 📋 REQUIREMENT
+
+**Goal:** Add `code_snippet` memory type to store actual code blocks (not just file references).
+
+**Why:** Users need to store reusable code snippets, patterns, and examples. File references are insufficient for code-heavy workflows.
+
+**Priority:** 🔴 CRITICAL (Gemini + Mistral flagged as critical blocker)  
+**Effort:** 2-3 days  
+**Status:** 🔴 Not Started
+
+---
+
+## 🎯 ACCEPTANCE CRITERIA
+
+### Must Have:
+- ✅ New memory type: `code_snippet`
+- ✅ Store actual code (not just file reference)
+- ✅ Store file path, language, line numbers
+- ✅ `memorylink snippet` command
+- ✅ Code snippets appear in `get-context` output
+- ✅ Code snippets searchable
+- ✅ Size limit (< 1KB per snippet)
+- ✅ Syntax highlighting info stored
+- ✅ Works on all platforms
+
+### Performance:
+- ✅ Operation completes in < 100ms
+- ✅ No memory leaks
+- ✅ Handles large code blocks efficiently
+
+### Error Handling:
+- ✅ Empty code → Clear error
+- ✅ Code too large → Clear error with limit
+- ✅ Invalid language → Warning but allow
+- ✅ File not found → Clear error
+
+---
+
+## 🏗️ DESIGN
+
+### Data Structure:
+```typescript
+export type MemoryType = 'note' | 'decision' | 'doc_ref' | 'context' | 'rule' | 'code_snippet';
+
+export interface CodeSnippetEntry extends MemoryEntry {
+  type: 'code_snippet';
+  details: string; // Description of the snippet
+  code: string; // Actual code content
+  language?: string; // Programming language (typescript, python, etc.)
+  file?: string; // Source file path (optional)
+  lines?: string; // Line range (e.g., "42-50" or "42")
+  context?: string; // Why this snippet is important
+}
+```
+
+### Command Structure:
+```bash
+memorylink snippet <description> [options]
+
+Options:
+  --code <code>        Code content (or use --file)
+  --file <path>        Read code from file
+  --lines <range>      Line range (e.g., "42-50")
+  --language <lang>    Programming language
+  --context <text>     Why this snippet is important
+  --tags <tags>        Comma-separated tags
+```
+
+### Implementation Flow:
+```
+1. Validate input (description required)
+2. Get code (from --code or --file)
+3. Validate code size (< 1KB)
+4. Detect language (if not provided)
+5. Create code_snippet entry
+6. Append to memory.log
+7. Return entry
+```
+
+### Files to Create/Modify:
+- `src/types.ts` (MODIFY - add code_snippet type)
+- `src/commands/snippet.ts` (NEW)
+- `src/commands/context.ts` (MODIFY - include snippets)
+- `src/commands/search.ts` (MODIFY - search code content)
+- `src/commands/memory.ts` (MODIFY - support code_snippet type)
+- `src/memorylink.ts` (MODIFY - add addCodeSnippet method)
+- `src/cli.ts` (MODIFY - add snippet command)
+
+---
+
+## 🧪 TEST PLAN (100% Coverage)
+
+### Unit Tests:
+- [ ] Test `createCodeSnippet()` - creates entry correctly
+- [ ] Test `validateCodeSize()` - enforces 1KB limit
+- [ ] Test `detectLanguage()` - detects from file extension
+- [ ] Test `readCodeFromFile()` - reads file correctly
+- [ ] Test `extractLines()` - extracts line range
+- [ ] Test `parseCodeSnippet()` - parses entry correctly
+
+### Integration Tests:
+- [ ] Test `memorylink snippet` command works
+- [ ] Test snippet stored in memory.log
+- [ ] Test snippet appears in get-context
+- [ ] Test snippet searchable
+- [ ] Test --file option works
+- [ ] Test --code option works
+- [ ] Test --lines option works
+- [ ] Test language detection works
+
+### End-to-End Tests:
+- [ ] Test in real project
+- [ ] Test with actual code files
+- [ ] Test with different languages
+- [ ] Test with line ranges
+- [ ] Test full workflow (add → search → get-context)
+
+### Hard Tests (Edge Cases):
+- [ ] Test with code > 1KB (should error)
+- [ ] Test with empty code (should error)
+- [ ] Test with binary files (should error)
+- [ ] Test with very long lines
+- [ ] Test with special characters
+- [ ] Test with unicode characters
+- [ ] Test with missing file
+- [ ] Test with invalid line range
+- [ ] Test with large file (> 10MB)
+
+### Performance Tests:
+- [ ] Test response time (< 100ms)
+- [ ] Test with large code blocks
+- [ ] Test memory usage
+
+### Cross-Platform Tests:
+- [ ] Test on macOS
+- [ ] Test on Linux
+- [ ] Test on Windows
+- [ ] Test path handling on all platforms
+
+### Manual Tests:
+- [ ] Real code snippets
+- [ ] Real file reading
+- [ ] Real user workflow
+
+---
+
+## 📝 IMPLEMENTATION STEPS
+
+### Step 1: Update types.ts
+- Add `'code_snippet'` to `MemoryType`
+- Add `CodeSnippetEntry` interface
+- Update type guards
+
+### Step 2: Create snippet.ts
+- Implement `snippetCommand()`
+- Implement code reading logic
+- Implement validation logic
+- Implement language detection
+
+### Step 3: Update context.ts
+- Include code snippets in output
+- Format code snippets nicely
+- Show language, file, lines
+
+### Step 4: Update search.ts
+- Search code snippet content
+- Search code snippet language
+- Highlight matches in code
+
+### Step 5: Update memory.ts
+- Support `--type code_snippet`
+- Validate code snippet fields
+
+### Step 6: Update memorylink.ts
+- Add `addCodeSnippet()` method
+- Add code snippet helpers
+
+### Step 7: Add CLI integration
+- Add command to `src/cli.ts`
+- Add export to `src/commands/index.ts`
+
+### Step 8: Write tests
+- Write unit tests
+- Write integration tests
+- Write E2E tests
+- Write hard tests
+
+### Step 9: Test everything
+- Run all tests
+- Manual testing
+- Cross-platform testing
+- Performance testing
+
+### Step 10: Verify
+- All tests pass
+- Performance acceptable
+- Code quality passes
+- Documentation updated
+
+---
+
+## 🚨 ERROR HANDLING
+
+### Error Cases:
+1. **Empty description**
+   - Error: "Description cannot be empty"
+   - Exit code: 1
+
+2. **No code provided**
+   - Error: "Code required. Use --code or --file"
+   - Exit code: 1
+
+3. **Code too large (> 1KB)**
+   - Error: "Code snippet too large (max 1KB). Use doc_ref for larger files."
+   - Exit code: 1
+
+4. **File not found**
+   - Error: "File not found: <path>"
+   - Exit code: 1
+
+5. **Invalid line range**
+   - Error: "Invalid line range. Use format: '42' or '42-50'"
+   - Exit code: 1
+
+---
+
+## 📊 SUCCESS METRICS
+
+### Feature is Complete When:
+- ✅ All code written
+- ✅ All tests written
+- ✅ All tests pass (100%)
+- ✅ Performance < 100ms
+- ✅ Code quality passes
+- ✅ Works on all platforms
+- ✅ Documentation updated
+- ✅ Manual testing done
+- ✅ No bugs found
+
+---
+
+## 📅 Document History
+
+- **Created:** December 13, 2025
+- **Status:** 🔴 Planning Complete - Ready to Develop
+- **Version:** 1.0.0
+