kinemotion 0.32.0__tar.gz → 0.32.2__tar.gz

{kinemotion-0.32.0 → kinemotion-0.32.2}/.basic-memory/deployment/vercel-monorepo-deployment-best-practice.md

@@ -1,7 +1,7 @@
 ---
 title: Vercel Monorepo Deployment Best Practice
 type: note
-permalink: deployment/vercel-monorepo-best-practice
+permalink: deployment/vercel-monorepo-deployment-best-practice
 tags:
 - vercel
 - deployment

kinemotion-0.32.2/.basic-memory/development/basic-memory-naming-hook-analysis.md

@@ -0,0 +1,148 @@
+---
+title: Basic Memory Naming Hook Analysis and Fix
+type: note
+permalink: development/basic-memory-naming-hook-analysis
+tags:
+  - development
+  - tooling
+  - naming-conventions
+  - hook
+---
+
+# Basic Memory Naming Hook Analysis and Fix
+
+## Issue Identified
+
+The hook script `/.claude/hooks/fix-basic-memory-names.sh` was not properly converting filenames to kebab-case when creating `.basic-memory/` notes. Files were being created with concatenated names like:
+
+❌ `frontenddependenciesanalysisnov2025.md`
+
+Instead of:
+
+✅ `frontend-dependencies-analysis-nov-2025.md`
+
+## Root Cause Analysis
+
+The hook script had **two distinct problems**:
+
+### 1. **Original Function Logic Flaw**
+The `to_kebab_case()` function wasn't handling word boundaries correctly:
+
+```bash
+# OLD (broken)
+sed 's/[[:space:]]\+/-/g' |        # Convert spaces to hyphens
+tr '[:upper:]' '[:lower:]' |       # Convert to lowercase
+sed 's/[^a-z0-9-]//g'             # Remove non-alphanumeric (except hyphens)
+```
+
+**Problem**: Without camelCase handling, "Frontend Dependencies" → "frontend dependencies" → "frontenddependencies" (spaces already removed, can't convert to hyphens)
+
+### 2. **Files Created Without Separators**
+More critically: When files are **created without word separators** (spaces, underscores, camelCase), the hook cannot reverse-engineer word boundaries. For example:
+- Input: `frontenddependenciesanalysisnov2025` (no separators)
+- Function output: `frontenddependenciesanalysisnov2025` (no way to know where word breaks are)
+
+**This is a limitation of any text-based kebab-case conversion function** - it requires existing word boundaries to work with.
+
+## Solution Implemented
+
+### 1. **Enhanced Kebab-Case Function**
+Added camelCase handling to the conversion function:
+
+```bash
+to_kebab_case() {
+    echo "$1" | \
+        sed 's/[[:space:]]\+/-/g' |              # Spaces → hyphens
+        sed 's/\([a-z]\)\([A-Z]\)/\1-\2/g' |    # camelCase → kebab-case
+        tr '[:upper:]' '[:lower:]' |             # All lowercase
+        sed 's/[^a-z0-9-]//g' |                  # Remove non-alphanumeric
+        sed 's/-\+/-/g'                          # Collapse multiple hyphens
+}
+```
+
+Now handles:
+- ✅ `"Frontend Dependencies Analysis"` → `frontend-dependencies-analysis`
+- ✅ `"CMJPhysiologicalBounds"` → `cmj-physiological-bounds`
+- ✅ `"Test-File-Name"` → `test-file-name`
+
+### 2. **Fixed Bash Syntax Error**
+**Critical bug found:** The original script used `local` keyword outside of function scope, which caused "can only be used in a function" errors.
+
+**Fixed by:** Removing `local` keyword from script-level variables. Variables are now declared without `local`:
+
+```bash
+# BEFORE (broken)
+dir=$(dirname "$file")        # ❌ Inside while loop, not a function
+basename=$(basename "$file")
+
+# AFTER (fixed)
+dir=$(dirname "$file")        # ✅ Works correctly now
+basename=$(basename "$file")
+```
+
+### 3. **Detection for Concatenated Filenames**
+Added logic to detect and warn about files with no word separators:
+
+```bash
+# Check if the new_name is significantly shorter (indicates concatenation)
+original_len=${#basename}
+new_len=${#new_name}
+if [ $((original_len - new_len)) -gt 5 ]; then
+    echo "⚠️  Cannot auto-fix: $basename (no word separators detected)"
+    echo "   → Please rename manually to follow kebab-case"
+```
+
+Now the hook will:
+- ✅ Auto-fix: `"Frontend Dependencies Analysis.md"` → `frontend-dependencies-analysis.md`
+- ✅ Auto-fix: `"CMJPhysiologicalBounds.md"` → `cmj-physiological-bounds.md`
+- ⚠️ Warn about: `"frontenddependenciesanalysisnov2025.md"` (needs manual rename)
+
+### 4. **Manual File Fix**
+Fixed the existing incorrectly-named file:
+
+```bash
+# BEFORE
+.basic-memory/development/frontenddependenciesanalysisnov2025.md
+
+# AFTER
+.basic-memory/development/frontend-dependencies-analysis-nov-2025.md
+```
+
+### 5. **Comprehensive Summary Output**
+The hook now provides clear feedback:
+
+```bash
+✅ Fixed 26 basic-memory filename(s) to kebab-case
+⚠️  Found X file(s) that need manual renaming
+```
+
+## How to Prevent Future Issues
+
+When creating new `.basic-memory/` notes, ensure that **naming functions already use word separators**:
+
+### ✅ GOOD: Uses spaces (or camelCase)
+```markdown
+write_note("Frontend Dependencies Analysis Nov 2025", "...", "development")
+```
+
+### ❌ AVOID: Concatenated without separators
+```markdown
+write_note("FrontendDependenciesAnalysisNov2025", "...", "development")
+```
+
+## Hook Behavior Summary
+
+The hook now:
+
+1. **Scans** all `.basic-memory/**/*.md` files
+2. **Attempts auto-fix** for files with word separators (spaces, camelCase, etc.)
+3. **Warns** about files with no detectable word boundaries
+4. **Git stages** all changes automatically
+5. **Outputs summary** of what was fixed or needs attention
+
+**Trigger**: Runs after user prompts (when using Claude Code hooks)
+
+## Files Updated
+
+- ✅ `.claude/hooks/fix-basic-memory-names.sh` - Enhanced conversion logic + detection
+- ✅ `.basic-memory/development/frontend-dependencies-analysis-nov-2025.md` - Renamed from concatenated version

kinemotion-0.32.2/.basic-memory/development/claude-code-hook-configuration.md

@@ -0,0 +1,343 @@
+---
+title: Claude Code Hook Configuration - best-basic-memory-names
+type: note
+permalink: development/claude-code-hook-configuration
+tags:
+  - development
+  - tooling
+  - hooks
+  - claude-code
+  - automation
+  - naming-conventions
+---
+
+# Claude Code Hook Configuration: fix-basic-memory-names
+
+## Overview
+
+This document describes the complete configuration of the `fix-basic-memory-names` hook, which automatically normalizes `.basic-memory/` filenames to follow kebab-case naming conventions.
+
+**Hook Type:** `UserPromptSubmit`
+**Script:** `.claude/hooks/fix-basic-memory-names.sh`
+**Configuration File:** `.claude/settings.local.json`
+
+## Why This Matters
+
+The `.basic-memory/` directory stores project knowledge, and filename consistency is critical for:
+- **Predictability**: Easy to guess and find notes
+- **URL safety**: Kebab-case works in URLs and permalinks
+- **Tool compatibility**: MCP basic-memory functions require consistent naming
+- **Git history**: Consistent naming reduces merge conflicts
+
+## Hook Configuration
+
+### Hook Registration
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/fix-basic-memory-names.sh",
+            "statusMessage": "Normalizing basic-memory filenames to kebab-case...",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Location:** `.claude/settings.local.json` (lines 3-17)
+
+### Configuration Details
+
+| Field | Value | Purpose |
+|-------|-------|---------|
+| **Hook Type** | `UserPromptSubmit` | Runs when user submits a prompt, before Claude processes it |
+| **Script Path** | `$CLAUDE_PROJECT_DIR/.claude/hooks/fix-basic-memory-names.sh` | Absolute reference to hook script (expandable) |
+| **Status Message** | "Normalizing basic-memory filenames to kebab-case..." | User-visible feedback during execution |
+| **Timeout** | 30000 ms (30s) | Reasonable for file I/O operations across many files |
+
+## Script Implementation
+
+### Entry Point
+
+```bash
+#!/bin/bash
+set -euo pipefail
+```
+
+**Why `set -euo pipefail`?**
+- `set -e` - Exit immediately if any command fails
+- `set -u` - Error on undefined variables
+- `set -o pipefail` - Pipe fails if any command in chain fails
+- Makes script robust and fail-fast
+
+### Error Handling
+
+```bash
+handle_error() {
+    local line_num=$1
+    echo "❌ Hook error on line $line_num" >&2
+    exit 1
+}
+trap 'handle_error $LINENO' ERR
+```
+
+**Features:**
+- Catches errors and reports exact line number
+- Outputs to stderr (standard for errors)
+- Exits cleanly with error code 1
+- Claude Code recognizes this and blocks operations if needed
+
+### Debug Logging
+
+```bash
+DEBUG="${DEBUG:-0}"
+debug_log() {
+    if [ "$DEBUG" = "1" ]; then
+        echo "[DEBUG] $*" >&2
+    fi
+}
+```
+
+**Usage:**
+```bash
+# Enable debug logging when testing
+DEBUG=1 bash .claude/hooks/fix-basic-memory-names.sh
+
+# Normal execution (no debug output)
+bash .claude/hooks/fix-basic-memory-names.sh
+```
+
+### Kebab-Case Conversion
+
+The `to_kebab_case()` function handles:
+
+1. **Spaces** → hyphens: `"Frontend Dependencies"` → `"frontend-dependencies"`
+2. **camelCase** → kebab-case: `"CMJPhysiologicalBounds"` → `"cmj-physiological-bounds"`
+3. **Mixed separators**: `"Test-File-Name"` → `"test-file-name"`
+4. **Multiple hyphens**: Collapse to single hyphen
+
+```bash
+to_kebab_case() {
+    echo "$1" | \
+        sed 's/[[:space:]]\+/-/g' |              # Spaces → hyphens
+        sed 's/\([a-z]\)\([A-Z]\)/\1-\2/g' |    # camelCase → kebab-case
+        tr '[:upper:]' '[:lower:]' |             # All lowercase
+        sed 's/[^a-z0-9-]//g' |                  # Remove non-alphanumeric (except hyphens)
+        sed 's/-\+/-/g'                          # Collapse multiple hyphens
+}
+```
+
+### File Processing Loop
+
+```bash
+while IFS= read -r file; do
+    # ... validation ...
+    dir=$(dirname "$file")
+    basename=$(basename "$file")
+    new_name=$(to_kebab_case "${basename%.md}")
+    new_path="${dir}/${new_name}.md"
+
+    if [ "$file" != "$new_path" ]; then
+        # Check for concatenation (no word separators)
+        original_len=${#basename}
+        new_len=${#new_name}
+
+        if [ $((original_len - new_len)) -gt 5 ]; then
+            # ⚠️ Cannot auto-fix - warn user
+        else
+            # ✅ Auto-fix with git staging
+            git rm --cached "$file" 2>/dev/null || true
+            mv "$file" "$new_path"
+            git add "$new_path" 2>/dev/null || true
+        fi
+    fi
+done < <(find .basic-memory -name "*.md" -type f 2>/dev/null || true)
+```
+
+**Key behaviors:**
+- Safely iterates with `IFS= read -r` (handles spaces/special chars)
+- Detects concatenated filenames (no separators) and warns instead of mangling
+- Stages git operations immediately for clean commit history
+- Continues on find errors (|| true)
+
+### Exit Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | Hook completed, files may have been fixed |
+| 1 | Error | Hook encountered errors, Claude Code may block |
+
+## Best Practices Applied
+
+### 1. Script Initialization
+✅ Shebang: `#!/bin/bash` (portable)
+✅ Error handling: `set -euo pipefail` with trap
+✅ Documented: Comments for each section
+
+### 2. Security
+✅ No recursive eval or backticks
+✅ Quoted variables: `"$var"` not $var
+✅ Minimal git operations (rm/add only)
+
+### 3. User Feedback
+✅ Status messages for each outcome
+✅ Debug logging for troubleshooting
+✅ Clear warnings for manual intervention
+
+### 4. Reliability
+✅ Timeout protection: 30s limit in config
+✅ Error recovery: Continues on transient failures
+✅ Atomic operations: Git staging prevents corruption
+
+## Troubleshooting
+
+### Hook Not Running
+
+**Check 1: Script Executable?**
+```bash
+ls -la .claude/hooks/fix-basic-memory-names.sh
+# Should show: -rwx--x--x (755 permissions)
+chmod +x .claude/hooks/fix-basic-memory-names.sh  # Fix if needed
+```
+
+**Check 2: Configuration Correct?**
+```bash
+# View hook configuration
+cat .claude/settings.local.json | grep -A 5 "UserPromptSubmit"
+
+# Should see reference to fix-basic-memory-names.sh
+```
+
+**Check 3: Enable Debug Logging**
+```bash
+# Test hook directly
+cd /project/root
+DEBUG=1 bash .claude/hooks/fix-basic-memory-names.sh
+```
+
+### Files Not Being Renamed
+
+**Likely causes:**
+1. Files already have correct names (no changes needed)
+2. Files have no word separators (concatenated) - hook warns instead
+3. Git operations failing (check permissions)
+
+**Debug:**
+```bash
+DEBUG=1 bash .claude/hooks/fix-basic-memory-names.sh
+# Look for "[DEBUG]" output lines showing what was checked
+```
+
+### Timeout Errors
+
+If hook times out (> 30s):
+- Increase timeout in settings.json: `"timeout": 60000`
+- Check if find is slow: `time find .basic-memory -name "*.md"`
+- If needed, exclude large directories with `! -path "*/.git/*"`
+
+## Testing the Hook
+
+### Manual Test
+
+```bash
+cd /Users/feniix/src/personal/cursor/dropjump-claude
+
+# Test with debug output
+DEBUG=1 bash .claude/hooks/fix-basic-memory-names.sh
+
+# Expected output:
+# [DEBUG] Starting basic-memory filename normalization
+# [DEBUG] Scan complete: fixed=0 warned=0 errors=0
+```
+
+### Create Test File
+
+```bash
+# Create a test file with bad naming
+touch .basic-memory/development/TestBadNaming.md
+
+# Run hook
+bash .claude/hooks/fix-basic-memory-names.sh
+
+# Check result
+ls .basic-memory/development/ | grep -i test
+# Should show: test-bad-naming.md
+
+# Clean up
+rm .basic-memory/development/test-bad-naming.md
+```
+
+## Integration with Claude Code
+
+### How It Works in Claude Code
+
+1. **User submits prompt** → Hook triggered
+2. **Hook scans** `.basic-memory/*.md` files
+3. **For each file:**
+   - Compare current vs. kebab-case name
+   - If different AND has word separators → Auto-fix
+   - If different AND NO word separators → Warn user
+4. **Git staging** happens automatically
+5. **Hook exits** with status code (0=success, 1=error)
+
+### Performance Impact
+
+- **Overhead**: ~50-200ms per prompt (depends on file count)
+- **Files scanned**: All `.basic-memory/**/*.md` (~30-40 files typically)
+- **Operations**: Quick stat checks + optional git operations
+
+## Related Files
+
+- **Hook Script**: `.claude/hooks/fix-basic-memory-names.sh`
+- **Configuration**: `.claude/settings.local.json`
+- **Analysis Document**: `.basic-memory/development/basic-memory-naming-hook-analysis.md`
+- **Official Docs**: https://docs.claude.com/en/docs/claude-code/hooks-guide
+
+## References
+
+### Claude Code Hooks Guide
+https://docs.claude.com/en/docs/claude-code/hooks-guide
+
+### Key Sections
+- Hook Events Overview - explains UserPromptSubmit and others
+- Code Formatting Hook - example of PostToolUse hook
+- File Protection Hook - example of using jq for input parsing
+
+### Bash Best Practices
+- `set -euo pipefail` - Standard for robust scripts
+- `trap 'cleanup' EXIT` - Cleanup pattern
+- Error handling with `$?` - Exit code checking
+
+## Maintenance
+
+### When to Update
+
+| Scenario | Action |
+|----------|--------|
+| Add new `.basic-memory/` folder | Hook automatically covers (uses find) |
+| Change kebab-case rules | Update `to_kebab_case()` function |
+| Adjust timeout | Edit `settings.local.json` timeout value |
+| Add debug capability | Already supported (DEBUG=1) |
+
+### Version History
+
+- **v1.0** - Initial implementation with camelCase support
+- **v1.1** - Added debug logging and error handling
+- **v1.2** - Added detection for concatenated filenames (no auto-fix)
+- **v2.0** - Proper configuration in settings.json with timeout
+
+## Future Improvements
+
+- [ ] Check for duplicate files after renaming
+- [ ] Support for other file types (.json, .yml)
+- [ ] Logging to file for audit trail
+- [ ] Integration with Git pre-commit hook
+- [ ] Webhook notifications on changes

kinemotion-0.32.2/.basic-memory/development/frontend-dependencies-analysis-nov-2025.md

@@ -0,0 +1,186 @@
+---
+title: Frontend Dependencies Analysis Nov 2025
+type: note
+permalink: development/frontend-dependencies-analysis-nov-2025-1
+tags:
+- frontend
+- dependencies
+- vite
+- react
+- typescript
+- devops
+---
+
+# Frontend Dependencies Analysis - November 2025
+
+## Current State
+- React: ^18.3.1 (April 2024)
+- Vite: ^5.1.0 (January 2024)
+- TypeScript: ^5.3.3 (November 2023)
+- Terser: ^5.31.0 (just added - GOOD)
+- @vitejs/plugin-react: ^4.3.0
+- @types packages: vary from 18.3.0 to 20.11.0
+
+## Latest Available Versions
+
+### React Ecosystem
+- **React Latest**: 19.2.0 (October 2025) - mature, 1+ year stable
+- **React 18 Latest**: 18.3.1 (April 2024) - still maintained, zero CVEs
+- **React DOM Latest**: 19.2.0 or 18.3.1
+- **@types/react Latest**: 18.3.3 (for React 18)
+- **@types/react-dom Latest**: 18.3.0 (for React 18)
+
+### Build Tools
+- **Vite Latest**: 6.3+ (November 2025) - production-ready since Dec 2024
+- **Vite 5 Latest**: 5.4.1 (still maintained)
+- **@vitejs/plugin-react Latest**: 4.3.x (works with both Vite 5 & 6)
+- **TypeScript Latest**: 5.9.x (December 2024)
+
+### Code Quality
+- **Terser Latest**: 5.31.0+ (current, good)
+- **@types/node Latest**: 20.12.x (safe patch bump from 20.11.0)
+
+## Codebase Compatibility Assessment
+
+### React 19 Readiness: ✅ READY
+The codebase is **already React 19 compatible**:
+- Using `React.createRoot()` (modern API) ✓
+- Using modern hooks (useState, useEffect, useContext) ✓
+- No PropTypes (using TypeScript instead) ✓
+- No string refs or legacy APIs ✓
+- No findDOMNode usage ✓
+- Proper Error Boundary implementation ✓
+- Using React.StrictMode ✓
+
+### Vite 6 Readiness: ✅ READY
+Simple SPA configuration is backward compatible:
+- Minimal vite.config.ts (no advanced features) ✓
+- Using @vitejs/plugin-react (stable in both v5 & v6) ✓
+- No SSR configuration ✓
+- Standard TypeScript config ✓
+
+## MVP Deployment Recommendation
+
+### TIER 1: IMMEDIATE UPGRADES (Safe, Zero Risk)
+```json
+{
+  "typescript": "^5.9.3",
+  "@types/node": "^20.12.0",
+  "@types/react": "^18.3.3",
+  "@types/react-dom": "^18.3.0",
+  "terser": "^5.31.0"
+}
+```
+**Rationale**: All safe minor/patch updates, no breaking changes, better TypeScript strict mode compliance
+
+### TIER 2: OPTIONAL (Very Low Risk)
+```json
+{
+  "vite": "^5.4.1"
+}
+```
+**Rationale**: Stay on Vite 5 (fully maintained), get latest v5 features without major refactor
+
+### TIER 3: POST-MVP (After Validation)
+```json
+{
+  "react": "^19.2.0",
+  "react-dom": "^19.2.0",
+  "vite": "^6.3.0"
+}
+```
+**Rationale**: After MVP validation, upgrade to latest stable versions with new capabilities
+
+## Breaking Changes Analysis
+
+### React 18 → 19
+**If upgrading later:**
+- Removed: ReactDOM.render (we use createRoot ✓)
+- Removed: PropTypes (we use TypeScript ✓)
+- Removed: Legacy Context API (not used ✓)
+- Changed: Error handling via window.reportError
+- No changes needed to current codebase
+
+### Vite 5 → 6
+**If upgrading later:**
+- Environment API changes (internal only, backward compatible)
+- Default browser target updated (baseline-widely-available)
+- Removed: Sass legacy API (not used)
+- Node.js requirement: 20.19+ / 22.12+ (already compatible)
+- Config remains unchanged for simple SPAs
+
+### TypeScript 5.3 → 5.9
+- **No breaking changes** in our strict mode config
+- Better type inference
+- Enhanced strict mode features
+- All updates are safe
+
+## Security Status
+- React 18.3.1: ✓ No known CVEs
+- React 19.2.0: ✓ No known CVEs
+- Vite 5.4.1: ✓ No known CVEs
+- Vite 6.3+: ✓ No known CVEs
+- TypeScript 5.9: ✓ No known CVEs
+- Terser 5.31.0: ✓ No known CVEs
+
+## Vercel Deployment Readiness
+- ✓ Vite officially supported on Vercel
+- ✓ React + TypeScript recommended stack
+- ✓ Current vite.config.ts compatible
+- ✓ tsconfig.json properly configured
+- ✓ Node.js support: 18+ (Vercel provides)
+
+## Recommended Action Plan
+
+1. **Week 1 (MVP)**: Update TIER 1 packages only
+   - Run `yarn upgrade typescript @types/node @types/react @types/react-dom`
+   - Verify build: `yarn build`
+   - Deploy to Vercel
+
+2. **Week 2-4 (Post-MVP)**: Evaluate Vite upgrade
+   - Test Vite 5.4.1
+   - Profile build times
+   - Monitor user feedback
+
+3. **Month 2 (Post-MVP Validation)**: Plan major upgrades
+   - React 18 → 19 migration (if benefits justify)
+   - Vite 5 → 6 migration (for new tooling features)
+   - Systematic testing and rollback plan
+
+## Package.json Recommendation (MVP Ready)
+
+```json
+{
+  "name": "kinemotion-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "packageManager": "yarn@4.12.0",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "terser": "^5.31.0",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.1"
+  }
+}
+```
+
+## Next Steps
+1. Update package.json with TIER 1 changes
+2. Run `yarn install`
+3. Run `yarn build` and `yarn type-check`
+4. Deploy to Vercel
+5. Schedule post-MVP evaluation for TIER 2 & 3 upgrades