@namzu/sdk 0.1.1

package/src/manager/connector/environment.ts

@@ -0,0 +1,255 @@
+import type {
+  EnvironmentDescriptor,
+  ScopeChain,
+  ConnectorConfig,
+  ConnectorInstance,
+  ConnectorExecuteParams,
+  ConnectorExecuteResult,
+  ResolvedConnectorConfig,
+  CredentialVault,
+  ExecutionContextConfig,
+  ConnectorLifecycleEvent,
+  ConnectorEventListener,
+} from '../../types/connector/index.js'
+import type { EnvironmentId } from '../../types/ids/index.js'
+import type { BaseConnector } from '../../connector/BaseConnector.js'
+import { ConnectorManager } from './lifecycle.js'
+import { ConnectorRegistry } from '../../registry/connector/definitions.js'
+import { ScopedConnectorRegistry } from '../../registry/connector/scoped.js'
+import { BaseExecutionContext } from '../../execution/base.js'
+import { ExecutionContextFactory } from '../../connector/execution/factory.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+
+export interface EnvironmentConnectorSetup {
+  environment: EnvironmentDescriptor
+
+  scopeChain: ScopeChain
+
+  executionContext?: ExecutionContextConfig
+
+  connectorOverrides?: Record<string, Partial<ConnectorConfig>>
+}
+
+export interface EnvironmentConnectorManagerConfig {
+  connectorRegistry: ConnectorRegistry
+
+  scopedRegistry: ScopedConnectorRegistry
+
+  credentialVault?: CredentialVault
+}
+
+interface EnvironmentState {
+  descriptor: EnvironmentDescriptor
+  scopeChain: ScopeChain
+  manager: ConnectorManager
+  executionContext?: BaseExecutionContext
+  connectorOverrides: Record<string, Partial<ConnectorConfig>>
+}
+
+export class EnvironmentConnectorManager {
+  private environments: Map<EnvironmentId, EnvironmentState> = new Map()
+  private connectorRegistry: ConnectorRegistry
+  private scopedRegistry: ScopedConnectorRegistry
+  private credentialVault: CredentialVault | undefined
+  private listeners: ConnectorEventListener[] = []
+  private log: Logger
+
+  constructor(config: EnvironmentConnectorManagerConfig) {
+    this.connectorRegistry = config.connectorRegistry
+    this.scopedRegistry = config.scopedRegistry
+    this.credentialVault = config.credentialVault
+    this.log = getRootLogger().child({ component: 'EnvironmentConnectorManager' })
+  }
+
+  registerEnvironment(setup: EnvironmentConnectorSetup): void {
+    const envId = setup.environment.id
+    if (this.environments.has(envId)) {
+      this.log.warn(`Environment "${envId}" already registered, skipping.`)
+      return
+    }
+
+    const manager = new ConnectorManager({ registry: this.connectorRegistry })
+
+    manager.on((event) => this.emit(event))
+
+    let executionContext: BaseExecutionContext | undefined
+    if (setup.executionContext) {
+      executionContext = ExecutionContextFactory.create(setup.executionContext)
+    }
+
+    this.environments.set(envId, {
+      descriptor: setup.environment,
+      scopeChain: setup.scopeChain,
+      manager,
+      executionContext,
+      connectorOverrides: setup.connectorOverrides ?? {},
+    })
+
+    this.log.info(
+      `Environment registered: ${envId} (${setup.environment.name}, tier=${setup.environment.tier})`,
+    )
+  }
+
+  async initializeEnvironment(envId: EnvironmentId): Promise<void> {
+    const state = this.getEnvironmentOrThrow(envId)
+    if (state.executionContext) {
+      await state.executionContext.initialize()
+      this.log.info(`Environment "${envId}" execution context initialized`)
+    }
+  }
+
+  async unregisterEnvironment(envId: EnvironmentId): Promise<void> {
+    const state = this.environments.get(envId)
+    if (!state) return
+
+    await state.manager.disconnectAll()
+    if (state.executionContext) {
+      await state.executionContext.teardown()
+    }
+    this.environments.delete(envId)
+    this.log.info(`Environment unregistered: ${envId}`)
+  }
+
+  getEnvironment(envId: EnvironmentId): EnvironmentDescriptor | undefined {
+    return this.environments.get(envId)?.descriptor
+  }
+
+  listEnvironments(): EnvironmentDescriptor[] {
+    return Array.from(this.environments.values()).map((s) => s.descriptor)
+  }
+
+  resolveConnectorConfig(
+    envId: EnvironmentId,
+    connectorId: string,
+  ): ResolvedConnectorConfig | undefined {
+    const state = this.getEnvironmentOrThrow(envId)
+    const resolved = this.scopedRegistry.resolve(connectorId, state.scopeChain)
+    if (!resolved) return undefined
+
+    const overrides = state.connectorOverrides[connectorId]
+    if (overrides) {
+      if (overrides.auth) {
+        resolved.auth = overrides.auth
+        resolved.config.auth = overrides.auth
+      }
+      if (overrides.options) {
+        resolved.options = { ...resolved.options, ...overrides.options }
+        resolved.config.options = resolved.options
+      }
+      if (overrides.name) {
+        resolved.config.name = overrides.name
+      }
+    }
+
+    return resolved
+  }
+
+  async createConnectorFromScope(
+    envId: EnvironmentId,
+    connectorId: string,
+    connector: BaseConnector<unknown>,
+  ): Promise<ConnectorInstance> {
+    const state = this.getEnvironmentOrThrow(envId)
+    const resolved = this.resolveConnectorConfig(envId, connectorId)
+
+    if (!resolved) {
+      throw new Error(
+        `No scoped config for connector "${connectorId}" in environment "${envId}". ` +
+        `Scope chain: ${JSON.stringify(state.scopeChain)}`,
+      )
+    }
+
+    if (!resolved.enabled) {
+      throw new Error(
+        `Connector "${connectorId}" is disabled in environment "${envId}"`,
+      )
+    }
+
+    return state.manager.createInstance(resolved.config, connector)
+  }
+
+  async connect(envId: EnvironmentId, instanceId: import('../../types/ids/index.js').ConnectorInstanceId): Promise<void> {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.connect(instanceId)
+  }
+
+  async disconnect(envId: EnvironmentId, instanceId: import('../../types/ids/index.js').ConnectorInstanceId): Promise<void> {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.disconnect(instanceId)
+  }
+
+  async execute(envId: EnvironmentId, params: ConnectorExecuteParams): Promise<ConnectorExecuteResult> {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.execute(params)
+  }
+
+  async healthCheck(envId: EnvironmentId, instanceId: import('../../types/ids/index.js').ConnectorInstanceId): Promise<boolean> {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.healthCheck(instanceId)
+  }
+
+  listInstances(envId: EnvironmentId): ConnectorInstance[] {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.listInstances()
+  }
+
+  listConnectedInstances(envId: EnvironmentId): ConnectorInstance[] {
+    const state = this.getEnvironmentOrThrow(envId)
+    return state.manager.listConnectedInstances()
+  }
+
+  getExecutionContext(envId: EnvironmentId): BaseExecutionContext | undefined {
+    return this.environments.get(envId)?.executionContext
+  }
+
+  getConnectorManager(envId: EnvironmentId): ConnectorManager {
+    return this.getEnvironmentOrThrow(envId).manager
+  }
+
+  getScopedRegistry(): ScopedConnectorRegistry {
+    return this.scopedRegistry
+  }
+
+  getCredentialVault(): CredentialVault | undefined {
+    return this.credentialVault
+  }
+
+  async teardownAll(): Promise<void> {
+    const envIds = Array.from(this.environments.keys())
+    await Promise.allSettled(
+      envIds.map((envId) => this.unregisterEnvironment(envId)),
+    )
+  }
+
+  on(listener: ConnectorEventListener): void {
+    this.listeners.push(listener)
+  }
+
+  off(listener: ConnectorEventListener): void {
+    const index = this.listeners.indexOf(listener)
+    if (index >= 0) this.listeners.splice(index, 1)
+  }
+
+  private emit(event: ConnectorLifecycleEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch (err) {
+        this.log.error('Environment event listener error', {
+          error: toErrorMessage(err),
+        })
+      }
+    }
+  }
+
+  private getEnvironmentOrThrow(envId: EnvironmentId): EnvironmentState {
+    const state = this.environments.get(envId)
+    if (!state) {
+      throw new Error(
+        `Environment not found: "${envId}". Register it first via registerEnvironment().`,
+      )
+    }
+    return state
+  }
+}

