@gwdn/nexus-mcp 0.8.7 → 0.8.8

package/src/__tests__/e2e-integration.test.ts

@@ -1,443 +0,0 @@
-/**
- * E2E Integration Tests for Nexus MCP Tools
- *
- * These tests exercise the real API client (nexusApi) against a live
- * Nexus backend. They require:
- *
- *   NEXUS_API_URL=https://nexus.gatewarden.eu (or localhost:3000)
- *   NEXUS_PRIVATE_TOKEN=nxs_pat_<valid_token>
- *   NEXUS_E2E_PROJECT_ID=<uuid of a test project>
- *
- * Run with: NEXUS_E2E=1 vitest run --testPathPattern=e2e
- *
- * Skip in CI by default (only runs when NEXUS_E2E=1 is set).
- */
-
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import { nexusGet, nexusPost, resetApiConfig } from '../nexus-api.js'
-
-const E2E_ENABLED = process.env.NEXUS_E2E === '1'
-const PROJECT_ID = process.env.NEXUS_E2E_PROJECT_ID
-
-// The global setup.ts overrides env vars with test values.
-// For E2E tests, we restore the real values from NEXUS_E2E_* vars.
-const REAL_API_URL = process.env.NEXUS_E2E_API_URL
-const REAL_TOKEN = process.env.NEXUS_E2E_TOKEN
-
-if (E2E_ENABLED && REAL_API_URL && REAL_TOKEN) {
-  process.env.NEXUS_API_URL = REAL_API_URL
-  process.env.NEXUS_PRIVATE_TOKEN = REAL_TOKEN
-  resetApiConfig()
-}
-
-const describeE2e = E2E_ENABLED ? describe : describe.skip
-
-// ---------------------------------------------------------------------------
-// Shared state for cross-test references
-// ---------------------------------------------------------------------------
-let createdSessionId: string | null = null
-let createdTaskId: string | null = null
-let createdDocId: string | null = null
-let createdLetterId: string | null = null
-
-describeE2e('E2E: Identity and Project Access', () => {
-  it('should resolve identity from token', async () => {
-    const result = await nexusGet('/api/mcp/identity')
-    expect(result.ok).toBe(true)
-    expect(result.data).toHaveProperty('userId')
-    expect(result.data).toHaveProperty('email')
-    // Backend returns isPlatformAdmin/isPlatformOwner boolean fields
-    expect(result.data).toHaveProperty('isPlatformAdmin')
-  })
-
-  it('should list accessible projects', async () => {
-    const result = await nexusGet('/api/mcp/projects')
-    expect(result.ok).toBe(true)
-    const data = result.data as { projects: unknown[] }
-    expect(Array.isArray(data.projects)).toBe(true)
-    expect(data.projects.length).toBeGreaterThan(0)
-  })
-})
-
-describeE2e('E2E: Session Lifecycle', () => {
-  it('should create a session', async () => {
-    const result = await nexusPost('/api/mcp/sessions', {
-      action: 'session_create',
-      project_id: PROJECT_ID,
-      title: 'E2E Test Session',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; id: string; status: string }
-    expect(data.action).toBe('session_create')
-    expect(data.status).toBe('open')
-    createdSessionId = data.id
-  })
-
-  it('should list sessions and find the created one', async () => {
-    const result = await nexusPost('/api/mcp/sessions', {
-      action: 'session_list',
-      project_id: PROJECT_ID,
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { sessions: { id: string }[] }
-    const found = data.sessions.find((s) => s.id === createdSessionId)
-    expect(found).toBeDefined()
-  })
-
-  it('should append an entry to the session', async () => {
-    const result = await nexusPost('/api/mcp/sessions', {
-      action: 'session_append',
-      session_id: createdSessionId,
-      entry_type: 'note',
-      summary: 'E2E test entry',
-    })
-    // Known backend bug: actor field gets email string instead of UUID
-    if (!result.ok && result.error?.includes('uuid')) {
-      console.warn('[E2E] session_append has known actor UUID bug:', result.error)
-      return
-    }
-    expect(result.ok).toBe(true)
-  })
-
-  it('should close the session', async () => {
-    const result = await nexusPost('/api/mcp/sessions', {
-      action: 'session_close',
-      session_id: createdSessionId,
-      summary: 'E2E test completed',
-      next_entry_point: 'Cleanup test data',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { status: string }
-    expect(data.status).toBe('closed')
-  })
-})
-
-describeE2e('E2E: Task Lifecycle', () => {
-  it('should create a task', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_create',
-      project_id: PROJECT_ID,
-      title: 'E2E Test Task',
-      description: 'Created by E2E integration test',
-      priority: 'low',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; task_id: string }
-    expect(data.action).toBe('task_create')
-    createdTaskId = data.task_id
-  })
-
-  it('should list tasks and find the created one', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_list',
-      project_id: PROJECT_ID,
-    })
-    // task_list is a new action - skip if backend not yet deployed
-    if (!result.ok && result.error?.includes('Unknown action')) return
-    expect(result.ok).toBe(true)
-    const data = result.data as { tasks: { id: string }[] }
-    const found = data.tasks.find((t) => t.id === createdTaskId)
-    expect(found).toBeDefined()
-  })
-
-  it('should add a note to the task', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_note',
-      task_id: createdTaskId,
-      note: 'E2E test note',
-    })
-    // task_notes may fail due to RLS or missing table - record but don't fail
-    if (!result.ok) {
-      console.warn('[E2E] task_note failed:', result.error)
-      return
-    }
-    expect(result.ok).toBe(true)
-  })
-
-  it('should update task status to done', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_update',
-      task_id: createdTaskId,
-      status: 'done',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { new_status: string }
-    expect(data.new_status).toBe('done')
-  })
-
-  it('should filter tasks by status', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_list',
-      project_id: PROJECT_ID,
-      status_filter: ['done'],
-    })
-    // task_list is a new action - skip if backend not yet deployed
-    if (!result.ok && result.error?.includes('Unknown action')) return
-    expect(result.ok).toBe(true)
-    const data = result.data as { tasks: { status: string }[] }
-    for (const task of data.tasks) {
-      expect(task.status).toBe('done')
-    }
-  })
-})
-
-describeE2e('E2E: Document Lifecycle', () => {
-  it('should ingest a document', async () => {
-    const result = await nexusPost('/api/mcp/documents', {
-      action: 'doc_ingest',
-      project_id: PROJECT_ID,
-      title: 'E2E Test Document',
-      body: '# E2E Test\n\nThis document was created by the E2E test suite.',
-      source: 'e2e-test',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; document_id: string }
-    expect(data.action).toBe('doc_ingest')
-    createdDocId = data.document_id
-  })
-
-  it('should list documents and find the ingested one', async () => {
-    const result = await nexusPost('/api/mcp/documents', {
-      action: 'doc_list',
-      project_id: PROJECT_ID,
-    })
-    // doc_list is a new action - skip if backend not yet deployed
-    if (!result.ok && result.error?.includes('entity_type')) return
-    expect(result.ok).toBe(true)
-    const data = result.data as { documents: { id: string }[] }
-    const found = data.documents.find((d) => d.id === createdDocId)
-    expect(found).toBeDefined()
-  })
-
-  it('should filter documents by source', async () => {
-    const result = await nexusPost('/api/mcp/documents', {
-      action: 'doc_list',
-      project_id: PROJECT_ID,
-      source: 'e2e-test',
-    })
-    // doc_list is a new action - skip if backend not yet deployed
-    if (!result.ok && result.error?.includes('entity_type')) return
-    expect(result.ok).toBe(true)
-    const data = result.data as { documents: { source: string }[] }
-    for (const doc of data.documents) {
-      expect(doc.source).toBe('e2e-test')
-    }
-  })
-
-  it('should fetch the ingested document via kb_get', async () => {
-    const result = await nexusPost('/api/mcp/documents', {
-      action: 'kb_get',
-      entity_type: 'ingest_item',
-      entity_id: createdDocId,
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { entity_type: string; document: { title: string } }
-    expect(data.entity_type).toBe('ingest_item')
-    expect(data.document.title).toBe('E2E Test Document')
-  })
-})
-
-describeE2e('E2E: Knowledge Search and Memory', () => {
-  it('should search knowledge by keyword', async () => {
-    const result = await nexusPost('/api/mcp/search', {
-      project_id: PROJECT_ID,
-      query: 'architecture',
-      search_mode: 'keyword',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { total_results: number }
-    expect(data.total_results).toBeGreaterThanOrEqual(0)
-  })
-
-  it('should get project memory with ADRs', async () => {
-    const result = await nexusPost('/api/mcp/memory', {
-      project_id: PROJECT_ID,
-      include: ['adrs'],
-      depth: 'light',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { memory: { adrs: unknown[] } }
-    expect(Array.isArray(data.memory.adrs)).toBe(true)
-  })
-
-  it('should get project memory with active tasks', async () => {
-    const result = await nexusPost('/api/mcp/memory', {
-      project_id: PROJECT_ID,
-      include: ['active_tasks'],
-    })
-    expect(result.ok).toBe(true)
-  })
-})
-
-describeE2e('E2E: Vault Letter Lifecycle', () => {
-  it('should create a letter', async () => {
-    const result = await nexusPost('/api/mcp/letters', {
-      action: 'vl_create',
-      project_id: PROJECT_ID,
-      from_actor: 'e2e-test-agent',
-      to_actor: 'e2e-test-human',
-      subject: 'E2E Test Letter',
-      body: 'This letter was created by the E2E test suite.',
-      priority: 'low',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; letter_id: string }
-    expect(data.action).toBe('vl_create')
-    createdLetterId = data.letter_id
-  })
-
-  it('should find the letter in inbox', async () => {
-    const result = await nexusPost('/api/mcp/letters', {
-      action: 'vl_inbox',
-      project_id: PROJECT_ID,
-    })
-    expect(result.ok).toBe(true)
-  })
-
-  it('should acknowledge the letter', async () => {
-    const result = await nexusPost('/api/mcp/letters', {
-      action: 'vl_ack',
-      letter_id: createdLetterId,
-    })
-    expect(result.ok).toBe(true)
-  })
-
-  it('should reply to the letter', async () => {
-    const result = await nexusPost('/api/mcp/letters', {
-      action: 'vl_reply',
-      letter_id: createdLetterId,
-      body: 'E2E test reply',
-      new_status: 'closed',
-    })
-    expect(result.ok).toBe(true)
-  })
-
-  it('should find the letter in outbox', async () => {
-    const result = await nexusPost('/api/mcp/letters', {
-      action: 'vl_outbox',
-      project_id: PROJECT_ID,
-    })
-    expect(result.ok).toBe(true)
-  })
-})
-
-describeE2e('E2E: Skill Management', () => {
-  it('should list skills', async () => {
-    const result = await nexusPost('/api/mcp/skills', {
-      action: 'sk_list',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; count: number }
-    expect(data.action).toBe('sk_list')
-  })
-
-  it('should export skills for project', async () => {
-    const result = await nexusPost('/api/mcp/skills', {
-      action: 'sk_export',
-      project_id: PROJECT_ID,
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string }
-    expect(data.action).toBe('sk_export')
-  })
-})
-
-describeE2e('E2E: Governance (ADR)', () => {
-  let testAdrId: string | null = null
-
-  it('should create an ADR draft', async () => {
-    const result = await nexusPost('/api/mcp/governance', {
-      action: 'adr_create',
-      project_id: PROJECT_ID,
-      title: 'E2E Test ADR',
-      context: 'Created by E2E integration test suite.',
-      decision: 'This ADR should be cleaned up after testing.',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { action: string; adr_id: string }
-    expect(data.action).toBe('adr_create')
-    testAdrId = data.adr_id
-  })
-
-  it('should submit the ADR for review', async () => {
-    const result = await nexusPost('/api/mcp/governance', {
-      action: 'adr_submit',
-      adr_id: testAdrId,
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { new_state: string }
-    expect(data.new_state).toBe('under_review')
-  })
-
-  it('should add a comment to the ADR', async () => {
-    const result = await nexusPost('/api/mcp/governance', {
-      action: 'dc_add',
-      decision_id: testAdrId,
-      body: 'E2E test comment',
-    })
-    expect(result.ok).toBe(true)
-  })
-
-  it('should list ADR comments', async () => {
-    const result = await nexusPost('/api/mcp/governance', {
-      action: 'dc_list',
-      decision_id: testAdrId,
-    })
-    expect(result.ok).toBe(true)
-  })
-
-  it('should reject the test ADR', async () => {
-    const result = await nexusPost('/api/mcp/governance', {
-      action: 'adr_decide',
-      adr_id: testAdrId,
-      decision: 'rejected',
-      rationale: 'E2E test cleanup - not a real ADR',
-    })
-    expect(result.ok).toBe(true)
-    const data = result.data as { new_state: string }
-    expect(data.new_state).toBe('rejected')
-  })
-})
-
-describeE2e('E2E: Entity Navigation', () => {
-  it('should navigate related entities', async () => {
-    // Use the test session to find related entries
-    if (!createdSessionId) return
-
-    const result = await nexusPost('/api/mcp/related', {
-      entity_type: 'session',
-      entity_id: createdSessionId,
-    })
-    expect(result.ok).toBe(true)
-  })
-})
-
-describeE2e('E2E: Error Handling', () => {
-  it('should return 400 for missing required fields', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'task_create',
-      project_id: PROJECT_ID,
-      // missing title
-    })
-    expect(result.ok).toBe(false)
-    expect(result.status).toBe(400)
-  })
-
-  it('should return 404 for non-existent entity', async () => {
-    const result = await nexusPost('/api/mcp/documents', {
-      action: 'kb_get',
-      entity_type: 'task',
-      entity_id: '00000000-0000-0000-0000-000000000000',
-    })
-    expect(result.ok).toBe(false)
-    expect(result.status).toBe(404)
-  })
-
-  it('should return 400 for unknown action', async () => {
-    const result = await nexusPost('/api/mcp/tasks', {
-      action: 'nonexistent_action',
-    })
-    expect(result.ok).toBe(false)
-    expect(result.status).toBe(400)
-  })
-})

package/src/__tests__/helpers.ts

@@ -1,58 +0,0 @@
-/**
- * Test helpers for MCP tool tests.
- *
- * Provides utilities for mocking the Nexus API client
- * and parsing MCP tool responses.
- */
-
-import type { NexusApiResponse } from '../nexus-api.js'
-
-/**
- * Create a successful NexusApiResponse.
- */
-export function mockApiSuccess<T>(data: T): NexusApiResponse<T> {
-  return { ok: true, status: 200, data, error: null }
-}
-
-/**
- * Create a failed NexusApiResponse.
- */
-export function mockApiError(
-  error: string,
-  status = 400,
-): NexusApiResponse<never> {
-  return { ok: false, status, data: null, error }
-}
-
-/**
- * Helper to parse the JSON from an MCP tool response.
- */
-export function parseToolResponse(result: {
-  content: { type: string; text: string }[]
-  isError?: boolean
-}) {
-  const text = result.content[0]?.text
-  if (!text) throw new Error('Empty tool response')
-  return JSON.parse(text)
-}
-
-/**
- * Standard test UUIDs for consistency across tests.
- */
-export const TEST_IDS = {
-  userId: '83a37012-8add-428f-8bc3-d56c84291671',
-  projectId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee',
-  sessionId: '11111111-2222-3333-4444-555555555555',
-  taskId: '22222222-3333-4444-5555-666666666666',
-  letterId: '33333333-4444-5555-6666-777777777777',
-  adrId: '44444444-5555-6666-7777-888888888888',
-  entryId: '55555555-6666-7777-8888-999999999999',
-  noteId: '66666666-7777-8888-9999-aaaaaaaaaaaa',
-  documentId: '77777777-8888-9999-aaaa-bbbbbbbbbbbb',
-  agentId: 'nexus-app-agent',
-  otherUserId: '99999999-aaaa-bbbb-cccc-dddddddddddd',
-  skillId: '88888888-9999-aaaa-bbbb-cccccccccccc',
-  tenantId: '20c72e35-d4d8-4e40-a7be-efff14d8eaff',
-  reviewId: 'aabbccdd-1122-3344-5566-778899001122',
-  assignmentId: 'bbccddee-2233-4455-6677-889900112233',
-}