@namzu/sdk 0.4.2 → 0.4.4

package/src/registry/Registry.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `register(id, item)` silently overwrites an existing entry —
+ *     NO duplicate-error is thrown (Codex #1 verified the design
+ *     §2.3 "typed DuplicateRegistrationError" claim was fiction).
+ *   - `get(id)` returns `undefined` for an unknown id (NOT a typed
+ *     error). `getAll`, `listIds`, `has`, `size` reflect the current
+ *     `Map` state; iteration order follows insertion order.
+ *   - `unregister(id)` returns true if the entry existed (and was
+ *     deleted), false otherwise.
+ *   - `clear()` empties the map.
+ *   - The generic `Registry<T>` has no component name, no logger, no
+ *     lifecycle. All enrichment (logs, idField inference, lifecycle)
+ *     happens in `ManagedRegistry`, not here.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { Registry } from './Registry.js'
+
+interface Item {
+	id: string
+	value: number
+}
+
+describe('Registry', () => {
+	it('register + get + has roundtrip', () => {
+		const r = new Registry<Item>()
+		const a: Item = { id: 'a', value: 1 }
+		r.register('a', a)
+		expect(r.get('a')).toBe(a)
+		expect(r.has('a')).toBe(true)
+		expect(r.get('b')).toBeUndefined()
+		expect(r.has('b')).toBe(false)
+	})
+
+	it('register silently overwrites an existing key', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		r.register('a', { id: 'a', value: 2 })
+		expect(r.get('a')?.value).toBe(2)
+		expect(r.size()).toBe(1)
+	})
+
+	it('listIds reflects insertion order', () => {
+		const r = new Registry<Item>()
+		r.register('x', { id: 'x', value: 1 })
+		r.register('y', { id: 'y', value: 2 })
+		r.register('z', { id: 'z', value: 3 })
+		expect(r.listIds()).toEqual(['x', 'y', 'z'])
+	})
+
+	it('getAll returns every item in insertion order', () => {
+		const r = new Registry<Item>()
+		const items = [
+			{ id: 'a', value: 1 },
+			{ id: 'b', value: 2 },
+		]
+		for (const item of items) r.register(item.id, item)
+		expect(r.getAll()).toEqual(items)
+	})
+
+	it('unregister returns true iff the key existed', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		expect(r.unregister('a')).toBe(true)
+		expect(r.unregister('a')).toBe(false)
+		expect(r.get('a')).toBeUndefined()
+	})
+
+	it('clear empties the map', () => {
+		const r = new Registry<Item>()
+		r.register('a', { id: 'a', value: 1 })
+		r.register('b', { id: 'b', value: 2 })
+		r.clear()
+		expect(r.size()).toBe(0)
+		expect(r.getAll()).toEqual([])
+	})
+
+	it('size matches the map size', () => {
+		const r = new Registry<Item>()
+		expect(r.size()).toBe(0)
+		r.register('a', { id: 'a', value: 1 })
+		expect(r.size()).toBe(1)
+		r.register('a', { id: 'a', value: 2 }) // overwrite
+		expect(r.size()).toBe(1)
+		r.register('b', { id: 'b', value: 3 })
+		expect(r.size()).toBe(2)
+	})
+})

