@memnexus-ai/cli 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,277 @@
+name: Publish CLI Package
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+      - '.github/workflows/publish.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'src/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'tsconfig.json'
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: 'Release type (patch/minor/major)'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      publish_github:
+        description: 'Publish to GitHub Packages'
+        required: true
+        type: boolean
+        default: true
+      publish_npm:
+        description: 'Publish to npm registry'
+        required: true
+        type: boolean
+        default: true
+
+env:
+  NODE_VERSION: '20.x'
+
+jobs:
+  validate:
+    name: Validate Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@memnexus-ai'
+
+      - name: Install dependencies
+        run: |
+          set -e
+          npm install || {
+            echo "npm install failed, dumping npm debug logs..."
+            find ~/.npm/_logs -maxdepth 1 -type f -name '*-debug-0.log' -print -exec cat {} \;
+            exit 1
+          }
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
+
+      - name: Lint code
+        run: npm run lint
+
+      - name: Build package
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Check package contents
+        run: npm pack --dry-run
+
+  publish:
+    name: Publish to GitHub Packages
+    runs-on: ubuntu-latest
+    needs: [validate]
+    permissions:
+      contents: write
+      packages: write
+    if: |
+      (github.ref == 'refs/heads/main' && github.event_name == 'push') ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.publish_github == 'true')
+    environment:
+      name: github-packages
+      url: https://github.com/memnexus-ai/memnexus/pkgs/npm/cli
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@memnexus-ai'
+
+      - name: Configure git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Install dependencies
+        run: npm install
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
+
+      - name: Build package
+        run: npm run build
+
+      - name: Bump version
+        if: github.event_name == 'workflow_dispatch'
+        run: npm version ${{ github.event.inputs.release_type }} --no-git-tag-version
+
+      - name: Get package version
+        id: package-version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Check if version exists on GitHub Packages
+        id: check-version
+        run: |
+          npm config set @memnexus-ai:registry https://npm.pkg.github.com
+          if npm view @memnexus-ai/cli@${{ steps.package-version.outputs.version }} version 2>/dev/null; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
+
+      - name: Publish to GitHub Packages
+        if: steps.check-version.outputs.exists == 'false'
+        run: npm publish --registry=https://npm.pkg.github.com
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
+
+      - name: Create git tag
+        if: steps.check-version.outputs.exists == 'false'
+        run: |
+          git add package.json
+          git commit -m "chore(cli): release v${{ steps.package-version.outputs.version }}"
+          git tag -a "cli-v${{ steps.package-version.outputs.version }}" -m "Release @memnexus-ai/cli v${{ steps.package-version.outputs.version }}"
+          git push origin main
+          git push origin "cli-v${{ steps.package-version.outputs.version }}"
+
+      - name: Create GitHub Release
+        if: steps.check-version.outputs.exists == 'false'
+        uses: softprops/action-gh-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: cli-v${{ steps.package-version.outputs.version }}
+          name: '@memnexus-ai/cli v${{ steps.package-version.outputs.version }}'
+          body: |
+            ## @memnexus-ai/cli v${{ steps.package-version.outputs.version }}
+
+            Published to GitHub Packages: https://github.com/memnexus-ai/memnexus/pkgs/npm/cli
+
+            ### Installation
+
+            ```bash
+            # Configure npm to use GitHub Packages for @memnexus-ai scope
+            npm config set @memnexus-ai:registry https://npm.pkg.github.com
+
+            # Authenticate with GitHub (requires personal access token with read:packages scope)
+            npm login --scope=@memnexus-ai --registry=https://npm.pkg.github.com
+
+            # Install globally
+            npm install -g @memnexus-ai/cli@${{ steps.package-version.outputs.version }}
+
+            # Verify installation
+            mx --version
+            ```
+
+            ### Quick Start
+
+            ```bash
+            # Configure authentication
+            mx auth login --interactive
+
+            # Verify connection
+            mx auth status
+
+            # Create your first memory
+            mx memories create --interactive
+            ```
+
+            ### Changes
+            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
+
+            ### Documentation
+            - [README](https://github.com/${{ github.repository }}/blob/main/README.md)
+            - [Usage Guide](https://github.com/${{ github.repository }}/blob/main/USAGE.md)
+          draft: false
+          prerelease: false
+
+      - name: Version already published
+        if: steps.check-version.outputs.exists == 'true'
+        run: |
+          echo "::warning::Version ${{ steps.package-version.outputs.version }} already exists on GitHub Packages. Skipping publish."
+
+  publish-npm:
+    name: Publish to npm Registry
+    runs-on: ubuntu-latest
+    needs: [validate]
+    if: |
+      (github.ref == 'refs/heads/main' && github.event_name == 'push') ||
+      (github.event_name == 'workflow_dispatch' && github.event.inputs.publish_npm == 'true')
+    environment:
+      name: npm-registry
+      url: https://www.npmjs.com/package/@memnexus-ai/cli
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js for npm
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@memnexus-ai'
+
+      - name: Configure git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Install dependencies
+        run: npm install
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_READ_TOKEN }}
+
+      - name: Build package
+        run: npm run build
+
+      - name: Bump version
+        if: github.event_name == 'workflow_dispatch'
+        run: npm version ${{ github.event.inputs.release_type }} --no-git-tag-version
+
+      - name: Get package version
+        id: package-version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Check if version exists on npm
+        id: check-version
+        run: |
+          if npm view @memnexus-ai/cli@${{ steps.package-version.outputs.version }} version 2>/dev/null; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to npm
+        if: steps.check-version.outputs.exists == 'false'
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Version already published
+        if: steps.check-version.outputs.exists == 'true'
+        run: |
+          echo "::warning::Version ${{ steps.package-version.outputs.version }} already exists on npm. Skipping publish."

