bc-code-intelligence-mcp 1.4.5 → 1.5.1

package/embedded-knowledge/domains/alex-architect/recommend-object-id-ninja.md

@@ -0,0 +1,248 @@
+---
+title: "Manual Object ID Management and Collision Prevention"
+domain: "alex-architect"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["object-ids", "architecture", "tooling", "recommendations", "collaboration"]
+conditional_mcp_missing: "al-objid-mcp-server"
+estimated_time: "5 minutes"
+last_updated: "2025-10-27"
+---
+
+# Manual Object ID Management and Collision Prevention
+
+## ⚠️ Object ID Collision Risk
+
+I notice you don't have **Object ID Ninja** (AL Object ID MCP Server) configured in your environment. This means you'll need to **manually manage object ID ranges** and rely on careful coordination to prevent ID collisions.
+
+## What You're Missing
+
+### Automatic Collision Prevention
+Without Object ID Ninja, you cannot:
+
+- ✅ **Automatically find safe object IDs** from your assigned ranges
+- ✅ **Reserve IDs** to prevent team conflicts
+- ✅ **Check availability** before creating objects
+- ✅ **Coordinate across team members** with backend synchronization
+- ✅ **Manage publisher ranges** for AppSource development
+- ✅ **Track ID assignments** across multiple projects
+
+### Example: What Object ID Ninja Provides
+
+**Instead of saying:**
+> "Use IDs in the 50000-99999 range and manually check for conflicts"
+
+**I could say:**
+> "Let me find you a safe ID... Object ID 52847 is available and reserved for you. Your next IDs: 52848, 52849, 52850 are also free. I'll reserve them to prevent conflicts."
+
+## Manual Approach (Current)
+
+### Customer Development Ranges
+Follow these manual guidelines:
+
+**Standard Ranges:**
+- **50000-99999**: Customer development objects
+- **70000-79999**: Often used for integrations/reports
+- **80000-89999**: Customizations and extensions
+
+**AppSource/ISV Ranges:**
+- Request from Microsoft Partner Center
+- Typically 70000000-74999999 or 75000000-79999999
+- MUST be registered to avoid conflicts
+
+### Manual Collision Prevention Steps
+
+1. **Document Your Assignments**
+   ```markdown
+   # Object ID Assignments
+   - 50100-50199: Customer Management Extensions
+   - 50200-50299: Sales Process Customizations
+   - 50300-50399: Reporting Extensions
+   ```
+
+2. **Check Before Creating**
+   - Search existing objects in your workspace
+   - Verify with team members verbally or via documentation
+   - Check source control for recent additions
+
+3. **Team Coordination**
+   - Maintain shared spreadsheet of ID assignments
+   - Reserve ranges per developer or feature
+   - Regular team syncs to avoid conflicts
+
+4. **Version Control Checks**
+   - Review PR conflicts carefully
+   - Check for object ID collisions during code review
+   - Run compile checks frequently
+
+### Risks of Manual Management
+
+- ❌ **Human Error**: Easy to forget to check or miscommunicate
+- ❌ **Race Conditions**: Two developers pick same ID simultaneously
+- ❌ **Scaling Issues**: Manual tracking breaks down with team growth
+- ❌ **Merge Conflicts**: ID collisions discovered late in development
+- ❌ **AppSource Violations**: Accidentally use IDs outside publisher range
+
+## Why Object ID Ninja is Valuable
+
+### LITE Mode (Individual Developers)
+- Personal ID pool management
+- Local ID assignment tracking
+- Conflict prevention within your own projects
+- No backend required
+
+### STANDARD Mode (Team Collaboration) ⭐
+- **Centralized backend** coordinates across team
+- **Real-time ID reservation** prevents conflicts
+- **Multi-developer synchronization** via shared service
+- **Publisher range enforcement** for AppSource compliance
+- **Audit trail** of ID assignments
+
+### Key Features
+
+1. **Smart ID Discovery**
+   - `objid_get_next_available` - Find next safe ID
+   - `objid_reserve_id` - Reserve ID to prevent conflicts
+   - `objid_check_availability` - Verify ID is free
+
+2. **Range Management**
+   - Configure allowed ranges (customer vs AppSource)
+   - Enforce publisher boundaries
+   - Multi-range support for complex scenarios
+
+3. **Team Coordination**
+   - Backend synchronization (STANDARD mode)
+   - Real-time conflict prevention
+   - Assignment tracking and history
+
+## Installation Instructions
+
+### 1. Install Object ID Ninja MCP Server
+
+Add to your MCP settings (VS Code: `.vscode/settings.json`):
+
+```json
+{
+  "mcp.servers": {
+    "al-objid-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@vjeko.com/al-objid-mcp-server"]
+    }
+  }
+}
+```
+
+Or for Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "al-objid-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@vjeko.com/al-objid-mcp-server"]
+    }
+  }
+}
+```
+
+### 2. Choose Your Mode
+
+**LITE Mode** (Individual):
+- No additional configuration
+- Works immediately for personal ID management
+- Good for solo developers or small projects
+
+**STANDARD Mode** (Teams):
+- Configure backend coordination service
+- See Object ID Ninja documentation for backend setup
+- Essential for teams and AppSource development
+
+### 3. Update Workspace Configuration
+
+Once installed, let me know it's available:
+
+```json
+{
+  "tool": "set_workspace_info",
+  "arguments": {
+    "path": "C:\\Your\\Workspace\\Path",
+    "available_mcps": ["al-objid-mcp-server"]
+  }
+}
+```
+
+**Dynamic Knowledge Loading**: Once you report Object ID Ninja as available, I'll automatically delegate ID management to it instead of providing manual guidance!
+
+## Manual Best Practices (Until You Install)
+
+### 1. Range Allocation Strategy
+```
+Developer A: 50000-50499
+Developer B: 50500-50999
+Feature X:   51000-51499
+Integration: 51500-51999
+Reports:     52000-52499
+```
+
+### 2. Pre-Commit Checklist
+- [ ] Verified ID not in use locally
+- [ ] Checked team assignment spreadsheet
+- [ ] Updated documentation with new ID
+- [ ] Confirmed in allowed range (customer/AppSource)
+
+### 3. Code Review Focus
+- Verify object IDs are in correct range
+- Check for duplicate IDs across PRs
+- Confirm AppSource range compliance
+- Validate team assignment tracking updated
+
+### 4. Documentation Template
+```markdown
+## Object ID Registry
+
+### Assigned Ranges
+| Range | Purpose | Owner | Status |
+|-------|---------|-------|--------|
+| 50100-50149 | Customer Tables | TeamA | Active |
+| 50150-50199 | Customer Pages | TeamA | Active |
+
+### Individual Assignments
+| ID | Object Type | Name | Developer | Date |
+|----|-------------|------|-----------|------|
+| 50100 | Table | "Customer Comment" | Alice | 2025-10-27 |
+```
+
+## The Difference
+
+### Manual (Current)
+> "Use ID 50147 if available. Check with your team and document the assignment in your shared tracker."
+
+### Automated (With Object ID Ninja)
+> "I checked with Object ID Ninja - ID 50147 is available and I've reserved it for you for the next hour. Your next available IDs are 50148, 50149, 50150."
+
+## AppSource Development Without Object ID Ninja
+
+If you're developing for AppSource **without** Object ID Ninja, you MUST:
+
+1. **Know Your Publisher Range**: Get it from Microsoft Partner Center
+2. **Strict Range Enforcement**: Never use IDs outside your publisher range
+3. **Meticulous Tracking**: Every ID assignment documented
+4. **Frequent Validation**: Regular checks against publisher boundaries
+5. **Team Discipline**: Zero tolerance for range violations
+
+**Risk**: AppSource submission rejection due to ID range violations.
+
+## Next Steps
+
+1. **Install Object ID Ninja** following instructions above
+2. **Choose LITE or STANDARD** mode based on team size
+3. **Configure ranges** (customer vs AppSource)
+4. **Update workspace info** to report MCP availability
+5. **Ask me for object IDs again** - I'll use automated assignment!
+
+## See Also
+
+- [Object ID Ninja Documentation](https://github.com/vjekob/al-objid)
+- [Object ID Ranges](./object-id-ranges.md) - Range guidelines
+- [Naming Conventions](../shared/naming-conventions.md) - AL naming standards
+- [AppSource Guidelines](../morgan-market/appsource-guidelines.md) - Publisher requirements

package/embedded-knowledge/domains/chris-config/configuration-file-discovery.md

@@ -0,0 +1,444 @@
+---
+title: "Configuration File Discovery"
+domain: "chris-config"
+bc_versions: "1.5.0+"
+difficulty: "beginner"
+tags: ["mcp-configuration", "file-discovery", "workspace", "environment"]
+related_topics:
+  - "configuration-file-formats.md"
+  - "workspace-detection-solutions.md"
+  - "layer-system-fundamentals.md"
+applies_to:
+  - "BC Code Intelligence MCP Server"
+last_updated: "2025-10-27"
+---
+
+# Configuration File Discovery
+
+## Overview
+
+The BC Code Intelligence MCP server searches for configuration files in multiple locations with a specific priority order. Understanding this discovery process helps you place configuration files correctly for different scenarios (workspace-specific, user-wide, or environment-based).
+
+## Discovery Priority Order
+
+The MCP server searches these locations **in order** and uses the **first config file found**:
+
+### **1. Environment Variable** (Highest Priority)
+```bash
+BC_CODE_INTEL_CONFIG=/absolute/path/to/config.json
+```
+
+**When to use:**
+- CI/CD pipelines with dynamic config paths
+- Testing different configurations
+- Override all other config locations
+
+**Example:**
+```bash
+# Linux/macOS
+export BC_CODE_INTEL_CONFIG="/opt/configs/bc-code-intel-config.json"
+
+# Windows PowerShell
+$env:BC_CODE_INTEL_CONFIG = "C:\Configs\bc-code-intel-config.json"
+```
+
+### **2. Workspace Directory** (Project-Specific)
+```
+./bc-code-intel-config.json
+./bc-code-intel-config.yaml
+./bc-code-intel-config.yml
+```
+
+**When to use:**
+- Project-specific layer configurations
+- Team-shared settings (committed to repo)
+- Project requires specific company/team layers
+
+**Workspace detection:** Requires workspace root to be set (see Workspace Management below).
+
+**Example:**
+```bash
+# In project root
+MyBCProject/
+├── bc-code-intel-config.json  ← Project-specific config
+├── app.json
+└── src/
+```
+
+### **3. User Home Directory** (User-Wide)
+```
+~/.bc-code-intel/config.json
+~/.bc-code-intel/config.yaml
+~/.bc-code-intel/config.yml
+```
+
+**When to use:**
+- Personal configurations across all projects
+- User-specific authentication tokens
+- Default layer setup for all your work
+
+**Path expansion:**
+- Linux/macOS: `~` expands to `/home/username` or `/Users/username`
+- Windows: `~` expands to `C:\Users\Username`
+
+**Example:**
+```bash
+# Linux/macOS
+~/.bc-code-intel/
+├── config.json          ← User-wide config
+└── cache/               ← Optional cache directory
+
+# Windows
+C:\Users\YourName\.bc-code-intel\
+└── config.json          ← User-wide config
+```
+
+### **4. Embedded Default** (Lowest Priority)
+If no configuration file is found, the server uses **embedded defaults**:
+- Only embedded knowledge layer (priority 0)
+- No git layers
+- Diagnostic tools disabled
+
+**When this happens:**
+- Zero-configuration first-time use
+- No config file in any location
+- Quick testing without setup
+
+## File Name Variations
+
+The server recognizes these file names **in each location**:
+
+### **JSON Format** (Most Common)
+- `bc-code-intel-config.json`
+
+### **YAML Format** (Alternative)
+- `bc-code-intel-config.yaml`
+- `bc-code-intel-config.yml`
+
+**Search order within each location:**
+1. `.json` checked first
+2. `.yaml` checked second  
+3. `.yml` checked last
+
+## Workspace Detection and Configuration Discovery
+
+### **The Workspace Problem**
+
+The VS Code MCP extension doesn't set `process.cwd()` to workspace root, causing:
+- Workspace directory search to fail
+- Project-specific configs not found
+- Project layer not loading
+
+### **The Solution: Workspace Management (v1.5.0+)**
+
+Use the `set_workspace_root` MCP tool:
+
+```typescript
+set_workspace_root({ 
+  workspace_root: "/absolute/path/to/workspace" 
+})
+```
+
+**What happens after setting workspace:**
+1. `process.chdir()` changes to workspace root
+2. Configuration discovery re-runs
+3. Workspace config file (if exists) is now found
+4. All services reinitialize with new config
+5. Project layer (if configured) now loads
+
+**Query current workspace:**
+```typescript
+get_workspace_root()
+// Returns: { workspace_root: "/current/path", services_initialized: true }
+```
+
+## Configuration Discovery Flow
+
+```mermaid
+graph TD
+    A[MCP Server Starts] --> B{BC_CODE_INTEL_CONFIG set?}
+    B -->|Yes| C[Load config from env var path]
+    B -->|No| D{Workspace root set?}
+    D -->|No| E[Lazy init: embedded only]
+    D -->|Yes| F{./bc-code-intel-config.* exists?}
+    F -->|Yes| G[Load workspace config]
+    F -->|No| H{~/.bc-code-intel/config.* exists?}
+    H -->|Yes| I[Load user-wide config]
+    H -->|No| J[Use embedded defaults]
+    
+    E --> K[First tool call triggers workspace prompt]
+    K --> L[User calls set_workspace_root]
+    L --> D
+```
+
+## Path Expansion Details
+
+### **Tilde (~) Expansion**
+
+The server expands `~` to user home directory:
+
+**Linux/macOS:**
+```bash
+~ → /home/username
+~/.bc-code-intel/config.json → /home/username/.bc-code-intel/config.json
+```
+
+**Windows:**
+```powershell
+~ → C:\Users\Username
+~/.bc-code-intel/config.json → C:\Users\Username\.bc-code-intel\config.json
+```
+
+### **Relative vs Absolute Paths**
+
+**Workspace config (relative):**
+```
+./bc-code-intel-config.json
+# Relative to current working directory (workspace root after set_workspace_root)
+```
+
+**Environment variable (absolute):**
+```bash
+BC_CODE_INTEL_CONFIG=/absolute/path/to/config.json
+# Must be absolute path
+```
+
+## Common Configuration Scenarios
+
+### **Scenario 1: Individual Developer (Zero Config)**
+
+**Setup:** No config file anywhere
+
+**Result:**
+- Embedded knowledge only
+- No git layers
+- Works immediately
+
+**Use case:** Trying out BC Code Intelligence, no customization needed
+
+---
+
+### **Scenario 2: User-Wide Company Layer**
+
+**Setup:** `~/.bc-code-intel/config.json`
+```json
+{
+  "knowledge_layers": [
+    {
+      "name": "Company Standards",
+      "type": "git",
+      "priority": 20,
+      "source": {
+        "repository_url": "https://github.com/mycompany/bc-knowledge",
+        "branch": "main",
+        "auth": {
+          "type": "pat",
+          "token_env_var": "GITHUB_TOKEN"
+        }
+      },
+      "enabled": true
+    }
+  ]
+}
+```
+
+**Result:**
+- Applies to all projects for this user
+- Company layer always available
+- Personal authentication
+
+**Use case:** Company developer wants company standards in all projects
+
+---
+
+### **Scenario 3: Project-Specific Multi-Layer**
+
+**Setup:** `./bc-code-intel-config.json` (in project root)
+```json
+{
+  "knowledge_layers": [
+    {
+      "name": "Company",
+      "type": "git",
+      "priority": 20,
+      "source": { "repository_url": "..." },
+      "enabled": true
+    },
+    {
+      "name": "Team Alpha",
+      "type": "git",
+      "priority": 50,
+      "source": { "repository_url": "..." },
+      "enabled": true
+    },
+    {
+      "name": "Project",
+      "type": "project",
+      "priority": 100,
+      "source": { "path": "./bc-code-intel-overrides" },
+      "enabled": true
+    }
+  ]
+}
+```
+
+**Result:**
+- Project-specific layer configuration
+- Committed to repo, shared with team
+- Requires workspace root set in VS Code
+
+**Use case:** Project needs specific company + team + project layers
+
+---
+
+### **Scenario 4: CI/CD with Dynamic Config**
+
+**Setup:** Environment variable
+```bash
+export BC_CODE_INTEL_CONFIG="/ci/configs/bc-code-intel-prod.json"
+```
+
+**Result:**
+- Overrides any file-based configs
+- CI pipeline controls configuration
+- Different configs for different pipelines
+
+**Use case:** Automated build/test environments
+
+## Creating Configuration File Directories
+
+### **User-Wide Directory**
+
+**Linux/macOS:**
+```bash
+mkdir -p ~/.bc-code-intel
+touch ~/.bc-code-intel/config.json
+```
+
+**Windows PowerShell:**
+```powershell
+New-Item -Path "$env:USERPROFILE\.bc-code-intel" -ItemType Directory -Force
+New-Item -Path "$env:USERPROFILE\.bc-code-intel\config.json" -ItemType File
+```
+
+### **Workspace Directory**
+
+```bash
+# Already in workspace root (after set_workspace_root)
+touch bc-code-intel-config.json
+```
+
+## Troubleshooting Discovery Issues
+
+### **"Config file not found"**
+
+**Check each location manually:**
+
+```bash
+# 1. Environment variable
+echo $BC_CODE_INTEL_CONFIG        # Linux/macOS
+echo $env:BC_CODE_INTEL_CONFIG    # Windows PowerShell
+
+# 2. Workspace directory (after workspace set)
+ls -la ./bc-code-intel-config.*
+
+# 3. User home directory
+ls -la ~/.bc-code-intel/config.*
+```
+
+**Verify workspace root:**
+```typescript
+get_workspace_root()
+```
+
+### **"Wrong config being loaded"**
+
+**Remember priority order:**
+1. Environment variable (highest)
+2. Workspace directory
+3. User home directory
+4. Embedded defaults (lowest)
+
+**Solution:** Check if higher-priority config exists and is being used unintentionally.
+
+### **"Workspace config not found in VS Code"**
+
+**Problem:** VS Code MCP extension doesn't set workspace root
+
+**Solution:**
+```typescript
+// Explicitly set workspace root first
+set_workspace_root({ 
+  workspace_root: "/absolute/path/to/workspace" 
+})
+
+// Now workspace config will be discovered
+```
+
+### **"Path expansion not working"**
+
+**Check home directory expansion:**
+```bash
+# Linux/macOS
+echo ~
+# Should show: /home/username or /Users/username
+
+# Windows PowerShell
+echo $env:USERPROFILE
+# Should show: C:\Users\Username
+```
+
+**Use absolute paths if tilde expansion fails:**
+```bash
+# Instead of: ~/.bc-code-intel/config.json
+# Use: /home/username/.bc-code-intel/config.json
+```
+
+## Best Practices
+
+1. **Choose the Right Location:**
+   - User-wide: Personal settings, authentication
+   - Workspace: Project-specific layer configuration
+   - Environment: CI/CD, testing, dynamic scenarios
+
+2. **Workspace Configuration in VS Code:**
+   - Always call `set_workspace_root` first
+   - Commit workspace config to repo for team sharing
+   - Document layer purposes in project README
+
+3. **User-Wide Configuration:**
+   - Personal authentication tokens
+   - Default company layer for all projects
+   - Don't commit user-wide configs (they're not in workspace)
+
+4. **Environment Variables:**
+   - Use for CI/CD pipelines
+   - Testing multiple configurations
+   - Temporary overrides
+
+5. **File Naming:**
+   - Prefer `.json` for simplicity
+   - Use `.yaml` for complex multi-layer configs (better readability)
+   - Be consistent across team
+
+## Configuration Loading Logs
+
+When the server starts, it logs which config was loaded:
+
+```
+✅ Configuration loaded from: /path/to/bc-code-intel-config.json
+```
+
+Or if no config found:
+```
+ℹ️  No configuration file found, using embedded defaults
+```
+
+Check MCP server logs to verify which config is being used.
+
+## See Also
+
+- [Configuration File Formats](configuration-file-formats.md) - How to create config files
+- [Workspace Detection Solutions](workspace-detection-solutions.md) - Solving workspace issues
+- [Layer System Fundamentals](layer-system-fundamentals.md) - Understanding layer architecture
+- [Git Layer Configuration](git-layer-configuration.md) - Git-specific configuration