package/src/registry/agent/definitions.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `AgentRegistry` extends `ManagedRegistry<AgentDefinition>` and
+ *     keys by `def.info.id` via `computeId` (NOT by the top-level id
+ *     field — there isn't one on AgentDefinition).
+ *   - `resolve(agentId)` returns `.typedAgent`; delegates to
+ *     `getOrThrow` and therefore throws a plain `Error` when missing.
+ *   - `listByType(type)` filters by `typedAgent.type`.
+ *   - `search({category?, query?})` filters by info.category then by
+ *     case-insensitive match against name OR description. An empty
+ *     query matches all.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { AgentInfo } from '../../contracts/api.js'
+import type { AgentType, BaseAgentConfig, BaseAgentResult } from '../../types/agent/base.js'
+import type { Agent } from '../../types/agent/core.js'
+import type { AgentDefinition } from '../../types/agent/factory.js'
+
+import { AgentRegistry } from './definitions.js'
+
+function makeDef(id: string, type: AgentType, overrides: Partial<AgentInfo> = {}): AgentDefinition {
+	const info: AgentInfo = {
+		id,
+		name: `Agent ${id}`,
+		version: '1.0.0',
+		category: 'general',
+		description: `agent ${id} does stuff`,
+		tools: [],
+		defaults: { model: 'opus', tokenBudget: 1000 },
+		...overrides,
+	}
+	const typedAgent = { type } as unknown as Agent<BaseAgentConfig, BaseAgentResult>
+	return { info, typedAgent }
+}
+
+describe('AgentRegistry', () => {
+	it('keys by info.id (computeId), not by a top-level id field', () => {
+		const r = new AgentRegistry()
+		r.register(makeDef('coder', 'reactive'))
+		expect(r.get('coder')).toBeDefined()
+	})
+
+	it('resolve returns typedAgent', () => {
+		const r = new AgentRegistry()
+		const def = makeDef('coder', 'reactive')
+		r.register(def)
+		expect(r.resolve('coder')).toBe(def.typedAgent)
+	})
+
+	it('resolve throws (plain Error) on unknown agentId', () => {
+		const r = new AgentRegistry()
+		expect(() => r.resolve('nope')).toThrow(/Not found/)
+	})
+
+	it('listByType filters by typedAgent.type', () => {
+		const r = new AgentRegistry()
+		r.register(makeDef('a', 'reactive'))
+		r.register(makeDef('b', 'pipeline'))
+		r.register(makeDef('c', 'reactive'))
+		expect(r.listByType('reactive').map((d) => d.info.id)).toEqual(['a', 'c'])
+		expect(r.listByType('pipeline').map((d) => d.info.id)).toEqual(['b'])
+	})
+
+	describe('search', () => {
+		it('empty query returns all', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('a', 'reactive'))
+			r.register(makeDef('b', 'pipeline'))
+			expect(r.search({})).toHaveLength(2)
+		})
+
+		it('category filter is strict-equal', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('coder', 'reactive', { category: 'coding' }))
+			r.register(makeDef('writer', 'reactive', { category: 'writing' }))
+			expect(r.search({ category: 'coding' }).map((d) => d.info.id)).toEqual(['coder'])
+		})
+
+		it('query matches name OR description case-insensitively', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('alpha', 'reactive', { name: 'CoderBot', description: 'writes code' }))
+			r.register(makeDef('beta', 'reactive', { name: 'Other', description: 'tests CODE' }))
+			r.register(makeDef('gamma', 'reactive', { name: 'Third', description: 'documentation' }))
+
+			const hits = r.search({ query: 'code' }).map((d) => d.info.id)
+			expect(hits).toEqual(['alpha', 'beta'])
+		})
+
+		it('combines category + query', () => {
+			const r = new AgentRegistry()
+			r.register(makeDef('alpha', 'reactive', { category: 'coding', name: 'CoderBot' }))
+			r.register(makeDef('beta', 'reactive', { category: 'writing', name: 'CoderWriter' }))
+			const hits = r.search({ category: 'coding', query: 'coder' }).map((d) => d.info.id)
+			expect(hits).toEqual(['alpha'])
+		})
+	})
+})

package/src/registry/connector/definitions.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `ConnectorRegistry` extends `ManagedRegistry<ConnectorDefinition>`
+ *     with `idField: 'id'` — it keys by the top-level `id` field, NOT
+ *     a nested path.
+ *   - `listByType(connectionType)` filters by `connectionType`.
+ *   - As a global (non-tenant-scoped) registry, ConnectorRegistry is
+ *     shared across tenants; tenant isolation lives in
+ *     `TenantConnectorManager` per Codex #5.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import type { ConnectorDefinition } from '../../types/connector/index.js'
+import type { ConnectorId } from '../../types/ids/index.js'
+
+import { ConnectorRegistry } from './definitions.js'
+
+function makeDef(
+	id: string,
+	connectionType: ConnectorDefinition['connectionType'],
+): ConnectorDefinition {
+	return {
+		id: id as ConnectorId,
+		name: id,
+		description: `${id} connector`,
+		connectionType,
+		configSchema: z.object({}),
+		methods: [],
+	}
+}
+
+describe('ConnectorRegistry', () => {
+	it('keys by top-level id', () => {
+		const r = new ConnectorRegistry()
+		r.register(makeDef('conn_a', 'http'))
+		expect(r.get('conn_a')).toBeDefined()
+	})
+
+	it('listByType filters by connectionType', () => {
+		const r = new ConnectorRegistry()
+		r.register(makeDef('conn_a', 'http'))
+		r.register(makeDef('conn_b', 'webhook'))
+		r.register(makeDef('conn_c', 'http'))
+		expect(r.listByType('http').map((d) => d.id)).toEqual(['conn_a', 'conn_c'])
+		expect(r.listByType('webhook').map((d) => d.id)).toEqual(['conn_b'])
+		expect(r.listByType('custom')).toEqual([])
+	})
+})

