@namzu/sdk 0.4.2 → 0.4.4

package/src/connector/builtins/http.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `HttpConnector.connect` stores config + auth, strips trailing
+ *     slashes from baseUrl, merges default headers with auth-derived
+ *     headers.
+ *   - Auth resolution (http only — webhook has its own):
+ *     - `api_key` with `apiKey` + optional `headerName` (default
+ *       `X-API-Key`).
+ *     - `bearer` with `token` → `Authorization: Bearer <token>`.
+ *     - `basic` with `username` + `password` → base64 encoded.
+ *     - `none` / `oauth2` / `custom` → no headers.
+ *     - Missing required credential fields throw a typed error string.
+ *   - `disconnect` clears internal state.
+ *   - `healthCheck` HEAD-fetches baseUrl with a 5s timeout; returns
+ *     true iff `response.ok || response.status < 500`; false on any
+ *     thrown fetch (e.g. timeout abort).
+ *   - `execute("request", input)`:
+ *     - `requireMethod` + `validateInput` run.
+ *     - Builds URL from `baseUrl + path` + appends query params.
+ *     - Sends default+input headers; auto-sets `Content-Type:
+ *       application/json` when a body is present and no content-type
+ *       was passed.
+ *     - Parses response JSON when `content-type: application/json`,
+ *       else text.
+ *     - `success: true` iff status in [200, 400). Metadata includes
+ *       status + statusText.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { HttpConnector } from './http.js'
+
+function makeResponse(init: {
+	status?: number
+	statusText?: string
+	headers?: Record<string, string>
+	body?: unknown
+}) {
+	const headers = new Headers(init.headers ?? { 'content-type': 'application/json' })
+	return {
+		ok: (init.status ?? 200) < 400,
+		status: init.status ?? 200,
+		statusText: init.statusText ?? 'OK',
+		headers,
+		json: async () => init.body,
+		text: async () => String(init.body ?? ''),
+	}
+}
+
+describe('HttpConnector', () => {
+	let fetchMock: ReturnType<typeof vi.fn>
+
+	beforeEach(() => {
+		fetchMock = vi.fn()
+		global.fetch = fetchMock as unknown as typeof fetch
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	describe('connect + disconnect', () => {
+		it('strips trailing slashes from baseUrl', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com//', timeoutMs: 30_000 })
+			// Follow-up request lands on the cleaned URL:
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: { ok: true } }))
+			await c.execute('request', { method: 'GET', path: 'x' })
+			expect(fetchMock).toHaveBeenCalledWith('https://api.example.com/x', expect.any(Object))
+		})
+
+		it('disconnect clears internal state; execute after disconnect treats baseUrl as empty', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com', timeoutMs: 30_000 })
+			await c.disconnect()
+			expect(await c.healthCheck()).toBe(false)
+		})
+	})
+
+	describe('auth resolution', () => {
+		it('api_key default header name = X-API-Key', async () => {
+			const c = new HttpConnector()
+			await c.connect(
+				{ baseUrl: 'https://api.example.com' },
+				{ type: 'api_key', credentials: { apiKey: 'secret' } },
+			)
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', { method: 'GET', path: 'x' })
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers['X-API-Key']).toBe('secret')
+		})
+
+		it('api_key custom header name is honored', async () => {
+			const c = new HttpConnector()
+			await c.connect(
+				{ baseUrl: 'https://api.example.com' },
+				{ type: 'api_key', credentials: { apiKey: 'secret', headerName: 'X-Custom' } },
+			)
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', { method: 'GET', path: 'x' })
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers['X-Custom']).toBe('secret')
+		})
+
+		it('bearer sets Authorization: Bearer <token>', async () => {
+			const c = new HttpConnector()
+			await c.connect(
+				{ baseUrl: 'https://api.example.com' },
+				{ type: 'bearer', credentials: { token: 'tkn' } },
+			)
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', { method: 'GET', path: 'x' })
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers.Authorization).toBe('Bearer tkn')
+		})
+
+		it('basic encodes username:password as base64', async () => {
+			const c = new HttpConnector()
+			await c.connect(
+				{ baseUrl: 'https://api.example.com' },
+				{ type: 'basic', credentials: { username: 'alice', password: 'pw' } },
+			)
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', { method: 'GET', path: 'x' })
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers.Authorization).toBe(`Basic ${btoa('alice:pw')}`)
+		})
+
+		it('none / oauth2 / custom add no auth headers', async () => {
+			for (const type of ['none', 'oauth2', 'custom'] as const) {
+				const c = new HttpConnector()
+				await c.connect({ baseUrl: 'https://api.example.com' }, { type, credentials: {} })
+				fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+				await c.execute('request', { method: 'GET', path: 'x' })
+				const headers = fetchMock.mock.calls.at(-1)?.[1].headers as Record<string, string>
+				expect(headers.Authorization).toBeUndefined()
+				expect(headers['X-API-Key']).toBeUndefined()
+			}
+		})
+
+		it('api_key throws when apiKey is missing', async () => {
+			const c = new HttpConnector()
+			await expect(
+				c.connect({ baseUrl: 'https://api.example.com' }, { type: 'api_key', credentials: {} }),
+			).rejects.toThrow(/missing required credential "apiKey"/)
+		})
+
+		it('bearer throws when token is missing', async () => {
+			const c = new HttpConnector()
+			await expect(
+				c.connect({ baseUrl: 'https://api.example.com' }, { type: 'bearer', credentials: {} }),
+			).rejects.toThrow(/missing required credential "token"/)
+		})
+
+		it('basic throws when either username or password is missing', async () => {
+			const c = new HttpConnector()
+			await expect(
+				c.connect(
+					{ baseUrl: 'https://api.example.com' },
+					{ type: 'basic', credentials: { username: 'a' } },
+				),
+			).rejects.toThrow(/missing required credentials/)
+		})
+	})
+
+	describe('healthCheck', () => {
+		it('returns true for ok responses', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200 }))
+			expect(await c.healthCheck()).toBe(true)
+		})
+
+		it('returns true for 4xx (not-ok but < 500)', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 404 }))
+			expect(await c.healthCheck()).toBe(true)
+		})
+
+		it('returns false for 5xx', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 503 }))
+			expect(await c.healthCheck()).toBe(false)
+		})
+
+		it('returns false on thrown fetch', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockRejectedValueOnce(new Error('timeout'))
+			expect(await c.healthCheck()).toBe(false)
+		})
+
+		it('returns false when never connected', async () => {
+			const c = new HttpConnector()
+			expect(await c.healthCheck()).toBe(false)
+		})
+	})
+
+	describe('execute', () => {
+		it('returns success:true for 2xx + 3xx responses', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: { ok: 1 } }))
+			const result = await c.execute('request', { method: 'GET', path: 'thing' })
+			expect(result.success).toBe(true)
+			expect(result.output).toMatchObject({ status: 200 })
+		})
+
+		it('returns success:false for 4xx / 5xx responses', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 500, body: { err: 1 } }))
+			const result = await c.execute('request', { method: 'GET', path: 'thing' })
+			expect(result.success).toBe(false)
+			expect(result.metadata).toMatchObject({ status: 500 })
+		})
+
+		it('sets Content-Type: application/json when body is set and none provided', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', {
+				method: 'POST',
+				path: 'thing',
+				body: { k: 'v' },
+			})
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers['Content-Type']).toBe('application/json')
+		})
+
+		it('preserves caller-supplied Content-Type', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: '' }))
+			await c.execute('request', {
+				method: 'POST',
+				path: 'thing',
+				body: 'raw',
+				headers: { 'Content-Type': 'text/plain' },
+			})
+			const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+			expect(headers['Content-Type']).toBe('text/plain')
+		})
+
+		it('appends query params to the URL', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+			await c.execute('request', {
+				method: 'GET',
+				path: 'thing',
+				query: { a: '1', b: '2' },
+			})
+			expect(fetchMock.mock.calls[0]?.[0]).toBe('https://api.example.com/thing?a=1&b=2')
+		})
+
+		it('parses JSON response when content-type is json', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(
+				makeResponse({
+					status: 200,
+					headers: { 'content-type': 'application/json' },
+					body: { ok: 1 },
+				}),
+			)
+			const result = await c.execute('request', { method: 'GET', path: 'x' })
+			expect((result.output as { body: unknown }).body).toEqual({ ok: 1 })
+		})
+
+		it('returns text body for non-JSON content-type', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			fetchMock.mockResolvedValueOnce(
+				makeResponse({ status: 200, headers: { 'content-type': 'text/plain' }, body: 'hello' }),
+			)
+			const result = await c.execute('request', { method: 'GET', path: 'x' })
+			expect((result.output as { body: unknown }).body).toBe('hello')
+		})
+
+		it('throws on invalid input (unknown method)', async () => {
+			const c = new HttpConnector()
+			await c.connect({ baseUrl: 'https://api.example.com' })
+			await expect(c.execute('not-a-method', {})).rejects.toThrow(/not found/)
+		})
+	})
+})

