bc-code-intelligence-mcp 1.5.6 → 1.5.8

package/embedded-knowledge/domains/casey-copilot/samples/long-running-session-instructions.md

@@ -0,0 +1,323 @@
+# Long-Running Session Instruction Examples
+
+## Complete Project Instructions Template
+
+```markdown
+# Project: Customer Integration Extension
+
+## Project Context
+This BC extension syncs customer data with ExternalCRM system.
+- BC Version: 24.0
+- Extension ID: 70100000-70100099
+- Dependencies: Base Application, System Application
+
+## Environment Setup
+- Workspace: /src contains AL code
+- Tests: /test contains test codeunits  
+- Config: app.json, launch.json configured for dev container
+
+## Getting Started Each Session
+
+Before any coding work:
+1. Run `pwd` to confirm you're in the project root
+2. Read PROGRESS.md for the latest session summary
+3. Read FEATURES.json to see what's complete and what's pending
+4. Check `git log --oneline -10` for recent commits
+5. Compile the extension (Ctrl+Shift+B) to verify baseline
+6. Run tests to confirm nothing is broken
+
+If the project is in a broken state, fix it BEFORE implementing new features.
+
+## Feature Requirements
+
+See FEATURES.json for the structured list. High-level features:
+1. Customer Lookup - Find BC customer by external ID
+2. Customer Create - Create BC customer from external data
+3. Customer Update - Sync specific fields from external system
+4. Error Logging - Log failures to Integration Log table
+5. Retry Mechanism - Automatic retry of failed syncs
+6. Manual Sync - Page action to trigger sync on demand
+
+## Working Pattern
+
+Each session, follow this pattern:
+1. Complete the orientation steps above
+2. Choose ONE incomplete feature from FEATURES.json
+3. Implement that feature incrementally:
+   - Table changes first (if needed)
+   - Codeunit logic second
+   - Page updates third
+   - Tests alongside each object
+4. Verify the feature works end-to-end
+5. Commit with message: "feat: [Feature Name] - [Brief Description]"
+6. Update PROGRESS.md with session summary
+7. Update FEATURES.json to mark feature as passing
+8. STOP - do not start another feature
+
+## Verification Requirements
+
+A feature is NOT complete until:
+- [ ] Extension compiles without errors or warnings
+- [ ] Unit tests pass for new code
+- [ ] Integration tests verify end-to-end behavior
+- [ ] Manual test confirms expected behavior
+- [ ] Existing tests still pass (no regressions)
+
+Do NOT mark features passing based on code review alone.
+
+## End of Session Checklist
+
+Before ending any session:
+- [ ] Extension compiles cleanly
+- [ ] All tests pass
+- [ ] Changes committed with descriptive message
+- [ ] PROGRESS.md updated
+- [ ] FEATURES.json updated if feature completed
+- [ ] No uncommitted work-in-progress
+
+It is unacceptable to leave the codebase in a non-compiling state.
+
+## Code Standards
+
+Follow these BC/AL standards:
+- Use meaningful names following BC conventions
+- Add XML documentation to public procedures
+- Use Error/FieldError for validation, not Message
+- Wrap external calls in Try functions
+- Log significant operations via Session.LogMessage
+- Test edge cases, not just happy path
+
+## Off-Limits
+
+Do NOT:
+- Modify FEATURES.json except to change "passes" field
+- Remove or weaken existing tests
+- Skip the orientation/verification steps
+- Implement multiple features in one session
+- Leave TODO comments without logging to ISSUES.md
+```
+
+---
+
+## PROGRESS.md Template
+
+```markdown
+# Integration Extension Progress
+
+## Project Status: In Progress
+Last Updated: 2024-01-16
+
+## Completed Features
+
+### Session 2024-01-15 (Evening)
+**Feature**: Customer Lookup by External ID
+**Commit**: abc1234
+**Summary**: 
+- Added ExternalCustomerID field to Customer table extension
+- Created CustomerIntegration codeunit with FindByExternalId function
+- Added unit tests for lookup scenarios (found, not found, multiple matches)
+- All tests passing
+
+### Session 2024-01-16 (Morning)  
+**Feature**: Customer Create from External Data
+**Commit**: def5678
+**Summary**:
+- Added CreateFromExternalData procedure
+- Maps external fields to BC customer fields
+- Sets default values for required fields (Customer Posting Group, etc.)
+- Creates customer in pending state for review
+- Tests cover creation and default value application
+
+## Current Status
+
+**Working On**: Customer Update Sync
+**State**: Not started - ready for next session
+
+**Next Up**: 
+1. Customer Update Sync (highest priority)
+2. Error Logging infrastructure
+3. Retry Mechanism
+
+## Known Issues
+
+| Issue | Severity | Notes |
+|-------|----------|-------|
+| Phone formatting inconsistent | Low | External system uses various formats |
+| No duplicate detection | Medium | Should check for existing before create |
+
+## Session Notes
+
+- External API documentation: /docs/external-api.md
+- Test credentials in launch.json (dev only)
+- Mock responses in /test/mocks/ for offline testing
+```
+
+---
+
+## FEATURES.json Template
+
+```json
+{
+  "project": "Customer Integration Extension",
+  "lastUpdated": "2024-01-16",
+  "features": [
+    {
+      "id": 1,
+      "category": "core",
+      "description": "Customer lookup by external ID returns matching BC customer",
+      "acceptance": [
+        "FindByExternalId returns customer record when match exists",
+        "Returns empty record when no match",
+        "Handles multiple matches gracefully (logs warning, returns first)"
+      ],
+      "passes": true,
+      "completedDate": "2024-01-15",
+      "commit": "abc1234"
+    },
+    {
+      "id": 2,
+      "category": "core", 
+      "description": "New external customers create BC customer with defaults",
+      "acceptance": [
+        "CreateFromExternalData creates new customer record",
+        "Required fields populated with configured defaults",
+        "External ID stored for future lookups",
+        "Customer created in Pending status"
+      ],
+      "passes": true,
+      "completedDate": "2024-01-16",
+      "commit": "def5678"
+    },
+    {
+      "id": 3,
+      "category": "core",
+      "description": "Customer updates sync specific fields from external system",
+      "acceptance": [
+        "Name, Address, Phone fields update from external data",
+        "Other fields remain unchanged",
+        "Update logged with before/after values",
+        "No update if no changes detected"
+      ],
+      "passes": false
+    },
+    {
+      "id": 4,
+      "category": "infrastructure",
+      "description": "Failed syncs log to Integration Log table with error details",
+      "acceptance": [
+        "Integration Log table captures: timestamp, operation, error, external ID",
+        "Failed operations do not stop batch processing",
+        "Log entries accessible via Integration Log page"
+      ],
+      "passes": false
+    },
+    {
+      "id": 5,
+      "category": "infrastructure",
+      "description": "Retry mechanism attempts failed syncs automatically",
+      "acceptance": [
+        "Job queue entry processes Integration Log failures",
+        "Retry attempts logged with count",
+        "Max retries configurable (default 3)",
+        "Successful retry updates log status"
+      ],
+      "passes": false
+    },
+    {
+      "id": 6,
+      "category": "ui",
+      "description": "Manual sync action available on Customer Card",
+      "acceptance": [
+        "Sync action visible when External ID populated",
+        "Action triggers immediate sync for single customer",
+        "Success/failure message displayed",
+        "Page refreshes to show updated data"
+      ],
+      "passes": false
+    }
+  ]
+}
+```
+
+---
+
+## Orientation Script Example
+
+```markdown
+## Session Start Script
+
+When beginning a new session on this project, execute these steps in order:
+
+### Step 1: Confirm Location
+\`\`\`
+pwd
+# Expected: /workspaces/customer-integration
+\`\`\`
+
+### Step 2: Check Git Status
+\`\`\`
+git status
+git log --oneline -5
+\`\`\`
+Look for: uncommitted changes, recent commit messages
+
+### Step 3: Read Progress
+\`\`\`
+cat PROGRESS.md
+\`\`\`
+Understand: what's done, what's in progress, known issues
+
+### Step 4: Check Features
+\`\`\`
+cat FEATURES.json | jq '.features[] | select(.passes == false)'
+\`\`\`
+Identify: next feature to implement
+
+### Step 5: Verify Baseline
+\`\`\`
+# Compile extension
+al: Download Symbols
+al: Build
+
+# Run tests
+al: Run Tests
+\`\`\`
+Confirm: extension compiles, tests pass
+
+### Step 6: Begin Work
+Only after all checks pass, begin implementing the next feature.
+If any check fails, fix the issue before new development.
+```
+
+---
+
+## Commit Message Standards
+
+```markdown
+## Commit Message Format
+
+Use conventional commit format for BC projects:
+
+feat: [Object Type] [Feature Description]
+fix: [Object Type] [Bug Description]  
+test: [Object Type] [Test Description]
+docs: [Documentation Change]
+refactor: [Object Type] [Refactor Description]
+
+### Examples
+
+feat: Codeunit CustomerIntegration - Add FindByExternalId function
+feat: TableExt Customer - Add External Customer ID field
+fix: Codeunit CustomerIntegration - Handle null response from API
+test: Codeunit CustomerIntegrationTest - Add lookup edge cases
+docs: README - Update setup instructions for external API
+refactor: Codeunit CustomerIntegration - Extract field mapping logic
+
+### Commit Body
+
+For significant changes, include:
+- What was implemented
+- Why this approach was chosen
+- Any known limitations
+- Related features or issues
+```

