@gwdn/nexus-mcp 0.7.0

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

@@ -0,0 +1,443 @@
+/**
+ * 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

@@ -0,0 +1,58 @@
+/**
+ * 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',
+}