embark-cli 1.1.7

package/.claude/CLAUDE.md

@@ -0,0 +1,33 @@
+# Tools
+
+## Semantic Code Search (EmbArk)
+
+You have access to the `mcp__embark-mcp__semantic_code_search` tool for searching the codebase semantically.
+This tool can search for code snippets related in meaning to the search query and search objective.
+
+### When to use semantic search:
+- Understanding unfamiliar codebases or locating specific functionality.
+- Finding implementations, definitions, or usage patterns.
+- Identifying code related to specific features or concepts.
+- Before making changes to understand the context and impact.
+
+### Usage rules:
+- The tool searches by MEANING, not just exact string matches.
+- The tool takes the `text` parameter that should combine both what you're looking for and why:
+    - Construct the `text` parameter by combining: what to find + search objective.
+    - Make search objective in the query specific and self-contained, describe what you are trying to achieve by search and how the search results should help.
+    - Objective should always provide an additional context of the query, describing the higher-level task.
+- The tool optionally takes the `pathFilter` parameter to narrow the search to a specific directory or file:
+    - Using `pathFilter` dramatically improves search relevance and precision.
+    - Semantic search without path constraints might return irrelevant results from unrelated modules.
+    - If not provided, the whole project is searched.
+
+### Examples:
+- `"text"="Refactor `MyFunction` to handle async operations", "pathFilter"="path/to/module"`: Searches `MyFunction` within the specified directory for refactoring.
+- `"text"="Find `authorization` to add OAuth2 support to existing auth system", "pathFilter"="path/to/file/example.kt"`: Searches `authorization` inside the specified file to add OAuth2 support.
+- `"text"="Find `class User` to add email validation to user model"`: Finds the definition of class `User` to add email validation.
+- `"text"="Find `class User` to add email validation to user model", "pathFilter"="path/to/file/example.kt"`: Finds the definition of class `User` inside the specified file to add email validation.
+- `"text"="Locate query with retries to improve error handling in database queries"`: Searches for anything containing `query*with*retries` in directory names, filenames, symbol names and semantic matches by meaning. It also returns a code line with the exact phrase `query with retries`.
+- `"text"="Find `fun getConfig` to change default headers in authentication", "pathFilter"="path/to/module/submodule"`: Searches for `fun getConfig` within the specified directory `path/to/module/submodule` to change the default headers in authentication.
+
+Use this tool proactively when you need to understand code structure or locate relevant implementations.

package/.claude/settings.local.json

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)",
+      "Bash(npm install)",
+      "Bash(npm run build:*)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "Bash(find:*)",
+      "Bash(ls:*)",
+      "Bash(claude mcp add:*)",
+      "Bash(claude mcp:*)",
+      "WebFetch(domain:modelcontextprotocol.io)",
+      "WebFetch(domain:github.com)",
+      "Bash(npm install:*)",
+      "mcp__embark-remote-mcp__semantic_code_search",
+      "Bash(chmod:*)",
+      "Bash(node test-roots.mjs)",
+      "Bash(node:*)",
+      "Read(//Users/dmitry.loktev/.embark/**)",
+      "Bash(cat:*)",
+      "Bash(ENABLE_REMOTE_LOGS=true node:*)",
+      "Bash(ENABLE_LOCAL_LOGS=true node:*)",
+      "Bash(ENABLE_LOCAL_LOGS=1 node dist/index.js:*)",
+      "mcp__jetbrains-app__semantic_code_search"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "embark-remote-mcp"
+  ]
+}

package/.github/WORKFLOWS.md

