@memnexus-ai/cli 0.1.0

package/docs/sync-strategy.md

@@ -0,0 +1,533 @@
+# CLI-API Sync Strategy
+
+## Overview
+
+This document outlines the strategy for keeping the mx-cli in sync with mx-core-api during active development. The goal is to ensure that CLI commands always work correctly with the latest API changes while maintaining version compatibility and preventing breaking changes from affecting users.
+
+## Current Architecture
+
+```
+mx-core-api (OpenAPI spec)
+    ↓ (generates)
+@memnexus-ai/contracts (TypeScript SDK)
+    ↓ (dependency)
+@memnexus-ai/cli (CLI tool)
+```
+
+**Key Insight**: The `@memnexus-ai/contracts` package serves as the intermediary layer between the API and CLI, providing type safety and automatic synchronization.
+
+## Important Note: Code Generation
+
+**Question**: What updates the actual CLI command code when APIs change?
+
+**Answer**: See **[Code Generation Strategy](./code-generation-strategy.md)** for the complete answer.
+
+**Summary**:
+- ✅ **Types sync automatically** via `@memnexus-ai/contracts`
+- ❌ **CLI commands are manual** (for v1.0)
+- 🔧 **Future**: Hybrid scaffolding generator (post-v1.0)
+- 📊 **Solution**: Coverage detection alerts when commands are missing
+
+This document covers type safety, contract testing, and version management. The code generation strategy document covers how to implement new CLI commands efficiently.
+
+## Sync Strategy
+
+### 1. OpenAPI as Single Source of Truth
+
+**Principle**: The OpenAPI specification in mx-core-api is the canonical definition of the API contract.
+
+**Implementation**:
+- OpenAPI spec lives in: `/mx-api-gateway/contracts/openapi.yaml`
+- All API changes MUST update the OpenAPI spec first (API-first development)
+- TypeScript types are auto-generated from OpenAPI via `openapi-typescript`
+
+**Benefits**:
+- ✅ Single source of truth for API structure
+- ✅ Prevents API drift between services
+- ✅ Enables automatic SDK generation
+- ✅ Powers contract testing
+
+### 2. Automated SDK Generation
+
+**Tool**: `openapi-typescript` (already in use by contracts package)
+
+**Workflow**:
+```bash
+# In mx-api-gateway/contracts/
+npm run generate:sdk  # Generates src/generated/schema.ts from openapi.yaml
+npm run build         # Compiles TypeScript
+npm run test          # Validates generated code
+```
+
+**Integration Points**:
+- Generation happens automatically in the `@memnexus-ai/contracts` build process
+- CLI inherits types via dependency on `@memnexus-ai/contracts`
+- No manual type definitions needed in CLI
+
+### 3. Contract Testing
+
+**Purpose**: Verify that the API implementation matches the OpenAPI specification and that the CLI works with the actual API.
+
+**Recommended Tools**:
+
+#### Option A: Dredd (Lightweight, CLI-focused)
+```bash
+# Install
+npm install -g dredd
+
+# Run contract tests
+dredd openapi.yaml http://localhost:3000
+```
+
+**Pros**: Simple, fast, good for CI/CD
+**Cons**: Basic validation only
+
+#### Option B: Prism (Mock server + validation)
+```bash
+# Install
+npm install -g @stoplight/prism-cli
+
+# Run mock server during development
+prism mock openapi.yaml
+
+# Run validation proxy
+prism proxy openapi.yaml http://localhost:3000
+```
+
+**Pros**: Can mock API during CLI development, validates requests/responses
+**Cons**: More complex setup
+
+#### Option C: Postman/Newman (Already in use)
+The repo already has Postman collection sync in the contracts workflow. Can extend this for CLI testing.
+
+**Recommendation**: Use **Prism** for development (instant feedback) + **Dredd** in CI/CD (automated validation)
+
+### 4. Version Management Strategy
+
+#### Semantic Versioning (SemVer)
+
+All packages follow strict semantic versioning:
+
+**Format**: `MAJOR.MINOR.PATCH`
+
+**Rules**:
+- **MAJOR**: Breaking changes (incompatible API changes)
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+#### Version Coupling Strategy
+
+**Tight Coupling** (Recommended for v1.0):
+```json
+// mx-cli/package.json
+{
+  "dependencies": {
+    "@memnexus-ai/contracts": "1.0.4"  // Exact version pinning
+  }
+}
+```
+
+**Pros**:
+- ✅ Guaranteed compatibility
+- ✅ Predictable behavior
+- ✅ Easy to debug
+
+**Cons**:
+- ❌ Requires CLI release for every contracts update
+- ❌ Manual version bumps
+
+**Loose Coupling** (Consider for v1.1+):
+```json
+// mx-cli/package.json
+{
+  "dependencies": {
+    "@memnexus-ai/contracts": "^1.0.0"  // Allow minor/patch updates
+  }
+}
+```
+
+**Pros**:
+- ✅ Automatic compatibility with new features
+- ✅ Bug fixes flow through automatically
+
+**Cons**:
+- ❌ Risk of unexpected behavior
+- ❌ Harder to reproduce issues
+
+**Recommendation**: Start with exact pinning, move to `^` (caret) after v1.0 stabilizes.
+
+### 5. Development Workflow
+
+#### Daily Development Flow
+
+```mermaid
+graph TD
+    A[Developer changes API] --> B[Update OpenAPI spec]
+    B --> C[Run contracts build]
+    C --> D[Generate TypeScript types]
+    D --> E[Run contract tests]
+    E --> F{Tests pass?}
+    F -->|Yes| G[Commit changes]
+    F -->|No| A
+    G --> H[Publish contracts package]
+    H --> I[Update CLI dependency]
+    I --> J[Test CLI commands]
+    J --> K[Publish CLI]
+```
+
+#### Step-by-Step Process
+
+**1. API Change in mx-core-api**
+```bash
+# Developer adds new endpoint to mx-core-api
+cd /workspaces/memnexus/mx-core-api
+# Add route, controller, schema
+```
+
+**2. Update OpenAPI Spec**
+```bash
+cd /workspaces/memnexus/mx-api-gateway/contracts
+# Edit openapi.yaml to add new endpoint
+vim openapi.yaml
+```
+
+**3. Regenerate SDK**
+```bash
+# Auto-generates TypeScript types
+npm run generate:sdk
+npm run build
+npm run test
+```
+
+**4. Run Contract Tests**
+```bash
+# Validate API matches spec
+prism proxy openapi.yaml http://localhost:3000
+
+# Or use Dredd
+dredd openapi.yaml http://localhost:3000
+```
+
+**5. Publish Contracts Package** (if tests pass)
+```bash
+# Via GitHub Actions workflow_dispatch
+# Or manual:
+npm version patch
+git push origin main
+git push --tags
+```
+
+**6. Update CLI Dependency**
+```bash
+cd /workspaces/memnexus/mx-cli
+npm install @memnexus-ai/contracts@latest
+```
+
+**7. Add CLI Command** (if new endpoint)
+```bash
+# Add new command implementation
+vim src/commands/new-feature.ts
+```
+
+**8. Test CLI Against Real API**
+```bash
+# Integration testing
+npm run build
+./bin/mx new-feature list --api-url http://localhost:3000
+```
+
+**9. Publish CLI**
+```bash
+# Via GitHub Actions workflow_dispatch
+```
+
+### 6. CI/CD Integration
+
+#### Contracts Package CI/CD (Already Exists)
+```yaml
+# .github/workflows/publish-contracts.yaml
+jobs:
+  validate:
+    - Lint OpenAPI spec
+    - Generate SDK
+    - Run tests
+
+  publish:
+    - Bump version
+    - Publish to GitHub Packages
+    - Create git tag
+```
+
+#### CLI Package CI/CD (Already Created)
+```yaml
+# .github/workflows/publish.yml
+jobs:
+  validate:
+    - Lint code
+    - Build
+    - Run tests
+
+  publish:
+    - Bump version
+    - Publish to GitHub Packages
+    - Create git tag
+```
+
+#### Proposed: Add Contract Testing to Both
+
+**Add to contracts workflow**:
+```yaml
+# .github/workflows/publish-contracts.yaml
+jobs:
+  contract-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Start mx-core-api
+        run: |
+          docker-compose up -d mx-core-api
+          # Wait for API to be ready
+
+      - name: Run Dredd contract tests
+        run: |
+          npm install -g dredd
+          dredd openapi.yaml http://localhost:3000
+```
+
+**Add to CLI workflow**:
+```yaml
+# .github/workflows/publish.yml
+jobs:
+  integration-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Start mock API with Prism
+        run: |
+          npm install -g @stoplight/prism-cli
+          prism mock contracts/openapi.yaml &
+
+      - name: Run CLI integration tests
+        run: |
+          npm run test:integration
+```
+
+### 7. Automated Dependency Updates
+
+#### Option A: Dependabot (GitHub Native)
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/mx-cli"
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-name: "@memnexus-ai/contracts"
+    commit-message:
+      prefix: "chore(deps)"
+```
+
+**Pros**: Free, built into GitHub, automatic PRs
+**Cons**: Can be noisy, requires manual review
+
+#### Option B: Renovate (More Configurable)
+```json
+// renovate.json
+{
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchPackagePatterns": ["@memnexus-ai/*"],
+      "groupName": "memnexus packages",
+      "automerge": false,
+      "schedule": ["before 9am on monday"]
+    }
+  ]
+}
+```
+
+**Pros**: Highly configurable, better monorepo support
+**Cons**: Requires setup
+
+**Recommendation**: Start with **Dependabot** for simplicity, migrate to **Renovate** if more control needed.
+
+### 8. Breaking Change Management
+
+#### Detecting Breaking Changes
+
+**Automated Tools**:
+- `oasdiff` - Detects breaking changes in OpenAPI specs
+- `openapi-diff` - Alternative tool
+
+```bash
+# Install
+npm install -g oasdiff
+
+# Compare versions
+oasdiff diff openapi-old.yaml openapi-new.yaml
+```
+
+**Integration**:
+```yaml
+# .github/workflows/publish-contracts.yaml
+jobs:
+  breaking-change-check:
+    steps:
+      - name: Check for breaking changes
+        run: |
+          oasdiff breaking openapi-old.yaml openapi.yaml
+          if [ $? -eq 1 ]; then
+            echo "::error::Breaking changes detected!"
+            exit 1
+          fi
+```
+
+#### Handling Breaking Changes
+
+**Process**:
+1. **Detect**: Automated check in CI/CD
+2. **Document**: Add to CHANGELOG.md with migration guide
+3. **Version**: Bump MAJOR version in contracts package
+4. **Notify**: Create GitHub issue, notify in PR
+5. **Update CLI**: Update CLI code to handle new contract
+6. **Version CLI**: Bump MAJOR version in CLI package
+7. **Deprecation**: Keep old version available if possible
+
+**Example Migration**:
+```typescript
+// v1.x - Old API
+client.memories.list({ limit: 10 })
+
+// v2.x - Breaking change (renamed parameter)
+client.memories.list({ pageSize: 10 })
+
+// CLI handles both versions
+if (contractsVersion.startsWith('1.')) {
+  await client.memories.list({ limit: options.limit });
+} else {
+  await client.memories.list({ pageSize: options.limit });
+}
+```
+
+### 9. Monitoring and Alerts
+
+#### Version Compatibility Dashboard
+
+**Recommended**: Create a simple status page showing:
+- Current mx-core-api version
+- Current @memnexus-ai/contracts version
+- Current @memnexus-ai/cli version
+- Compatibility matrix
+
+**Implementation**:
+```bash
+# Can be a simple GitHub README badge
+![CLI Version](https://img.shields.io/github/package-json/v/memnexus-ai/memnexus?filename=mx-cli%2Fpackage.json)
+![Contracts Version](https://img.shields.io/github/package-json/v/memnexus-ai/mx-api-gateway?filename=contracts%2Fpackage.json)
+```
+
+#### Slack/Discord Notifications
+
+**On contracts package publish**:
+```yaml
+- name: Notify team
+  uses: 8398a7/action-slack@v3
+  with:
+    status: custom
+    text: |
+      📦 New @memnexus-ai/contracts v${{ steps.version.outputs.version }} published
+      🔗 Update CLI: npm install @memnexus-ai/contracts@${{ steps.version.outputs.version }}
+```
+
+### 10. Documentation Sync
+
+**Keep docs in sync automatically**:
+
+```yaml
+# .github/workflows/sync-docs.yml
+name: Sync API Documentation
+
+on:
+  workflow_run:
+    workflows: ["Publish Contracts Package"]
+    types: [completed]
+
+jobs:
+  update-cli-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate CLI docs from OpenAPI
+        run: |
+          npm install -g widdershins
+          widdershins openapi.yaml -o CLI_API_REFERENCE.md
+
+      - name: Create PR to update CLI docs
+        uses: peter-evans/create-pull-request@v5
+        with:
+          title: "docs: update API reference from contracts v${{ version }}"
+          body: "Automated update from contracts package"
+```
+
+## Recommended Tooling Setup
+
+### Phase 1: Immediate (Week 1)
+- [x] Use existing `@memnexus-ai/contracts` as intermediary
+- [ ] Pin exact version in CLI's package.json
+- [ ] Add contract tests to contracts CI/CD (Dredd)
+- [ ] Document version compatibility in CLI README
+
+### Phase 2: Short-term (Week 2-4)
+- [ ] Set up Dependabot for automated dependency updates
+- [ ] Add breaking change detection (oasdiff) to contracts workflow
+- [ ] Create version compatibility badge/dashboard
+- [ ] Add Prism mock server to CLI development workflow
+
+### Phase 3: Medium-term (Month 2)
+- [ ] Implement automated CLI integration tests against Prism
+- [ ] Set up Slack/Discord notifications for new releases
+- [ ] Create migration guides for breaking changes
+- [ ] Consider loose version coupling (^1.0.0) after stabilization
+
+### Phase 4: Long-term (Month 3+)
+- [ ] Evaluate Changesets for monorepo-wide versioning
+- [ ] Implement automated documentation generation
+- [ ] Add telemetry to track CLI version distribution
+- [ ] Consider API versioning strategy (v1, v2, etc.)
+
+## Key Takeaways
+
+1. **OpenAPI First**: Always update the spec before changing the API
+2. **Contracts as Bridge**: Let `@memnexus-ai/contracts` handle API changes
+3. **Exact Pinning**: Start with exact versions for stability
+4. **Automate Testing**: Contract tests catch breaking changes early
+5. **Clear Versioning**: Follow SemVer strictly
+6. **Fast Feedback**: Use Prism during development
+7. **Monitor Compatibility**: Keep version dashboard updated
+8. **Document Everything**: Migration guides for breaking changes
+
+## Success Metrics
+
+**Short-term**:
+- ✅ Zero "API not found" errors in CLI
+- ✅ All CI/CD pipelines passing
+- ✅ <1 day lag between API changes and CLI updates
+
+**Long-term**:
+- ✅ Zero breaking changes without MAJOR version bump
+- ✅ <1 hour from API change to contracts publish
+- ✅ 100% OpenAPI spec coverage
+- ✅ Automated contract test success rate >95%
+
+## References
+
+- **Stripe's Approach**: https://docs.stripe.com/libraries/set-version
+- **Contract Testing with OpenAPI**: https://www.speakeasy.com/blog/contract-testing-with-openapi
+- **Monorepo Versioning**: https://turbo.build/repo/docs/handbook/publishing-packages/versioning-and-publishing
+- **OpenAPI Tools**: https://openapi.tools/
+
+---
+
+**Document Version**: 1.0
+**Last Updated**: 2025-11-13
+**Author**: Claude Code
+**Status**: Proposed Strategy

package/jest.config.js

@@ -0,0 +1,30 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/index.ts', '!src/**/*.d.ts'],
+  coverageThreshold: {
+    global: {
+      branches: 70,
+      functions: 70,
+      lines: 70,
+      statements: 70,
+    },
+  },
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+    '^chalk$': '<rootDir>/tests/__mocks__/chalk.ts',
+    '^configstore$': '<rootDir>/tests/__mocks__/configstore.ts',
+    '^cli-table3$': '<rootDir>/tests/__mocks__/cli-table3.ts',
+  },
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        useESM: false,
+        isolatedModules: true,
+      },
+    ],
+  },
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@memnexus-ai/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for MemNexus Core API",
+  "main": "dist/index.js",
+  "bin": {
+    "mx": "./bin/mx.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "format": "prettier --write 'src/**/*.ts'",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "memnexus",
+    "cli",
+    "api",
+    "memory",
+    "ai"
+  ],
+  "author": "MemNexus Team",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/memnexus-ai/mx-cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@memnexus-ai/mx-typescript-sdk": "^1.0.10",
+    "axios": "^1.13.2",
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "configstore": "^7.0.0",
+    "dotenv": "^16.3.1",
+    "inquirer": "^9.2.12",
+    "js-yaml": "^4.1.0",
+    "ora": "^7.0.1"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/jest": "^29.5.8",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.13.2",
+    "@typescript-eslint/parser": "^6.13.2",
+    "eslint": "^8.55.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.0.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.0",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/scripts/install-deps.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+# Install dependencies with GitHub Packages authentication
+# This script uses gh CLI to authenticate with GitHub Packages
+
+set -e
+
+echo "🔐 Setting up GitHub Packages authentication..."
+
+# Check if gh CLI is available
+if ! command -v gh &> /dev/null; then
+    echo "❌ Error: gh CLI is not installed"
+    echo "Please install it from: https://cli.github.com/"
+    exit 1
+fi
+
+# Check if gh is authenticated
+if ! gh auth status &> /dev/null; then
+    echo "❌ Error: gh CLI is not authenticated"
+    echo "Please run: gh auth login"
+    exit 1
+fi
+
+# Get the GitHub token
+GITHUB_TOKEN=$(gh auth token)
+
+if [ -z "$GITHUB_TOKEN" ]; then
+    echo "❌ Error: Could not get GitHub token"
+    exit 1
+fi
+
+echo "✅ GitHub authentication configured"
+echo "📦 Installing dependencies..."
+
+# Install with the token
+GITHUB_TOKEN=$GITHUB_TOKEN npm install
+
+echo "✅ Dependencies installed successfully!"
+