@mpowr/nexus-mcp 0.5.0 → 0.6.1

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.mpowr.tech (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__/layer2-coordination.test.ts

@@ -126,6 +126,34 @@ describe('Layer 2: Session tools', () => {
       expect(parsed.count).toBe(2)
       expect(parsed.sessions).toHaveLength(2)
     })
+
+    it('should return error on API failure', async () => {
+      vi.mocked(nexusPost).mockResolvedValue(mockApiError('Project not found', 404))
+
+      const { listOpenSessions } = await import('../tools/sessions.js')
+      const result = await listOpenSessions({ project_id: TEST_IDS.projectId })
+
+      expect(result.isError).toBe(true)
+    })
+
+    it('should handle empty session list', async () => {
+      vi.mocked(nexusPost).mockResolvedValue(
+        mockApiSuccess({
+          action: 'session_list',
+          project_id: TEST_IDS.projectId,
+          count: 0,
+          sessions: [],
+        }),
+      )
+
+      const { listOpenSessions } = await import('../tools/sessions.js')
+      const result = await listOpenSessions({ project_id: TEST_IDS.projectId })
+
+      expect(result.isError).toBeUndefined()
+      const parsed = parseToolResponse(result)
+      expect(parsed.count).toBe(0)
+      expect(parsed.sessions).toHaveLength(0)
+    })
   })
 })
 
@@ -388,6 +416,19 @@ describe('Layer 2: Letter tools', () => {
       expect(parsed.action).toBe('vl_reply')
     })
 
+    it('should return error on API failure', async () => {
+      vi.mocked(nexusPost).mockResolvedValue(mockApiError('Letter not found', 404))
+
+      const { replyLetter } = await import('../tools/letters.js')
+      const result = await replyLetter({
+        letter_id: TEST_IDS.letterId,
+        body: 'Reply to missing letter',
+        user_id: TEST_IDS.userId,
+      })
+
+      expect(result.isError).toBe(true)
+    })
+
     it('should include new_status when provided', async () => {
       vi.mocked(nexusPost).mockResolvedValue(
         mockApiSuccess({
@@ -497,6 +538,18 @@ describe('Layer 2: Inbox and Outbox tools', () => {
       expect(parsed.action).toBe('vl_outbox')
       expect(parsed.count).toBe(1)
     })
+
+    it('should return error on API failure', async () => {
+      vi.mocked(nexusPost).mockResolvedValue(mockApiError('Project not found', 404))
+
+      const { listOutbox } = await import('../tools/letter-inbox.js')
+      const result = await listOutbox({
+        project_id: TEST_IDS.projectId,
+        user_id: TEST_IDS.userId,
+      })
+
+      expect(result.isError).toBe(true)
+    })
   })
 
   describe('acknowledgeLetter', () => {
@@ -693,6 +746,20 @@ describe('Layer 2: Skill tools', () => {
       expect(parsed.status).toBe('draft')
       expect(parsed.command_slug).toBe('nexus-test-skill')
     })
+
+    it('should return error on API failure', async () => {
+      vi.mocked(nexusPost).mockResolvedValue(mockApiError('Duplicate skill_id', 409))
+
+      const { skCreate } = await import('../tools/skills.js')
+      const result = await skCreate({
+        skill_id: 'nx-duplicate',
+        name: 'Duplicate Skill',
+        body: '# Dup',
+        user_id: TEST_IDS.userId,
+      })
+
+      expect(result.isError).toBe(true)
+    })
   })
 
   describe('skUpdate', () => {

package/src/__tests__/server.test.ts

@@ -78,9 +78,9 @@ describe('MCP Server: withIdentity wrapper', () => {
 })
 
 describe('MCP Server: Schema exports', () => {
-  const EXPECTED_TOOL_COUNT = 36
+  const EXPECTED_TOOL_COUNT = 38
 
-  it('should register exactly 36 tools in server.ts', () => {
+  it('should register exactly 38 tools in server.ts', () => {
     // Static analysis: count server.tool( calls in server.ts as a regression guard.
     // If you add or remove a tool, update EXPECTED_TOOL_COUNT above.
     const serverSource = readFileSync(
@@ -234,5 +234,17 @@ describe('MCP Server: Schema exports', () => {
     expect(typeof reviews.rvCreate).toBe('function')
     expect(typeof reviews.rvDecide).toBe('function')
     expect(typeof reviews.rvComment).toBe('function')
+
+    // list-tasks module (task_list)
+    const listTasks = await import('../tools/list-tasks.js')
+    expect(listTasks.listTasksSchema).toBeDefined()
+    expect(listTasks.listTasksSchema.project_id).toBeDefined()
+    expect(typeof listTasks.listTasks).toBe('function')
+
+    // list-documents module (doc_list)
+    const listDocuments = await import('../tools/list-documents.js')
+    expect(listDocuments.listDocumentsSchema).toBeDefined()
+    expect(listDocuments.listDocumentsSchema.project_id).toBeDefined()
+    expect(typeof listDocuments.listDocuments).toBe('function')
   })
 })