@@ -0,0 +1,147 @@
+# GitHub Actions Workflows
+
+This repository uses GitHub Actions for continuous integration and deployment.
+
+## Workflows
+
+### 1. CI Workflow (`.github/workflows/ci.yml`)
+
+**Triggers:**
+- Push to `main` or `develop` branches
+- Pull requests to `main` or `develop` branches
+
+**Jobs:**
+- Runs on Node.js versions 18, 20, and 22
+- Installs dependencies
+- Builds the project
+- Runs tests (if available)
+- Verifies build artifacts
+- Validates package can be packed
+
+### 2. Publish Workflow (`.github/workflows/publish.yml`)
+
+**Triggers:**
+- Manual trigger via GitHub UI (workflow_dispatch)
+- Requires selecting version bump type: patch, minor, or major
+
+**Jobs:**
+- Checks out code
+- Configures Git for automated commits
+- Sets up Node.js 20
+- Installs dependencies
+- Builds the project
+- Runs tests (if available)
+- **Automatically bumps version** in package.json based on input
+- Checks if version is already published to NPM
+- Commits the version bump back to the repository
+- Creates and pushes a git tag (e.g., v1.0.17)
+- Publishes to NPM with provenance (if version is new)
+
+## Setting Up NPM Token
+
+To enable automatic publishing to NPM, you need to configure the `NPM_TOKEN` secret:
+
+### Step 1: Generate an NPM Access Token
+
+1. Log in to [npmjs.com](https://www.npmjs.com/)
+2. Click on your profile picture → "Access Tokens"
+3. Click "Generate New Token" → "Classic Token"
+4. Select "Automation" type (for CI/CD)
+5. Copy the generated token
+
+### Step 2: Add Token to GitHub Secrets
+
+1. Go to your GitHub repository
+2. Navigate to **Settings** → **Secrets and variables** → **Actions**
+3. Click **"New repository secret"**
+4. Name: `NPM_TOKEN`
+5. Value: Paste your NPM token
+6. Click **"Add secret"**
+
+## Publishing a New Version
+
+The publish workflow is fully automated and handles version bumping for you:
+
+### Steps to Publish:
+
+1. Go to the **Actions** tab in your GitHub repository
+2. Select **"Publish to NPM"** workflow from the left sidebar
+3. Click **"Run workflow"** button (top right)
+4. Choose the version bump type:
+   - **patch**: Bug fixes and minor updates (1.0.16 → 1.0.17)
+   - **minor**: New features (1.0.16 → 1.1.0)
+   - **major**: Breaking changes (1.0.16 → 2.0.0)
+5. Click **"Run workflow"** to start
+
+### What Happens Automatically:
+
+1. ✅ Runs build and tests
+2. ✅ Bumps version in `package.json` and `package-lock.json`
+3. ✅ Checks if version already exists on NPM
+4. ✅ Commits the version bump with message: `chore: bump version to vX.Y.Z`
+5. ✅ Creates and pushes a git tag (e.g., `v1.0.17`)
+6. ✅ Publishes to NPM with provenance
+
+**Note**: You don't need to manually update `package.json` or create git tags anymore - the workflow handles everything!
+
+## Workflow Features
+
+### Build & Test
+- Uses `npm ci` for reproducible installs
+- Runs `npm run build` to compile TypeScript
+- Executes `npm test` if test script exists
+
+### Version Check
+- Automatically checks if the version in `package.json` is already published
+- Skips publishing if version already exists on NPM
+- Prevents accidental republishing of the same version
+
+### NPM Provenance
+- Publishes with `--provenance` flag for supply chain security (public repos only)
+- Links published package to the specific commit and workflow
+- Provides transparency about package origins
+- **Note**: Provenance is automatically disabled for internal/private repositories as it's only supported for public repos
+
+### Public Access
+- Publishes with `--access public` for scoped or public packages
+- Remove this flag if publishing a private package
+
+## Troubleshooting
+
+### "Version already published" Error
+- The workflow automatically checks NPM before publishing
+- If you see this error, the version already exists
+- Solution: Run the workflow again with a higher bump type (e.g., use `minor` instead of `patch`)
+
+### NPM Token Invalid
+- Verify token is an "Automation" type token
+- Check token hasn't expired
+- Regenerate token and update GitHub secret
+
+### Build Failures
+- Check Node.js version compatibility
+- Ensure all dependencies are properly declared
+- Review build logs in Actions tab
+
+### Provenance Error (E422)
+- If you see "Unsupported GitHub Actions source repository visibility: internal"
+- This is expected - provenance is only supported for public repositories
+- The workflow automatically handles this by publishing without provenance for internal/private repos
+- No action needed on your part
+
+### Push Rejected / Protected Branch
+- Ensure the workflow has `contents: write` permission (already configured)
+- If branch protection is enabled on `main`, you may need to:
+  - Allow GitHub Actions to bypass branch protection rules
+  - Or temporarily disable "Require pull request reviews before merging" for bots
+
+### Workflow Not Visible
+- Ensure the workflow file is committed to the `main` branch
+- Check `.github/workflows/publish.yml` exists in the repository
+
+## Security Notes
+
+- Never commit NPM tokens to the repository
+- Use GitHub Secrets for sensitive credentials
+- Rotate tokens periodically
+- Use Automation tokens (not classic tokens with full access)

package/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run tests (if test script exists)
+        run: npm test --if-present
+
+      - name: Check dist directory
+        run: |
+          if [ ! -d "dist" ]; then
+            echo "Error: dist directory not created"
+            exit 1
+          fi
+          echo "Build artifacts created successfully"
+
+      - name: Verify package can be packed
+        run: npm pack --dry-run

package/.github/workflows/publish.yml

@@ -0,0 +1,109 @@
+name: Publish to NPM
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: patch
+
+jobs:
+  build-test-publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # Required to push commits and tags
+      id-token: write  # Required for provenance
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper versioning
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      # Ensure npm 11.5.1 or later is installed
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run tests (if test script exists)
+        run: npm test --if-present
+
+      - name: Bump version
+        id: version
+        run: |
+          # Bump version in package.json
+          NEW_VERSION=$(npm version ${{ inputs.version_bump }} --no-git-tag-version)
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "New version: $NEW_VERSION"
+
+      - name: Check if version is already published
+        id: check-version
+        run: |
+          PACKAGE_NAME=$(node -p "require('./package.json').name")
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+
+          if npm view "$PACKAGE_NAME@$PACKAGE_VERSION" version 2>/dev/null; then
+            echo "Version $PACKAGE_VERSION is already published"
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+          else
+            echo "Version $PACKAGE_VERSION is not published yet"
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit version bump
+        if: steps.check-version.outputs.should_publish == 'true'
+        run: |
+          git add package.json package-lock.json
+          git commit -m "chore: bump version to ${{ steps.version.outputs.new_version }}"
+          git tag ${{ steps.version.outputs.new_version }}
+
+      - name: Push changes
+        if: steps.check-version.outputs.should_publish == 'true'
+        run: |
+          git push origin main
+          git push origin ${{ steps.version.outputs.new_version }}
+
+      - name: Publish to NPM (with provenance for public repos)
+        if: steps.check-version.outputs.should_publish == 'true' && github.event.repository.visibility == 'public'
+        run: npm publish --provenance --access public
+
+      - name: Publish to NPM (without provenance for private/internal repos)
+        if: steps.check-version.outputs.should_publish == 'true' && github.event.repository.visibility != 'public'
+        run: npm publish --access public
+
+      - name: Skip publishing
+        if: steps.check-version.outputs.should_publish == 'false'
+        run: |
+          echo "Skipping publish - version already exists on NPM"
+          echo "Please increment the version manually or choose a different bump type"
+          exit 1

package/.idea/embark-remote-mcp.iml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="JAVA_MODULE" version="4">
+  <component name="NewModuleRootManager" inherit-compiler-output="true">
+    <exclude-output />
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

package/.idea/encodings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding" addBOMForNewFiles="with BOM under Windows, with no BOM otherwise" />
+</project>

package/.idea/indexLayout.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="UserContentModel">
+    <attachedFolders />
+    <explicitIncludes />
+    <explicitExcludes />
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "embark-remote-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "dist/index.js"
+      ],
+      "env": {
+        "ENABLE_LOCAL_LOGS": true
+      }
+    }
+  }
+}

