@mhingston5/conduit 1.0.0

package/tests/__snapshots__/assets.test.ts.snap

@@ -0,0 +1,97 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Asset Integrity (Golden Tests) > should match Isolate SDK snapshot 1`] = `
+"// Generated SDK for isolated-vm
+const __allowedTools = ["test__*","github__*"];
+const tools = {
+  test: {
+    async hello(args) {
+      const resStr = await __callTool("test__hello", JSON.stringify(args || {}));
+      return JSON.parse(resStr);
+    },
+  },
+  github: {
+    async create_issue(args) {
+      const resStr = await __callTool("github__create_issue", JSON.stringify(args || {}));
+      return JSON.parse(resStr);
+    },
+  },
+  async $raw(name, args) {
+    const normalized = name.replace(/\\./g, '__');
+    if (__allowedTools) {
+      const allowed = __allowedTools.some(p => {
+        if (p.endsWith('__*')) return normalized.startsWith(p.slice(0, -1));
+        return normalized === p;
+      });
+      if (!allowed) throw new Error(\`Tool \${name} is not in the allowlist\`);
+    }
+    const resStr = await __callTool(normalized, JSON.stringify(args || {}));
+    return JSON.parse(resStr);
+  },
+};"
+`;
+
+exports[`Asset Integrity (Golden Tests) > should match Python SDK snapshot 1`] = `
+"# Generated SDK - Do not edit
+_allowed_tools = ["test__*","github__*"]
+
+class _ToolNamespace:
+    def __init__(self, methods):
+        for name, fn in methods.items():
+            setattr(self, name, fn)
+
+class _Tools:
+    def __init__(self):
+        self.test = _ToolNamespace({
+            "hello": lambda args, n="test__hello": _internal_call_tool(n, args)
+        })
+        self.github = _ToolNamespace({
+            "create_issue": lambda args, n="github__create_issue": _internal_call_tool(n, args)
+        })
+
+    async def raw(self, name, args):
+        """Call a tool by its full name (escape hatch for dynamic/unknown tools)"""
+        normalized = name.replace(".", "__")
+        if _allowed_tools is not None:
+            allowed = any(
+                normalized.startswith(p[:-1]) if p.endswith("__*") else normalized == p
+                for p in _allowed_tools
+            )
+            if not allowed:
+                raise PermissionError(f"Tool {name} is not in the allowlist")
+        return await _internal_call_tool(normalized, args)
+
+tools = _Tools()"
+`;
+
+exports[`Asset Integrity (Golden Tests) > should match TypeScript SDK snapshot 1`] = `
+"// Generated SDK - Do not edit
+const __allowedTools = ["test__*","github__*"];
+const tools = {
+  test: {
+    /** Returns a greeting */
+    async hello(args) {
+      return await __internalCallTool("test__hello", args);
+    },
+  },
+  github: {
+    /** Creates a GitHub issue */
+    async create_issue(args) {
+      return await __internalCallTool("github__create_issue", args);
+    },
+  },
+  /** Call a tool by its full name (escape hatch for dynamic/unknown tools) */
+  async $raw(name, args) {
+    const normalized = name.replace(/\\./g, '__');
+    if (__allowedTools) {
+      const allowed = __allowedTools.some(p => {
+        if (p.endsWith('__*')) return normalized.startsWith(p.slice(0, -1));
+        return normalized === p;
+      });
+      if (!allowed) throw new Error(\`Tool \${name} is not in the allowlist\`);
+    }
+    return await __internalCallTool(normalized, args);
+  },
+};
+(globalThis as any).tools = tools;"
+`;

package/tests/assets.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { SDKGenerator, toToolBinding } from '../src/sdk/index.js';
+import { ToolSchema } from '../src/gateway/schema.cache.js';
+
+describe('Asset Integrity (Golden Tests)', () => {
+    const generator = new SDKGenerator();
+
+    const sampleTools: ToolSchema[] = [
+        {
+            name: 'test__hello',
+            description: 'Returns a greeting',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' }
+                },
+                required: ['name']
+            }
+        },
+        {
+            name: 'github__create_issue',
+            description: 'Creates a GitHub issue',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: { type: 'string' },
+                    body: { type: 'string' }
+                },
+                required: ['title']
+            }
+        }
+    ];
+
+    const bindings = sampleTools.map(t => toToolBinding(t.name, t.inputSchema, t.description));
+
+    it('should match TypeScript SDK snapshot', () => {
+        const sdk = generator.generateTypeScript(bindings, ['test__*', 'github__*']);
+        expect(sdk).toMatchSnapshot();
+    });
+
+    it('should match Python SDK snapshot', () => {
+        const sdk = generator.generatePython(bindings, ['test__*', 'github__*']);
+        expect(sdk).toMatchSnapshot();
+    });
+
+    it('should match Isolate SDK snapshot', () => {
+        const sdk = generator.generateIsolateSDK(bindings, ['test__*', 'github__*']);
+        expect(sdk).toMatchSnapshot();
+    });
+});