package/src/connector/builtins/webhook.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `WebhookConnector.connect` stores config + auth; merges default
+ *     headers; sets `Authorization: Bearer <token>` iff auth is
+ *     bearer with a token (other auth types are ignored here).
+ *   - `disconnect` clears state.
+ *   - `healthCheck` HEAD-fetches the configured url; true iff
+ *     `ok || status < 500`; false on thrown fetch or empty url.
+ *   - `execute("send", input)`:
+ *     - Validates input via zod.
+ *     - Posts JSON to `input.url ?? config.url`.
+ *     - Always sets `Content-Type: application/json`.
+ *     - When `config.secret` is set, computes HMAC-SHA256 over the
+ *       stringified payload and sets `X-Webhook-Signature: sha256=<hex>`.
+ *     - `success: true` iff `status in [200, 400)`.
+ *     - `metadata.deliveredAt` is a recent timestamp.
+ */
+
+import { createHmac } from 'node:crypto'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { WebhookConnector } from './webhook.js'
+
+function makeResponse(init: {
+	status?: number
+	headers?: Record<string, string>
+	body?: unknown
+}) {
+	const headers = new Headers(init.headers ?? { 'content-type': 'application/json' })
+	return {
+		ok: (init.status ?? 200) < 400,
+		status: init.status ?? 200,
+		statusText: 'OK',
+		headers,
+		json: async () => init.body,
+		text: async () => String(init.body ?? ''),
+	}
+}
+
+describe('WebhookConnector', () => {
+	let fetchMock: ReturnType<typeof vi.fn>
+
+	beforeEach(() => {
+		fetchMock = vi.fn()
+		global.fetch = fetchMock as unknown as typeof fetch
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+	})
+
+	it('connect + disconnect round-trip state', async () => {
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com/x' })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200 }))
+		expect(await c.healthCheck()).toBe(true)
+		await c.disconnect()
+		expect(await c.healthCheck()).toBe(false)
+	})
+
+	it('bearer auth sets Authorization header on send', async () => {
+		const c = new WebhookConnector()
+		await c.connect(
+			{ url: 'https://hook.example.com' },
+			{ type: 'bearer', credentials: { token: 'tkn' } },
+		)
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		await c.execute('send', { payload: {} })
+		const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+		expect(headers.Authorization).toBe('Bearer tkn')
+	})
+
+	it('send posts JSON to the configured URL', async () => {
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com' })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		await c.execute('send', { payload: { k: 'v' } })
+		expect(fetchMock).toHaveBeenCalledWith(
+			'https://hook.example.com',
+			expect.objectContaining({
+				method: 'POST',
+				body: JSON.stringify({ k: 'v' }),
+			}),
+		)
+	})
+
+	it('input.url overrides the configured URL', async () => {
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://default.example.com' })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		await c.execute('send', { payload: {}, url: 'https://override.example.com' })
+		expect(fetchMock).toHaveBeenCalledWith('https://override.example.com', expect.any(Object))
+	})
+
+	it('includes HMAC signature when secret is configured', async () => {
+		const secret = 's3cret'
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com', secret })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		await c.execute('send', { payload: { k: 'v' } })
+		const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+		const expected = `sha256=${createHmac('sha256', secret)
+			.update(JSON.stringify({ k: 'v' }))
+			.digest('hex')}`
+		expect(headers['X-Webhook-Signature']).toBe(expected)
+	})
+
+	it('omits HMAC signature when no secret is configured', async () => {
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com' })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		await c.execute('send', { payload: {} })
+		const headers = fetchMock.mock.calls[0]?.[1].headers as Record<string, string>
+		expect(headers['X-Webhook-Signature']).toBeUndefined()
+	})
+
+	it('success: true for 2xx; false for 4xx/5xx', async () => {
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com' })
+
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		expect((await c.execute('send', { payload: {} })).success).toBe(true)
+
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 500, body: 'err' }))
+		expect((await c.execute('send', { payload: {} })).success).toBe(false)
+	})
+
+	it('metadata.deliveredAt is a recent timestamp', async () => {
+		const before = Date.now()
+		const c = new WebhookConnector()
+		await c.connect({ url: 'https://hook.example.com' })
+		fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: 'ok' }))
+		const result = await c.execute('send', { payload: {} })
+		const delivered = (result.metadata as { deliveredAt: number }).deliveredAt
+		expect(delivered).toBeGreaterThanOrEqual(before)
+	})
+})

