📝 Update Information

Primitive Details

• Type: Prompts, Extension
• Name: All 14 workflow prompts, VS Code extension infrastructure
• Update Category: Feature Enhancement, Robustness, UX

⚠️ CRITICAL: PR SCOPE VALIDATION

✅ ALLOWED FILES:

• Server implementation files (server/src/**/*.ts)
• Updated primitive implementations
• Updated or new test files (server/test/**/*.ts)
• Extension source files (extensions/vscode/src/**/*.ts)
• Extension test files (extensions/vscode/test/**/*.ts)
• Build configuration (extensions/vscode/esbuild.config.js)
• Shared constants (server/src/prompts/constants.ts)

🚫 FORBIDDEN FILES:

• No unrelated files included

🛑 MANDATORY PR VALIDATION CHECKLIST

• ONLY server and extension implementation files are included
• NO temporary or output files are included
• NO unrelated configuration files are included
• ALL existing tests continue to pass
• NEW functionality is properly tested

• Impact Scope: Moderate — touches all prompt registrations, extension CLI resolver, pack installer, watchers, and MCP provider

Update Metadata

• Breaking Changes: No
• API Compatibility: Enhanced (additive only — completion/complete responses are new, language parameter now optional on several prompts)
• Performance Impact: Neutral (completions are lazy with 5s TTL cache; debounced MCP definition-change events reduce noise)

🎯 Changes Description

Current Behavior

Workflow prompts used as VS Code Copilot Chat slash commands show raw text input fields for all parameters. Users must manually type full file paths for CodeQL queries, databases, SARIF files, etc. The language parameter is required on every prompt, even when it could be inferred. Extension-side CLI resolution can race, pack installer logging is inconsistent, and file watchers fire noisy MCP definition-change events.

Updated Behavior

MCP Server Prompt Completions:

• Prompt parameters now provide auto-complete suggestions via the MCP SDK's completable() function. VS Code shows a filtered dropdown as the user types:
  • language — filters SUPPORTED_LANGUAGES by prefix
  • queryPath — discovers .ql/.qlref files in workspace
  • sarifPath/sarifPathA/sarifPathB — discovers .sarif/.sarif.json files
  • database/databasePath — lists CodeQL database directories from CODEQL_DATABASES_BASE_DIRS, $HOME/codeql/databases/, and workspace
  • workspaceUri/packRoot — finds directories containing codeql-pack.yml
• Completion results are cached with a 5-second TTL to avoid repeated workspace scans.
• A centralized SKIP_DIRS set ensures all completion providers consistently skip node_modules, .git, .github, .tmp, build, coverage, and dist directories.

Optional Language with Auto-Derivation:

• Several workflow prompts (workshop_creation_workflow, explain_codeql_query, document_codeql_query, ql_lsp_iterative_development) now accept language as optional.
• When omitted, language is auto-derived from the nearest codeql-pack.yml with a codeql/<lang>-all or codeql/<lang>-queries dependency via resolveLanguageFromPack().
• A shared getEffectiveLanguage() helper centralizes the derivation logic, debug logging, and warning generation across all prompt handlers.
• queryPath is ordered before language in schema shapes so the user fills in the query first, enabling better auto-derivation.

Extension Robustness:

• CliResolver ensures only one resolution runs at a time, validates PATH-discovered binaries, and uses generation tokens to prevent stale cache writes after invalidation.
• PackInstaller uses consistent "download" terminology for codeql pack download operations and provides detailed per-language logging.
• McpProvider.fireDidChange debounces rapid-fire notifications and clears pending timers on dispose/restart.
• File watchers use relative paths in log messages and no longer trigger MCP definition changes for content-only file events.

Circular Dependency Fix:

• SUPPORTED_LANGUAGES moved to server/src/prompts/constants.ts to break the circular import between workflow-prompts.ts and prompt-completions.ts.

Motivation

The VS Code MCP integration supports completion/complete for prompt arguments. The MCP SDK already ships completable() — we just weren't using it. Additionally, requiring language when it could be inferred from pack metadata created unnecessary friction, and extension-side race conditions in CLI resolution and noisy watcher events degraded the user experience.

🔄 Before vs. After Comparison

Functionality Changes

// BEFORE: raw shape, no completions, language always required
server.prompt('explain_codeql_query', description,
  toPermissiveShape(explainCodeqlQuerySchema.shape),
  handler);

// AFTER: completable-wrapped shape, language optional + auto-derived
server.prompt('explain_codeql_query', description,
  addCompletions(toPermissiveShape(explainCodeqlQuerySchema.shape)),
  createSafePromptHandler('explain_codeql_query', explainCodeqlQuerySchema,
    async ({ queryPath, language }) => {
      // ...
      const langResult = await getEffectiveLanguage('explain_codeql_query', language, resolvedQueryPath);
      const effectiveLanguage = langResult.language;
      if (langResult.warning) warnings.push(langResult.warning);
      // ...
    }));

API Changes

// Input Schema Changes — language now optional on select prompts
// BEFORE:
const explainCodeqlQuerySchema = z.object({
  queryPath: z.string(),
  language: z.enum(SUPPORTED_LANGUAGES),
  databasePath: z.string().optional(),
});

// AFTER:
const explainCodeqlQuerySchema = z.object({
  queryPath: z.string(),
  language: z.enum(SUPPORTED_LANGUAGES).optional(),
  databasePath: z.string().optional(),
});

Output Format Changes

New completion/complete responses:

{
  "completion": {
    "values": ["java", "javascript"],
    "hasMore": false,
    "total": 2
  }
}

