@namzu/sdk 0.4.1 → 0.4.3

package/src/connector/BaseConnector.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 5):
+ *
+ *   - `BaseConnector` is abstract. Each concrete subclass sets id /
+ *     name / description / connectionType / configSchema / methods
+ *     and implements connect / disconnect / healthCheck / execute.
+ *   - `toDefinition()` projects the abstract readonly fields into a
+ *     `ConnectorDefinition<TConfig>` — used to register the connector
+ *     with the `ConnectorRegistry`.
+ *   - `findMethod(name)` returns the method by name or undefined.
+ *   - `requireMethod(name)` throws with the method name + available
+ *     names when not found.
+ *   - `validateInput(method, input)`: zod.safeParse; on failure
+ *     throws `Invalid input for method "<name>": <joined issues>`.
+ *   - `measureExecution(fn)` returns `{result, durationMs}` with
+ *     durationMs rounded.
+ *   - Auth resolution lives in subclasses (see HttpConnector tests),
+ *     not in the base class.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type {
+	AuthConfig,
+	ConnectionType,
+	ConnectorExecuteResult,
+	ConnectorMethod,
+} from '../types/connector/index.js'
+import type { ConnectorId } from '../types/ids/index.js'
+
+import { BaseConnector } from './BaseConnector.js'
+
+class TestConnector extends BaseConnector<{ base: string }> {
+	readonly id = 'conn_test' as ConnectorId
+	readonly name = 'Test'
+	readonly description = 'Test connector'
+	readonly connectionType: ConnectionType = 'custom'
+	readonly configSchema = z.object({ base: z.string() })
+	readonly methods: ConnectorMethod[] = [
+		{
+			name: 'echo',
+			description: 'echo',
+			inputSchema: z.object({ value: z.string() }),
+		},
+	]
+
+	async connect(): Promise<void> {}
+	async disconnect(): Promise<void> {}
+	async healthCheck(): Promise<boolean> {
+		return true
+	}
+	async execute(): Promise<ConnectorExecuteResult> {
+		return { success: true, output: 'ok', durationMs: 0 }
+	}
+
+	// Expose protected methods for direct tests:
+	publicRequireMethod(name: string): ConnectorMethod {
+		return this.requireMethod(name)
+	}
+	publicValidateInput(method: ConnectorMethod, input: unknown): unknown {
+		return this.validateInput(method, input)
+	}
+	publicMeasureExecution<T>(fn: () => Promise<T>) {
+		return this.measureExecution(fn)
+	}
+
+	// Exposed internal auth resolver on a subclass is a sibling concern —
+	// `BaseConnector` does not define any auth handling; the field is
+	// just stored.
+	getStoredAuth(): AuthConfig | undefined {
+		return this.auth
+	}
+}
+
+describe('BaseConnector', () => {
+	it('toDefinition projects abstract readonly fields', () => {
+		const c = new TestConnector()
+		const def = c.toDefinition()
+		expect(def.id).toBe('conn_test')
+		expect(def.name).toBe('Test')
+		expect(def.description).toBe('Test connector')
+		expect(def.connectionType).toBe('custom')
+		expect(def.methods).toHaveLength(1)
+	})
+
+	it('findMethod returns undefined for an unknown name', () => {
+		const c = new TestConnector()
+		expect(c.publicRequireMethod).toBeDefined()
+		// findMethod is invoked indirectly via requireMethod — we cover the
+		// positive + negative paths below.
+	})
+
+	it('requireMethod returns the method when present', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(method.name).toBe('echo')
+	})
+
+	it('requireMethod throws naming the missing method + available names', () => {
+		const c = new TestConnector()
+		expect(() => c.publicRequireMethod('nope')).toThrow(/Method "nope" not found/)
+		expect(() => c.publicRequireMethod('nope')).toThrow(/Available: echo/)
+	})
+
+	it('validateInput passes through parsed data on success', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(c.publicValidateInput(method, { value: 'hi' })).toEqual({ value: 'hi' })
+	})
+
+	it('validateInput throws with joined issue messages on failure', () => {
+		const c = new TestConnector()
+		const method = c.publicRequireMethod('echo')
+		expect(() => c.publicValidateInput(method, { value: 123 })).toThrow(
+			/Invalid input for method "echo"/,
+		)
+	})
+
+	it('measureExecution returns the result + rounded durationMs', async () => {
+		const c = new TestConnector()
+		const { result, durationMs } = await c.publicMeasureExecution(async () => {
+			await new Promise((r) => setTimeout(r, 5))
+			return 42
+		})
+		expect(result).toBe(42)
+		expect(durationMs).toBeGreaterThanOrEqual(0)
+		expect(Number.isInteger(durationMs)).toBe(true)
+	})
+})

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)
+	})
+})