package/embedded-knowledge/domains/eva-errors/codeunit-run-pattern.md

@@ -0,0 +1,159 @@
+---
+title: "Codeunit.Run() Error Handling Pattern"
+domain: "eva-errors"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["codeunit-run", "error-handling", "transactions", "commit", "isolation"]
+samples: "samples/codeunit-run-pattern.md"
+related_topics:
+  - "try-function-usage.md"
+  - "testfield-error-handling.md"
+---
+# Codeunit.Run() Error Handling Pattern
+
+## Overview
+
+The `if Codeunit.Run() then` pattern is a fundamental error handling mechanism in Business Central that enables transaction isolation and error recovery. Unlike try functions, this pattern allows write operations within its scope, making it essential for robust business process implementation.
+
+**Core Principle**: Capturing the boolean result from Codeunit.Run() fundamentally changes its behavior—enabling isolated transactions with error suppression and recovery.
+
+## How It Works
+
+### Standard Codeunit.Run()
+When you call `Codeunit.Run(CodeunitID)` without capturing the result:
+- Executes in the current transaction context
+- Errors propagate up and terminate execution
+- No special transaction handling occurs
+
+### Captured Result Pattern
+When you call `if Codeunit.Run(CodeunitID) then`:
+- A **new transaction** is started for the codeunit execution
+- If the codeunit succeeds, the transaction is committed
+- If the codeunit fails, the transaction is rolled back
+- Errors are **suppressed**—they don't terminate execution
+- The calling code continues regardless of success or failure
+- The developer must capture errors using GetLastErrorText()
+
+## Transaction Behavior
+
+### Transaction Isolation
+The captured Codeunit.Run() creates a transaction boundary:
+- All database operations inside the codeunit are isolated
+- Success commits all changes atomically
+- Failure rolls back all changes completely
+- The calling transaction is unaffected by the codeunit's outcome
+
+### Critical Requirement: Commit Before Run
+**Any open transaction MUST be committed before calling Codeunit.Run() with result capture.**
+
+This is required because:
+- The new transaction cannot begin while another is pending
+- Uncommitted changes from the caller would be in an undefined state
+- The runtime requires a clean transaction state
+
+Failure to commit first will result in a runtime error.
+
+## Implementation Guidelines
+
+### Proper Placement
+Use this pattern at logical boundaries in your processes:
+- Between major process phases
+- At the start of independent operations
+- When calling potentially failing external integrations
+- For batch processing individual records
+
+### Avoid Mid-Process Usage
+Do NOT use this pattern in the middle of a transaction sequence:
+- Commit() has permanent effects—it cannot be undone
+- Partial commits can leave data in inconsistent states
+- Plan your process flow to have clean commit points
+
+### Error Capture
+Always capture and handle errors when using this pattern:
+- Check the boolean result immediately
+- Use GetLastErrorText() to get error details
+- Log, notify, or take corrective action as appropriate
+
+## Use Cases
+
+### Batch Processing
+Process multiple records where individual failures shouldn't stop the entire batch:
+```
+// Conceptual pattern:
+foreach record in batch do begin
+    Commit();  // Clean slate for each record
+    if Codeunit.Run(ProcessorCodeunit, record) then
+        SuccessCount += 1
+    else begin
+        LogError(record, GetLastErrorText());
+        FailureCount += 1;
+    end;
+end;
+```
+
+### External Integration Points
+Isolate external system calls that include database updates:
+- Prepare staging data
+- Commit current transaction
+- Run integration codeunit with capture
+- Handle success or failure appropriately
+
+### Optional Processing Steps
+For process steps that should not block the main flow:
+- Archive operations
+- Notification sending
+- Audit logging to external systems
+
+## Comparison with Try Functions
+
+| Aspect | Try Function | Codeunit.Run() Pattern |
+|--------|--------------|------------------------|
+| Write Operations | NOT allowed in call stack | Fully allowed |
+| Transaction | Same transaction | New isolated transaction |
+| Error Behavior | Caught, rolled back | Caught, isolated rollback |
+| Commit Required | No | Yes, before the call |
+| Use Case | External calls, validation | Business processes, batch |
+
+## Best Practices
+
+### Plan Transaction Boundaries
+Design your process to have natural commit points before using this pattern. Don't force commits just to use Codeunit.Run().
+
+### Create Dedicated Codeunits
+Build codeunits specifically designed to be called with result capture:
+- Self-contained logic
+- Clear success/failure semantics
+- Appropriate error messaging
+
+### Document the Pattern
+When using Codeunit.Run() with capture, add comments explaining:
+- Why isolation is needed
+- What the commit point means
+- How failures are handled
+
+### Error Handling is Mandatory
+Never ignore the return value. The pattern's power comes from handling both success and failure cases appropriately.
+
+## Common Mistakes
+
+### Forgetting the Commit
+Calling Codeunit.Run() with capture while a transaction is open causes runtime errors. Always commit first.
+
+### Using Mid-Transaction
+Forcing a Commit() in the middle of a logical transaction to use this pattern leads to data integrity issues.
+
+### Ignoring Failures
+Capturing the result but not acting on failures defeats the purpose and hides problems.
+
+### Overusing the Pattern
+Not every codeunit call needs isolation. Use this pattern when you specifically need independent transaction handling.
+
+## Summary
+
+The Codeunit.Run() pattern with result capture is essential for:
+- Enabling error handling with database operations
+- Isolating transactions for failure recovery
+- Building robust batch and integration processes
+
+Remember: **Commit() before, capture the result, handle errors explicitly.**
+