package/GIT_DISCOVERY.md

@@ -0,0 +1,231 @@
+# Git Repository Discovery from Roots
+
+This document explains how the Embark MCP server automatically discovers Git repositories from client-provided roots.
+
+## How It Works
+
+### 1. Server Requests Roots from Client
+
+When the server starts and connects to a client (like Claude Code), it requests the list of roots:
+
+```typescript
+const response = await server.listRoots();
+```
+
+### 2. Client Provides Directories
+
+The client responds with file:// URIs representing directories it wants the server to have access to:
+
+```json
+{
+  "roots": [
+    {
+      "uri": "file:///Users/dmitry.loktev/Projects/my-project",
+      "name": "My Project"
+    }
+  ]
+}
+```
+
+### 3. Server Discovers Git Remotes
+
+For each root directory, the server:
+1. Converts the file:// URI to a filesystem path
+2. Checks if it's a Git repository
+3. Runs `git remote get-url origin` to discover the remote URL
+4. Caches the discovered repository URLs
+
+### 4. Automatic Repository Selection
+
+When you use the search tools without specifying a `repositoryGitRemoteUrl`, the server automatically uses the discovered repository.
+
+## Benefits
+
+### No Manual Configuration Required
+
+Users don't need to set `REPOSITORY_GIT_REMOTE_URL` environment variable. The server automatically discovers repositories from the directories Claude Code is working with.
+
+### Multi-Repository Support
+
+If the client provides multiple roots with different Git repositories, the server discovers all of them (currently uses the first one for searches).
+
+### Fallback to Environment Variable
+
+If roots discovery fails or no roots are provided, the server falls back to `REPOSITORY_GIT_REMOTE_URL` if it's set.
+
+## Implementation Details
+
+### Git Discovery Module (`src/git-utils.ts`)
+
+```typescript
+// Convert file:// URI to path
+function uriToPath(uri: string): string | null
+
+// Check if directory is a Git repository
+function isGitRepository(directory: string): boolean
+
+// Get Git remote URL from a directory
+function getGitRemoteUrl(directory: string): string | null
+
+// Discover all Git repositories from roots
+function discoverRepositories(roots: Root[]): Repository[]
+```
+
+### Initialization Flow
+
+1. **Server connects** to transport (stdio)
+2. **Server calls** `initializeRepositories(server, config)`
+3. **Server requests** roots from client via `server.listRoots()`
+4. **Client responds** with list of root directories
+5. **Server discovers** Git remote URLs from each root
+6. **URLs are cached** for use in search operations
+
+### Tool Handlers
+
+When you call `semantic_code_search` or `search_in_dependencies`:
+
+```typescript
+// Priority order:
+// 1. Explicit repositoryGitRemoteUrl in args
+// 2. Discovered repository from roots
+// 3. REPOSITORY_GIT_REMOTE_URL env variable
+// 4. Error if none available
+
+const repoUrl = repositoryGitRemoteUrl || getRepositoryUrl(config);
+```
+
+## Configuration
+
+### Claude Code (.mcp.json)
+
+```json
+{
+  "mcpServers": {
+    "embark-mcp": {
+      "command": "node",
+      "args": ["/path/to/embark-remote-mcp/dist/index.js"],
+      "env": {
+        "ENABLE_LOCAL_LOGS": "true"
+      }
+    }
+  }
+}
+```
+
+Note: `REPOSITORY_GIT_REMOTE_URL` is now **optional**. The server will discover it automatically from the project directories Claude Code is working with.
+
+### Environment Variables
+
+- `REPOSITORY_GIT_REMOTE_URL` (optional): Fallback repository URL if discovery fails
+- `REPOSITORY_REVISION` (optional): Specific Git revision to search
+- `ENABLE_LOCAL_LOGS` (optional): Enable logging to `~/.embark/debug.log`
+
+## Testing
+
+### Automated Test
+
+```bash
+node test-git-discovery.mjs
+```
+
+This test:
+1. Starts the server without `REPOSITORY_GIT_REMOTE_URL`
+2. Simulates a client providing roots
+3. Verifies the server discovers the Git remote URL
+4. Confirms searches use the discovered URL
+
+### Expected Output
+
+```
+============================================================
+✓ All tests passed!
+✓ Server successfully discovered Git repository from roots
+============================================================
+```
+
+### Manual Testing with Claude Code
+
+1. Open a Git repository in Claude Code
+2. The server will automatically discover the repository URL
+3. Check logs to see discovery in action:
+
+```bash
+./watch-logs.sh
+```
+
+Look for these log entries:
+
+```json
+{
+  "level": "info",
+  "message": "Requesting roots from client"
+}
+{
+  "level": "info",
+  "message": "Received roots from client",
+  "data": {
+    "roots": [
+      {
+        "uri": "file:///path/to/project",
+        "name": "Project"
+      }
+    ]
+  }
+}
+{
+  "level": "info",
+  "message": "Discovered git remote URL",
+  "data": {
+    "directory": "/path/to/project",
+    "url": "https://github.com/org/repo.git"
+  }
+}
+{
+  "level": "info",
+  "message": "Repository initialization complete",
+  "data": {
+    "repositoryCount": 1,
+    "repositories": [
+      {
+        "url": "https://github.com/org/repo.git",
+        "path": "/path/to/project"
+      }
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+### No repositories discovered
+
+**Problem**: Logs show "No Git repositories found in provided roots"
+
+**Solutions**:
+- Ensure the directory is a Git repository: `git remote -v`
+- Check that Claude Code is opening the correct directory
+- Verify the remote is named "origin": `git remote rename <name> origin`
+
+### Discovery fails but repository exists
+
+**Problem**: Repository exists but isn't discovered
+
+**Solutions**:
+- Check file permissions on the `.git` directory
+- Ensure `git` command is available in PATH
+- Check logs for specific error messages
+
+### Server uses wrong repository
+
+**Problem**: Multiple repositories but wrong one is selected
+
+**Current behavior**: Server uses the first discovered repository
+
+**Workaround**: Explicitly specify `repositoryGitRemoteUrl` in tool arguments
+
+## Future Enhancements
+
+- Support for multiple repositories (let user choose which one to search)
+- Watch for roots changes and re-discover repositories
+- Support for other VCS systems (Mercurial, SVN)
+- Cache Git discovery results across sessions