package/src/registry/connector/scoped.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `ScopedConnectorRegistry` stores per-scope config by a composite
+ *     key `<scope>:<scopeId>:<connectorId>`. Multiple configs at
+ *     different scopes for the same connector coexist.
+ *   - `set`, `remove`, `getAt` round-trip through the same key.
+ *   - `resolve(connectorId, chain)` iterates in `CONNECTOR_SCOPE_ORDER`
+ *     (org → environment → team → project → agent) and merges layers
+ *     — later scopes override earlier ones. Specifically:
+ *     - `options` are shallow-merged across layers.
+ *     - `auth` is last-wins (any layer with an explicit auth replaces).
+ *     - `enabled` is last-wins (defaulting to true when no layer sets it).
+ *     - The final `ConnectorConfig.name` falls back to `connectorId`
+ *       when no layer sets a name.
+ *   - `resolve` returns undefined when no layer matches the chain.
+ *   - `listForConnector` returns every config for a connector across
+ *     all scopes; `listAtScope` returns every connector at a given scope.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ConnectorId } from '../../types/ids/index.js'
+
+import { ScopedConnectorRegistry } from './scoped.js'
+
+const CID = 'conn_http' as ConnectorId
+
+describe('ScopedConnectorRegistry', () => {
+	describe('set + getAt + remove', () => {
+		it('round-trips via the composite key', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				options: { k: 'v' },
+			})
+			expect(r.getAt({ scope: 'org', scopeId: 'org_1' }, CID)?.options).toEqual({ k: 'v' })
+		})
+
+		it('remove returns true iff an entry existed', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			expect(r.remove({ scope: 'org', scopeId: 'org_1' }, CID)).toBe(true)
+			expect(r.remove({ scope: 'org', scopeId: 'org_1' }, CID)).toBe(false)
+		})
+
+		it('different scopes coexist for the same connector', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			expect(r.listForConnector(CID)).toHaveLength(2)
+		})
+	})
+
+	describe('resolve layering', () => {
+		it('merges options shallow; later scopes override', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				options: { host: 'api.org', timeout: 30 },
+			})
+			r.set({
+				scope: { scope: 'project', scopeId: 'proj_1' },
+				connectorId: CID,
+				options: { host: 'api.project' },
+			})
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.options).toEqual({ host: 'api.project', timeout: 30 })
+		})
+
+		it('auth is last-wins (CONNECTOR_SCOPE_ORDER)', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: CID,
+				auth: { type: 'none' },
+			})
+			r.set({
+				scope: { scope: 'project', scopeId: 'proj_1' },
+				connectorId: CID,
+				auth: { type: 'api_key', credentials: { apiKey: 'secret' } },
+			})
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.auth).toEqual({ type: 'api_key', credentials: { apiKey: 'secret' } })
+		})
+
+		it('enabled defaults to true and is last-wins', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID, enabled: false })
+			const resolved = r.resolve(CID, { org: 'org_1' })
+			expect(resolved?.enabled).toBe(false)
+		})
+
+		it('config.name falls back to connectorId when no layer sets a name', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			const resolved = r.resolve(CID, { org: 'org_1' })
+			expect(resolved?.config.name).toBe(CID)
+		})
+
+		it('resolvedFrom preserves layer order by CONNECTOR_SCOPE_ORDER', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			const resolved = r.resolve(CID, { org: 'org_1', project: 'proj_1' })
+			expect(resolved?.resolvedFrom.map((s) => s.scope)).toEqual(['org', 'project'])
+		})
+
+		it('returns undefined when no layer matches the chain', () => {
+			const r = new ScopedConnectorRegistry()
+			expect(r.resolve(CID, { org: 'org_none' })).toBeUndefined()
+		})
+	})
+
+	describe('list operations', () => {
+		it('listAtScope filters by scope prefix', () => {
+			const r = new ScopedConnectorRegistry()
+			r.set({ scope: { scope: 'org', scopeId: 'org_1' }, connectorId: CID })
+			r.set({
+				scope: { scope: 'org', scopeId: 'org_1' },
+				connectorId: 'conn_other' as ConnectorId,
+			})
+			r.set({ scope: { scope: 'project', scopeId: 'proj_1' }, connectorId: CID })
+			expect(r.listAtScope({ scope: 'org', scopeId: 'org_1' })).toHaveLength(2)
+		})
+	})
+})