🧪 Testing & Validation

Test Coverage Updates

• Existing Tests: All existing tests continue to pass (1377 server, 182 extension unit)
• New Test Cases: 65 unit tests for completion providers, addCompletions, resolveLanguageFromPack, getEffectiveLanguage, and schema field ordering
• Regression Tests: Existing workflow-prompts.test.ts (309 tests) validates schema consistency
• Edge Case Tests: ZodEnum handling, mutation safety, empty workspace, skipped directories, Windows env var stubs, cross-platform homedir() behavior

Validation Scenarios

1. Backward Compatibility: All 309 existing workflow prompt tests pass unchanged
2. New Functionality: 65 new completion/auto-derivation tests; 12 new E2E integration tests
3. Error Handling: getEffectiveLanguage returns user-friendly warnings when language can't be derived
4. Performance: Completion results cached with 5s TTL; SKIP_DIRS set avoids scanning large output directories

Test Results

• Unit Tests: 1377/1377 pass (server), 182/182 pass (extension)
• Integration Tests: 12 new E2E tests in mcp-completion-e2e.integration.test.ts
• Manual Testing: N/A (sandbox environment cannot download VS Code)
• Performance Testing: No regressions detected

📋 Implementation Details

Files Modified

• Core Implementation: server/src/prompts/prompt-completions.ts — completion providers, addCompletions(), resolveLanguageFromPack(), getEffectiveLanguage()
• Core Implementation: server/src/prompts/workflow-prompts.ts — apply addCompletions() to all 14 prompts, use getEffectiveLanguage() helper, make language optional on select prompts
• Shared Constants: server/src/prompts/constants.ts — SUPPORTED_LANGUAGES extracted to break circular dependency
• Extension: extensions/vscode/src/codeql/cli-resolver.ts — concurrency control, PATH validation, generation tokens
• Extension: extensions/vscode/src/server/pack-installer.ts — consistent download terminology, detailed logging
• Extension: extensions/vscode/src/server/mcp-provider.ts — debounced fireDidChange, timer cleanup on dispose
• Extension: extensions/vscode/src/bridge/database-watcher.ts, query-results-watcher.ts — relative path logging, no MCP definition changes on content events
• Tests: server/test/src/prompts/prompt-completions.test.ts — 65 tests for completions, language resolution, getEffectiveLanguage, schema ordering
• Tests: extensions/vscode/test/suite/mcp-completion-e2e.integration.test.ts — 12 E2E completion tests
• Build Config: extensions/vscode/esbuild.config.js — add new test entry point

Code Changes Summary

• Algorithm Improvements: Centralized SKIP_DIRS set for workspace scanning; cached completion results with TTL
• Error Handling: getEffectiveLanguage() returns structured {language, warning} result
• Performance Optimization: 5-second scan cache, consistent directory skip list
• Type Safety: cloneStringType preserves ZodEnum types; runtime checks for unexpected Zod types
• Input Validation: Enum preservation for prompts using raw shapes (e.g., findOverlappingQueriesSchema)

Dependencies

• No New Dependencies: Uses existing @modelcontextprotocol/sdk v1.29 (completable export)

🔍 Quality Improvements

Code Quality Enhancements

• Readability: Centralized SKIP_DIRS, extracted getEffectiveLanguage() helper to eliminate 4× duplicated language auto-derivation blocks
• Maintainability: SUPPORTED_LANGUAGES in shared constants.ts breaks circular dependency
• Testability: 65 new unit tests + 12 E2E tests; Windows env var stubs for cross-platform test compatibility
• Reusability: addCompletions() automatically enhances any prompt shape with matching parameter names

🔗 References

External References

• VS Code MCP developer guide — Prompts with completions
• MCP SDK completable() API

🚀 Compatibility & Migration

Backward Compatibility

• Fully Compatible: No breaking changes. Clients that don't support completion/complete simply never call it. Prompts that previously required language now accept it as optional with auto-derivation fallback.

API Evolution

• Enhanced Parameters: language now optional on select prompts; all prompt arguments gain auto-complete
• Improved Responses: Warnings when language can't be auto-derived
• Maintained Contracts: All prompt schemas, handlers, and validation unchanged for non-affected prompts

👥 Review Guidelines

For Reviewers

• ⚠️ SCOPE COMPLIANCE: Server + extension files, all directly related
• ⚠️ BACKWARD COMPATIBILITY: Zero changes to prompt handler logic or schemas for non-affected prompts
• Functionality: addCompletions() is a pure wrapper — prompt behavior unchanged
• Test Coverage: 65 new unit tests + 12 E2E tests + all existing tests pass
• Code Quality: Centralized SKIP_DIRS, extracted getEffectiveLanguage(), broke circular dependency

Testing Instructions

# Full server test suite (1377 tests)
npm test -w server

# Extension unit tests (182 tests)
npm run test:coverage -w extensions/vscode

# Specific prompt completion tests
cd server && npx vitest run test/src/prompts/prompt-completions.test.ts

# Full build and lint
npm run build-and-test

📊 Impact Assessment

Server Impact

• Startup Time: Negligible — addCompletions runs once during registration
• Runtime Stability: Completion callbacks are async, error-resilient (catch + empty array)
• Resource Usage: File scans capped at 50 results, 8 levels deep, cached with 5s TTL
• Concurrent Usage: Safe for concurrent access

AI Assistant Impact

• Enhanced User Experience: Users pick from dropdowns instead of typing raw paths
• Enhanced Accuracy: Language auto-derivation reduces user error
• Improved Reliability: Debounced MCP events, concurrent CLI resolution guard