@memnexus-ai/cli 0.1.0

package/PLATFORM_TESTING.md

@@ -0,0 +1,243 @@
+# Platform Testing Report
+
+This document tracks testing results across different platforms and Node.js versions.
+
+## Supported Platforms
+
+The mx-cli is designed to work on:
+- **Linux** (Ubuntu, Debian, Fedora, etc.)
+- **macOS** (10.15+)
+- **Windows** (10/11 with PowerShell or CMD)
+
+## Supported Node.js Versions
+
+- **Node.js 18.x** (LTS)
+- **Node.js 20.x** (LTS) - Recommended
+- **Node.js 22.x** (Current)
+
+## Testing Matrix
+
+### Linux
+
+| Distribution | Node Version | Status | Test Results | Notes |
+|--------------|--------------|--------|--------------|-------|
+| Ubuntu 22.04 (WSL2) | 24.11.0 | ✅ Passed | 128/128 tests passed | All features working |
+| Ubuntu 20.04 | 20.x | ⏳ Pending | - | - |
+| Debian 11 | 18.x | ⏳ Pending | - | - |
+
+**Tested Features:**
+- ✅ Installation via `npm link`
+- ✅ All 128 tests passing
+- ✅ Interactive prompts with inquirer
+- ✅ Progress spinners with ora
+- ✅ Colored output with chalk
+- ✅ Table formatting with cli-table3
+- ✅ JSON/YAML output formats
+- ✅ File system operations (config storage)
+- ✅ Environment variable handling
+
+**Known Issues:**
+- None
+
+### macOS
+
+| Version | Node Version | Status | Test Results | Notes |
+|---------|--------------|--------|--------------|-------|
+| macOS 14 (Sonoma) | 20.x | ⏳ Pending | - | - |
+| macOS 13 (Ventura) | 20.x | ⏳ Pending | - | - |
+| macOS 12 (Monterey) | 18.x | ⏳ Pending | - | - |
+
+**Expected Compatibility:**
+- All features should work identically to Linux
+- Terminal colors and spinners supported in Terminal.app and iTerm2
+- Config file location: `~/.mx-cli/config.json`
+
+**Potential Issues:**
+- None anticipated (POSIX-compliant like Linux)
+
+### Windows
+
+| Version | Node Version | Status | Test Results | Notes |
+|---------|--------------|--------|--------------|-------|
+| Windows 11 | 20.x | ⏳ Pending | - | PowerShell |
+| Windows 11 | 20.x | ⏳ Pending | - | CMD |
+| Windows 10 | 20.x | ⏳ Pending | - | PowerShell |
+
+**Expected Compatibility:**
+- All features should work with minor differences
+- Terminal colors supported in Windows Terminal and PowerShell
+- Config file location: `%USERPROFILE%\.mx-cli\config.json`
+
+**Potential Issues:**
+- Path separators (handled by Node.js `path` module)
+- Line endings (CRLF vs LF) - should be transparent
+- Terminal color support in older CMD.exe (may need Windows Terminal)
+
+## Testing Checklist
+
+When testing on a new platform, verify the following:
+
+### Installation
+- [ ] `npm install -g @memnexus-ai/cli` succeeds
+- [ ] `mx --version` displays version
+- [ ] `mx --help` displays help text
+
+### Authentication
+- [ ] `mx auth login --interactive` prompts for API key
+- [ ] Password masking works (API key hidden during input)
+- [ ] `mx auth status` shows configuration
+- [ ] Config file created at correct location
+
+### Memory Operations
+- [ ] `mx memories create --interactive` prompts work
+- [ ] `mx memories list` displays table correctly
+- [ ] `mx memories list --format json` outputs valid JSON
+- [ ] `mx memories list --format yaml` outputs valid YAML
+- [ ] Spinners display during operations
+- [ ] Colors display correctly
+
+### Fact Operations
+- [ ] `mx facts create --interactive` prompts work
+- [ ] `mx facts list` displays correctly
+- [ ] Confirmation prompts work for delete
+
+### Advanced Commands
+- [ ] `mx topics list` works
+- [ ] `mx graphrag query --query "test"` works
+- [ ] `mx system health` works
+
+### Error Handling
+- [ ] Invalid API key shows helpful error message
+- [ ] Network errors show troubleshooting steps
+- [ ] Validation errors show clear messages
+
+### Output Formats
+- [ ] Table format displays correctly in terminal
+- [ ] JSON format is valid and parseable
+- [ ] YAML format is valid and parseable
+- [ ] Spinners disabled in JSON mode
+
+### Interactive Features
+- [ ] Arrow keys work in prompts
+- [ ] Tab completion works (if applicable)
+- [ ] Ctrl+C cancels operations gracefully
+
+## Test Execution
+
+### Running Tests
+
+```bash
+# Install dependencies
+npm install
+
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- tests/commands/memories.test.ts
+```
+
+### Manual Testing
+
+```bash
+# Build and link
+npm run build
+npm link
+
+# Test authentication
+mx auth login --interactive
+mx auth status
+
+# Test memory creation
+mx memories create --interactive
+
+# Test different output formats
+mx memories list --format table
+mx memories list --format json
+mx memories list --format yaml
+
+# Test error handling
+mx memories list  # Without auth (should show helpful error)
+```
+
+## Platform-Specific Notes
+
+### Linux
+- **Terminal Emulators**: Tested with standard terminal, should work with all modern terminals
+- **Shell**: Works with bash, zsh, fish
+- **Permissions**: No special permissions required
+- **Dependencies**: All dependencies are pure JavaScript (no native modules)
+
+### macOS
+- **Terminal Emulators**: Should work with Terminal.app, iTerm2, Hyper, etc.
+- **Shell**: Works with bash, zsh (default on macOS 10.15+)
+- **Permissions**: No special permissions required
+- **M1/M2 Chips**: No native dependencies, should work on both Intel and Apple Silicon
+
+### Windows
+- **Terminal Emulators**: 
+  - ✅ Windows Terminal (recommended)
+  - ✅ PowerShell 7+
+  - ⚠️ PowerShell 5.1 (colors may be limited)
+  - ⚠️ CMD.exe (colors may be limited)
+- **Shell**: PowerShell recommended, CMD supported
+- **Permissions**: No admin rights required
+- **Path**: Ensure npm global bin directory is in PATH
+
+## CI/CD Testing
+
+The GitHub Actions workflow tests on:
+- **ubuntu-latest** (Linux)
+- Node.js 20.x
+
+Future enhancements could add:
+- macOS runner: `macos-latest`
+- Windows runner: `windows-latest`
+- Multiple Node.js versions: 18.x, 20.x, 22.x
+
+## Reporting Issues
+
+If you encounter platform-specific issues:
+
+1. **Check Node.js version**: `node --version` (must be 18+)
+2. **Check npm version**: `npm --version`
+3. **Check terminal**: Try Windows Terminal on Windows
+4. **Run tests**: `npm test` to verify installation
+5. **Report issue**: Include platform, Node version, terminal, and error message
+
+## Test Results Summary
+
+| Platform | Status | Tests Passed | Last Tested | Tester |
+|----------|--------|--------------|-------------|--------|
+| Linux (Ubuntu 22.04 WSL2) | ✅ Passed | 128/128 | 2024-11-14 | Automated |
+| macOS | ⏳ Pending | - | - | - |
+| Windows | ⏳ Pending | - | - |
+
+## Conclusion
+
+**Current Status:**
+- ✅ Linux: Fully tested and working (128/128 tests passed)
+- ⏳ macOS: Expected to work (POSIX-compliant, no platform-specific code)
+- ⏳ Windows: Expected to work (no native dependencies, path handling via Node.js)
+
+**Confidence Level:**
+- **High** for Linux (tested)
+- **High** for macOS (similar to Linux, no platform-specific code)
+- **Medium-High** for Windows (no native deps, but terminal differences possible)
+
+**Recommendation:**
+The CLI is ready for release with Linux support confirmed. macOS and Windows testing should be performed by early adopters or in CI/CD before v1.0.0 final release.
+
+**Next Steps:**
+1. Add macOS and Windows runners to GitHub Actions
+2. Test on real macOS and Windows machines
+3. Document any platform-specific issues discovered
+4. Update this document with results
+
+---
+
+*Last updated: 2024-11-14*
+