package/src/registry/plugin/index.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 3):
+ *
+ *   - `PluginRegistry` extends `ManagedRegistry<PluginDefinition>`
+ *     with `idField: 'id'`.
+ *   - `listByScope(scope)` filters by `def.scope`.
+ *   - `listByStatus(status)` filters by `def.status`.
+ *   - `findByName(name)` does a linear scan through `getAll()` and
+ *     returns the first match by `manifest.name`, or undefined.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { PluginId } from '../../types/ids/index.js'
+import type { PluginDefinition, PluginScope, PluginStatus } from '../../types/plugin/index.js'
+
+import { PluginRegistry } from './index.js'
+
+function makeDef(
+	id: string,
+	scope: PluginScope,
+	status: PluginStatus,
+	name = id,
+): PluginDefinition {
+	return {
+		id: id as PluginId,
+		manifest: {
+			name,
+			version: '1.0.0',
+			description: `${name} plugin`,
+		},
+		scope,
+		status,
+		rootDir: `/plugins/${id}`,
+		installedAt: Date.now(),
+	}
+}
+
+describe('PluginRegistry', () => {
+	it('keys by top-level id', () => {
+		const r = new PluginRegistry()
+		r.register(makeDef('plugin_a', 'project', 'installed'))
+		expect(r.get('plugin_a')).toBeDefined()
+	})
+
+	it('listByScope filters by scope', () => {
+		const r = new PluginRegistry()
+		r.register(makeDef('a', 'project', 'installed'))
+		r.register(makeDef('b', 'user', 'enabled'))
+		r.register(makeDef('c', 'project', 'disabled'))
+		expect(r.listByScope('project').map((d) => d.id)).toEqual(['a', 'c'])
+		expect(r.listByScope('user').map((d) => d.id)).toEqual(['b'])
+	})
+
+	it('listByStatus filters by status', () => {
+		const r = new PluginRegistry()
+		r.register(makeDef('a', 'project', 'installed'))
+		r.register(makeDef('b', 'project', 'enabled'))
+		r.register(makeDef('c', 'project', 'enabled'))
+		expect(r.listByStatus('enabled').map((d) => d.id)).toEqual(['b', 'c'])
+		expect(r.listByStatus('error')).toEqual([])
+	})
+
+	describe('findByName', () => {
+		it('returns the first def with matching manifest.name', () => {
+			const r = new PluginRegistry()
+			r.register(makeDef('id_1', 'project', 'installed', 'alpha'))
+			r.register(makeDef('id_2', 'project', 'installed', 'beta'))
+			expect(r.findByName('beta')?.id).toBe('id_2')
+		})
+
+		it('returns undefined when no match', () => {
+			const r = new PluginRegistry()
+			r.register(makeDef('id_1', 'project', 'installed', 'alpha'))
+			expect(r.findByName('missing')).toBeUndefined()
+		})
+
+		it('is case-sensitive (exact string match)', () => {
+			const r = new PluginRegistry()
+			r.register(makeDef('id_1', 'project', 'installed', 'Alpha'))
+			expect(r.findByName('alpha')).toBeUndefined()
+			expect(r.findByName('Alpha')?.id).toBe('id_1')
+		})
+	})
+})