package/src/connector/execution/factory.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `ExecutionContextFactory.create(config)` dispatches by
+ *     `config.environment`:
+ *     - 'local' → `LocalExecutionContext` with the forwarded fields.
+ *     - 'remote' → `RemoteExecutionContext` with target + capabilities.
+ *     - 'hybrid' → `HybridExecutionContext` with local + remotes +
+ *       routingStrategy.
+ *   - Unknown environment hits the exhaustive throw (unreachable via
+ *     types).
+ *   - The static `createLocal` / `createRemote` / `createHybrid`
+ *     helpers directly return the appropriate subclass.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { LocalExecutionContext } from '../../execution/local.js'
+import { ExecutionContextFactory } from './factory.js'
+import { HybridExecutionContext } from './hybrid.js'
+import { RemoteExecutionContext } from './remote.js'
+
+describe('ExecutionContextFactory', () => {
+	it('creates a LocalExecutionContext for environment: local', () => {
+		const ctx = ExecutionContextFactory.create({
+			id: 'c1',
+			environment: 'local',
+			cwd: '/tmp',
+			fsAccess: true,
+		})
+		expect(ctx).toBeInstanceOf(LocalExecutionContext)
+		expect(ctx.id).toBe('c1')
+		expect(ctx.environment).toBe('local')
+	})
+
+	it('creates a RemoteExecutionContext for environment: remote', () => {
+		const ctx = ExecutionContextFactory.create({
+			id: 'c2',
+			environment: 'remote',
+			target: { type: 'ssh', host: 'server.example.com' },
+		})
+		expect(ctx).toBeInstanceOf(RemoteExecutionContext)
+		expect(ctx.environment).toBe('remote')
+	})
+
+	it('creates a HybridExecutionContext for environment: hybrid', () => {
+		const ctx = ExecutionContextFactory.create({
+			id: 'c3',
+			environment: 'hybrid',
+			local: { cwd: '/tmp', fsAccess: true },
+			remotes: [{ type: 'ssh', host: 'r1.example.com' }],
+		})
+		expect(ctx).toBeInstanceOf(HybridExecutionContext)
+		expect(ctx.environment).toBe('hybrid')
+	})
+
+	it('createLocal / createRemote / createHybrid return the right subclass', () => {
+		expect(
+			ExecutionContextFactory.createLocal({ id: 'x', cwd: '/tmp', fsAccess: true }),
+		).toBeInstanceOf(LocalExecutionContext)
+		expect(
+			ExecutionContextFactory.createRemote({
+				id: 'y',
+				target: { type: 'ssh', host: 'h' },
+			}),
+		).toBeInstanceOf(RemoteExecutionContext)
+		expect(
+			ExecutionContextFactory.createHybrid({
+				id: 'z',
+				local: { cwd: '/tmp', fsAccess: true },
+				remotes: [],
+			}),
+		).toBeInstanceOf(HybridExecutionContext)
+	})
+})