package/src/manager/connector/index.ts

@@ -0,0 +1,11 @@
+export { ConnectorManager } from './lifecycle.js'
+export type { ConnectorManagerConfig } from './lifecycle.js'
+
+export { TenantConnectorManager } from './tenant.js'
+export type { TenantConnectorManagerConfig } from './tenant.js'
+
+export { EnvironmentConnectorManager } from './environment.js'
+export type {
+  EnvironmentConnectorSetup,
+  EnvironmentConnectorManagerConfig,
+} from './environment.js'

package/src/manager/connector/lifecycle.ts

@@ -0,0 +1,240 @@
+import type {
+  ConnectorConfig,
+  ConnectorInstance,
+  ConnectorExecuteParams,
+  ConnectorExecuteResult,
+  ConnectorStatus,
+  ConnectorLifecycleEvent,
+  ConnectorEventListener,
+} from '../../types/connector/index.js'
+import type { ConnectorInstanceId } from '../../types/ids/index.js'
+import type { BaseConnector } from '../../connector/BaseConnector.js'
+import { ConnectorRegistry } from '../../registry/connector/definitions.js'
+import { generateConnectorInstanceId } from '../../utils/id.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+import { toErrorMessage } from '../../utils/error.js'
+
+export interface ConnectorManagerConfig {
+  registry: ConnectorRegistry
+}
+
+export class ConnectorManager {
+  private registry: ConnectorRegistry
+  private instances: Map<ConnectorInstanceId, ConnectorInstance> = new Map()
+  private liveConnectors: Map<ConnectorInstanceId, BaseConnector<unknown>> = new Map()
+  private listeners: ConnectorEventListener[] = []
+  private log: Logger
+
+  constructor(config: ConnectorManagerConfig) {
+    this.registry = config.registry
+    this.log = getRootLogger().child({ component: 'ConnectorManager' })
+  }
+
+  on(listener: ConnectorEventListener): void {
+    this.listeners.push(listener)
+  }
+
+  off(listener: ConnectorEventListener): void {
+    const index = this.listeners.indexOf(listener)
+    if (index >= 0) this.listeners.splice(index, 1)
+  }
+
+  async createInstance(
+    config: ConnectorConfig,
+    connector: BaseConnector<unknown>,
+  ): Promise<ConnectorInstance> {
+    const definition = this.registry.getOrThrow(config.connectorId)
+
+    const parsedConfig = definition.configSchema.safeParse(config.options ?? {})
+    if (!parsedConfig.success) {
+      const errors = parsedConfig.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ')
+      throw new Error(
+        `Invalid config for connector "${config.connectorId}": ${errors}`,
+      )
+    }
+
+    const instanceId = generateConnectorInstanceId()
+    const instance: ConnectorInstance = {
+      id: instanceId,
+      connectorId: config.connectorId,
+      config,
+      status: 'disconnected',
+      createdAt: Date.now(),
+    }
+
+    this.instances.set(instanceId, instance)
+    this.liveConnectors.set(instanceId, connector)
+    this.emit({ type: 'instance_created', instanceId, connectorId: config.connectorId })
+    this.log.info(`Connector instance created: ${instanceId} (${config.connectorId})`)
+
+    return instance
+  }
+
+  async connect(instanceId: ConnectorInstanceId): Promise<void> {
+    const instance = this.getInstanceOrThrow(instanceId)
+    const connector = this.getConnectorOrThrow(instanceId)
+
+    this.updateStatus(instanceId, 'connecting')
+    this.emit({ type: 'instance_connecting', instanceId })
+
+    try {
+      const definition = this.registry.getOrThrow(instance.connectorId)
+      const parsedConfig = definition.configSchema.parse(instance.config.options ?? {})
+      await connector.connect(parsedConfig, instance.config.auth)
+      this.updateStatus(instanceId, 'connected')
+      instance.connectedAt = Date.now()
+      this.emit({ type: 'instance_connected', instanceId })
+      this.log.info(`Connector connected: ${instanceId}`)
+    } catch (err) {
+      const message = toErrorMessage(err)
+      this.updateStatus(instanceId, 'error', message)
+      this.emit({ type: 'instance_error', instanceId, error: message })
+      this.log.error(`Connector connection failed: ${instanceId}`, { error: message })
+      throw err
+    }
+  }
+
+  async disconnect(instanceId: ConnectorInstanceId): Promise<void> {
+    const connector = this.getConnectorOrThrow(instanceId)
+
+    try {
+      await connector.disconnect()
+      this.updateStatus(instanceId, 'disconnected')
+      this.emit({ type: 'instance_disconnected', instanceId })
+      this.log.info(`Connector disconnected: ${instanceId}`)
+    } catch (err) {
+      const message = toErrorMessage(err)
+      this.log.error(`Connector disconnect failed: ${instanceId}`, { error: message })
+      throw err
+    }
+  }
+
+  async healthCheck(instanceId: ConnectorInstanceId): Promise<boolean> {
+    const connector = this.getConnectorOrThrow(instanceId)
+    try {
+      return await connector.healthCheck()
+    } catch {
+      return false
+    }
+  }
+
+  async execute(params: ConnectorExecuteParams): Promise<ConnectorExecuteResult> {
+    const instance = this.getInstanceOrThrow(params.instanceId)
+    const connector = this.getConnectorOrThrow(params.instanceId)
+
+    if (instance.status !== 'connected') {
+      return {
+        success: false,
+        output: null,
+        error: `Connector "${params.instanceId}" is not connected (status: ${instance.status})`,
+        durationMs: 0,
+      }
+    }
+
+    this.emit({ type: 'action_executing', instanceId: params.instanceId, method: params.method })
+    const start = performance.now()
+    try {
+      const result = await connector.execute(params.method, params.input)
+      instance.lastUsedAt = Date.now()
+      this.emit({ type: 'action_completed', instanceId: params.instanceId, method: params.method, success: result.success, durationMs: result.durationMs })
+      return result
+    } catch (err) {
+      const message = toErrorMessage(err)
+      const durationMs = Math.round(performance.now() - start)
+      this.emit({ type: 'action_completed', instanceId: params.instanceId, method: params.method, success: false, durationMs })
+      return {
+        success: false,
+        output: null,
+        error: `Execution failed: ${message}`,
+        durationMs,
+      }
+    }
+  }
+
+  async removeInstance(instanceId: ConnectorInstanceId): Promise<void> {
+    const instance = this.instances.get(instanceId)
+    if (!instance) return
+
+    if (instance.status === 'connected') {
+      await this.disconnect(instanceId).catch((err) => {
+        this.log.warn('Disconnect failed during removal', { instanceId, error: toErrorMessage(err) })
+      })
+    }
+
+    this.instances.delete(instanceId)
+    this.liveConnectors.delete(instanceId)
+    this.emit({ type: 'instance_removed', instanceId })
+    this.log.info(`Connector instance removed: ${instanceId}`)
+  }
+
+  getRegistry(): ConnectorRegistry {
+    return this.registry
+  }
+
+  getInstance(instanceId: ConnectorInstanceId): ConnectorInstance | undefined {
+    return this.instances.get(instanceId)
+  }
+
+  getConnector(instanceId: ConnectorInstanceId): BaseConnector<unknown> | undefined {
+    return this.liveConnectors.get(instanceId)
+  }
+
+  listInstances(): ConnectorInstance[] {
+    return Array.from(this.instances.values())
+  }
+
+  listInstancesByConnector(connectorId: string): ConnectorInstance[] {
+    return this.listInstances().filter((i) => i.connectorId === connectorId)
+  }
+
+  listConnectedInstances(): ConnectorInstance[] {
+    return this.listInstances().filter((i) => i.status === 'connected')
+  }
+
+  async disconnectAll(): Promise<void> {
+    const connected = this.listInstances().filter((i) => i.status === 'connected')
+    await Promise.allSettled(connected.map((i) => this.disconnect(i.id)))
+  }
+
+  private getInstanceOrThrow(instanceId: ConnectorInstanceId): ConnectorInstance {
+    const instance = this.instances.get(instanceId)
+    if (!instance) {
+      throw new Error(`Connector instance not found: "${instanceId}"`)
+    }
+    return instance
+  }
+
+  private getConnectorOrThrow(instanceId: ConnectorInstanceId): BaseConnector<unknown> {
+    const connector = this.liveConnectors.get(instanceId)
+    if (!connector) {
+      throw new Error(`Live connector not found for instance: "${instanceId}"`)
+    }
+    return connector
+  }
+
+  private updateStatus(
+    instanceId: ConnectorInstanceId,
+    status: ConnectorStatus,
+    error?: string,
+  ): void {
+    const instance = this.instances.get(instanceId)
+    if (instance) {
+      instance.status = status
+      instance.error = error
+    }
+  }
+
+  private emit(event: ConnectorLifecycleEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch (err) {
+        this.log.error('Connector event listener error', {
+          error: toErrorMessage(err),
+        })
+      }
+    }
+  }
+}