package/tests/auth.service.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AuthService } from '../src/gateway/auth.service.js';
+import pino from 'pino';
+import axios from 'axios';
+
+vi.mock('axios');
+const logger = pino({ level: 'silent' });
+
+describe('AuthService', () => {
+    let authService: AuthService;
+
+    beforeEach(() => {
+        authService = new AuthService(logger);
+        vi.clearAllMocks();
+    });
+
+    it('should return API key header', async () => {
+        const headers = await authService.getAuthHeaders({
+            type: 'apiKey',
+            apiKey: 'test-key',
+        });
+        expect(headers['X-API-Key']).toBe('test-key');
+    });
+
+    it('should refresh OAuth2 token when expired', async () => {
+        const creds: any = {
+            type: 'oauth2',
+            oauth2: {
+                clientId: 'id',
+                clientSecret: 'secret',
+                tokenUrl: 'http://token',
+                refreshToken: 'refresh',
+                expiresAt: Date.now() - 1000, // Expired
+            },
+        };
+
+        (axios.post as any).mockResolvedValue({
+            data: {
+                access_token: 'new-access',
+                expires_in: 3600,
+            },
+        });
+
+        const headers = await authService.getAuthHeaders(creds);
+        expect(headers['Authorization']).toBe('Bearer new-access');
+        expect(axios.post).toHaveBeenCalled();
+    });
+
+    it('should reuse OAuth2 token if not expired', async () => {
+        // First call - will trigger refresh
+        const creds: any = {
+            type: 'oauth2',
+            oauth2: {
+                clientId: 'id',
+                clientSecret: 'secret',
+                tokenUrl: 'http://token',
+                refreshToken: 'refresh',
+            },
+        };
+
+        (axios.post as any).mockResolvedValue({
+            data: {
+                access_token: 'cached-access',
+                expires_in: 3600,
+            },
+        });
+
+        // First call fetches the token
+        const headers1 = await authService.getAuthHeaders(creds);
+        expect(headers1['Authorization']).toBe('Bearer cached-access');
+        expect(axios.post).toHaveBeenCalledTimes(1);
+
+        // Second call should reuse cached token (no additional post)
+        const headers2 = await authService.getAuthHeaders(creds);
+        expect(headers2['Authorization']).toBe('Bearer cached-access');
+        expect(axios.post).toHaveBeenCalledTimes(1); // Still 1, not 2
+    });
+});

package/tests/code-mode-lite-execution.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ExecutionService } from '../src/core/execution.service.js';
+import { ExecutionContext } from '../src/core/execution.context.js';
+import { GatewayService } from '../src/gateway/gateway.service.js';
+import { PolicyService } from '../src/core/policy.service.js';
+import { SDKGenerator } from '../src/sdk/sdk-generator.js';
+import { createLogger } from '../src/core/logger.js';
+import { ConfigService } from '../src/core/config.service.js';
+
+describe('ExecutionService (Code Mode Lite)', () => {
+    let executionService: ExecutionService;
+    let gatewayService: any;
+    let logger: any;
+    let executorRegistry: any;
+
+    beforeEach(() => {
+        logger = createLogger(new ConfigService());
+
+        gatewayService = {
+            listToolPackages: vi.fn(),
+            listToolStubs: vi.fn(),
+            discoverTools: vi.fn(), // Should NOT be called
+        } as any;
+
+        const policyService = new PolicyService();
+
+        const securityService = {
+            validateCode: vi.fn().mockReturnValue({ valid: true }),
+            createSession: vi.fn().mockReturnValue('token'),
+            invalidateSession: vi.fn(),
+        } as any;
+
+        executorRegistry = {
+            has: vi.fn().mockReturnValue(true),
+            get: vi.fn().mockReturnValue({
+                execute: vi.fn().mockResolvedValue({ stdout: 'ok', stderr: '', exitCode: 0 })
+            }),
+            shutdownAll: vi.fn(),
+        };
+
+        executionService = new ExecutionService(
+            logger,
+            { maxMemoryMb: 128, timeoutMs: 1000 } as any,
+            gatewayService,
+            securityService,
+            executorRegistry
+        );
+        executionService.ipcAddress = 'test-sock';
+    });
+
+    it('should use listToolPackages and listToolStubs instead of discoverTools for TypeScript execution', async () => {
+        const context = new ExecutionContext({ logger });
+
+        gatewayService.listToolPackages.mockResolvedValue([
+            { id: 'pkg1' }
+        ]);
+        gatewayService.listToolStubs.mockResolvedValue([
+            { id: 'pkg1__tool1', name: 'tool1', description: 'desc' }
+        ]);
+
+        await executionService.executeTypeScript('console.log("hi")', {}, context);
+
+        expect(gatewayService.discoverTools).not.toHaveBeenCalled();
+        expect(gatewayService.listToolPackages).toHaveBeenCalled();
+        expect(gatewayService.listToolStubs).toHaveBeenCalledWith('pkg1', context);
+    });
+
+    it('should use listToolPackages and listToolStubs for Python execution', async () => {
+        const context = new ExecutionContext({ logger });
+
+        gatewayService.listToolPackages.mockResolvedValue([
+            { id: 'pkg1' }
+        ]);
+        gatewayService.listToolStubs.mockResolvedValue([
+            { id: 'pkg1__tool1', name: 'tool1' }
+        ]);
+
+        await executionService.executePython('print("hi")', {}, context);
+
+        expect(gatewayService.discoverTools).not.toHaveBeenCalled();
+        expect(gatewayService.listToolPackages).toHaveBeenCalled();
+        expect(gatewayService.listToolStubs).toHaveBeenCalledWith('pkg1', context);
+    });
+});