package/src/connector/execution/remote.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `RemoteExecutionContext` starts disconnected; `connect()` flips
+ *     `connected = true` and emits `remote_connected`.
+ *   - `disconnect()` is idempotent — the second call emits nothing
+ *     and returns quietly.
+ *   - `getTarget()` returns a COPY (mutating the returned object does
+ *     not mutate internal state).
+ *   - `initialize()` succeeds for supported target types; emits
+ *     `context_initialized` + `context_ready`.
+ *   - `isReady()` reflects post-initialize state.
+ *   - `environment` is 'remote'.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { RemoteTarget } from '../../types/connector/index.js'
+
+import { RemoteExecutionContext } from './remote.js'
+
+const target: RemoteTarget = { type: 'ssh', host: 'server.example.com', port: 22 }
+
+describe('RemoteExecutionContext', () => {
+	it('environment is remote', () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		expect(r.environment).toBe('remote')
+	})
+
+	it('starts disconnected; connect flips to connected', async () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		expect(r.isConnected()).toBe(false)
+		await r.connect()
+		expect(r.isConnected()).toBe(true)
+	})
+
+	it('disconnect when not connected is a no-op', async () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		await r.disconnect()
+		expect(r.isConnected()).toBe(false)
+	})
+
+	it('disconnect flips back to disconnected', async () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		await r.connect()
+		await r.disconnect()
+		expect(r.isConnected()).toBe(false)
+	})
+
+	it('getTarget returns a copy (mutation does not leak)', () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		const copy = r.getTarget()
+		copy.host = 'mutated.example.com'
+		expect(r.getTarget().host).toBe('server.example.com')
+	})
+
+	it('initialize flips isReady to true', async () => {
+		const r = new RemoteExecutionContext({ id: 'r1', target })
+		expect(r.isReady()).toBe(false)
+		await r.initialize()
+		expect(r.isReady()).toBe(true)
+	})
+})