package/.github/workflows/test-app-token.yml

@@ -0,0 +1,54 @@
+name: Test GitHub App Token
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test-token:
+    name: Test GitHub App Token
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate GitHub App Token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.MX_BOTT_APP_ID }}
+          private-key: ${{ secrets.MX_BOTT_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: mx-cli,mx-api-gateway
+
+      - name: Test token - Get user info
+        run: |
+          echo "Testing GitHub App token..."
+          curl -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+               -H "Accept: application/vnd.github+json" \
+               https://api.github.com/user | jq .
+
+      - name: Test token - List packages
+        run: |
+          echo "Attempting to list organization packages..."
+          curl -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+               -H "Accept: application/vnd.github+json" \
+               https://api.github.com/orgs/memnexus-ai/packages?package_type=npm | jq .
+
+      - name: Test token - Get specific package
+        run: |
+          echo "Attempting to get mx-typescript-sdk package..."
+          curl -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+               -H "Accept: application/vnd.github+json" \
+               https://api.github.com/orgs/memnexus-ai/packages/npm/mx-typescript-sdk | jq .
+
+      - name: Test token - Check app installation
+        run: |
+          echo "Checking app installation permissions..."
+          curl -H "Authorization: Bearer ${{ steps.app-token.outputs.token }}" \
+               -H "Accept: application/vnd.github+json" \
+               https://api.github.com/installation/repositories | jq .
+
+      - name: Test npm authentication
+        run: |
+          echo "Testing npm authentication with the token..."
+          echo "@memnexus-ai:registry=https://npm.pkg.github.com" > .npmrc
+          echo "//npm.pkg.github.com/:_authToken=${{ steps.app-token.outputs.token }}" >> .npmrc
+          npm view @memnexus-ai/mx-typescript-sdk --registry=https://npm.pkg.github.com || echo "Failed to view package"
+

package/.npmrc.backup

@@ -0,0 +1,3 @@
+@memnexus-ai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
+npm.pkg.github.com/:_authToken=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

package/.npmrc.example

@@ -0,0 +1,6 @@
+# NPM Configuration for MemNexus CLI
+# Copy this file to .npmrc and set your GITHUB_TOKEN environment variable
+
+@memnexus-ai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+

package/.prettierignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+coverage
+*.md

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to the mx-cli project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive README with GitHub Packages installation instructions
+- Quick Start guide with 5-minute setup
+- Common workflows documentation (daily memory capture, knowledge graph building, batch operations)
+- Complete USAGE.md with detailed command reference for all 12 command categories
+- Interactive mode for artifacts create command
+- Comprehensive input validation library (`src/lib/validators.ts`)
+- Progress spinners for all memory operations
+- Conditional spinner helper that respects output format
+- Enhanced error messages with actionable troubleshooting steps
+- Platform testing documentation (PLATFORM_TESTING.md)
+- Release process documentation (RELEASE.md)
+- GitHub Actions publishing workflow with automated testing and release creation
+
+### Changed
+- Updated features list to reflect 128 tests and new capabilities
+- Enhanced error handling with "💡 To fix this" sections for all HTTP error codes
+- Improved interactive mode documentation with password masking details
+- Updated prerequisites to Node.js 18+
+- Spinners automatically disabled for JSON output format (prevents interference with piping)
+
+### Fixed
+- Password masking now works correctly in auth login interactive mode
+- Validation errors now show helpful messages with examples
+
+## [0.1.0] - 2024-11-14
+
+### Added
+- Initial release of mx-cli
+- Authentication commands (login, logout, status)
+- Configuration commands (get, set, list)
+- Memory management (CRUD operations, search)
+- Conversation tracking (list, get, timeline, search, by-topic)
+- Fact management (CRUD operations, search)
+- Topic commands (list, get, merge, discover-related, similarity, find-similar, cluster, detect-communities)
+- Community commands (list, get, merge)
+- Pattern commands (compile, feedback, set-state)
+- GraphRAG commands (query, explain, query-communities)
+- Artifact commands (CRUD operations)
+- API key commands (list, create, delete)
+- System commands (health, status, feature-flags)
+- Multiple output formats (JSON, table, YAML)
+- Interactive mode for memory and fact creation
+- Confirmation prompts for destructive operations
+- Pagination support for list operations
+- Environment variable configuration
+- Config file storage (~/.mx-cli/config.json)
+- Comprehensive test suite (128 tests, >80% coverage)
+- TypeScript SDK integration (@memnexus-ai/mx-typescript-sdk)
+- CLI framework with Commander.js
+- Colored terminal output with chalk
+- Table formatting with cli-table3
+- Progress indicators with ora
+- Interactive prompts with inquirer
+
+### Security
+- API key storage in config file with restricted permissions
+- Password masking for sensitive inputs
+- No API keys logged or displayed in output
+
+## Version History
+
+### Version Numbering
+
+This project follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version (X.0.0): Incompatible API changes
+- **MINOR** version (0.X.0): New functionality in a backward-compatible manner
+- **PATCH** version (0.0.X): Backward-compatible bug fixes
+
+### Release Types
+
+- **Major Release (1.0.0, 2.0.0, etc.)**
+  - Breaking changes to command syntax or behavior
+  - Removal of deprecated features
+  - Major architectural changes
+  - Requires user action to upgrade
+
+- **Minor Release (0.1.0, 0.2.0, etc.)**
+  - New commands or features
+  - New options for existing commands
+  - Performance improvements
+  - Non-breaking enhancements
+  - Backward-compatible changes
+
+- **Patch Release (0.1.1, 0.1.2, etc.)**
+  - Bug fixes
+  - Documentation updates
+  - Security patches
+  - Minor improvements
+  - No new features
+
+### Deprecation Policy
+
+When features are deprecated:
+1. Marked as deprecated in documentation
+2. Warning message shown when used
+3. Maintained for at least one minor version
+4. Removed in next major version
+
+Example:
+- v0.5.0: Feature X deprecated (warning shown)
+- v0.6.0: Feature X still works (warning shown)
+- v1.0.0: Feature X removed
+
+## Migration Guides
+
+### Upgrading to v1.0.0 (Future)
+
+When v1.0.0 is released, this section will contain:
+- Breaking changes from v0.x
+- Migration steps
+- Command syntax changes
+- Configuration changes
+
+## Links
+
+- [GitHub Repository](https://github.com/memnexus-ai/memnexus/tree/main/mx-cli)
+- [GitHub Packages](https://github.com/memnexus-ai/memnexus/pkgs/npm/cli)
+- [Issue Tracker](https://github.com/memnexus-ai/memnexus/issues)
+- [README](README.md)
+- [Usage Guide](USAGE.md)
+- [Release Process](RELEASE.md)
+
+---
+
+[Unreleased]: https://github.com/memnexus-ai/memnexus/compare/cli-v0.1.0...HEAD
+[0.1.0]: https://github.com/memnexus-ai/memnexus/releases/tag/cli-v0.1.0
+