package/tests/code-mode-lite-gateway.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { GatewayService } from '../src/gateway/gateway.service.js';
+import { ExecutionContext } from '../src/core/execution.context.js';
+import { UpstreamInfo } from '../src/gateway/upstream.client.js';
+import { createLogger } from '../src/core/logger.js';
+import { ConfigService } from '../src/core/config.service.js';
+import { IUrlValidator } from '../src/core/interfaces/url.validator.interface.js';
+import { PolicyService } from '../src/core/policy.service.js';
+
+class MockUrlValidator implements IUrlValidator {
+    async validateUrl(url: string) { return { valid: true }; }
+}
+
+describe('GatewayService (Code Mode Lite)', () => {
+    let gateway: GatewayService;
+    let logger: any;
+    let urlValidator: IUrlValidator;
+    let policyService: PolicyService;
+
+    const mockUpstream: UpstreamInfo = {
+        id: 'mock-upstream',
+        type: 'http',
+        url: 'http://localhost:3000/mcp'
+    };
+
+    beforeEach(() => {
+        logger = createLogger(new ConfigService());
+        urlValidator = new MockUrlValidator();
+        policyService = new PolicyService();
+        gateway = new GatewayService(logger, urlValidator, policyService);
+        gateway.registerUpstream(mockUpstream);
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    describe('listToolPackages', () => {
+        it('should return registered tool packages', async () => {
+            const packages = await gateway.listToolPackages();
+            expect(packages).toHaveLength(1);
+            expect(packages[0].id).toBe('mock-upstream');
+            expect(packages[0].description).toContain('Upstream mock-upstream');
+        });
+    });
+
+    describe('listToolStubs', () => {
+        it('should list tool stubs from upstream', async () => {
+            // Mock the upstream client call
+            const client = (gateway as any).clients.get('mock-upstream');
+            vi.spyOn(client, 'call').mockResolvedValue({
+                jsonrpc: '2.0',
+                id: 1,
+                result: {
+                    tools: [
+                        { name: 'op1', description: 'Operation 1', inputSchema: {} },
+                        { name: 'op2', description: 'Operation 2', inputSchema: {} }
+                    ]
+                }
+            });
+
+            const context = new ExecutionContext({ logger });
+            const stubs = await gateway.listToolStubs('mock-upstream', context);
+
+            expect(stubs).toHaveLength(2);
+            expect(stubs[0]).toMatchObject({
+                id: 'mock-upstream__op1',
+                name: 'op1',
+                description: 'Operation 1'
+            });
+            expect(stubs[1]).toMatchObject({
+                id: 'mock-upstream__op2',
+                name: 'op2',
+                description: 'Operation 2'
+            });
+        });
+
+        it('should filter stubs based on allowlist', async () => {
+            const client = (gateway as any).clients.get('mock-upstream');
+            vi.spyOn(client, 'call').mockResolvedValue({
+                jsonrpc: '2.0',
+                id: 1,
+                result: {
+                    tools: [
+                        { name: 'allowed', description: 'Allowed Tool', inputSchema: {} },
+                        { name: 'blocked', description: 'Blocked Tool', inputSchema: {} }
+                    ]
+                }
+            });
+
+            const context = new ExecutionContext({ logger });
+            // PolicyService expects dot notation for allowlist patterns
+            context.allowedTools = ['mock-upstream.allowed'];
+
+            const stubs = await gateway.listToolStubs('mock-upstream', context);
+            expect(stubs).toHaveLength(1);
+            expect(stubs[0].name).toBe('allowed');
+        });
+    });
+
+    describe('getToolSchema', () => {
+        it('should return schema for specific tool', async () => {
+            const client = (gateway as any).clients.get('mock-upstream');
+            vi.spyOn(client, 'call').mockResolvedValue({
+                jsonrpc: '2.0',
+                id: 1,
+                result: {
+                    tools: [
+                        { name: 'target', description: 'Target Tool', inputSchema: { type: 'object' } }
+                    ]
+                }
+            });
+
+            const context = new ExecutionContext({ logger });
+            // First call triggers discovery (lazy load simulation)
+            const schema = await gateway.getToolSchema('mock-upstream__target', context);
+
+            expect(schema).not.toBeNull();
+            expect(schema?.name).toBe('mock-upstream__target'); // Namespaced
+            expect(schema?.description).toBe('Target Tool');
+        });
+
+        it('should block access if not in allowlist', async () => {
+            const context = new ExecutionContext({ logger });
+            context.allowedTools = ['other-tool'];
+
+            try {
+                await gateway.getToolSchema('mock-upstream__target', context);
+                expect.fail('Should have thrown error');
+            } catch (err: any) {
+                expect(err.message).toContain('forbidden by allowlist');
+            }
+        });
+
+        it('should return null if tool does not exist', async () => {
+            const client = (gateway as any).clients.get('mock-upstream');
+            vi.spyOn(client, 'call').mockResolvedValue({
+                jsonrpc: '2.0',
+                id: 1,
+                result: {
+                    tools: []
+                }
+            });
+
+            const context = new ExecutionContext({ logger });
+            const schema = await gateway.getToolSchema('mock-upstream__nonexistent', context);
+            expect(schema).toBeNull();
+        });
+    });
+});

package/tests/concurrency.service.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { ConcurrencyService } from '../src/core/concurrency.service.js';
+import pino from 'pino';
+
+const logger = pino({ level: 'silent' });
+
+describe('ConcurrencyService', () => {
+    it('should limit concurrent tasks', async () => {
+        const service = new ConcurrencyService(logger, { maxConcurrent: 2 });
+        let active = 0;
+        let maxSeen = 0;
+
+        const task = async () => {
+            active++;
+            maxSeen = Math.max(maxSeen, active);
+            await new Promise(resolve => setTimeout(resolve, 10));
+            active--;
+        };
+
+        await Promise.all([
+            service.run(task),
+            service.run(task),
+            service.run(task),
+            service.run(task),
+        ]);
+
+        expect(maxSeen).toBe(2);
+    });
+
+    it('should track stats correctly', async () => {
+        const service = new ConcurrencyService(logger, { maxConcurrent: 1 });
+
+        const task1 = service.run(async () => {
+            await new Promise(resolve => setTimeout(resolve, 50));
+        });
+
+        const task2 = service.run(async () => {
+            await new Promise(resolve => setTimeout(resolve, 50));
+        });
+
+        // At this point, task1 is active, task2 is pending
+        expect(service.stats.activeCount).toBe(1);
+        expect(service.stats.pendingCount).toBe(1);
+
+        await Promise.all([task1, task2]);
+
+        expect(service.stats.activeCount).toBe(0);
+        expect(service.stats.pendingCount).toBe(0);
+    });
+});

package/tests/concurrency.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ConcurrencyService } from '../src/core/concurrency.service.js';
+import pino from 'pino';
+
+const logger = pino({ level: 'silent' });
+
+describe('ConcurrencyService', () => {
+    it('should limit concurrent executions', async () => {
+        const service = new ConcurrencyService(logger, { maxConcurrent: 2 });
+        let activeCount = 0;
+        let maxActive = 0;
+
+        const tasks = Array.from({ length: 5 }, async (_, i) => {
+            return service.run(async () => {
+                activeCount++;
+                maxActive = Math.max(maxActive, activeCount);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                activeCount--;
+            });
+        });
+
+        await Promise.all(tasks);
+
+        expect(maxActive).toBe(2);
+    });
+
+    it('should handle errors without stucking', async () => {
+        const service = new ConcurrencyService(logger, { maxConcurrent: 1 });
+
+        await expect(service.run(async () => {
+            throw new Error('fail');
+        })).rejects.toThrow('fail');
+
+        // Should still be able to run next task
+        let ran = false;
+        await service.run(async () => {
+            ran = true;
+        });
+        expect(ran).toBe(true);
+    });
+});

package/tests/config.service.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ConfigService } from '../src/core/config.service.js';
+import fs from 'fs';
+import path from 'path';
+
+describe('ConfigService', () => {
+    beforeEach(() => {
+        vi.stubEnv('PORT', '4000');
+        vi.stubEnv('NODE_ENV', 'test');
+    });
+
+    it('should load config from environment variables', () => {
+        const configService = new ConfigService();
+        expect(configService.get('port')).toBe(4000);
+        expect(configService.get('nodeEnv')).toBe('test');
+    });
+
+    it('should use default values when env vars are missing', () => {
+        vi.stubEnv('PORT', '');
+        const configService = new ConfigService();
+        // Since port has a default('3000'), it should be 3000
+    });
+
+    it('should prioritize overrides over env vars', () => {
+        const configService = new ConfigService({ port: 5000 as any });
+        expect(configService.get('port')).toBe(5000);
+    });
+
+    it('should throw error on invalid configuration', () => {
+        vi.stubEnv('NODE_ENV', 'invalid');
+        expect(() => new ConfigService()).toThrow(/Invalid configuration/);
+    });
+
+    it('should substitute env vars in config file', () => {
+        const existsSpy = vi.spyOn(fs, 'existsSync').mockImplementation((p: any) => p.endsWith('conduit.test.yaml'));
+        const readSpy = vi.spyOn(fs, 'readFileSync').mockReturnValue("port: ${TEST_PORT}\nmetricsUrl: ${TEST_URL:-http://default}");
+
+        vi.stubEnv('CONFIG_FILE', 'conduit.test.yaml');
+        vi.stubEnv('TEST_PORT', '6000');
+        vi.stubEnv('TEST_URL', 'http://overridden');
+
+        // Ensure env var doesn't override file config
+        delete process.env.PORT;
+
+        const configService = new ConfigService();
+        expect(configService.get('port')).toBe(6000);
+        expect(configService.get('metricsUrl')).toBe('http://overridden');
+
+        existsSpy.mockRestore();
+        readSpy.mockRestore();
+    });
+
+    it('should use default values in substitution', () => {
+        const existsSpy = vi.spyOn(fs, 'existsSync').mockImplementation((p: any) => p.endsWith('conduit.test.yaml'));
+        const readSpy = vi.spyOn(fs, 'readFileSync').mockReturnValue("port: ${TEST_PORT:-7000}");
+
+        vi.stubEnv('CONFIG_FILE', 'conduit.test.yaml');
+        vi.stubEnv('TEST_PORT', '');
+        delete process.env.TEST_PORT;
+
+        // Ensure env var doesn't override file config
+        delete process.env.PORT;
+
+        const configService = new ConfigService();
+        expect(configService.get('port')).toBe(7000);
+
+        existsSpy.mockRestore();
+        readSpy.mockRestore();
+    });
+});

package/tests/contract.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import { GatewayService } from '../src/gateway/gateway.service.js';
+import { ExecutionContext } from '../src/core/execution.context.js';
+import { startReferenceMCP } from './reference_mcp.js';
+import pino from 'pino';
+
+const logger = pino({ level: 'silent' });
+
+describe('Contract Test: Conduit vs Reference MCP', () => {
+    let gateway: GatewayService;
+    let context: ExecutionContext;
+    let refServer: any;
+    const REF_PORT = 4567;
+
+    beforeAll(async () => {
+        refServer = await startReferenceMCP(REF_PORT);
+        const securityService = {
+            validateUrl: vi.fn().mockReturnValue({ valid: true }),
+        } as any;
+        gateway = new GatewayService(logger, securityService);
+        context = new ExecutionContext({ logger });
+
+        gateway.registerUpstream({
+            id: 'ref',
+            url: `http://localhost:${REF_PORT}`,
+        });
+    });
+
+    afterAll(async () => {
+        await refServer.close();
+    });
+
+    it('should successfully discover tools from reference MCP', async () => {
+        const tools = await gateway.discoverTools(context);
+        expect(tools).toHaveLength(1);
+        expect(tools[0].name).toBe('ref__echo');
+    });
+
+    it('should successfully call tool on reference MCP', async () => {
+        const response = await gateway.callTool('ref__echo', { msg: 'hello' }, context);
+        expect(response.result.content[0].text).toContain('{"msg":"hello"}');
+    });
+});